aldakit 0.1.3

Python parser and MIDI generator for the Alda music programming language

aldakit

A zero-dependency Python parser and MIDI generator for the Alda music programming language[^1].

[^1]: Includes a rich repl and native MIDI support via bundled prompt-toolkit and libremidi respectively.

Installation

Requires Python 3.10+

pip install aldakit

Or with uv:

uv add aldakit

Quick Start

Command Line

# Evaluate inline code
aldakit -e "piano: c d e f g"

# Interactive REPL
aldakit repl

# Play an Alda file (examples available in the repository)
aldakit examples/twinkle.alda

# Export to MIDI file
aldakit examples/bach-prelude.alda -o bach.mid

Python API

from aldakit import parse, generate_midi, LibremidiBackend

# Parse Alda source code
ast = parse("""
piano:
  (tempo 120)
  o4 c4 d e f | g a b > c
""")

# Generate MIDI sequence
sequence = generate_midi(ast)

# Save to file
backend = LibremidiBackend()
backend.save(sequence, "output.mid")

# Or play directly
with LibremidiBackend() as backend:
    backend.play(sequence)

CLI Reference

aldakit [-h] [--version] [-e CODE] [-o FILE] [--port NAME]
       [--stdin] [--parse-only] [--no-wait] [-v]
       {repl,ports,play} [file]

Subcommands

Command	Description
repl	Interactive REPL with syntax highlighting and auto-completion
ports	List available MIDI output ports
play	Play an Alda file or code (default behavior)

Options

Option	Description
file	Alda file to play (use - for stdin)
-e, --eval CODE	Evaluate Alda code directly
-o, --output FILE	Save to MIDI file instead of playing
--port NAME	MIDI output port name
--stdin	Read from stdin (blank line to play)
--parse-only	Print AST without playing
--no-wait	Don't wait for playback to finish
-v, --verbose	Verbose output

Examples

# Interactive REPL with syntax highlighting
aldakit repl

# List available MIDI ports
aldakit ports

# Play with verbose output
aldakit -v examples/jazz.alda

# Read from stdin
echo "piano: c d e f g" | aldakit -

# Parse and show AST
aldakit --parse-only -e "piano: c/e/g"

# Export to MIDI file
aldakit examples/twinkle.alda -o twinkle.mid

Interactive REPL

The REPL provides an interactive environment for composing and playing Alda code:

aldakit repl

Features:

• Syntax highlighting
• Auto-completion for instruments (3+ characters)
• Command history (persistent across sessions)
• Multi-line paste (use platform-specific paste: ctrl-v, shift-ctrl-v, cmd-v, etc.)
• Multi-line input (Alt+Enter)
• MIDI playback control (Ctrl+C to stop)

REPL Commands:

• :help - Show help
• :quit - Exit REPL
• :ports - List MIDI ports
• :instruments - List available instruments
• :tempo [BPM] - Show/set default tempo
• :stop - Stop playback

Alda Syntax Reference

Notes and Rests

piano:
  c d e f g a b   # Notes
  r               # Rest
  c4 d8 e16       # With duration (4=quarter, 8=eighth, etc.)
  c4. d4..        # Dotted notes
  c500ms d2s      # Milliseconds and seconds

Accidentals

c+    # Sharp
c-    # Flat
c_    # Natural
c++   # Double sharp

Octaves

o4 c    # Set octave to 4
> c     # Octave up
< c     # Octave down

Chords

c/e/g           # C major chord
c1/e/g          # Whole note chord
c/e/g/>c        # With octave change

Ties and Slurs

c1~1            # Tied notes (duration adds)
c4~d~e~f        # Slurred notes (legato)

Parts

piano: c d e

violin "v1": c d e    # With alias

violin/viola/cello "strings":   # Multi-instrument
  c d e

Attributes

(tempo 120)     # Set tempo (BPM)
(tempo! 120)    # Global tempo

(vol 80)        # Volume (0-100)
(volume 80)

(quant 90)      # Quantization/legato (0-100)

(panning 50)    # Pan (0=left, 100=right)

# Dynamic markings
(pp) (p) (mp) (mf) (f) (ff)

Variables

riff = c8 d e f g4

