--- url: /docs/guide.md description: Introduction to the Digital Arabic Maqām Archive (DiArMaqAr) --- # Getting Started Welcome to the Digital Arabic Maqām Archive (DiArMaqAr) documentation! ## What is DiArMaqAr? The Digital Arabic Maqām Archive (DiArMaqAr) is an open-source, multilingual, browser-based application and repository designed for musicians, composers, developers, and scholars engaged with Arabic maqām theory. The application integrates an archive of historically documented **tanāghīm** (تناغيم, tuning systems), **ajnās** (أجناس, melodic segments), **maqāmāt** (مقامات, modal frameworks), **suyūr** (سيور, melodic pathways), and **intiqālāt** (انتقالات, modulations) within a unified digital framework, establishing verified reference data for education, performance, composition, software development, machine learning applications, and instrument design. ### Key Features * **multilingual Interface**: Arabic/English (with Library of Congress Romanization standards) * **Comprehensive Tuning Systems**: Access to historical and modern tuning systems from the 9th century to present with historical source attributions * **Maqāmāt and Ajnās Data**: Complete database with modern source attributions * **Tuning-System-Sensitive Transposition**: Systematic computation of all mathematically valid ajnās and maqāmāt transpositions * **Al-Shawwā Modulation Algorithm**: First algorithmic implementation of Sāmī al-Shawwā's 1946 modulation guidelines * **Bibliographic Attribution System**: Complete source references with scholarly verification * **Real-Time Audio Synthesis**: Hear precise intonational relationships with Web Audio API * **MIDI Integration**: Support for MIDI input and MPE (MIDI Polyphonic Expression) output * **Data Export**: JSON and Scala (.scl/.kbm) formats for research and composition * **REST API**: Programmatic access to all data ### Cultural Framework All functionality is rooted in the **theoretical framework of Arabic maqām theory** and its epistemological traditions. The system uses the historical Persian-Arab-Ottoman note naming conventions (rāst, dugāh, segāh, etc.) and supports tuning-system-aware transposition, ensuring precise intervallic relationships are preserved across all maqāmāt and ajnās. ## Quick Start ### Using the REST API The easiest way to get started is using the REST API: ```bash # Get all maqāmāt curl https://diarmaqar.net/api/maqamat # Get specific maqām data with full details curl "https://diarmaqar.net/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents" # Include modulation analysis on the maqām detail response curl "https://diarmaqar.net/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&includeModulations=true" # List transpositions (separate endpoint; `includeTranspositions` applies to GET /tuning-systems/{id}/{startingNote}/maqamat, not maqām detail) curl "https://diarmaqar.net/api/maqamat/maqam_bayyat/transpositions?tuningSystem=alfarabi_950g&startingNote=ushayran" ``` ## Documentation Guide ### Core Concepts 1. **[Theoretical Framework](/guide/theoretical-framework/)** - Understanding the conceptual hierarchy: Tanāghīm → Ajnās → Maqāmāt → Suyūr → Intiqālāt 2. **[Tuning Systems](/guide/tuning-systems/)** - Learn about tanāghīm, mathematical representations, and historical sources 3. **[Ajnās](/guide/ajnas/)** - Understanding ajnās (3-5 note sequences) as building blocks of maqāmāt 4. **[Maqāmāt](/guide/maqamat/)** - Complete modal frameworks with ascending/descending sequences 5. **[Suyūr](/guide/suyur/)** - Traditional melodic performance pathways ### Advanced Features 6. **[Taṣwīr (Transposition)](/guide/taswir/)** - Tuning-system-sensitive transposition of ajnās and maqāmāt 7. **[Intiqāl (Modulation)](/guide/intiqal/)** - Al-Shawwā's modulation algorithm and network analysis 8. **[Audio Synthesis](/guide/audio-synthesis/)** - Real-time audio playback using Web Audio API 9. **[MIDI Integration](/guide/midi-integration/)** - MIDI input/output with MPE support for precise non-12-EDO playback 10. **[Data Export](/guide/data-export/)** - Export capabilities: JSON, CSV, Scala formats ### Research and Methodology 11. **[Research Applications](/guide/research-applications/)** - Use cases for computational musicology, ML/AI, and academic research 12. **[Cultural Framework](/guide/cultural-framework/)** - Decolonial computing principles and culturally-specific methodology 13. **[Bibliographic Sources](/guide/bibliographic-sources/)** - Complete source attribution system and scholarly verification ## Next Steps * Start with [Quick Start Guide](/guide/quick-start/) for immediate hands-on experience * Explore [Theoretical Framework](/guide/theoretical-framework/) to understand core concepts * Visit the [API Reference](/api/) for complete endpoint documentation * Visit the [Interactive API Playground](http://localhost:3000/api-playground) to test endpoints interactively ## Resources * [Source Code](https://github.com/Music-Intelligence-Lab/DiArMaqAr) - View on GitHub * [Music Intelligence Lab](https://music-intelligence-lab.org) - Research lab website * [Live Application](https://diarmaqar.net/) - Interactive web interface --- --- url: /docs/guide/quick-start.md description: Get up and running with DiArMaqAr quickly --- # Quick Start Guide This guide will help you get started with the Digital Arabic Maqām Archive in just a few minutes. ## Installation ### For API Usage No installation needed! The API is accessible via HTTP requests. ### For TypeScript/JavaScript Usage If using the library directly, import from source in your project. ## First API Request Let's make your first API call: ```bash # List all maqāmāt curl https://diarmaqar.net/api/maqamat ``` This will return a list of all available maqāmāt with basic metadata. ## Get Detailed Maqām Data To get detailed data for a specific maqām: ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents" ``` This returns: * Complete pitch data in the specified tuning system * Ajnās information (always included) * Optional intervals, modulations, and suyūr ## Explore Further * [API Reference](/api/) - Complete API documentation * [Interactive API Playground](http://localhost:3000/api-playground) - Test endpoints in your browser --- --- url: /docs/guide/theoretical-framework.md description: >- Understanding the conceptual hierarchy and foundations of Arabic maqām theory in DiArMaqAr --- # Theoretical Framework DiArMaqAr's architecture reflects the traditional conceptual hierarchy of maqām theory as documented in historical and contemporary sources. Understanding this framework is essential for effectively using the platform. ## Conceptual Hierarchy The system organizes content according to five hierarchical levels: ### 1. Tanāghīm (tuning systems) Tuning systems provide the fundamental pitch framework for all operations. A tuning system is an ordered sequence of pitch classes (pitches/tones/notes) that can be expressed through various mathematical representations: * **Frequency ratios** (fractions such as 1/1, 9/8, 4/3, 3/2) * **Cents values** (relative to a reference, such as 0, 203.9, 498.0, 702.0) * **String lengths** or **fret divisions** (historical measurement approaches) For a tuning system to be rendered sonically, a reference frequency associated with its first pitch class needs to be defined. Additionally, all pitch classes are assigned a note name from the Persian-Arab-Ottoman naming convention to allow for conventional forms of ajnās, maqāmāt and suyūr to be represented across different tuning systems. **Key Characteristics:** * Tuning systems contain various amounts of pitch classes * They use different mathematical approaches based on historical sources * All values are relative to the first pitch class (1/1 or 0 cents) * Reference frequency is variable, based on theoretical standardization or performance practice ### 2. Ajnās (tri/tetra/penta-chords) A jins (plural, ajnās) is a unique sequence of 3, 4, or 5 notes (trichord, tetrachord, or pentachord), each defined by its characteristic interval pattern. Ajnās are the foundational building blocks of maqāmāt. **Key Characteristics:** * Ajnās are constructed based on their constituent note names * Not all ajnās are compatible with every tuning system * The platform searches across the tuning system when determining ajnās compatibility * Each jins has a specific intervallic pattern that defines its character **Example:** In Al-Kindī's tuning system, jins kurd (dūgāh, kurdī, chahārgāh, nawā) can be constructed because all these note names exist within the system. ### 3. Maqāmāt (modal frameworks) A maqām is a a complete modal framework built from an ordered sequence of pitch classes that form the contituent ajnās from which the maqāmāt are constructed. Each maqām contains: * **Ascending sequence (ṣuʿūd)**: Seven or more notes defining the upward melodic path * **Descending sequence (hubūṭ)**: Seven or more notes defining the downward melodic path The ascending and descending sequences can either be identical or different, creating asymmetrical modal structures. **Key Characteristics:** * In DiArMaqAr, the Maqāmāt are constructed based on their constituent note names as defined in bibliographic sources * The base form of each maqām is subject to tuning system compatibility (all its note names must exist in the selected tuning system) * All maqāmāt are automatically analyzed for constituent ajnās * Transpositions are tuning system sensitive, meaning that not all maqāmāt nor all their transpositions are available in every tuning system. ### 4. Suyūr (pathways of melodic development) Suyūr are conventional melodic pathways for developing or modulating within maqām frameworks. These are characteristic modal transformations or transitions, generally understood in performance practice but not always documented in theoretical literature. **Key Characteristics:** * Conventional practice, not strictly prescriptive * Pathways may include modulation and melodic transitions * Documentation limited; many practical variants exist * Specific to certain maqāmāt, not universal * Guide improvisational and compositional choices **Implementation:** * Suyūr are implemented as structured sequences of "stops" * Each stop represents either: * A specific note (from the Persian-Arab-Ottoman naming convention) * A jins (maintains structural identity while allowing transposition) * A maqām (allows description of modulatory pathways) * A directional instruction (ascending/descending) * A standalone directional instruction **Historical Context:** In historical sources (Meshshāqa 1899, Al-Shawwā 1946, Al-Ṣabbāgh 1950, Al-Ḥilū 1961), suyūr are always presented as prose text and are never represented for transpositions of any given maqām. DiArMaqAr addresses this limitation through computational transposition of suyūr. ### 5. Intiqālāt (modulations) Intiqāl is the process of moving from one maqām to another during performance or composition. Modulation is only possible when the darajat al-istiqrār (stabilizing degree) or tonic of the target jins or maqām exists among the current maqām's pitch classes. DiArMaqAr implements the first algorithmic interpretation of Sāmī al-Shawwā's (1946) modulation guidelines, making explicit the networked relationships underlying maqām modulation theory. **Key Characteristics:** * Tonic requirement: Target tonic (darajat al-istiqrār/al-rukūz) must exist in the current pitch class set * Permitted maqām degrees (al-Shawwā): 1st, 3rd, 4th, 5th, or 6th (and/or alternative third) * Context-dependent, based on pitch class presence and theoretical relationships * Specific maqāmāt prescribe allowable modulation pathways (suyūr) * Maintains modal identity: The new maqām establishes its own structure ## Note Naming Convention The application's data model is fundamentally grounded in the **historical Persian-Arab-Ottoman note naming convention**. This naming system serves as the primary reference framework for all operations: **Standard Note Names:** * yegāh, qarār ḥiṣār, ʿushayrān, ʿirāq, rāst, dūgāh, segāh, chahārgāh, nawā, ḥusaynī, awj, etc. **Extended Ranges:** * **Lower register**: qarār qarār or qarār prefixes * **Main register**: Standard note names * **Upper register**: Standard note names (higher range) * **Extended upper register**: jawāb or jawāb jawāb prefixes **Theoretical Significance:** Using Persian-Arab-Ottoman note names is the only approach that enables exploring multiple tuning systems based on Arabic maqām theory conventions, which regularly analyze maqāmāt using note names rather than historical or mathematical pitch class definitions. This methodology: * **Grounds analysis in Arabic theoretical frameworks**: Maqām theory developed using these specific note names as the primary organizational system * **Enables cross-tuning-system analysis**: The same note names (e.g., rāst, dūgāh, segāh) allow comparison across different historical tanāghīm * **Preserves historical analytical methods**: Reflects how Arabic music theorists have analyzed and documented maqāmāt for centuries * **Avoids Anglo-European-centric impositions**: Does not force International Pitch Notation (C, D, E) or solfege (do, re, mi)—approaches that became common practice in Arabic music theory only since the mid-20th century * **Maintains theoretical independence**: Arabic maqām analysis operates within its own conceptual framework without requiring Western reference systems ## Tuning System Starting Note Name The note name for the first pitch class from which all remaining pitch classes are ordered and calculated is the tuning system's starting note name. This is always associated with the first pitch class in the tuning system (ratio 1/1, 0 cents, or open string length). Starting note names reflect different traditions and methodologies: * **ʿUshayrān-based**: Related to theorisations based on defining frets/division of the oud strings where the open oud strings are tuned in perfect fourths. ʿUshayrān is the modern note name assigned to the fourth string of a standard 6-string oud, which is the lowest (in pitch) of the four strings that are tuned in fourths. * **Yegāh-based**: This is the first note name utilised in modern Arabic music theory. It also represents tuning systems that were developed based on long necked lute family instruments (the Persian Tar or Sehtar) or the division of a single string using a monochord or sonometer. * **Rāst-based**: Tuning systems using rāst for their starting note name are mid-20th century onwards and represent a trend of modifying Anglo-European music theory standards to suit the Arabic maqām system. The note name rāst is associated with the International Pitch Notation note name C. Most theoretical representations of Anglo-European scales or the 12-EDO tuning system start on the note C, as opposed to A which is used to define the reference frequency (i.e. A4 = 440 Hz), hence the modern usage of rāst. **Key Characteristics:** * Note name, not actual pitch class * Always refers to first pitch class * Frequency value independent; theoretical anchor for ordering * Not arbitrary: determined by historical or practical tradition **Theoretical Implications:** The choice of starting note name is not arbitrary—it represents a fundamental theoretical decision that affects the entire mathematical and practical framework of maqām analysis: * **Availability of Ajnās and Maqāmāt**: Different tuning system starting note names determine which maqāmāt and ajnās are available within a tuning system. The same tuning system with different starting notes (e.g., ʿushayrān vs. yegāh) may support different numbers of possible maqāmāt and ajnās due to the unequal divisions used in the tuning system itself. * **Mathematical Relationships**: The starting note name determines how intervals are mathematically organized. Changing the starting note name affects the relative positions of all pitch classes and their intervallic relationships within the tuning system. * **Intiqālāt (modulations)**: The networks of possible modulations between maqāmāt vary substantially depending on the starting note name of a tuning system. Some modulation pathways that are possible in one system may not be available in another due to the different pitch class organization. * **Structural Accessibility**: Certain maqām structures may be accessible in a framework based on a certain starting note name but not another, even within the same underlying tuning system. This affects which structures can be constructed and analyzed. * **Theoretical Framework Significance**: Starting note names signal theoretical, mathematical, or historical approaches (oud-based, monochord-based, or Anglo-European-influenced) rather than simple transpositions. This reflects different epistemological foundations and measurement traditions. ## Mathematical Calculations The core TuningSystem class implements mathematical conversion between different pitch representation formats, maintaining mathematical accuracy while supporting diverse representations: * Frequency ratios (fractions) * Decimal ratios * Cents values * String lengths * Fret divisions * Frequencies in Hz * Deviation from 12-EDO in ±cents * MIDI note numbers in decimal format * MIDI note numbers plus the deviation in ±cents All calculations are based on the original unit of measurement in the relevant bibliographic source, ensuring historical accuracy. ## Next Steps * Learn about [Tuning Systems](/guide/tuning-systems/) * Explore [Ajnās](/guide/ajnas/) * Understand [Maqāmāt](/guide/maqamat/) * Discover [Intiqāl (Modulation)](/guide/intiqal/) --- --- url: /docs/guide/tuning-systems.md description: Understanding tanāghīm (tuning systems) and their role in Arabic maqām theory --- # Tanāghīm (Tuning Systems) Tanāghīm (tuning systems, singular: tanghīm) are the foundational layer of Arabic maqām theory in DiArMaqAr. They provide the pitch framework upon which all other musical structures are built. ## What is a tanghīm? A tanghīm is an ordered sequence of pitch classes within an octave. These pitch classes can be expressed through various mathematical representations, all relative to the first pitch class. ### Mathematical Representations **Frequency Ratios (Fractions):** * Example: 1/1, 9/8, 4/3, 3/2, 16/9 * All ratios are relative to 1/1 (the reference pitch) **Cents Values:** * Example: 0, 203.9, 498.0, 702.0, 996.1 * All values are relative to 0 cents (the reference pitch) **String Lengths / Fret Divisions:** * Historical measurement approaches used in medieval treatises * Converted to other formats for computational use ## Reference Frequency and Note Names To render a tanghīm sonically, two additional pieces of information are needed: 1. **Reference Frequency**: The absolute frequency (in Hz) assigned to the first pitch class 2. **Note Names**: Mapping to the Persian-Arab-Ottoman note naming convention These associations are documented in historical sources and reflect either theoretical standardization or performance practice traditions. ## Historical Sources DiArMaqAr integrates tanāghīm spanning over 1,000 years of documented theory and practice, from medieval theorists like al-Kindī (874), al-Fārābī (950), and Ibn Sīnā (1037), through modern sources including the Cairo Congress Tuning Committee (1932) and al-Ṣabbāgh (1950), to contemporary approaches (Allami 2022-2025). Each tanghīm includes complete bibliographic attribution with source references and page numbers where applicable. ## Extended Range System In DiArMaqAr, tanāghīm are expanded across multiple registers to support comprehensive musical analysis: * **Lower register**: qarār qarār or qarār prefixes * **Main register**: Standard note names * **Upper register**: Standard note names (higher range) * **Extended upper register**: jawāb or jawāb jawāb prefixes This expansion is essential for: * Jins and maqām analysis across full ranges * Transposition calculations * Modulation pathway exploration * Authentic representation of Arabic theory ## Starting Note Conventions Tanāghīm follow different starting note conventions based on their historical sources: **Oud-based systems** start on ʿushayrān, reflecting oud tuning in perfect fourths (e.g., al-Kindī, al-Fārābī, Ibn Sīnā). **Monochord/sonometer systems** start on yegāh or rāst, reflecting theoretical measurement approaches (e.g., Cairo Congress 1932). The starting note affects available maqāmāt, transposition possibilities, and modulation characteristics. ## Mathematical Conversion Each pitch class is automatically converted to multiple formats including frequency ratios, cents, absolute frequencies, MIDI values, string lengths, and cents deviations from 12-EDO reference notes. ## Tanāghīm Whose Octaves Are Not Exact In most tanāghīm each octave repeats the first exactly, so the pitch classes of the second octave are the first octave's pitch classes doubled. Some historical tanāghīm do not work this way. In the tuning of Ibn Sīnā (1037), every string of the ʿūd carries the same frets while the strings are tuned a fourth apart, so a pitch class of the first dīwān does not always have an exact double in the second. For example, the exact double of 273/256 would be 273/128, but the nearest pitch class of the second dīwān is 512/243, about 21.08 cents lower. For such tanāghīm, DiArMaqAr stores the values of dīwān 0, 2 and 3 as the source gives them (or as its ʿūd produces them), instead of halving and doubling the first dīwān. The tables mark every value that is not an exact double or half of a value in the neighbouring dīwān. Note names in these dawāwīn follow one rule. A pitch class that is an exact double or half of a named pitch class, or within 3 cents of one, takes that note's name in the higher or lower register. Any other pitch class takes the name of the nearest named pitch class with tīk when it lies above it, or nīm when it lies below it. The note names tīk yegāh, tīk ʿushayrān and tīk dūgāh were added for this rule. If a tīk name already belongs to another pitch class of the same tanghīm, a pitch class between a note and its tīk is named nīm tīk; such a name is added when a tanghīm first needs one. ## Viewing a Tanghīm: Jadāwel and Awtār A tanghīm can be viewed in two ways, chosen under **View**. **Jadāwel (tables)** shows each dīwān as a table of its pitch classes, with their note names and their values in every unit (ratios, cents, decimal ratios, string lengths, frequencies, MIDI and more). The row in the unit the source uses is marked as the source values. **Awtār (strings)** shows the same pitch classes on the strings of an ʿūd, from the anf (nut) to half the string length, with every pitch class at its exact position on each string. The labels above and below each string can show the note names (PAO), IPN names, solfège, ratios, cents or fret divisions. **Dūzān/Taswīya** sets how the open strings are tuned: * **Source ʿūd**: for a tanghīm whose source describes its ʿūd, such as Ibn Sīnā (1037), the strings, their tuning and the frets are drawn exactly as the source gives them, with the source's own string and fret names. This is the default for those tanāghīm. Each fret's name sits above the strings, at its exact position. * **Custom**: choose the number of strings and the open note of each string. * **Presets**: two strings (a fourth apart or a fifth apart), four strings tuned in fourths, five- and six-string ʿūds named by their lowest and highest open strings, and the violin and the cello. The violin comes with its Anglo-European open strings (yegāh, dūgāh, ḥusaynī, jawāb būselīk) and its Arabic open strings (yegāh, dūgāh, nawā, muḥayyar). The cello's open strings are qarār rāst, yegāh, dūgāh and ḥusaynī; qarār rāst is the lowest rāst the archive holds, so the cello sits a fifth below the violin here rather than an octave and a fifth. Positions on a string that are not an exact octave of a value in the neighbouring dīwān are marked, with a legend under the strings. For a tanghīm with a source ʿūd, a note on how the strings represent the source is shown above the commentary. The view and the dūzān are part of the page address, so a shared link opens the same view: `view=tables` or `view=strings`, and `duzan=` with the preset (for example `duzan=source`), or `duzan=custom&openStrings=yegah,dugah,kurdan` for a custom tuning. ## Using Tanāghīm ### Via REST API ```bash # Get all available tuning systems (full metadata per tanghīm) curl https://diarmaqar.net/api/tuning-systems # There is no GET /api/tuning-systems/{id}; use list + idName, or pitch classes / maqāmāt in context: curl "https://diarmaqar.net/api/tuning-systems/alfarabi_950g/ushayran/pitch-classes?pitchClassDataType=cents" ``` ## Bibliographic Attribution Every tanghīm includes: * **Source citation**: Complete bibliographic reference * **Page references**: Specific pages where the system appears * **Creator attribution**: Historical theorist or modern scholar * **Publication year**: Temporal context * **Commentary**: Contextual notes by Dr. Khyam Allami This transparent provenance enables: * Scholarly verification * Academic citation * Further research * Understanding of theoretical evolution ## Next Steps * Learn how tanāghīm relate to [Ajnās](/guide/ajnas/) * Explore [Taṣwīr (Transposition)](/guide/taswir/) capabilities * Understand [Starting Note Conventions](/guide/theoretical-framework/#starting-note-conventions) --- --- url: /docs/guide/ajnas.md description: Understanding ajnās as the building blocks of maqāmāt --- # Ajnās A jins is a unique sequence of 3, 4, or 5 notes (trichord, tetrachord, or pentachord), each defined by its characteristic interval pattern. The plural, ajnās, refers to multiple jins. Ajnās are the foundational building blocks of maqāmāt. Understanding ajnās is essential for comprehending how maqāmāt are structured. ## What is a Jins? A jins is a unique sequence of 3, 4, or 5 notes, each defined by its characteristic interval pattern that defines its identity. Unlike maqāmāt, ajnās are components that combine to form complete modal frameworks. ### Key Characteristics * **Size**: Typically 3-5 pitch classes * **Structure**: Defined by intervallic relationships between consecutive notes * **Note name-based**: Constructed using Persian-Arab-Ottoman note names * **Compatibility**: Dependent on tuning system (not all ajnās work in all tuning systems) ## Construction and Compatibility Ajnās are constructed based on their constituent note names. For a jins to be possible in a given tuning system, **all required note names must exist within the system**. ### Example: Jins Kurd **Note sequence**: dūgāh → kurdī → chahārgāh → nawā **Compatibility Check:** * ✅ **Al-Kindī system**: All note names exist → Jins kurd is possible * ❌ **Some systems**: Missing one or more note names → Jins kurd is not possible The platform automatically searches the tuning system when determining ajnās compatibility. ## Jins Transpositions A jins transposition is the systematic shifting of a jins to begin from a different pitch class while **preserving its intervallic relationships**. This is not simply moving pitches up or down by a fixed amount—instead, it involves pattern matching the original sequence of intervals against all possible starting positions within the tuning system. ### Naming Convention Transpositions follow Arabic music theory naming: * **Base form**: The jins on its own tonic (e.g., "jins kurd" starting on dūgāh) * **Taṣwīr**: A transposition to another modal degree (e.g., "jins kurd al-ḥusaynī" starting on ḥusaynī) * **Octave rendering**: The base form an octave away (e.g., "jins kurd al-muḥayyar", since muḥayyar is the octave of dūgāh). Not a transposition **Example:** * Original: Jins kurd starting on dūgāh → **jins kurd** * Transposition: Same interval pattern starting on ḥusaynī → **jins kurd al-ḥusaynī** When a maqām degree matches more than one jins under this naming, [suyūr attestation decides which one leads the display](/guide/maqamat/#multiple-ajnas-on-one-degree). ### How Transposition Works The transposition algorithm: 1. Extracts the interval pattern from the original jins 2. Systematically searches through the tuning system 3. Finds all valid starting points where the complete interval pattern can be realized 4. Generates transposition objects with appropriate naming **Algorithm Details:** * Uses recursive sequence building with early termination * Matches interval patterns (not fixed pitches) * Considers cents tolerance for fuzzy matching (±5 cents default) * Handles both exact fractional ratios and approximate matches ## Ajnās Within Maqāmāt One of the platform's most significant analytical capabilities is identifying which ajnās exist within each maqām across different tuning systems and transpositions. ### Automatic Detection When you select a maqām, the platform automatically: 1. Searches both ascending and descending sequences 2. Compares subsequences against known ajnās interval patterns 3. Identifies matches using configurable cents tolerance 4. Generates jins entries with: * Transposed name (following "jins \[name] al-\[starting note]" convention) * Specification of ascending or descending appearance * Precise intervallic structure within the maqām context ### Example Analysis When analyzing **maqām rāst** transposed to begin on nawā, the algorithm might identify: * jins rāst al-nawā (in ascending sequence) * jins bayāt al-ḥusaynī (in ascending sequence) * jins segāh al-awj (in descending sequence) * jins rāst al-muḥayyar (in ascending sequence) This comprehensive analysis reveals the primary structural ajnās that define the maqām's character. ## Using Ajnās ### Via REST API ```bash # Get all ajnās curl https://diarmaqar.net/api/ajnas # Get specific jins with zalzalian intervals curl "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents" ``` ## Bibliographic Sources Ajnās in DiArMaqAr are compiled from: * Historical Arabic music theory treatises * Modern scholarly works (Al-Shawwā 1946, Al-Ḥilū 1961, etc.) * Performance practice documentation Each jins includes: * Complete bibliographic references * Source and page citations * Historical context ## Next Steps * Learn about [Maqāmāt](/guide/maqamat/) that combine ajnās * Explore [Taṣwīr (Transposition)](/guide/taswir/) in depth * Understand how ajnās relate to [Intiqāl (Modulation)](/guide/intiqal/) --- --- url: /docs/guide/maqamat.md description: Understanding maqāmāt as complete modal frameworks --- # Maqāmāt Maqām is a complete modal framework built from an ordered sequence of pitch classes (typically 7–13+ notes), ascending (ṣuʿūd) and descending (hubūṭ) sequences (which may differ), positioning of multiple ajnās at specific maqām degrees, melodic development pathways (suyūr), and unique theoretical and aesthetic properties. ## What is a Maqām? Maqām is a complete modal framework that differs from ajnās in its scope and structure, representing a complete modal framework rather than a building block component. ### Structure Each maqām contains: **Ascending Sequence (Ṣuʿūd):** * Seven or more notes defining the upward melodic path * Represents how the maqām develops when ascending **Descending Sequence (Hubūṭ):** * Seven or more notes defining the downward melodic path * Can be identical to the ascending sequence or different **Asymmetrical Structures:** * Many maqāmāt employ different sequences in ascent and descent * The platform visually distinguishes notes that appear only in descending sequence * This asymmetry is a characteristic feature of Arabic maqām practice ## Construction and Compatibility Similar to ajnās, maqāmāt are constructed based on constituent note names and are subject to tuning system compatibility. **Requirements:** * All note names in both ascending and descending sequences must exist within the selected tuning system * If any required note name is missing, the maqām is not possible in that tuning system **Example:** Maqām farahfazza in Al-Kindī's tuning system extends from yegāh to ḥusaynī, utilizing notes across this range. ## Ajnās Within Maqāmāt As building blocks, ajnās combine to form maqāmāt. The platform automatically analyzes each maqām to identify: * Which ajnās appear in the ascending sequence * Which ajnās appear in the descending sequence * Whether they are in their base form or transposed (taṣwīr) * Their precise intervallic structure within the maqām context **Analysis Algorithm:** * Searches every starting point within both sequences * Compares subsequences of 3-5 consecutive notes * Matches against known ajnās interval patterns * Uses cents tolerance mechanism for performance practice variations ### Multiple Ajnās on One Degree A maqām degree often satisfies the interval pattern of more than one jins. Most of these are not real ambiguity: the ajnās involved share an identical interval pattern and exist as separate entries only because tradition seats that one shape on different notes. Jins rāst and jins yegāh are the same shape, named for where each is conventionally played. The platform shows every jins that matches a degree, stacked together on that degree. Nothing is hidden in favor of a single "correct" reading. **Ordering.** Where a degree carries more than one match, which one leads is decided by the suyūr. A sayr's stops record which jins the historical sources actually name at a given note, and that recorded usage is evidence, while a jins's structural seat — the note tradition treats as its home — is only inference. Evidence outranks inference: at the degree nawā in maqām rāst, jins yegāh is the jins conventionally seated there, but the suyūr, across the whole corpus, repeatedly name jins rāst at nawā and never jins yegāh — so jins rāst leads instead. Where the suyūr are silent about a family, seating decides instead, and a jins nested inside a longer one ranks below the jins containing it. Where even that ties, a stable identifier settles it, so the order shown never depends on how the underlying data happens to be listed. **Families.** A maqām named for one of its own ajnās is classified under that eponymous jins even when a different reading leads the tonic degree's display — maqām nawā athar's tonic also matches jins nikrīz, but the maqām still files under nawā athar. Family names always carry the jins's full name rather than a truncated first word — nawā athar, rāḥat al-arwāḥ, ḥijāz kār kurd — and keep any source attribution that distinguishes readings, so būselīk (al-Shawwā) and būselīk (al-Ḥilū) remain separate families. ## Maqām Transpositions Like ajnās, maqāmāt can be systematically transposed to begin from different pitch classes while preserving their essential intervallic relationships and directional characteristics. ### How It Works The transposition algorithm: 1. **Separately processes** both ascending and descending sequences 2. **Ensures** all required note names exist within the tuning system 3. **Maintains** original intervallic relationships 4. **Recalculates** all embedded ajnās for each transposition 5. **Generates** transposed names following "maqām \[name] al-\[starting note]" convention ### Example **Original:** Maqām farahfazza starting on yegāh **Transposition:** Maqām farahfazza starting on rāst → **"maqām farahfazza al-rāst"** Each transposition: * Retains original intervallic relationships between consecutive notes * Adapts to the new tonal center * Automatically recalculates constituent ajnās * Maintains ascending/descending sequence characteristics ## Maqām Suyūr Suyūr (singular: sayr) represent traditional melodic development pathways that define how a maqam unfolds in performance practice. They go beyond basic ascending and descending sequences to describe: * Characteristic melodic progressions * Emphasis points * Developmental patterns * Traditional performance practices **Structure:** * Implemented as sequences of "stops" * Each stop can be: a note, a jins, a maqām, or a directional instruction * Automatically transposed when the maqām is transposed See the [Suyūr Guide](/guide/suyur/) for detailed information. ## Using Maqāmāt ### Via REST API ```bash # Get all maqāmāt curl https://diarmaqar.net/api/maqamat # Get specific maqām with full details curl "https://diarmaqar.net/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents" # List transpositions (dedicated endpoint) curl "https://diarmaqar.net/api/maqamat/maqam_bayyat/transpositions?tuningSystem=alfarabi_950g&startingNote=ushayran" # Include modulation analysis curl "https://diarmaqar.net/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&includeModulations=true" ``` ## Bibliographic Sources Maqāmāt in DiArMaqAr are compiled from: * Historical Arabic music theory treatises (9th-20th centuries) * Modern scholarly works * Performance practice documentation Each maqām includes: * Complete bibliographic references * Source and page citations * Multilingual commentary (Arabic/English/French) * Suyūr from original sources * Historical context ## Visual Analysis The platform provides multiple visualization modes: * **Tabular display**: Mathematical details for all pitch classes * **Pitch class bar**: Visual representation with highlighting * **Ascending/descending notation**: Clear distinction of sequences * **Ajnās overlay**: Visual indication of constituent ajnās ## Next Steps * Learn about [Suyūr](/guide/suyur/) * Explore [Taṣwīr (Transposition)](/guide/taswir/) capabilities * Discover [Intiqāl (Modulation)](/guide/intiqal/) networks * Understand [Bibliographic Sources](/guide/bibliographic-sources/) --- --- url: /docs/guide/suyur.md description: Understanding suyūr as traditional melodic development pathways --- # Suyūr Suyūr are conventional melodic pathways for developing or modulating within maqām frameworks. These are characteristic modal transformations or transitions, generally understood in performance practice. They go beyond the basic ascending and descending sequences to describe characteristic melodic progressions, emphasis points, and developmental patterns. ## What are Suyūr? Suyūr are structured descriptions of how maqāmāt are traditionally developed in performance. While the ascending and descending sequences define the basic structure, suyūr describe the actual melodic pathways musicians follow. ### Historical Documentation Suyūr documentation appears in important Arabic music theory sources: * Meshshāqa (1899) * Al-Shawwā (1946) * Al-Ṣabbāgh (1950) * Al-Ḥilū (1961) **Important Note:** In these historical sources, suyūr are always presented as prose text and are never represented for transpositions of any given maqām. DiArMaqAr addresses this limitation through computational transposition of suyūr. ## Structure: "Stops" Suyūr are implemented as structured sequences of "stops," where each stop represents: **Note Stops:** * A specific note from the Persian-Arab-Ottoman naming convention * Example: "dūgāh" or "ḥusaynī" **Jins Stops:** * A reference to a jins * Maintains structural identity while allowing transposition **Maqām Stops:** * A reference to another maqām * Allows description of modulatory pathways **Directional Instructions:** * Standalone instructions like "ascending" or "descending" * Indicate melodic direction **Combined Instructions:** * Direction combined with note/jins/maqām * Example: "ascending to nawā" Jins stops do more than record structural identity: the sources naming a jins at a note is exactly the evidence used to [decide which jins leads when a maqām degree matches several](/guide/maqamat/#multiple-ajnas-on-one-degree). ## Transposition of Suyūr One of the platform's innovative features is the **automatic transposition of suyūr** to any possible maqām transposition. ### How It Works The `transposeSayr()` function operates through three stages: 1. **Calculate Transposition Interval** * Compares the first notes of original and target maqāmāt * Determines the interval shift required 2. **Apply Intelligent Note Shifting** * Shifts note stops by the calculated interval * Includes bounds checking to prevent invalid transpositions * Maintains musical logic 3. **Process Different Stop Types** * **Note stops**: Direct pitch transposition * **Jins stops**: Maintain structural identity while transposing starting note * **Maqām stops**: Transpose to equivalent maqām transposition * **Directional instructions**: Remain unchanged ### Example **Original Sayr for Maqām Rāst (starting on dūgāh):** ``` dūgāh → ascending → segāh → jins bayāt al-segāh → nawā ``` **Transposed Sayr for Maqām Rāst (starting on nawā):** ``` nawā → ascending → kurdān → jins bayāt al-kurdān → muḥayyar ``` ## Which Suyūr Can Be Played A sayr is shown, returned by the API and counted in the [statistics](/api/#statistics) only where it can be played: in the tuning system and on the starting note selected, on the maqām form being shown. On a taṣwīr or an octave rendering, the sayr is first moved onto that form's tonic, then judged. Every stop must be playable: * **Note stops**: the tuning system has the note, and moving the sayr does not push it past either end of the tuning system's range. * **Jins and maqām stops**: the tuning system lists that jins or maqām on that note as one of its forms (its base form, a taṣwīr or an octave rendering), with the same intervals within the cents tolerance. Having the notes is not enough. * **Directional instructions**: always playable. For example, Cairo Congress (1929) on yegāh has the notes nawā, ḥusaynī, awj and kurdān. But between them the steps are 200, 149 and 149 cents, while jins rāst is 204, 149 and 159 cents. The last step differs by 10 cents, beyond the 5-cent tolerance, so this tuning system has no jins rāst on nawā, and a sayr that moves to jins rāst on nawā is not playable there. In al-Kindī's tuning system (874), the sayr of maqām nikrīz that descends to ʿirāq is not playable, because the tuning system has no ʿirāq. A jins or maqām stop that names no starting note sits on that jins's or maqām's own first note, and moves with the rest of the sayr. ## Multilingual Support Suyūr are preserved in their original Arabic form with translations: * Original Arabic prose from historical sources * English (and French, where applicable) translations maintaining scholarly accuracy * Library of Congress Arabic Romanization standard ## Using Suyūr ### Via REST API Suyūr are included in maqām responses: ```bash # Get maqām with suyūr curl "https://diarmaqar.net/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&includeSuyur=true" # Transpositions are listed via the transpositions endpoint (combine with the detail response as needed) curl "https://diarmaqar.net/api/maqamat/maqam_bayyat/transpositions?tuningSystem=alfarabi_950g&startingNote=ushayran" ``` ## Research Applications The computational transposition of suyūr enables: * **Systematic exploration**: All possible melodic pathways across pitch centers * **Comparative analysis**: How suyūr vary across transpositions * **Theoretical investigation**: Relationships between structure and performance practice * **Pedagogical use**: Learning traditional pathways in different keys ## Historical Significance Suyūr represent one of the most detailed aspects of Arabic maqām theory that has rarely been systematically documented in computational form. By making these pathways accessible and transposable, DiArMaqAr provides unprecedented tools for: * Understanding traditional performance practices * Comparing theoretical frameworks * Exploring melodic development patterns * Supporting contemporary composition informed by tradition ## Next Steps * Learn about [Maqāmāt](/guide/maqamat/) structure * Explore [Taṣwīr (Transposition)](/guide/taswir/) capabilities * Understand [Intiqāl (Modulation)](/guide/intiqal/) practices * Review [Bibliographic Sources](/guide/bibliographic-sources/) --- --- url: /docs/guide/taswir.md description: Understanding tuning-system-sensitive transposition capabilities --- # Taṣwīr (Transposition) Transposition is one of DiArMaqAr's most sophisticated features, enabling systematic analysis of how any jins or maqām can be shifted to different starting pitches while maintaining essential intervallic relationships. ## Overview In written Arabic maqām theory, transposition is recognised as a fundamental feature of maqāmic practice, but transpositions are rarely explicitly rendered in full. DiArMaqAr's transposition capabilities represent a significant computational advancement, revealing theoretical possibilities that would require extensive manual calculation to discover. ## How Transposition Works Transposition is **not** simply moving pitches up or down by a fixed amount. Instead, it involves: 1. **Extracting the interval pattern** from the original structure 2. **Systematically applying** the pattern to all possible starting points 3. **Pattern matching** against the tuning system's available pitch classes 4. **Preserving intervallic relationships** while adapting to new tonal centers ### Interval Pattern Extraction The algorithm: * Cross-references maqām/jins note name sequences to the tuning system * Extracts the sequence of intervals between consecutive notes * Uses these intervals (not fixed pitches) as the pattern to match ### Matching Process **For systems using fractional ratios:** * Requires exact fractional ratio matches * Mathematical precision is preserved **For systems using any other original input data type (decimal ratios, string lengths, fret divisions or cents):** * Uses cents values for matching * Applies user-definable ±cents tolerance (default: ±5 cents, Just Noticeable Difference JND) to allow for performance practice variations. ## Jins Transposition A jins transposition systematically shifts a jins to begin from a different pitch class while preserving its intervallic relationships. ### Example: Jins Kurd **Base form:** Jins kurd starting on dūgāh * Pattern: dūgāh → kurdī → chahārgāh → nawā * Intervals: \[specific cents pattern] **Transposition (Taṣwīr):** Jins kurd starting on ḥusaynī * Pattern: ḥusaynī → \[notes maintaining same intervals] * Name: "jins kurd al-ḥusaynī" Jins kurd on muḥayyar is *not* a transposition. Muḥayyar is the octave of dūgāh, so it is the base form one octave up: an octave rendering. ### Algorithm Characteristics * **Recursive search**: Finds all valid starting points * **Early termination**: Optimizes performance * **Automatic generation**: All possible transpositions are calculated * **Naming convention**: Follows Arabic maqām theory ("jins \[name] al-\[starting note]") ## Maqām Transposition Maqām transposition handles both ascending and descending sequences separately, accounting for the fact that many maqāmāt employ different sequences in their ascent and descent. ### Algorithm Details 1. **Separate Processing**: Ascending and descending sequences analyzed independently 2. **Validation**: Ensures all required note names exist in the tuning system 3. **Interval Preservation**: Maintains original intervallic relationships 4. **Automatic Recalculation**: All embedded ajnās recalculated for each transposition 5. **Suyūr Transposition**: Associated suyūr automatically transposed ### Example: Maqām Faraḥfazza **Original:** Starting on yegāh * Ascending: yegāh → rāst → dūgāh → ... * Descending: \[possibly different sequence] **Transposition:** Starting on rāst → "maqām faraḥfazza al-rāst" * Ascending: rāst → \[transposed maintaining intervals] → ... * Descending: \[transposed maintaining intervals] * All ajnās recalculated * All suyūr transposed ## Computational Complexity The implementation employs: * **Recursive sequence building** with early termination * **O(n×m×k) complexity** where: * n = available pitch classes * m = pattern length * k = tolerance width This efficiency enables: * Real-time transposition generation * Comprehensive dataset export (all transpositions for all maqāmāt) * Large-scale comparative analysis ## API Naming Conventions for Transpositions When working with transposed maqāmāt in the API, it's important to understand how identifiers work. ### Two ID Fields Each maqām node in API responses includes two identifier fields: | Field | Purpose | Stability | Example | |-------|---------|-----------|---------| | `baseMaqamIdName` | Query/lookup identifier | **Stable** across transpositions | `maqam_nahawand` | | `maqamIdName` | Display identifier | **Changes** with transposition | `maqam_nahawand_al_nawa` | ### Naming Pattern * **Base form**: Uses base name only → `maqam_nahawand` * **Transposed form (taṣwīr)**: Adds `_al_{tonic}` suffix → `maqam_nahawand_al_nawa` * **Octave rendering**: Adds the same suffix → `maqam_nahawand_al_kurdan` (kurdān is the octave of rāst, so this is not a transposition) ### Querying Transposed Maqāmāt **To find a specific transposition, use base maqam ID + tonic parameters:** ```bash # Find maqām nahāwand on nawā ?toMaqam=maqam_nahawand&toTonic=nawa # ✅ Correct # NOT the display name format ?toMaqam=maqam_nahawand_al_nawa # ❌ Will not work ``` ### Example Response ```json { "from": { "baseMaqamIdName": "maqam_rast", "maqamIdName": "maqam_rast", "maqamDisplayName": "maqām rāst", "isTransposition": false }, "to": { "baseMaqamIdName": "maqam_nahawand", "maqamIdName": "maqam_nahawand_al_nawa", "maqamDisplayName": "maqām nahāwand al-nawā", "isTransposition": true } } ``` ::: tip Always use `baseMaqamIdName` + `tonic` parameters for API queries. The `maqamIdName` field is for display purposes and includes the transposition suffix. ::: ## Using Transposition ### Via REST API ```bash # List all transpositions for a maqām in a tuning context (separate endpoint) curl "https://diarmaqar.net/api/maqamat/maqam_rahat_alarwah/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah" # Or fetch full pitch-class detail for one realization: curl "https://diarmaqar.net/api/maqamat/maqam_rahat_alarwah?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents" # The transpositions response includes entries with: # - Transposed name # - Ascending/descending sequences # - Recalculated ajnās # - Transposed suyūr ``` ## Research Applications Transposition capabilities enable: * **Systematic exploration**: All mathematically valid possibilities * **Comparative analysis**: How transposition possibilities vary across tuning systems * **Theoretical investigation**: Relationships between tuning systems and modal availability * **Dataset generation**: Complete mappings for machine learning applications ### Example Research Questions * Which tuning systems support the most transpositions for a given maqām? * How do starting note conventions affect transposition possibilities? * What is the relationship between tuning system complexity and transposition availability? ## Next Steps * Learn about [Intiqāl (Modulation)](/guide/intiqal/) (related but distinct) * Explore [Tuning Systems](/guide/tuning-systems/) and their impact on transposition * Understand how transposition relates to [Ajnās](/guide/ajnas/) --- --- url: /docs/guide/intiqal.md description: Understanding Al-Shawwā's modulation algorithm and modulation networks --- # Intiqāl (Modulation) DiArMaqAr implements the **first algorithmic interpretation** of Sāmī al-Shawwā's (1946) modulation guidelines, enabling systematic exploration of intiqālāt (modulation practices) networks that were previously documented only in prose. ## Overview Unlike Anglo-European modulation theory, Turkish makam theory, or contemporary Arabic theoretical approaches, Al-Shawwā's method employs specific conditions based on maqām degree relationships within the Persian-Arab-Ottoman note naming framework. ### Historical Context Sāmī Al-Shawwā, a revered Cairo-born, Aleppine violinist, provided unique guidelines for maqām modulation in his 1946 work *Al-Qawāʿid al-Fannīya fī al-Mūsīqa al-Sharqīya wa al-Gharbīya* (The Artistic Principles of Eastern and Western Music). **Key Principle:** Modulation should occur through specific maqām degree relationships while maintaining "good disposition" (ḥusn al-taṣarruf) and avoiding abrupt transitions that would be "hard on the ear" (ṣaʿb ʿalā al-udhun). This approach emphasizes **melodic connection** rather than harmonic compatibility, reflecting the fundamentally melodic nature of maqāmic practice. ## Theoretical Foundation ### The 24-Tone Classification System Al-Shawwā classified a 24-tone system into three categories based on the Persian-Arab-Ottoman note naming framework: 1. **Aṣlīya or Ṭabīʿīya** (Original/Natural): Represented as "n" * These are stable, consonant maqām degrees that form the foundation of maqām structure which are whole tones and three-fourths tones. 2. **Anṣāf** (Half-notes, sing. niṣf): Represented as "h" (niṣf, half) * These represent the half-tones 3. **Arbāʿ** (One-fourth notes, sing. rubʿ): Represented as "q" (rubʿ, quarter) * These represent one-fourth tones, reflecting our understanding of Arabic maqām theory dividing a whole tone into four unequal parts (not equal divisions) ### The Shawwā Function Implemented as: *sh(n): N → {"n", "h", "q", "/"}* This function evaluates the validity of proposed modulations based on the specific classification of individual note names within the 24-tone system. The function returns "n" for natural/original notes, "h" for half-notes (anṣāf), "q" for quarter-notes (arbāʿ), and "/" for notes outside Al-Shawwā's theoretical framework. ## Modulation Rules The algorithm evaluates multiple cases for valid transitions: ### 1. Tonic Correspondence Modulation between maqāmāt sharing the same tonic (qarār). Al-Shawwā opens his guidelines by requiring that every maqām rest its qarār "on one of the seven original «natural» notes, or on a niṣf of the seven anṣāf" — so the tonic must be classified as an "original" note ("n") or a half-note ("h"). A quarter-note ("q") tonic falls outside his framework. ### 2. Third-Degree Modulation Transition where the third degree of the source maqām becomes the tonic of the target, valid only when: * The third degree is classified as an "original" note (aṣlīya/ṭabīʿīya, represented as "n") ### 3. Alternative Third-Degree Modulation If the standard third degree is invalid, Al-Shawwā permits using an anṣāf (half-note, represented as "h") maqām degree immediately below it, provided: * It is the sixth pitch class from the fundamental (qarār) maqām degree of the source maqām according to the 24-tone list * It maintains a distance of two pitch classes from the preceding maqām degree within the source maqām ### 4. Fourth and Fifth-Degree Modulation Transitions using the fourth or fifth maqām degrees of the source maqām as the tonic of the target. Al-Shawwā attaches no condition of their own to these degrees. The only constraint is his opening principle that every maqām rests its qarār on an original note or on a niṣf, and a pivot works by hosting the target's qarār — so the fourth or fifth degree must be classified "n" or "h". A "q" (rubʿ) degree can host no qarār. ### 5. Sixth-Degree Modulation (No Third) When both the third degree and its alternative are invalid, modulation may occur through the sixth maqām degree, provided: * It is the sixteenth or seventeenth pitch class from the tonic of the source maqām * It remains an "original" maqām degree (aṣlīya/ṭabīʿīya, represented as "n") ### 6. Sixth-Degree Modulation (Between Naturals) The sixth maqām degree may also be used when it is a half-note ("h") lying between two "natural" maqām degrees — al-Shawwā's example is ʿajam over dūgāh in maqām al-bayyāt, "a niṣf confined between two natural notes, ḥusaynī and awj". Unlike rule 5 this is not a fallback: bayyāt's third degree is perfectly valid. ## Algorithmic Implementation The `modulate.ts` function implements these rules using Al-Shawwā's specific 24-tone classification system as the reference framework. **Process:** 1. Evaluates source maqām's maqām degrees according to Al-Shawwā's classification 2. Tests each modulation rule against potential target maqāmāt 3. Generates list of valid modulation pathways 4. Creates interactive networks showing relationships ## Using Modulation Analysis ### Via REST API ```bash # Get modulation analysis for a maqām (example: principle maqām used in adhān) curl "https://diarmaqar.net/api/maqamat/maqam_hijaz?tuningSystem=ibnsina_1037&startingNote=yegah&includeModulations=true&pitchClassDataType=cents" # Response includes: # - Valid modulation targets # - Modulation type (third-degree, fourth-degree, etc.) # - Network relationships ``` ## Research Applications The implementation of the Shawwā algorithm enables: ### Modulation Network Analysis * **Interactive lists**: All valid modulation pathways from any maqām * **Network visualization**: Structural relationships between maqāmāt * **Hub identification**: Central maqāmāt serving as modulation hubs * **Cluster analysis**: Groups of closely related modes ### Quantitative Analysis * **Pattern recognition**: Systematic modulation structures * **Comparative studies**: How modulation possibilities vary across tuning systems * **Theoretical investigation**: Validation against historical practices ### Compositional Applications * **Systematic exploration**: Discover modulation pathways * **Traditional frameworks**: Informed by historical theory * **Creative practice**: Contemporary composition grounded in tradition ## Limitations and Context The modulation algorithm: * Represents **one theoretical perspective** (Al-Shawwā 1946) * Is historically accurate to documented approach * Could benefit from incorporating additional frameworks * May be supplemented by audio analysis of recorded performances Future enhancements could integrate: * Modulation analysis from audio recordings * Additional theoretical frameworks * Performance practice documentation * Contemporary compositional approaches ## Next Steps * Explore [Taṣwīr (Transposition)](/guide/taswir/) capabilities * Learn about [Maqāmāt](/guide/maqamat/) structure * Understand [Bibliographic Sources](/guide/bibliographic-sources/) * Review [Research Applications](/guide/research-applications/) --- --- url: /docs/guide/audio-synthesis.md description: >- Real-time audio synthesis capabilities for auditioning maqāmāt and tuning systems --- # Audio Synthesis DiArMaqAr provides real-time audio synthesis capabilities that allow users to audition precise intonational relationships of maqāmāt and their ajnās across different tuning systems, hearing the theoretical data as actual sound. ## Overview Real-time audio synthesis utilizes the Web Audio API through a dedicated SoundContext provider that manages oscillator nodes, envelope control, and MIDI integration. This enables immediate auditory feedback for theoretical concepts, making abstract relationships tangible through sound. ## Key Features ### Individual Note Playback * Select any pitch class and hear its precise intonation * Compare intervals between different notes * Audition tuning system pitch classes independently of maqām structures ### Sequence Synthesis * Play ascending sequences of maqāmāt or ajnās * Play descending sequences * Pattern playback with rhythmic variations * Demonstrate modal character beyond abstract sequences ### Pattern Playback * Pre-defined melodic patterns (patterns.json) * Customizable tempo (BPM) * Rhythmic cells and motifs * Dynamic control (velocity specifications) ## Waveform Support The audio system supports multiple periodic and aperiodic waveforms: **Periodic Waveforms:** * Sine * Triangle * Sawtooth * Square **Aperiodic Waveforms:** * Multiple custom waveforms (as utilized in Scale Workshop) * Rich harmonic content options * Instrument-like timbres ### Envelope Control (ADSR) Precise control over sound articulation: * **Attack**: Initial rise time (default: 0.01s) * **Decay**: Initial fall time (default: 0.20s) * **Sustain**: Sustained level (default: 0.50) * **Release**: Final fall time (default: 0.40s) This allows for: * Realistic musical articulation * Expressive control * Comparison between different tunings with consistent articulation ## Tuning System Fidelity The audio synthesis maintains **mathematical precision** when rendering tuning systems: * **Non-12-EDO intervals**: Accurately rendered without artifacts * **Fractional ratios**: Precisely calculated frequencies * **Historical tunings**: Authentic intonational relationships * **No quantization**: Continuous pitch variation preserved ## Real-Time Processing The implementation ensures: * **Low latency**: Suitable for real-time interaction * **Responsive interface**: No blocking during audio generation * **Smooth playback**: Continuous sequences without gaps * **Performance optimization**: Efficient Web Audio API usage ## Interactive Features ### Keyboard Input * Computer keyboard mapping to pitch classes * Real-time response to key presses * Visual feedback on pitch class bar * Immediate auditory feedback ### MIDI Integration * External MIDI controller support * Real-time input processing * Low-latency response * Both monophonic and polyphonic capabilities See the [MIDI Integration Guide](/guide/midi-integration/) for detailed MIDI features. ## Research Applications Real-time audio synthesis enables: ### Comparative Listening * Compare same maqām across different tuning systems * Hear how historical tunings affect modal character * Understand theoretical differences through direct experience ### Educational Use * Students can hear theoretical concepts * Immediate feedback on learning materials * Auditory reinforcement of visual/analytical work ### Compositional Exploration * Composers can audition theoretical possibilities * Discover new harmonic/melodic relationships * Explore tuning systems before composition ## Technical Implementation The audio system: * Uses Web Audio API for browser-based synthesis * Supports all major browsers (Chrome, Firefox, Safari, Edge) * Implements graceful degradation for older platforms * Manages oscillator nodes efficiently * Handles precise frequency calculations for all intervals ## Limitations Current implementation focuses on: * Theoretical representation (not performance practice analysis) * Synthetic waveforms (not sampled instruments) * Browser-based synthesis (subject to browser audio limitations) Future enhancements could include: * Audio analysis capabilities for recorded performances * Integration with digital audio workstations * Mobile application support * Expanded waveform library ## Next Steps * Learn about [MIDI Integration](/guide/midi-integration/) for advanced control * Explore [Data Export](/guide/data-export/) for external synthesis * Understand how audio relates to [Tuning Systems](/guide/tuning-systems/) --- --- url: /docs/guide/midi-integration.md description: >- MIDI input/output capabilities including MPE support for precise non-12-EDO playback --- # MIDI Integration DiArMaqAr implements sophisticated MIDI integration allowing users to interact with any tuning system, or the subsequences of ajnās or maqāmāt, through both computer keyboard and MIDI controller input, with precise pitch output capabilities for all intervals. ## Overview The platform supports comprehensive MIDI functionality: * **Input**: Computer keyboard and MIDI controllers * **Output**: Monophonic and MPE (MIDI Polyphonic Expression) * **Precision**: 14-bit pitch bend for accurate non-12-EDO intervals * **Real-time**: Low-latency response for live exploration ## MIDI Input ### Computer Keyboard * QWERTY keyboard mapping to pitch classes * Visual feedback on interface * Immediate response * No additional hardware required ### MIDI Controllers * External MIDI device support * Real-time input processing * Low-latency response * Works with any MIDI-compatible controller **Setup:** 1. Connect MIDI controller to computer 2. Browser will detect available MIDI devices 3. Select device from interface 4. Start playing ## MIDI Output ### Monophonic Output * Standard MIDI protocol * Single channel output * Wide accessibility * Compatible with most software and hardware ### MPE (MIDI Polyphonic Expression) **What is MPE?** MIDI Polyphonic Expression enables accurate tuning of polyphonic software and hardware synthesizers without tuning artifacts. Traditional MIDI uses pitch bend on a single channel for all voices, causing conflicts when playing non-12-EDO harmonies. **How MPE Works:** * Each voice gets its own MIDI channel * Individual pitch bend per channel * No conflicts between simultaneous pitches * Precise non-12-EDO intervals preserved **MPE Precision:** * **14-bit pitch bend**: High resolution control messages * **Accurate conversion**: Fractional ratios and cents converted to precise MIDI values * **No artifacts**: Pitch relationships remain accurate in digital audio workstations * **Polyphonic harmony**: Multiple non-12-EDO pitches simultaneously ## Pitch Bend Calculation The system uses 14-bit pitch bend calculations to achieve precise non-12-EDO intervals: **Process:** 1. Converts fractional ratios/cents to target frequency 2. Calculates deviation from 12-EDO equivalent 3. Generates 14-bit pitch bend value 4. Sends on appropriate MIDI channel (MPE) or channel 1 (monophonic) **Precision:** * Maintains mathematical accuracy * Preserves pitch relationships essential to traditional practice * Enables authentic playback of all intervals in external systems ## Use Cases ### Live Performance * Perform maqāmāt using MIDI controllers * Real-time exploration of tuning systems * Integration with external synthesizers ### Composition * Export MIDI data to DAWs * Use MPE-capable instruments * Create compositions with authentic tunings ### Research * Audition theoretical data through external systems * Compare different synthesizers/samplers * Test tuning system compatibility ### Education * Interactive learning with MIDI keyboards * Hands-on exploration of maqāmic relationships * Integration with music education tools ## Technical Details ### Voice Distribution (MPE) The system manages voice distribution across multiple MIDI channels: * Automatic channel assignment * Voice allocation and release * Conflict prevention * Efficient channel management ### Latency * **Low-latency processing**: Real-time input handling * **Optimized routing**: Direct MIDI I/O * **Browser compatibility**: Works with Web MIDI API ### Compatibility * **Hardware**: Any MIDI-compatible controller * **Software**: DAWs supporting MIDI and MPE * **Browsers**: Chrome, Edge, Opera (Web MIDI API support) ## Integration with DAWs DiArMaqAr MIDI output can be used with: * **Ableton Live**: MPE support for non-12-EDO playback * **Logic Pro**: MIDI and MPE compatibility * **Bitwig Studio**: Native MPE support * **Reaper**: MIDI routing capabilities * **Any DAW**: Basic MIDI output (monophonic mode) ## Limitations * **Browser support**: Web MIDI API not available in all browsers * **MPE requirement**: External systems must support MPE for polyphonic non-12-EDO playback * **Latency**: Browser audio processing may introduce slight latency ## Next Steps * Learn about [Audio Synthesis](/guide/audio-synthesis/) capabilities * Explore [Data Export](/guide/data-export/) including Scala formats * Understand [Tuning Systems](/guide/tuning-systems/) for MIDI applications --- --- url: /docs/guide/data-export.md description: Comprehensive data export capabilities for research and composition --- # Data Export DiArMaqAr provides comprehensive data export capabilities designed to support both academic research and practical music-making applications. Users can export complete datasets including tuning systems, ajnās, maqāmāt, and modulation analysis results in structured formats. ## Export Formats ### JSON Structured, machine-readable format maintaining complete data relationships: ```json { "maqam": { "name": "Maqam Rast", "ascendingSequence": [...], "descendingSequence": [...], "ajnas": [...], "transpositions": [...], "modulations": [...] } } ``` **Use Cases:** * Programmatic access in other applications * Data analysis and processing * Integration with custom tools * API development ### CSV Tabular format suitable for spreadsheet software and statistical analysis: **Columns typically include:** * Pitch class values * Mathematical representations * Note names * Intervallic relationships * Source attributions **Use Cases:** * Statistical analysis * Spreadsheet manipulation * Data visualization * Quantitative research ### Scala (.scl and .kbm) Scala is a widely-used format for tuning system representation, compatible with many music software and hardware. #### Scala Tuning Files (.scl) * Contains tuning system definition with pitch ratios or cents * Comprehensive metadata from database * Proper formatting for Scala software * Includes bibliographic attribution #### Scala Keymap Files (.kbm) * Maps tuning system pitch classes to MIDI keys * Defines reference note and octave size * Enables accurate playback in compatible software **Use Cases:** * Integration with synthesizers and samplers * Contemporary composition practice * Software instrument design * Hardware synthesizer configuration #### 12-Pitch-Class Chromatic Set (.scl) * Available when exporting a maqām * Gives each pitch class the maqām uses, ascending and descending, its own key among the 12 keys of an octave * Fills the keys the maqām does not use with the tuning system's own chromatic pitch classes, or with those of al-Kindī (874) on the same starting note when the tuning system does not have all 12 * Exports exactly the transposition you are viewing, under that transposition's name Earlier versions could export a different transposition of the same maqām under the name of the one you had selected. That no longer happens. Some transpositions cannot form a 12-pitch-class set. For these, the option is shown disabled. The export window gives the reason: the key and the pitch classes that need it. It also lists the other tonics on which the maqām does fit, or says that no transposition of the maqām fits in this tuning system. See [Maqāmāt that cannot form a 12-pitch-class set](#maqamat-that-cannot-form-a-12-pitch-class-set). ### Maqāmāt that cannot form a 12-pitch-class set {#maqamat-that-cannot-form-a-12-pitch-class-set} A 12-pitch-class set assigns each pitch class a maqām uses to its own key on a keyboard with 12 keys per octave, such as a piano keyboard or a piano roll. Octaves count as the same pitch class. When a pitch class's key is already taken by another, it can move to the key next to it. A maqām does not fit when two of its pitch classes need the same key and the keys next to it are taken as well. This is rare. Such maqāmāt are always listed, with the key and the pitch classes that need it. **Example:** in al-Ṣabbāgh (1954) from rāst, maqām faraḥnāk (al-Ḥilū) on qarār segāh does not fit. Two of its pitch classes, ʿirāq (B-b2) and nīm kawasht (B-2), are 29.5 cents apart. Both need the B key. Neither can move, because the keys next to it are taken: nīm ʿajam is on Bb and rāst is on C. Where this is reported: * **In the app:** the 12-Pitch-Class Chromatic Set (.scl) export option is disabled for that transposition, with the reason and the tonics on which the maqām does fit. * **In the API:** the `/api/maqamat/classification/12-pitch-class-sets` endpoint lists every transposition that does not fit, with the key and the pitch classes that need it. See [Transpositions that do not fit a 12-pitch-class set](/api/#transpositions-that-do-not-fit-a-12-pitch-class-set). ## Export Options **For Maqāmāt:** * Include/exclude transpositions * Include/exclude modulation analysis * Include/exclude embedded ajnās * Include/exclude suyūr * Specify pitch data formats **For Tuning Systems:** * All pitch representations * Note name associations * Source attributions * Mathematical calculations **For Ajnās:** * Transposition data * Intervallic structures * Bibliographic references ## Complete Dataset Export The platform enables comprehensive dataset generation: ### All Transpositions Export all possible transpositions for: * All maqāmāt within a tuning system * All ajnās within a tuning system * Complete theoretical mappings ### Modulation Networks Export complete modulation matrices: * All valid modulation pathways * Network relationships * Comparative analysis data ### Comparative Analysis Export data for comparing: * Different tuning systems * Starting note conventions * Historical vs. modern approaches ## Research Applications ### Quantitative Analysis * Statistical analysis of modal relationships * Correlations between tuning system characteristics * Transposition and modulation pattern analysis * Large-scale comparative studies ### Machine Learning Datasets * Training data for maqām detection models * Feature engineering for classification * Ground truth labels with provenance * Structured, validated reference data ### Musicological Research * Systematic analysis of traditional repertoire * Comparative tuning system studies * Historical framework analysis * Theoretical validation studies ## Export Metadata All exports include: * **Complete source attribution**: Bibliographic references * **Mathematical details**: All pitch representations * **Cross-references**: Relationships between entities * **Provenance**: Transparent data origin * **Version information**: Data version and platform version ## Integration Examples ### Python Analysis ```python import json import pandas as pd # Load exported JSON with open('maqamat_export.json') as f: data = json.load(f) # Convert to DataFrame for analysis df = pd.DataFrame(data['maqamat']) # Perform statistical analysis ``` ### Scala Software 1. Export tuning system to .scl format 2. Import into Scala software 3. Load into compatible synthesizer 4. Play with accurate tuning ### DAW Integration 1. Export Scala files (.scl/.kbm) 2. Import into DAW (e.g., via MTS-ESP, Kontakt, etc.) 3. Create instruments with authentic tunings 4. Compose using historical frameworks ## Best Practices ### Data Verification * Always include source attribution in exports * Verify mathematical calculations * Check note name associations * Validate against original sources ### Format Selection * **JSON**: For programmatic access * **CSV**: For statistical analysis * **Scala**: For music software integration * **Custom**: For specific research needs ### Documentation * Document export parameters * Record source tuning system * Note any transformations applied * Maintain export logs ## Next Steps * Learn about [Research Applications](/guide/research-applications/) * Explore [Bibliographic Sources](/guide/bibliographic-sources/) * Understand [Tuning Systems](/guide/tuning-systems/) for export --- --- url: /docs/guide/research-applications.md description: Research use cases and academic applications of DiArMaqAr --- # Research Applications DiArMaqAr provides unprecedented tools for systematic investigation of maqāmic relationships while maintaining connection to conventional frameworks. This guide outlines key research applications and use cases. ## Comparative Tuning System Analysis The platform's integration of historical tuning systems enables comparative analysis of Arabic theoretical frameworks through consistent Persian-Arab-Ottoman note naming. ### Research Questions * How does the same maqām manifest across different temperaments? * What are the consistencies and variations in theoretical approaches? * How do historical tuning systems compare to modern frameworks? * What are the practical implications of theoretical choices? ### Methodology 1. Select a maqām (e.g., Maqām Rāst) 2. Compare across multiple tuning systems: * Al-Kindī (9th century ratios) * Al-Fārābī (10th century tunings) * Ibn Sīnā (11th century approaches) * Al-Ṣabbāgh (20th century comma-based system) 3. Analyze: * Pitch class values * Interval relationships * Available transpositions * Modulation possibilities ### Example: Theoretical Evolution Comparing Al-Fārābī's 10th-century ratios with Al-Ṣabbāgh's 20th-century comma-based system demonstrates: * Theoretical evolution over time * Maintenance of essential intervallic relationships * Impact of measurement approaches on modal availability ## Starting Note Convention Analysis A crucial analytical capability lies in systematic comparison of tuning systems based on different starting note conventions. DiArMaqAr supports three starting note names: **ʿushayrān**, **yegāh**, and **rāst**. ### Research Framework **Oud-Based Systems (ʿushayrān):** * Reflect the conventional tuning of the oud in perfect fourths (4/3) * ʿushayrān marks the 1/1, corresponding to the lowest of the four strings tuned in perfect fourths — the two or more strings lower in pitch remain tuning-independent * Examples: al-Kindī, al-Fārābī (oud conventions), al-Urmawī **Longnecked-Lute and Monochord/Sonometer Systems (yegāh/rāst):** * Derived from the fret divisions of longnecked lutes (Arabic tanbūr, Persian tar/sehtar, Turkish tanbur) or from monochord/sonometer measurements * Follow a theoretical framework rather than a fixed instrument tuning * Examples: al-Fārābī's Tanbūr al-Baghdādī and Tanbūr al-Khorasānī, through to the Tuning Committee of the 1932 Cairo Congress for Arabic Music Al-Fārābī appears in both categories because he described multiple tuning systems derived from different instruments. When a tuning system begins from ʿushayrān versus yegāh (which are a 9/8 whole-tone apart), the resulting intervallic relationships, the availability of specific maqāmāt and ajnās, and the modulation pathways can vary substantially. ### Research Applications 1. **Availability Analysis:** * Compare number of available maqāmāt * Compare number of available ajnās * Analyze transposition possibilities 2. **Modulation Networks:** * Compare modulation capabilities * Identify differences in pathway structures * Analyze theoretical accessibility 3. **Historical Instrument Practice:** * Understand how instrumental traditions affect theory * Reveal connections between practice and theory * Examine theoretical evolution ## Quantitative Analysis The platform's analytics capabilities provide quantitative insights into maqāmic relationships. ### Dataset Generation Export comprehensive datasets for: * All maqāmāt in selected tuning systems * All possible transpositions * Complete modulation networks * Ajnās compatibility matrices ### Statistical Analysis **Correlation Studies:** * Relationship between tuning system characteristics and transposition possibilities * Correlation between transposition availability and modulation networks * Impact of starting note conventions on modal accessibility **Pattern Recognition:** * Systematic modulation structures * Transposition frequency patterns * Ajnās distribution analysis ### Example Research Analyse relationships between: * Number of pitch classes and available maqāmāt * Starting note convention and transposition possibilities * Tuning system complexity and modulation network density **Concrete example (al-Shawwā modulation algorithm):** For maqām bayyāt on its conventional tonic of dūgāh in al-Ṣabbāgh's 24-tone comma-based tuning system (1954), the al-Shawwā modulation algorithm identifies **41 valid modulation pathways**, whereas al-Ṣabbāgh's book provides only **8 fixed modulation targets** for the same maqām. See §6.3 of the accompanying article for the full analysis. ## Musicological Research The platform enables systematic analysis of the documented maqām tradition that would be extremely laborious through manual cross-referencing of dispersed, multilingual sources. ### Repertoire Analysis (Forthcoming) The platform's current scope is theoretical rather than practice-based. Integration with audio analysis for recorded performances is an active research direction, alongside the forthcoming downstream projects described in the accompanying article (§8): * **Arabic Maqām Identification (MIR)**: automatic maqām identification from audio recordings, using DiArMaqAr's JSON exports as verified theoretical reference data * **Arabic Maqām Networks**: web-based visualisation and exploration of maqām construction and modulation networks across tuning systems * **Comparison between documented theory and performance practice**, once audio-analysis capabilities are integrated ### Maqām Naming and Classification **Theoretical Investigation:** * Analyse comma-based systems (e.g. al-Ṣabbāgh 1954) * Understand the relationship between transposition and naming * Investigate why certain maqām transpositions are given unique names even when sayr is not the differentiating factor ### Arabic Music Pedagogy **Tuning and Intonation Analysis:** * Ground pedagogical discussions in historically documented Arabic tuning systems rather than 24-EDO by default * Provide reference implementations that can support works which engage this subject critically (e.g. Farraj & Shumays 2019, chapter 11) * Replace unreferenced assertions about Arabic intonation with source-backed pitch-class data * Enable nuanced discussions beyond binary "quarter-tone vs. not quarter-tone" debates ## Machine Learning and AI Applications ### Training Data * **Ground truth labels**: Validated, computationally accessible reference data * **Structured datasets**: Ready for ML model training * **Provenance**: Transparent source attribution * **Comprehensive coverage**: Multiple tuning systems and historical frameworks ### Model Development * **Maqām detection**: Training data with verified labels * **Modulation prediction**: Network data for sequence modeling * **Transposition analysis**: Pattern recognition datasets * **Classification**: Features based on theoretical structures ### Dataset Construction Address limitations in existing research: * Documented ground truth methodology * Multiple performer/reciter data * Historical framework validation * Culturally specific feature engineering ## Computational Musicology ### Systematic Analysis * **Network analysis**: Modulation pathway structures * **Graph theory**: Relationships between maqāmāt * **Pattern recognition**: Recurring intervallic structures * **Comparative studies**: Cross-cultural modal analysis ### Infrastructure for Research Address gaps identified by Gedik and Bozkurt (2009): * Valid pitch-class definitions grounded in culturally specific frameworks * Computationally accessible theory * Verified reference data * Transparent methodology ## Instrument Design ### Tuning System Analysis * **Mathematical precision**: Exact pitch class values * **Historical frameworks**: Authentic reference data * **Hardware integration**: Scala export for synthesizers * **Software instruments**: Accurate implementation of all intervals ### Design Applications * Digital instrument interfaces * Software synthesizer design * Hardware controller mapping * Pedagogical instrument development ## Pedagogical Research ### Educational Applications * **Interactive learning**: Real-time exploration of theory * **Comparative study**: Multiple frameworks simultaneously * **Visual-auditory integration**: See and hear relationships * **Systematic exploration**: Comprehensive coverage ### Learning Outcomes * Understand theoretical evolution * Compare historical approaches * Hear mathematical relationships * Explore beyond simplified models ## Academic Citation All data exports include: * **Complete bibliographic references**: Ready for academic citation * **Source and page numbers**: Precise attribution * **Historical context**: Temporal framework * **Scholarly verification**: Enables replication ## Next Steps * Explore [Bibliographic Sources](/guide/bibliographic-sources/) for citations * Learn about [Data Export](/guide/data-export/) capabilities * Understand [Cultural Framework](/guide/cultural-framework/) methodology --- --- url: /docs/guide/cultural-framework.md description: Decolonial computing principles and culture-specific methodology --- # Cultural Framework DiArMaqAr implements a culture-specific methodology that centres Arabic theoretical frameworks and epistemological systems. By grounding every operation in the tradition's own scholarship, terminology, and analytical categories, the platform approaches Arabic maqām as an autonomous scholarly and musical tradition with its own intellectual history. ## Decolonial Computing Principles ### Foundational Philosophy Computational approaches to musicology have historically reflected what Serra (2011) identified as a foundational epistemological problem: information technologies imposing the paradigms of market-driven western culture. In parallel, Irani et al.'s (2010) postcolonial computing framework articulated how digital technologies can either reinforce or challenge hierarchies of knowledge. Ali (2016) extended this analysis to encourage designing systems informed by cultural epistemologies to undermine global power asymmetries, rather than extending Anglo-European-centric frameworks to new domains — a perspective further developed by Abdilla et al. (2018) on decolonising digital technology as cultural practice. Together, these perspectives treat cultural assumptions as architectural decisions embedded in technical foundations, not merely as user-interface choices. ### DiArMaqAr's Approach DiArMaqAr implements this perspective by: 1. **Grounding all operations in the Persian-Arab-Ottoman note naming convention** * PAO note names (rāst, dūgāh, segāh, chahārgāh, nawā…) serve as the platform's foundational data abstraction and primary pitch identifier. * Structuring all pitch-class representations through PAO enables tuning-system-sensitive rendering of every maqām, jins, and taṣwīr across compiled tanāghīm, without privileging any single theoretical framework. 2. **Implementing Arabic theoretical categories at the system level** * The data model is organised around the conceptual hierarchy of Arabic maqām theory: tanāghīm, ajnās, maqāmāt, suyūr, and intiqālāt. * Computational operations — rendering, transposition, modulation — are built directly from this hierarchy. * The interface presents Arabic concepts in their original terminology and categories. 3. **Treating Arabic maqām theory as an autonomous musical epistemology** * Arabic maqām theory is presented on its own terms: an independent scholarly and musical tradition with its own note-name system, tuning frameworks, and analytical categories. * Longstanding debates around tuning and intonation are addressed by providing direct access to the documented diversity of historical frameworks across more than a millennium of scholarship. ## Historical Authenticity ### Source-Based Implementation * **Historical sources**: medieval treatises through modern scholarship * **Bibliographic attribution**: complete source references for every tuning system, jins, maqām, and sayr * **Scholarly verification**: enables academic citation and reproduction * **Transparent provenance**: clear data origin with source and page citations ### Avoiding Standardisation Bias Since the mid-20th century, Anglo-European standardisation pushed Arabic maqām theory toward a 24-tone system (not necessarily equally tempered), collapsing the diversity of historical systems from the 10th–14th centuries that utilised varying numbers of pitch classes — al-Fārābī's 27, 35 or 22 (Forster 2010:643), Ibn Sīnā's 17 (Farmer 1937:249), al-Urmawī's 17 (al-Urmawī, Khashaba 1986/2017), and al-Lādhiqī's 17 (Allāh Wīrdī 1949:163-164). Modern Arab theorists such as al-Ḥilū (1961:76) sought to simplify the system through Anglo-European logics, attributing its complexities to centuries of "neglect" rather than recognising them as inherent to the tradition. DiArMaqAr: * Preserves historical diversity across tuning systems * Avoids forcing external frameworks or a single theoretical model * Maintains multiple theoretical approaches side by side * Respects interpretative flexibility ## Computational Representation ### Culture-Specific Formalisation Following Serra (2017), DiArMaqAr approaches Arabic maqām as "a system of interconnected entities" that require "adequate digital traces" and "rigorous formalisation", grounded in culture-specific theoretical frameworks. The platform's architecture operationalises this framework through: * **A conceptual hierarchy drawn from the tradition itself**: tanāghīm, ajnās, maqāmāt, suyūr, and intiqālāt, with the Persian-Arab-Ottoman note naming convention functioning as the foundational data model. * **Five curated JSON corpora** — tuning systems, ajnās, maqāmāt, sources, and patterns — preserving academic provenance and supporting every platform operation. * **Faithful units of measurement**: each tanghīm's pitch class values are entered in the original unit used in its bibliographic source (fraction ratios, cents, string lengths, or fret divisions) and dynamically converted between representations while maintaining mathematical accuracy. * **A practice-based perspective** combining rigorous academic research and computational precision, re-reading primary texts alongside secondary compilations to render the musical information unified, meaningful, true to its sources, and immediately accessible. ### Integration of Perspectives As Srinivasamurthy et al. (2023) demonstrate for Indian art music, computational musicology requires: * Integration of ethnomusicological perspectives alongside signal processing * Making explicit what remains implicit in Anglo-European-centric approaches * Recognising that every computational method carries embedded musicological assumptions ## Research Implications DiArMaqAr addresses the core structural problem identified by Gedik and Bozkurt (2009) in the computational research of modal musics: * Divergence between theory and practice * Lack of reliable, computationally accessible theory * Need for valid pitch-class definitions grounded in culturally specific frameworks ## Multilingual Support * **Library of Congress Romanization**: international scholarly standards * **Arabic script**: native language support * **Reverse transliteration**: accurate conversion between Arabic script and romanised forms * **Cultural accessibility**: local and international communities (Arabic, English, French) ## Next Steps * Learn about [Theoretical Framework](/guide/theoretical-framework/) * Explore [Bibliographic Sources](/guide/bibliographic-sources/) * Understand [Research Applications](/guide/research-applications/) --- --- url: /docs/guide/bibliographic-sources.md description: Comprehensive source attribution and scholarly verification --- # Bibliographic Sources DiArMaqAr maintains rigorous bibliographic attribution across all data, enabling scholarly verification, academic citation, and further research. Every tuning system, jins, and maqām includes complete source references. ## Source Attribution System ### Integration Levels **Tuning Systems:** * Creator attribution (historical theorist or modern scholar) * Publication year * Source citation with page references * Commentary providing theoretical context **Ajnās:** * Bibliographic references * Source and page citations * Historical context * Cross-references to related sources **Maqāmāt:** * Complete bibliographic references * Source and page citations * Multilingual commentary (Arabic/English/French) * Suyūr from original sources ## Historical Sources Database The `sources.json` corpus maintains a comprehensive bibliographic database supporting all platform content with: * **Complete academic citations** in Arabic, English, and French * **Books and articles** with full publication details * **Contributor information** * **DOI links** where available * **Access dates** for digital sources ### Source Types **Historical Treatises (9th–16th centuries):** * Al-Kindī — 9th c. (e.g. twelve-tone ratios dated 847 CE via Farmer 1937:248) * Al-Fārābī — d. 950 (multiple tuning systems of 27, 35, or 22 pitch classes per Forster 2010:643) * Ibn Sīnā — d. ca. 1037 (17-tone system per Farmer 1937:249) * Al-Urmawī — 13th c. (17-tone system, *Kitāb al-Adwār* 1252, ed. Khashaba 1986/2017) * Al-Lādhiqī — late 15th – early 16th c. (17-tone system per Allāh Wīrdī 1949:163-164) **Modern Scholarship (19th–20th centuries):** * Meshshāqa (1899) * Al-Khulaʿī (1904/2011) * Ronzevalle (1904) — Modernist Arabic 24-tone tuning * Cairo Congress for Arabic Music (1932) * Al-Shawwā (1946) — including the modulation guidelines formalised in DiArMaqAr * Allāh Wīrdī (1949) * Al-Ṣabbāgh (1950, 1954) — 19-tone and 24-tone comma-based systems * Al-Ḥilū (1961) * Abbās (1986) — extended maqām transpositions **Secondary Compilations and Contemporary Sources:** * d'Erlanger (6 vols., 1930–1959) * Farmer (1937) * Shawqī (1969) * Maalouf (2002) * Al-Rejab (2002) * Forster (2010) * Beyhom (2010) * Farraj & Shumays (2019) ## Note Name Compilation The Persian-Arab-Ottoman note naming convention compiled in DiArMaqAr totals **36 note names per octave** across **four octaves** (Octave 0 through Octave 3). In most bibliographic sources the range spans two octaves (Octaves 1–2, from yegāh to saham/ramal tūtī/jawāb al-nawā); DiArMaqAr extends this downward with qarār / qarār qarār prefixes (Octave 0) and upward with jawāb / jawāb jawāb prefixes (Octave 3) in accordance with maqām theory convention. The compiled note names are drawn from: * Meshshāqa (1899:18) * Al-Khulaʿī (1904/2011:50–54, 77–78) * Al-Shawwā (1946:11–12) * Allāh Wīrdī (1949:58, 153, 157, 177, 198, 203, 207) * Al-Ṣabbāgh (1954:47) * Al-Ḥilū (1961:69) * Al-Rejab (2002:79-80) **Extended ranges** (qarār/qarār qarār prefixes for the lower register, jawāb/jawāb jawāb prefixes for the upper register) follow conventions documented in: * Allāh Wīrdī (1949:203) * Al-Ḥilū (1961:70) * Arel (1968:1) — extended four-octave Turkish makam equivalents ### Names Added in DiArMaqAr Four note names are used in DiArMaqAr that are not in the compiled sources. Each was added because a tanghīm in the archive contains a pitch class that the compiled names could not name without giving two different pitch classes the same name. All four follow the PAO convention that tīk raises a note and nīm lowers it. * **tīk rāst** names pitch classes above rāst and below nīm zīrgūleh for the sake of al-Fārābī's tanāghīm (see al-Fārābī 950g, 950h) and the ʿushayrān-based version of al-Ṣabbāgh's tanghīm, where his own kurdī falls there (see al-Ṣabbāgh 1950). * **tīk yegāh**, **tīk ʿushayrān**, **tīk dūgāh**: pitch classes above yegāh, ʿushayrān and dūgāh and below the next name in the list, for the sake of tanāghīm whose octaves are not exact (see Ibn Sīnā 1037). With these, the app uses 40 note names per octave. A name is added only when a tanghīm in the archive uses it. The full list, with the source of every name, is on the [PAO Note Names](/guide/note-names) page. ## Source Selection Methodology ### Where Note Names Exist in Sources Where Persian-Arab-Ottoman note name associations to pitch classes exist in bibliographic sources, they are **explicitly used**. ### Where Note Names Must Be Inferred Where direct associations are not documented, note names are **inferred** based on: * Compiled note names list * Relationship to al-Kindī's 9th-century 12-tone chromatic tuning system * Al-Fārābī's comprehensive 10th-century tunings * 20th-century sources (al-Ṣabbāgh 1954, Allāh Wīrdī 1949) ## Commentary and Context Each tuning system includes editorial commentary providing: * **Theoretical context**: How the system fits in historical development * **Bibliographic analysis**: Discussion of source and its significance * **Mathematical explanation**: How the system was calculated/rendered * **Practical implications**: How the system affects maqāmic practice ### Example Commentary From "Contemporary Arabic 19-Tone" system by Al-Ṣabbāgh (1950:173): "This tuning system by Tawfīq Al-Ṣabbāgh is built on a theoretical 53-comma per octave division, resulting in 19-tones that are used in the maqāmāt he recounts in his book. Ṣabbāgh gives the comma a value of 1/81th of a string length of 10,000 = 123.4567901235 (1950:38), erroneously defined by Shawqī as 0,012346 (1969:147). This is a syntonic comma, also known as Didymus' comma, the meantone comma or the Ptolemaic comma, with a frequency ratio of 81/80..." ## Accessing Source Information ### Via REST API ```bash # Get sources database curl https://diarmaqar.net/api/sources # Maqām responses include source references curl "https://diarmaqar.net/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents" # Response includes: # - source references # - page numbers # - bibliographic citations ``` ## Academic Citation All data is ready for academic citation with: * **Complete bibliographic references**: Full citations in Arabic, English, and French * **Page numbers**: Specific locations in sources * **Transparent methodology**: How data was derived * **Version tracking**: Platform version and data version ### Citation Formats Used in DiArMaqAr DiArMaqAr cites its sources in the author-date form with a colon between the year and the page, the form common in ethnomusicology. **Sources list.** Each tanghīm, jins and maqām lists its sources by author, year and pages, for example Farmer (1937:251–256). Where a book has an original and a later edition, both years are given, original first, for example al-Khulaʿī (1904/2011). **In-text citations in commentary.** Commentary cites the page of every claim and every quotation: * one page: (Farmer 1937:254) * a range of pages, with an en dash: (al-Ḥilū 1961:120–121) * separate pages, with commas: (ʿAbbās 1986:62, 70) * when the author is already named in the sentence, only the year and page: al-Shawwā (1946:80) * a remark about the citation follows a semicolon: (1961:123; the square brackets are printed in the original) Arabic commentary uses the same form with Arabic punctuation: (فارمر 1937: 254), (1986: 62، 70). Numerals are western digits in both languages. **Quotations.** Text inside quotation marks, "…" in English and «…» in Arabic, is the source's own words, quoted exactly and followed by its citation. Where a quotation contains square brackets, the commentary says whose they are, for example the translator's. In the app, quoted text is shown in a different colour from the commentary around it, and a paragraph that opens with "NOTE:" is shown as a separate note. **Romanization.** Arabic names and terms follow the Library of Congress romanization. ## Historical Context ### Compilation Methodology Many of DiArMaqAr's tuning systems are reconstructed by re-reading primary Arabic, English, and French texts alongside secondary compilations (d'Erlanger 1930–1959, Farmer 1937, Allāh Wīrdī 1949, Shawqī 1969, Maalouf 2002, Forster 2010, Beyhom 2010). Where these works render musical information reductively, use interchangeable units of measurement, or rely on Anglo-European / International Pitch Notation and staff notation, DiArMaqAr re-interprets the material and renders it through: * Critical editions collating multiple manuscripts * Scholarly publications with textual variants * Documented commentary and annotations ### Theoretical Evolution Sources span from the 9th century to the present: * **9th–13th centuries**: Medieval polymath theorists (al-Kindī, al-Fārābī, Ibn Sīnā, al-Urmawī) * **14th–16th centuries**: al-Shīrāzī and al-Irbilī (first attested uses of Persian-Arab-Ottoman note names), al-Lādhiqī * **19th–20th centuries**: Modern systematisation (Meshshāqa, al-Khulaʿī, Ronzevalle, al-Shawwā, Allāh Wīrdī, al-Ṣabbāgh, al-Ḥilū); Cairo Congress (1932) * **Late 20th century – contemporary**: Abbās (1986), al-Rejab (2002), Beyhom (2010), Farraj & Shumays (2019) DiArMaqAr enables immediate access to over a thousand years of musical and mathematical scholarship. ## Verification and Validation ### Scholarly Verification The transparent source attribution enables: * **Verification**: Checking original sources * **Validation**: Confirming theoretical accuracy * **Replication**: Reproducing results * **Extension**: Building upon existing work ### Critical Edition Approach Following principles of critical editions: * **Multiple sources**: Collated from various manuscripts * **Reliable text**: Established through scholarly comparison * **Documented variants**: Textual differences noted * **Commentary**: Scholarly analysis included ## Research Applications ### Academic Research * **Citation**: Ready-to-use bibliographic references * **Verification**: Transparent data origin * **Extension**: Building upon documented theory * **Comparative study**: Multiple source comparison ### Musicological Analysis * **Historical development**: Tracing theoretical evolution * **Source comparison**: Analyzing different approaches * **Validation**: Confirming theoretical claims * **Contextualization**: Understanding historical setting ## Next Steps * Explore [Research Applications](/guide/research-applications/) * Learn about [Cultural Framework](/guide/cultural-framework/) * Understand [Theoretical Framework](/guide/theoretical-framework/) --- --- url: /docs/guide/note-names.md description: >- The full list of Persian-Arab-Ottoman note names used in DiArMaqAr, with their sources --- # PAO Note Names DiArMaqAr names every pitch class with the Persian-Arab-Ottoman (PAO) note names. The list below is the full set the app uses, one row per note, with its name in each of the four registers (Octave 0 to Octave 3), its IPN equivalent, and where the name comes from. ## Where the names come from The names of Octave 1 and Octave 2 are compiled from Meshshāqa (1899:18), al-Khulaʿī (1904/2011:50–54, 77–78), al-Shawwā (1946:11–12), Allāh Wīrdī (1949:58, 153, 157, 177, 198, 203, 207), al-Ṣabbāgh (1954:47), al-Ḥilū (1961:69) and al-Rejab (2002:79–80). This compilation gives 36 note names per octave. Most sources cover two octaves, from yegāh to saham/ramal tūtī. The lower register (Octave 0) uses the prefixes qarār and qarār qarār, and the upper register (Octave 3) uses jawāb and jawāb jawāb, following the convention found in Allāh Wīrdī (1949:203), al-Ḥilū (1961:70) and the four-octave list of Turkish makam equivalents in Arel (1968:1). ## Names added in DiArMaqAr Four rows are not in the compiled sources. They were added because tanāghīm in the archive contain pitch classes that the compiled names cannot name without giving two different pitch classes the same name. Each follows the PAO convention that tīk raises a note and nīm lowers it. * **tīk rāst** names pitch classes above rāst and below nīm zīrgūleh for the sake of al-Fārābī's tanāghīm (see al-Fārābī 950g, 950h) and the ʿushayrān-based version of al-Ṣabbāgh's tanghīm, where his own kurdī falls there (see al-Ṣabbāgh 1950). * **tīk yegāh**, **tīk ʿushayrān** and **tīk dūgāh** name pitch classes just above yegāh, ʿushayrān and dūgāh (each below the next name in the list). They are needed in tanāghīm whose octaves are not exact, such as Ibn Sīnā (1037), where the strings added below the bamm sound these pitch classes in Octave 0 (see [Tanāghīm whose octaves are not exact](/guide/tuning-systems#tanaghim-whose-octaves-are-not-exact)). With these additions the app uses 40 note names per octave. A name is added to this list only when a tanghīm in the archive uses it. ## The full list Notes in the last column refer to the register named at their start. IPN names mark the PAO tīk variants with + and the nīm variants with -, after the letter and accidental they vary (for example C+ for tīk rāst, C#- for nīm zīrgūleh). | No | IPN | Octave 0 | Octave 1 | Octave 2 | Octave 3 | Sources and notes | |---|---|---|---|---|---|---| | 1 | G | qarār yegāh | yegāh | nawā | saham/ramal tūtī | Octave 3: Meshshāqa names this ramal tūtī (1899:18) as does al-Khulaʿī (1904/2011:31–35, 56, 62, 88) but al-Khulaʿī also calls it jawāb nawā (1904/2011:50) as does al-Ḥilū (1961:69). Al-Rejab (2002:70) gives all three variations. | | 2 | G+ | qarār tīk yegāh | tīk yegāh | tīk nawā | tīk saham/ramal tūtī | **Added in DiArMaqAr, for pitch classes above yegāh and below qarār nīm ḥiṣār for the sake of tanāghīm whose octaves are not exact (see Ibn Sīnā 1037).** | | 3 | Ab-- | qarār qarār nīm ḥiṣār | qarār nīm ḥiṣār | nīm ḥiṣār | jawāb nīm ḥiṣār | Octave 3: Used by al-Ḥilū (1961:70) | | 4 | Ab- | qarār shūrī | shūrī | jawāb shūrī | jawāb jawāb shūrī | Octave 1: Extended note given by al-Shawwā as one comma below qarār ḥiṣār (1946:13) | | 5 | Ab | qarār qarār ḥiṣār | qarār ḥiṣār | ḥiṣār | jawāb ḥiṣār | Octave 2: Al-Ḥilū names this ḥiṣār/shūrī (1961:69)Octave 3: Used by al-Ḥilū (1961:70) | | 6 | A-b | qarār qarār tīk ḥiṣār/shūrī | qarār tīk ḥiṣār/shūrī | tīk ḥiṣār | jawāb tīk ḥiṣār | Octave 0: Al-Khulaʿī names this tīk qabā ḥiṣār/shūrī based on information from Idrīs Rāgheb (1904/2011:51)Octave 3: Used by al-Ḥilū (1961:70) | | 7 | A- | qarār nīm ʿushayrān | nīm ʿushayrān | nīm ḥusaynī | jawāb nīm ḥusaynī | Octave 1: Not present in al-Ḥilū (1961:69)Octave 2: Yaḥyā al-Laythī Kāmil names this ḥusaynī ṭabīʿī (the natural ḥusaynī), 5/3, below his ḥusaynī (27/16) by the ratio 81/80 (Shawqī 1969:190) | | 8 | A | qarār ʿushayrān | ʿushayrān | ḥusaynī | jawāb ḥusaynī | Octave 3: Used by al-Ḥilū (1961:70) | | 9 | A+ | qarār tīk ʿushayrān | tīk ʿushayrān | tīk ḥusaynī | jawāb tīk ḥusaynī | **Added in DiArMaqAr, for pitch classes above ʿushayrān and below nīm ʿajam ʿushayrān for the sake of tanāghīm whose octaves are not exact (see Ibn Sīnā 1037).** | | 10 | A-# | qarār nīm ʿajam ʿushayrān | nīm ʿajam ʿushayrān | nīm ʿajam | jawāb nīm ʿajam | Octave 1: Al-Ḥilū names this qarār nīm ʿajam (1961:69)Octave 3: Used by al-Ḥilū (1961:70) | | 11 | Bb- | qarār nayrūz | nayrūz | jawāb nayrūz | jawāb jawāb nayrūz | Octave 1: Extended note given by al-Shawwā as one comma below ajam ushayrān (1946:13). This name is also used by al-Ḥilū as ʿajam/nayriz (nīriz) (1961:69) | | 12 | Bb | qarār ʿajam ʿushayrān | ʿajam ʿushayrān | ʿajam | jawāb ʿajam | Octave 1: Al-Ḥilū names this qarār ʿajam (1961:69)Octave 2: Al-Ḥilū names this ʿajam/nayriz (nīriz) (1961:69)Octave 3: Used by al-Ḥilū (1961:70) | | 13 | Bb+ | qarār tīk ʿajam ʿushayrān | tīk ʿajam ʿushayrān | tīk ʿajam | jawāb tīk ʿajam | — | | 14 | B-b | qarār ʿirāq | ʿirāq | awj | jawāb awj | Octave 3: Used by al-Ḥilū (1961:70) | | 15 | B-- | qarār rahāwī | rahāwī | jawāb rahāwī | jawāb jawāb rahāwī | Octave 1: Extended note given by al-Shawwā as one comma higher than ʿirāq (1946:13) | | 16 | B- | qarār nīm kawasht/rahāwī | nīm kawasht | nīm māhūr | jawāb nīm māhūr | Octave 0: Al-Khulaʿī names this nīm kawasht or rahāwī based on information from Idrīs Rāgheb (1904/2011:51) | | 17 | B | qarār kawasht | kawasht | māhūr | jawāb māhūr | Octave 2: Al-Ḥilū names this nuhuft (1961:69)Octave 3: Al-Ḥilū names this jawāb nuhuft (1961:70) | | 18 | C-b | qarār tīk kawasht | tīk kawasht | tīk māhūr | jawāb tīk māhūr | Octave 2: Al-Ḥilū names this tīk nuhuft (1961:69)Octave 3: Al-Ḥilū names this jawāb tīk nuhuft (1961:70) | | 19 | C | qarār rāst | rāst | kurdān | jawāb kurdān | Octave 2: Al-Ḥilū names this kurdān/mahūr (1961:69) | | 20 | C+ | qarār tīk rāst | tīk rāst | tīk kurdān | jawāb tīk kurdān | **Added in DiArMaqAr, for pitch classes above rāst and below nīm zīrgūleh for the sake of al-Fārābī's tanāghīm (see al-Fārābī 950g, 950h) and the ʿushayrān-based version of al-Ṣabbāgh's tanghīm, where his own kurdī falls there (see al-Ṣabbāgh 1950).** | | 21 | C#- | qarār nīm zīrgūleh | nīm zīrgūleh | nīm shahnāz | jawāb nīm shahnāz | — | | 22 | C# | qarār zīrgūleh | zīrgūleh | shahnāz | jawāb shahnāz | — | | 23 | D-b | qarār tīk zīrgūleh | tīk zīrgūleh | jawāb tīk zīrgūleh | jawāb jawāb tīk zīrgūleh | Octave 2: Al-Ḥilū names this tīk shahnāz (1961:69) | | 24 | D | qarār dūgāh | dūgāh | muḥayyar | jawāb muḥayyar | — | | 25 | D+ | qarār tīk dūgāh | tīk dūgāh | tīk muḥayyar | jawāb tīk muḥayyar | **Added in DiArMaqAr, for pitch classes above dūgāh and below nīm kurdī/nahāwand for the sake of tanāghīm whose octaves are not exact (see Ibn Sīnā 1037).** | | 26 | D-# | qarār nīm kurdī/nahāwand | nīm kurdī/nahāwand | nīm sunbuleh | jawāb nīm sunbuleh | Octave 0: Al-Khulaʿī names this nīm kurdī/nahāwand based on information from Idrīs Rāgheb (1904/2011:51)Octave 2: Al-Ḥilū names this nīm zawwāl (1961:69) | | 27 | Eb- | qarār nahāwand | nahāwand | jawāb nahāwand | jawāb jawāb nahāwand | Octave 1: Extended note given by al-Shawwā as one comma less than kurdī (1946:13) | | 28 | Eb | qarār kurdī | kurdī | sunbuleh/zawāl | jawāb sunbuleh/zawāl | Octave 1: Often also referred to as kurd instead of kurdī, see for example al-Ḥilū (1961:69) | | 29 | Eb+ | qarār tīk kūrdī | tīk kūrdī | jawāb tīk kūrdī | jawāb jawāb tīk kūrdī | — | | 30 | E-b | qarār segāh | segāh | buzurk | jawāb buzurk | — | | 31 | E- | qarār nīm būselīk | nīm būselīk | jawāb nīm būselīk | jawāb jawāb nīm būselīk | — | | 32 | E | qarār būselīk/ʿushshāq | būselīk/ʿushshāq | jawāb būselīk | jawāb jawāb būselīk | Octave 1: Al-Khulaʿī names this buselīk/’ushshāq based on information from Idrīs Rāgheb (1904/2011:51)Octave 2: Al-Ḥilū names this ḥusaynī shad (1961:69) | | 33 | F-b | qarār tīk būselīk | tīk būselīk | jawāb tīk būselīk | jawāb jawāb tīk būselīk | Octave 1: Al-Ḥilū names this tīk ḥusaynī shad (1961:69) | | 34 | F | qarār chahārgāh | chahārgāh | māhūrān | jawāb māhūrān | — | | 35 | F+ | qarār tīk chahārgāh | tīk chahārgāh | tīk māhūrān | jawāb tīk māhūrān | — | | 36 | F-# | qarār nīm ḥijāz | nīm ḥijāz | jawāb nīm ḥijāz | jawāb jawāb nīm ḥijāz | Octave 1: Al-Ḥilū names this ʿurbā’ (1961:69) | | 37 | F#- | qarār ṣabā | ṣabā | jawāb ṣabā | jawāb jawāb ṣabā | Octave 1: Extended note given by al-Shawwā as one comma lower than ḥijāz (1946:13) | | 38 | F# | qarār ḥijāz | ḥijāz | jawāb ḥijāz | jawāb jawāb ḥijāz | Octave 1: Al-Ḥilū names this ḥijāz/ṣabā (1961:69) | | 39 | G-b | qarār tīk ḥijāz/ṣabā | tīk ḥijāz/ṣabā | jawāb tīk ḥijāz | jawāb jawāb tīk ḥijāz | Octave 1: Al-Khulaʿī names this tīk ḥijāz/ṣabā based on information from Idrīs Rāgheb (1904/2011:51) | | 40 | G- | nīm yegāh | nīm nawā | nīm saham/ramal tūtī | jawāb saham/ramal tūtī | — | --- --- url: /docs/api.md description: Programmatic access to Arabic maqāmāt, ajnās, and tuning systems data --- # API Documentation Digital Arabic Maqām Archive (DiArMaqAr) — programmatic access to historically documented maqāmāt, ajnās, and tuning systems spanning from al-Kindī (874 CE) to contemporary approaches. ## Quick Start **Try this first:** ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents" ``` **Base URL:** `https://diarmaqar.net/api` ## Documentation Resources ### For Humans * **[Endpoints Reference](./endpoints-reference)** - Complete endpoint documentation with parameters and responses * **[Interactive Playground](./playground)** - Test API calls live in your browser * **[Representative Examples](./representative-examples)** - Recommended examples for proper API usage ### For LLMs * **OpenAPI Specification:** [openapi.json](/openapi.json) | [openapi.yaml](/openapi.yaml) * **LLM-optimized:** [llms.txt](/llms.txt) | [llms-full.txt](/llms-full.txt) *** ## API Endpoints All API endpoints are organized by resource type. Each endpoint includes a link to detailed documentation with parameters, examples, and response formats. **Total: 27 endpoints** across 7 resource categories. ### Maqāmāt Documented modal frameworks with historical source attribution. **Endpoints (8):** * `GET /maqamat` - List all maqāmāt → [Details](./endpoints-reference#listMaqamat) * `GET /maqamat/families` - List maqām families → [Details](./endpoints-reference#listMaqamFamilies) * `GET /maqamat/{idName}` - Get detailed maqām data → [Details](./endpoints-reference#getMaqam) · [Every maqām form in one request](#every-maqam-form-in-one-request) * `GET /maqamat/{idName}/availability` - Check maqām availability across tuning systems → [Details](./endpoints-reference#getMaqamAvailability) * `GET /maqamat/{idName}/transpositions` - List transpositions for a maqām → [Details](./endpoints-reference#listMaqamTranspositions) * `GET /maqamat/{idName}/compare` - Compare maqām data across multiple tuning systems → [Details](./endpoints-reference#compareMaqam) * `GET /maqamat/classification/12-pitch-class-sets` - Classify maqāmāt by 12-pitch-class sets → [Details](./endpoints-reference#classifyMaqamat12PitchClassSets) · [Transpositions that do not fit](#transpositions-that-do-not-fit-a-12-pitch-class-set) * `GET /maqamat/classification/maqam-pitch-class-sets` - Classify maqāmāt by maqam-based pitch class sets → [Details](./endpoints-reference#classifyMaqamatByMaqamPitchClassSets) ### Ajnās Documented tri/tetra/penta-chords with historical source attribution. **Endpoints (5):** * `GET /ajnas` - List all ajnās → [Details](./endpoints-reference#listAjnas) * `GET /ajnas/{idName}` - Get detailed jins data → [Details](./endpoints-reference#getJins) * `GET /ajnas/{idName}/availability` - Check jins availability across tuning systems → [Details](./endpoints-reference#getJinsAvailability) * `GET /ajnas/{idName}/transpositions` - List transpositions for a jins → [Details](./endpoints-reference#listJinsTranspositions) * `GET /ajnas/{idName}/compare` - Compare jins data across multiple tuning systems → [Details](./endpoints-reference#compareJins) ### Tuning Systems Historical tuning systems spanning from al-Kindī (874 CE) to contemporary approaches. **Endpoints (4):** * `GET /tuning-systems` - List all tuning systems → [Details](./endpoints-reference#listTuningSystems) * `GET /tuning-systems/{id}/{startingNote}/pitch-classes` - Get tuning system details (pitch classes) → [Details](./endpoints-reference#getTuningSystemPitchClasses) * `GET /tuning-systems/{id}/{startingNote}/maqamat` - List maqāmāt available in a tuning system → [Details](./endpoints-reference#listTuningSystemMaqamat) * `GET /tuning-systems/{id}/{startingNote}/ajnas` - List ajnās available in a tuning system → [Details](./endpoints-reference#listTuningSystemAjnas) ### Pitch Classes Note names and pitch class data across all tuning systems. **Endpoints (4):** * `GET /pitch-classes/note-names` - List all note names → [Details](./endpoints-reference#listNoteNames) * `GET /pitch-classes/note-names/{noteName}` - Get pitch class details by note name → [Details](./endpoints-reference#getPitchClassByNoteName) * `GET /pitch-classes/note-names/{noteName}/availability` - Check note name availability across tuning systems → [Details](./endpoints-reference#getNoteNameAvailability) * `GET /pitch-classes/note-names/{noteName}/compare` - Compare pitch class by note name across tuning systems → [Details](./endpoints-reference#comparePitchClassByNoteName) ### Intervals Calculate intervals between note names. **Endpoints (2):** * `GET /intervals` - Calculate intervals by note names → [Details](./endpoints-reference#calculateIntervalsByNoteNames) * `GET /intervals/compare` - Compare intervals across tuning systems → [Details](./endpoints-reference#compareIntervalsByNoteNames) ### Sources Bibliographic sources documenting the historical foundation of the archive's musical data. **Endpoints (5):** * `GET /sources` - List all bibliographic sources → [Details](./endpoints-reference#listSources) * `GET /sources/{id}` - Get a single bibliographic source → [Details](./endpoints-reference#getSource) * `GET /sources/{id}/tuning-systems` - List tuning systems by source → [Details](./endpoints-reference#listTuningSystemsBySource) * `GET /sources/{id}/maqamat` - List maqamat by source → [Details](./endpoints-reference#listMaqamatBySource) * `GET /sources/{id}/ajnas` - List ajnas by source → [Details](./endpoints-reference#listAjnasBySource) ### Modulations Modulation routes between maqāmāt using al-Shawwā's 1946 modulation guidelines. **Endpoints (1):** * `GET /modulation-routes` - Find modulation routes between maqāmāt → [Details](./endpoints-reference#findModulationRoutes) ### Statistics What the archive holds, and for every tuning system on every starting note: the ajnās and maqāmāt it can build, their transpositions (taṣwīr) and octave renderings, and the modulations from base forms, transpositions and octave renderings. **Endpoints (1):** * `GET /statistics` - Get archive statistics → [Details](./endpoints-reference#getStatistics) *** ## Identifiers of transpositions {#identifiers-of-transpositions} A transposed maqām or jins has one `idName`, and every endpoint returns the same one. It is the base `idName`, then `_al_`, then the tonic's note-name `idName`: | Display name | `idName` | |---|---| | maqām rāst al-qarār chahārgāh | `maqam_rast_al_qarar_chahargah` | | jins segāh al-tīk ḥiṣār | `jins_segah_al_tik_hisar` | | maqām ḥijāz (al-Ṣabbāgh/ʿAbbās) al-saham/ramal tūtī | `maqam_hijaz_alsabbagh_abbas_al_saham_ramal_tuti` | The separator is always `_al_`. The "al" inside a base name is closed up, so it never looks like a separator: `maqam_hijaz_alsabbagh_abbas` and `jins_buselik_alhilu` are base names, not transpositions. The base form is its bare `idName` (`maqam_rast`). A rendering an octave away from the base form, such as maqām rāst on qarār rāst, is not a taṣwīr (`isTransposed: false`, `isBaseForm: false`), but it still names its tonic: `maqam_rast_al_qarar_rast`. So the `idName` in a maqām's `availableTranspositions` list is exactly the `maqam.idName` you get back when you request that transposition. The same `idName` appears in: * each entry of `GET /maqamat/{idName}/transpositions` and `GET /ajnas/{idName}/transpositions`; * each entry of the `transpositions` array that `includeTranspositions=true` adds to `GET /tuning-systems/{id}/{startingNote}/maqamat` and `.../ajnas`; * the 12-pitch-class-set and maqām-pitch-class-set classifications; * ajnās named inside maqām responses; * modulation routes. A classification set is named after one of its members, so its `setIdName` is that member's `idName` plus `_set`. A set that holds a base form is named after one (`maqam_hijaz_kar_kurd_set`); a set that holds none is named after a transposition (`maqam_rast_al_kawasht_set`). The rule is given in the [12-pitch-class sets endpoint](./endpoints-reference#classifyMaqamat12PitchClassSets) description. ### Using a transposed `idName` in the path A transposed `idName` can go straight into the path. It means the same as the base `idName` with the tonic given separately: | Path | Same as | |---|---| | `/maqamat/maqam_rast_al_qarar_chahargah` | `/maqamat/maqam_rast?transposeTo=qarar_chahargah` | | `/maqamat/maqam_rast_al_nawa/compare` | `/maqamat/maqam_rast/compare?transposeTo=nawa` | | `/maqamat/maqam_rast_al_nawa/availability` | `/maqamat/maqam_rast/availability?transpositionNoteName=nawa` | | `/ajnas/jins_segah_al_tik_hisar` | `/ajnas/jins_segah?transposeTo=tik_hisar` | You still pass the usual tuning-system and starting-note parameters. Whether a tonic is reachable depends on the tuning system and starting note, so a transposed `idName` that cannot be built there gets the same 400 as the matching `transposeTo` would. Name the tonic once. A transposed `idName` together with a `transposeTo` (or `transpositionNoteName`) for a different tonic is a 400. Giving the same tonic both ways is fine. `/maqamat/{idName}/transpositions` and `/ajnas/{idName}/transpositions` list every transposition, so they take the base `idName` only. A transposed `idName` there is a 400 whose `hint` names the base `idName` to use. **Older spelling.** Until October 2026, some endpoints closed up the separator, spelling maqām rāst on qarār chahārgāh as `maqam_rast_alqarar_chahargah`. These were the base response's `availableTranspositions`, the compare endpoints, both classification endpoints (including set IDs), and modulation routes. Separately, a request with `transposeTo` set to a note an octave away from the base form (`transposeTo=qarar_rast` for maqām rāst) used to return the bare base `idName` and display name; it now returns `maqam_rast_al_qarar_rast`, matching the rest of the API. If you stored one of the closed-up IDs, it is still accepted wherever an `idName` is: in the path of every `/maqamat/{idName}` and `/ajnas/{idName}` route, and in the `maqamId` and `setId` filters on the classification endpoints. It is read as the current spelling. Responses use only the current spelling. **Ajnās an octave from their own tonic.** Until November 2026, a jins found at a maqām degree an octave from its own tonic kept its bare base `idName`: jins yegāh on nawā came back as `jins_yegah` with `isBaseForm: false`. It now names its tonic like every other form, `jins_yegah_al_nawa`, the same `idName` the jins endpoints give it. **Lower-octave modulation targets.** Until November 2026, a target in `lowerOctaveModulations` could carry a name no other endpoint used. Maqām yegāh on nawā, moved down an octave, came back as `maqam_yegah_al_yegah`, although it is maqām yegāh itself. Every lower-octave target is now the same form, with the same `idName`, that the listings and `GET /maqamat/all` give. *** ## Every maqām form in one request {#every-maqam-form-in-one-request} `GET /maqamat/all` describes every maqām a tuning system can build from a starting note, so a client does not need one `GET /maqamat/{idName}` call per form. Each item in `maqamat` is exactly the body `GET /maqamat/{idName}` returns for that form with the same options, minus the envelope (`parameters`, `context`, `links`). The response carries the envelope once. Code that reads one maqām response can read each item unchanged. | Parameter | Values | What it does | |---|---|---| | `forms` | `base` (default), `transpositions`, `all` | The base form of each maqām, its transpositions (taṣwīr), or both | | `includeOctaveRenderings` | `true` / `false` | Also returns each maqām an octave from its base form, such as `maqam_rast_al_qarar_rast`. These are neither the base form nor a taṣwīr, and they appear as modulation targets | | `fields` | e.g. `ajnas,primaryJins,modulations` | Keeps only these top-level fields in each item. `maqam` is always kept. A field left out is not computed, so leaving out `modulations`, `lowerOctaveModulations` and `stats` skips the modulation analysis | | `offset` | integer | Where a page starts. Leave it out and follow `next` | `includeModulations`, `includeModulations8vb`, `includeIntervals`, `includeSuyur`, `includeArabic`, `pitchClassDataType` and `centsTolerance` work as they do for one maqām. **Pages.** A full analysis is larger than one response can be. For al-Fārābī (950g) from ʿushayrān, all 440 forms (101 base forms and 339 taṣwīr) with both kinds of modulation are about 25 MB. So the response is cut into pages of at most about 5 MB. `total` counts every selected form, `count` counts the forms on this page, and `next` is the URL of the next page, or `null` on the last one. Requests without modulations usually fit on one page. ```bash # First page; then request each `next` URL until it is null curl "https://diarmaqar.net/api/maqamat/all?tuningSystem=alfarabi_950g&startingNote=ushayran&forms=all&includeModulations=true&includeModulations8vb=true&pitchClassDataType=cents&fields=pitchData,ajnas,primaryJins,secondaryJins,tertiaryJins,ghammaz,modulations,lowerOctaveModulations" ``` Every page is cached at the edge and carries an `ETag`, so a client can check for changes with `If-None-Match` and get a 304 when nothing changed. *** ## Kinds of maqām and jins form {#kinds-of-form} Every maqām and jins form in a response carries `formType`, read from the form itself: | `formType` | Meaning | Example | |---|---|---| | `base` | The base form: the form on the tonic the sources give | maqām rāst on rāst, `maqam_rast` | | `transposition` | A taṣwīr: the form moved to another modal degree | maqām rāst on nawā, `maqam_rast_al_nawa` | | `octaveRendering` | The base form an octave or more away, on the same modal degree | maqām rāst on qarār rāst, `maqam_rast_al_qarar_rast` | A form's `idName` is its identifier. It is unique within a tuning system and starting note, and the same form has the same `idName` in every response. `formType` is on the `maqam` of a maqām response, on the `jins` of a jins response, on every entry of `ajnas`, on modulation targets, in the listings, and as `jinsFormType` on the structural jins entries. **Listing every form.** `GET /tuning-systems/{id}/{startingNote}/maqamat` and `/ajnas` take `includeOctaveRenderings=true`. Each entry then has an `octaveRenderings` array next to `transpositions`, with the same shape. The base forms, `transpositions` and `octaveRenderings` together are every form a maqām response can refer to. In al-Fārābī (950g) from ʿushayrān, the octave renderings add 206 maqām forms and 108 jins forms, such as maqām yegāh on nawā (`maqam_yegah_al_nawa`) and jins yegāh on nawā (`jins_yegah_al_nawa`). In a maqām response, `availableOctaveRenderings` lists them next to `availableTranspositions`. `GET /maqamat/all` with `includeOctaveRenderings=true` returns the full detail of each. ## Structural ajnās and the ghammāz {#structural-ajnas-and-the-ghammaz} The sources give each structural jins as a degree: maqām rāst has its primary jins on rāst and its secondary jins on nawā. `primaryJins`, `secondaryJins` and `tertiaryJins` name that degree and the first jins the archive finds starting on it in the ascending form. `primaryJinsDescending`, `secondaryJinsDescending` and `tertiaryJinsDescending` read the same degree in the descending form. The sources give one degree per slot, not a separate descending one, so the descending jins is the archive's match, not a source statement. Each entry has a `jinsStatus`: | `jinsStatus` | Meaning | |---|---| | `matched` | A jins in the archive starts on this degree | | `noMatchingJins` | The degree is in the maqām, but no jins in the archive starts there in this tuning system. Maqām lāmī, degree IV (nawā), is one. The jins fields are `null` | | `degreeNotInMaqam` | The stored degree is not one of the notes of this direction. `maqamDegree` and the jins fields are `null` | Each direction is read on its own. Until November 2026, an ascending entry with no jins took the jins of the descending form instead. Each `ghammaz` entry has `intervalFromTonic`: the interval from the tonic up to the ghammāz, as `cents`, `fraction` and `decimalRatio`. For maqām rāst the ghammāz is nawā, at 3/2 (702 cents). `fraction` is exact in tuning systems defined by ratios and an approximation in the others. ## Citing sources {#citing-sources} `GET /sources` and `GET /sources/{id}` give each source a `citation`: the authors' family names and the year, such as `al-Shawwā 1946`. A book with both an original and an edition year gives both: `al-Khulaʿī 1904/2011`. Two authors are joined with "and", three or more become "et al.". With `includeArabic=true`, `citationAr` gives the same in Arabic, with western digits: `الشوا 1946`. `displayName` is unchanged: it is an identifier, not a citation. *** ## Transpositions that do not fit a 12-pitch-class set {#transpositions-that-do-not-fit-a-12-pitch-class-set} `GET /maqamat/classification/12-pitch-class-sets` groups maqām transpositions into 12-pitch-class sets. A few transpositions cannot form one. For what that means, see [Maqāmāt that cannot form a 12-pitch-class set](/guide/data-export#maqamat-that-cannot-form-a-12-pitch-class-set). The endpoint never skips these transpositions silently. It reports each one, with the key and the pitch classes that need it. ### Counts and lists * Every response includes `statistics.incompatibleMaqamatCount`, the number of transpositions in this tuning system, from this starting note, that do not fit. * `includeIncompatible=true` adds the full list in `incompatibleMaqamat`, with its count in `incompatibleMaqamatCount`. ### Each transposition that does not fit | Field | Description | |-------|-------------| | `compatible` | Always `false` | | `reason` | Always `"shared_key"`: two or more pitch classes need the same key, and the keys next to it are taken. This replaces the former `"duplicate_ipn_reference"`. | | `explanation` | One plain sentence, e.g. `"ʿirāq (B-b2) and nīm kawasht (B-2) both need the B key, and the keys next to it are taken."` | | `clashes` | One entry for each key that more than one pitch class needs | | `clashes[].key` | The key, e.g. `"B"` | | `clashes[].notes` | The notes that need that key. Each note has `noteName` (URL-safe), `displayName`, `englishName`, `cents` and `centsInOctave`. With `includeArabic=true`, each note also has `displayNameAr`. | `centsInOctave` is the note's position above the transposition's tonic, with the octave ignored. It is the value the 12-pitch-class set compares. Two notes in the same clash with different `centsInOctave` values are different pitch classes competing for one key. ### Filtering by maqām (`maqamId`) * **Some transpositions fit:** the response has `compatible: true` and returns their sets as before. It adds `incompatibleTranspositions`, listing the transpositions that do not fit. * **No transposition fits:** the response is still `200`. It has `compatible: false`, `sets: []`, `incompatibleTranspositions`, and an `explanation` of the form `"No transposition of maqām X fits a 12-pitch-class set in from ."` * **The maqām cannot be built in this tuning system from this starting note** (the tuning system lacks some of its notes): the response is still `200`, with `compatible: false`, `sets: []`, an empty `incompatibleTranspositions` and an `explanation` saying so. * **The maqām does not exist:** the response is `404`. `maqamId` accepts a maqām's idName, its numeric id, or the idName of one of its transpositions. It matches exactly: `maqam_hijaz` does not also match `maqam_hijaz_kar`. The older closed-up spelling of a transposition (`maqam_rast_alqarar_chahargah`) is also accepted. See [Identifiers of transpositions](#identifiers-of-transpositions). ### Example In al-Ṣabbāgh (1954) from rāst, maqām faraḥnāk (al-Ḥilū) on qarār segāh does not fit. ʿirāq (B-b2) and nīm kawasht (B-2) are 29.5 cents apart, and both need the B key. The keys next to it are taken: nīm ʿajam is on Bb and rāst is on C. ```bash curl "https://diarmaqar.net/api/maqamat/classification/12-pitch-class-sets?tuningSystem=alsabbagh_1954&startingNote=rast&maqamId=maqam_farahnak_alhilu" ``` The entry for that transposition in `incompatibleTranspositions`: ```json { "maqam": { "id": "145", "idName": "maqam_farahnak_alhilu", "displayName": "maqām faraḥnāk (al-Ḥilū)" }, "transposition": { "idName": "maqam_farahnak_alhilu_al_qarar_segah", "displayName": "maqām faraḥnāk (al-Ḥilū) al-qarār segāh", "isTransposed": true, "isBaseForm": false }, "compatible": false, "reason": "shared_key", "explanation": "ʿirāq (B-b2) and nīm kawasht (B-2) both need the B key, and the keys next to it are taken.", "clashes": [ { "key": "B", "notes": [ { "noteName": "iraq", "displayName": "ʿirāq", "englishName": "B-b2", "cents": -141.2, "centsInOctave": 701.9 }, { "noteName": "nim_kawasht", "displayName": "nīm kawasht", "englishName": "B-2", "cents": -111.7, "centsInOctave": 731.4 } ] } ] } ``` The two `centsInOctave` values, 701.9 and 731.4, differ by 29.5 cents. They are two pitch classes, and both need the B key. *** ## Getting Started All endpoints return JSON. No authentication required. **Common parameters:** * `includeArabic` (default: "false") - Include Arabic script alongside transliteration * `includeSources` (default varies) - Include bibliographic source references For complete parameter documentation, see the [Endpoints Reference](./endpoints-reference). For recommended example values, see [Representative Examples](./representative-examples). --- --- url: /docs/api/representative-examples.md description: Recommended tuning systems, maqāmāt, and ajnās for proper API usage --- # Representative Examples These examples have been carefully selected to demonstrate the full capabilities of the API while respecting the cultural and historical significance of Arabic maqām theory. **Quick test URL:** ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents" ``` ## Quick Access Jump to specific example categories: * **[Representative Tuning Systems](#representative-tuning-systems)** - Historical and contemporary tuning systems * [al-Kindī (874)](#al-kindi-874-alkindi-874) - 12-Tone * [al-Fārābī (950g)](#al-farabi-950g-alfarabi-950g) - First Oud Tuning 27-Tone * [Ibn Sīnā (1037)](#ibn-sina-1037-ibnsina-1037) - 7-Fret Oud 17-Tone * [Meshshāqa (1899)](#meshshaqa-1899-meshshaqa-1899) - Arabic Octave According to the Modernists * [Cairo Congress Tuning Committee (1929)](#cairo-congress-tuning-committee-1929-cairocongresstuningcommittee-1929) - Egyptian Tuning * [al-Ṣabbāgh (1954)](#al-sabbagh-1954-alsabbagh-1954) - Contemporary Arabic Tuning 24-Tone * **[Representative Ajnās](#representative-ajnas)** - Tri/tetra/penta-chords * With zalzalian intervals: [jins rāst](#jins-rast-jins-rast), [jins bayyāt](#jins-bayyat-jins-bayyat), [jins segāh](#jins-segah-jins-segah), [jins ṣabā](#jins-saba-jins-saba) * Without zalzalian intervals: [jins nikrīz](#jins-nikriz-jins-nikriz), [jins kurd](#jins-kurd-jins-kurd), [jins nahāwand](#jins-nahawand-jins-nahawand), [jins ḥijāz](#jins-hijaz-jins-hijaz) * **[Representative Maqāmāt](#representative-maqamat)** - Complete modal frameworks * Principle maqāmāt: [maqām rāst](#maqam-rast-maqam-rast), [maqām bayyāt](#maqam-bayyat-maqam-bayyat), [maqām ḥijāz](#maqam-hijaz-maqam-hijaz) * Complex and transposed: [rāḥat al-arwāḥ](#rahat-al-arwah-maqam-rahat-al-arwah), [maqām bestenegar](#maqam-bestenegar-maqam-bestenegar) * Without zalzalian intervals: [maqām kurd](#maqam-kurd-maqam-kurd), [maqām athar kurd](#maqam-athar-kurd-maqam-athar-kurd), [maqām dilkesh ḥūrān](#maqam-dilkesh-huran-maqam-dilkesh-huran) *** ## ⚠️ Critical Requirements **REQUIRED Parameters for Detail Endpoints:** All detail endpoints (`https://diarmaqar.net/api/maqamat/{id}`, `https://diarmaqar.net/api/ajnas/{id}`) **MUST** include these two parameters: 1. **`tuningSystem`** - ID of the tuning system (e.g., `ibnsina_1037`) 2. **`startingNote`** - Starting note in URL-safe format (e.g., `yegah`, `ushayran`, `rast`) And should almost always include a third: 3. **`pitchClassDataType`** - Format for pitch class data (e.g., `cents`, `fraction`, `all`). When omitted, pitch classes contain only minimal note-name fields — include it to get actual pitch data. **Why these are required:** * Pitch class calculations depend on the tuning system and starting note * The API needs to know which format to return the data in * Without these parameters, the API cannot calculate or return pitch class data **Not sure which combinations are valid?** Every maqām and jins has an availability endpoint that lists every valid `tuningSystem` + `startingNote` pair: ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast/availability GET https://diarmaqar.net/api/ajnas/jins_rast/availability ``` **Example - CORRECT:** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` **Example - WRONG (missing parameters):** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast # ❌ Missing required parameters GET https://diarmaqar.net/api/maqamat/rast # ❌ Wrong endpoint format AND missing parameters ``` *** ## ❌ Common Mistakes to Avoid ### 1. Missing Required Parameters **WRONG:** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast GET https://diarmaqar.net/api/ajnas/jins_rast ``` **CORRECT:** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents GET https://diarmaqar.net/api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` ### 2. Wrong Endpoint Format **WRONG:** ```bash GET https://diarmaqar.net/api/maqamat/rast # Missing "maqam_" prefix GET https://diarmaqar.net/api/ajnas/rast # Missing "jins_" prefix ``` **CORRECT:** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast # Includes "maqam_" prefix GET https://diarmaqar.net/api/ajnas/jins_rast # Includes "jins_" prefix ``` ### 3. Using Display Names Instead of URL-Safe IDs **WRONG:** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=Ibn Sīnā (1037)&startingNote=yegah ``` **CORRECT:** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah ``` **Note:** Entity and tuning-system IDs must be exact URL-safe `idName` values (lowercase, no spaces or display formatting). Note-name parameters (`startingNote`, `transposeTo`) are matched diacritics-insensitively — `yegah` and `yegāh` both resolve — but the URL-safe form is canonical and recommended. ### 4. Parameter Discovery If you need to discover available parameters, use `options=true`: ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true ``` This returns available parameters instead of data, which is useful for programmatic discovery. **Precondition:** discovery mode requires a valid `tuningSystem`. `startingNote` is optional — without it the response lists the tuning system's valid starting notes and returns `transposeTo.options: null` (transpositions depend on the starting note). If you don't have a valid tuning system yet, start with the availability endpoint instead: ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast/availability ``` *** ## 🤖 For LLMs and AI Assistants **Explicit Instructions for AI Systems:** 1. **Always include required parameters** (`tuningSystem`, `startingNote`, `pitchClassDataType`) for detail endpoints 2. **Use Representative Examples** (this page) as the source of truth for correct API usage 3. **Reference the OpenAPI specification** at `/docs/openapi.json` for complete parameter documentation 4. **Use the availability endpoint first** (`https://diarmaqar.net/api/maqamat/{idName}/availability`, `https://diarmaqar.net/api/ajnas/{idName}/availability`) when you don't already have a known-valid `tuningSystem` + `startingNote` combination 5. **Use parameter discovery** (`options=true`) once you know a valid `tuningSystem` — `startingNote` is optional in discovery mode and the response lists the valid ones **If a request fails with HTTP 400:** the response body contains `error`, `hint`, and `validOptions` fields explaining exactly what to fix — but many AI HTTP tools cannot read 4xx response bodies, so you may only see the status code. In that case do not guess: call the availability endpoint for the entity and rebuild the request from a listed combination. **Example Parameter Discovery Request:** ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true ``` **Response includes:** * Valid starting notes for the requested tuning system (as URL-safe idNames, ready to use as parameter values) * Valid `pitchClassDataType` values * Valid `transposeTo` tonics, calculated for the requested tuning system and starting note * The boolean flags (`includeIntervals`, `includeModulations`, `includeModulations8vb`, `includeSuyur`) **Example options=true response** (maqām rāst, ibnsina\_1037, yegah): ```json { "maqam": "maqām rāst", "tuningSystem": "ibnsina_1037", "availableParameters": { "tuningSystem": { "required": true, "description": "ID of tuning system (see /availability for options)" }, "startingNote": { "options": [ "ushayran", "yegah" ], "required": true, "description": "Theoretical framework for note naming. Required for data retrieval. Optional for discovery mode (options=true). Needed to calculate transposition options." }, "pitchClassDataType": { "options": [ "all", "englishName", "fraction", "cents", "decimalRatio", "stringLength", "frequency", "abjadName", "fretDivision", "midiNoteNumber", "midiNoteDeviation", "centsDeviation", "referenceNoteName" ], "required": false, "description": "Output format for pitch data. Optional — when omitted, pitch classes contain only minimal note-name fields. Use 'cents' for tuning analysis or 'all' for complete pitch class information." }, "includeIntervals": { "type": "boolean", "default": false, "description": "Include interval data between pitch classes (?includeIntervals=true)" }, "transposeTo": { "options": [ "rast", "qarar_rast", "qarar_chahargah", "chahargah", "kurdan", "mahuran" ], "description": "Transpose to specific tonic (taṣwīr) - only valid transpositions shown. Calculated based on the provided tuningSystem and startingNote; null until a startingNote is provided." }, "includeModulations": { "type": "boolean", "default": false, "description": "Include modulation analysis (maqāmāt and ajnās)" }, "includeModulations8vb": { "type": "boolean", "default": false, "description": "Include available modulations an octave below" }, "includeSuyur": { "type": "boolean", "default": false, "description": "Include documented performance practices (suyūr)" } }, "notes": { "ajnasData": "Ajnās (constituent melodic structures) are always included in the response for maqām analysis", "formatOptions": "The 'pitchClassDataType' parameter controls which pitch class properties are returned. Use 'all' for comprehensive data or specific formats like 'cents', 'fraction', etc. for targeted data." }, "examples": [ "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&includeIntervals=true", "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&transposeTo=qarar_rast&includeModulations=true", "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=all&includeSuyur=true" ] } ``` **Best Practice:** * When users ask about a specific maqām, jins, or tuning system, use the Representative Examples to find the correct endpoint format * Always include all three required parameters * Use `cents` as the default `pitchClassDataType` for most use cases * For users who don't know specific names, use `maqam_rast` with `ibnsina_1037` and `yegah` as safe defaults * For valid `filterByFamily` values, use `GET https://diarmaqar.net/api/maqamat/families?tuningSystem=ibnsina_1037&startingNote=yegah` *** ## 📋 Actual Response Structure API responses are complex nested structures, not simple arrays. A typical response includes: **Key Response Fields:** * `maqam` / `jins` - Entity metadata (`id`, `idName`, `displayName`, `version`) * `family` / `tonic` - Entity references (`idName`, `displayName`) * `stats` - Statistics (number of transpositions, pitch classes, modulations) * `characteristics` - Musical characteristics (`isOctaveRepeating`, `hasAsymmetricDescending`, `hasSuyur`) * `availableTranspositions` - Valid transposition targets for the requested tuning system and starting note * `context` - Tuning system context: its valid starting notes (`idNames` + `displayNames`), the selected starting note, reference frequency * `pitchData` - Pitch class data in ascending/descending arrays (each entry carries `pitchClassIndex`, `octave`, `scaleDegree`, `noteName`, `noteNameDisplay`, plus the requested data type fields) * `ajnas`, `primaryJins`, `secondaryJins`, `tertiaryJins`, `ghammaz` - Constituent melodic structures per maqām degree * `intervals` - Interval data (if `includeIntervals=true`) * `sources` - Bibliographic source references * `links` - Related API endpoint URLs **Minimal Example Response** (abridged): ```json { "maqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst", "version": "2025-12-10T17:03:34.565Z" }, "family": { "idName": "rast", "displayName": "rāst" }, "tonic": { "idName": "rast", "displayName": "rāst" }, "stats": { "numberOfTranspositions": 3, "numberOfPitchClasses": 7, "numberOfMaqamModulations": 49, "numberOfAjnasModulations": 47 }, "characteristics": { "isOctaveRepeating": true, "hasAsymmetricDescending": true, "hasSuyur": true }, "context": { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "startingNotes": { "idNames": ["ushayran", "yegah"], "displayNames": ["ʿushayrān", "yegāh"] }, "selectedStartingNote": { "idName": "yegah", "displayName": "yegāh" } } }, "pitchData": { "ascending": [ { "pitchClassIndex": 7, "octave": 1, "scaleDegree": "I", "noteName": "rast", "noteNameDisplay": "rāst", "cents": 498.0449991346125 }, { "pitchClassIndex": 10, "octave": 1, "scaleDegree": "II", "noteName": "dugah", "noteNameDisplay": "dūgāh", "cents": 701.9550008653874 } ], "descending": [ { "pitchClassIndex": 4, "octave": 2, "scaleDegree": "VII", "noteName": "ajam", "noteNameDisplay": "ʿajam", "cents": 1494.1349974038376 } ] }, "sources": [{ "sourceId": "alshawwa_1946", "page": "42" }], "links": { "self": "…", "detail": "…", "availability": "…", "compare": "…" } } ``` **For complete response schemas**, see the [OpenAPI Specification](../openapi.json). *** ## Representative Tuning Systems ### al-Kindī (874) - `alkindi_874` **Title**: 12-Tone **Starting Notes**: ʿushayrān - `ushayran`, yegāh - `yegah`, rāst - `rast` **Description**: One of the oldest tuning systems documented in Arabic music theory. It is a 12-tone chromatic tuning system based on Greek theory and doesn't include the quintessential so-called Arabic "quarter tone" pitch classes ʿirāq, nīm zīrgūleh, segāh, nīm ḥijāz, or awj, also referred to as zalzalian intervals. It can only render ajnās and maqāmāt that don't use those notes such as kurd, nahāwand, nikrīz and ʿajam ʿushayrān. **Source**: [Farmer (1937:248)](../../bibliography?source=farmer_1937), [Forster (2010:615)](../../bibliography?source=forster_2010) **Required Parameters:** * `tuningSystem`: `alkindi_874` * `startingNote`: `ushayran` * `pitchClassDataType`: `cents` (or `fraction`, `all`, etc.) **Example**: ```bash GET https://diarmaqar.net/api/tuning-systems/alkindi_874/ushayran/pitch-classes?pitchClassDataType=cents ``` **Good for testing**: * Ajnās without zalzalian intervals: `jins_kurd`, `jins_nahawand`, `jins_nikriz` * Maqāmāt without zalzalian intervals: `maqam_kurd`, `maqam_nahawand` *** ### al-Fārābī (950g) - `alfarabi_950g` **Title**: First Oud Tuning (Full First Octave) 27-Tone **Starting Notes**: ʿushayrān - `ushayran`, yegāh - `yegah` **Description**: The first documentation of the wuṣtā zalzal interval, the so-called Arabic "quarter tone" using a frequency ratio of 27/22. It is a comprehensive 27-tone tuning system that allows for many ajnās and maqāmāt and their transpositions, therefore also modulations. **Source**: [Farmer (1937:249)](../../bibliography?source=farmer_1937), [Land (1885:134-137)](../../bibliography?source=land_1885), [d'Erlanger (1930:165-185)](../../bibliography?source=derlanger_1930) **Example**: ``` GET https://diarmaqar.net/api/tuning-systems/alfarabi_950g/ushayran/pitch-classes?pitchClassDataType=cents ``` **Good for testing**: * Comprehensive ajnās and maqāmāt coverage * Zalzalian intervals * Historical comparison studies *** ### Ibn Sīnā (1037) - `ibnsina_1037` **Title**: 7-Fret Oud 17-Tone **Starting Notes**: ʿushayrān - `ushayran`, yegāh - `yegah` **Description**: An excellent concise and precise 17-tone tuning that allows for a wide range of ajnās and maqāmāt and their transpositions. Includes the wuṣtā zalzal interval with the frequency ratio of 39/32. **Source**: [Farmer (1937:249)](../../bibliography?source=farmer_1937) **Example**: ``` GET https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/pitch-classes?pitchClassDataType=cents ``` **Good for testing**: * All primary maqāmāt: `maqam_rast`, `maqam_bayyat`, `maqam_hijaz` * All primary ajnās: `jins_rast`, `jins_bayyat`, `jins_hijaz` * Transpositions and modulations *** ### Meshshāqa (1899) - `meshshaqa_1899` **Title**: Arabic Octave According to the Modernists **Starting Notes**: yegāh - `yegah` **Description**: The first documented tuning system that is based on literal quarter tones, 24 equal divisions of the octave. Defined by Meshshāqa as the "Arabic Octave According to the Modernists", meaning that it was already known before him but undocumented - though no one knows if it was really used. Because it is 24 equal divisions of the octave it allows for many ajnās and maqāmāt and their transpositions, therefore also modulations. Even though it allows the same number of maqāmāt as Ibn Sīnā's tuning system, it allows for more transpositions. **Source**: [Meshshāqa (1899:18)](../../bibliography?source=meshshaqa_1899) **Example**: ``` GET https://diarmaqar.net/api/tuning-systems/meshshaqa_1899/yegah/pitch-classes?pitchClassDataType=cents ``` **Good for testing**: * Modern equal-division approach * Comparison with historical unequal systems * All maqāmāt and ajnās * Extended transposition capabilities *** ### Cairo Congress Tuning Committee (1929) - `cairocongresstuningcommittee_1929` **Title**: Egyptian Tuning **Starting Notes**: yegāh - `yegah`, rāst - `rast` **Description**: The tuning system researched, measured and prepared in preparation for the 1932 Cairo Congress of Arabic Music. It is referred to as an "Egyptian Tuning" and is an unequal 24-tone system. Also comprehensive in its maqām availability and was rendered based on the measurement and expertise of Egyptian musicians at the time. **Source**: [Shawqi (1969:48-49)](../../bibliography?source=shawqi_1969), [na. (1933:336)](../../bibliography?source=na_1933), [Allāh-Wīrdī (1949:80)](../../bibliography?source=allahwirdi_1949) **Example**: ``` GET https://diarmaqar.net/api/tuning-systems/cairocongresstuningcommittee_1929/rast/pitch-classes?pitchClassDataType=cents ``` **Good for testing**: * Egyptian performance practice * 20th-century documentation standards * Unequal divisions vs. equal divisions *** ### al-Ṣabbāgh (1954) - `alsabbagh_1954` **Title**: Contemporary Arabic Tuning 24-Tone **Starting Notes**: rāst - `rast` **Description**: The only documented theorisation of an Arabic tuning system that exclusively uses the "comma" (syntonic comma of 81/80) as a basis for its construction. It is an unequal 24-tone system and allows for many maqāmāt and ajnās but with limited transpositions. **Source**: [al-Ṣabbāgh (1954:47)](../../bibliography?source=alsabbagh_1954) **Example**: ``` GET https://diarmaqar.net/api/tuning-systems/alsabbagh_1954/rast/pitch-classes?pitchClassDataType=cents ``` **Good for testing**: * Acoustic purity approaches * Limited transposition scenarios * Theoretical vs. practical systems *** ## Representative Ajnās **Ajnās with zalzalian intervals** (ʿirāq, nīm zīrgūleh, segāh, nīm ḥijāz, or awj): ### jins rāst - `jins_rast` **Description**: Includes the zalzalian interval segāh. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Required Parameters:** * `tuningSystem`: `ibnsina_1037`, `alfarabi_950g`, `meshshaqa_1899`, or `cairocongresstuningcommittee_1929` * `startingNote`: e.g. `yegah` (IbnSina, Meshshaqa), `ushayran` (al-Farabi), `rast` (CairoCongress) — several systems accept more than one starting note; `GET https://diarmaqar.net/api/ajnas/jins_rast/availability` lists every valid combination * `pitchClassDataType`: `cents` (or `fraction`, `all`, etc.) **Example**: ```bash GET https://diarmaqar.net/api/ajnas/jins_rast?tuningSystem=meshshaqa_1899&startingNote=yegah&pitchClassDataType=cents ``` *** ### jins bayyāt - `jins_bayyat` **Description**: Includes the zalzalian interval segāh. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=cairocongresstuningcommittee_1929&startingNote=rast&pitchClassDataType=cents ``` *** ### jins segāh - `jins_segah` **Description**: Its tonic is the zalzalian interval segāh. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_segah?tuningSystem=alsabbagh_1954&startingNote=rast&pitchClassDataType=cents ``` *** ### jins ṣabā - `jins_saba` **Description**: Includes the zalzalian interval segāh. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: [al-Khulaʿī (2011:55)](../../bibliography?source=alkhulai_1904_2011), [al-Urmawī-al-Baghdādī (2017:23)](../../bibliography?source=alurmawialbaghdadi_1986_2017) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_saba?tuningSystem=meshshaqa_1899&startingNote=yegah&pitchClassDataType=cents ``` *** **Ajnās without zalzalian intervals:** ### jins nikrīz - `jins_nikriz` **Description**: Does not include a zalzalian interval. **Tuning System**: `alkindi_874` on `ushayran`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_nikriz?tuningSystem=alkindi_874&startingNote=ushayran&pitchClassDataType=cents ``` *** ### jins kurd - `jins_kurd` **Description**: Does not include a zalzalian interval. **Tuning System**: `alkindi_874` on `ushayran`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_kurd?tuningSystem=alkindi_874&startingNote=ushayran&pitchClassDataType=cents ``` *** ### jins kurd (binsir) - `jins_kurd_binsir` **Description**: The same as jins kurd but starting on a different tonic, giving it slightly different intervals. Interesting for comparison and understanding why the maqām based on it (maqām ḥijāz kār kurd) is supposedly a transposition of maqām kurd with the same intervals, but in fact is not. Does not include a zalzalian interval. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `yegah`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `yegah` or `rast`. Not available in `alkindi_874`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_kurd_binsir?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` *** ### jins nahāwand - `jins_nahawand` **Description**: Does not include a zalzalian interval. **Tuning System**: `alkindi_874` on `ushayran`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_nahawand?tuningSystem=alkindi_874&startingNote=ushayran&pitchClassDataType=cents ``` *** ### jins ḥijāz - `jins_hijaz` **Description**: Does not include a zalzalian interval. **Tuning System**: `alkindi_874` on `ushayran` or `ibnsina_1037` on `yegah`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_hijaz?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` *** ### jins ḥijāz (binsir) - `jins_hijaz_binsir` **Description**: The same as jins ḥijāz but starting on a different tonic, giving it slightly different intervals. Interesting for comparison. Does not include a zalzalian interval. **Tuning System**: `ibnsina_1037` on `yegah`. Not available in `alkindi_874`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/ajnas/jins_hijaz_binsir?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` *** ## Representative Maqāmāt **Principle maqāmāt** - fundamental and archetypal: ### maqām rāst - `maqam_rast` **Description**: One of the principle and archetypal Arabic maqāmāt. Prominently used in Egypt across both popular and religious sufi musics. Includes the zalzalian intervals segāh and awj in its ascending form. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Required Parameters:** * `tuningSystem`: `ibnsina_1037`, `alfarabi_950g`, `meshshaqa_1899`, or `cairocongresstuningcommittee_1929` * `startingNote`: e.g. `yegah` (IbnSina, Meshshaqa), `ushayran` (al-Farabi), `rast` (CairoCongress) — several systems accept more than one starting note; `GET https://diarmaqar.net/api/maqamat/maqam_rast/availability` lists every valid combination * `pitchClassDataType`: `cents` (or `fraction`, `all`, etc.) **Example**: ```bash GET https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=cairocongresstuningcommittee_1929&startingNote=rast&pitchClassDataType=cents ``` *** ### maqām bayyāt - `maqam_bayyat` **Description**: Also a principle and archetypal Arabic maqām, that is used widely in popular and rural musics across the Arabic speaking region and beyond. It is the base maqām for many variations in Arabic repertoire and beyond. Includes the zalzalian interval segāh and awj in its ascending form. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/maqamat/maqam_bayyat?tuningSystem=meshshaqa_1899&startingNote=yegah&pitchClassDataType=cents ``` *** ### maqām ḥijāz - `maqam_hijaz` **Description**: A principle Arabic maqām, known primarily for its use in the adhān, the call to prayer. Includes the zalzalian interval awj in its ascending form. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/maqamat/maqam_hijaz?tuningSystem=alsabbagh_1954&startingNote=rast&pitchClassDataType=cents ``` *** **Complex and transposed maqāmāt:** ### rāḥat al-arwāḥ - `maqam_rahat_alarwah` **Description**: A transposition of maqām huzām given its own name because of its character. Its darajat al-istiqrār (tonic) is the zalzalian interval ʿirāq. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/maqamat/maqam_rahat_alarwah?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` *** ### maqām bestenegar - `maqam_bestenegar` **Description**: Complex and rarely used non-octave repeating maqam. Its darajat al-istiqrār (tonic) is the zalzalian interval segāh. **Tuning System**: `ibnsina_1037` on `yegah`, `alfarabi_950g` on `ushayran`, `meshshaqa_1899` on `yegah`, or `cairocongresstuningcommittee_1929` on `rast`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/maqamat/maqam_bestenegar?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents ``` *** **Maqāmāt without zalzalian intervals:** ### maqām kurd - `maqam_kurd` **Description**: This maqām came to much prominence in 1960s and 70s Egyptian popular music, and is one of the most used in pop music across the region today. It doesn't include the quintessential so-called Arabic "quarter tone", i.e. pitch classes ʿirāq, nīm zīrgūleh, segāh, nīm ḥijāz, or awj. **Tuning System**: `alkindi_874` on `ushayran`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/maqamat/maqam_kurd?tuningSystem=alkindi_874&startingNote=ushayran&pitchClassDataType=cents ``` *** ### maqām athar kurd - `maqam_athar_kurd` **Description**: A rarely used maqām with a very specific character. It doesn't include the quintessential so-called Arabic "quarter tone", i.e. pitch classes ʿirāq, nīm zīrgūleh, segāh, nīm ḥijāz, or awj. **Tuning System**: `alkindi_874` on `ushayran`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/maqamat/maqam_athar_kurd?tuningSystem=alkindi_874&startingNote=ushayran&pitchClassDataType=cents ``` *** ### maqām dilkesh ḥūrān - `maqam_dilkesh_huran` **Description**: A complex non-octave repeating Ottoman maqām that is rarely used in Arabic music but was a part of early 20th century music theory. **Tuning System**: `ibnsina_1037` on `yegah` or `meshshaqa_1899` on `yegah`. **Source**: (No source references in data) **Example**: ``` GET https://diarmaqar.net/api/maqamat/maqam_dilkesh_huran?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents ``` *** ## Representative Usage Patterns ### Basic Detail Request ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents" ``` ### With All Optional Parameters ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&includeArabic=true&includeIntervals=true&includeModulations=true&includeModulations8vb=true&includeSuyur=true" ``` ### Parameter Discovery ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true" ``` ### Availability (valid tuningSystem + startingNote combinations) ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast/availability" ``` ### Comparison Across Tuning Systems ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast/compare?tuningSystems=ibnsina_1037,alfarabi_950g&startingNotes=yegah&pitchClassDataType=cents" ``` ### Transposition ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&transposeTo=chahargah" ``` Valid `transposeTo` tonics depend on the maqām, tuning system, and starting note — use `options=true` (above) to list them for a given combination. ### 12-Pitch-Class Sets ```bash curl "https://diarmaqar.net/api/maqamat/classification/12-pitch-class-sets?tuningSystem=alsabbagh_1954&startingNote=rast&includeIncompatible=true" ``` A transposition that does not fit (maqām faraḥnāk (al-Ḥilū) on qarār segāh): ```bash curl "https://diarmaqar.net/api/maqamat/classification/12-pitch-class-sets?tuningSystem=alsabbagh_1954&startingNote=rast&maqamId=maqam_farahnak_alhilu" ``` Transpositions that do not fit are always counted, and listed with the key and the pitch classes that need it. See [Transpositions that do not fit a 12-pitch-class set](./index#transpositions-that-do-not-fit-a-12-pitch-class-set). *** ## Testing Combinations ### Test Basic Coverage * Tuning: `ibnsina_1037` on `yegah` * Maqām: `maqam_rast` * Jins: `jins_rast` * Format: `cents` ### Test Zalzalian Intervals * Tuning: `alfarabi_950g` on `ushayran` * Ajnās: `jins_rast`, `jins_bayyat`, `jins_segah`, `jins_saba` ### Test Non-Zalzalian Systems * Tuning: `alkindi_874` on `ushayran` * Ajnās: `jins_kurd`, `jins_nahawand`, `jins_nikriz` ### Test Modern Equal Divisions * Tuning: `meshshaqa_1899` on `yegah` * Compare with: `ibnsina_1037` to see equal vs. unequal ### Test Complex Structures * Maqām: `maqam_bestenegar` (non-octave-repeating) * Maqām: `maqam_dilkesh_huran` (Ottoman complexity) ### Test Historical Documentation * Tuning: `cairocongresstuningcommittee_1929` on `rast` * Compare with: `alsabbagh_1954` on `rast` *** ## See Also * [API Documentation](./index) - Main API overview * [Interactive Playground](./playground) - Test these examples interactively * [OpenAPI Specification](/openapi.yaml) - Complete parameter documentation --- --- url: /docs/api/endpoints-reference.md description: Complete API endpoint documentation --- # API Endpoints Reference Complete documentation for all API endpoints. For quick start, see [API Documentation](./index). For examples, see [Representative Examples](./representative-examples). *** # Quick Reference ## Base URL * **Production**: `https://diarmaqar.net/api` * **Development**: `http://localhost:3000/api` ## OpenAPI Specification Machine-readable OpenAPI 3.1.0 specification: * [openapi.json](/openapi.json) * [openapi.yaml](/openapi.yaml) ## Authentication The API does not require authentication. All endpoints are publicly accessible. ## Response Format All API responses are in JSON format. List endpoints return: ```json { "count": , "data": [] } ``` ## Rate Limiting Currently, there are no rate limits. Please use the API responsibly. ## Common Parameters Most endpoints support these optional parameters: * **`includeArabic`** (default: `"false"`): Include Arabic script alongside transliteration * `"true"`: Bilingual responses with `*Ar` suffixed fields (`displayNameAr`, `noteNameDisplayAr`, etc.) * `"false"`: English transliteration only * **`includeSources`** (default: `"true"` for list endpoints, `"false"` for detail endpoints): Include bibliographic source references * `"true"`: Include `sources` array with `{sourceId, page}` objects * `"false"`: Omit source references for performance *** # Endpoints ## Maqāmāt Documented modal frameworks with historical source attribution. ### List all maqāmāt {#listMaqamat} ``` GET /maqamat ``` Retrieve all available maqāmāt with optional filtering and sorting. **Returns:** All maqāmāt with their tuning system availability information. This endpoint does **not** include note names or pitch class data—only metadata about which tuning systems can realize each maqām. Returns concise metadata including: * URL-safe identifiers and display names for each maqām * Maqām family and maqām tonic identifiers (both URL-safe and display formats) * Availability counts across tuning systems with their valid starting note names (e.g., "ʿushayrān", "yegāh" etc...) * Optional bibliographic source references (sourceId and page) when `includeSources=true` * Filter values must be URL-safe; see parameter enums for complete list of valid options **Note:** For detailed pitch class data, note names, and ajnās information, use the `/maqamat/{idName}` endpoint. **Query Parameters:** * `filterByFamily` (optional): Filter by maqām family name (URL-safe, case-insensitive, diacritics-insensitive). Use GET /maqamat/families to retrieve valid family values.. Use GET /maqamat/families to retrieve valid family values. * Type: `string` - Valid values: `ajam`, `athar_kurd`, `awj_ara`, `bayyat`, `buselik`, ... (16 total) * Example: `rast` * `filterByTonic` (optional): Filter by maqām tonic/first note (URL-safe, case-insensitive, diacritics-insensitive) - Type: `string` - Valid values: `ajam_ushayran`, `chahargah`, `dugah`, `iraq`, `nawa`, `rast`, `segah`, `ushayran`, `yegah` * `sortBy` (optional): Sort order for results. including empty string) return HTTP 400. * Type: `string` - Valid values: `alphabetical`, `tonic` - Default: `alphabetical` * Example: `alphabetical` - Sort alphabetically by display name (default) * Example: `tonic` - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak * `includeSources` (optional): Include bibliographic source references (sourceId and page) for each maqām - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat?includeSources=true&includeArabic=true" ``` **Response:** List of maqāmāt retrieved successfully **Example response — default:** ```json { "count": 105, "data": [ { "maqam": { "id": "102", "idName": "maqam_ajam_buselik", "displayName": "maqām ʿajam būselīk", "version": "2026-07-20T16:38:38.320Z" }, "family": { "idName": "bayyat", "displayName": "bayyāt" }, "tonic": { "idName": "dugah", "displayName": "dūgāh" }, "stats": { "numberOfPitchClasses": 7, "availableInTuningSystems": 6 }, "characteristics": { "isOctaveRepeating": true, "hasAsymmetricDescending": true, "hasSuyur": true }, "availability": { "tuningSystems": [ { "tuningSystem": { "id": "alfarabi_950i", "idName": "alfarabi_950i", "displayName": "al-Fārābī (950i) Second Oud Tuning 22-Tone", "version": "2026-08-05T14:18:59.205Z" }, "startingNotes": { "idNames": [ "yegah" ], "displayNames": [ "yegāh" ] } }, { "tuningSystem": { "id": "alfarabi_950g", "idName": "alfarabi_950g", "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone", "version": "2026-08-05T14:18:59.205Z" }, "startingNotes": { "idNames": [ "ushayran" ], "displayNames": [ "ʿushayrān" ] } } ] }, "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_ajam_buselik" } } ] } ``` ### List maqām families {#listMaqamFamilies} ``` GET /maqamat/families ``` Retrieve maqām families for maqāmāt available in the specified tuning system. Families are classified by the first jins at scale degree 1. Use the `maqamat` link to filter maqāmāt by family via GET /maqamat?filterByFamily={idName}. **Query Parameters:** * `tuningSystem` **(required)**: Tuning system identifier (e.g., ibnsina\_1037, alsabbagh\_1954) - Type: `string` * Example: `ibnsina_1037` * `startingNote` **(required)**: Starting note name (URL-safe, diacritics-insensitive) - Type: `string` * Example: `yegah` * `includeArabic` (optional): Include Arabic display names in family objects - Type: `string` - Valid values: `true`, `false` - Default: `false` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat/families?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=false" ``` **Response:** Maqām families retrieved successfully **Example response:** ```json { "count": 16, "data": [ { "family": { "idName": "rast", "displayName": "rāst" } }, { "family": { "idName": "bayyat", "displayName": "bayyāt" } }, { "family": { "idName": "hijaz", "displayName": "ḥijāz" } }, { "family": { "idName": "ajam", "displayName": "ʿajam" } } ] } ``` ### Get detailed maqām data {#getMaqam} ``` GET /maqamat/{idName} ``` Retrieve comprehensive data for a specific maqām on its conventional or a transposed tonic, in a specific tuning system on a specific starting note name. **Special Path Parameter Value:** * The `{idName}` path parameter accepts the special value `"all"` to retrieve every maqām form a tuning system can build from a starting note, in one request * When using `"all"`, both `tuningSystem` and `startingNote` query parameters are required * Each item of `maqamat` is exactly the body this endpoint returns for that form with the same options, without the envelope (`parameters`, `context`, `links`), which the bulk response carries once * `forms` chooses the base forms (default), their transpositions (taṣwīr), or both; `includeOctaveRenderings=true` adds the octave-register renderings (e.g. `maqam_rast_al_qarar_rast`), which are neither * `fields` keeps only the named top-level fields of each item (`maqam` is always kept) and skips the work for the others * Responses are paged by size: a page holds at most about 5 MB of items. `total` counts every selected form, `count` the forms on this page, and `next` is the URL of the next page (`null` on the last). Follow `next` until it is `null` Returns: * Comprehensive pitch class data in the requested tuning system and starting note name * All ajnās present at each maqām degree in the ascending and descending maqām structure, keyed by each degree's URL-safe `noteName` (the same value as `pitchData[].noteName`, e.g. `segah`) * The maqām's primary, secondary, and (when defined) tertiary jins positions as transposed per-degree entries — each carrying the note name, maqām degree (roman numeral), and the resolved jins entity `{jinsId, jinsIdName, jinsDisplayName}` * The maqām's ghammāz (modulation emphasis note) as a note-name + maqām-degree entry (no jins fields — the ghammāz is a melodic-emphasis note, not a jins) * All four of `primaryJins`, `secondaryJins`, `tertiaryJins`, and `ghammaz` are transposed in sync with the selected transposition (e.g. when `transposeTo=nawa` is used, every entry reflects the new tonic and the new maqām-degree position of each note). They are returned as arrays of per-degree objects to accommodate alternatives, or `null` when a maqām has no entry for that slot (e.g. rāst has no tertiary). * Optional includeIntervals data, transposition to different tonics, tuning-system-specific modulations (including lower octave), and suyūr Parameter Discovery: * Use options=true to discover valid values for all parameters including dynamically calculated transposition options * Especially useful for finding valid tuning system starting notes and transposition tonics for a specific maqām Important: * When options=true, the endpoint returns parameter discovery metadata instead of maqām data * This mode is mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, include suyūr, pitch class data type, includeIntervals) * If data-returning parameters are provided with options=true, the API returns a 400 Bad Request error with details about conflicting parameters Requirements: * Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes * These are fundamental to all pitch class calculations **Path Parameters:** * `idName`: URL-safe maqām identifier: A maqām's idName (`maqam_rast`), its numeric id, or the idName of one of its transpositions (`maqam_rast_al_qarar_chahargah`). A transposed idName works like adding `transposeTo` for its tonic; giving it together with a different `transposeTo` is a 400. The older closed-up spelling (`maqam_rast_alqarar_chahargah`) is also accepted. **Special value**: Use `"all"` to retrieve every maqām form in a specific tuning system and starting note at once (see `forms`, `includeOctaveRenderings`, `fields` and `offset`). When using `"all"`, both `tuningSystem` and `startingNote` query parameters are required. (string) **(required)** * Example: `maqam_rast` - Maqām Rāst (representative example) * Example: `maqam_bayyat` - Maqām Bayyāt (representative example) * Example: `maqam_saba` - Maqām Ṣabā (representative example) * Example: `all` - All maqāmāt (requires tuningSystem and startingNote query parameters) **Query Parameters:** * `tuningSystem` **(required)**: Tuning system identifier (e.g., 'ibnsina\_1037', 'alfarabi\_950g', 'meshshaqa\_1899') - Type: `string` * Example: `ibnsina_1037` - Ibn Sīnā (1037) - 7-Fret Oud 17-Tone (representative example) * Example: `alfarabi_950g` - al-Fārābī (950g) - First Oud Tuning 27-Tone (representative example) * `startingNote` **(required)**: Tuning system starting note name (URL-safe, diacritics-insensitive). * Different starting notes represent different theoretical frameworks within the same tuning system * Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh * Type: `string` * Example: `yegah` - yegāh (for IbnSina, Meshshaqa) * Example: `ushayran` - ʿushayrān (for al-Farabi, al-Kindi) * `options` (optional): When true, returns available parameter options instead of maqām data. * Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes * These are fundamental to all pitch class calculations and calculate valid starting note options and transposition tonics * Mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, include suyūr, pitch class data type, includeIntervals) * Transposition options are dynamically calculated based on the specific maqām, tuning system, and starting note combination * Only tonics where the maqām can be validly transposed (preserving interval pattern) are included, not all possible pitch classes * If data-returning parameters are provided, returns 400 Bad Request error with details about conflicting parameters * Type: `string` - Valid values: `true`, `false` - Default: `false` * `pitchClassDataType` (optional): Specifies which pitch class data type to return for each pitch class. * When provided, returns the specified data type for all pitch classes in the maqām * In discovery mode (when options=true), this parameter is optional since the response returns parameter metadata instead of formatted data * Use 'all' for complete pitch class data across all available formats * `pitchClassIndex` and `scaleDegree` return the minimal field set explicitly * Type: `string` - Valid values: `all`, `abjadName`, `englishName`, `solfege`, `fraction`, ... (16 total) * Example: `cents` * `transposeTo` (optional): Transpose the maqām to a new tonic by preserving the interval patterns (URL-safe, diacritics-insensitive). * To see all valid transposition options, request available parameter options instead of maqām data * Type: `string` * `includeIntervals` (optional): Include interval data between maqām degrees - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeModulations` (optional): Include modulation possibilities to other maqāmāt and ajnās - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeModulations8vb` (optional): Include available modulations an octave below - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeSuyur` (optional): Include the suyūr (melodic paths) that can be played on the maqām form requested, each moved onto that form. each moved onto that form. See `suyur` in the response. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` * `forms` (optional): Only with idName `all`. * `transpositions`: every transposition (taṣwīr) of each maqām in this tuning system and starting note * `all`: both, the base form of each maqām followed by its transpositions * Type: `string` - Valid values: `base`, `transpositions`, `all` - Default: `base` * `includeOctaveRenderings` (optional): Only with idName `all`. same maqām an octave from its base form (e.g. `maqam_rast_al_qarar_rast`). They are neither the base form nor a transposition, and they appear as modulation targets. * Type: `string` - Valid values: `true`, `false` - Default: `false` * `fields` (optional): Only with idName `all`. `ajnas,primaryJins,modulations`. `maqam` is always kept. A field left out is not computed, so leaving out `modulations`, `lowerOctaveModulations` and `stats` skips the modulation analysis. Unknown or empty values are a 400. Valid fields: family, tonic, transposition, stats, characteristics, availableTranspositions, availableOctaveRenderings, comments, sources, pitchData, intervals, ajnas, primaryJins, secondaryJins, tertiaryJins, primaryJinsDescending, secondaryJinsDescending, tertiaryJinsDescending, ghammaz, suyur, modulations, lowerOctaveModulations. * Type: `string` * `offset` (optional): Only with idName `all`. out for the first page, then follow the `next` URL of each response, which sets it. A negative, fractional or too large value is a 400. * Type: `integer` - Default: `0` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=true" ``` **Response:** Maqām data retrieved successfully. * With idName `all`, the response is a `MaqamBulkResponse`: one page of maqām forms, each shaped as below without `parameters`, `context` and `links` * When options is true, the response structure differs and returns available parameter options instead of maqām data * In that case, transposition options contain only valid transposition tonics for this specific maqām, tuning system, and starting note combination **Example response — basic:** ```json { "maqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst", "version": "2026-08-11T19:43:52.080Z", "isBaseForm": true, "formType": "base" }, "family": { "idName": "rast", "displayName": "rāst" }, "tonic": { "idName": "rast", "displayName": "rāst" }, "stats": { "numberOfTranspositions": 3, "numberOfPitchClasses": 7, "numberOfMaqamModulations": 79, "numberOfAjnasModulations": 49 }, "characteristics": { "isOctaveRepeating": true, "hasAsymmetricDescending": true, "hasSuyur": true }, "availableTranspositions": [ { "idName": "maqam_rast_al_qarar_chahargah", "displayName": "maqām rāst al-qarār chahārgāh", "formType": "transposition", "tonic": { "idName": "qarar_chahargah", "displayName": "qarār chahārgāh" } }, { "idName": "maqam_rast_al_chahargah", "displayName": "maqām rāst al-chahārgāh", "formType": "transposition", "tonic": { "idName": "chahargah", "displayName": "chahārgāh" } }, { "idName": "maqam_rast_al_mahuran", "displayName": "maqām rāst al-māhūrān", "formType": "transposition", "tonic": { "idName": "mahuran", "displayName": "māhūrān" } } ], "availableOctaveRenderings": [ { "idName": "maqam_rast_al_qarar_rast", "displayName": "maqām rāst al-qarār rāst", "formType": "octaveRendering", "tonic": { "idName": "qarar_rast", "displayName": "qarār rāst" } }, { "idName": "maqam_rast_al_kurdan", "displayName": "maqām rāst al-kurdān", "formType": "octaveRendering", "tonic": { "idName": "kurdan", "displayName": "kurdān" } } ], "comments": { "english": "This maqām's data is compiled from al-Shawwā (1946, p.42), al-Ṣabbāgh (1950, p.41) and al-Ḥilū (1961, p.107). The sources agree on the scale in both directions: al-Ḥilū's construction runs two identical disjunct octaves, rāst to jawāb kurdān, and his printed note against awj, \"and in the descent it is substituted by ʿajam\", independently reproduces al-Shawwā's descending ʿajam; his ḥusaynī row is annotated \"to make būselīk on nawā\" (1961, p.107). On the maqām's character: \"it rests on presenting the jins rāst on the two degrees nawā and yegāh\" (1961, p.107), agreeing with the ghammāz nawā assigned here. His footnote explains the maqām's canonical standing: \"this maqām rāst is composed of the succession of the natural tonal degrees, as we indicated earlier; for that disposition, and because from each of these eight notes, that is its degrees, an Arab maqām standing in its own right is composed, it has been considered the fundamental scale in Arab music. In view of this standing of it, we ought to have presented it in analysis and notation before the other maqāms, were it not that the necessity of our ordering the maqāms in this book according to the degrees of their finals, from the deepest note upwards in sequence, made us fix it here in its rank, that is, in the centre of the tonal register on which it rests\" (1961, p.107).", "arabic": "جُمعت بيانات هذا المقام من الشوا (1946، ص42) والصباغ (1950، ص41) والحلو (1961، ص107). تتفق المصادر على السلّم في الاتجاهين: تكوين الحلو ديوانان منفصلان متطابقان من الراست الى جواب الكردان، وملاحظته المطبوعة عند الاوج «وفي الهبوط يستبدل بالعجم» تعيد باستقلال انتاج العجم في هبوط الشوا؛ وصف الحسيني عنده معلّم «لعمل بوسليك على النوا» (1961، ص107). عن شخصية المقام: «تقوم على اظهار جنس الراست على درجتي النوا واليكاه» (1961، ص107)، بما يوافق الغماز النوا المعتمد هنا. تشرح حاشيته مكانة المقام: «ان مقام الراست هذا يتألف من تتابع الدرجات الصوتية الطبيعية كما اشرنا سابقاً ، فهو لذلك الوضع ولكون اصواته أي درجاته الثمانية هــذه يتألف من كل منها مقام عربي قائم في ذاته . قد اعتبر السلم الاساسي في الموسيقى العربية . ونظراً لمقامه هذا ، فقد كان يجب علينا ان نقدمه في التحليل والتدوين على سواه من المقامات لولا ان وجوب ترتيبنا وضع المقامات في هذا الكتاب بحسب درجات ارتكازاتها من اغلظ صوت الى ما فوقه حدّةً على التوالي جعلنا نثبته هنا في صفه ، اي في مركز طبقته الصوتية التي يستقر عليها» (1961، ص107)." }, "sources": [ { "sourceId": "alshawwa_1946", "page": "42" }, { "sourceId": "alhilu_1961", "page": "107" }, { "sourceId": "abbas_1986", "page": "30/36/91" } ], "parameters": { "pitchClassDataType": null, "includeIntervals": false, "includeModulations": false, "includeModulations8vb": false, "includeSuyur": false, "transposeTo": null, "centsTolerance": 5 }, "context": { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2026-08-16T22:20:52.549Z", "startingNotes": { "idNames": [ "ushayran", "yegah", "rast" ], "displayNames": [ "ʿushayrān", "yegāh", "rāst" ] }, "selectedStartingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClassCounts": { "singleOctave": 17, "allOctaves": 68 }, "originalValueType": "fraction", "referenceFrequency": 98 } }, "links": { "self": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah", "detail": "https://diarmaqar.net/api/maqamat/maqam_rast", "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability", "compare": "https://diarmaqar.net/api/maqamat/maqam_rast/compare" }, "pitchData": { "ascending": [ { "pitchClassIndex": 7, "octave": 1, "scaleDegree": "I", "noteName": "rast", "noteNameDisplay": "rāst" }, { "pitchClassIndex": 10, "octave": 1, "scaleDegree": "II", "noteName": "dugah", "noteNameDisplay": "dūgāh" }, { "pitchClassIndex": 12, "octave": 1, "scaleDegree": "III", "noteName": "segah", "noteNameDisplay": "segāh" }, { "pitchClassIndex": 14, "octave": 1, "scaleDegree": "IV", "noteName": "chahargah", "noteNameDisplay": "chahārgāh" }, { "pitchClassIndex": 0, "octave": 2, "scaleDegree": "V", "noteName": "nawa", "noteNameDisplay": "nawā" }, { "pitchClassIndex": 3, "octave": 2, "scaleDegree": "VI", "noteName": "husayni", "noteNameDisplay": "ḥusaynī" }, { "pitchClassIndex": 5, "octave": 2, "scaleDegree": "VII", "noteName": "awj", "noteNameDisplay": "awj" } ], "descending": [ { "pitchClassIndex": 4, "octave": 2, "scaleDegree": "VII", "noteName": "ajam", "noteNameDisplay": "ʿajam" }, { "pitchClassIndex": 3, "octave": 2, "scaleDegree": "VI", "noteName": "husayni", "noteNameDisplay": "ḥusaynī" }, { "pitchClassIndex": 0, "octave": 2, "scaleDegree": "V", "noteName": "nawa", "noteNameDisplay": "nawā" }, { "pitchClassIndex": 14, "octave": 1, "scaleDegree": "IV", "noteName": "chahargah", "noteNameDisplay": "chahārgāh" }, { "pitchClassIndex": 12, "octave": 1, "scaleDegree": "III", "noteName": "segah", "noteNameDisplay": "segāh" }, { "pitchClassIndex": 10, "octave": 1, "scaleDegree": "II", "noteName": "dugah", "noteNameDisplay": "dūgāh" }, { "pitchClassIndex": 7, "octave": 1, "scaleDegree": "I", "noteName": "rast", "noteNameDisplay": "rāst" } ] }, "ajnas": { "ascending": { "rast": [ { "id": "19", "idName": "jins_rast", "displayName": "jins rāst", "isBaseForm": true, "formType": "base" }, { "id": "32", "idName": "jins_yegah_al_rast", "displayName": "jins yegāh al-rāst", "isBaseForm": false, "formType": "transposition" } ], "dugah": [ { "id": "2", "idName": "jins_bayyat", "displayName": "jins bayyāt", "isBaseForm": true, "formType": "base" } ], "segah": [ { "id": "3", "idName": "jins_segah_alhilu", "displayName": "jins segāh (al-Ḥilū)", "isBaseForm": true, "formType": "base" }, { "id": "52", "idName": "jins_mayeh_al_segah", "displayName": "jins māyeh al-segāh", "isBaseForm": false, "formType": "transposition" }, { "id": "16", "idName": "jins_segah", "displayName": "jins segāh", "isBaseForm": true, "formType": "base" }, { "id": "36", "idName": "jins_farahnak_al_segah", "displayName": "jins faraḥnāk al-segāh", "isBaseForm": false, "formType": "transposition" } ], "chahargah": [ { "id": "41", "idName": "jins_mahran_al_chahargah", "displayName": "jins mahrān al-chahārgāh", "isBaseForm": false, "formType": "transposition" } ], "nawa": [ { "id": "19", "idName": "jins_rast_al_nawa", "displayName": "jins rāst al-nawā", "isBaseForm": false, "formType": "transposition" }, { "id": "32", "idName": "jins_yegah_al_nawa", "displayName": "jins yegāh al-nawā", "isBaseForm": false, "formType": "octaveRendering" } ], "husayni": [ { "id": "2", "idName": "jins_bayyat_al_husayni", "displayName": "jins bayyāt al-ḥusaynī", "isBaseForm": false, "formType": "transposition" } ], "awj": [ { "id": "51", "idName": "jins_awj", "displayName": "jins awj", "isBaseForm": true, "formType": "base" }, { "id": "26", "idName": "jins_iraq_al_awj", "displayName": "jins ʿirāq al-awj", "isBaseForm": false, "formType": "octaveRendering" }, { "id": "16", "idName": "jins_segah_al_awj", "displayName": "jins segāh al-awj", "isBaseForm": false, "formType": "transposition" } ] }, "descending": { "ajam": [ { "id": "41", "idName": "jins_mahran_al_ajam", "displayName": "jins mahrān al-ʿajam", "isBaseForm": false, "formType": "octaveRendering" } ], "husayni": [ { "id": "7", "idName": "jins_kurd_al_husayni", "displayName": "jins kurd al-ḥusaynī", "isBaseForm": false, "formType": "transposition" } ], "nawa": [ { "id": "22", "idName": "jins_buselik_alhilu_al_nawa", "displayName": "jins būselīk (al-Ḥilū) al-nawā", "isBaseForm": false, "formType": "transposition" }, { "id": "6", "idName": "jins_nahawand_al_nawa", "displayName": "jins nahāwand al-nawā", "isBaseForm": false, "formType": "transposition" } ], "chahargah": [ { "id": "5", "idName": "jins_ajam_ushayran_al_chahargah", "displayName": "jins ʿajam ʿushayrān al-chahārgāh", "isBaseForm": false, "formType": "transposition" }, { "id": "31", "idName": "jins_chahargah", "displayName": "jins chahārgāh", "isBaseForm": true, "formType": "base" } ], "segah": [ { "id": "3", "idName": "jins_segah_alhilu", "displayName": "jins segāh (al-Ḥilū)", "isBaseForm": true, "formType": "base" }, { "id": "52", "idName": "jins_mayeh_al_segah", "displayName": "jins māyeh al-segāh", "isBaseForm": false, "formType": "transposition" }, { "id": "16", "idName": "jins_segah", "displayName": "jins segāh", "isBaseForm": true, "formType": "base" }, { "id": "36", "idName": "jins_farahnak_al_segah", "displayName": "jins faraḥnāk al-segāh", "isBaseForm": false, "formType": "transposition" } ], "dugah": [ { "id": "2", "idName": "jins_bayyat", "displayName": "jins bayyāt", "isBaseForm": true, "formType": "base" } ], "rast": [ { "id": "19", "idName": "jins_rast", "displayName": "jins rāst", "isBaseForm": true, "formType": "base" }, { "id": "32", "idName": "jins_yegah_al_rast", "displayName": "jins yegāh al-rāst", "isBaseForm": false, "formType": "transposition" } ] } }, "primaryJins": [ { "noteName": "rast", "noteNameDisplay": "rāst", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast", "jinsDisplayName": "jins rāst", "jinsIsBaseForm": true, "jinsFormType": "base" } ], "primaryJinsDescending": [ { "noteName": "rast", "noteNameDisplay": "rāst", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast", "jinsDisplayName": "jins rāst", "jinsIsBaseForm": true, "jinsFormType": "base" } ], "secondaryJins": [ { "noteName": "nawa", "noteNameDisplay": "nawā", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_nawa", "jinsDisplayName": "jins rāst al-nawā", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "secondaryJinsDescending": [ { "noteName": "nawa", "noteNameDisplay": "nawā", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "22", "jinsIdName": "jins_buselik_alhilu_al_nawa", "jinsDisplayName": "jins būselīk (al-Ḥilū) al-nawā", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "tertiaryJins": null, "tertiaryJinsDescending": null, "ghammaz": [ { "noteName": "nawa", "noteNameDisplay": "nawā", "maqamDegree": "V", "intervalFromTonic": { "cents": 701.9550008653875, "fraction": "3/2", "decimalRatio": 1.5 } } ] } ``` ### Check maqām availability across tuning systems {#getMaqamAvailability} ``` GET /maqamat/{idName}/availability ``` Return tuning-system availability for a maqām. * Shows which tuning systems on which starting note names can realize the specified maqām * If `transpositionNoteName` is provided, filters results to show only tuning systems where the maqām can be transposed to that specific note * Validity is computed against each tuning system's note name sets and the maqām's pitch class intervals * Tuning system starting note names are returned as both display values (with diacritics) and URL-safe identifiers **Path Parameters:** * `idName`: URL-safe maqām identifier: A maqām's idName (`maqam_rast`), its numeric id, or the idName of one of its transpositions (`maqam_rast_al_nawa`). A transposed idName works like `transpositionNoteName` for its tonic; giving it together with a different `transpositionNoteName` is a 400. The older closed-up spelling is also accepted. (string) **(required)** * Example: `maqam_bayyat` **Query Parameters:** * `transpositionNoteName` (optional): Filter results to show only tuning systems where the maqām can be transposed to this specific note (URL-safe, diacritics-insensitive). - Type: `string` * Example: `nawa` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat/maqam_bayyat/availability?includeArabic=true" ``` **Response:** Availability information retrieved successfully **Example response — withoutTransposition:** ```json { "maqam": { "id": "1", "idName": "maqam_rast", "displayName": "Maqam Rāst", "version": "2025-10-18T19:41:17.132Z" }, "availability": { "count": 29, "tuningSystems": [ { "tuningSystemId": "ibnsina_1037", "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "tuningSystemStartingNoteNames": [ "ʿushayrān", "yegāh" ], "tuningSystemStartingNoteNamesIds": [ "ushayran", "yegah" ] }, { "tuningSystemId": "alfarabi_950g", "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)", "tuningSystemStartingNoteNames": [ "ʿushayrān", "yegāh" ], "tuningSystemStartingNoteNamesIds": [ "ushayran", "yegah" ] } ] } } ``` ### List transpositions for a maqām {#listMaqamTranspositions} ``` GET /maqamat/{idName}/transpositions ``` Lists distinct transpositions (taswīr) for a maqām within a specific tuning system and starting note. The base form is excluded. Octave renderings of the same modal degree (e.g. qarār dūgāh vs dūgāh vs muḥayyar) are not treated as distinct taswīr. If there are no distinct taswīr for this tuning-system + starting-note combination, this endpoint returns `422` with an `{ error, hint }` payload (it does not return a 200 with an empty list). **Path Parameters:** * `idName`: URL-safe maqām identifier: A maqām's idName (`maqam_rast`) or its numeric id. This route lists every transposition of the maqām, so the idName of a single transposition (`maqam_rast_al_nawa`) is rejected with a 400 that names the base idName to use. (string) **(required)** * Example: `maqam_rast` **Query Parameters:** * `tuningSystem` **(required)**: Tuning system identifier (e.g., 'ibnsina\_1037', 'alfarabi\_950g', 'meshshaqa\_1899') - Type: `string` * Example: `ibnsina_1037` * `startingNote` **(required)**: Tuning system starting note name (URL-safe, diacritics-insensitive). - Type: `string` * Example: `yegah` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat/maqam_rast/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=true" ``` **Response:** Transpositions retrieved successfully **Example response:** ```json { "maqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst", "version": "2026-08-11T19:43:52.080Z", "isBaseForm": true, "formType": "base" }, "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2026-08-16T22:20:52.549Z", "numberOfPitchClassesSingleOctave": 17 }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "transpositions": { "total": 3, "options": { "idNames": [ "qarar_chahargah", "chahargah", "mahuran" ], "displayNames": [ "qarār chahārgāh", "chahārgāh", "māhūrān" ] }, "detailed": [ { "idName": "maqam_rast_al_qarar_chahargah", "displayName": "maqām rāst al-qarār chahārgāh", "tonic": { "idName": "qarar_chahargah", "displayName": "qarār chahārgāh" }, "pitchClass": { "pitchClassIndex": 14, "octave": 0 }, "isBaseForm": false, "formType": "transposition", "primaryJins": [ { "noteName": "qarar_chahargah", "noteNameDisplay": "qarār chahārgāh", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_qarar_chahargah", "jinsDisplayName": "jins rāst al-qarār chahārgāh", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "secondaryJins": [ { "noteName": "rast", "noteNameDisplay": "rāst", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast", "jinsDisplayName": "jins rāst", "jinsIsBaseForm": true, "jinsFormType": "base" } ], "tertiaryJins": null, "primaryJinsDescending": [ { "noteName": "qarar_chahargah", "noteNameDisplay": "qarār chahārgāh", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_qarar_chahargah", "jinsDisplayName": "jins rāst al-qarār chahārgāh", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "secondaryJinsDescending": [ { "noteName": "rast", "noteNameDisplay": "rāst", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "6", "jinsIdName": "jins_nahawand", "jinsDisplayName": "jins nahāwand", "jinsIsBaseForm": true, "jinsFormType": "base" } ], "tertiaryJinsDescending": null, "ghammaz": [ { "noteName": "rast", "noteNameDisplay": "rāst", "maqamDegree": "V", "intervalFromTonic": { "cents": 701.9550008653874, "fraction": "3/2", "decimalRatio": 1.5 } } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_chahargah" } }, { "idName": "maqam_rast_al_chahargah", "displayName": "maqām rāst al-chahārgāh", "tonic": { "idName": "chahargah", "displayName": "chahārgāh" }, "pitchClass": { "pitchClassIndex": 14, "octave": 1 }, "isBaseForm": false, "formType": "transposition", "primaryJins": [ { "noteName": "chahargah", "noteNameDisplay": "chahārgāh", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_chahargah", "jinsDisplayName": "jins rāst al-chahārgāh", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "secondaryJins": [ { "noteName": "kurdan", "noteNameDisplay": "kurdān", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_kurdan", "jinsDisplayName": "jins rāst al-kurdān", "jinsIsBaseForm": false, "jinsFormType": "octaveRendering" } ], "tertiaryJins": null, "primaryJinsDescending": [ { "noteName": "chahargah", "noteNameDisplay": "chahārgāh", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_chahargah", "jinsDisplayName": "jins rāst al-chahārgāh", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "secondaryJinsDescending": [ { "noteName": "kurdan", "noteNameDisplay": "kurdān", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "6", "jinsIdName": "jins_nahawand_al_kurdan", "jinsDisplayName": "jins nahāwand al-kurdān", "jinsIsBaseForm": false, "jinsFormType": "octaveRendering" } ], "tertiaryJinsDescending": null, "ghammaz": [ { "noteName": "kurdan", "noteNameDisplay": "kurdān", "maqamDegree": "V", "intervalFromTonic": { "cents": 701.9550008653874, "fraction": "3/2", "decimalRatio": 1.5 } } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=chahargah" } }, { "idName": "maqam_rast_al_mahuran", "displayName": "maqām rāst al-māhūrān", "tonic": { "idName": "mahuran", "displayName": "māhūrān" }, "pitchClass": { "pitchClassIndex": 14, "octave": 2 }, "isBaseForm": false, "formType": "transposition", "primaryJins": [ { "noteName": "mahuran", "noteNameDisplay": "māhūrān", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_mahuran", "jinsDisplayName": "jins rāst al-māhūrān", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "secondaryJins": [ { "noteName": "jawab_kurdan", "noteNameDisplay": "jawāb kurdān", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_jawab_kurdan", "jinsDisplayName": "jins rāst al-jawāb kurdān", "jinsIsBaseForm": false, "jinsFormType": "octaveRendering" } ], "tertiaryJins": null, "primaryJinsDescending": [ { "noteName": "mahuran", "noteNameDisplay": "māhūrān", "maqamDegree": "I", "jinsStatus": "matched", "jinsId": "19", "jinsIdName": "jins_rast_al_mahuran", "jinsDisplayName": "jins rāst al-māhūrān", "jinsIsBaseForm": false, "jinsFormType": "transposition" } ], "secondaryJinsDescending": [ { "noteName": "jawab_kurdan", "noteNameDisplay": "jawāb kurdān", "maqamDegree": "V", "jinsStatus": "matched", "jinsId": "6", "jinsIdName": "jins_nahawand_al_jawab_kurdan", "jinsDisplayName": "jins nahāwand al-jawāb kurdān", "jinsIsBaseForm": false, "jinsFormType": "octaveRendering" } ], "tertiaryJinsDescending": null, "ghammaz": [ { "noteName": "jawab_kurdan", "noteNameDisplay": "jawāb kurdān", "maqamDegree": "V", "intervalFromTonic": { "cents": 701.9550008653873, "fraction": "3/2", "decimalRatio": 1.5 } } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=mahuran" } } ] }, "links": { "self": "https://diarmaqar.net/api/maqamat/maqam_rast/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah", "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability", "detail": "https://diarmaqar.net/api/maqamat/maqam_rast" } } ``` ### Compare maqām data across multiple tuning systems and starting notes {#compareMaqam} ``` GET /maqamat/{idName}/compare ``` Compare comprehensive maqām data across multiple tuning systems **and** multiple starting notes in a single request. Given `N` tuning systems and `M` starting notes, the response contains the Cartesian product of `N × M` comparison cells in user-supplied order (outer loop = `tuningSystems`, inner loop = `startingNotes`). Each successful cell includes ascending/descending pitch class sequences, optional interval data, ajnās mapping, family classification, and transposition details. When a requested starting note is not available in a given tuning system the cell carries an informational `note` field (not `error`) together with `validStartingNotes`. When a hard failure occurs (tuning system not found, maqām not realizable in this configuration, or a `transposeTo` target that is unreachable) the cell carries an `error` field. The overall response is always HTTP 200 — per-cell outcomes do not affect the HTTP status. The following invariant always holds: ``` successfulComparisons + unavailableStartingNotes + failedComparisons === totalComparisons ``` This endpoint is ideal for comparative musicological analysis across historical tuning systems and/or multiple modal transpositions. **Path Parameters:** * `idName`: URL-safe maqām identifier: A maqām's idName (`maqam_rast`), its numeric id, or the idName of one of its transpositions (`maqam_rast_al_qarar_chahargah`). A transposed idName works like adding `transposeTo` for its tonic; giving it together with a different `transposeTo` is a 400. The older closed-up spelling (`maqam_rast_alqarar_chahargah`) is also accepted. (string) **(required)** * Example: `maqam_bayyat` **Query Parameters:** * `tuningSystems` **(required)**: Comma-separated list of tuning system IDs. product of these tuning systems with the requested `startingNotes` (outer loop = `tuningSystems`, inner loop = `startingNotes`). Use `all` to include every tuning system in the archive (cannot be combined with explicit IDs). * Type: `string` * Example: `alsabbagh_1954,ibnsina_1037` * `startingNotes` **(required)**: Comma-separated list of starting note names (URL-safe, diacritics-insensitive). response contains `N × M` cells for `N` tuning systems × `M` starting notes, in user-supplied order. If a starting note is not available in a given tuning system that cell carries an informational `note` field (with a `validStartingNotes` namespace) rather than pitch data. * Type: `string` * Example: `rast,yegah,ushayran` * `pitchClassDataType` (optional): Output format for pitch class data. Defaults to `all` when omitted. - Type: `string` - Valid values: `all`, `englishName`, `solfege`, `fraction`, `cents`, ... (14 total) - Default: `all` * Example: `cents` * `includeIntervals` (optional): Whether to include interval data between adjacent pitch classes on each cell. Defaults to `"false"` when omitted.. Defaults to `"false"` when omitted. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `transposeTo` (optional): Transpose every successful cell to the given tonic note (applies to every cell in the Cartesian product). Cartesian product). If the requested target is not reachable in a given cell the cell carries an `error` plus an `availableTranspositions` list. * Type: `string` * Example: `nawa` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with `Ar` suffix (e.g., `displayNameAr`, `noteNameDisplayAr`) * Note names, maqām names, and jins names get Arabic versions in `*Ar` fields * Tuning system display names get Arabic versions in `displayNameAr` if available * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat/maqam_bayyat/compare?tuningSystems=alsabbagh_1954,ibnsina_1037&startingNotes=rast,yegah,ushayran&includeArabic=true" ``` **Response:** Comparison data retrieved successfully. Note that the response is always HTTP 200 regardless of per-cell outcomes; individual failures (missing starting note, tuning system not found, maqām not realizable, unreachable transposeTo) are reported on the respective cell via `note` or `error` fields. The counters `successfulComparisons + unavailableStartingNotes + failedComparisons` always equal `totalComparisons`. **Example response — twoTuningSystems:** ```json { "maqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst", "version": "2025-12-10T17:03:34.565Z" }, "comparisons": { "count": 1, "totalComparisons": 1, "successfulComparisons": 1, "unavailableStartingNotes": 0, "failedComparisons": 0, "data": [ { "tuningSystem": { "id": "alsabbagh_1954", "idName": "alsabbagh_1954", "displayName": "al-Ṣabbāgh (1954) Contemporary Arabic Tuning 24-Tone", "version": "2025-10-18T19:42:23.643Z" }, "startingNote": { "idName": "rast", "displayName": "rāst" }, "maqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst", "version": "2025-12-10T17:03:34.565Z", "maqamFamilyId": "rast", "maqamFamilyDisplayName": "rāst" }, "tonic": { "idName": "rast", "displayName": "rāst" }, "stats": { "tuningSystem": { "numberOfPitchClassesSingleOctave": 24, "referenceFrequency": 130.665 }, "maqam": { "numberOfPitchClasses": 7, "isOctaveRepeating": true } }, "availableTranspositions": [], "pitchData": { "ascending": [ { "pitchClassIndex": 0, "octave": 1, "scaleDegree": "I", "noteName": "rast", "noteNameDisplay": "rāst", "cents": 0 }, { "pitchClassIndex": 4, "octave": 1, "scaleDegree": "II", "noteName": "dugah", "noteNameDisplay": "dūgāh", "cents": 203.91000173077484 } ], "descending": [ { "pitchClassIndex": 20, "octave": 1, "scaleDegree": "VII", "noteName": "ajam", "noteNameDisplay": "ʿajam", "cents": 1019.5580263750745 }, { "pitchClassIndex": 18, "octave": 1, "scaleDegree": "VI", "noteName": "husayni", "noteNameDisplay": "ḥusaynī", "cents": 905.8650025961623 } ] }, "ajnas": { "ascending": { "rast": [ { "id": "19", "idName": "jins_rast", "displayName": "jins rāst" } ], "dugah": [ { "id": "2", "idName": "jins_bayyat", "displayName": "jins bayyāt" } ], "chahargah": [] }, "descending": { "ajam": [], "husayni": [ { "id": "30", "idName": "jins_kurd_ushayran", "displayName": "jins kurd ʿushayrān" } ] } }, "intervals": { "ascending": [ { "cents": 203.91000173077484 }, { "cents": 152.95309101871007 } ], "descending": [ { "cents": 113.69302377891222 }, { "cents": 203.91000173077487 } ] }, "parameters": { "pitchClassDataType": "cents", "includeIntervals": true, "transposeTo": null }, "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_rast?tuningSystem=alsabbagh_1954&startingNote=r%C4%81st&pitchClassDataType=cents&includeIntervals=true", "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability" } } ] }, "parameters": { "tuningSystems": { "idNames": [ "alsabbagh_1954" ], "displayNames": [ "alsabbagh_1954" ] }, "startingNotes": { "idNames": [ "rast" ], "displayNames": [ "rast" ] }, "pitchClassDataType": "cents", "includeIntervals": true, "transposeTo": null }, "links": { "self": "https://diarmaqar.net/api/maqamat/maqam_rast/compare?tuningSystems=alsabbagh_1954&startingNotes=rast&pitchClassDataType=cents", "detail": "https://diarmaqar.net/api/maqamat/maqam_rast", "availability": "https://diarmaqar.net/api/maqamat/maqam_rast/availability" } } ``` ### Classify maqāmāt by 12-pitch-class sets {#classifyMaqamat12PitchClassSets} ``` GET /maqamat/classification/12-pitch-class-sets ``` Groups maqāmāt according to sets of 12 pitch classes suitable for MIDI keyboard tuning and Scala file export. Each set is created by merging pitch classes from the specified tuning system with alkindi\_874 filler pitch classes, based on matching IPN reference note names. **Critical Design Principles:** * **Octave Alignment**: Both the maqām tuning system and alkindi\_874 use the same `startingNote` to ensure octaves align correctly * **Chromatic Order**: Each set contains exactly 12 pitch classes ordered chromatically starting from the maqām's tonic (e.g., C, C#, D, D#... for Rāst) * **Arabic Musicological Logic**: IPN references follow Arabic maqām theory: a note's quarter-tone or comma spelling names the note it is a variant of (E-b is a variant of E), not the nearest 12-EDO semitone * **Direct Tuning System Values**: All cent values come directly from tuning systems without post-processing or calculation **The Algorithm:** 1. Loads pitch classes from both the specified tuning system and alkindi\_874 using the same `startingNote` 2. For each maqām transposition: * Extracts IPN reference note names from ascending and descending sequences * Puts every degree of the maqām on its key; each key the maqām leaves empty takes al-Kindī's (alkindi\_874) pitch on that key. Nothing else enters a set: maqām nayrūz's set holds tīk ḥiṣār on G#, its own degree; the set holding maqām lāmī has ḥiṣār there. * Places the tonic in the first octave above `startingNote` (0 to 1200 cents) and each following key in the lowest octave above the key before, so every set ascends from its tonic within both tuning systems. A set has no register: one made from qarār dūgāh is listed from dūgāh. 3. Groups compatible maqāmāt together: a transposition joins a set only when every pitch of its ascending and descending sequences is in the set 4. Names each group after one of its members (see Set names) and lists the 12 pitch classes from that member's tonic **Set names:** A set is named after one of its members, chosen by one rule. The name never changes which maqāmāt are in the set or which 12 pitches it holds. 1. A set that holds one or more base forms is named after the base form whose maqām has the lowest id. Maqām lāmī (allami\_2022 from ʿushayrān) is in the maqām ḥijāz kār kurd set: that set holds the base forms of ḥijāz kār kurd (id 4), lāmī (id 9) and others. 2. A set with no base form is named after its commonest family (the jins on the first degree of each member's maqām, as `/maqamat/families` reads it; "no jins" is not counted). Of that family, the maqām with the lowest id names the set. Two families with the same count: the one whose lowest maqām id is lower. When every member is "no jins", the lowest maqām id of all names the set. 3. When that maqām is in the set more than once, the form whose tonic has no qarār or jawāb prefix is used, else any form; between several, the lowest tonic in pitch. The set ID is the chosen member's idName plus `_set`, and `sourceMaqam` and `sourceTransposition` are that member. **Compatibility:** * A 12-pitch-class set has one pitch class per key. Each pitch class of a maqām takes the key of its own note letter, or a neighbouring key when that one is taken. * A maqām transposition is incompatible when two different pitch classes would need the same key and the keys next to it are already taken. For example, maqām faraḥnāk (al-Ḥilū) on qarār segāh needs both ʿirāq (B-b2) and nīm kawasht (B-2) on the B key. * Each incompatible transposition says which keys clash, which notes need them, and gives the same in one plain sentence (`explanation`). * The number of incompatible transpositions is always in `statistics.incompatibleMaqamatCount`; the full list is included on request. * A maqām transposition is compatible with a set when every one of its pitches, octave ignored, is within `centsTolerance` of one of the set's 12 pitches. Only the pitch is compared, not the key it sits on. Maqām chahārgāh (al-Ṣabbāgh) needs nīm ʿajam (60.41 cents above the octave in allami\_2022), so it is not in a set that has ʿajam (90.22) instead. * Compatible maqāmāt can be performed entirely within a single 12-pitch-class set **Output Format:** * Pitch classes ordered chromatically (C, C#, D, D#, E, F, F#, G, G#, A, A#, B) * Starting from the tonic of the member the set is named after, in the first octave above `startingNote` (default), OR from IPN "C" at or below that tonic (if `startSetFromC=true`) * Relative cents from 0 (reference note) to ~1050-1200 (octave) * `maqamTonic` field indicates the actual maqām tonic position and note name * Suitable for MIDI keyboard tuning and Scala (.scl) file generation **Filtering Options:** * Use `setId` to retrieve a specific set and its compatible maqāmāt * Use `maqamId` to find all sets containing a specific maqām, together with its transpositions that fit no set. A maqām with no transposition that fits still returns 200, with `compatible: false`, an explanation and an empty `sets` list. Only an id that names no maqām or transposition returns 404. **Query Parameters:** * `tuningSystem` **(required)**: Tuning system ID for maqāmāt - Type: `string` * Example: `cairocongresstuningcommittee_1929` * `startingNote` **(required)**: Starting note for both the maqām tuning system and alkindi\_874. IMPORTANT: Both tuning systems must use the same starting note to ensure octaves align correctly and pitch classes can be properly selected from matching octaves. IMPORTANT: Both tuning systems must use the same starting note to ensure octaves align correctly and pitch classes can be properly selected from matching octaves. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh * Type: `string` * Example: `yegah` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` * `includeIncompatible` (optional): Include the full list of maqām transpositions that cannot form a 12-pitch-class set, with the clashing keys and notes of each (their number is always in the statistics). - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `startSetFromC` (optional): Start pitch class set from IPN reference "C" (degree 0) instead of from the maqām's tonic. When `true`, the set is reordered to start from C at 0.00 cents (relative), making it directly compatible with Scala (.scl) file format which maps degree 0 to middle C by default. When `true`, the set is reordered to start from C at 0.00 cents (relative), making it directly compatible with Scala (.scl) file format which maps degree 0 to middle C by default. **Technical Implementation:** 1. **Octave Selection**: For maqāmāt starting mid-octave (e.g., D), pitch classes before the tonic in chromatic order (C, C#) are taken from octave 1, while those at or after the tonic use their original octaves 2. **Array Rotation**: The 12 pitch classes are rotated to place C first 3. **Relative Cents**: Calculated from C (0.00 cents), with octave wrap-around handling (negative values + 1200) 4. **Note Names**: Arabic note names follow the NoteName model's octave conventions (e.g., C octave 1 = rāst, C octave 2 = kurdān) 5. **Tonic Tracking**: The `maqamTonic` field indicates the actual maqām tonic's IPN, note names, and position in the reordered set **Use Cases:** * `false` (default): For understanding maqām structure starting from its tonic * `true`: For Scala .scl export (no .kbm file needed) or MIDI keyboard mapping where C = degree 0 **Example:** * Maqām ḥijāz (tonic D/dūgāh at 702.13 cents): - Default mode: D at position 0 (0.00 cents relative) - Scala mode: C (rāst, 498.04 cents) at position 0 (0.00 cents relative), D at position 2 (204.08 cents relative) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `pitchClassDataType` (optional): Controls which pitch class data fields are returned in the response. * `all`: Returns all available pitch class data fields * `englishName`: English note name with octave (e.g., "D2", "E-b3") * `fraction`: Frequency ratio as a fraction string * `cents`: Absolute cents value from the tuning system * `decimalRatio`: Frequency ratio as decimal number * `stringLength`: String length for oud/qanun (if available) * `frequency`: Frequency in Hz * `abjadName`: Arabic abjad notation (if available) * `fretDivision`: Fret position for oud (if available) * `midiNoteNumber`: MIDI note number as decimal * `midiNoteDeviation`: MIDI note with cents deviation string * `centsDeviation`: Cents deviation from 12-EDO * `referenceNoteName`: IPN reference note name * `relativeCents`: Cents relative to the first pitch class (0.00 for tonic or C) **Default Behavior (parameter omitted):** * Returns minimal fields: `ipnReferenceNoteName`, `noteName`, `relativeCents`, `octave` **Example:** * `?pitchClassDataType=cents` returns only IPN, note name, and cents values * `?pitchClassDataType=all` returns all available data fields * Type: `string` - Valid values: `all`, `abjadName`, `englishName`, `solfege`, `fraction`, ... (15 total) * Example: `cents` * `setId` (optional): Filter by specific set ID to retrieve that set and its compatible maqāmāt (e.g., 'maqam\_rast\_set'). - Type: `string` * Example: `maqam_rast_set` * `maqamId` (optional): Filter by maqām to find all sets containing it and list its transpositions that fit no set: a maqām idName (e.g., 'maqam\_rast'), its numeric id, or one transposition's idName (e.g., 'maqam\_rast\_al\_qarar\_chahargah'; the older closed-up spelling 'maqam\_rast\_alqarar\_chahargah' is also accepted). - Type: `string` * Example: `maqam_rast` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat/classification/12-pitch-class-sets?tuningSystem=cairocongresstuningcommittee_1929&startingNote=yegah&includeArabic=true" ``` **Response:** Classification results with sets and compatible maqāmāt; with a maqām filter, also whether the maqām fits any set and which of its transpositions do not **Example response — default:** ```json { "summary": [ { "setIdName": "maqam_rast_set", "setDisplayName": "maqām rāst set", "compatibleMaqamat": [ { "maqamIdName": "maqam_rast", "maqamDisplayName": "maqām rāst", "isTransposed": false, "isBaseForm": true } ] } ], "statistics": { "totalSets": 1, "sets": [ { "setIdName": "maqam_rast_set", "setDisplayName": "maqām rāst set", "compatibleMaqamatCount": 1 } ], "totalCompatibleMaqamat": 1, "incompatibleMaqamatCount": 0 }, "sets": [ { "id": "maqam_rast_set", "setIdName": "maqam_rast_set", "setDisplayName": "maqām rāst set", "sourceMaqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst" }, "sourceTransposition": { "idName": "maqam_rast", "displayName": "maqām rāst", "isTransposed": false, "isBaseForm": true }, "pitchClassSet": [ { "ipnReferenceNoteName": "C", "noteName": "rāst", "cents": 0, "fraction": "1/1", "decimalRatio": 1, "frequency": 130.665, "octave": 1 } ], "compatibleMaqamat": [ { "maqamIdName": "maqam_rast", "maqamDisplayName": "maqām rāst", "isTransposed": false, "isBaseForm": true } ], "compatibleMaqamatCount": 1 } ], "totalSets": 1, "totalCompatibleMaqamat": 1, "incompatibleMaqamat": [], "incompatibleMaqamatCount": 0, "parameters": { "tuningSystem": { "id": "cairocongresstuningcommittee_1929", "idName": "cairocongresstuningcommittee-1929", "displayName": "Cairo Congress Tuning Committee (1929)" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "alKindiTuningSystem": { "id": "alkindi_874", "idName": "al-kindi-874", "displayName": "al-Kindī (874)" }, "alKindiStartingNote": { "idName": "ushayran", "displayName": "ʿushayrān" }, "centsTolerance": 5, "startSetFromC": false } } ``` ### Classify maqāmāt by maqam-based pitch class sets {#classifyMaqamatByMaqamPitchClassSets} ``` GET /maqamat/classification/maqam-pitch-class-sets ``` Groups maqāmāt according to maqam-based pitch class sets. Each set contains all pitch classes from a single maqām transposition (union of ascending and descending), and identifies which other maqāmāt can be performed using only those pitch classes. **Musicological Purpose:** Answers the question: "Which maqāmāt can be performed using only the pitch classes of maqām X?" For example, maqām rāst on rāst includes pitch classes that can perform maqām bayyāt on dūgāh and maqām segāh on segāh. **Key Differences from 12-Pitch-Class-Sets:** * **No Chromatic Base**: Does not merge with alkindi\_874 or chromatic filler pitch classes * **Variable Set Sizes**: Sets can contain any number of pitch classes (7, 8, 10, etc.), not fixed at 12 * **Octave-Equivalent Matching**: Pitch classes in different octaves treated as equivalent (C in octave 1 = C in octave 2) * **Single Tuning System**: Uses only the specified tuning system (simpler than 12-pitch-class-sets) * **Subset Matching**: Compatible maqāmāt must use subset of source maqam's pitch classes **Critical Design Principles:** * **Octave Equivalence**: IPN references are compared octave-normalized (C at any octave = "C") * **Union of Melodic Paths**: Includes all pitch classes from both ascending AND descending sequences * **Exact Matching**: All pitch classes from a compatible maqām must exist in the source set (within tolerance) * **Direct Values**: All cent values come directly from tuning system without calculation * **Base-form Priority**: Base forms create canonical sets first, then transpositions **The Algorithm:** 1. For each maqām form (base form first, then transpositions): * Extracts all unique pitch classes from ascending + descending sequences * Groups by IPN reference (octave-equivalent) * Validates no duplicate IPN references with different cents values * Creates a maqam-based pitch class set 2. For each set, finds compatible maqāmāt: * Checks if all pitch classes needed by candidate maqām exist in source set * Compares cents values within tolerance (octave-normalized) * Marks candidate as compatible if all pitch classes match 3. Groups compatible maqāmāt together 4. Names each group after one of its members (see Set names) **Set names:** A set is named by the same rule as on `/maqamat/classification/12-pitch-class-sets`: after its lowest-id base form when it holds one, else after the lowest-id maqām of its commonest family, preferring a tonic with no qarār or jawāb prefix, then the lowest tonic. The set's pitch classes are those of the transposition that made it. The maqām the set is named after is a member, so its pitch classes are all in the set, but the set can hold more. The set ID is the chosen member's idName plus `_set`. **Compatibility:** * Maqāmāt with duplicate IPN references (same IPN with different cents values when octave-normalized) are marked as incompatible * Compatible maqāmāt can be performed entirely using the pitch classes of the source maqām * **Minimum Set Size**: Only sets with 2 or more maqāmāt are returned (source + at least one compatible). One maqām on one tonic key counts once however many octaves it appears in, so a set holding only maqām rāst on rāst and on kurdān is not returned. * Every member is listed, octave equivalents included: maqām bayyāt on yegāh, on nawā and on saham/ramal tūtī are three entries of one set **Output Format:** * Sets ordered by number of compatible maqāmāt (descending) * Each set includes: source maqām, all pitch classes (in ascending cents order), compatible maqāmāt, pitch class count * Pitch classes include: English name, note name, cents, frequency, fraction, etc. **Filtering Options:** * Use `setId` to retrieve a specific set and its compatible maqāmāt * Use `maqamId` to find all sets containing a specific maqām **Query Parameters:** * `tuningSystem` **(required)**: Tuning system ID for all maqāmāt - Type: `string` * Example: `cairocongresstuningcommittee_1929` * `startingNote` **(required)**: Starting note for the tuning system. - Type: `string` * Example: `yegah` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` * `includeIncompatible` (optional): Include maqāmāt that cannot form valid maqam-based pitch class sets - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includePitchClassData` (optional): Include pitch class data in the response (default: false). When false: Omits pitch class data, returning only set metadata and compatible maqamat * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `setId` (optional): Filter by specific set ID to retrieve that set and its compatible maqāmāt (e.g., 'maqam\_rast\_set'). - Type: `string` * Example: `maqam_rast_set` * `maqamId` (optional): Filter by maqām to find all sets containing it: a maqām idName (e.g., 'maqam\_rast'), its numeric id, or one transposition's idName (e.g., 'maqam\_rast\_al\_qarar\_chahargah'; the older closed-up spelling 'maqam\_rast\_alqarar\_chahargah' is also accepted). - Type: `string` * Example: `maqam_rast` **Example:** ```bash curl "https://diarmaqar.net/api/maqamat/classification/maqam-pitch-class-sets?tuningSystem=cairocongresstuningcommittee_1929&startingNote=yegah&includeArabic=true" ``` **Response:** Classification results with maqam-based pitch class sets and compatible maqāmāt **Example response — default:** ```json { "statistics": { "totalSets": 1, "totalCompatibleMaqamat": 3, "incompatibleMaqamatCount": 0, "totalProcessed": 3 }, "sets": [ { "setIdName": "maqam_rast_set", "setDisplayName": "maqām rāst set", "compatibleMaqamatCount": 3, "sourceMaqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst" }, "pitchClassSet": [ { "englishName": "C3", "noteName": "rāst", "cents": 0, "fraction": "1/1", "decimalRatio": 1, "frequency": 130.665, "octave": 1 }, { "englishName": "D3", "noteName": "dūgāh", "cents": 203.91, "fraction": "9/8", "decimalRatio": 1.125, "frequency": 146.998, "octave": 1 }, { "englishName": "E3", "noteName": "segāh", "cents": 407.82, "fraction": "81/64", "decimalRatio": 1.266, "frequency": 165.361, "octave": 1 } ], "pitchClassCount": 7, "compatibleMaqamat": [ { "maqamIdName": "maqam_rast", "maqamDisplayName": "maqām rāst", "isTransposed": false, "isBaseForm": true, "tonic": { "ipnReferenceNoteName": "C", "noteNameIdName": "rast", "noteNameDisplayName": "rāst" } }, { "maqamIdName": "maqam_bayyat_dugah", "maqamDisplayName": "maqām bayyāt (dūgāh)", "isTransposed": true, "isBaseForm": false, "tonic": { "ipnReferenceNoteName": "D", "noteNameIdName": "dugah", "noteNameDisplayName": "dūgāh" } }, { "maqamIdName": "maqam_segah_segah", "maqamDisplayName": "maqām segāh (segāh)", "isTransposed": true, "isBaseForm": false, "tonic": { "ipnReferenceNoteName": "E", "noteNameIdName": "segah", "noteNameDisplayName": "segāh" } } ] } ], "parameters": { "tuningSystem": { "id": "cairocongresstuningcommittee_1929", "idName": "cairocongresstuningcommittee-1929", "displayName": "Cairo Congress Tuning Committee (1929)" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "centsTolerance": 5 } } ``` *** ## Ajnās Documented tri/tetra/penta-chords with historical source attribution. ### List all ajnās {#listAjnas} ``` GET /ajnas ``` Return all ajnās (singular: jins) with metadata. * Includes URL-safe identifiers, display names, and structural information * Structural information includes note sequences needed for maqām construction and analysis * Optional bibliographic source references (sourceId and page) when `includeSources=true` **Query Parameters:** * `filterByTonic` (optional): Filter by jins tonic/first note (URL-safe, case-insensitive, diacritics-insensitive) - Type: `string` * Example: `rast` * `sortBy` (optional): Sort order for results. including empty string) return HTTP 400. * Type: `string` - Valid values: `alphabetical`, `tonic` - Default: `alphabetical` * Example: `alphabetical` - Sort alphabetically by display name (default) * Example: `tonic` - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak * `includeSources` (optional): Include bibliographic source references (sourceId and page) for each jins - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/ajnas?includeSources=true&includeArabic=true" ``` **Response:** List of ajnās retrieved successfully **Example response:** ```json { "count": 38, "data": [ { "jins": { "id": "42", "idName": "jins_ajam_sultani", "displayName": "jins ʿajam sulṭānī", "version": "2026-07-20T09:57:37.540Z" }, "tonic": { "idName": "ajam_ushayran", "displayName": "ʿajam ʿushayrān" }, "stats": { "numberOfPitchClasses": 4, "availableInTuningSystems": 26 }, "availability": { "tuningSystems": [ { "tuningSystem": { "id": "ronzevalle_1904", "idName": "ronzevalle_1904", "displayName": "Ronzevalle (1904) Modernist Arabic Tuning", "version": "2026-08-05T13:44:18.170Z" }, "startingNotes": { "idNames": [ "ushayran", "yegah" ], "displayNames": [ "ʿushayrān", "yegāh" ] } }, { "tuningSystem": { "id": "alkindi_874", "idName": "alkindi_874", "displayName": "al-Kindī (874) 12-Tone", "version": "2026-08-05T14:18:59.205Z" }, "startingNotes": { "idNames": [ "ushayran", "yegah", "rast" ], "displayNames": [ "ʿushayrān", "yegāh", "rāst" ] } } ] }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_ajam_sultani" } } ] } ``` ### Get detailed jins data {#getJins} ``` GET /ajnas/{idName} ``` Retrieve comprehensive data for a specific jins on its conventional or a transposed tonic, in a specific tuning system on a specific starting note name. Returns: * Comprehensive pitch class data in the requested tuning system and starting note name * Optional includeIntervals data, transposition to different tonics, and tuning-system-specific modulations (including lower octave) Parameter Discovery: * Use options=true to discover valid values for all parameters including dynamically calculated transposition options * Especially useful for finding valid tuning system starting notes and transposition tonics for a specific jins Important: * When options=true, the endpoint returns parameter discovery metadata instead of jins data * This mode is mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, pitch class data type, includeIntervals) * If data-returning parameters are provided with options=true, the API returns a 400 Bad Request error with details about conflicting parameters Requirements: * Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes * These are fundamental to all pitch class calculations **Path Parameters:** * `idName`: URL-safe jins identifier: A jins's idName (`jins_segah`), its numeric id, or the idName of one of its transpositions (`jins_segah_al_tik_hisar`). A transposed idName works like adding `transposeTo` for its tonic; giving it together with a different `transposeTo` is a 400. The older closed-up spelling (`jins_segah_altik_hisar`) is also accepted. (string) **(required)** * Example: `jins_rast` - Jins Rāst (representative example - with zalzalian intervals) * Example: `jins_kurd` - Jins Kurd (representative example - without zalzalian intervals) * Example: `jins_bayyat` - Jins Bayyāt (representative example - with zalzalian intervals) **Query Parameters:** * `tuningSystem` **(required)**: Tuning system identifier (e.g., 'ibnsina\_1037', 'alfarabi\_950g', 'meshshaqa\_1899') - Type: `string` * Example: `ibnsina_1037` - Ibn Sīnā (1037) - 7-Fret Oud 17-Tone (representative example) * Example: `alfarabi_950g` - al-Fārābī (950g) - First Oud Tuning 27-Tone (representative example) * `startingNote` **(required)**: Tuning system starting note name (URL-safe, diacritics-insensitive). * Different starting notes represent different theoretical frameworks within the same tuning system * Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh * Type: `string` * Example: `yegah` - yegāh (for IbnSina, Meshshaqa) * Example: `ushayran` - ʿushayrān (for al-Farabi, al-Kindi) * `options` (optional): When true, returns available parameter options instead of jins data. * Tuning system is required for all requests; a starting note is required for data retrieval and optional in discovery mode (options=true), where omitting it returns the tuning system's valid starting notes * These are fundamental to all pitch class calculations and calculate valid starting note options and transposition tonics * Mutually exclusive with data-returning parameters (transpose to, include modulations, include lower octave modulations, pitch class data type, intervals) * Transposition options are dynamically calculated based on the specific jins, tuning system, and starting note combination * Only tonics where the jins can be validly transposed (preserving interval pattern) are included, not all possible pitch classes * If data-returning parameters are provided, returns 400 Bad Request error with details about conflicting parameters * Type: `string` - Valid values: `true`, `false` - Default: `false` * `pitchClassDataType` **(required)**: Specifies which pitch class data type to return for each pitch class. * When set to `all`, returns the full set of pitch class fields (englishName, solfege, abjadName, fraction, cents, decimalRatio, stringLength, frequency, fretDivision, midiNoteDecimal, midiNotePlusCentsDeviation, centsDeviation, ipnReferenceNoteName) plus the always-included identifiers (pitchClassIndex, octave, scaleDegree, noteName, noteNameDisplay, and noteNameDisplayAr if includeArabic is enabled). * When set to a specific format, returns only that field plus the always-included identifiers. * Empty string and unrecognised values return HTTP 400 with a hint listing valid options. * In discovery mode (when options=true), this parameter remains optional. Passing any value other than `cents` in discovery mode is treated as a conflict (400). * Type: `string` - Valid values: `all`, `abjadName`, `englishName`, `solfege`, `fraction`, ... (14 total) - Default: `all` * Example: `cents` * `transposeTo` (optional): Transpose the jins to a new tonic by preserving the interval patterns (URL-safe, diacritics-insensitive). * To see all valid transposition options, request available parameter options instead of jins data * Type: `string` * `includeIntervals` (optional): Include interval data between jins degrees - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&includeArabic=true" ``` **Response:** Jins data retrieved successfully. * When options is true, the response structure differs and returns available parameter options instead of jins data * In that case, transposition options contain only valid transposition tonics for this specific jins, tuning system, and starting note combination **Example response — basic:** ```json { "jins": { "id": "5", "idName": "jins_kurd", "displayName": "jins kurd", "version": "2025-10-18T19:41:17.132Z", "isBaseForm": true }, "tonic": { "idName": "rast", "displayName": "rāst" }, "stats": { "numberOfTranspositions": 17, "numberOfPitchClasses": 4 }, "comments": { "english": null, "arabic": null }, "sources": [], "parameters": { "pitchClassDataType": "all", "includeIntervals": false, "centsTolerance": 5 }, "context": { "tuningSystem": { "id": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-10-18T19:41:17.132Z", "originalValueType": "fraction", "numberOfPitchClassesSingleOctave": 17, "numberOfPitchClassesAllOctaves": 68, "startingNoteName": "yegah", "referenceFrequency": 440 } }, "pitchData": [ { "pitchClassIndex": 0, "octave": 1, "scaleDegree": "I", "noteName": "rast", "noteNameDisplay": "rāst", "englishName": "C3", "fraction": "1/1", "cents": 0, "decimalRatio": 1, "stringLength": 1000, "frequency": 440, "fretDivision": "0.000", "midiNoteDecimal": 48, "midiNotePlusCentsDeviation": "48 +0.0", "centsDeviation": 0, "ipnReferenceNoteName": "C" }, { "pitchClassIndex": 1, "octave": 1, "scaleDegree": "II", "noteName": "dugah", "noteNameDisplay": "dūgāh", "englishName": "D3", "fraction": "204/182", "cents": 204, "decimalRatio": 1.12, "frequency": 492.8 } ] } ``` ### Check jins availability across tuning systems {#getJinsAvailability} ``` GET /ajnas/{idName}/availability ``` Return tuning-system availability for a jins. * Shows which tuning systems on which starting note names can realize the specified jins * If `transpositionNoteName` is provided, filters results to show only tuning systems where the jins can be transposed to that specific note * Validity is computed against each tuning system's note name sets and the jins's pitch class intervals * Availability is checked in every octave the tuning system builds from each starting note, so ajnās that span several octaves are found **Path Parameters:** * `idName`: URL-safe jins identifier: A jins's idName (`jins_rast`), its numeric id, or the idName of one of its transpositions (`jins_rast_al_nawa`). A transposed idName works like `transpositionNoteName` for its tonic; giving it together with a different `transpositionNoteName` is a 400. The older closed-up spelling is also accepted. (string) **(required)** * Example: `jins_rast` **Query Parameters:** * `transpositionNoteName` (optional): Filter results to show only tuning systems where the jins can be transposed to this specific note (URL-safe, diacritics-insensitive). - Type: `string` * Example: `nawa` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/ajnas/jins_rast/availability?includeArabic=true" ``` **Response:** Availability information retrieved successfully **Example response — withoutTransposition:** ```json { "jins": { "id": "5", "idName": "jins_kurd", "displayName": "Jins Kurd", "version": "2025-10-18T19:41:17.132Z" }, "availability": { "count": 29, "tuningSystems": [ { "tuningSystemId": "ibnsina_1037", "tuningSystemDisplayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "tuningSystemStartingNoteNames": [ "ʿushayrān", "yegāh" ], "tuningSystemStartingNoteNamesIds": [ "ushayran", "yegah" ] }, { "tuningSystemId": "alfarabi_950g", "tuningSystemDisplayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave)", "tuningSystemStartingNoteNames": [ "ʿushayrān", "yegāh" ], "tuningSystemStartingNoteNamesIds": [ "ushayran", "yegah" ] } ] } } ``` ### List transpositions for a jins {#listJinsTranspositions} ``` GET /ajnas/{idName}/transpositions ``` Lists distinct transpositions (taswīr) for a jins within a specific tuning system and starting note. The base form is excluded. Octave renderings of the same modal degree (e.g. qarār dūgāh vs dūgāh vs muḥayyar) are not treated as distinct taswīr. If there are no distinct taswīr for this tuning-system + starting-note combination, this endpoint returns `422` with an `{ error, hint }` payload (it does not return a 200 with an empty list). **Path Parameters:** * `idName`: URL-safe jins identifier: A jins's idName (`jins_rast`) or its numeric id. This route lists every transposition of the jins, so the idName of a single transposition (`jins_rast_al_nawa`) is rejected with a 400 that names the base idName to use. (string) **(required)** * Example: `jins_bayyat` **Query Parameters:** * `tuningSystem` **(required)**: Tuning system identifier (e.g., 'ibnsina\_1037', 'alfarabi\_950g', 'meshshaqa\_1899') - Type: `string` * Example: `meshshaqa_1899` * `startingNote` **(required)**: Tuning system starting note name (URL-safe, diacritics-insensitive). - Type: `string` * Example: `yegah` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/ajnas/jins_bayyat/transpositions?tuningSystem=meshshaqa_1899&startingNote=yegah&includeArabic=true" ``` **Response:** Transpositions retrieved successfully **Example response:** ```json { "jins": { "id": "2", "idName": "jins_bayyat", "displayName": "jins bayyāt", "version": "2025-10-18T19:35:30.479Z" }, "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-11-09T00:44:40.275Z", "numberOfPitchClassesSingleOctave": 17 }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "transpositions": { "total": 12, "options": { "idNames": [ "qarar_yegah", "qarar_ushayran", "qarar_rast", "yegah", "ushayran", { "…": "truncated — 7 more items" } ], "displayNames": [ "qarār yegāh", "qarār ʿushayrān", "qarār rāst", "yegāh", "ʿushayrān", { "…": "truncated — 7 more items" } ] }, "detailed": [ { "idName": "jins_bayyat_al_qarar_yegah", "displayName": "jins bayyāt al-qarār yegāh", "tonic": { "idName": "qarar_yegah", "displayName": "qarār yegāh" }, "pitchClass": { "pitchClassIndex": 0, "octave": 0 }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_yegah" } }, { "idName": "jins_bayyat_al_qarar_ushayran", "displayName": "jins bayyāt al-qarār ʿushayrān", "tonic": { "idName": "qarar_ushayran", "displayName": "qarār ʿushayrān" }, "pitchClass": { "pitchClassIndex": 3, "octave": 0 }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_ushayran" } }, { "idName": "jins_bayyat_al_qarar_rast", "displayName": "jins bayyāt al-qarār rāst", "tonic": { "idName": "qarar_rast", "displayName": "qarār rāst" }, "pitchClass": { "pitchClassIndex": 7, "octave": 0 }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=qarar_rast" } }, { "idName": "jins_bayyat_al_yegah", "displayName": "jins bayyāt al-yegāh", "tonic": { "idName": "yegah", "displayName": "yegāh" }, "pitchClass": { "pitchClassIndex": 0, "octave": 1 }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=yegah" } }, { "idName": "jins_bayyat_al_ushayran", "displayName": "jins bayyāt al-ʿushayrān", "tonic": { "idName": "ushayran", "displayName": "ʿushayrān" }, "pitchClass": { "pitchClassIndex": 3, "octave": 1 }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat?tuningSystem=ibnsina_1037&startingNote=yegah&transposeTo=ushayran" } }, { "…": "truncated — 7 more items" } ] }, "links": { "self": "https://diarmaqar.net/api/ajnas/jins_bayyat/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah", "availability": "https://diarmaqar.net/api/ajnas/jins_bayyat/availability", "detail": "https://diarmaqar.net/api/ajnas/jins_bayyat" } } ``` ### Compare jins data across multiple tuning systems and starting notes {#compareJins} ``` GET /ajnas/{idName}/compare ``` Compare comprehensive jins data across multiple tuning systems **and** multiple starting notes in a single request. Given `N` tuning systems and `M` starting notes, the response contains the Cartesian product of `N × M` comparison cells in user-supplied order (outer loop = `tuningSystems`, inner loop = `startingNotes`). Each successful cell includes the (unidirectional) pitch class sequence, optional interval data, and transposition details. When a requested starting note is not available in a given tuning system the cell carries an informational `note` field (not `error`) together with `validStartingNotes`. When a hard failure occurs (tuning system not found, jins not realizable in this configuration, or an unreachable `transposeTo` target) the cell carries an `error` field. The overall response is always HTTP 200 — per-cell outcomes do not affect the HTTP status. The following invariant always holds: ``` successfulComparisons + unavailableStartingNotes + failedComparisons === totalComparisons ``` This endpoint is ideal for comparative musicological analysis of melodic structures across historical tuning systems and/or multiple modal transpositions. **Path Parameters:** * `idName`: URL-safe jins identifier: A jins's idName (`jins_segah`), its numeric id, or the idName of one of its transpositions (`jins_segah_al_tik_hisar`). A transposed idName works like adding `transposeTo` for its tonic; giving it together with a different `transposeTo` is a 400. The older closed-up spelling (`jins_segah_altik_hisar`) is also accepted. (string) **(required)** * Example: `jins_bayyat` **Query Parameters:** * `tuningSystems` **(required)**: Comma-separated list of tuning system IDs. product of these tuning systems with the requested `startingNotes` (outer loop = `tuningSystems`, inner loop = `startingNotes`). Use `all` to include every tuning system in the archive (cannot be combined with explicit IDs). * Type: `string` * Example: `alsabbagh_1954,ibnsina_1037` * `startingNotes` **(required)**: Comma-separated list of starting note names (URL-safe, diacritics-insensitive). response contains `N × M` cells for `N` tuning systems × `M` starting notes, in user-supplied order. If a starting note is not available in a given tuning system that cell carries an informational `note` field (with a `validStartingNotes` namespace) rather than pitch data. * Type: `string` * Example: `rast,yegah,ushayran` * `pitchClassDataType` (optional): Output format for pitch class data. Defaults to `all` when omitted. - Type: `string` - Valid values: `all`, `englishName`, `solfege`, `fraction`, `cents`, ... (14 total) - Default: `all` * Example: `cents` * `includeIntervals` (optional): Whether to include interval data between adjacent pitch classes on each cell. Defaults to `"false"` when omitted.. Defaults to `"false"` when omitted. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `transposeTo` (optional): Transpose every successful cell to the given tonic note (applies to every cell in the Cartesian product). Cartesian product). If the requested target is not reachable in a given cell the cell carries an `error` plus an `availableTranspositions` list. * Type: `string` * Example: `nawa` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with `Ar` suffix (e.g., `displayNameAr`, `noteNameDisplayAr`) * Note names and jins names get Arabic versions in `*Ar` fields * Tuning system display names get Arabic versions in `displayNameAr` if available * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/ajnas/jins_bayyat/compare?tuningSystems=alsabbagh_1954,ibnsina_1037&startingNotes=rast,yegah,ushayran&includeArabic=true" ``` **Response:** Comparison data retrieved successfully. Note that the response is always HTTP 200 regardless of per-cell outcomes; individual failures (missing starting note, tuning system not found, jins not realizable, unreachable transposeTo) are reported on the respective cell via `note` or `error` fields. The counters `successfulComparisons + unavailableStartingNotes + failedComparisons` always equal `totalComparisons`. **Example response — twoTuningSystems:** ```json { "jins": { "id": "19", "idName": "jins_rast", "displayName": "jins rāst", "version": "2025-10-18T19:34:26.343Z" }, "comparisons": { "count": 1, "totalComparisons": 1, "successfulComparisons": 1, "unavailableStartingNotes": 0, "failedComparisons": 0, "data": [ { "tuningSystem": { "id": "alsabbagh_1954", "idName": "alsabbagh_1954", "displayName": "al-Ṣabbāgh (1954) Contemporary Arabic Tuning 24-Tone", "version": "2025-10-18T19:42:23.643Z" }, "startingNote": { "idName": "rast", "displayName": "rāst" }, "jins": { "id": "19", "idName": "jins_rast", "displayName": "jins rāst", "version": "2025-10-18T19:34:26.343Z" }, "tonic": { "idName": "rast", "displayName": "rāst" }, "stats": { "tuningSystem": { "numberOfPitchClassesSingleOctave": 24, "referenceFrequency": 130.665 }, "jins": { "numberOfPitchClasses": 4 } }, "availableTranspositions": [], "pitchData": [ { "pitchClassIndex": 0, "octave": 1, "scaleDegree": "I", "noteName": "rast", "noteNameDisplay": "rāst", "cents": 0 }, { "pitchClassIndex": 4, "octave": 1, "scaleDegree": "II", "noteName": "dugah", "noteNameDisplay": "dūgāh", "cents": 203.91000173077484 }, { "pitchClassIndex": 7, "octave": 1, "scaleDegree": "III", "noteName": "segah", "noteNameDisplay": "segāh", "cents": 356.8630927494849 }, { "pitchClassIndex": 10, "octave": 1, "scaleDegree": "IV", "noteName": "chahargah", "noteNameDisplay": "chahārgāh", "cents": 498.0449991346125 } ], "parameters": { "pitchClassDataType": "cents", "includeIntervals": true, "transposeTo": null }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_rast?tuningSystem=alsabbagh_1954&startingNote=r%C4%81st&pitchClassDataType=cents&includeIntervals=true", "availability": "https://diarmaqar.net/api/ajnas/jins_rast/availability" }, "intervals": [ { "cents": 203.91000173077484 }, { "cents": 152.95309101871007 }, { "cents": 141.1819063851276 } ] } ] }, "parameters": { "tuningSystems": { "idNames": [ "alsabbagh_1954" ], "displayNames": [ "alsabbagh_1954" ] }, "startingNotes": { "idNames": [ "rast" ], "displayNames": [ "rast" ] }, "pitchClassDataType": "cents", "includeIntervals": true, "transposeTo": null }, "links": { "self": "https://diarmaqar.net/api/ajnas/jins_rast/compare?tuningSystems=alsabbagh_1954&startingNotes=rast&pitchClassDataType=cents", "detail": "https://diarmaqar.net/api/ajnas/jins_rast", "availability": "https://diarmaqar.net/api/ajnas/jins_rast/availability" } } ``` *** ## Tuning Systems Historical tuning systems spanning from al-Kindī (874 CE) to contemporary approaches. ### List all tuning systems {#listTuningSystems} ``` GET /tuning-systems ``` Retrieve metadata for all available tuning systems. * Includes identifiers, display names, version information, primary value type, and pitch class counts per octave * Responses include available starting note names for each tuning system * Different starting notes represent different theoretical frameworks (e.g., ʿushayrān for oud tuning, yegāh for monochord measurements) * Optional bibliographic source references (sourceId and page) when `includeSources=true` **Query Parameters:** * `includeSources` (optional): Include bibliographic source references (sourceId and page) for each tuning system - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/tuning-systems?includeSources=true&includeArabic=true" ``` **Response:** List of tuning systems **Example response — english:** ```json { "count": 35, "data": [ { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-10-18T19:42:23.643Z", "year": "1037" }, "startingNotes": { "idNames": [ "ushayran", "yegah" ], "displayNames": [ "ʿushayrān", "yegāh" ] }, "stats": { "numberOfPitchClassesSingleOctave": 17 }, "sources": [ { "sourceId": "alshawwa_1946", "page": "49" } ] }, { "tuningSystem": { "id": "alfarabi_950g", "idName": "alfarabi_950g", "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone", "version": "2025-10-18T19:42:23.643Z", "year": "950g" }, "startingNotes": { "idNames": [ "ushayran", "yegah" ], "displayNames": [ "ʿushayrān", "yegāh" ] }, "stats": { "numberOfPitchClassesSingleOctave": 27 }, "sources": [ { "sourceId": "alshawwa_1946", "page": "50" } ] } ] } ``` ### Get Tuning System Details {#getTuningSystemPitchClasses} ``` GET /tuning-systems/{id}/{startingNote}/pitch-classes ``` Get Tuning System Details - Returns all pitch classes for a specific tuning system and starting note. This endpoint is essential for tuning system operations, providing comprehensive pitch class data across all octaves with full formatting options. **Path Parameters:** * `id`: Tuning system identifier (string) **(required)** * Example: `cairocongresstuningcommittee_1929` * `startingNote`: Tuning system starting note name (URL-safe, diacritics-insensitive). Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh (string) **(required)** * Example: `rast` **Query Parameters:** * `pitchClassDataType` (optional): Pitch class data format. * `all` returns all available fields including englishName, solfege, abjadName, fraction, cents, decimalRatio, stringLength, frequency, fretDivision, midiNoteDecimal, midiNotePlusCentsDeviation, centsDeviation, ipnReferenceNoteName * Use a specific value to return only that field plus minimal identifiers * Type: `string` - Valid values: `all`, `englishName`, `solfege`, `fraction`, `cents`, ... (14 total) - Default: `all` * Example: `all` * `octave` (optional): Filter by octave number. Use a specific octave number (0, 1, 2, 3) to filter to that octave only. * Type: `string` - Valid values: `all`, `0`, `1`, `2`, `3` - Default: `all` * Example: `all` * `includeSources` (optional): Include bibliographic source references (sourceId and page) for the tuning system - Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/tuning-systems/cairocongresstuningcommittee_1929/rast/pitch-classes?includeSources=true&includeArabic=true" ``` **Response:** Tuning system pitch classes retrieved successfully **Example response:** ```json { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-11-09T00:44:40.275Z", "year": "1037", "numberOfPitchClassesSingleOctave": 17 }, "startingNotes": { "idNames": [ "ushayran", "yegah" ], "displayNames": [ "ʿushayrān", "yegāh" ] }, "selectedStartingNote": { "idName": "yegah", "displayName": "yegāh" }, "stats": { "totalPitchClasses": 17, "numberOfPitchClassesSingleOctave": 17, "referenceFrequency": 97.999, "octaves": [ 0, 1, 2, 3 ] }, "pitchClasses": [ { "pitchClassIndex": 0, "octave": 0, "noteName": "qarar_yegah", "noteNameDisplay": "qarār yegāh", "cents": -1200 }, { "pitchClassIndex": 1, "octave": 0, "noteName": "qarar_qarar_hisar", "noteNameDisplay": "qarār qarār ḥiṣār", "cents": -1088.691430896177 }, { "pitchClassIndex": 2, "octave": 0, "noteName": "qarar_qarar_tik_hisar/shuri", "noteNameDisplay": "qarār qarār tīk ḥiṣār/shūrī", "cents": -1061.427339096077 }, { "pitchClassIndex": 3, "octave": 0, "noteName": "qarar_ushayran", "noteNameDisplay": "qarār ʿushayrān", "cents": -996.0899982692251 }, { "pitchClassIndex": 4, "octave": 0, "noteName": "qarar_ajam_ushayran", "noteNameDisplay": "qarār ʿajam ʿushayrān", "cents": -905.8650025961624 }, { "…": "truncated — 63 more items" } ], "context": { "pitchClassDataType": "cents", "octave": "all" }, "links": { "self": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/pitch-classes", "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037" }, "sources": [ { "sourceId": "farmer_1937", "page": "249" } ] } ``` ### List maqāmāt available in a tuning system {#listTuningSystemMaqamat} ``` GET /tuning-systems/{id}/{startingNote}/maqamat ``` Return all maqāmāt that can be realized in a given tuning system beginning on a specific starting note name. * Feasibility is determined by comparing maqām note names to every pitch class the tuning system builds from that starting note, in all its octaves (the same pitch space transpositions and modulations are calculated in) * `characteristics.hasSuyur` is true when at least one sayr can be played on the maqām's base form in this pitch space (the suyūr `GET /maqamat/{idName}?includeSuyur=true` returns) **Path Parameters:** * `id`: Tuning system identifier (e.g., 'ibnsina\_1037', 'alfarabi\_950g', 'meshshaqa\_1899') (string) **(required)** * Example: `alfarabi_950g` * `startingNote`: Tuning system starting note name (URL-safe, diacritics-insensitive). Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh (string) **(required)** * Example: `ushayran` **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeMaqamDegrees` (optional): When true, each maqām in data includes a `maqamDegrees` object with ascending and descending arrays of PAO note name idNames (URL-safe identifiers for scale degrees).. of PAO note name idNames (URL-safe identifiers for scale degrees). * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeDegreeDetails` (optional): When true (and when includeMaqamDegrees=true), the endpoint returns `maqamDegrees.ascending` / `maqamDegrees.descending` as arrays of objects `{ noteName, englishName, solfege, ipnReferenceNoteName, centsDeviation, midiNotePlusCentsDeviation }` instead of note-name strings. The same transformation applies to `transpositions[].maqamDegrees`. `maqamDegrees.descending` as arrays of objects `{ noteName, englishName, solfege, ipnReferenceNoteName, centsDeviation, midiNotePlusCentsDeviation }` instead of note-name strings. The same transformation applies to `transpositions[].maqamDegrees`. The last three fields are the same as in GET /maqamat/{id}: the 12-EDO key the degree is spelled against (`ipnReferenceNoteName`, e.g. "Bb"), the degree's deviation from it in cents (`centsDeviation`), and the MIDI note number followed by the deviation (`midiNotePlusCentsDeviation`, e.g. "58 -9.8"). Each direction is spelled on its own, so an ascending and a descending degree may share a key. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeTranspositions` (optional): When true, each maqām in data includes a `transpositions` array with the other transpositions (excluding the base tonic). (excluding the base tonic). Each transposition has its own `idName` and `displayName` (`maqam_rast_al_chahargah`, "maqām rāst al-chahārgāh"; plus `displayNameAr` with `inArabic=true`), its `tonic`, and `maqamDegrees` with ascending/descending note name idNames for that transposed position. The `idName` works as a path segment: `/maqamat/maqam_rast_al_chahargah`. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeOctaveRenderings` (optional): When true, each maqām in data also has an `octaveRenderings` array: the base form an octave or more away, on the same modal degree (`maqam_yegah_al_nawa`, maqām yegāh on nawā). octave or more away, on the same modal degree (`maqam_yegah_al_nawa`, maqām yegāh on nawā). These are not taṣwīr, so they are never in `transpositions`. Entries have the same shape as `transpositions`. Together with the base form and `transpositions`, this lists every maqām form that maqām detail can refer to (in `ajnas`, the structural jins slots, `modulations` and `lowerOctaveModulations`). Every listed form carries `formType` (base, transposition or octaveRendering). * Type: `string` - Valid values: `true`, `false` - Default: `false` * `sortBy` (optional): Sort order for results. and `/ajnas`, which default to `alphabetical`) because the endpoint is intrinsically about a concrete pitch layout. Invalid values return HTTP 400. * Type: `string` - Valid values: `alphabetical`, `tonic` - Default: `tonic` * Example: `tonic` - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak * Example: `alphabetical` - Sort alphabetically by display name * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/tuning-systems/alfarabi_950g/ushayran/maqamat?includeArabic=true" ``` **Response:** Maqāmāt list retrieved successfully **Example response:** ```json { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2026-08-16T22:20:52.549Z", "year": "1037", "numberOfPitchClassesSingleOctave": 17 }, "startingNotes": { "idNames": [ "ushayran", "yegah", "rast" ], "displayNames": [ "ʿushayrān", "yegāh", "rāst" ] }, "selectedStartingNote": { "idName": "yegah", "displayName": "yegāh" }, "stats": { "totalMaqamatForStartingNote": 69, "totalMaqamatInLibrary": 145, "uniqueTonicCount": 8, "uniqueFamilyCount": 26, "referenceFrequency": 98 }, "data": [ { "maqam": { "id": "34", "idName": "maqam_dilkeshidah", "displayName": "maqām dilkeshīdah", "version": "2025-10-18T19:41:17.132Z", "isBaseForm": true, "formType": "base" }, "family": { "idName": "buselik_alhilu", "displayName": "būselīk (al-Ḥilū)" }, "tonic": { "idName": "yegah", "displayName": "yegāh" }, "stats": { "numberOfPitchClasses": 7 }, "characteristics": { "isOctaveRepeating": true, "hasAsymmetricDescending": true, "hasSuyur": true }, "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_dilkeshidah" }, "transpositions": [ { "idName": "maqam_dilkeshidah_al_qarar_rast", "displayName": "maqām dilkeshīdah al-qarār rāst", "tonic": { "idName": "qarar_rast", "displayName": "qarār rāst" }, "isBaseForm": false, "formType": "transposition", "maqamDegrees": { "ascending": [ "qarar_rast", "qarar_dugah", "qarar_kurdi", "qarar_chahargah", "yegah", "qarar_tik_hisar_shuri", "kawasht" ], "descending": [ "ajam_ushayran", "qarar_tik_hisar_shuri", "yegah", "qarar_chahargah", "qarar_kurdi", "qarar_dugah", "qarar_rast" ] } } ], "octaveRenderings": [ { "idName": "maqam_dilkeshidah_al_qarar_yegah", "displayName": "maqām dilkeshīdah al-qarār yegāh", "tonic": { "idName": "qarar_yegah", "displayName": "qarār yegāh" }, "isBaseForm": false, "formType": "octaveRendering", "maqamDegrees": { "ascending": [ "qarar_yegah", "qarar_ushayran", "qarar_ajam_ushayran", "qarar_rast", "qarar_dugah", "qarar_segah", "qarar_hijaz" ], "descending": [ "qarar_chahargah", "qarar_segah", "qarar_dugah", "qarar_rast", "qarar_ajam_ushayran", "qarar_ushayran", "qarar_yegah" ] } } ] }, { "maqam": { "id": "30", "idName": "maqam_farahfazza", "displayName": "maqām faraḥfazzā", "version": "2026-07-25T15:22:12.206Z", "isBaseForm": true, "formType": "base" }, "family": { "idName": "buselik_alhilu", "displayName": "būselīk (al-Ḥilū)" }, "tonic": { "idName": "yegah", "displayName": "yegāh" }, "stats": { "numberOfPitchClasses": 7 }, "characteristics": { "isOctaveRepeating": true, "hasAsymmetricDescending": true, "hasSuyur": true }, "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_farahfazza" }, "transpositions": [ { "idName": "maqam_farahfazza_al_qarar_ushayran", "displayName": "maqām faraḥfazzā al-qarār ʿushayrān", "tonic": { "idName": "qarar_ushayran", "displayName": "qarār ʿushayrān" }, "isBaseForm": false, "formType": "transposition", "maqamDegrees": { "ascending": [ "qarar_ushayran", "qarar_kawasht", "qarar_rast", "qarar_dugah", "qarar_buselik_ushshaq", "qarar_chahargah", "yegah" ], "descending": [ "qarar_hisar", "qarar_chahargah", "qarar_buselik_ushshaq", "qarar_dugah", "qarar_rast", "qarar_kawasht", "qarar_ushayran" ] } } ], "octaveRenderings": [ { "idName": "maqam_farahfazza_al_qarar_yegah", "displayName": "maqām faraḥfazzā al-qarār yegāh", "tonic": { "idName": "qarar_yegah", "displayName": "qarār yegāh" }, "isBaseForm": false, "formType": "octaveRendering", "maqamDegrees": { "ascending": [ "qarar_yegah", "qarar_ushayran", "qarar_ajam_ushayran", "qarar_rast", "qarar_dugah", "qarar_kurdi", "qarar_chahargah" ], "descending": [ "qarar_hijaz", "qarar_kurdi", "qarar_dugah", "qarar_rast", "qarar_ajam_ushayran", "qarar_ushayran", "qarar_yegah" ] } } ] } ], "links": { "self": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/maqamat", "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037", "collection": "https://diarmaqar.net/api/maqamat" } } ``` ### List ajnās available in a tuning system {#listTuningSystemAjnas} ``` GET /tuning-systems/{id}/{startingNote}/ajnas ``` Return all ajnās that can be realized in a given tuning system beginning on a specific starting note name. * Feasibility is determined by comparing jins note names to every pitch class the tuning system builds from that starting note, in all its octaves (the same pitch space transpositions and modulations are calculated in) * A jins is a single ascending set of note names, so unlike a maqām it has no descending counterpart, no sayr and no family classification. `jinsDegrees` is therefore one array rather than an ascending/descending pair * This is the ajnās counterpart of `/tuning-systems/{id}/{startingNote}/maqamat` and returns the same response shape **Path Parameters:** * `id`: Tuning system identifier (e.g., 'ibnsina\_1037', 'alfarabi\_950g', 'meshshaqa\_1899') (string) **(required)** * Example: `ibnsina_1037` * `startingNote`: Tuning system starting note name (URL-safe, diacritics-insensitive). Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh (string) **(required)** * Example: `yegah` **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr) * Jins names and note names get Arabic versions in \*Ar fields * Tuning system display names get Arabic versions in displayNameAr if available * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeJinsDegrees` (optional): When true, each jins in data includes a `jinsDegrees` array of PAO note name idNames (URL-safe identifiers for the jins degrees), in ascending order from the tonic.. (URL-safe identifiers for the jins degrees), in ascending order from the tonic. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeDegreeDetails` (optional): When true (and when includeJinsDegrees=true), the endpoint returns `jinsDegrees` as an array of objects `{ noteName, englishName, solfege }` instead of note-name strings. objects `{ noteName, englishName, solfege }` instead of note-name strings. The same transformation applies to `transpositions[].jinsDegrees`. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeTranspositions` (optional): When true, each jins in data includes a `transpositions` array with the other transpositions (taṣwīr) available in this tuning system, excluding the base tonic. (taṣwīr) available in this tuning system, excluding the base tonic. Each entry has its own `idName` and `displayName` (`jins_rast_al_nawa`, "jins rāst al-nawā"; plus `displayNameAr` with `inArabic=true`), its `tonic`, and `jinsDegrees` for that transposed position. The `idName` works as a path segment: `/ajnas/jins_rast_al_nawa`. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeOctaveRenderings` (optional): When true, each jins in data also has an `octaveRenderings` array: the base form an octave or more away, on the same modal degree (`jins_yegah_al_nawa`, jins yegāh on nawā). octave or more away, on the same modal degree (`jins_yegah_al_nawa`, jins yegāh on nawā). These are not taṣwīr, so they are never in `transpositions`. Entries have the same shape as `transpositions`. Together with the base form and `transpositions`, this lists every jins form that maqām detail can refer to (in `ajnas`, the structural jins slots, `modulations` and `lowerOctaveModulations`). Every listed form carries `formType` (base, transposition or octaveRendering). * Type: `string` - Valid values: `true`, `false` - Default: `false` * `sortBy` (optional): Sort order for results. defaults to `alphabetical`) because the endpoint is intrinsically about a concrete pitch layout. Invalid values return HTTP 400. * Type: `string` - Valid values: `alphabetical`, `tonic` - Default: `tonic` * Example: `tonic` - Sort by tonic note priority across the full NoteName.ts octave-stratified order, alphabetical tiebreak * Example: `alphabetical` - Sort alphabetically by display name * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/ajnas?includeArabic=true" ``` **Response:** Ajnās list retrieved successfully **Example response:** ```json { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2026-08-16T22:20:52.549Z", "year": "1037", "numberOfPitchClassesSingleOctave": 17 }, "startingNotes": { "idNames": [ "ushayran", "yegah", "rast" ], "displayNames": [ "ʿushayrān", "yegāh", "rāst" ] }, "selectedStartingNote": { "idName": "yegah", "displayName": "yegāh" }, "stats": { "totalAjnasForStartingNote": 39, "totalAjnasInLibrary": 44, "uniqueTonicCount": 10, "referenceFrequency": 98 }, "data": [ { "jins": { "id": "39", "idName": "jins_qaf", "displayName": "jins qāf", "version": "2026-07-20T09:57:37.540Z", "isBaseForm": true, "formType": "base" }, "tonic": { "idName": "yegah", "displayName": "yegāh" }, "stats": { "numberOfPitchClasses": 4 }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_qaf" }, "transpositions": [ { "idName": "jins_qaf_al_qarar_rast", "displayName": "jins qāf al-qarār rāst", "tonic": { "idName": "qarar_rast", "displayName": "qarār rāst" }, "isBaseForm": false, "formType": "transposition", "jinsDegrees": [ "qarar_rast", "qarar_zirguleh", "qarar_kurdi", "qarar_hijaz" ] } ], "octaveRenderings": [ { "idName": "jins_qaf_al_qarar_yegah", "displayName": "jins qāf al-qarār yegāh", "tonic": { "idName": "qarar_yegah", "displayName": "qarār yegāh" }, "isBaseForm": false, "formType": "octaveRendering", "jinsDegrees": [ "qarar_yegah", "qarar_qarar_hisar", "qarar_ajam_ushayran", "qarar_zirguleh" ] } ] }, { "jins": { "id": "48", "idName": "jins_shad_araban", "displayName": "jins shad ʿarabān", "version": "2026-07-20T18:09:15.658Z", "isBaseForm": true, "formType": "base" }, "tonic": { "idName": "yegah", "displayName": "yegāh" }, "stats": { "numberOfPitchClasses": 4 }, "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_shad_araban" }, "transpositions": [ { "idName": "jins_shad_araban_al_qarar_ajam_ushayran", "displayName": "jins shad ʿarabān al-qarār ʿajam ʿushayrān", "tonic": { "idName": "qarar_ajam_ushayran", "displayName": "qarār ʿajam ʿushayrān" }, "isBaseForm": false, "formType": "transposition", "jinsDegrees": [ "qarar_ajam_ushayran", "qarar_kawasht", "qarar_dugah", "qarar_kurdi" ] } ], "octaveRenderings": [ { "idName": "jins_shad_araban_al_qarar_yegah", "displayName": "jins shad ʿarabān al-qarār yegāh", "tonic": { "idName": "qarar_yegah", "displayName": "qarār yegāh" }, "isBaseForm": false, "formType": "octaveRendering", "jinsDegrees": [ "qarar_yegah", "qarar_qarar_hisar", "qarar_kawasht", "qarar_rast" ] } ] } ], "links": { "self": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037/yegah/ajnas", "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037", "collection": "https://diarmaqar.net/api/ajnas" } } ``` *** ## Modulations ### Find modulation routes between maqāmāt {#findModulationRoutes} ``` GET /modulation-routes ``` Calculate possible modulation routes between maqāmāt, similar to a navigation/maps application. Uses al-Shawwā's 1946 modulation rules to find shortest paths between a source and target maqām, with optional waypoints and return-to-start functionality. **Key Features:** * Finds shortest paths (fewest modulation steps) using BFS algorithm * Supports waypoints for multi-stop journeys * Optional return-to-start for round-trip routes (reflecting traditional maqām performance practice) * `limitToShortestHops=true` returns only the shortest-length routes; default (`false`) pads the result with progressively longer routes up to `maxRoutes` / `maxHops` * `allowOctaveJumps=true` lets BFS traverse register-shift (8va/8vb) edges between register-equivalent siblings; default (`false`) keeps routes strictly within al-Shawwā's scale-degree modulation rules * `allowDownwardModulation=true` lets BFS traverse direct downward-modulation edges (`*OctaveBelow` categories, e.g. `sixthDegreeAscOctaveBelow` / `VI-8vb`). These are single-hop modulations to a different maqām whose tonic sits one octave below the ascending rule's target — common in Arabic practice (e.g. saba:dūgāh → ajam ushayrān:ajam ushayrān as one move). Default (`false`) ignores those edges * Results cached per tuning system + starting note combination for performance * `maxHops` is required and capped at 20 to prevent combinatorial explosion **Graph Structure:** * Nodes: Each (maqamId, tonic) pair is a unique node * Edges: Modulation possibilities based on al-Shawwā's rules (scale degrees I, III, IV, V, VI) **Performance Notes:** * maxHops is required to prevent combinatorial explosion * First request for a tuning system + starting note builds the graph (may take longer) * Subsequent requests use cached graph data **Query Parameters:** * `tuningSystem` **(required)**: Tuning system identifier (e.g., 'alfarabi\_950g', 'ibnsina\_1037') - Type: `string` * Example: `alfarabi_950g` * `startingNote` **(required)**: Tuning system starting note name (URL-safe, diacritics-insensitive). This is MANDATORY as it affects which maqāmāt are available and their modulation possibilities.. This is MANDATORY as it affects which maqāmāt are available and their modulation possibilities. * Type: `string` * Example: `ushayran` * `fromMaqam` **(required)**: Source maqam base ID (the starting point of the journey). Use the base maqam identifier (e.g., "maqam\_nahawand"), not the transposition display name. Combine with `fromTonic` to specify a particular transposition.. Use the base maqam identifier (e.g., "maqam\_nahawand"), not the transposition display name. Combine with `fromTonic` to specify a particular transposition. * Type: `string` * Example: `maqam_rast` * `fromTonic` (optional): Optional specific tonic for the source maqam (URL-safe). If not specified, uses the base form. - Type: `string` * Example: `rast` * `toMaqam` **(required)**: Target maqam base ID (the destination of the journey). Use the base maqam identifier (e.g., "maqam\_nahawand"), not the transposition display name. Combine with `toTonic` to specify a particular transposition.. Use the base maqam identifier (e.g., "maqam\_nahawand"), not the transposition display name. Combine with `toTonic` to specify a particular transposition. * Type: `string` * Example: `maqam_segah` * `toTonic` (optional): Optional specific tonic for the target maqam (URL-safe). If not specified, uses the base form. - Type: `string` * Example: `segah` * `maxHops` **(required)**: Maximum number of modulation steps allowed (required safeguard). Prevents combinatorial explosion in route calculation. Most musical modulation sequences are 2-4 hops. Maximum allowed value is 20.. Prevents combinatorial explosion in route calculation. Most musical modulation sequences are 2-4 hops. Maximum allowed value is 20. * Type: `integer` * Example: `5` * `waypoints` (optional): Optional comma-separated waypoints to pass through. Format: maqamId:tonicId or just maqamId (uses canonical tonic). Example: "maqam\_bayyat:dugah,maqam\_saba". Format: maqamId:tonicId or just maqamId (uses canonical tonic). Example: "maqam\_bayyat:dugah,maqam\_saba" * Type: `string` * Example: `maqam_bayyat:dugah` * `returnToStartingMaqam` (optional): Whether to calculate the return path back to the source (starting) maqam. Reflects traditional maqām performance practice where music returns to the starting mode. When true, response includes both outbound and return routes.. Reflects traditional maqām performance practice where music returns to the starting mode. When true, response includes both outbound and return routes. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `maxRoutes` (optional): Maximum number of routes to return - Type: `integer` - Default: `10` * Example: `10` * `limitToShortestHops` (optional): When `true`, only routes at the minimum hop count are returned — all routes in the response share the same `hops` value. returned — all routes in the response share the same `hops` value. When `false` (default), the response is filled out with progressively longer simple paths (still capped by `maxHops` and `maxRoutes`, ordered shortest-first). * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `allowOctaveJumps` (optional): When `true`, BFS may traverse register-shift (`8va` / `8vb`) edges between register-equivalent siblings of the same maqām (e.g. edges between register-equivalent siblings of the same maqām (e.g. ḥijāz:muḥayyar → ḥijāz:dūgāh). These edges appear anywhere in a route — at the start, in the middle, or at the end — and let the algorithm reach register variants that aren't directly connected by scale-degree modulation. When `false` (default), those edges are ignored and every hop in every returned route must be a genuine al-Shawwā modulation (degrees I / III / IV / V / VI). Note: `allowOctaveJumps` controls PURE register shifts (same maqām, different octave). `allowDownwardModulation` controls DOWNWARD MODULATIONS (different maqām at a lower-octave tonic). They are independent flags. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `allowDownwardModulation` (optional): When `true`, BFS may traverse direct downward-modulation edges (`*OctaveBelow` categories, e.g. `sixthDegreeAscOctaveBelow` / `VI-8vb`). edges (`*OctaveBelow` categories, e.g. `sixthDegreeAscOctaveBelow` / `VI-8vb`). These represent a single-hop modulation to a different maqām whose tonic sits one octave below the corresponding ascending rule's target — common in Arabic practice (e.g. saba:dūgāh → ajam ushayrān:ajam ushayrān as one move rather than as VI↑ + 8vb). When `false` (default), those edges are ignored and such a move can only be reached via the equivalent two-hop ascending-modulation + register-shift combination. * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. Adds Arabic versions with "Ar" suffix (e.g., maqamDisplayNameAr, tonicDisplayAr). Adds Arabic versions with "Ar" suffix (e.g., maqamDisplayNameAr, tonicDisplayAr) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` * `centsTolerance` (optional): Tolerance in cents for pitch class comparison (default: 5) - Type: `number` - Default: `5` * Example: `5` **Example:** ```bash curl "https://diarmaqar.net/api/modulation-routes?tuningSystem=alfarabi_950g&startingNote=ushayran&fromMaqam=maqam_rast&toMaqam=maqam_segah&maxHops=5&includeArabic=true" ``` **Response:** Modulation routes calculated successfully **Example response — routeFound:** ```json { "totalPossibleRoutes": { "outboundRoutesCount": 1, "data": [ { "routeNumber": 1, "outboundRoute": { "hops": 2, "steps": [ { "from": { "maqamId": "1", "maqamIdName": "maqam_rast", "maqamDisplayName": "maqām rāst", "tonicId": "rast", "tonicDisplay": "rāst", "isTransposition": false }, "to": { "maqamId": "2", "maqamIdName": "maqam_bayyat", "maqamDisplayName": "maqām bayyāt", "tonicId": "dugah", "tonicDisplay": "dūgāh", "isTransposition": false }, "modulationDegree": "III", "modulationCategory": "thirdDegree" }, { "from": { "maqamId": "2", "maqamIdName": "maqam_bayyat", "maqamDisplayName": "maqām bayyāt", "tonicId": "dugah", "tonicDisplay": "dūgāh", "isTransposition": false }, "to": { "maqamId": "5", "maqamIdName": "maqam_hijaz", "maqamDisplayName": "maqām ḥijāz", "tonicId": "nawa", "tonicDisplay": "nawā", "isTransposition": false }, "modulationDegree": "IV", "modulationCategory": "fourthDegree" } ] } } ] }, "context": { "tuningSystem": { "id": "alfarabi_950g", "displayName": "al-Fārābī (950) غ" }, "startingNote": { "idName": "ushayran", "displayName": "ʿushayrān" }, "sourceNode": { "maqamId": "maqam_rast", "maqamDisplayName": "Maqam Rast", "tonicId": "rast", "tonicDisplay": "rāst", "isTransposition": false }, "targetNode": { "maqamId": "maqam_hijaz", "maqamDisplayName": "Maqam Hijaz", "tonicId": "nawa", "tonicDisplay": "nawā", "isTransposition": false }, "searchConstraints": { "maxHops": 5, "maxRoutes": 10, "returnToStartingMaqam": false, "limitToShortestHops": false, "allowOctaveJumps": false, "allowDownwardModulation": false } } } ``` *** ## Pitch Classes ### List all note names {#listNoteNames} ``` GET /pitch-classes/note-names ``` Returns all note names used in the app, bilingually, sortable by note name order or alphabetically. Note names are sourced from all octave arrays in NoteName.ts (octaveZeroNoteNames, octaveOneNoteNames, octaveTwoNoteNames, octaveThreeNoteNames, octaveFourNoteNames). Each note name includes: * Canonical order (index within its octave array) * Octave number (0-4) * English IPN equivalent Note names are unique per octave, so the same note name string in different octaves represents different pitch classes. **Note**: Availability data is not included in this endpoint (it's expensive to calculate). Use the availability endpoint (`/api/pitch-classes/note-names/{noteName}/availability`) to get availability information for a specific note name. **Query Parameters:** * `sortBy` (optional): Sort order for results - Type: `string` - Valid values: `order`, `alphabetical` - Default: `order` * Example: `order` - Sort by canonical note name order (from NoteName.ts arrays) * Example: `alphabetical` - Sort alphabetically by display name * `filterByTuningSystem` (optional): Filter by tuning system ID to show only note names that exist in that system (URL-safe, case-insensitive, diacritics-insensitive). - Type: `string` * Example: `meshshaqa_1899` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/pitch-classes/note-names?includeArabic=true" ``` **Response:** List of note names retrieved successfully **Example response:** ```json { "count": 183, "data": [ { "noteName": { "idName": "qarar_yegah", "displayName": "qarār yegāh" }, "englishName": "G1", "order": 0, "octave": 0, "links": { "detail": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_yegah", "availability": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_yegah/availability" } }, { "noteName": { "idName": "yegah", "displayName": "yegāh" }, "englishName": "G2", "order": 0, "octave": 1, "links": { "detail": "https://diarmaqar.net/api/pitch-classes/note-names/yegah", "availability": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability" } }, { "noteName": { "idName": "nawa", "displayName": "nawā" }, "englishName": "G3", "order": 0, "octave": 2, "links": { "detail": "https://diarmaqar.net/api/pitch-classes/note-names/nawa", "availability": "https://diarmaqar.net/api/pitch-classes/note-names/nawa/availability" } }, { "noteName": { "idName": "saham/ramal_tuti", "displayName": "saham/ramal tūtī" }, "englishName": "G4", "order": 0, "octave": 3, "links": { "detail": "https://diarmaqar.net/api/pitch-classes/note-names/saham/ramal_tuti", "availability": "https://diarmaqar.net/api/pitch-classes/note-names/saham/ramal_tuti/availability" } }, { "noteName": { "idName": "qarar_qarar_nim_hisar", "displayName": "qarār qarār nīm ḥiṣār" }, "englishName": "Ab--1", "order": 1, "octave": 0, "links": { "detail": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_qarar_nim_hisar", "availability": "https://diarmaqar.net/api/pitch-classes/note-names/qarar_qarar_nim_hisar/availability" } }, { "…": "truncated — 178 more items" } ] } ``` ### Get pitch class details by note name {#getPitchClassByNoteName} ``` GET /pitch-classes/note-names/{noteName} ``` Get pitch class details for a note name, across all tuning systems or a specific one. When querying by note name, the note name itself identifies the octave (note names are unique per octave). The octave parameter is optional and can be used for validation. Supports: * Single tuning system with specific starting note * Single tuning system with startingNote="all" (returns array for all starting notes) * All tuning systems (returns array for all tuning systems and starting notes) **Path Parameters:** * `noteName`: URL-safe note name (e.g., "rast", "dugah", "nawa") (string) **(required)** * Example: `rast` **Query Parameters:** * `tuningSystem` (optional): Tuning system ID. - Type: `string` * Example: `cairocongresstuningcommittee_1929` * `startingNote` (optional): Starting note for the tuning system. * Use "all" to include all available starting notes for that tuning system (returns array of results, one per starting note) Note: Since note names are unique per octave, the note name itself identifies the octave. No octave parameter is needed. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh * Type: `string` * Example: `rast` * `pitchClassDataType` (optional): Pitch class data format (defaults to `all` when omitted, matching the handler) - Type: `string` - Valid values: `all`, `abjadName`, `englishName`, `solfege`, `fraction`, ... (14 total) - Default: `all` * Example: `cents` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/pitch-classes/note-names/rast?includeArabic=true" ``` **Response:** Pitch class data retrieved successfully **Example response:** ```json { "context": { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-11-09T00:44:40.275Z" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "noteName": { "idName": "yegah", "displayName": "yegāh" }, "referenceFrequency": 97.999, "pitchClassDataType": "cents" }, "pitchClass": { "pitchClassIndex": 0, "octave": 1, "noteName": "yegah", "noteNameDisplay": "yegāh", "cents": 0 }, "links": { "self": "https://diarmaqar.net/api/pitch-classes/note-names/yegah?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents", "availability": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability", "compare": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/compare" } } ``` ### Check note name availability across tuning systems {#getNoteNameAvailability} ``` GET /pitch-classes/note-names/{noteName}/availability ``` Check which tuning systems support a specific note name and what pitch class index it has in each tuning system. Returns for each tuning system: * All starting notes where the note name exists * The pitch class index for each starting note * The octave where the note name was found **Path Parameters:** * `noteName`: URL-safe note name (e.g., "rast", "dugah", "nawa") (string) **(required)** * Example: `rast` **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/pitch-classes/note-names/rast/availability?includeArabic=true" ``` **Response:** Availability data retrieved successfully **Example response:** ```json { "noteName": { "idName": "yegah", "displayName": "yegāh" }, "availability": { "count": 35, "data": [ { "tuningSystem": { "id": "ronzevalle_1904", "idName": "ronzevalle_1904", "displayName": "Ronzevalle (1904) Modernist Arabic Tuning", "version": "2025-11-26T10:19:38.569Z" }, "startingNotes": [ { "startingNote": { "idName": "ushayran", "displayName": "ʿushayrān" }, "pitchClassIndex": 20, "octave": 0 }, { "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClassIndex": 0, "octave": 1 } ] }, { "tuningSystem": { "id": "alkindi_874", "idName": "alkindi_874", "displayName": "al-Kindī (874) 12-Tone", "version": "2025-11-17T13:16:34.754Z" }, "startingNotes": [ { "startingNote": { "idName": "ushayran", "displayName": "ʿushayrān" }, "pitchClassIndex": 10, "octave": 0 }, { "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClassIndex": 0, "octave": 1 }, { "startingNote": { "idName": "rast", "displayName": "rāst" }, "pitchClassIndex": 7, "octave": 0 } ] }, { "tuningSystem": { "id": "angloeuropean_1700", "idName": "angloeuropean_1700", "displayName": "Anglo-European (1700) 12-EDO", "version": "2025-11-18T11:53:58.428Z" }, "startingNotes": [ { "startingNote": { "idName": "ushayran", "displayName": "ʿushayrān" }, "pitchClassIndex": 10, "octave": 0 }, { "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClassIndex": 0, "octave": 1 } ] }, { "tuningSystem": { "id": "aldik_1926a", "idName": "aldik_1926a", "displayName": "al-Dīk (1926a) al-Sullam al-Fārsī or al-'Arabī (!!!)", "version": "2025-10-18T19:42:23.643Z" }, "startingNotes": [ { "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClassIndex": 0, "octave": 1 } ] }, { "tuningSystem": { "id": "aldik_1926b", "idName": "aldik_1926b", "displayName": "al-Dīk (1926b) Old Arabic Scale", "version": "2025-10-18T19:42:23.643Z" }, "startingNotes": [ { "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClassIndex": 0, "octave": 1 } ] }, { "…": "truncated — 30 more items" } ] }, "links": { "self": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability", "detail": "https://diarmaqar.net/api/pitch-classes/note-names/yegah", "compare": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/compare" } } ``` ### Compare pitch class by note name across tuning systems {#comparePitchClassByNoteName} ``` GET /pitch-classes/note-names/{noteName}/compare ``` Compare a pitch class (by note name) across different tuning systems. Returns comprehensive data for each tuning system including: * Pitch class data in the requested format * Context information (tuning system, starting note, reference frequency) **Path Parameters:** * `noteName`: URL-safe note name (e.g., "rast", "dugah", "nawa") (string) **(required)** * Example: `rast` **Query Parameters:** * `tuningSystems` **(required)**: Comma-separated tuning system IDs, or `all` for every tuning system (cannot be combined with explicit IDs). - Type: `string` * Example: `meshshaqa_1899,cairocongresstuningcommittee_1929` * `startingNote` **(required)**: Starting note (applies to all tuning systems), or "all" to include all available starting notes for each tuning system. - Type: `string` * Example: `yegah` * `pitchClassDataType` (optional): Pitch class data format (defaults to `all` when omitted, matching the handler) - Type: `string` - Valid values: `all`, `abjadName`, `englishName`, `solfege`, `fraction`, ... (14 total) - Default: `all` * Example: `cents` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/pitch-classes/note-names/rast/compare?tuningSystems=meshshaqa_1899,cairocongresstuningcommittee_1929&startingNote=yegah&includeArabic=true" ``` **Response:** Comparison data retrieved successfully **Example response:** ```json { "context": { "noteName": { "idName": "yegah", "displayName": "yegāh" } }, "comparisons": [ { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-11-09T00:44:40.275Z" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClass": { "pitchClassIndex": 0, "octave": 1, "noteName": "yegah", "noteNameDisplay": "yegāh", "cents": 0 }, "context": { "referenceFrequency": 97.999, "pitchClassDataType": "cents" } }, { "tuningSystem": { "id": "alfarabi_950g", "idName": "alfarabi_950g", "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone", "version": "2025-10-18T19:42:23.643Z" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "pitchClass": { "pitchClassIndex": 0, "octave": 1, "noteName": "yegah", "noteNameDisplay": "yegāh", "cents": 0 }, "context": { "referenceFrequency": 97.999, "pitchClassDataType": "cents" } } ], "meta": { "totalComparisons": 2, "successfulComparisons": 2, "failedComparisons": 0 }, "links": { "self": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/compare?tuningSystems=ibnsina_1037%2Calfarabi_950g&pitchClassDataType=cents&startingNote=yegah", "detail": "https://diarmaqar.net/api/pitch-classes/note-names/yegah", "availability": "https://diarmaqar.net/api/pitch-classes/note-names/yegah/availability" } } ``` *** ## Intervals ### Calculate intervals by note names {#calculateIntervalsByNoteNames} ``` GET /intervals ``` Get interval calculations for 2 or more pitch classes by listing their note names. Calculates intervals between consecutive note names: \[0→1, 1→2, 2→3, ...] Supports: * Single tuning system with specific starting note * Single tuning system with startingNote="all" (returns array for all starting notes) * All tuning systems (returns array for all tuning systems and starting notes) Note: When querying by note names, the pitchClassIndex field is excluded from interval responses as it is not meaningful in this context. **Query Parameters:** * `noteNames` **(required)**: Comma-separated note names (e.g., "rast,dugah,segah"). Note names can come from any octave. - Type: `string` * Example: `rast,dugah,segah` * `tuningSystem` (optional): Tuning system ID. - Type: `string` * Example: `alsabbagh_1954` * `startingNote` (optional): Starting note. * Use "all" to include all available starting notes for that tuning system (returns array of results, one per starting note) Note: Since note names are unique per octave, each note name already identifies its octave. No octave parameter is needed. Use `yegah` for IbnSina/Meshshaqa, `ushayran` for al-Farabi/al-Kindi, `rast` for CairoCongress/al-Sabbagh * Type: `string` * Example: `rast` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/intervals?noteNames=rast,dugah,segah&includeArabic=true" ``` **Response:** Interval calculations retrieved successfully **Example response:** ```json { "context": { "noteNames": [ { "idName": "yegah", "displayName": "yegāh" }, { "idName": "dugah", "displayName": "dūgāh" }, { "idName": "segah", "displayName": "segāh" } ] }, "intervals": [ { "tuningSystemContext": { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-11-09T00:44:40.275Z" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "referenceFrequency": 97.999 }, "fromNote": { "idName": "yegah", "displayName": "yegāh" }, "toNote": { "idName": "dugah", "displayName": "dūgāh" }, "intervalData": { "fraction": "3/2", "cents": 701.9550008653874, "decimalRatio": 1.5, "stringLength": -333.33333333333337, "fretDivision": 333.333, "originalValue": "3/2", "originalValueType": "fraction" } }, { "tuningSystemContext": { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-11-09T00:44:40.275Z" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "referenceFrequency": 97.999 }, "fromNote": { "idName": "dugah", "displayName": "dūgāh" }, "toNote": { "idName": "segah", "displayName": "segāh" }, "intervalData": { "fraction": "13/12", "cents": 138.57266090392318, "decimalRatio": 1.0833333333333333, "stringLength": -51.28205128205127, "fretDivision": 51.28199999999998, "originalValue": "13/12", "originalValueType": "fraction" } } ], "links": { "self": "https://diarmaqar.net/api/intervals?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents¬eNames=yegah%2Cdugah%2Csegah", "compare": "https://diarmaqar.net/api/intervals/compare?noteNames=yegah,dugah,segah" } } ``` ### Compare intervals across tuning systems {#compareIntervalsByNoteNames} ``` GET /intervals/compare ``` Compare interval calculations for 2+ pitch classes across different tuning systems by listing their note names. Calculates intervals between consecutive note names: \[0→1, 1→2, 2→3, ...] Note: When querying by note names, the pitchClassIndex field is excluded from interval responses as it is not meaningful in this context. **Query Parameters:** * `noteNames` **(required)**: Comma-separated note names. Note names can come from any octave. - Type: `string` * Example: `rast,dugah,segah` * `tuningSystems` **(required)**: Comma-separated tuning system IDs, or `all` for every tuning system (cannot be combined with explicit IDs). - Type: `string` * Example: `alfarabi_950g,cairocongresstuningcommittee_1929` * `startingNote` **(required)**: Starting note (applies to all tuning systems), or "all" to include all available starting notes for each tuning system. - Type: `string` * Example: `ushayran` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/intervals/compare?noteNames=rast,dugah,segah&tuningSystems=alfarabi_950g,cairocongresstuningcommittee_1929&startingNote=ushayran&includeArabic=true" ``` **Response:** Comparison data retrieved successfully **Example response:** ```json { "context": { "noteNames": [ { "idName": "yegah", "displayName": "yegāh" }, { "idName": "dugah", "displayName": "dūgāh" }, { "idName": "segah", "displayName": "segāh" } ] }, "comparisons": [ { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037) 7-Fret Oud 17-Tone", "version": "2025-11-09T00:44:40.275Z" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "intervals": [ { "from": { "idName": "yegah", "displayName": "yegāh" }, "to": { "idName": "dugah", "displayName": "dūgāh" }, "interval": { "fraction": "3/2", "cents": 701.9550008653874, "decimalRatio": 1.5, "stringLength": -333.33333333333337, "fretDivision": 333.333, "originalValue": "3/2", "originalValueType": "fraction" } }, { "from": { "idName": "dugah", "displayName": "dūgāh" }, "to": { "idName": "segah", "displayName": "segāh" }, "interval": { "fraction": "13/12", "cents": 138.57266090392318, "decimalRatio": 1.0833333333333333, "stringLength": -51.28205128205127, "fretDivision": 51.28199999999998, "originalValue": "13/12", "originalValueType": "fraction" } } ], "context": { "referenceFrequency": 97.999 } }, { "tuningSystem": { "id": "alfarabi_950g", "idName": "alfarabi_950g", "displayName": "al-Fārābī (950g) First Oud Tuning (Full First Octave) 27-Tone", "version": "2025-10-18T19:42:23.643Z" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "intervals": [ { "from": { "idName": "yegah", "displayName": "yegāh" }, "to": { "idName": "dugah", "displayName": "dūgāh" }, "interval": { "fraction": "3/2", "cents": 701.9550008653874, "decimalRatio": 1.5, "stringLength": -333.33333333333337, "fretDivision": 333.333, "originalValue": "3/2", "originalValueType": "fraction" } }, { "from": { "idName": "dugah", "displayName": "dūgāh" }, "to": { "idName": "segah", "displayName": "segāh" }, "interval": { "fraction": "12/11", "cents": 150.63705850063081, "decimalRatio": 1.0909090909090908, "stringLength": -55.55555555555554, "fretDivision": 55.55599999999998, "originalValue": "12/11", "originalValueType": "fraction" } } ], "context": { "referenceFrequency": 97.999 } } ], "meta": { "totalComparisons": 2, "successfulComparisons": 2, "failedComparisons": 0 }, "links": { "self": "https://diarmaqar.net/api/intervals/compare?tuningSystems=ibnsina_1037%2Calfarabi_950g&startingNote=yegah&pitchClassDataType=cents¬eNames=yegah%2Cdugah%2Csegah", "intervals": "https://diarmaqar.net/api/intervals?noteNames=yegah,dugah,segah" } } ``` ### Calculate interval between two pitch classes {#calculateIntervalBetweenPitchClasses} ``` GET /intervals/calculate ``` Calculate the interval between two pitch classes in a specific tuning system. Supports flexible pitch class identification: * By note name (e.g., "rast", "dugah") * By value in any format: fraction (e.g., "3/2"), cents (e.g., "701.955"), decimalRatio (e.g., "1.5"), stringLength, or fretDivision Returns the interval in the requested unit format, plus all other unit formats for reference. **Query Parameters:** * `from` **(required)**: First pitch class identifier (note name or value) - Type: `string` * Example: `rast` * `to` **(required)**: Second pitch class identifier (note name or value) - Type: `string` * Example: `dugah` * `tuningSystem` **(required)**: Tuning system ID - Type: `string` * Example: `ibnsina_1037` * `startingNote` **(required)**: Starting note for the tuning system - Type: `string` * Example: `yegah` * `unit` **(required)**: Output unit format for the interval - Type: `string` - Valid values: `fraction`, `cents`, `centsFromZero`, `decimalRatio`, `stringLength`, `fretDivision` * Example: `cents` * `fromType` (optional): Type of 'from' value if it's a value (not a note name). Required if 'from' is a value and cannot be auto-detected.. Required if 'from' is a value and cannot be auto-detected. * Type: `string` - Valid values: `fraction`, `cents`, `decimalRatio`, `stringLength`, `fretDivision` * Example: `fraction` * `toType` (optional): Type of 'to' value if it's a value (not a note name). Required if 'to' is a value and cannot be auto-detected.. Required if 'to' is a value and cannot be auto-detected. * Type: `string` - Valid values: `fraction`, `cents`, `decimalRatio`, `stringLength`, `fretDivision` * Example: `fraction` * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/intervals/calculate?from=rast&to=dugah&tuningSystem=ibnsina_1037&startingNote=yegah&unit=cents&includeArabic=true" ``` **Response:** Interval calculated successfully **Example response — noteNames:** ```json { "context": { "tuningSystem": { "id": "ibnsina_1037", "idName": "ibnsina_1037", "displayName": "Ibn Sīnā (1037)" }, "startingNote": { "idName": "yegah", "displayName": "yegāh" }, "referenceFrequency": 97.999 }, "from": { "pitchClass": { "pitchClassIndex": 0, "octave": 0, "noteName": "yegah", "noteNameDisplay": "yegāh", "englishName": "D", "solfege": "re", "abjadName": "د", "fraction": "1/1", "cents": 0, "decimalRatio": 1, "stringLength": 1000, "fretDivision": 0 }, "identifier": { "idName": "yegah", "displayName": "yegāh" } }, "to": { "pitchClass": { "pitchClassIndex": 1, "octave": 0, "noteName": "dugah", "noteNameDisplay": "dūgāh", "englishName": "E", "solfege": "mi", "abjadName": "ه", "fraction": "9/8", "cents": 203.91, "decimalRatio": 1.125, "stringLength": 888.889, "fretDivision": 102 }, "identifier": { "idName": "dugah", "displayName": "dūgāh" } }, "interval": { "value": 203.91, "unit": "cents", "allUnits": { "fraction": "9/8", "cents": 203.91, "decimalRatio": 1.125, "stringLength": 111.111, "fretDivision": 102 } }, "links": { "self": "https://diarmaqar.net/api/intervals/calculate?from=yegah&to=dugah&tuningSystem=ibnsina_1037&startingNote=yegah&unit=cents", "tuningSystem": "https://diarmaqar.net/api/tuning-systems/ibnsina_1037", "intervals": "https://diarmaqar.net/api/intervals?noteNames=yegah,dugah&tuningSystem=ibnsina_1037&startingNote=yegah" } } ``` *** ## Sources ### List all bibliographic sources {#listSources} ``` GET /sources ``` Return all bibliographic sources (books, articles, theses) with comprehensive metadata. * Includes titles, contributors, publication information, and version timestamps * Sources document the historical and scholarly foundation for the archive's musical data * All sources include common fields (edition, publication date, URL, etc.) * Type-specific fields are included based on sourceType: * Books: publisher, place, ISBN, original publication date * Articles: journal, volume, issue, page range, DOI * Theses: degree type, university, department, database information **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/sources?includeArabic=true" ``` **Response:** List of sources retrieved successfully **Example response — comprehensive:** ```json { "count": 2, "data": [ { "id": "alkhulai_1904_2011", "displayName": "al-khulai-(1904/2011)", "citation": "al-Khulaʿī 1904/2011", "citationAr": "الخلعي 1904/2011", "sourceType": "Book", "title": "Kitāb al-Mūsiqā al-Sharqī", "titleAr": "كتاب الموسيقى الشرقي", "contributors": [ { "type": "Author", "firstName": "Muḥammad Kāmil", "lastName": "al-Khulaʿī", "firstNameAr": "محمد كامل", "lastNameAr": "الخلعي" } ], "edition": "", "editionAr": "", "publicationDate": "2011", "publicationDateAr": "٢٠١١", "url": "https://www.hindawi.org/books/46319638/", "dateAccessed": "21-05-2025", "version": "2025-10-18T19:50:31.664Z", "originalPublicationDate": "1904", "originalPublicationDateAr": "١٩٠٤", "publisher": "Hindawi Foundation for Education and Culture", "publisherAr": "مؤسسة هنداوي للتعليم والثقافة", "place": "Cairo", "placeAr": "القاهرة", "ISBN": "9789776416543" }, { "id": "farmer_1937", "displayName": "farmer-(1937)", "citation": "Farmer 1937", "citationAr": "فارمر 1937", "sourceType": "Article", "title": "The Lute Scale of Avicenna", "titleAr": "سلم العود لإبن سينا", "contributors": [ { "type": "Author", "firstName": "Henry George", "lastName": "Farmer", "firstNameAr": "هنري جورج", "lastNameAr": "فارمر" } ], "edition": "", "editionAr": "", "publicationDate": "1937", "publicationDateAr": "١٩٣٧", "url": "", "dateAccessed": "", "version": "2025-10-18T19:50:31.664Z", "journal": "The Journal of the Royal Asiatic Society of Great Britain and Ireland", "journalAr": "مجلة الجمعية الملكية الآسيوية في بريطانيا العظمى وأيرلندا", "volume": "2", "volumeAr": "٢", "issue": "", "issueAr": "", "pageRange": "245–257", "pageRangeAr": "٢٤٥-٢٥٧", "DOI": "" }, { "id": "allami_2022", "displayName": "allami-(2022)", "citation": "Allami 2022", "citationAr": "اللامي 2022", "sourceType": "Thesis", "title": "Échos-monde: Towards a hybrid repertoire of contemporary and experimental acoustic, electroacoustic and electronic Arabic music", "titleAr": "‎عالم الأصداء: نحو رصيدٍ هجينٍ للموسيقى العربية المعاصرة والتجريبية، صوتياً وكهروصوتياً وإلكترونياً", "contributors": [ { "type": "Author", "firstName": "Khyam", "lastName": "Allami", "firstNameAr": "خيّام", "lastNameAr": "اللامي" } ], "edition": "", "editionAr": "", "publicationDate": "2022", "publicationDateAr": "", "url": "https://www.open-access.bcu.ac.uk/14036/", "dateAccessed": "16-10-2025", "version": "2025-10-23T22:32:56.276Z", "degreeType": "PhD Dissertation", "degreeTypeAr": "أطروحة دكتوراه", "university": "Birmingham City University", "universityAr": "جامعة برمنغهام سيتي", "department": "Royal Birmingham Conservatoire", "departmentAr": "معهد برمنغهام الملكي", "databaseIdentifier": "", "databaseName": "" } ], "meta": { "total": 17 } } ``` ### Get a single bibliographic source {#getSource} ``` GET /sources/{id} ``` Return detailed information for a single bibliographic source by ID. * Returns comprehensive bibliographic metadata for the specified source * Includes all common fields (title, contributors, publication date, etc.) * Includes type-specific fields based on sourceType: * Books: publisher, place, ISBN, original publication date * Articles: journal, volume, issue, page range, DOI * Theses: degree type, university, department, database information * Supports bilingual responses (English/Arabic) via includeArabic parameter **Path Parameters:** * `id`: The unique identifier for the bibliographic source. Examples: * `alkhulai_1904_2011` - Book source ID (URL-safe, diacritics removed) * `farmer_1937` - Article source ID * `allami_2022` - Thesis source ID **Note**: Source IDs use only the publication date (not original publication date) and are URL-safe with diacritics removed for compatibility. Use the `/api/sources` endpoint to retrieve all available source IDs. (string) **(required)** * Example: `farmer_1937` **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., titleAr, firstNameAr, lastNameAr) * Contributors get Arabic name versions in firstNameAr and lastNameAr fields * Type-specific fields get Arabic versions (e.g., publisherAr, journalAr, universityAr) * Display name gets Arabic version in displayNameAr field * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/sources/farmer_1937?includeArabic=true" ``` **Response:** Source retrieved successfully **Example response — book:** ```json { "source": { "id": "alkhulai_1904_2011", "displayName": "al-khulai-(1904/2011)", "citation": "al-Khulaʿī 1904/2011", "sourceType": "Book", "title": "Kitāb al-Mūsiqā al-Sharqī", "contributors": [ { "type": "Author", "firstName": "Muḥammad Kāmil", "lastName": "al-Khulaʿī" } ], "edition": "", "publicationDate": "2011", "url": "https://www.hindawi.org/books/46319638/", "dateAccessed": "21-05-2025", "version": "2025-10-18T19:50:31.664Z", "originalPublicationDate": "1904", "publisher": "Hindawi Foundation for Education and Culture", "place": "Cairo", "ISBN": "9789776416543" } } ``` ### List tuning systems by source {#listTuningSystemsBySource} ``` GET /sources/{id}/tuning-systems ``` Returns all tuning systems that reference the specified source. A tuning system is included if any of its sourcePageReferences match the source ID. This endpoint provides an easy way to see which tuning systems have been derived from a specific source. **Path Parameters:** * `id`: The unique identifier for the bibliographic source. Use the `/api/sources` endpoint to retrieve all available source IDs. (string) **(required)** * Example: `farmer_1937` **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/sources/farmer_1937/tuning-systems?includeArabic=true" ``` **Response:** Tuning systems retrieved successfully **Example response:** ```json { "context": { "source": { "id": "alsabbagh_1954", "idName": "alsabbagh_1954", "displayName": "al-Anghām al-Sharqīya: al-Qism al-Thānī min kitāb al-Dalīl al-Mūsīqī al-ʿĀm fi Aṭrab al-Anghām" } }, "count": 1, "data": [ { "tuningSystem": { "id": "alsabbagh_1954", "idName": "alsabbagh_1954", "displayName": "al-Ṣabbāgh (1954) Contemporary Arabic Tuning 24-Tone", "version": "2026-08-05T14:14:27.676Z", "year": "1954" }, "sourceReferences": [ { "page": "47" } ], "startingNotes": [ "rast" ], "links": { "detail": "https://diarmaqar.net/api/tuning-systems/alsabbagh_1954", "source": "https://diarmaqar.net/api/sources/alsabbagh_1954" } } ] } ``` ### List maqamat by source {#listMaqamatBySource} ``` GET /sources/{id}/maqamat ``` Returns all maqamat that reference the specified source. A maqam is included if any of its sourcePageReferences match the source ID. This endpoint provides an easy way to see which maqamat have been documented in a specific source. **Path Parameters:** * `id`: The unique identifier for the bibliographic source. Use the `/api/sources` endpoint to retrieve all available source IDs. (string) **(required)** * Example: `alshawwa_1946` **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/sources/alshawwa_1946/maqamat?includeArabic=true" ``` **Response:** Maqamat retrieved successfully **Example response:** ```json { "context": { "source": { "id": "alshawwa_1946", "idName": "alshawwa_1946", "displayName": "al-Qawaʿid al-Fannīya fī al-Mūsiqa al-Sharqīya wa al-Gharbīya" } }, "count": 36, "data": [ { "maqam": { "id": "1", "idName": "maqam_rast", "displayName": "maqām rāst", "version": "2025-12-10T17:03:34.565Z" }, "sourceReferences": [ { "page": "42" } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_rast", "source": "https://diarmaqar.net/api/sources/alshawwa_1946" } }, { "maqam": { "id": "6", "idName": "maqam_nawa_athar", "displayName": "maqām nawā athar", "version": "2025-12-10T18:28:28.107Z" }, "sourceReferences": [ { "page": "52" } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_nawa_athar", "source": "https://diarmaqar.net/api/sources/alshawwa_1946" } }, { "maqam": { "id": "10", "idName": "maqam_nahawand", "displayName": "maqām nahāwand", "version": "2025-10-18T19:41:17.132Z" }, "sourceReferences": [ { "page": "49" } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_nahawand", "source": "https://diarmaqar.net/api/sources/alshawwa_1946" } }, { "maqam": { "id": "11", "idName": "maqam_nahawand_kabir", "displayName": "maqām nahāwand kabīr", "version": "2025-10-18T19:41:17.132Z" }, "sourceReferences": [ { "page": "50" } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_nahawand_kabir", "source": "https://diarmaqar.net/api/sources/alshawwa_1946" } }, { "maqam": { "id": "17", "idName": "maqam_ajam_ushayran", "displayName": "maqām ʿajam ʿushayrān", "version": "2025-10-18T19:41:17.132Z" }, "sourceReferences": [ { "page": "30" } ], "links": { "detail": "https://diarmaqar.net/api/maqamat/maqam_ajam_ushayran", "source": "https://diarmaqar.net/api/sources/alshawwa_1946" } }, { "…": "truncated — 31 more items" } ] } ``` ### List ajnas by source {#listAjnasBySource} ``` GET /sources/{id}/ajnas ``` Returns all ajnas that reference the specified source. A jins is included if any of its SourcePageReferences match the source ID. This endpoint provides an easy way to see which ajnas have been documented in a specific source. **Path Parameters:** * `id`: The unique identifier for the bibliographic source. Use the `/api/sources` endpoint to retrieve all available source IDs. (string) **(required)** * Example: `alshawwa_1946` **Query Parameters:** * `includeArabic` (optional): Return bilingual responses with Arabic script when true. * All English/transliteration fields remain unchanged * Arabic versions are added with "Ar" suffix (e.g., displayNameAr, noteNameDisplayAr) * Note names, maqām names, and jins names get Arabic versions in \*Ar fields * Comments get Arabic versions in commentsAr if available * Tuning system display names get Arabic versions in displayNameAr if available * Source metadata gets Arabic versions in \*Ar fields (titleAr, firstNameAr, etc.) * Type: `string` - Valid values: `true`, `false` - Default: `false` * Example: `true` **Example:** ```bash curl "https://diarmaqar.net/api/sources/alshawwa_1946/ajnas?includeArabic=true" ``` **Response:** Ajnas retrieved successfully **Example response:** ```json { "context": { "source": { "id": "alshawwa_1946", "idName": "alshawwa_1946", "displayName": "al-Qawaʿid al-Fannīya fī al-Mūsiqa al-Sharqīya wa al-Gharbīya" } }, "count": 2, "data": [ { "jins": { "id": "21", "idName": "jins_buselik_alshawwa", "displayName": "jins būselīk (al-Shawwā)", "version": "2025-10-18T19:34:26.343Z" }, "sourceReferences": [ { "page": "70" } ], "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_buselik_alshawwa", "source": "https://diarmaqar.net/api/sources/alshawwa_1946" } }, { "jins": { "id": "24", "idName": "jins_awj_ara", "displayName": "jins awj ʾārāʾ", "version": "2025-10-18T19:34:26.343Z" }, "sourceReferences": [ { "page": "38" } ], "links": { "detail": "https://diarmaqar.net/api/ajnas/jins_awj_ara", "source": "https://diarmaqar.net/api/sources/alshawwa_1946" } } ] } ``` *** ## Statistics ### Get archive statistics {#getStatistics} ``` GET /statistics ``` Return the archive's totals and, for every tuning system on every starting note, how many ajnās and maqāmāt it can build, how many transpositions (taṣwīr) and octave renderings they have, and how many modulations their forms allow. Each maqām or jins has three kinds of form in a tuning system: * **base form**: the maqām on its own notes, e.g. maqām rāst on rāst * **transposition** (taṣwīr): moved onto another tonic, e.g. maqām rāst al-nawā * **octave rendering**: the base form or a taṣwīr one or more octaves away, e.g. maqām rāst on qarār rāst. Not a taṣwīr, so never counted in `transpositions`. Modulations follow al-Shawwā's 1946 guidelines. Each form's options are counted degree by degree, as GET /maqamat/{idName} lists them, then summed over the forms: a target on the sixth degree that qualifies both ascending and descending counts 2. They are kept apart by the kind of form they start from (`fromBaseForms`, `fromTranspositions`, `fromOctaveRenderings`); base forms plus transpositions is the headline figure the statistics page shows. The numbers are computed before a deploy whenever the data they count has changed, not per request. They carry a `dataFingerprint` of that data and the time they were computed (`generatedAt`). **Example:** ```bash curl "https://diarmaqar.net/api/statistics" ``` **Response:** Archive statistics retrieved successfully **Example response — oneRow:** ```json { "dataFingerprint": "4f1c…", "generatedAt": "2026-11-10T19:30:00.000Z", "archive": { "tuningSystems": 28, "tuningSystemStartingNotes": 48, "maqamat": 145, "ajnas": 44, "suyur": 193, "sources": 19, "patterns": 7 }, "count": 48, "data": [ { "tuningSystem": { "id": "ronzevalle_1904", "idName": "ronzevalle_1904", "displayName": "Ronzevalle (1904) Modernist Arabic Tuning", "year": "1904" }, "startingNote": { "idName": "ushayran", "displayName": "ʿushayrān" }, "ajnas": { "possible": 42, "total": 44, "transpositions": 3440, "octaveRenderings": 118 }, "maqamat": { "possible": 105, "total": 145, "transpositions": 7383, "octaveRenderings": 212, "suyur": 129 }, "modulations": { "fromBaseForms": { "maqamat": 50523, "ajnas": 20286 }, "fromTranspositions": { "maqamat": 1776759, "ajnas": 815983 }, "fromOctaveRenderings": { "maqamat": 91504, "ajnas": 40647 } }, "links": { "maqamat": "https://diarmaqar.net/api/tuning-systems/ronzevalle_1904/ushayran/maqamat", "ajnas": "https://diarmaqar.net/api/tuning-systems/ronzevalle_1904/ushayran/ajnas" } } ], "links": { "self": "https://diarmaqar.net/api/statistics" } } ``` *** --- --- url: /docs/README DiArMaqAr Tuning System JSON Data Export.md --- # Digital Arabic Maqām Archive (DiArMaqAr) ## README • Tuning System Export Data Format ## Overview This document describes the structure and contents of comprehensive tuning system export files from the Maqām Network. These JSON exports contain complete musical data for a specific historical tuning system, including all available maqāmāt and ajnās, their transpositions, and modulation relationships. ## Table of Contents * [Quick Start](#quick-start) * [Common Tasks](#common-tasks) * [File Structure](#file-structure) * [Export Tree Diagram](#export-tree-diagram) * [Legend](#legend) * [Export Metadata](#export-metadata) * [Tuning System Information](#tuning-system-information) * [Tuning System Pitch Classes](#tuning-system-pitch-classes) * [Summary Statistics](#summary-statistics) * [Pitch Class Reference](#pitch-class-reference) * [Maqām Family Reference](#maqām-family-reference) * [Ajnās Data](#ajnās-data) * [Maqāmāt Data](#maqāmāt-data) * [JSON Structure Elements](#json-structure-elements) * [Keys vs Objects vs References](#keys-vs-objects-vs-references) * [Object Keys](#object-keys) * [Reference Values](#reference-values) * [Data Objects](#data-objects) * [Arrays](#arrays) * [Data Navigation](#data-navigation) * [Finding Specific Content](#finding-specific-content) * [Working with Transpositions](#working-with-transpositions) ## Quick Start **Just need the basics?** Start here. Each export file contains: 1. **`summaryStats`** — Quick facts: How many maqāmāt? How many ajnās? How many pitch classes? 2. **`tuningSystemData`** — Metadata: Creator, year, source, tuning details 3. **`tuningSystemPitchClasses[]`** — All pitch class names (keys to look up in `pitchClassReference`) 4. **`allMaqamatData{}`** — Complete maqāmāt with their structure and relationships 5. **`allAjnasData{}`** — Ajnās that form the basis of maqāmāt 6. **`pitchClassReference{}`** — Detailed info on each pitch: fractions, cents, string lengths **The core insight:** Maqāmāt are built from ajnās, which are built from pitch classes. Use `ascendingMaqamAjnas` and `descendingMaqamAjnas` to see which ajnās are used on each degree of a maqām. ## Common Tasks **Looking for something specific?** Try these navigation patterns. ### Find all maqāmāt available in this tuning ``` Look at: summaryStats.maqamatAvailableInTuning Then: Iterate through allMaqamatData keys where isBaseForm: true for base forms ``` ### See which ajnās make up a maqām ``` For any maqam in allMaqamatData: - Check ascendingMaqamAjnas {} to see ascending structure - Check descendingMaqamAjnas {} to see descending structure - Each maps pitch class name → jins reference - Look up that jins reference in allAjnasData ``` ### Understand a maqām's pitch structure ``` For any maqam in allMaqamatData: - ascendingPitchClasses[]: Names of pitches in ascending order - ascendingPitchClassIntervals[]: Size of each step (as fractions, cents, string lengths) - Use pitchClassReference to look up each pitch class and access its fractions, cents, cents deviations, and string lengths ``` ### See how two maqāmāt modulate into each other ``` For any maqam in allMaqamatData: - Check maqamToMaqamModulations.maqamToMaqamModulations - Each degree (first, third, fourth, etc.) has an array of possible maqāmāt to modulate to - Look up each maqām reference in allMaqamatData ``` ### Find pitch frequency information ``` For any pitch name (e.g., "rast"): - Look in pitchClassReference using key like "rast" or "qarar_rast" - Properties available: frequency (Hz), cents, fraction, decimalRatio, MIDI note ``` ### Understand the 4-octave system Arabic maqām theory traditionally spans 2 octaves. This system extends to 4 for broader instrument compatibility and extra detail. ## File Structure ### Export Tree Diagram ``` tuning-system-export.json ├── exportInfo │ └── timestamp ├── tuningSystemData │ ├── id │ ├── titleEnglish │ ├── titleArabic │ ├── year │ ├── sourceEnglish │ ├── sourceArabic │ ├── sourcePageReferences [] │ ├── creatorEnglish │ ├── creatorArabic │ ├── commentsEnglish │ ├── commentsArabic │ ├── startingNote │ ├── originalPitchClassValues [] │ ├── originalPitchClassNoteNames [[]] │ ├── abjadNames [] │ ├── stringLength │ ├── referenceFrequencies {} │ ├── defaultReferenceFrequency │ ├── saved │ └── version ├── tuningSystemPitchClasses [] ├── summaryStats │ ├── totalAjnasInDatabase │ ├── totalMaqamatInDatabase │ ├── tuningPitchClassesInSingleOctave │ ├── tuningPitchClassesInAllOctaves │ ├── ajnasAvailableInTuning │ ├── maqamatAvailableInTuning │ ├── totalAjnasTranspositions │ ├── totalMaqamatTranspositions │ ├── totalMaqamModulations │ └── totalAjnasModulations ├── pitchClassReference │ ├── qarar_ushayran {} │ ├── ... (all pitch classes across 4 octaves) │ └── jawab_jawab_tik_hisar {} ├── maqamFamilyReference │ ├── rast {} │ ├── ... (all maqām families) │ └── chahargah {} ├── allAjnasData │ ├── jins_rast_nawa │ │ ├── jinsId │ │ ├── name │ │ ├── jinsPitchClasses [] │ │ ├── jinsPitchClassIntervals [] │ │ ├── transposition │ │ ├── isBaseForm │ │ ├── commentsEnglish │ │ ├── commentsArabic │ │ ├── SourcePageReferences [] │ │ └── version │ └── ... (additional ajnās following same structure) └── allMaqamatData ├── maqam_rast │ ├── maqamId │ ├── name │ ├── ascendingPitchClasses [] │ ├── descendingPitchClasses [] │ ├── ascendingPitchClassIntervals [] │ ├── descendingPitchClassIntervals [] │ ├── ascendingMaqamAjnas {} │ ├── descendingMaqamAjnas {} │ ├── suyur [] │ │ ├── id │ │ ├── creatorEnglish │ │ ├── creatorArabic │ │ ├── sourceId │ │ ├── page │ │ ├── commentsEnglish │ │ ├── commentsArabic │ │ ├── stops [] │ │ └── version │ ├── transposition │ ├── isBaseForm │ ├── commentsEnglish │ ├── commentsArabic │ ├── SourcePageReferences [] │ ├── version │ ├── maqamFamilyClassification │ │ └── firstJins │ │ └── familyName │ ├── maqamToMaqamModulations │ │ ├── maqamToMaqamModulationsDegreesNoteNames {} │ │ ├── maqamToMaqamModulationsLowerOctaveDegreesNoteNames {} │ │ ├── maqamToMaqamModulations {} │ │ │ ├── maqamToMaqamModulationsOnFirstDegree [] │ │ │ ├── maqamToMaqamModulationsOnThirdDegree [] │ │ │ ├── maqamToMaqamModulationsOnAltThirdDegree [] │ │ │ ├── maqamToMaqamModulationsOnFourthDegree [] │ │ │ ├── maqamToMaqamModulationsOnFifthDegree [] │ │ │ ├── maqamToMaqamModulationsOnSixthDegreeAsc [] │ │ │ ├── maqamToMaqamModulationsOnSixthDegreeDesc [] │ │ │ ├── maqamToMaqamModulationsOnSixthDegreeIfNoThird [] │ │ │ └── maqamToMaqamModulationsNisfBelowThirdNoteName │ │ └── maqamToMaqamModulationsLowerOctave {} │ │ ├── maqamToMaqamModulationsOnFirstDegree8vb [] │ │ ├── maqamToMaqamModulationsOnThirdDegree8vb [] │ │ ├── maqamToMaqamModulationsOnAltThirdDegree8vb [] │ │ ├── maqamToMaqamModulationsOnFourthDegree8vb [] │ │ ├── maqamToMaqamModulationsOnFifthDegree8vb [] │ │ ├── maqamToMaqamModulationsOnSixthDegreeAsc8vb [] │ │ ├── maqamToMaqamModulationsOnSixthDegreeDesc8vb [] │ │ ├── maqamToMaqamModulationsOnSixthDegreeIfNoThird8vb [] │ │ └── maqamToMaqamModulationsNisfBelowThird8vb │ └── maqamToJinsModulations │ ├── maqamToJinsModulationDegreesNoteNames {} │ ├── maqamToJinsModulationsLowerOctaveDegreesNoteNames {} │ ├── maqamToJinsModulations {} │ │ ├── maqamToJinsModulationsOnFirstDegree [] │ │ ├── maqamToJinsModulationsOnThirdDegree [] │ │ ├── maqamToJinsModulationsOnAltThirdDegree [] │ │ ├── maqamToJinsModulationsOnFourthDegree [] │ │ ├── maqamToJinsModulationsOnFifthDegree [] │ │ ├── maqamToJinsModulationsOnSixthDegreeAsc [] │ │ ├── maqamToJinsModulationsOnSixthDegreeDesc [] │ │ ├── maqamToJinsModulationsOnSixthDegreeIfNoThird [] │ │ └── maqamToJinsNoteNameNisfBelowThird │ └── maqamToJinsModulationsLowerOctave {} │ ├── maqamToJinsModulationsOnFirstDegree8vb [] │ ├── maqamToJinsModulationsOnThirdDegree8vb [] │ ├── maqamToJinsModulationsOnAltThirdDegree8vb [] │ ├── maqamToJinsModulationsOnFourthDegree8vb [] │ ├── maqamToJinsModulationsOnFifthDegree8vb [] │ ├── maqamToJinsModulationsOnSixthDegreeAsc8vb [] │ ├── maqamToJinsModulationsOnSixthDegreeDesc8vb [] │ ├── maqamToJinsModulationsOnSixthDegreeIfNoThird8vb [] │ └── maqamToJinsNoteNameNisfBelowThird8vb └── ... (additional maqāmāt following same structure) ``` ### **Legend:** \- {} = Object containing multiple properties \- \[] = Array of values \- \[\[]] = Array of arrays \- No symbol = Single value (string, number, boolean) ### Export Metadata ```json { "exportInfo": { "timestamp": "2025-09-28T20:25:10.371Z" } } ``` | Property | Description | Type | |----------|-------------|------| | `timestamp` | ISO 8601 timestamp indicating when this export file was generated | string | ### Tuning System Information ```json { "tuningSystemData": { "id": "ibnsina_1037", "titleEnglish": "7-Fret Oud 17-Tone", "titleArabic": "7 نغمات 17 دستان على العود", "year": "1037", "sourceEnglish": "", "sourceArabic": "", "sourcePageReferences": [], "creatorEnglish": "Ibn Sīnā", "creatorArabic": "إبن سينا", "commentsEnglish": "Farmer, H.G. (1937) 'The Lute Scale of Avicenna'...", "commentsArabic": "", "startingNote": "ushayran", "originalPitchClassValues": ["1/1", "273/256", "13/12", "9/8", "32/27", "39/32", "81/64", "4/3", "91/64", "13/9", "3/2", "128/81", "13/8", "27/16", "16/9", "91/48", "52/27"], "originalPitchClassNoteNames": [["ʿushayrān", "ʿajam ʿushayrān", "ʿirāq", "kawasht", "rāst", "nīm zīrgūleh", "zīrgūleh", "dūgāh", "kurdī", "segāh", "būselīk/ʿushshāq", "chahārgāh", "nīm ḥijāz", "ḥijāz", "nawā", "ḥiṣār", "tīk ḥiṣār"]], "abjadNames": ["", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""], "stringLength": 1000, "referenceFrequencies": {"yegāh": 97.999, "ʿushayrān": 110}, "defaultReferenceFrequency": 97.999, "saved": true, "version": "2025-10-18T19:41:17.132Z" } } ``` ### Tuning System Information Properties | Property | Description | Type | |----------|-------------|------| | `id` | Unique identifier for this tuning system (e.g., composer name and year) | string | | `titleEnglish` | Title or description of the tuning system in English | string | | `titleArabic` | Title or description in Arabic | string | | `year` | Historical year or period of origin | string | | `sourceEnglish` | Primary bibliographic source title in English (may be empty) | string | | `sourceArabic` | Primary bibliographic source title in Arabic (may be empty) | string | | `sourcePageReferences[]` | Array of page references from the primary source | array | | `creatorEnglish` | Creator or documenter name in English | string | | `creatorArabic` | Creator or documenter name in Arabic | string | | `commentsEnglish` | Additional scholarly or historical context in English | string | | `commentsArabic` | Additional context in Arabic | string | | `startingNote` | Reference pitch class name for this tuning system | string | | `originalPitchClassValues[]` | Array of frequency ratios as defined in the bibliographic source | array | | `originalPitchClassNoteNames[][]` | Array of note name arrays assigned to the pitch class values in the source | array of arrays | | `abjadNames[]` | Traditional abjad notation assigned to pitch classes (if used in the source; empty otherwise) | array | | `stringLength` | Reference string length used for fret division calculations (in arbitrary units) | number | | `referenceFrequencies{}` | Object mapping specific note names to reference frequencies in Hz | object | | `defaultReferenceFrequency` | Default reference frequency in Hz if not specified per note | number | | `saved` | Database save status flag | boolean | | `version` | ISO 8601 timestamp of last modification | string | ### Tuning System Pitch Classes ```json { "tuningSystemPitchClasses": [ "qarar_ushayran", "qarar_ajam_ushayran", "qarar_iraq", "qarar_kawasht", "qarar_rast", "... (all pitch classes across 4 octaves)", "jawab_jawab_tik_hisar" ] } ``` The `tuningSystemPitchClasses` array contains all pitch class keys available in this tuning system across all four octaves. Use these keys to look up detailed information in `pitchClassReference`. ### Summary Statistics ```json { "summaryStats": { "totalAjnasInDatabase": 32, "totalMaqamatInDatabase": 60, "tuningPitchClassesInSingleOctave": 17, "tuningPitchClassesInAllOctaves": 68, "ajnasAvailableInTuning": 25, "maqamatAvailableInTuning": 39, "totalAjnasTranspositions": 244, "totalMaqamatTranspositions": 198, "totalMaqamModulations": 4799, "totalAjnasModulations": 5490 } } ``` | Property | Description | Type | |----------|-------------|------| | `totalAjnasInDatabase` | Total count of distinct ajnās in the core database | number | | `totalMaqamatInDatabase` | Total count of distinct maqāmāt in the core database | number | | `tuningPitchClassesInSingleOctave` | Number of distinct pitch classes in one octave of this tuning | number | | `tuningPitchClassesInAllOctaves` | Total pitch classes across all four octaves | number | | `ajnasAvailableInTuning` | Count of ajnās that can be realized with this tuning's pitch classes | number | | `maqamatAvailableInTuning` | Count of maqāmāt that can be realized with this tuning's pitch classes | number | | `totalAjnasTranspositions` | Total count of all ajnās transpositions (base forms + all transpositions at all starting notes) | number | | `totalMaqamatTranspositions` | Total count of all maqāmāt transpositions (base forms + all transpositions at all starting notes) | number | | `totalMaqamModulations` | Total count of all possible maqām-to-maqām modulation relationships | number | | `totalAjnasModulations` | Total count of all possible jins-to-jins modulation relationships | number | ## Pitch Class Reference The `pitchClassReference` section contains detailed information for each pitch class across all four octaves. Each entry uses the pitch class name as a key: ```json { "pitchClassReference": { "qarar_ushayran": { "noteName": "qarār ʿushayrān", "abjadName": "", "englishName": "A1", "pitchClassIndex": 0, "octave": 0, "originalValue": "1/2", "originalValueType": "fraction", "cents": "-1200", "centsDeviation": 0, "fraction": "1/2", "decimalRatio": "0.5", "stringLength": "2000", "fretDivision": "-1000.000", "midiNoteDecimal": 33, "referenceNoteName": "A1", "midiNoteDeviation": "33 0", "frequency": "55" }, // ... additional pitch classes for all four octaves } } ``` ### Pitch Class Properties Each pitch class contains the following properties. **Core properties** (needed to understand basic pitch information) are marked: | Property | Description | Type | |----------|-------------|------| | **`noteName`** ⭐ | Display name with proper diacritics for UI presentation | string | | **`octave`** ⭐ | Octave number (0–3): qarār (0), ʿushayrān (1), jawāb (2), jawāb jawāb (3) | number | | **`frequency`** ⭐ | Frequency in Hz, calculated from reference frequency | number | | **`cents`** ⭐ | Cents relative to this tuning's fundamental (0 cents = `1/1` ratio) | string | | **`englishName`** | International Pitch Notation equivalent (e.g., "G", "E-b"). Determined by maqām theory, not mathematical proximity to 12-EDO | string | | `pitchClassIndex` | 0-based position within a single octave (0–16 for 17-tone system). Index repeats across octaves to group pitch class types | number | | `fraction` | Frequency ratio as mathematical fraction relative to fundamental (`1/1`) | string | | `decimalRatio` | Frequency ratio as decimal relative to fundamental | string | | `originalValue` | Value from bibliographic source (may be fraction, decimal, or cents) | string | | `originalValueType` | Format type of source value: "fraction", "decimal", or "cents" | string | | `centsDeviation` | Deviation in cents from 12-EDO reference note (determined by maqām theory logic, not mathematical rounding) | number | | `stringLength` | String length relative to tuning system's reference (used for fret calculations on oud/qanun) | string | | `fretDivision` | Calculated fret position on reference string length (negative = position beyond open string) | string | | `referenceNoteName` | 12-EDO reference note (e.g., "A2", "C#2"). For pitches with modifiers (C-b, D-#), this is the natural note, NOT closest 12-EDO pitch | string | | `midiNoteDeviation` | MIDI note number + cents offset (e.g., "45 0" means MIDI 45 with 0 cents deviation). Deviation can exceed ±50 cents when referenced by maqām theory | string | | `abjadName` | Traditional abjad notation (if used). Populated for octaves 1–2 in systems with abjad notation; empty for octaves 0, 3 | string | | `midiNoteDecimal` | MIDI note with decimal/fractional precision for pitches between standard MIDI notes | number | ## Maqām Family Reference The maqamFamilyReference section provides a lookup table for maqām family display names used throughout the export. Each maqām belongs to a family (e.g., Maqām Rāst belongs to the Rāst family, Maqām Māhūr belongs to the Rāst family, etc.). This reference allows quick lookup of properly formatted family names with diacritics. ```json { "maqamFamilyReference": { "rast": { "displayName": "rāst" }, "hijaz": { "displayName": "ḥijāz" }, "bayyat": { "displayName": "bayyāt" } } } ``` ### Maqām Family Properties | Property | Description | Type | |----------|-------------|------| | Family Key (e.g., `rast`) | Reference identifier for the maqām family (lowercase, no diacritics or spaces) | string (object key) | | `displayName` | Display name with proper Arabic diacritics for use in UI and documentation | string | ## Ajnās Data The `allAjnasData` section contains all melodic genera available in the tuning system. Each jins includes pitch classes with pitch class intervals arrays: ```json { "allAjnasData": { "jins_bayyat": { "jinsId": "2", "name": "jins bayyāt", "jinsPitchClasses": ["dugah", "segah", "chahargah", "nawa"], "jinsPitchClassIntervals": [ { "fraction": "13/12", "cents": 138.57266090392324, "decimalRatio": 1.0833333333333333, "stringLength": -57.692307692307736, "fretDivision": 57.69200000000001, "pitchClassIndex": 2, "originalValue": "13/12", "originalValueType": "fraction" }, { "fraction": "128/117", "cents": 155.5623364999144, "decimalRatio": 1.0940170940170941, "stringLength": -59.495192307692264, "fretDivision": 59.49599999999998, "pitchClassIndex": 2, "originalValue": "128/117", "originalValueType": "fraction" }, { "fraction": "2187/2048", "cents": 113.68500605771214, "decimalRatio": 1.06787109375, "stringLength": -40.21990740740739, "fretDivision": 40.218999999999994, "pitchClassIndex": 2, "originalValue": "2187/2048", "originalValueType": "fraction" } ], "transposition": false, "isBaseForm": true, "commentsEnglish": "", "commentsArabic": "", "SourcePageReferences": [ {"sourceId": "alkhulai_1904_2011", "page": "55"}, {"sourceId": "alurmawialbaghdadi_1986_2017", "page": "23"} ], "version": "2025-10-18T19:34:26.343Z" } // ... additional ajnās } } ``` ### Ajnās Properties | Property | Description | Logic | |----------|-------------|-------| | `jinsId` | Core database ID linking to original jins definition. Multiple transpositions share same ID | Numerical identifier | | **`name`** | Display name with diacritics and spaces. Used for UI and documentation | Example: "jins bayyāt" | | **`jinsPitchClasses[]`** | Array of pitch class keys in ascending order. Use these keys to look up `pitchClassReference` for fractions, cents, and string lengths | `["dugah", "segah", "chahargah", "nawa"]` | | **`jinsPitchClassIntervals[]`** | Array of interval objects between consecutive pitches (see Interval Properties table below) | Computed from pitch frequency ratios | | `transposition` | Boolean: `true` for taṣwīr (transposed to a different modal degree), `false` for the base form **and** for its octave/register siblings, since a register shift is not taṣwīr | Distinguishes original vs transposed structures | | `isBaseForm` | Boolean: `true` only for the base form — the canonical form of this jins, from which its transpositions are derived. Every transposition of one jins repeats that jins's `jinsId`, and exactly one entry has `isBaseForm: true`. Use this, not `transposition`, to find base forms | Disambiguates the base form from its octave renderings | | `commentsEnglish` | Additional context, performance notes, or musicological context in English | May reference historical sources or performance practice | | `commentsArabic` | Same as above in Arabic | For preservation of original terminology | | `SourcePageReferences[]` | Array of academic citations (sourceId + page number) supporting this jins | Links to bibliographic sources | | `version` | ISO 8601 timestamp of last modification | Tracks data provenance and changes | ### Interval Properties (for `jinsPitchClassIntervals` and `ascendingPitchClassIntervals`) | Property | Description | |----------|-------------| | **`fraction`** | Frequency ratio as reduced fraction (e.g., "3/2", "9/8") | | **`cents`** | Logarithmic interval measurement (1200 cents = an octave) | | **`decimalRatio`** | Frequency ratio as decimal (fraction value converted) | | `stringLength` | Relative string length for this pitch class | | `fretDivision` | String division calculation on reference string length | | `pitchClassIndex` | Pitch class index difference considering octave positions | | `originalValue` | Value from bibliographic source as per historical documentation | | `originalValueType` | Format of original value: "fraction", "decimal", or "cents" | ## Maqāmāt Data The `allMaqamatData` section contains complete maqām information with pitch sequences, ajnās structure, suyur (documented performance practice), and modulation relationships: ```json { "allMaqamatData": { "maqam_rast": { "maqamId": "1", "name": "maqām rāst", "ascendingPitchClasses": ["rast", "dugah", "segah", "chahargah", "nawa", "husayni", "awj"], "descendingPitchClasses": ["ajam", "husayni", "nawa", "chahargah", "segah", "dugah", "rast"], "ascendingPitchClassIntervals": [ {"fraction": "9/8", "cents": 203.91000173077487, "decimalRatio": 1.125, ...}, {"fraction": "13/12", "cents": 138.57266090392324, "decimalRatio": 1.0833333333333333, ...}, {"fraction": "128/117", "cents": 155.5623364999144, "decimalRatio": 1.0940170940170941, ...} // ... additional intervals ], "descendingPitchClassIntervals": [ {"fraction": "273/256", "cents": 111.30856910382295, "decimalRatio": 1.06640625, ...}, {"fraction": "9/8", "cents": 203.91000173077498, "decimalRatio": 1.125, ...} // ... additional intervals ], "ascendingMaqamAjnas": { "rast": ["jins_rast", "jins_yegah_al_rast"], "dugah": ["jins_bayyat"], "segah": ["jins_segah_alhilu", "jins_mayeh_al_segah", "jins_segah", "jins_farahnak_al_segah"], "chahargah": [], "nawa": ["jins_rast_al_nawa", "jins_yegah"], "husayni": ["jins_bayyat_al_husayni"], "awj": ["jins_awj", "jins_iraq", "jins_segah_al_awj"] }, "descendingMaqamAjnas": { "ajam": ["jins_mahran"], "husayni": ["jins_kurd_al_husayni"], "nawa": ["jins_nahawand_al_nawa"], "chahargah": ["jins_chahargah"], "segah": ["jins_segah_alhilu", "jins_mayeh_al_segah", "jins_segah", "jins_farahnak_al_segah"], "dugah": ["jins_bayyat"], "rast": ["jins_rast", "jins_yegah_al_rast"] }, "suyur": [ { "id": "sayr_alsabbagh_1950", "creatorEnglish": "Ṣabbāgh", "creatorArabic": "صبّاغ", "sourceId": "alsabbagh_1950", "page": "41", "commentsEnglish": "Known in Tunis as Ṭabe' al-Dhīl, also Ṭabe' al-Sharqī and Inqilāb al-'irāq...", "commentsArabic": "", "stops": [ {"type": "jins", "value": "1", "startingNote": "rāst"}, {"type": "jins", "value": "10", "startingNote": "rāst"}, {"type": "jins", "value": "3", "startingNote": "rāst"} // ... additional stops ], "version": "2025-10-18T19:41:17.132Z" } // ... additional suyur ], "transposition": false, "isBaseForm": true, "commentsEnglish": "", "commentsArabic": "", "SourcePageReferences": [], "version": "2025-10-18T19:41:17.132Z", "maqamFamilyClassification": { "firstJins": {"familyName": "rast"} }, "maqamToMaqamModulations": { "maqamToMaqamModulationsDegreesNoteNames": { "maqamModulationsOnFirstDegreeNoteName": "rast", "maqamModulationsOnThirdDegreeNoteName": "segah", "maqamModulationsOnAltThirdDegreeNoteName": "kurdi", // ... additional degree names }, "maqamToMaqamModulationsLowerOctaveDegreesNoteNames": { "maqamModulationsOnFirstDegree8vbNoteName": "qarar_rast", "maqamModulationsOnThirdDegree8vbNoteName": "qarar_segah", // ... additional lower octave degree names }, "maqamToMaqamModulations": { "maqamToMaqamModulationsOnFirstDegree": [ "maqam_hijaz_kar_kurd", "maqam_nikriz", "maqam_nawa_athar", "... (additional modulation references)" ], "maqamToMaqamModulationsOnThirdDegree": ["maqam_segah", "maqam_huzam", "..."], "... (additional modulation arrays for other degrees)": [] }, "maqamToMaqamModulationsLowerOctave": { "... (same structure as above for lower octave)": {} } }, "maqamToJinsModulations": { "maqamToJinsModulationDegreesNoteNames": { "... (jins modulation degrees)": "" }, "maqamToJinsModulationsLowerOctaveDegreesNoteNames": { "... (lower octave jins modulation degrees)": "" }, "maqamToJinsModulations": { "... (jins references at each degree)": [] }, "maqamToJinsModulationsLowerOctave": { "... (lower octave jins modulations)": {} } } } // ... additional maqāmāt } } ``` ### Maqām Core Properties | Property | Description | Logic | |----------|-------------|-------| | `maqamId` | Core database ID linking to original maqām definition. Multiple transpositions share same ID | Numerical identifier | | **`name`** | Display name with diacritics and starting note | Example: "maqām rāst" | | **`ascendingPitchClasses[]`** | Array of pitch class keys for ascending melodic motion in order from lowest to highest | Keys match `pitchClassReference` | | **`descendingPitchClasses[]`** | Array of pitch class keys for descending melodic motion (may differ from ascending) | Keys match `pitchClassReference` | | **`ascendingPitchClassIntervals[]`** | Array of interval objects between consecutive ascending pitches (see Interval Properties) | Computed from pitch ratios | | **`descendingPitchClassIntervals[]`** | Array of interval objects between consecutive descending pitches | Computed from pitch ratios | | **`ascendingMaqamAjnas{}`** | Object mapping each ascending pitch degree to an array of jins references, in suyūr-attested order. Empty array if no jins matches | Example: `"rast": ["jins_rast", "jins_yegah_al_rast"]` | | **`descendingMaqamAjnas{}`** | Object mapping each descending pitch degree to an array of jins references, in suyūr-attested order | Same structure as ascending | | `suyur[]` | Array of sayr (plural: suyur) objects. Each contains documentation from a specific source about how a maqām is performed, including stops and structural notes. Only the suyūr that can be played on this form in the exported tuning system are included, each moved onto the form's tonic (see [Which Suyūr Can Be Played](/guide/suyur#which-suyur-can-be-played)) | Links to documented performance practice | | `transposition` | Boolean: `true` for taṣwīr (transposed to a different modal degree), `false` for the base form **and** for its octave/register siblings, since a register shift is not taṣwīr | Distinguishes original vs transposed forms | | `isBaseForm` | Boolean: `true` only for the base form — the canonical form of this maqām, from which its transpositions are derived. Every transposition of one maqām repeats that maqām's `maqamId`, and exactly one entry has `isBaseForm: true`. Use this, not `transposition`, to find base forms | Disambiguates the base form from its octave renderings | | `commentsEnglish` | Structural description and performance details from the source, including melodic context and usage information in English | From original bibliographic source | | `commentsArabic` | Same as above in Arabic | Preserves original terminology | | `SourcePageReferences[]` | Array of academic citations (sourceId + page) supporting this maqām | Links to bibliographic sources | | `version` | ISO 8601 timestamp of last modification | Tracks data provenance | | `maqamFamilyClassification` | Object containing `firstJins.familyName`: the maqām family name determined by its opening jins | Links maqām to family classifications | | `maqamToMaqamModulations` | Object containing all possible maqām-to-maqām modulations organized by degree and octave | Advanced feature for composition/analysis | | `maqamToJinsModulations` | Object containing all possible jins-to-jins modulations organized by degree and octave | Advanced feature for composition/analysis | ### Sayr Properties | Property | Description | |----------|-------------| | `id` | Unique identifier combining source, creator, and date (e.g., "Sayr al-Ṣabbāgh-(1950)") | | `creatorEnglish` | Name of sayr creator/documenter in English (may be empty) | | `creatorArabic` | Name of sayr creator/documenter in Arabic (may be empty) | | `sourceId` | Reference ID to source document in bibliography | | `page` | Page number(s) in source document (may be empty) | | `commentsEnglish` | Structural description and performance details from the source in English | | `commentsArabic` | Structural description and performance details from the source in Arabic (may be empty) | | `stops[]` | Array of stops defining the sayr structure. Each stop has: `type` (jins, note, direction, or maqam), `value` (reference ID, note name, or direction), and optional `startingNote` (present only for jins and maqam types) | | `version` | ISO 8601 timestamp of last modification | ## JSON Structure Elements Understanding the different types of elements in the export format: ### Keys vs Objects vs References #### *Object Keys* These are string identifiers that serve as keys in JSON objects: ```json { "allMaqamatData": { // Main Section: Collection of all maqām data "maqam_rast": { // ← Object Key: Identifies this specific maqām "maqamId": "1", // ← Property: Links to core database "name": "maqām rāst" // ← Property: Display name // ... more properties } } } ``` #### *Reference Values* String values that point to other objects in the data structure: ```json { "ascendingMaqamAjnas": { // Property: Maps degrees to arrays of jins references "rāst": ["jins_rast", "jins_yegah_al_rast"], // ← Reference Values: each points to an allAjnasData object "dūgāh": ["jins_bayyat"] // ← Reference Value: Points to allAjnasData object // ... more references } } ``` #### *Data Objects* Complete objects containing structured information: ````json ```json { "qarar_ushayran": { // ← Object Key: Identifies this pitch class "noteName": "qarār ʿushayrān", // ← Property: Display name "englishName": "G", // ← Property: International Pitch Notation equivalent "fraction": "1/2", // ← Property: Mathematical ratio "cents": "-1200" // ← Property: Logarithmic measurement // ... more properties } ```` ```` #### *Arrays* Ordered lists of elements: ```json { "ascendingPitchClasses": ["rast", "dugah", "segah"], // ← Array: Ordered sequence of pitch class names "modulationsOnOne": [ // ← Array: List of references to other maqāmāt "maqam_hijaz_kar_kurd", // ← Reference Value: Points to allMaqamatData object "maqam_nikriz" // ← Reference Value: Points to allMaqamatData object ] } ```` ## Data Navigation ### Finding Specific Content 1. **Browse by type**: Use allAjnasData to access all melodic genera (ajnās) and allMaqamatData for all modal scales (maqāmāt). Each entry is keyed by a unique identifier and contains detailed properties and references. 2. **Check availability**: Refer to the summaryStats section for the total number of ajnās and maqāmāt in the database, as well as how many are available in the current tuning system. This helps determine the scope of musical material supported by the export. 3. **Navigate pitch classes**: Use the tuningSystemPitchClasses array to get a complete list of all pitch class keys available in the tuning system. These keys correspond to entries in the pitchClassReference section and are used throughout ajnās and maqāmāt data. 4. **Explore relationships**: Use modulation arrays (such as modulationsOnOne, modulationsOnThree, etc.) within each maqām or jins object to find all possible modulations and related structures. These arrays provide references to other maqāmāt or ajnās that can be reached from specific degrees. 5. **Access pitch details**: Reference the pitchClassReference section for comprehensive information about each pitch class, including note names, frequency ratios, cents, decimal values, abjad notation, and more. Use the pitch class names found in ajnās and maqāmāt arrays as keys to look up their detailed definitions here. 6. **Trace structure composition**: For each maqām, examine the ascendingMaqamAjnas and descendingMaqamAjnas objects to see which ajnās are used on each degree in both directions. This reveals the internal structure and constituent ajnās of each scale. 7. **Locate bibliographic context**: Use the SourcePageReferences arrays in ajnās and maqāmāt objects to find academic or historical sources for each structure, supporting further research or verification. ### Working with Transpositions * All structures marked with "transposition": true are taṣwīr — transposed forms derived from a base structure. These represent the same modal pattern starting on a different modal degree. * Base forms have "isBaseForm": true and serve as the canonical version of each jins or maqām. Exactly one entry per `jinsId` / `maqamId` carries it. * **"transposition": false does not by itself mean base form.** A register shift is not taṣwīr, so the octave siblings of the base form (e.g. `jins_bayyat_al_muhayyar` beside `jins_bayyat`) also carry "transposition": false. Filtering on that alone returns the base form *and* its octave siblings. Filter on "isBaseForm": true instead. * The two flags together give the full taxonomy: | `transposition` | `isBaseForm` | Meaning | |---|---|---| | `false` | `true` | the base form | | `false` | `false` | octave rendering of the base form | | `true` | `false` | taṣwīr — a transposition to another modal degree | * Modulation arrays within maqāmāt and ajnās may include both base forms and transpositions, reflecting all possible modulation relationships in the system. * To analyze all possible realizations of a jins or maqām, enumerate every entry sharing its `jinsId` / `maqamId`. * When comparing structures across tuning systems, check `isBaseForm` to identify the canonical form and `transposition` to tell taṣwīr from register shifts. --- --- url: /docs/scripts/README.md --- # Documentation Generation Scripts This folder contains scripts used for generating and maintaining the DiArMaqAr documentation. ## Scripts ### `generate-openapi-json.js` Converts the OpenAPI YAML specification (`openapi.yaml`) to JSON format and places it in multiple locations: * `public/docs/openapi.json` - For Next.js to serve directly * `docs/public/openapi.json` - For VitePress to copy during build * `docs/openapi.json` - Legacy location Also copies the YAML file to `public/docs/openapi.yaml` and `docs/public/openapi.yaml`. **Usage:** ```bash npm run docs:openapi ``` ### `generate-api-docs.js` Generates comprehensive API endpoint reference documentation from the OpenAPI specification. Outputs to `docs/api/endpoints-reference.md`. **Usage:** ```bash npm run docs:api ``` ### `post-process-llms-txt.js` Post-processes the generated `docs/llms.txt` file (created by `vitepress-plugin-llms`) to add: * Link to `llms-full.txt` * Link to root-level `/llms.txt` * API instructions section at the top with Representative Examples * Replaces any "Canonical Examples" references with "Representative Examples" **Usage:** Automatically runs as part of `npm run docs:build`, or manually: ```bash node scripts/docs/post-process-llms-txt.js ``` ### `test-docs-locally.sh` Bash script for testing API documentation locally without deploying to Netlify. Tests: * `/docs/openapi.json` endpoint * `/api/openapi.json` endpoint * `/docs/api/` page **Usage:** ```bash # Make sure Next.js dev server is running first npm run dev # In another terminal ./docs/scripts/test-docs-locally.sh ``` ## Path References All scripts use `__dirname` with relative paths to reference project locations: * To project root: `../..` (up from `scripts/` to `docs/`, then up to root) * To files within `docs/`: `..` (up from `scripts/` to `docs/`) * Scripts are located in `docs/scripts/` (two levels deep from the root) ## Integration These scripts are integrated into npm scripts in `package.json`: * `docs:openapi` - Generates OpenAPI JSON files * `docs:api` - Generates API documentation * `docs:dev` - Runs both generation scripts then starts VitePress dev server * `docs:build` - Runs generation scripts, builds VitePress docs, then post-processes llms.txt