Arabic Maqām tuning plugin for any DAW.
Tanghīm is an open-source plugin that dynamically accesses Arabic maqām tuning data from the Digital Arabic Maqām Archive (DiArMaqAr) API and applies it tuning to your software and hardware instruments. Importantly, all tuning data is easily modifiable so that users can tailor the intonation to their personal tastes without being bound to the data.
It is available as VST3, AU, and CLAP on macOS, Windows, and Linux. Three tuning methods — MTS-ESP, MPE, and Mono Pitch Bend — ensure compatibility with virtually any synthesizer.
Internet access is needed only when selecting a tuning — once selected, the tuning data is saved in a cache on your local drive.
The project consists of two plugins for use in any DAW (Desktop Audio Workstation):
- Tanghim (Transmitter) — the main plugin with a full graphical interface. Broadcasts tuning via MTS-ESP and hosts a built-in reference oscillator.
- Tanghim Receiver — a lightweight MIDI effect plugin that reads the MTS-ESP tuning broadcast and delivers it to non-MTS-ESP instruments as MPE per-note pitch bend or monophonic 14-bit pitch bend per MIDI channel.
For use with Ableton Live the user is obliged to use the main Transmitter plugin alongside the included Max for Live devices because Live does not allow MIDI Plugins in any format. To solve this we provide:
- Tanghim MPE Receiver — A Max for Live MPE MIDI Effect that should be used with MPE enabled synthesisers
- Tanghim Mono PB Receiver — A Max For Live Monophonic Pitch Bend MIDI Effect that should be used with non-MPE enabled synthesisers
As of Live 12, all Live instruments support MPE. In Live 11, only the following Live devices support MPE: Drift, Wavetable, Sampler, Simpler (MPE settings can be changed by converting to Sampler), Arpeggiator, AAS devices (Analog, Tension, Collision, Electric). For more info check the dedicated instructions below: Using Tanghim in Ableton Live
Tanghīm was concieved and designed by Khyam Allami as part of his postdoctoral research in the Music Intelligence Lab at the American University of Beirut, 2026.
- Installation
- Quick Start
- Interface Overview
- Tuning Systems and Starting Note Names
- Maqam Selection
- The Slider Bank
- Reference Frequency
- Presets
- MIDI Preset Mapping
- Tuning Methods
- Utility Modes
- Tanghim Receiver
- MIDI File Export
- Save & Load State Files
- DAW Automation
- Using Tanghim in Ableton Live
- Troubleshooting
Download the latest release for your platform from the GitHub Releases page.
For Ableton Live check the dedicated instructions below: Using Tanghim in Ableton Live
For all other DAWs continue as follows:
You should have two plugins after installation:
- Tanghim (Transmitter) —
.vst3/.component/.clap - Tanghim Receiver —
.vst3/.component/.clap
If they didn't auto install correctly, copy the two plugin files to the appropriate system directories for your operating system. After installing/copying, rescan plugins in your DAW if they don't appear immediately.
| Format | Install Path |
|---|---|
| VST3 | ~/Library/Audio/Plug-Ins/VST3/ |
| AU | ~/Library/Audio/Plug-Ins/Components/ |
| CLAP | ~/Library/Audio/Plug-Ins/CLAP/ |
On first launch, macOS may block the plugin. Right-click the .vst3 bundle → Open to bypass Gatekeeper, or go to System Settings → Privacy & Security and click Allow.
| Format | Install Path |
|---|---|
| VST3 | C:\Program Files\Common Files\VST3\ |
| CLAP | C:\Program Files\Common Files\CLAP\ |
AU is not available on Windows.
| Format | Install Path |
|---|---|
| VST3 | ~/.vst3/ |
| CLAP | ~/.clap/ |
AU is not available on Linux. Some DAWs also check /usr/lib/vst3/ and /usr/lib/clap/ — consult your DAW's documentation if the plugin isn't detected.
Tanghīm broadcasts tuning through ODDSound's MTS-ESP system, which relies on a shared system library (libMTS) that all MTS-ESP software loads at runtime. The installers install it for you — you only need this section if you installed the plugins manually, or if tuning isn't reaching your synth.
Symptom of a missing library: the MTS-ESP badge lights up in Tanghīm (it looks connected), but no synth is actually retuned — MTS-ESP-native synths (e.g. Surge) don't appear in the badge count, and the MPE / Mono PB receivers stay at standard 12-tone tuning. If this happens, install the library to the system location for your OS:
| Platform | Library path |
|---|---|
| macOS | /Library/Application Support/MTS-ESP/libMTS.dylib |
| Windows | C:\Program Files\Common Files\MTS-ESP\LIBMTS.dll |
| Linux | /usr/local/lib/libMTS.so |
The library file is bundled with each release. It is shared across all MTS-ESP products on your machine, so installers only add it if it isn't already present and never remove it on uninstall.
Tanghīm stores cached tuning data, settings, and exported MIDI files locally:
| macOS | Windows | Linux | |
|---|---|---|---|
| Settings | ~/Library/Tanghim/settings.json |
%APPDATA%\Tanghim\settings.json |
~/.config/Tanghim/settings.json |
| Cache | ~/Library/Tanghim/cache/ |
%APPDATA%\Tanghim\cache\ |
~/.config/Tanghim/cache/ |
| MIDI export | ~/Library/Tanghim/midi-export/ |
%APPDATA%\Tanghim\midi-export\ |
~/.config/Tanghim/midi-export/ |
Each release ships a standalone uninstaller that fully removes Tanghīm — both plug-ins, the Max for Live devices and Max package (if installed), and all local data (cached tuning data, settings, presets, exported MIDI).
| Platform | How to uninstall |
|---|---|
| macOS | Download uninstall-macos.sh from the release, then run sudo bash uninstall-macos.sh |
| Windows | Download uninstall-windows.bat from the release, right-click it → Run as administrator |
| Linux | Delete the plug-in files from ~/.vst3/ and ~/.clap/, and the data folder ~/.config/Tanghim/ |
Reinstalling does not require uninstalling first. Every installer automatically clears the previous version's files (in all locations, including any left in wrong folders by older builds) before installing the new ones, while preserving your settings, presets, and cache. Use the uninstaller only for a complete removal or a fully clean reset.
- Load Tanghīm on an instrument track in your DAW (it appears under Instruments / Tools).
- Choose a tuning system from the dropdown at the top left (e.g. "Ibn Sīnā (1037) 7-Fret Oud 17-Tone").
- Choose a starting note name from the dropdown next to it (e.g. "yegāh").
- Select a maqam from the maqam selector dropdown.
- Play your MIDI keyboard. Your instrument will receive the tuning via one of three methods depending on its capabilities — see Tuning Methods.
The Tanghīm window is organized into three main areas:
- Tuning System Selector (left) — choose the tuning system and starting note name. Dropdowns show contextual placeholders (e.g. "Loading…", "Select Tuning System") and disable when their prerequisite hasn't been selected yet
- Reference Frequency Control (center) — adjust the reference pitch
- Mode Badges (right) — status indicators for MTS-ESP, MPE, and Mono PB connections; clickable toggles for Oscillator and Heptatonic modes
- Maqam Selector — searchable dropdown for maqam + variant/transposition. Cache status indicators (green ticks) show which starting note / maqam combinations have been cached locally
- Preset Bar — 8 preset slots for saving and recalling maqam configurations
- 12 chromatic pitch sliders — fine-tune each pitch class with cent-accurate control; multiple tuning variants per pitch class appear as snap markers
- Range Scroller — navigate the full MIDI range; magnetic snap to C, G, and A positions
- Piano key indicators — white/black key bars beneath each slider
- Version and build info (left)
- Download status indicator — shows "Downloading…" during data fetches, or "No internet connection" with a Retry button if the connection fails
- MIDI preset mapping controls, MIDI drag export, Clear Cache, and Check for Updates (right)
A tuning system (tanghīm) is an ordered sequence of pitch classes within an octave. The tuning system selector lets you browse all available systems from the DiArMaqAr API. The plugin automatically checks for new data when it loads; if updates are available, the Check for Updates button in the status bar turns gold.
Each tuning system has one or more starting note names — the name for the foundational pitch from which the tuning begins. Starting note names are not arbitrary transpositions; they reflect the historical and practical origins of each system:
- Oud-based systems (e.g. al-Kindī, al-Fārābī, Ibn Sīnā) typically start on ʿushayrān, reflecting oud tuning in perfect fourths
- Monochord and sonometer systems (e.g. Cairo Congress 1932) typically start on yegāh or rāst, reflecting theoretical measurement approaches
The starting note name matters because it determines the available maqāmāt, transposition possibilities, and modulation characteristics of the system. Changing the starting note name changes which maqamat are available and how they can be transposed — it is functionally the same as switching to a different tuning system entirely.
The plugin caches tuning data locally, so internet access is only needed the first time you select a particular tuning system and starting note name combination.
The maqam selector is a two-part dropdown:
- Maqam name — searchable list of all maqamat available in the selected tuning system
- Variant / Transposition — when a maqam has multiple transpositions, a second dropdown appears. Each entry is labeled with the tonic's PAO name, IPN reference, and solfège — for example,
nawā / G3 / Sol3 (qarār)for the base position, ordūgāh / D3 / Re3for a transposition
When a maqam is selected:
- The slider bank snaps to the maqam's interval pattern
- Degree highlights (gold) mark which sliders correspond to maqam degrees
- Slider labels update to show context-aware IPN names (e.g. "F#" in Hijaz vs "Gb" in Saba)
- The range scroller centers on the maqam's octave
The slider bank presents 12 sliders — one for each chromatic step of the octave — arranged in the standard Anglo-European chromatic order: C, C#, D, D# (Eb), E, F, F#, G, G# (Ab), A, A# (Bb), B. Each slider controls the tuning of its dedicated pitch class. The same tuning applies to that pitch class across all octaves (unless overridden per-note — see below).
Arabic maqām tuning systems define far more than 12 pitch classes per octave — for example, the modern Arabic system has 24 distinct pitches whilst Ibn Sīnā's tuning system from (11th century) defines 17 distinct pitches. Tanghīm resolves this by assigning each pitch class to the chromatic slider it is a variant of, based on Arabic musicological logic and the 12-tone chromatic system documented by Al-Kindi (9th century).
For example, in the 24-tone system starting on yegāh, the pitches between D and G map as follows:
| Slider | Snap markers (variants) | PAO names |
|---|---|---|
| E | E−b (half-flat), E♮ | segāh, būselīk |
| F | F♮, F+# (half-sharp) | chahārgāh, tīk būselīk |
| F# | F#♮, F#+# (half-sharp) | nīm ḥijāz, ḥijāz |
| G | G♮ | nawā |
The key principle: each pitch is a variant of the chromatic note it modifies, not the chromatic note it is closest to. For example the half-flat E (segāh, E−b) lives on the E slider because it is a lowered E, not a raised Eb. Similarly, a half-sharp F (tīk būselīk, F+#) lives on the F slider because it is a raised F.
When a slider has multiple variants, small snap markers on the slider track indicate each available tuning position. They can also be overridden for user defined tuning changes.
Snap markers indicate the tuning positions defined by the selected tuning system. When you select a maqam, the sliders snap to these positions automatically. However, snap markers are only a starting point. You are free to drag any slider away from its marker to adjust the tuning by ear. This is a core feature of Tanghīm — tuning systems in the database represent theoretical models, but in practice, performers constantly adjust intonation based on context, taste, and tradition. The sliders let you do exactly that: start from a theoretical tuning and refine it to match what sounds right to you.
When you move a slider away from its snapped position, the thumb turns cyan and the maqam name shows an asterisk (*) suffix, indicating the tuning has been modified from its theoretical values.
There are two ways to override the tuning of a pitch class:
All octaves (drag) — Drag a slider normally to adjust that pitch class across every octave at once. For example, dragging the D slider changes the tuning of every D on the keyboard (D2, D3, D4, etc.). This is the most common way to refine a tuning. Modified sliders show a cyan thumb (maqam degrees) or teal thumb (non-degree notes).
Single octave (Shift+drag) — Hold Shift and drag a slider to adjust the tuning of that note in only the current octave, leaving the same pitch class in all other octaves unchanged. This is useful when you need a note to be tuned differently in one register — for example, a slightly sharper segāh in a higher octave. Per-note overridden notes show a blue thumb glow.
- Variant selector (click the note name) — some pitch classes have multiple tuning variants (e.g. different sizes of segāh). Click to cycle through them
The horizontal range bar below the sliders lets you pan across the full MIDI range:
- Drag to scroll
- Double-click to center on the maqam octave
- Magnetic snap to C, G, and A tick marks
The reference frequency control adjusts the frequency of the tuning system's first pitch — for example, yegāh = 98 Hz or ʿushayrān = 110 Hz.
- Arc knob — drag to adjust (±700 cents range)
- Hz input — type an exact frequency; use up/down arrow keys for ±1 Hz nudges
- Cents display — shows the current offset in cents
- Semitone buttons (±) — shift by 100 cents
- Transposition indicator — shows the IPN shift (e.g. "C ↗ C#" or "G ↘ F#−")
The reference frequency persists relatively when switching tuning systems or starting note names. For example, if you select a tuning system with starting note name yegāh = 98 Hz and change it to 100 Hz, then switch the starting note name to ʿushayrān, it will use 112.25 Hz rather than reverting to its default of 110 Hz.
The preset bar has 8 preset slots. Each preset saves:
- The selected maqam and its degree positions
- All 12 slider cent offsets
- Optionally, the tuning system and starting note name (for modified presets)
- Save a preset — select a maqam, then click an empty slot to save the current tuning state to it
- Activate a preset — click a saved preset to load it
- Deactivate a preset — click the active preset again to deactivate it (clears the maqam and resets sliders)
- Delete a preset — click the x on a saved preset to clear that slot
- Map a preset to MIDI — Shift+click a preset to enter MIDI learn mode (requires a MIDI device and channel to be selected first — see MIDI Preset Mapping)
If you adjust sliders after loading a maqam, the preset becomes "modified":
- The name shows an asterisk (
*) - Modified slider thumbs turn cyan
- The tuning system is stored with the preset so it can reload correctly
Presets are stored locally and shared across all DAWs — a preset saved in one DAW will be available in any other. To save and load different groups of presets along with all other settings (reference frequency, tuning system, etc.), use the Save/Load menu to export a .tanghim file (see Save & Load State Files).
When you select a maqam from the dropdown, the plugin automatically activates a matching unmodified preset if one exists.
You can map MIDI notes to presets so you can switch between maqamat during performance using a MIDI controller.
- In the status bar, select your MIDI input device and channel from the dropdowns
- Shift+click a preset slot to enter learn mode
- Play the desired MIDI note on your controller
- The note is now mapped — a badge appears on the preset showing the assigned note
Click the note badge on a preset to remove the mapping.
- MIDI preset mapping uses a dedicated MIDI input separate from your DAW's MIDI routing, ensuring reliable triggering regardless of DAW state
- MIDI notes on the preset mapping channel are filtered from the oscillator to prevent double-triggering
- Ableton Live users: Ableton merges all incoming MIDI to channel 1 between tracks. If your MIDI controller sends preset pads on a different channel (e.g. channel 10), set Ableton's MIDI track input to a specific channel (e.g. channel 1 for keys) rather than "All Channels". This way, pad notes on channel 10 won't be routed to the plugin and won't accidentally trigger the oscillator. The dedicated MIDI input still receives all channels directly, so preset switching works regardless of this setting
- Device and mapping settings are saved in
~/Library/Tanghim/settings.json
Tanghīm supports three methods for delivering maqam tuning to your instruments. The right choice depends on what your instrument supports. The top bar shows status badges for each active method (these are indicators, not toggles).
MTS-ESP is an open protocol that broadcasts a 128-note frequency table. Instruments that support MTS-ESP retune themselves automatically — no Receiver plugin needed.
- Best for: Software synths with built-in MTS-ESP support
- How it works: Tanghīm broadcasts tuning data via shared memory. Any MTS-ESP-compatible instrument running on the same machine picks it up instantly
- Compatible instruments include: Surge XT, Vital, Diva (enable MTS-ESP in settings), Pianoteq, ZynAddSubFX, and many others
- Setup: Just load Tanghīm and your instrument — the connection is automatic
MPE delivers tuning as per-note pitch bend messages across MIDI channels 2–16. Each note gets its own channel, allowing polyphonic tuning with independent pitch bend per voice.
- Best for: Polyphonic instruments that support MPE but not MTS-ESP, including many hardware synths and some software instruments
- How it works: The Tanghīm Receiver plugin sits before your instrument in the signal chain and converts the MTS-ESP tuning into MPE pitch bend messages
- Default pitch bend range: 48 semitones (set this to match your instrument's MPE pitch bend range)
- Setup: Load Tanghīm Receiver before your instrument and select MPE mode
Mono Pitch Bend delivers tuning as 14-bit pitch bend on a single MIDI channel. This is the most universally compatible method — nearly every synth responds to pitch bend.
- Best for: Monophonic patches, instruments without MPE support, hardware synths, and any instrument that only responds to standard pitch bend
- How it works: The Tanghīm Receiver calculates the required pitch bend for each note and sends it on the same channel. Includes a note stack with last-note priority for legato playing
- Default pitch bend range: 2 semitones (set this to match your instrument's pitch bend range)
- Setup: Load Tanghīm Receiver before your instrument and select Mono PB mode
| Your Instrument | Recommended Method |
|---|---|
| Software synth with MTS-ESP support (Surge XT, Vital, Pianoteq, etc.) | MTS-ESP — zero setup, polyphonic, highest precision |
| Software synth with MPE support but no MTS-ESP | MPE — polyphonic tuning via Receiver |
| Hardware synth with MPE support | MPE — polyphonic tuning via Receiver |
| Hardware synth (standard MIDI only) | Mono PB — works with any pitch-bend-capable instrument |
| Monophonic synth or mono patch | Mono PB — simplest, most compatible |
| Instrument with no pitch bend at all | MTS-ESP is the only option (if supported) |
You can use multiple methods simultaneously — for example, MTS-ESP for your main synths and a Receiver in Mono PB mode for a hardware synth, all driven by the same Tanghīm instance.
In addition to the tuning delivery methods above, Tanghīm has two utility modes. Unlike the tuning method badges (which are status indicators), these are clickable toggles in the top bar.
Click the Osc badge to enable a built-in 16-voice polyphonic triangle wave synthesizer. This lets you hear and audition tunings directly from the plugin without needing any external instrument loaded. The oscillator responds to MIDI input just like a regular synth — play notes and you'll hear the current tuning immediately.
The oscillator runs alongside the tuning output, so you can use it at the same time as your other instruments. It's particularly useful for:
- Quickly previewing how a maqam or tuning system sounds before setting up instruments
- Verifying tuning adjustments in real time as you move sliders
- Teaching and demonstration purposes
Click the Hept badge to remap your MIDI keyboard so that the white keys play the maqam degrees in order, starting from the tonic's natural key position. Black keys retain their standard chromatic pitch. This mode is only available when a maqam is selected.
Most maqamat are heptatonic (7-note) scales, but on a standard 12-key chromatic keyboard, the scale degrees often fall on a mix of white and black keys depending on the tonic. Heptatonic mode eliminates this problem — no matter what the tonic is, you can play the full maqam scale using just the white keys, making it much easier to play melodies without memorizing which black keys are part of the scale.
Heptatonic mode affects all tuning delivery methods (MTS-ESP, MPE, and Mono PB) simultaneously.
The Receiver is a lightweight MIDI effect plugin that enables MPE and Mono Pitch Bend tuning delivery. It reads the MTS-ESP tuning broadcast from Tanghīm and converts it to pitch bend messages that any instrument can understand. See Tuning Methods for details on when to use MPE vs Mono PB.
- Load Tanghīm on one track (the transmitter)
- Load Tanghīm Receiver before each instrument that needs pitch-bend-based tuning
- Choose MPE or Mono PB mode depending on your instrument (see the comparison table)
- Set the Receiver's pitch bend range to match your instrument's pitch bend range setting
- The Receiver automatically connects to the Transmitter — the status display shows the active tuning system
You can run multiple Receiver instances simultaneously, each in a different mode for different instruments.
Note: Ableton Live does not support VST3 MIDI effect plugins, so the Receiver cannot be loaded directly in Ableton. A Max for Live device is provided instead — see Using Tanghim in Ableton Live for details.
If the player sends pitch bend wheel messages, the Receiver combines them with the tuning bend. This means your pitch wheel works normally on top of the maqam tuning.
You can export the current maqam scale as a Standard MIDI File for use in other applications.
- Click the MIDI drag button in the status bar
- Drag it into your DAW or file manager
- The file is saved to
~/Library/Tanghim/midi-export/ - Filename format:
maqamname_(PAOname-IPN-solfege).mid
The exported file contains all scale degrees played simultaneously as a chord (SMF Type 0, one quarter note).
If a preset is active when you export, a MIDI Program Change message is embedded at the start of the file. When the clip plays back through Tanghim, the preset will automatically activate before the notes sound.
Tanghim responds to MIDI Program Change messages for preset switching:
- PC 0-7 activates presets 1-8 respectively
- Program Change messages from any source (DAW MIDI clips, external controllers, etc.) are accepted
- This is always on — no configuration needed
- Program Change messages are consumed and not passed through to the output
This works alongside MIDI Preset Mapping, which uses a dedicated MIDI input device for note-based switching.
Tanghīm can save and load its complete state as .tanghim files — human-readable JSON that captures your tuning system, maqam, slider positions, presets, and reference frequency.
- Save: File → Save (or use the menu/bridge command) to export a
.tanghimfile - Load: File → Load to restore a saved state
This is useful for sharing tuning configurations or backing up your setup outside of DAW project files.
Tanghīm exposes its key tuning parameters to your DAW's automation system. You can draw automation curves, map MIDI CC, or use any DAW automation feature to control these parameters in real time.
| Parameter | Range | Description |
|---|---|---|
Slider 1 – Slider 12 |
±150 cents | Cents deviation for each of the 12 chromatic pitch classes. Slider 1 = C, Slider 2 = C#, etc. |
Ref Freq |
±700 cents | Reference frequency offset from the tuning system's default |
Preset |
None, 1–8 | Active preset index. Automate this to switch between saved maqam presets at specific points in your arrangement |
- Automating sliders (
Slider 1–Slider 12) lets you smoothly glide tuning between positions — useful for creative effects or gradual intonation shifts during a performance - Automating the preset parameter is a simple way to switch between maqamat at defined points in a song without MIDI preset mapping
- Automating the reference frequency lets you create pitch drifts or transpose the entire tuning smoothly over time
- All automation updates are applied at audio-rate for glitch-free transitions
- Automation and manual slider adjustments coexist — the last value written (whether from automation or the UI) takes effect
Most DAWs allow you to map MIDI CC messages to plugin parameters. This means you can control any of the above parameters from a hardware MIDI controller's knobs or faders. Consult your DAW's documentation for how to set up MIDI CC → parameter mapping (sometimes called "MIDI Learn" on the DAW side — this is separate from Tanghīm's own MIDI preset mapping feature).
Ableton Live has some specific requirements and limitations that affect how Tanghīm works. This section covers everything you need to know.
Ableton Live does not support VST3 MIDI effects. This means the Tanghīm Receiver plugin (which is a MIDI effect) cannot be loaded directly in Ableton as it can in other DAWs. Additionally, Ableton merges all MIDI to channel 1 between tracks, which breaks MPE routing between tracks.
To work around these limitations, Tanghīm provides a Max for Live Receiver device that replicates the Receiver's MPE and Mono Pitch Bend functionality within Ableton's MIDI effect framework.
If your instrument supports MTS-ESP, this is the simplest path — no Receiver or M4L device needed.
- Create a new MIDI track
- Load Tanghīm as an instrument on that track
- On any other instrument track, load an MTS-ESP-compatible synth (e.g. Surge XT, Vital)
- The synth will automatically receive the tuning broadcast
For instruments that don't support MTS-ESP — including hardware synths and many software instruments — Tanghīm ships two native Max for Live devices that deliver tuning via MPE or Mono Pitch Bend, just like the standalone Receiver plugin:
- Tanghim MPE Receiver.amxd — per-note channel allocation with per-note pitch bend (MPE)
- Tanghim Mono PB Receiver.amxd — single-channel monophonic 14-bit pitch bend
The macOS and Windows installers install both devices and the required Max package automatically when the M4L component is enabled. If you're building from source:
- Copy both
.amxdfiles fromm4l/into:~/Music/Ableton/User Library/Presets/MIDI Effects/Max MIDI Effect/Tanghim/ - Copy the entire
m4l/MTS-ESP-Max-Package/directory into both:~/Documents/Max 8/Packages/MTS-ESP-Max-Package/ (Live 11) ~/Documents/Max 9/Packages/MTS-ESP-Max-Package/ (Live 12) - Restart Ableton Live.
The Max package contains the ODDSound MTS-ESP externals (the MTS-ESP.mtof Max object the receiver patches use). It must live in the Max Packages folder (not Library/) so Max registers it as a structured package — a standalone external next to the .amxd does not work for frozen Max for Live devices.
- Load the main Tanghīm plugin on one MIDI track
- On your instrument track, add either Tanghim MPE Receiver or Tanghim Mono PB Receiver as a MIDI effect before your instrument (choose based on the comparison table)
- Set the pitch bend range in the device to match your instrument's setting
- Play — the device reads the MTS-ESP tuning and applies pitch bend to each note
Both devices are pure-native Max patches built on ODDSound's MTS-ESP Max Package. They read the live MTS-ESP tuning broadcast directly (no VST3 bridge, no JavaScript) and emit standard MPE or 14-bit mono pitch-bend MIDI. The MPE and Mono PB versions are shipped as separate .amxd files because the is_mpe patcher flag is set at patch-load time and cannot be toggled at runtime.
- Computer MIDI Keyboard: When the Tanghīm plugin window is focused, Ableton's built-in computer keyboard MIDI input is disabled (this is standard DAW behavior when a plugin window has focus). Workaround: click outside the plugin window to return focus to Ableton, or use an external MIDI controller (which is unaffected).
- Plugin scanning: On Apple Silicon Macs, Ableton's plugin scanner runs under Rosetta (x86_64). The plugin is built as a universal binary to ensure compatibility.
- MIDI routing between tracks: Ableton normalizes MIDI to channel 1 between tracks. This is why the standalone Receiver VST3 cannot be used in Ableton — you must use the M4L Receiver device for MPE and Mono PB delivery, or use MTS-ESP directly.
- MIDI preset mapping with multi-channel controllers: If your MIDI controller sends keys on one channel and pads on another (e.g. keys on ch1, pads on ch10), set the Ableton track's MIDI input to the keys channel only — not "All Channels". Because Ableton merges all channels to ch1, the plugin's channel filter cannot distinguish pad notes from key notes if both arrive on the same channel. The dedicated MIDI preset input receives directly from the device and preserves channel info, so preset switching works correctly regardless.
- Verify the plugin files are in the correct directory for your OS (see Installation)
- Rescan plugins in your DAW's preferences
- On macOS, you may need to bypass Gatekeeper (see macOS installation notes)
- Ensure only one Tanghīm transmitter instance is running. Multiple transmitters will conflict
- Check that your instrument has MTS-ESP support enabled in its settings
- Check that the MTS-ESP badge (teal) is lit in the top bar, confirming the transmitter is active
If you're building from source: when reinstalling the plugin, you must delete the old .vst3 bundle before copying the new one. Overwriting corrupts macOS's kernel code signature cache, causing Ableton's Rosetta plugin scanner to kill the plugin. Always:
rm -rf ~/Library/Audio/Plug-Ins/VST3/Tanghim.vst3
# then copy the new build- Click the Osc badge (amber) in the top bar to make sure it's enabled
- Check that MIDI is reaching the plugin (the slider bank shows gold thumb glows on active notes)
- The oscillator is quiet by design (−18 dBFS) — check your output volume
Click Check for Updates in the status bar — the plugin also checks automatically when it loads. If updates are available, the button turns gold and reads "Update Available"; click it to download the latest data. You can also click Clear Cache (which asks for confirmation) to wipe all cached tuning data and force a fresh fetch on next load. Your presets are preserved.
- Check that the correct MIDI input device and channel are selected in the status bar
- If the device was disconnected and reconnected, the plugin should auto-detect it. If not, reselect it from the dropdown
Conceived and designed by Khyam Allami at the Music Intelligence Lab, American University of Beirut, 2026.
Accesses tuning data via the Digital Arabic Maqām Archive (DiArMaqAr) API and broadcasts tuning via the MTS-ESP protocol.
Coded with Claude.
Built with JUCE 8.