piano:
  riff riff > riff

Repeats

c*4             # Repeat note 4 times
[c d e]*4       # Repeat sequence
[c d e f]*8     # 8 times

Cram (Tuplets)

{c d e}4        # Triplet in quarter note
{c d e f g}2    # Quintuplet in half note
{c {d e} f}4    # Nested cram

Voices

piano:
  V1: c4 d e f
  V2: e4 f g a
  V0:           # End voices

Markers

piano:
  c d e f
  %chorus
  g a b > c

violin:
  @chorus       # Jump to chorus marker
  e f g a

Supported Instruments

All 128 General MIDI instruments are supported. Common examples:

• piano, acoustic-grand-piano
• violin, viola, cello, contrabass
• flute, oboe, clarinet, bassoon
• trumpet, trombone, french-horn, tuba
• acoustic-guitar, electric-guitar-clean, electric-bass
• choir, strings, brass-section

See midi/types.py for the complete mapping.

MIDI Backend

aldakit uses libremidi via nanobind for cross-platform MIDI I/O:

• Low-latency realtime playback
• Virtual MIDI port support (AldaPyMIDI), makes it easy to just send to your DAW.
• Pure Python MIDI file writing (no external dependencies)
• Cross-platform: macOS (CoreMIDI), Linux (ALSA), Windows (WinMM)
• Supports hardware and software/virtual MIDI ports (FluidSynth, IAC Driver, etc.)

from aldakit import LibremidiBackend

backend = LibremidiBackend()

# List available ports
print(backend.list_output_ports())

# Play to virtual port (visible in DAWs like Ableton Live)
backend.play(sequence)

# Save to MIDI file
backend.save(sequence, "output.mid")

MIDI Playback Setup

Virtual Port (Recommended)

When no hardware MIDI ports are available, aldakit creates a virtual port named "AldaPyMIDI". This port is visible to DAWs and other MIDI software:

1. Start the REPL: aldakit repl
2. In your DAW (Ableton Live, Logic Pro, etc.), look for "AldaPyMIDI" in MIDI input settings
3. Play code in the REPL - notes will be sent to your DAW

Software Synthesizer (FluidSynth)

For high-quality General MIDI playback without hardware, use FluidSynth:

# Install FluidSynth (macOS)
brew install fluidsynth

# Install FluidSynth (Debian/Ubuntu)
sudo apt install fluidsynth 

# Download a SoundFont (e.g., FluidR3_GM.sf2)
# eg. sudo apt install fluid-soundfont-gm
# Place in ~/Music/sf2/

# Start FluidSynth with CoreMIDI (macOS)
fluidsynth -a coreaudio -m coremidi ~/Music/sf2/FluidR3_GM.sf2

# In another terminal, start aldakit
aldakit repl
# aldakit> piano: c d e f g

A helper script is available in the repository:

# Set the SoundFont directory (add to your shell profile)
export ALDAPY_SF2_DIR=~/Music/sf2

# Run with default SoundFont (FluidR3_GM.sf2)
python scripts/fluidsynth-gm.py

# Or specify a SoundFont directly
python scripts/fluidsynth-gm.py /path/to/soundfont.sf2

# List available SoundFonts
python scripts/fluidsynth-gm.py --list

Hardware MIDI

Connect a USB MIDI interface or synthesizer, then:

# List available ports
aldakit ports

# Play to a specific port
aldakit --port "My MIDI Device" examples/twinkle.alda

MIDI File Export

If you don't have MIDI playback set up, export to a file:

# Save to MIDI file
aldakit examples/twinkle.alda -o twinkle.mid

# Open with default app
open twinkle.mid

Development

Setup

git clone https://github.com/shakfu/aldakit.git
cd aldakit
make  # Build the libremidi extension

Run Tests

make test
# or
uv run pytest tests/ -v

Architecture

License

MIT

See Also

• Alda - The original Alda language and reference implementation
• Alda Cheat Sheet - Syntax reference
• Extending aldakit - Design document for programmatic API
• libremidi - A modern C++ MIDI 1 / MIDI 2 real-time & file I/O library. Supports Windows, macOS, Linux and WebMIDI.
• nanobind - a tiny and efficient C++/Python bindings