---
url: /docs/guide/intiqal.md
description: Understanding Al-Shawwā's modulation algorithm and modulation networks
---

# Intiqāl (Modulation)

DiArMaqAr implements the **first algorithmic interpretation** of Sāmī al-Shawwā's (1946) modulation guidelines, enabling systematic exploration of intiqālāt (modulation practices) networks that were previously documented only in prose.

## Overview

Unlike Anglo-European modulation theory, Turkish makam theory, or contemporary Arabic theoretical approaches, Al-Shawwā's method employs specific conditions based on maqām degree relationships within the Persian-Arab-Ottoman note naming framework.

### Historical Context

Sāmī Al-Shawwā, a revered Cairo-born, Aleppine violinist, provided unique guidelines for maqām modulation in his 1946 work *Al-Qawāʿid al-Fannīya fī al-Mūsīqa al-Sharqīya wa al-Gharbīya* (The Artistic Principles of Eastern and Western Music).

**Key Principle:** Modulation should occur through specific maqām degree relationships while maintaining "good disposition" (ḥusn al-taṣarruf) and avoiding abrupt transitions that would be "hard on the ear" (ṣaʿb ʿalā al-udhun).

This approach emphasizes **melodic connection** rather than harmonic compatibility, reflecting the fundamentally melodic nature of maqāmic practice.

## Theoretical Foundation

### The 24-Tone Classification System

Al-Shawwā classified a 24-tone system into three categories based on the Persian-Arab-Ottoman note naming framework:

1. **Aṣlīya or Ṭabīʿīya** (Original/Natural): Represented as "n"
   * These are stable, consonant maqām degrees that form the foundation of maqām structure which are whole tones and three-fourths tones.

2. **Anṣāf** (Half-notes, sing. niṣf): Represented as "h" (niṣf, half)
   * These represent the half-tones

3. **Arbāʿ** (One-fourth notes, sing. rubʿ): Represented as "q" (rubʿ, quarter)
   * These represent one-fourth tones, reflecting our understanding of Arabic maqām theory dividing a whole tone into four unequal parts (not equal divisions)

### The Shawwā Function

Implemented as: *sh(n): N → {"n", "h", "q", "/"}*

This function evaluates the validity of proposed modulations based on the specific classification of individual note names within the 24-tone system. The function returns "n" for natural/original notes, "h" for half-notes (anṣāf), "q" for quarter-notes (arbāʿ), and "/" for notes outside Al-Shawwā's theoretical framework.

## Modulation Rules

The algorithm evaluates multiple cases for valid transitions:

### 1. Tonic Correspondence

Modulation between maqāmāt sharing the same tonic (qarār). Al-Shawwā opens his guidelines by requiring that every maqām rest its qarār "on one of the seven original «natural» notes, or on a niṣf of the seven anṣāf" — so the tonic must be classified as an "original" note ("n") or a half-note ("h"). A quarter-note ("q") tonic falls outside his framework.

### 2. Third-Degree Modulation

Transition where the third degree of the source maqām becomes the tonic of the target, valid only when:

* The third degree is classified as an "original" note (aṣlīya/ṭabīʿīya, represented as "n")

### 3. Alternative Third-Degree Modulation

If the standard third degree is invalid, Al-Shawwā permits using an anṣāf (half-note, represented as "h") maqām degree immediately below it, provided:

* It is the sixth pitch class from the fundamental (qarār) maqām degree of the source maqām according to the 24-tone list
* It maintains a distance of two pitch classes from the preceding maqām degree within the source maqām

### 4. Fourth and Fifth-Degree Modulation

Transitions using the fourth or fifth maqām degrees of the source maqām as the tonic of the target. Al-Shawwā attaches no condition of their own to these degrees. The only constraint is his opening principle that every maqām rests its qarār on an original note or on a niṣf, and a pivot works by hosting the target's qarār — so the fourth or fifth degree must be classified "n" or "h". A "q" (rubʿ) degree can host no qarār.

### 5. Sixth-Degree Modulation (No Third)

When both the third degree and its alternative are invalid, modulation may occur through the sixth maqām degree, provided:

* It is the sixteenth or seventeenth pitch class from the tonic of the source maqām
* It remains an "original" maqām degree (aṣlīya/ṭabīʿīya, represented as "n")

### 6. Sixth-Degree Modulation (Between Naturals)

The sixth maqām degree may also be used when it is a half-note ("h") lying between two "natural" maqām degrees — al-Shawwā's example is ʿajam over dūgāh in maqām al-bayyāt, "a niṣf confined between two natural notes, ḥusaynī and awj". Unlike rule 5 this is not a fallback: bayyāt's third degree is perfectly valid.

## Algorithmic Implementation

The `modulate.ts` function implements these rules using Al-Shawwā's specific 24-tone classification system as the reference framework.

**Process:**

1. Evaluates source maqām's maqām degrees according to Al-Shawwā's classification
2. Tests each modulation rule against potential target maqāmāt
3. Generates list of valid modulation pathways
4. Creates interactive networks showing relationships

## Using Modulation Analysis

### Via REST API

```bash
# Get modulation analysis for a maqām (example: principle maqām used in adhān)
curl "https://diarmaqar.net/api/maqamat/maqam_hijaz?tuningSystem=ibnsina_1037&startingNote=yegah&includeModulations=true&pitchClassDataType=cents"

# Response includes:
# - Valid modulation targets
# - Modulation type (third-degree, fourth-degree, etc.)
# - Network relationships
```

## Research Applications

The implementation of the Shawwā algorithm enables:

### Modulation Network Analysis

* **Interactive lists**: All valid modulation pathways from any maqām
* **Network visualization**: Structural relationships between maqāmāt
* **Hub identification**: Central maqāmāt serving as modulation hubs
* **Cluster analysis**: Groups of closely related modes

### Quantitative Analysis

* **Pattern recognition**: Systematic modulation structures
* **Comparative studies**: How modulation possibilities vary across tuning systems
* **Theoretical investigation**: Validation against historical practices

### Compositional Applications

* **Systematic exploration**: Discover modulation pathways
* **Traditional frameworks**: Informed by historical theory
* **Creative practice**: Contemporary composition grounded in tradition

## Limitations and Context

The modulation algorithm:

* Represents **one theoretical perspective** (Al-Shawwā 1946)
* Is historically accurate to documented approach
* Could benefit from incorporating additional frameworks
* May be supplemented by audio analysis of recorded performances

Future enhancements could integrate:

* Modulation analysis from audio recordings
* Additional theoretical frameworks
* Performance practice documentation
* Contemporary compositional approaches

## Next Steps

* Explore [Taṣwīr (Transposition)](/guide/taswir/) capabilities
* Learn about [Maqāmāt](/guide/maqamat/) structure
* Understand [Bibliographic Sources](/guide/bibliographic-sources/)
* Review [Research Applications](/guide/research-applications/)