---
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:

* **Taḥlīl**: The original jins (e.g., "jins kurd" starting on dūgāh)
* **Taṣwīr**: A transposition (e.g., "jins kurd al-muhayyar" starting on muhayyar)

**Example:**

* Original: Jins kurd starting on dūgāh → **jins kurd**
* Transposition: Same interval pattern starting on muhayyar → **jins kurd al-muhayyar**

### 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 http://localhost:3000/api/ajnas

# Get specific jins with zalzalian intervals
curl "http://localhost:3000/api/ajnas/jins_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents"
```

### Via TypeScript Library

```typescript
import { Jins } from '@/models/Jins'
import { getJinsTranspositions } from '@/functions/transpose'

// Create jins instance
const jins = new Jins(jinsData)

// Get all possible transpositions in a tuning system
const transpositions = getJinsTranspositions(jins, tuningSystem)
```

## 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/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.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents"
```

**Base URL:** `https://diarmaqar.netlify.app/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)
* `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)
* `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 (3):**

* `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)

### 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)

***

## Getting Started

All endpoints return JSON. No authentication required.

**Common parameters:**

* `includeArabic` (default: "true") - 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/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.netlify.app/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": <number>,
  "data": [<array>]
}
```

## Rate Limiting

Currently, there are no rate limits. Please use the API responsibly.

## Common Parameters

Most endpoints support these optional parameters:

* **`includeArabic`** (default: `"true"`): 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 - Type: `string` - Valid values: `tonic`, `alphabetical` - Default: `alphabetical`
  * Example: `tonic` - Sort by tonic note priority (NoteName.ts order)
  * Example: `alphabetical` - Sort alphabetically by display name
* `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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/maqamat?includeSources=true&includeArabic=true"
```

**Response:** List of maqāmāt retrieved successfully

### 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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/families?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=false"
```

**Response:** Maqām families retrieved successfully

### 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 data for all maqāmāt in a specific tuning system and starting note
* When using `"all"`, both `tuningSystem` and `startingNote` query parameters are required

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, organized by their maqām degree note names
* 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 and starting note are required for all requests (both data retrieval and discovery mode)
* These are fundamental to all pitch class calculations

**Path Parameters:**

* `idName`: URL-safe maqām identifier.

**Special value**: Use `"all"` to retrieve data for all maqāmāt in a specific tuning system and starting note. 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_hijaz` - Maqām Ḥijāz (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)
  * Example: `meshshaqa_1899` - Meshshāqa (1899) - Arabic Octave According to the Modernists (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)
* Example: `rast` - rāst (for CairoCongress, al-Sabbagh)
* `options` (optional): When true, returns available parameter options instead of maqām data.
  * Tuning system and starting note are required for all requests (both data retrieval and discovery mode)
  * 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`
* Example: `true`
* `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
* Type: `string` - Valid values: `all`, `abjadName`, `englishName`, `solfege`, `fraction`, ... (14 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`
* Example: `nawa`
* `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 suyūr (melodic paths) data - 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.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&includeArabic=true"
```

**Response:** Maqām data retrieved successfully.

* 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

### 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 (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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/maqam_bayyat/availability?includeArabic=true"
```

**Response:** Availability information retrieved successfully

### List transpositions for a maqām {#listMaqamTranspositions}

```
GET /maqamat/{idName}/transpositions
```

List all available transposition options for a maqām within a specific tuning system and starting note.

Returns all tonic transpositions that are feasible under the tuning system across all octaves.

**Path Parameters:**

* `idName`: URL-safe maqām identifier (string) **(required)**
  * Example: `maqam_hijaz`

**Query Parameters:**

* `tuningSystem` **(required)**: Tuning system identifier (e.g., 'ibnsina\_1037', 'alfarabi\_950g', 'meshshaqa\_1899') - Type: `string`
  * Example: `alsabbagh_1954`
* `startingNote` **(required)**: Tuning system starting note name (URL-safe, diacritics-insensitive). - 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.netlify.app/api/maqamat/maqam_hijaz/transpositions?tuningSystem=alsabbagh_1954&startingNote=rast&includeArabic=true"
```

**Response:** Transpositions retrieved successfully

### Compare maqām data across multiple tuning systems {#compareMaqam}

```
GET /maqamat/{idName}/compare
```

Compare comprehensive maqām data across multiple tuning systems and starting note configurations in a single request.

Returns comprehensive data similar to `/maqamat/{idName}` but without modulations and suyur. Each comparison includes:

* Pitch class data (ascending and descending sequences)
* Optional interval data
* Ajnās (constituent melodic structures) mapping
* Maqām metadata (family classification, tonic, transposition status)
* Context information (tuning system, starting note, reference frequency)

This endpoint is ideal for comparative musicological analysis across different historical tuning systems.

**Path Parameters:**

* `idName`: URL-safe maqām identifier (string) **(required)**
  * Example: `maqam_bayyat`

**Query Parameters:**

* `tuningSystems` **(required)**: Comma-separated tuning system IDs. - Type: `string`
  * Example: `cairocongresstuningcommittee_1929,alsabbagh_1954`
* `startingNote` **(required)**: Starting note name (URL-safe, diacritics-insensitive) - applies to all tuning systems. - Type: `string`
  * Example: `rast`
* `pitchClassDataType` **(required)**: Output format for pitch class data - Type: `string` - Valid values: `all`, `englishName`, `fraction`, `cents`, `decimalRatio`, ... (13 total)
  * Example: `cents`
* `includeIntervals` (optional): Include interval data between pitch classes - Type: `string` - Valid values: `true`, `false` - Default: `false`
  * Example: `true`
* `transposeTo` (optional): Transpose to specific tonic note (applies to all tuning systems) - 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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/maqam_bayyat/compare?tuningSystems=cairocongresstuningcommittee_1929,alsabbagh_1954&startingNote=rast&pitchClassDataType=cents&includeArabic=true"
```

**Response:** Comparison data retrieved successfully

### 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 respect Arabic maqām theory where
  microtonal modifiers indicate what the pitch is a variant OF, not mathematical proximity
  to 12-EDO semitones
* **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
   * Replaces matching pitch classes in al-Kindi base (ascending takes priority, then descending)
   * Selects pitch classes from correct octaves to ensure ascending chromatic order
   * Orders the 12 pitch classes chromatically starting from the maqām's tonic
3. Groups compatible maqāmāt together
4. Names each group after the source maqām (e.g., "maqām rāst set")

**Compatibility:**

* Maqāmāt with duplicate IPN references (same IPN appearing with different pitch values)
  are marked as incompatible and cannot form valid 12-pitch-class sets
* 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 maqām's tonic (default) OR from IPN "C" (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

**Query Parameters:**

* `tuningSystem` (optional): Tuning system ID for maqāmāt (default: cairocongresstuningcommittee\_1929) - Type: `string` - Default: `cairocongresstuningcommittee_1929`
  * Example: `cairocongresstuningcommittee_1929`
* `startingNote` (optional): Starting note for both the maqām tuning system and alkindi\_874 (default: yegah).
  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` - Default: `yegah`
* 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 12-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
  * 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 ID to find all sets containing that maqām (e.g., 'maqam\_rast') - Type: `string`
  * Example: `maqam_rast`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/classification/12-pitch-class-sets?includeArabic=true"
