Maqam

Arabic maqamat — the named melodic modes of Arabic, Turkish, and related music, in their real quarter-tone (just) intonation.

A maqam is more than a scale. It’s built from ajnas (sing. jins), the trichord/tetrachord cells that stack into the full mode, and it has a seyir, the conventional way a melody moves through it (where it starts, where it rests, whether it favours the ascent or the descent). Most of all, a maqam is defined by notes a piano can’t play: the half-flats, the neutral 2nds, 3rds, 6ths and 7ths that sit a quarter-tone away from the tempered grid. Rast’s third (a neutral 27/22, ~355 cents) is the sound of the whole tradition, and it lives in the crack between E-flat and E.

This module encodes the best-known maqamat with their scale degrees, the ajnas they’re built from, the seyir, and — crucially — the 5-limit / quarter-tone ratios, so they render in true intonation rather than snapped to 12-TET.

Degrees are positions in the Do-based Arabic layout (Do = the tonic); ↓ marks a quarter-flat. Like a raga, the tonic is movable.

Example:

>>> from pytheory import Maqam
>>> rast = Maqam.get("rast")
>>> rast.degree_names()
['Do', 'Re', 'Mi↓', 'Fa', 'Sol', 'La', 'Si↓']
>>> rast.maqam_table("C")[2]["cents_off"]      # the neutral 3rd
-45.5
>>> rast.play("C")                              # oud, just intonation

class pytheory.maqam.Maqam(name, *, family, degrees, ajnas, seyir, mood, aka=None)

Bases: object

An Arabic maqam: its scale, ajnas, seyir, and quarter-tone tuning.

name

the maqam’s name.

family

the maqam family (fasila) it belongs to.

degrees

scale positions in the Do-based layout (tonic = 0).

ajnas

the jins cells it’s built from.

seyir

how a melody conventionally moves through it.

mood

its emotional character.

aka

alternative names.

__init__(name, *, family, degrees, ajnas, seyir, mood, aka=None)

degree_names() → list[str]

The ascending scale as Arabic note names (↓ = quarter-flat).

property has_quartertones: bool

Whether the maqam uses any neutral (quarter-tone) degree.

note_names(tonic='C') → list[str]

Nearest 12-TET note names in the key of tonic.

Quarter-tones round to the closest piano key, so half-flats lose their bend here — use maqam_table() or play() for the true intonation.

just_ratios() → dict

Each degree’s just ratio from the tonic (keyed by Arabic name).

maqam_table(tonic='C') → list[dict]

Per-degree tuning: ratio, ≈ note, Hz, and cents off 12-TET.

The neutral degrees come out tens of cents from the piano — that gap is the maqam.

just_frequencies(tonic='C4') → list[float]

The ascending then descending run, just-intoned (Hz).

render(tonic='C4', *, synth='oud', t=420, envelope='pluck', reverb=0.3)

Render the ascending→descending run to a mono sample buffer.

Quarter-tone accurate (the half-flats are voiced where they actually sit), with a reverb tail tying the phrase together. Returns a NumPy array (no audio device needed).

play(tonic='C4', *, synth='oud', t=420, envelope='pluck', reverb=0.3)

Play the maqam (ascending then descending) in just intonation.

Defaults to the oud voice. Like a raga, this is quarter-tone accurate — the half-flats are voiced where they actually sit.

classmethod get(name: str) → Maqam

Look up a maqam by name; an exact name beats any alias.

classmethod all() → list[Maqam]

classmethod names() → list[str]

classmethod by_family(family: str) → list[Maqam]

__repr__() → str

Return repr(self).