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:
- Extracting the interval pattern from the original structure
- Systematically applying the pattern to all possible starting points
- Pattern matching against the tuning system's available pitch classes
- Preserving intervallic relationships while adapting to new tonal centers
Interval Pattern Extraction
The algorithm:
- Cross-references maqām/jins note name sequences to the tuning system
- Extracts the sequence of intervals between consecutive notes
- Uses these intervals (not fixed pitches) as the pattern to match
Matching Process
For systems using fractional ratios:
- Requires exact fractional ratio matches
- Mathematical precision is preserved
For systems using any other original input data type (decimal ratios, string lengths, fret divisions or cents):
- Uses cents values for matching
- Applies user-definable ±cents tolerance (default: ±5 cents, Just Noticeable Difference JND) to allow for performance practice variations.
Jins Transposition
A jins transposition systematically shifts a jins to begin from a different pitch class while preserving its intervallic relationships.
Example: Jins Kurd
Base form: Jins kurd starting on dūgāh
- Pattern: dūgāh → kurdī → chahārgāh → nawā
- Intervals: [specific cents pattern]
Transposition (Taṣwīr): Jins kurd starting on ḥusaynī
- Pattern: ḥusaynī → [notes maintaining same intervals]
- Name: "jins kurd al-ḥusaynī"
Jins kurd on muḥayyar is not a transposition. Muḥayyar is the octave of dūgāh, so it is the base form one octave up: an octave rendering.
Algorithm Characteristics
- Recursive search: Finds all valid starting points
- Early termination: Optimizes performance
- Automatic generation: All possible transpositions are calculated
- Naming convention: Follows Arabic maqām theory ("jins [name] al-[starting note]")
Maqām Transposition
Maqām transposition handles both ascending and descending sequences separately, accounting for the fact that many maqāmāt employ different sequences in their ascent and descent.
Algorithm Details
- Separate Processing: Ascending and descending sequences analyzed independently
- Validation: Ensures all required note names exist in the tuning system
- Interval Preservation: Maintains original intervallic relationships
- Automatic Recalculation: All embedded ajnās recalculated for each transposition
- Suyūr Transposition: Associated suyūr automatically transposed
Example: Maqām Faraḥfazza
Original: Starting on yegāh
- Ascending: yegāh → rāst → dūgāh → ...
- Descending: [possibly different sequence]
Transposition: Starting on rāst → "maqām faraḥfazza al-rāst"
- Ascending: rāst → [transposed maintaining intervals] → ...
- Descending: [transposed maintaining intervals]
- All ajnās recalculated
- All suyūr transposed
Computational Complexity
The implementation employs:
- Recursive sequence building with early termination
- O(n×m×k) complexity where:
- n = available pitch classes
- m = pattern length
- k = tolerance width
This efficiency enables:
- Real-time transposition generation
- Comprehensive dataset export (all transpositions for all maqāmāt)
- Large-scale comparative analysis
API Naming Conventions for Transpositions
When working with transposed maqāmāt in the API, it's important to understand how identifiers work.
Two ID Fields
Each maqām node in API responses includes two identifier fields:
| Field | Purpose | Stability | Example |
|---|---|---|---|
baseMaqamIdName | Query/lookup identifier | Stable across transpositions | maqam_nahawand |
maqamIdName | Display identifier | Changes with transposition | maqam_nahawand_al_nawa |
Naming Pattern
- Base form: Uses base name only →
maqam_nahawand - Transposed form (taṣwīr): Adds
_al_{tonic}suffix →maqam_nahawand_al_nawa - Octave rendering: Adds the same suffix →
maqam_nahawand_al_kurdan(kurdān is the octave of rāst, so this is not a transposition)
Querying Transposed Maqāmāt
To find a specific transposition, use base maqam ID + tonic parameters:
# Find maqām nahāwand on nawā
?toMaqam=maqam_nahawand&toTonic=nawa # ✅ Correct
# NOT the display name format
?toMaqam=maqam_nahawand_al_nawa # ❌ Will not workExample Response
{
"from": {
"baseMaqamIdName": "maqam_rast",
"maqamIdName": "maqam_rast",
"maqamDisplayName": "maqām rāst",
"isTransposition": false
},
"to": {
"baseMaqamIdName": "maqam_nahawand",
"maqamIdName": "maqam_nahawand_al_nawa",
"maqamDisplayName": "maqām nahāwand al-nawā",
"isTransposition": true
}
}TIP
Always use baseMaqamIdName + tonic parameters for API queries. The maqamIdName field is for display purposes and includes the transposition suffix.
Using Transposition
Via REST API
# List all transpositions for a maqām in a tuning context (separate endpoint)
curl "https://diarmaqar.net/api/maqamat/maqam_rahat_alarwah/transpositions?tuningSystem=ibnsina_1037&startingNote=yegah"
# Or fetch full pitch-class detail for one realization:
curl "https://diarmaqar.net/api/maqamat/maqam_rahat_alarwah?tuningSystem=ibnsina_1037&startingNote=yegah&pitchClassDataType=cents"
# The transpositions response includes entries with:
# - Transposed name
# - Ascending/descending sequences
# - Recalculated ajnās
# - Transposed suyūrResearch 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) (related but distinct)
- Explore Tuning Systems and their impact on transposition
- Understand how transposition relates to Ajnās