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

Theoretical Framework - Understanding the conceptual hierarchy: Tanāghīm → Ajnās → Maqāmāt → Suyūr → Intiqālāt
Tuning Systems - Learn about tanāghīm, mathematical representations, and historical sources
Ajnās - Understanding ajnās (3-5 note sequences) as building blocks of maqāmāt
Maqāmāt - Complete modal frameworks with ascending/descending sequences
Suyūr - Traditional melodic performance pathways

Advanced Features

Taṣwīr (Transposition) - Tuning-system-sensitive transposition of ajnās and maqāmāt
Intiqāl (Modulation) - Al-Shawwā's modulation algorithm and network analysis
Audio Synthesis - Real-time audio playback using Web Audio API
MIDI Integration - MIDI input/output with MPE support for precise non-12-EDO playback
Data Export - Export capabilities: JSON, CSV, Scala formats

Research and Methodology

Research Applications - Use cases for computational musicology, ML/AI, and academic research
Cultural Framework - Decolonial computing principles and culturally-specific methodology
Bibliographic Sources - Complete source attribution system and scholarly verification

Next Steps

Start with Quick Start Guide for immediate hands-on experience
Explore Theoretical Framework to understand core concepts
Visit the API Reference for complete endpoint documentation
Check out the TypeScript Library Documentation for programmatic usage
Visit the Interactive API Playground to test endpoints interactively

Resources

Source Code - View on GitHub
Music Intelligence Lab - Research lab website
Live Application - Interactive web interface

Getting Started ​

What is DiArMaqAr? ​

Key Features ​

Cultural Framework ​

Quick Start ​

Using the REST API ​

Using the TypeScript Library ​

Documentation Guide ​

Core Concepts ​

Advanced Features ​

Research and Methodology ​

Next Steps ​

Resources ​