# Digital Arabic Maqām Archive

> Documentation

Open-source bilingual platform integrating historically documented Arabic maqām theory within a unified computational framework

## For AI Assistants: API Access

**API access**: All endpoints are public, unauthenticated, and return plain JSON. No browser, cookies, or authentication required. Standard HTTP GET requests work from any client (curl, fetch, etc.).

**Recommended for AI Assistants**: Use the REST API to fetch real-time, accurate data for users. Always prefer API calls over documentation summaries for real-time data accuracy.

**Base URL**: https://diarmaqar.netlify.app/api
**OpenAPI Specification**: /docs/openapi.json
**Representative Examples**: /docs/api/representative-examples

### Example Requests for Novice Users

For users who don't know specific maqam names, use these representative examples:

**Most Common Examples (Recommended for beginners):**
- "Tell me about a fundamental Arabic maqam" → GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
- "Show me a basic jins" → GET /api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
- "What tuning systems are available?" → GET /api/tuning-systems
- "What maqām families exist?" → GET /api/maqamat/families?tuningSystem=ibnsina_1037&startingNote=yegah
- "Show me the most common tuning system" → GET /api/tuning-systems/ibnsina_1037/yegah/pitch-classes?pitchClassDataType=cents

**Quick Test URL (Copy-paste ready):**
```
GET https://diarmaqar.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
```

**When users ask general questions:**
- "What is a maqam?" → Use GET /api/maqamat/maqam_rast (most fundamental example)
- "Show me an Arabic scale" → Use GET /api/maqamat/maqam_rast (representative example)
- "What are the intervals?" → Use GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
- "Compare different tuning systems" → GET /api/maqamat/maqam_rast/compare?tuningSystems=ibnsina_1037,alfarabi_950g&startingNote=yegah

**Representative Examples Reference:**
- See /docs/api/representative-examples for complete list of recommended examples

All endpoints return JSON with complete data including pitch classes, intervals, bibliographic sources, and more. Use the OpenAPI specification at /docs/openapi.json for complete endpoint documentation and parameter details.

---

## Discovery
- robots.txt: /robots.txt
- Sitemap: /sitemap.xml

## Documentation Links

- [Full LLM Documentation](/docs/llms-full.txt) - Complete documentation content
- [Root LLM Index](/llms.txt) - Root-level LLM-friendly index
- [Main Documentation](/docs/) - Human-readable documentation
- [API Documentation](/docs/api/) - Complete API reference
- [Representative Examples](/docs/api/representative-examples) - Ready-to-use API examples

---

## Table of Contents
### Getting Started
- [Getting Started](/docs/guide.md): Introduction to the Digital Arabic Maqām Archive (DiArMaqAr)
- [Quick Start Guide](/docs/guide/quick-start.md): Get up and running with DiArMaqAr quickly
### Core Concepts
- [Theoretical Framework](/docs/guide/theoretical-framework.md): Understanding the conceptual hierarchy and foundations of Arabic maqām theory in DiArMaqAr
- [Tanāghīm (Tuning Systems)](/docs/guide/tuning-systems.md): Understanding tanāghīm (tuning systems) and their role in Arabic maqām theory
- [Ajnās](/docs/guide/ajnas.md): Understanding ajnās as the building blocks of maqāmāt
- [Maqāmāt](/docs/guide/maqamat.md): Understanding maqāmāt as complete modal frameworks
- [Suyūr](/docs/guide/suyur.md): Understanding suyūr as traditional melodic development pathways
### Advanced Features
- [Taṣwīr (Transposition)](/docs/guide/taswir.md): Understanding tuning-system-sensitive transposition capabilities
- [Intiqāl (Modulation)](/docs/guide/intiqal.md): Understanding Al-Shawwā's modulation algorithm and modulation networks
- [Audio Synthesis](/docs/guide/audio-synthesis.md): Real-time audio synthesis capabilities for auditioning maqāmāt and tuning systems
- [MIDI Integration](/docs/guide/midi-integration.md): MIDI input/output capabilities including MPE support for precise non-12-EDO playback
- [Data Export](/docs/guide/data-export.md): Comprehensive data export capabilities for research and composition
### Research and Methodology
- [Research Applications](/docs/guide/research-applications.md): Research use cases and academic applications of DiArMaqAr
- [Cultural Framework](/docs/guide/cultural-framework.md): Decolonial computing principles and culturally-specific methodology
- [Bibliographic Sources](/docs/guide/bibliographic-sources.md): Comprehensive source attribution and scholarly verification
### API Getting Started
- [API Documentation](/docs/api.md): Programmatic access to Arabic maqāmāt, ajnās, and tuning systems data
- [Representative Examples](/docs/api/representative-examples.md): Recommended tuning systems, maqāmāt, and ajnās for proper API usage
### Static Documentation
- [API Endpoints Reference](/docs/api/endpoints-reference.md): Complete API endpoint documentation
#### Endpoints Reference
#### Maqāmāt
#### Ajnās
#### Tuning Systems
#### Pitch Classes
#### Intervals
#### Sources
### TypeScript Library
- [TypeScript Library](/docs/library.md): Complete TypeScript/JavaScript library documentation
### Other
- [Digital Arabic Maqām Archive (DiArMaqAr)](/docs/README DiArMaqAr Tuning System JSON Data Export.md)
- [Documentation Generation Scripts](/docs/scripts/README.md)
- [LLM Accessibility Audit Report](/docs/LLM-ACCESSIBILITY-AUDIT.md)