```

**Response:** Classification results with sets and compatible maqāmāt

### 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 source maqam (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
* **Tahlil Priority**: Base (non-transposed) maqāmāt create canonical sets first, then transpositions

**The Algorithm:**

1. For each maqām transposition (tahlil 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 the source maqām (e.g., "maqām rāst 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)
* Sets containing only the source maqām (no compatible maqāmāt) are filtered out

**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` (optional): Tuning system ID for all maqāmāt (default: cairocongresstuningcommittee\_1929) - Type: `string` - Default: `cairocongresstuningcommittee_1929`
  * Example: `cairocongresstuningcommittee_1929`
* `startingNote` (optional): Starting note for the tuning system (default: yegah). - Type: `string` - Default: `yegah`
  * 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 ID to find all sets containing that maqām (e.g., 'maqam\_rast') - Type: `string`
  * Example: `maqam_rast`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/classification/maqam-pitch-class-sets?includeArabic=true"
```

**Response:** Classification results with maqam-based pitch class sets and compatible maqāmāt

***

## 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 - Type: `string` - Valid values: `tonic`, `alphabetical` - Default: `alphabetical`
  * Example: `tonic` - Sort by tonic note priority (NoteName.ts order)
  * Example: `alphabetical` - Sort alphabetically by display name
* `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.netlify.app/api/ajnas?includeSources=true&includeArabic=true"
```

**Response:** List of ajnās retrieved successfully

### 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 and starting note are required for all requests (both data retrieval and discovery mode)
* These are fundamental to all pitch class calculations

**Path Parameters:**

* `idName`: URL-safe jins identifier (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)
  * Example: `meshshaqa_1899` - Meshshāqa (1899) - Arabic Octave According to the Modernists (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)
* Example: `rast` - rāst (for CairoCongress, al-Sabbagh)
* `options` (optional): When true, returns available parameter options instead of jins data.
  * Tuning system and starting note are required for all requests (both data retrieval and discovery mode)
  * 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`
* Example: `true`
* `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 jins
  * 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
* Type: `string` - Valid values: `all`, `abjadName`, `englishName`, `solfege`, `fraction`, ... (14 total)
* 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`
* Example: `nawa`
* `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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&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

### 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 checking spans 3 octaves to correctly handle ajnās that may span multiple octaves

**Path Parameters:**

* `idName`: URL-safe jins identifier (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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/ajnas/jins_rast/availability?includeArabic=true"
```

**Response:** Availability information retrieved successfully

### List transpositions for a jins {#listJinsTranspositions}

```
GET /ajnas/{idName}/transpositions
```

List all available transposition options for a jins within a specific tuning system and starting note.

Returns all tonic transpositions that are feasible under the tuning system across all octaves.

**Path Parameters:**

