Maqamusic

An accessible Arabic maqam musical keyboard for NVDA.

Maqamusic turns your computer keyboard into an Arabic maqam instrument — the modal, quarter-tone system of Middle-Eastern (oriental) music — played and spoken through the NVDA screen reader, for blind and low-vision musicians. It is written in pure Python and ships as a single NVDA add-on with no external dependencies.

Press NVDA+Shift+M to start playing, and F1 for the list of commands.

Features

• A full maqam keyboard. Play any of 21 maqamat with correct quarter-tone tuning, across three rows of keys, with flat and half-flat accidentals on Shift and Alt.
• Three sound engines, switchable on the fly (NVDA+Shift+E):
  • a built-in pure-Python synth (no dependencies, instant),
  • a SoundFont engine that plays any .sf2 file you point it at (a General-MIDI font is bundled), and
  • an enhanced WebAudio engine that opens the full Web Audio simulator in an embedded browser view.
• A percussion kit: turn the keyboard into drums and hand percussion — over sixty sounds reachable across the rows with Shift and Alt.
• MIDI in and out. Load a MIDI file, hear it, isolate any track, transpose, retune to a maqam, quantise, swing, humanise, add a drone, and export.
• A layer editor for MIDI and for the human-readable .mqm text format: open a piece as layers, play any layer or note alone, edit notes as plain text (or add them from dialogs with lists), and export back to MIDI with no loss.
• .mqm — music as text. A simple, hand-editable text format for maqam music, including quarter tones. A full guide is included (doc/en/mqm-guide.html).
• Practice games: interval, maqam and rhythm recognition, and call-and-response.
• Spoken, screen-reader-first design throughout, in English and Arabic.

Installing

1. Download the latest Maqamusic-<version>.nvda-addon from the Releases page.
2. Open it (or, in NVDA, use Tools → Add-on store → Install from external source).
3. Restart NVDA when prompted.
4. Press NVDA+Shift+M to turn the keyboard on, then F1 for help.

Requires NVDA 2023.1 or newer.

Building from source

The add-on is a normal NVDA add-on package (a renamed zip). You can build it with the included script, which needs only Python 3 — no SCons, no compiler, no third-party libraries:

python3 build.py

This produces Maqamusic-<version>.nvda-addon in the project root, along with a matching source zip. The version, name, author and other metadata come from manifest.ini and buildVars.py.

The bundled SoundFont (globalPlugins/maqamKeyboard/soundfonts/maqam_gm.sf2) is generated from pure-Python synthesis; to regenerate it:

python3 -c "import sys; sys.path.insert(0,'globalPlugins/maqamKeyboard'); import build_soundfont as b; b.build('globalPlugins/maqamKeyboard/soundfonts/maqam_gm.sf2')"

Repository layout

manifest.ini                     add-on metadata (name, version, author, …)
buildVars.py                     build metadata for the NVDA add-on template
build.py                         dependency-free build script (makes the .nvda-addon)
LICENSE                          GNU GPL v2
globalPlugins/maqamKeyboard/     the add-on itself (all Python modules)
  __init__.py                    the NVDA global plugin (commands, keyboard, engines)
  synth.py  mixer.py             the built-in pure-Python audio engine
  sfengine.py                    the SoundFont (.sf2) engine
  build_soundfont.py             generates the bundled General-MIDI SoundFont
  midifile.py  midiplayer.py     MIDI reading, writing and playback
  mqm.py                         the .mqm text music format
  editorwindow.py                the layer editor and tool windows (wx)
  maqamat.py  maqamtheory.py     the maqam and jins definitions and theory
  iqaat.py  ornaments.py         rhythms (iqa'at) and ornamentation
  …                              (and more: analysis, transforms, trainer, etc.)
  web/maqam.html                 the WebAudio simulator
  soundfonts/maqam_gm.sf2        the bundled General-MIDI SoundFont
locale/ar/LC_MESSAGES/           Arabic translation (.po/.mo)
doc/en/  doc/ar/                 English and Arabic documentation
  readme.html                    the in-add-on manual
  mqm-guide.html                 a friendly guide to writing .mqm files

A note on the audio engines

The built-in engine is deliberately compact (pure Python, single file). For a fuller sound, switch to the SoundFont engine and load a high-quality .sf2, or try the enhanced WebAudio engine. All three are built in — nothing separate to install.

Contributing

Issues and pull requests are welcome. Because the add-on runs inside NVDA's frozen Python, please keep the shipped code to the standard library only — no numpy/scipy/ffmpeg or other native dependencies. Audio and screen-reader behaviour can only be fully tested inside NVDA on Windows, so please describe testing done on real hardware.

Author and license

Created by Riad Assoum (رياض أسّوم).

Released under the GNU General Public License, version 2 — see LICENSE. NVDA is a product of NV Access.