Digital Arabic Maqām Archive (DiArMaqAr)

Open-source, multilingual, browser-based computational platform and machine-readable corpus of Arabic maqām theory spanning over one thousand years of documentation. Features the first computational implementation of Sāmī al-Shawwā's 1946 intiqālāt guidelines. Grounded in culture-specific and decolonial computing methodologies.

Documentation

API Access

Base URL: https://diarmaqar.netlify.app/api

OpenAPI Spec: /docs/openapi.json

For AI Assistants

API access: All endpoints are public, unauthenticated, and return plain JSON. No browser, cookies, or authentication required.

Recommended for AI Assistants: Use the REST API to fetch real-time, accurate data for users. Always prefer API calls over documentation summaries. Example: GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents to get detailed maqām data. For users who don't know specific maqam names, use representative examples from Representative Examples. See OpenAPI spec for all endpoints.

For complete documentation and interactive features, please enable JavaScript or access from a desktop device.

🖥️

Desktop Required

The Digital Arabic Maqām Archive is designed for laptop and desktop computers only.

Please access this application from a device with a larger screen for the best experience.

Digital Arabic Maqām Archive (DiArMaqAr)

Comprehensive bilingual browser-based application and repository integrating historically documented Arabic maqām theory within a unified computational framework. Provides rigorously sourced, computationally accessible reference data with transparent provenance for computational musicology, music information retrieval, machine learning applications, and scholarly research.

Documentation

API Access

Base URL: https://diarmaqar.netlify.app/api

OpenAPI Specification: /docs/openapi.json

Interactive Playground: /docs/api/playground

For AI Assistants and LLMs

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. The API provides programmatic access to all maqāmāt, ajnās, and tuning systems data.

Example Requests for Novice Users: For users who don't know specific maqam names, use these representative examples:

Quick Test URL: GET https://diarmaqar.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents

All endpoints return JSON with complete data including pitch classes, intervals, bibliographic sources, and more. See Representative Examples for complete list of recommended examples. Use the OpenAPI specification for complete endpoint documentation and parameter details.

Quick Links

About

Digital Arabic Maqām Archive (DiArMaqAr) is an open-source platform for Arabic maqām theory providing REST API and TypeScript library. Includes historically documented maqāmāt, ajnās, and tuning systems spanning from al-Kindī (874 CE) to contemporary approaches. All data includes comprehensive bibliographic attribution following decolonial computing principles.

Note: Full interactive features require a desktop device. However, all documentation and API endpoints are accessible programmatically. For complete documentation, see: /docs/llms.txt

أرشيف المقامات العربية الرقمي
Digital Arabic Maqām Archive

Open-source interactive online platform and library for exploring the Arabic maqām system

Enter the Archive
Take an Interactive TourAccess the DocumentationAccess the Source CodeRead the Academic Paper

About

The Digital Arabic Maqām Archive is an innovative open-access and open-source online platform dedicated to the study and exploration of the Arabic maqām system.

The platform is designed as a resource for students, musicians, composers, musicologists, educators, researchers, coders/developers, and anyone interested in the rich music theory of the Arabic-speaking region.

It offers an interactive and academically rigorous repository of tuning systems, ajnās, and maqāmāt, along with their suyūr (pathways of melodic development) and intiqālāt (modulations), all of which can be played and heard with a computer keyboard or via MIDI.

Musicians and composers can export Scala tuning files for integration with external instruments and software. In parallel, developers and researchers can access structured, computationally queryable data through comprehensive JSON exports and API endpoints, alongside in-depth mathematical data and analysis.

Core Features

Interactive Exploration

Play and hear hundreds of tuning systems, ajnās, and maqāmāt (on all their transpositions) using your computer keyboard or MIDI devices.

Comparative Analysis

Switch between multiple tuning systems to hear and compare their intervals on the same jins or maqām.

Mathematical Precision

Access detailed mathematical analysis including interval calculations, frequency ratios, cent values, string lengths, and ajnās constructions.

Algorithmic Modulations

Explore maqām modulation based on our unique algorithm created from Sāmī Al-Shawwā's rules for maqām modulation.

Scholarly Rigour

Access a comprehensive bibliography and source references for all the musicological data alongside analyses and commentaries.

Open Data Access

Export the data in various formats for research or creative use and access our open API for programmatic integration.

For Developers & LLMs

This site is LLM-friendly and provides comprehensive programmatic access to Arabic maqām data. All API 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.). The API returns complete, structured JSON responses with pitch classes, intervals, bibliographic sources, and more.

⚠️ Critical: Required Parameters

All detail endpoints (/api/maqamat/{id}, /api/ajnas/{id}) require three parameters: tuningSystem, startingNote, and pitchClassDataType. These are required because pitch class calculations depend on the tuning system and starting note, and the API needs to know which format to return the data in.

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

🤖 Explicit Instructions for AI Assistants:

  • Always include required parameters (tuningSystem, startingNote, pitchClassDataType) for detail endpoints
  • Use Representative Examples from Representative Examples as the source of truth for correct API usage
  • Prefer API calls over documentation summaries for real-time data accuracy
  • Use parameter discovery (?options=true) to programmatically discover available parameters
  • For users who don't know specific names, use maqam_rast with ibnsina_1037 and yegah as safe defaults
  • Reference the OpenAPI specification at /docs/openapi.json for complete parameter documentation

Common Mistakes to Avoid:

  • ❌ GET /api/maqamat/maqam_rast (missing required parameters)
  • ❌ GET /api/maqamat/rast (wrong format - missing "maqam_" prefix)
  • ❌ GET /api/maqamat/maqam_rast?tuningSystem=Ibn Sīnā (1037) (using display name instead of URL-safe ID)
  • ✅ GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents

📋 Common Use Cases for AI Assistants:

  • "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
  • "Compare different tuning systems" → GET /api/maqamat/maqam_rast/compare?tuningSystems=ibnsina_1037,alfarabi_950g&startingNote=yegah
  • "Discover available parameters" → GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true

Response Structure: API responses are complex nested JSON structures including maqam/jins metadata, pitchData (ascending/descending arrays), intervals, context (tuning system info), sources (bibliographic references), links (related endpoints), and characteristics (musical properties). See the OpenAPI specification for complete response schemas.

Documentation

API Access

Project Team

This project was researched, designed and developed by Khyam Allami and Ibrahim El Khansa in the Music Intelligence Lab at the American University of Beirut, Lebanon, and launched in September 2025.

Contribute

We welcome contributions from the community to help improve and expand this project further. Please visit our GitHub repository to report issues, suggest features, or submit pull requests. Alternatively, if you would like to help with data entry please get in touch with Khyam Allami directly on ka109@aub.edu.lb.