* `idName`: URL-safe jins identifier (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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/ajnas/jins_bayyat/transpositions?tuningSystem=meshshaqa_1899&startingNote=yegah&includeArabic=true"
```

**Response:** Transpositions retrieved successfully

### Compare jins data across multiple tuning systems {#compareJins}

```
GET /ajnas/{idName}/compare
```

Compare comprehensive jins data across multiple tuning systems and starting note configurations in a single request.

Returns comprehensive data similar to `/ajnas/{idName}` but without modulations. Each comparison includes:

* Pitch class data (single sequence, as ajnās are unidirectional)
* Optional interval data
* Jins metadata (tonic, transposition status)
* Context information (tuning system, starting note, reference frequency)

This endpoint is ideal for comparative musicological analysis of melodic structures across different historical tuning systems.

**Path Parameters:**

* `idName`: URL-safe jins identifier (string) **(required)**
  * Example: `jins_segah`

**Query Parameters:**

* `tuningSystems` **(required)**: Comma-separated tuning system IDs. - Type: `string`
  * Example: `alfarabi_950g,meshshaqa_1899`
* `startingNote` **(required)**: Starting note name (URL-safe, diacritics-insensitive) - applies to all tuning systems. - Type: `string`
  * Example: `ushayran`
* `pitchClassDataType` **(required)**: Output format for pitch class data - Type: `string` - Valid values: `all`, `englishName`, `fraction`, `cents`, `decimalRatio`, ... (13 total)
  * Example: `cents`
* `includeIntervals` (optional): Include interval data between pitch classes - Type: `string` - Valid values: `true`, `false` - Default: `false`
  * Example: `true`
* `transposeTo` (optional): Transpose to specific tonic note (applies to all tuning systems) - 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`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/ajnas/jins_segah/compare?tuningSystems=alfarabi_950g,meshshaqa_1899&startingNote=ushayran&pitchClassDataType=cents&includeArabic=true"
```

**Response:** Comparison data retrieved successfully

***

## 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.netlify.app/api/tuning-systems?includeSources=true&includeArabic=true"
```

**Response:** List of tuning systems

### 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)
* 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`
* Example: `all`
* `includeSources` (optional): Include bibliographic source references (sourceId and page) for the tuning system - Type: `string` - Valid values: `true`, `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.netlify.app/api/tuning-systems/cairocongresstuningcommittee_1929/rast/pitch-classes?includeSources=true&includeArabic=true"
```

**Response:** Tuning system pitch classes retrieved successfully

### 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 pitch classes to the tuning system's note name sets (including adjacent octave context)

**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 }` instead of
  note-name strings.
  `maqamDegrees.descending` as arrays of objects `{ noteName, englishName, solfege }` instead of
  note-name strings. The same transformation applies to `transpositions[].maqamDegrees`.
* 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 `tonic` and `maqamDegrees` with ascending/descending
  note name idNames for that transposed position.
* Type: `string` - Valid values: `true`, `false` - Default: `false`
* Example: `true`

**Example:**

```bash
curl "https://diarmaqar.netlify.app/api/tuning-systems/alfarabi_950g/ushayran/maqamat?includeArabic=true"
```

**Response:** Maqāmāt list retrieved successfully

***

## 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.netlify.app/api/pitch-classes/note-names?includeArabic=true"
```

**Response:** List of note names retrieved successfully

### 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.netlify.app/api/pitch-classes/note-names/rast?includeArabic=true"
```

**Response:** Pitch class data retrieved successfully

### 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.netlify.app/api/pitch-classes/note-names/rast/availability?includeArabic=true"
```

**Response:** Availability data retrieved successfully

### 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 - 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.netlify.app/api/pitch-classes/note-names/rast/compare?tuningSystems=meshshaqa_1899,cairocongresstuningcommittee_1929&startingNote=yegah&includeArabic=true"
```

**Response:** Comparison data retrieved successfully

***

## 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.netlify.app/api/intervals?noteNames=rast,dugah,segah&includeArabic=true"
```

**Response:** Interval calculations retrieved successfully

### 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 - 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.netlify.app/api/intervals/compare?noteNames=rast,dugah,segah&tuningSystems=alfarabi_950g,cairocongresstuningcommittee_1929&startingNote=ushayran&includeArabic=true"
```

**Response:** Comparison data retrieved successfully

### 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.netlify.app/api/intervals/calculate?from=rast&to=dugah&tuningSystem=ibnsina_1037&startingNote=yegah&unit=cents&includeArabic=true"
```

**Response:** Interval calculated successfully

***

## 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.netlify.app/api/sources?includeArabic=true"
```

**Response:** List of sources retrieved successfully

### 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:

* `al-Khuli-(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.netlify.app/api/sources/Farmer-(1937)?includeArabic=true"
```

**Response:** Source retrieved successfully

### 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.netlify.app/api/sources/Farmer-(1937)/tuning-systems?includeArabic=true"
```

**Response:** Tuning systems retrieved successfully

### 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: `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.netlify.app/api/sources/Farmer-(1937)/maqamat?includeArabic=true"
```

**Response:** Maqamat retrieved successfully

### 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: `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.netlify.app/api/sources/Farmer-(1937)/ajnas?includeArabic=true"
```

**Response:** Ajnas retrieved successfully

***

---

---
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/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
* Bilingual commentary (Arabic/English)
* 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 both Arabic and English
* **Books and articles** with full publication details
* **Contributor information**
* **DOI links** where available
* **Access dates** for digital sources

### Source Types

**Historical Treatises (9th-13th centuries):**

* Al-Kindī (d. 847)
* Al-Fārābī (d. 950)
* Ibn Sīnā (d. ca. 1037)
* Al-Urmawī (13th century)

**Modern Scholarship (19th-20th centuries):**

* Meshshāqa (1899)
* Al-Khulʿī (1904/2011)
* Al-Shawwā (1946)
* Allāh Wīrdī (1949)
* Al-Ṣabbāgh (1954)
* Al-Ḥilū (1961)

**Contemporary Sources:**

* Beyhom (2010)
* Modern theoretical works
* Performance practice documentation

## Note Name Compilation

The Persian-Arab-Ottoman note naming convention is compiled from:

* Meshshāqa (1899:18)
* Al-Khulʿī (1904/2011:50-54 and 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)

**Extended ranges** (qarār prefixes, jawāb prefixes) follow conventions documented in:

* Allāh Wīrdī (1949:203)
* Al-Ḥilū (1961:70)

## 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, Allah Wīrdī 1949)

## Commentary and Context

Each tuning system includes commentary by Dr. Khyam Allami 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 http://localhost:3000/api/sources

# Maqām responses include source references
curl "http://localhost:3000/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents"

# Response includes:
# - source references
# - page numbers
# - bibliographic citations
```

### Via TypeScript Library

```typescript
import { getSources } from '@/functions/import'

// Get all bibliographic sources
const sources = getSources()

// Each source includes:
// - Full citation (Arabic and English)
// - Publication details
// - Contributor information
// - DOI links (if available)
```

## Academic Citation

All data is ready for academic citation with:

* **Complete bibliographic references**: Full citations in Arabic and English
* **Page numbers**: Specific locations in sources
* **Transparent methodology**: How data was derived
* **Version tracking**: Platform version and data version

### Citation Format

Citations follow international scholarly standards:

* Library of Congress Arabic Romanization
* Standard academic citation formats
* Bilingual support (Arabic/English)
* DOI links where available

## Historical Context

### Manuscript Availability

**Challenge**: Many historical treatises exist only as copies in Anglo-European libraries due to colonial expatriation:

* Leyden, London, Oxford, Madrid, Paris, Berlin, Munich
* Initiated by Napoleon's 1798 invasion of Egypt
* Continuing through 2003 plunder of Iraq

**Response**: DiArMaqAr provides access to content from:

* Critical editions collating multiple manuscripts
* Scholarly publications with textual variants
* Documented commentary and annotations

### Theoretical Evolution

Sources span:

* **8th century**: Early theoretical works
* **9th-13th centuries**: Medieval polymath theorists
* **19th-20th centuries**: Modern systematization
* **Contemporary**: Recent scholarship

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/cultural-framework.md
description: Decolonial computing principles and culturally-specific methodology
---

# Cultural Framework

DiArMaqAr operates through a culturally-specific methodology that prioritizes Arabic theoretical frameworks and epistemological systems. This approach reflects decolonial computing principles and challenges Anglo-European-centric paradigms in digital musicology.

## Decolonial Computing Principles

### Foundational Philosophy

As Serra (2011) identifies, there is a foundational epistemological problem in digital musicology: "Our information technologies do not respond to the world's multicultural reality; instead, we are imposing the paradigms of our market-driven western culture on IT."

**Postcolonial Computing Framework** (Irani et al. 2010):

* Digital technologies can either reinforce or challenge hierarchies of knowledge
* Scope must encompass software and hardware design
* Systems embed cultural assumptions into technical foundations
* Not just user interface choices, but architectural decisions

### DiArMaqAr's Approach

The platform implements culture-specific methodology by:

1. **Prioritizing Arabic Theoretical Frameworks**
   * All operations grounded in Persian-Arab-Ottoman note naming convention
   * Arabic concepts as foundational logic, not exotic variation

2. **System-Level Implementation**
   * Data model enforces Arabic structures
   * Computational operations built from Arabic theory
   * Interface presents Arabic hierarchies natively

3. **Avoiding Western-Centrism**
   * Arabic maqām theory is not a deviation from Western tuning
   * Represents independent theoretical frameworks
   * Avoids positioning as "alternative" or "xenharmonic"

## Persian-Arab-Ottoman Note Naming Convention

### Primary Reference System

All pitch calculations begin from this framework:

* **Note names**: rāst, dugāh, segāh, chahārgāh, nawā, etc.
* **Organizational hierarchies**: Tanāghīm → Ajnās → Maqāmāt → Suyūr → Intiqālāt
* **Extended ranges**: Lower register (qarār prefixes) and upper register (jawāb prefixes)

### Implementation

* **Data model**: Enforces Arabic note naming
* **Calculations**: Begin from Arabic frameworks
* **Interface**: Presents Arabic hierarchies natively
* **Operations**: Built directly from Arabic structures

## Avoiding Microtonality Terminology

### Critical Terminology Standards

**NEVER use "microtonal":**
This Western-centric term implies deviation from equal temperament as the norm.

**Use culturally appropriate alternatives:**

* "Unequal divisions"
* "Non-12-EDO pitches"
* "Pitches with fractional precision"
* "Pitches with decimal/fractional MIDI values"
* Describe specific theoretical framework (e.g., "following Arabic maqām theory")

**This applies to ALL:**

* Code comments
* Documentation
* Variable names
* Function descriptions
* Export data
* User-facing text

## Historical Authenticity

### Source-Based Implementation

* **Historical sources**: Medieval treatises through modern scholarship
* **Bibliographic attribution**: Complete source references
* **Scholarly verification**: Enables academic citation
* **Transparent provenance**: Clear data origin

### Avoiding Standardization Bias

As Marcus (1989) documents, 20th-century "modernisation" trend increasingly adopted Anglo-European frameworks to standardize historical diversity. DiArMaqAr:

* Preserves historical diversity
* Avoids forcing external frameworks
* Maintains multiple theoretical approaches
* Respects interpretative flexibility

## Computational Representation

### Culture-Specific Formalization

Following Serra (2017), DiArMaqAr approaches Arabic maqām as:

* "A system of interconnected entities"
* Musicians, instruments, performances, melodic motifs
* Linked through various relations
* Requiring "adequate digital traces, rigorous formalization"
* Grounded in culture-specific theoretical frameworks

### 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 Western-centric approaches
* Recognizing that every computational method carries embedded musicological assumptions

## Research Implications

### Infrastructure Gap

Addresses core structural problem identified by Gedik and Bozkurt (2009):

* Divergence between theory and practice
* Lack of reliable, computationally accessible theory
* Need for "valid pitch-class definitions grounded in culturally-specific frameworks"

### Model for Other Traditions

DiArMaqAr demonstrates:

* Viability of culture-specific approaches
* Preservation of cultural specificity
* Computational accessibility without cultural compromise
* Potential for broader digital humanities applications

## Practical Implementation

### Technical Architecture

* **Note naming**: Persian-Arab-Ottoman convention as primary
* **Data organization**: Arabic hierarchies enforced
* **Calculations**: Begin from Arabic frameworks
* **Interface**: Arabic concepts presented natively

### Bilingual Support

* **Library of Congress Romanization**: International scholarly standards
* **Arabic script**: Native language support
* **Reverse transliteration**: Accurate conversion
* **Cultural accessibility**: Local and international communities

## Challenges and Responses

### Avoiding Reductionism

* Maintains complexity of historical sources
* Preserves multiple theoretical perspectives
* Resists simplification to fit computational models
* Honors interpretative traditions

### Computational Precision vs. Cultural Authenticity

* Mathematical accuracy maintained
* Historical sources preserved
* Performance practice variations accommodated (cents tolerance)
* Balance between precision and authenticity

## Academic Context

### Scholarly Contribution

DiArMaqAr contributes to:

* Decolonial computing discourse
* Computational ethnomusicology
* Digital humanities methodology
* Culturally-responsive technology

### Model for Future Work

Provides framework for:

* Similar projects in other musical traditions
* Culture-specific digital musicology
* Preservation of local knowledge systems
* Global accessibility with cultural integrity

## Next Steps

* Learn about [Theoretical Framework](/guide/theoretical-framework/)
* Explore [Bibliographic Sources](/guide/bibliographic-sources/)
* Understand [Research Applications](/guide/research-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

## Export Functions

### Via TypeScript Library

```typescript
import { 
  exportMaqam, 
  exportJins, 
  exportTuningSystem,
  exportToScala 
} from '@/functions/export'

// Export maqām data
const maqamJSON = exportMaqam(maqam, {
  includeTranspositions: true,
  includeModulations: true,
  includeAjnās: true
})

// Export tuning system to Scala
const scalaFiles = exportToScala(tuningSystem, {
  format: 'scl', // or 'kbm'
  referenceNote: 'A4',
  referenceFrequency: 440
})
```

### 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/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 transposition: false 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
│   │   ├── 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
    │   ├── commentsEnglish
    │   ├── commentsArabic
    │   ├── SourcePageReferences []
    │   ├── version
    │   ├── maqamFamilyClassification
    │   │   └── firstJins
    │   │       └── familyName
    │   ├── maqamToMaqamModulations
    │   │   ├── maqamToMaqamModulationsDegreesNoteNames {}
    │   │   ├── maqamToMaqamModulationsLowerOctaveDegreesNoteNames {}
    │   │   ├── maqamToMaqamModulations {}
    │   │   │   ├── maqamToMaqamModulationsOnFirstDegree []
    │   │   │   ├── maqamToMaqamModulationsOnThirdDegree []
    │   │   │   ├── maqamToMaqamModulationsOnAltThirdDegree []
    │   │   │   ├── maqamToMaqamModulationsOnFourthDegree []
    │   │   │   ├── maqamToMaqamModulationsOnFifthDegree []
    │   │   │   ├── maqamToMaqamModulationsOnSixthDegreeAsc []
    │   │   │   ├── maqamToMaqamModulationsOnSixthDegreeDesc []
    │   │   │   ├── maqamToMaqamModulationsOnSixthDegreeIfNoThird []
    │   │   │   └── maqamToMaqamModulations2pBelowThirdNoteName
    │   │   └── maqamToMaqamModulationsLowerOctave {}
    │   │       ├── maqamToMaqamModulationsOnFirstDegree8vb []
    │   │       ├── maqamToMaqamModulationsOnThirdDegree8vb []
    │   │       ├── maqamToMaqamModulationsOnAltThirdDegree8vb []
    │   │       ├── maqamToMaqamModulationsOnFourthDegree8vb []
    │   │       ├── maqamToMaqamModulationsOnFifthDegree8vb []
    │   │       ├── maqamToMaqamModulationsOnSixthDegreeAsc8vb []
    │   │       ├── maqamToMaqamModulationsOnSixthDegreeDesc8vb []
    │   │       ├── maqamToMaqamModulationsOnSixthDegreeIfNoThird8vb []
    │   │       └── maqamToMaqamModulations2pBelowThird8vb
    │   └── maqamToJinsModulations
    │       ├── maqamToJinsModulationDegreesNoteNames {}
    │       ├── maqamToJinsModulationsLowerOctaveDegreesNoteNames {}
    │       ├── maqamToJinsModulations {}
    │       │   ├── maqamToJinsModulationsOnFirstDegree []
    │       │   ├── maqamToJinsModulationsOnThirdDegree []
    │       │   ├── maqamToJinsModulationsOnAltThirdDegree []
    │       │   ├── maqamToJinsModulationsOnFourthDegree []
    │       │   ├── maqamToJinsModulationsOnFifthDegree []
    │       │   ├── maqamToJinsModulationsOnSixthDegreeAsc []
    │       │   ├── maqamToJinsModulationsOnSixthDegreeDesc []
    │       │   ├── maqamToJinsModulationsOnSixthDegreeIfNoThird []
    │       │   └── maqamToJinsNoteName2pBelowThird
    │       └── maqamToJinsModulationsLowerOctave {}
    │           ├── maqamToJinsModulationsOnFirstDegree8vb []
    │           ├── maqamToJinsModulationsOnThirdDegree8vb []
    │           ├── maqamToJinsModulationsOnAltThirdDegree8vb []
    │           ├── maqamToJinsModulationsOnFourthDegree8vb []
    │           ├── maqamToJinsModulationsOnFifthDegree8vb []
    │           ├── maqamToJinsModulationsOnSixthDegreeAsc8vb []
    │           ├── maqamToJinsModulationsOnSixthDegreeDesc8vb []
    │           ├── maqamToJinsModulationsOnSixthDegreeIfNoThird8vb []
    │           └── maqamToJinsNoteName2pBelowThird8vb
    └── ... (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,
      "commentsEnglish": "",
      "commentsArabic": "",
      "SourcePageReferences": [
        {"sourceId": "al-Khulʿī-(2011)", "page": "55"},
        {"sourceId": "al-Urmawī-al-Baghdādī-(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: `false` for base form (canonical), `true` for transposed instances | Distinguishes original vs derived structures |
| `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",
        "dugah": "jins_bayyat",
        "segah": "jins_segah",
        "chahargah": null,
        "nawa": "jins_rast_al-nawa",
        "husayni": "jins_bayyat_al-husayni",
        "awj": "jins_segah_al-awj"
      },
      "descendingMaqamAjnas": {
        "ajam": null,
        "husayni": "jins_kurd_al-husayni",
        "nawa": "jins_nahawand_al-nawa",
        "chahargah": "jins_chahargah_(al-Shawwa)",
        "segah": "jins_segah",
        "dugah": "jins_bayyat",
        "rast": "jins_rast"
      },
      "suyur": [
        {
          "id": "Sayr al-Ṣabbāgh-(1950)",
          "creatorEnglish": "Ṣabbāgh",
          "creatorArabic": "صبّاغ",
          "sourceId": "al-Ṣabbāgh-(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,
      "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 its associated jins reference. Value is `null` if no jins assigned | Example: `"rast": "jins_rast"` |
| **`descendingMaqamAjnas{}`** | Object mapping each descending pitch degree to its associated jins reference | 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 | Links to documented performance practice |
| `transposition` | Boolean: `false` for base form (canonical), `true` for transposed starting note | Distinguishes original vs derived forms |
| `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 jins references
    "rāst": "jins_rast",    // ← Reference Value: Points to 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 transposed forms derived from a base (untransposed) structure. These represent the same modal pattern starting on different notes.

* Base forms have "transposition": false and serve as the canonical version of each jins or maqām.

* 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 both the base form and all its transpositions as listed in the export.

* When comparing structures across tuning systems, always check the transposition property to distinguish between original and derived forms.

---

---
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

---

---
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, bilingual, 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

* **Bilingual 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
* **TypeScript Library**: Complete JavaScript/TypeScript library with full type safety

### 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 http://localhost:3000/api/maqamat

# Get specific maqām data with full details
curl "http://localhost:3000/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents"

# Include modulation analysis on the maqām detail response
curl "http://localhost:3000/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 "http://localhost:3000/api/maqamat/maqam_bayyat/transpositions?tuningSystem=alfarabi_950g&startingNote=ushayran"
```

### Using the TypeScript Library

First, install the library in your project (or clone the repository for direct development access). Then import the required modules:

```typescript
import MaqamData from '@/models/Maqam'
import JinsData from '@/models/Jins'
import TuningSystem from '@/models/TuningSystem'
import { calculateMaqamTranspositions } from '@/functions/transpose'
import modulate from '@/functions/modulate'

// Create instances
const tuningSystem = new TuningSystem(tuningSystemData)
const maqamData = new MaqamData(maqamDataInterface)
const maqam = maqamData.generate(tuningSystem)

// Get transpositions
const transpositions = calculateMaqamTranspositions(maqam, tuningSystem)

// Analyze modulations
const modulations = modulate(maqam, allMaqamat, tuningSystem)
```

## 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
* Check out the [TypeScript Library Documentation](/library/) for programmatic usage
* 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.netlify.app/) - Interactive web interface

---

---
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 "2p" (two parts)
   * These represent the half-tones

3. **Arbāʿ** (One-fourth notes, sing. rubʿ): Represented as "1p" (one part)
   * 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", "1p", "2p", "/"}*

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, "2p" for half-notes (anṣāf), "1p" 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), provided the tonic is classified as an "original" note (aṣlīya/ṭabīʿīya, represented as "n").

### 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 "2p") 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.

### 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 lies between two "natural" maqām degrees within the source maqām.

## 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 "http://localhost:3000/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
```

### Via TypeScript Library

```typescript
import { modulate } from '@/functions/modulate'

// Get valid modulations from source maqām
const modulations = modulate(sourceMaqam, allMaqamat, tuningSystem)

// Each modulation includes:
// - Target maqām
// - Modulation type
// - Maqām degree relationship
// - Classification validation
```

## 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/LLM-ACCESSIBILITY-AUDIT.md
---
# LLM Accessibility Audit Report

**Date:** February 27, 2025\
**Audited URL:** https://diarmaqar.netlify.app/

## Executive Summary

The DiArMaqAr site has strong LLM-oriented design with dedicated documentation, explicit AI assistant instructions, and comprehensive API access. **One critical bug was found and fixed**: LLM documentation files used incorrect `tuningSystem` parameter values (`IbnSina-(1037)`) that return 404—the correct URL-safe format is `ibnsina_1037`.

***

## Strengths

### 1. Dedicated LLM Documentation

* **Root `/llms.txt`** – Concise index at the domain root for easy discovery
* **`/docs/llms.txt`** – Full documentation index with API instructions
* **`/docs/llms-full.txt`** – Complete documentation content
* Plain-text format ideal for LLM consumption (no JavaScript required)

### 2. Explicit AI Assistant Instructions

* "For AI Assistants and LLMs" sections on root page and docs
* Clear required parameters: `tuningSystem`, `startingNote`, `pitchClassDataType`
* Common mistakes to avoid (with ❌/✅ examples)
* Common use cases mapped to API endpoints
* Parameter discovery via `?options=true`

### 3. robots.txt Configuration

* Explicitly allows major LLM crawlers (GPTBot, Claude-Web, PerplexityBot, etc.)
* Allows `/docs/`, `/api/`, OpenAPI spec
* Welcoming message: "We welcome LLM bots to access our documentation and API"
* **Updated:** Root `/llms.txt` now explicitly allowed

### 4. Representative Examples

* `/docs/api/representative-examples` uses correct URL-safe IDs throughout
* Serves as authoritative source for API usage
* Clear "For LLMs and AI Assistants" section

### 5. Root Page Content

* HTML includes full LLM-relevant content (not hidden behind client-side rendering)
* Multilingual (EN/AR/FR) with consistent API examples
* Quick test URL prominently displayed

### 6. OpenAPI Specification

* Machine-readable spec at `/docs/openapi.json`
* Complete parameter documentation
* Interactive playground at `/docs/api/playground`

***

## Issues Found & Fixed

### Critical: Wrong tuningSystem Parameter Values (FIXED)

**Problem:** `public/llms.txt` and `docs/scripts/post-process-llms-txt.js` used display-style IDs that the API rejects:

* `IbnSina-(1037)` → **404 Not Found**
* `al-Farabi-(950g)` → **404 Not Found**

**Correct format:** URL-safe IDs from `data/tuningSystems.json`:

* `ibnsina_1037` → **200 OK**
* `alfarabi_950g` → **200 OK**

**Fix applied:**

* `public/llms.txt` – All examples updated to use `ibnsina_1037` and `alfarabi_950g`
* `docs/scripts/post-process-llms-txt.js` – API instructions template updated (affects generated `docs/llms.txt` on each build)

### Minor: robots.txt Root llms.txt (FIXED)

**Problem:** Root `/llms.txt` was not explicitly listed in robots.txt (though `Allow: /` covered it).

**Fix applied:** Added `Allow: /llms.txt` for explicit LLM discovery.

***

## Recommendations (All Addressed)

### 1. docs/llms.txt Table of Contents Duplication ✅

**Implemented:** Post-process deduplication in `post-process-llms-txt.js` removes duplicate TOC links by URL (keeping first occurrence). Plugin config excludes duplicate route sidebars (`/api/playground`, `/api/endpoints-reference`) from LLM TOC generation. "API Endpoints Reference" now appears once instead of 50+ times.

### 2. Root Page "Desktop Required" Overlay ✅

**Verified:** Fetch returns full HTML content including all LLM sections. The overlay does not hide content from programmatic access.

### 3. Link Consistency ✅

**Implemented:** Post-process script uses correct URL-safe IDs (`ibnsina_1037`, `alfarabi_950g`) in the API instructions it injects into `docs/llms.txt`. Root `public/llms.txt` manually updated to match. Both files stay in sync on each docs build.

### 4. Sitemap ✅

**Implemented:** `src/app/sitemap.ts` includes `/llms.txt`, `/docs/llms.txt`, `/docs/llms-full.txt`, and `/docs/openapi.json` for discovery.

***

## Follow-up Audit (Claude Sonnet 4.6)

### Issues Addressed

**1. links.self branch URL leak (PRIORITY)** ✅\
API responses were returning `main--diarmaqar.netlify.app` or deploy-preview URLs instead of `diarmaqar.netlify.app`. Fixed by adding `getCanonicalSelfUrl(request)` and `getCanonicalApiUrl(path)` in `response-shapes.ts`; all API routes now use canonical production URL for `links.self`.

**2. robots.txt and sitemap discovery** ✅\
Added explicit links to `/robots.txt` and `/sitemap.xml` in `public/llms.txt` and post-process `docs/llms.txt` under a "Discovery" section.

**3. Desktop Required clarification** ✅\
Added note in `public/llms.txt`: "The 'Desktop Required' message on the homepage refers only to the interactive UI. All documentation and API endpoints are fully accessible programmatically."

**4. options=true example** ✅\
Added abbreviated example response structure to representative-examples.md for the parameter discovery endpoint.

### Verified

* **docs/llms.txt accessibility**: Returns 200, publicly accessible (auditor's tool constraint was tool-specific).
* **robots.txt**: Exists at `/robots.txt`, references sitemap.

***

## Verification Checklist

After deployment, verify:

* \[ ] `GET https://diarmaqar.netlify.app/llms.txt` returns content with `ibnsina_1037`
* \[ ] `GET https://diarmaqar.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents` returns 200
* \[ ] `GET https://diarmaqar.netlify.app/docs/llms.txt` (after next docs build) uses correct IDs
* \[ ] Root page HTML contains "For AI Assistants and LLMs" section
* \[ ] `GET https://diarmaqar.netlify.app/docs/openapi.json` returns valid OpenAPI 3.x

***

## Files Modified

| File | Change |
|------|--------|
| `public/llms.txt` | Replaced `IbnSina-(1037)` → `ibnsina_1037`, `al-Farabi-(950g)` → `alfarabi_950g` |
| `docs/scripts/post-process-llms-txt.js` | Same replacements in API instructions template; added TOC deduplication by URL |
| `docs/.vitepress/config.mts` | Exclude `/api/playground` and `/api/endpoints-reference` from sidebar passed to vitepress-plugin-llms |
| `public/robots.txt` | Added `Allow: /llms.txt` |
| `src/app/sitemap.ts` | Added `/llms.txt` to sitemap (others already present) |

***

*Audit conducted by reviewing root URL, llms.txt files, representative examples, API responses, and robots.txt configuration.*

---

---
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 original form (taḥlīl) 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

## 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 http://localhost:3000/api/maqamat

# Get specific maqām with full details
curl "http://localhost:3000/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&pitchClassDataType=cents"

# List transpositions (dedicated endpoint)
curl "http://localhost:3000/api/maqamat/maqam_bayyat/transpositions?tuningSystem=alfarabi_950g&startingNote=ushayran"

# Include modulation analysis
curl "http://localhost:3000/api/maqamat/maqam_bayyat?tuningSystem=alfarabi_950g&startingNote=ushayran&includeModulations=true"
```

### Via TypeScript Library

```typescript
import { Maqam } from '@/models/Maqam'
import { getMaqamTranspositions } from '@/functions/transpose'

// Create maqam instance
const maqam = new Maqam(maqamData)

// Get all possible transpositions in a tuning system
const transpositions = getMaqamTranspositions(maqam, tuningSystem)

// Access ascending and descending sequences
console.log(maqam.ascendingSequence)
console.log(maqam.descendingSequence)

// Access embedded ajnās (automatically analyzed)
console.log(maqam.ajnas)
```

## 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
* Bilingual commentary (Arabic/English)
* 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/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/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 http://localhost:3000/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 "http://localhost:3000/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
* [TypeScript Library](/library/) - Programmatic usage guide
* [Interactive API Playground](http://localhost:3000/api-playground) - Test endpoints in your browser

---

---
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.netlify.app/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-kindī-874---al-kindi-874) - 12-Tone
  * [al-Fārābī (950g)](#al-fārābī-950g---al-farabi-950g) - First Oud Tuning 27-Tone
  * [Ibn Sīnā (1037)](#ibn-sīnā-1037---ibnsina-1037) - 7-Fret Oud 17-Tone
  * [Meshshāqa (1899)](#meshshāqa-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-ṣabbāgh-1954---al-sabbagh-1954) - Contemporary Arabic Tuning 24-Tone

* **[Representative Ajnās](#representative-ajnās)** - Tri/tetra/penta-chords
  * With zalzalian intervals: [jins rāst](#jins-rāst---jins_rast), [jins bayyāt](#jins-bayyāt---jins_bayyat), [jins segāh](#jins-segāh---jins_segah), [jins ṣabā](#jins-ṣabā---jins_saba)
  * Without zalzalian intervals: [jins nikrīz](#jins-nikrīz---jins_nikriz), [jins kurd](#jins-kurd---jins_kurd), [jins nahāwand](#jins-nahāwand---jins_nahawand), [jins ḥijāz](#jins-ḥijāz---jins_hijaz)

* **[Representative Maqāmāt](#representative-maqāmāt)** - Complete modal frameworks
  * Principle maqāmāt: [maqām rāst](#maqām-rāst---maqam_rast), [maqām bayyāt](#maqām-bayyāt---maqam_bayyat), [maqām ḥijāz](#maqām-ḥijāz---maqam_hijaz)
  * Complex and transposed: [rāḥat al-arwāḥ](#rāḥat-al-arwāḥ---maqam_rahat_al-arwah), [maqām bestenegar](#maqām-bestenegar---maqam_bestenegar)
  * Without zalzalian intervals: [maqām kurd](#maqām-kurd---maqam_kurd), [maqām āthār kurd](#maqām-āthār-kurd---maqam_athar-kurd), [maqām dilkesh ḥūrān](#maqām-dilkesh-ḥūrān---maqam_dilkesh-huran)

***

## ⚠️ Critical Requirements

**REQUIRED Parameters for Detail Endpoints:**

All detail endpoints (`/api/maqamat/{id}`, `/api/ajnas/{id}`) **MUST** include these three 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`)
3. **`pitchClassDataType`** - Format for pitch class data (e.g., `cents`, `fraction`, `all`)

**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

**Example - CORRECT:**

```bash
GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
```

**Example - WRONG (missing parameters):**

```bash
GET /api/maqamat/maqam_rast  # ❌ Missing required parameters
GET /api/maqamat/rast  # ❌ Wrong endpoint format AND missing parameters
```

***

## ❌ Common Mistakes to Avoid

### 1. Missing Required Parameters

**WRONG:**

```bash
GET /api/maqamat/maqam_rast
GET /api/ajnas/jins_rast
```

**CORRECT:**

```bash
GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
GET /api/ajnas/jins_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
```

### 2. Wrong Endpoint Format

**WRONG:**

```bash
GET /api/maqamat/rast  # Missing "maqam_" prefix
GET /api/ajnas/rast     # Missing "jins_" prefix
```

**CORRECT:**

```bash
GET /api/maqamat/maqam_rast  # Includes "maqam_" prefix
GET /api/ajnas/jins_rast     # Includes "jins_" prefix
```

### 3. Using Display Names Instead of URL-Safe IDs

**WRONG:**

```bash
GET /api/maqamat/maqam_rast?tuningSystem=Ibn Sīnā (1037)&startingNote=yegāh
```

**CORRECT:**

```bash
GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah
```

**Note:** All IDs and parameter values must be URL-safe (no spaces, diacritics, or special characters).

### 4. Parameter Discovery

If you need to discover available parameters, use `options=true`:

```bash
GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true
```

This returns available parameters instead of data, which is useful for programmatic discovery.

***

## 🤖 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 parameter discovery** (`options=true`) to programmatically discover available parameters

**Example Parameter Discovery Request:**

```bash
GET /api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true
```

**Response includes:**

* Available tuning systems for this maqām
* Available starting notes for each tuning system
* Available pitch class data types
* All other optional parameters

**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 (URL-safe, diacritics-insensitive)."
    },
    "pitchClassDataType": {
      "options": ["all", "englishName", "fraction", "cents", "decimalRatio", "stringLength", "frequency", "abjadName", "fretDivision", "midiNoteNumber", "midiNoteDeviation", "centsDeviation", "referenceNoteName"],
      "required": true,
      "description": "Output format for pitch data."
    },
    "transposeTo": {
      "options": ["rast", "qarar_rast", "qarar_chahargah", "chahargah", "kurdan", "mahuran"],
      "description": "Transpose to specific tonic (taṣwīr)."
    },
    "intervals": { "type": "boolean", "default": false },
    "includeModulations": { "type": "boolean", "default": false },
    "includeSuyur": { "type": "boolean", "default": false }
  },
  "notes": {
    "ajnasData": "Ajnās are always included in maqām responses",
    "formatOptions": "Use 'all' for complete pitch class information."
  },
  "examples": [
    "/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=ushayran&pitchClassDataType=cents&includeIntervals=true",
    "/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=ushayran&pitchClassDataType=cents&transposeTo=nawa&includeModulations=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 /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, etc.)
* `pitchData` - Pitch class data in ascending/descending arrays
* `intervals` - Interval data (if `includeIntervals=true`)
* `context` - Tuning system context, starting note info, reference frequencies
* `sources` - Bibliographic source references
* `links` - Related API endpoint URLs
* `stats` - Statistics (number of pitch classes, etc.)
* `characteristics` - Musical characteristics (isOctaveRepeating, hasAsymmetricDescending, etc.)

**Minimal Example Response:**

```json
{
  "maqam": {
    "id": "maqam_rast",
    "idName": "maqam_rast",
    "displayName": "maqām rāst",
    "version": "2025-10-18T19:42:23.643Z"
  },
  "pitchData": {
    "ascending": [
      { "cents": 0, "englishName": "yegāh", ... },
      { "cents": 204, "englishName": "ʿushayrān", ... },
      ...
    ],
    "descending": [...]
  },
  "context": {
    "tuningSystem": {
      "id": "ibnsina_1037",
      "displayName": "Ibn Sīnā (1037) - 7-Fret Oud 17-Tone",
      "selectedStartingNote": { "idName": "yegah", "displayName": "yegāh" },
      "referenceFrequency": 97.999
    },
    "pitchClassDataType": "cents"
  },
  "sources": [...],
  "links": {...}
}
```

**For complete response schemas**, see the [OpenAPI Specification](../openapi.json).

***

## Representative Tuning Systems

### al-Kindī (874) - `alkindi_874`

**Title**: 12-Tone
**Starting Note**: ʿushayrān - `ushayran`

**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 /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 Note**: ʿushayrān - `ushayran`

**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=d'Erlanger-\(1930\))

**Example**:

```
GET /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 Note**: 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 /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 Note**: 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=Meshshāqa-\(1899\))

**Example**:

```
GET /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 Note**: 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=Allāh-Wīrdī-\(1949\))

**Example**:

```
GET /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 Note**: 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=al-Ṣabbāgh-\(1954\))

**Example**:

```
GET /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`: `yegah` (for IbnSina, Meshshaqa), `ushayran` (for al-Farabi), or `rast` (for CairoCongress)
* `pitchClassDataType`: `cents` (or `fraction`, `all`, etc.)

**Example**:

```bash
GET /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 /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 /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-Khulʿī (2011:55)](../../bibliography?source=al-Khulʿī-\(2011\)), [al-Urmawī-al-Baghdādī (2017:23)](../../bibliography?source=al-Urmawī-al-Baghdādī-\(2017\))

**Example**:

```
GET /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 /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 /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**: `alkindi_874` on `ushayran`.

**Source**: (No source references in data)

**Example**:

```
GET /api/ajnas/jins_kurd_(binsir)?tuningSystem=alkindi_874&startingNote=ushayran&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 /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 /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**: `alkindi_874` on `ushayran` or `ibnsina_1037` on `yegah`.

**Source**: (No source references in data)

**Example**:

```
GET /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`: `yegah` (for IbnSina, Meshshaqa), `ushayran` (for al-Farabi), or `rast` (for CairoCongress)
* `pitchClassDataType`: `cents` (or `fraction`, `all`, etc.)

**Example**:

```bash
GET /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 /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 /api/maqamat/maqam_hijaz?tuningSystem=alsabbagh_1954&startingNote=rast&pitchClassDataType=cents
```

***

**Complex and transposed maqāmāt:**

### rāḥat al-arwāḥ - `maqam_rahat_al-arwah`

**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 /api/maqamat/maqam_rahat_al-arwah?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 /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 /api/maqamat/maqam_kurd?tuningSystem=alkindi_874&startingNote=ushayran&pitchClassDataType=cents
```

***

### maqām āthār 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 /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 /api/maqamat/maqam_dilkesh-huran?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents
```

***

## Representative Usage Patterns

### Basic Detail Request

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents"
```

### With All Optional Parameters

```bash
curl "https://diarmaqar.netlify.app/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.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&options=true"
```

### Comparison Across Tuning Systems

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/maqam_rast/compare?tuningSystems=ibnsina_1037,alfarabi_950g&startingNote=yegah&pitchClassDataType=cents"
```

### Transposition

```bash
curl "https://diarmaqar.netlify.app/api/maqamat/maqam_rast?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents&transposeTo=nawa"
```

***

## 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/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.

### Research Framework

**Oud-Based Systems (ʿushayrān):**

* Reflect oud tuning in perfect fourths
* Instrument-specific approaches
* Examples: Al-Kindī, Al-Fārābī (oud conventions)

**Monochord/Sonometer Systems (yegāh/rāst):**

* Abstract theoretical measurement
* Cairo Congress (1932) approaches
* Examples: Modern theoretical frameworks

### 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

Analyze relationships between:

* Number of pitch classes and available maqāmāt
* Starting note convention and transposition possibilities
* Tuning system complexity and modulation network density

## Musicological Research

The platform enables systematic analysis of traditional repertoire that would be extremely laborious through manual methods.

### Arabic Composition Practice

**Historical Analysis:**

* Compare modulation pathways in compositions for Um Kulthūm by:
  * Muḥammad ʿAbd al-Wahhāb
  * Riyāḍ Al-Ṣunbāṭī
  * Balīgh Ḥamdī
* Reveal compositional patterns beyond documented frameworks
* Identify innovations in modulation practice

### Maqām Naming and Classification

**Theoretical Investigation:**

* Analyze comma-based systems (Al-Ṣabbāgh)
* Understand relationship between transposition and naming
* Examine why same pitch classes with different transpositions receive different names
* Example: Maqām ḥijāz vs. Maqām shad ʿarabān

### Arabic Music Pedagogy

**Tuning and Intonation Analysis:**

* Address contradictory discussions (e.g., Faraj and Shumays 2019)
* Provide reference to specific Arabic tuning systems
* Support nuanced discussions beyond binary debates
* Enable analysis beyond assertions of "arbitrariness"

## 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/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ā"

## 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
```

The bounds safety mechanism ensures transposed suyūr remain within practical tuning system limits, mirroring real-world musical constraints.

## Bilingual Support

Suyūr are preserved in their original Arabic form with English translations:

* Original Arabic prose from historical sources
* English 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 "http://localhost:3000/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 "http://localhost:3000/api/maqamat/maqam_bayyat/transpositions?tuningSystem=alfarabi_950g&startingNote=ushayran"
```

### Via TypeScript Library

```typescript
import { transposeSayr } from '@/functions/transpose'

// Transpose suyūr along with maqām transposition
const originalSayr = maqam.suyur
const transposedMaqam = transpositions[0] // First transposition
const transposedSayr = transposeSayr(originalSayr, maqam, transposedMaqam)
```

## 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/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.

## Using Tanāghīm

### Via REST API

```bash
# Get all available tuning systems (full metadata per tanghīm)
curl http://localhost:3000/api/tuning-systems

# There is no GET /api/tuning-systems/{id}; use list + idName, or pitch classes / maqāmāt in context:
curl "http://localhost:3000/api/tuning-systems/alfarabi_950g/ushayran/pitch-classes?pitchClassDataType=cents"
```

### Via TypeScript Library

```typescript
import { TuningSystem } from '@/models/TuningSystem'
import { getTuningSystemPitchClasses } from '@/functions/getTuningSystemPitchClasses'

// Create tuning system instance
const tuningSystem = new TuningSystem(tuningSystemData)

// Get all pitch classes
const pitchClasses = getTuningSystemPitchClasses(tuningSystem, 'ushayran')
```

## 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/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

**Original (Tahlīl):** Jins kurd starting on dūgāh

* Pattern: dūgāh → kurdī → chahārgāh → nawā
* Intervals: \[specific cents pattern]

**Transposition (Taswīr):** Jins kurd starting on muḥayyar

* Pattern: muhayyar → \[notes maintaining same intervals]
* Name: "jins kurd al-muḥayyar"

### 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-kurdan` |

### Naming Pattern

* **Original form (taḥlīl)**: Uses base name only → `maqam_nahawand`
* **Transposed form (taṣwīr)**: Adds `_al-{tonic}` suffix → `maqam_nahawand_al-kurdan`

### Querying Transposed Maqāmāt

**To find a specific transposition, use base maqam ID + tonic parameters:**

```bash
# Find maqām nahāwand on kurdān
?toMaqam=maqam_nahawand&toTonic=kurdan   # ✅ Correct

# NOT the display name format
?toMaqam=maqam_nahawand_al-kurdan        # ❌ 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-kurdan",
    "maqamDisplayName": "maqām nahāwand al-kurdān",
    "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 "http://localhost:3000/api/maqamat/maqam_rahat_al-arwah/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah"

# Or fetch full pitch-class detail for one realization:
curl "http://localhost:3000/api/maqamat/maqam_rahat_al-arwah?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents"

# The transpositions response includes entries with:
# - Transposed name
# - Ascending/descending sequences
# - Recalculated ajnās
# - Transposed suyūr
```

### Via TypeScript Library

```typescript
import { getJinsTranspositions, getMaqamTranspositions } from '@/functions/transpose'

// Get all jins transpositions
const jinsTranspositions = getJinsTranspositions(jins, tuningSystem)

// Get all maqām transpositions
const maqamTranspositions = getMaqamTranspositions(maqam, tuningSystem)

// Each transposition includes:
// - Name (following Arabic convention)
// - Starting note
// - All pitch classes with mathematical values
// - Constituent ajnās (for maqāmāt)
// - Transposed suyūr (for maqāmāt)
```

## 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/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/library.md
description: Complete TypeScript/JavaScript library documentation
---

# TypeScript Library Documentation

The DiArMaqAr TypeScript library provides a comprehensive, type-safe interface for working with maqām data programmatically.

## Overview

The library is organized into several key modules:

* **Models**: Core data structures (Maqam, Jins, TuningSystem, PitchClass, NoteName)
* **Functions**: Utility functions for processing, transposition, modulation, and export
* **Interfaces**: Type definitions for data structures

## Installation

Import directly from the source code in your project.

## Basic Usage

```typescript
import { Maqam } from '@/models/Maqam'
import { TuningSystem } from '@/models/TuningSystem'
import { getTuningSystemPitchClasses } from '@/functions/getTuningSystemPitchClasses'

// Load data
const tuningSystem = new TuningSystem(tuningSystemData)
const maqam = new Maqam(maqamData)

// Work with pitch classes
const pitchClasses = getTuningSystemPitchClasses(tuningSystem, 'ushayran')
```

## Library Reference

The complete TypeScript library reference documentation is generated from JSDoc comments in the source code. The documentation is organized by modules:

* **[Complete Reference](./api/README.md)** - Overview and index of all documentation
* **[Modules Index](./api/modules.md)** - All available modules

### Models

* **[Maqam](./api/models/Maqam/README.md)** - Maqām data structure and methods
* **[Jins](./api/models/Jins/README.md)** - Jins (tri/tetra/penta-chord) data structure
* **[TuningSystem](./api/models/TuningSystem/README.md)** - Tuning system definitions
* **[PitchClass](./api/models/PitchClass/README.md)** - Individual pitch class data
* **[NoteName](./api/models/NoteName/README.md)** - Note name handling and transliteration
* **[Pattern](./api/models/Pattern/README.md)** - Pattern data structures

### Functions

Browse all functions in the [modules documentation](./api/modules.md). Key function modules include:

* **[Export Functions](./api/functions/export/README.md)** - Data export utilities
* **[Transpose Functions](./api/functions/transpose/README.md)** - Transposition calculations
* **[Modulation Functions](./api/functions/modulate/README.md)** - Modulation analysis
* **[Import Functions](./api/functions/import/README.md)** - Data loading utilities

The documentation is automatically generated from TypeScript source files with JSDoc comments. Run `npm run docs:ts` to regenerate after code changes.