🚀 Getting Started

ABC Music Maker is a multi-track DAW built around ABC notation — a plain-text music format. Every song is stored as a human-readable .abc text file. The interface has three main areas:

• Toolbar — file operations, transport controls, global settings, and panel toggles.
• Piano Roll — graphical note editor. Multiple coloured tracks are displayed simultaneously.
• ABC Editor — raw notation editor. Bidirectionally synced with the piano roll.

Typical workflow: Open or create an .abc file → edit notes in the piano roll or editor → pick instruments in the Tracks panel → adjust mix → export audio.

Quick-start: Click New to create a blank song, or Open to load an existing .abc file. Make sure the Integrated Synth is loaded (toolbar button) before playing — it loads the GM soundfont on first use and may take a few seconds.

⌨ Global Keyboard Shortcuts

🎹 Piano Roll — Editing Modes

The piano roll shows all tracks as coloured note blocks on a time/pitch grid. The active track (selected in the Tracks panel) is brighter; other tracks are dimmed but still visible. Switch editing modes via the toolbar mode buttons or keyboard shortcuts:

Navigation:

Grid snap: Notes snap to the current quantisation value shown in the toolbar snap selector. Common values: 1/4, 1/8, 1/16, 1/32, and Triplet variants. Set to Free to place notes without snapping.

▣ Selection & Clipboard

Copy / paste works across tracks — paste adds notes to whichever track is currently active. Copy then switch tracks before pasting to duplicate a phrase onto another instrument.

🎚 Transport & Song Metadata

The transport bar (top of piano roll area) contains the play controls and song-wide settings:

📋 Tracks Panel

Each row represents one ABC voice (V: header). Click a row to make that track active in the piano roll.

📄 ABC Notation Primer

ABC notation represents music as plain text. A minimal single-track file looks like this:

X:1
T:My Song
M:4/4
L:1/8
Q:120
K:C
V:1 name="Piano"
%%MIDI program 0
C D E F | G A B c |

Header fields (before the first note line):

Note syntax: C D E F G A B = middle octave; c d e f g a b = octave above. Add ' to go up an octave, , to go down. Use ^ for sharp, _ for flat, = for natural. Duration multipliers: C2 = double length, C/ = half. Use | for bar lines, z for rests, x for invisible rests.

Chords: Wrap simultaneous notes in square brackets: [CEG].

Tuplets: (3ABC = triplet of A B C.

📝 ABC Editor

The editor is a code editor with ABC-aware syntax highlighting and error checking. Changes you make are reflected in the piano roll when you press Apply (Ctrl Enter). Conversely, every piano-roll edit, track rename, mixer change, or transport adjustment immediately regenerates the ABC text in the editor.

Editor shortcuts:

Auto-Apply toggle (toolbar): When on, the piano roll updates automatically after every keystroke with a short debounce delay. Useful for short compositions; turn off for large files to avoid lag.

Hints mode (toolbar toggle): Enables contextual tooltips that explain ABC tokens as you hover or type — useful for learning the format.

%%MIDI extensions supported in the editor:

🔊 Integrated Synth (SpessaSynth GM)

The primary audio engine is SpessaSynth, a high-quality General MIDI synthesizer that uses the included Integrated_Synth.SF2 soundfont. It supports all 128 GM programs across 16 MIDI channels simultaneously.

• Load it once per session with the Integrated Synth toolbar button. The first load downloads and decodes the SF2 file (~30–60 s on slow machines).
• Once loaded, it remains active for the entire session and is the default playback engine.
• GM program numbers 0–127 correspond to standard instruments: 0=Acoustic Grand Piano, 24=Nylon Guitar, 40=Violin, 56=Trumpet, 73=Flute, etc.
• Channel 10 is always drums — note C2 = Bass Drum, D2 = Snare, F#2 = Hi-hat, etc. (GM drum map).
• Reverb and chorus levels sent via %%MIDI control 91/93 are handled internally by SpessaSynth's built-in effects.

🎛 DX7 FM Synthesizer

A second synth engine based on the Yamaha DX7 FM synthesis model. Runs as a Web Audio Worklet alongside the GM synth. Assign it to a track by selecting a DX7 preset as the track instrument.

Preset Browser: Click any track's instrument button while the DX7 synth engine is loaded to open the DX7 Preset Picker overlay. It provides:

• Search box — type any part of a patch name to filter across all loaded banks instantly.
• Bank selector — choose from all .syx DX7 sysex bank files found in webdx7-master/dist/dx7/presets/.
• Patch selector — 32 patches per bank; select to load immediately.

Adding custom banks: Drop any Yamaha DX7 .syx sysex file (32-voice format, 4104 bytes) into webdx7-master/dist/dx7/presets/ and reload the app. The bank appears automatically.

The DX7 synth is polyphonic and supports velocity sensitivity. It outputs to the same master audio bus as the GM synth, so Mixer and FX chain settings apply to its output.

🎚 Mixer

Open with Mixer button or F9. Shows one channel strip per track plus a master strip on the right.

Automation: Draw automation curves into the ABC with %%MIDI automation lines. During playback the automation values smoothly override the static fader/knob positions. Automation is written per-beat and interpolated.

🔧 FX Chain

Open with the FX toolbar button. A master effects rack that processes the combined output of all tracks. Built on the Tuna.js audio effect library. Effects run in the listed order (signal chain top-to-bottom).

Each effect has its own enable toggle. Disabled effects pass signal through unchanged with no CPU cost. Drag effect rows to reorder the chain.

🤖 AI Assistant

Open with the AI toolbar button. Sends your ABC text and a prompt to a GitHub Models AI API endpoint and applies the response back into the editor.

Capabilities:

• Generate a new song from a text description ("Write a melancholic waltz in D minor at 80 BPM").
• Add instrumentation to an existing melody ("Add a bass line and drum track").
• Transform a section ("Vary bars 5–8 with passing tones").
• Explain or annotate the current score ("What chords does this use?").
• Fix notation errors ("Correct any bar-length mismatches").

Model selector: Choose from available GitHub Models including GPT-4o, GPT-4o-mini, Llama 3, Mistral, Phi-4, and others. More capable models produce better musical output but may be slower.

API key: Requires a GitHub Personal Access Token with the models:inference scope. Paste it into the API key field in the AI panel. The key is stored in localStorage and never leaves your machine except in the API request.

Tips for better results:

• Include the desired key, tempo, and style in your prompt.
• Ask the model to keep your existing headers and voice structure when transforming.
• Use the Undo shortcut (Ctrl Z) to revert an AI change you don't like.

⬇ Audio Export

Click ⬇ Audio in the piano roll header to export the current song as a WebM/Opus audio file. The format is supported by all modern browsers and media players.

How it works:

1. Playback starts from the beginning of the song.
2. Audio is captured directly from the master audio output bus using a MediaStreamDestination node — no microphone or screen-capture required.
3. Recording stops automatically 1.5 seconds after the song ends (to capture reverb tails).
4. The file is named after the song's T: title field and downloaded automatically.

Notes:

• The Integrated Synth must be loaded before exporting.
• The export captures exactly what you hear — all active mixer settings, FX chain, and mute/solo states are reflected.
• Click ⏹ Cancel to abort mid-recording (no file will be saved).
• Do not interact with the app during export for best results.

🌀 3D Visualizer

Toggle with Viz toolbar button or F10. Opens a full-screen 3D animated display that shows notes flying toward the camera and a 3D piano keyboard that lights up in real time during playback.

• Camera orbit: Left-drag to rotate the scene. Right-drag to pan. Scroll to zoom.
• Playable keyboard: Click the 3D piano keys to play notes through the active synth, even while playback is stopped.
• Note colours match the track colours in the piano roll.
• Performance note: the visualizer uses WebGL. On low-end hardware consider reducing the window size or closing other GPU-heavy applications.

⏺ Recorder

Toggle with F8 or the toolbar button. Records from your microphone and converts pitched audio into MIDI note events on the active track using real-time pitch detection.

• Grant microphone permission when the browser asks.
• Best results come from monophonic sources (singing, whistle, single-note instruments).
• Detected notes appear in the piano roll in real time and are also written to the ABC editor.
• Set the active track before recording — notes are added to whichever track is selected.
• Quantisation: recorded notes are snapped to the current grid snap value.

💾 File Operations

The title bar shows the filename and a • dot when there are unsaved changes. Closing the window with unsaved changes will prompt you to save.

🔌 MIDI Output

If your system has MIDI output ports (virtual or hardware), use the MIDI Port selector in the toolbar to route playback to an external synthesizer, DAW, or device. When a port is selected, MIDI note-on/off, program-change, and CC messages are sent in real time during playback.

• Connect a DAW (e.g. Ableton, FL Studio) via a virtual MIDI cable (loopMIDI on Windows) to use ABC Music Maker as a sequencer.
• Internal audio (SpessaSynth / DX7) continues to play unless you mute the master or lower volume.
• MIDI output and audio export are independent — you can export audio while also sending MIDI.

💡 Tips & Advanced Workflows

• Multi-instrument arrangements: Add one track per instrument. Assign unique MIDI channels (1–9, 11–16) and GM programs. Keep channel 10 for drums.
• Quick transposition: Select all notes on a track (Ctrl A) then use ↑/↓ for semitones or Shift ↑/↓ for octaves.
• Copy a phrase to another track: Select notes (Ctrl C), click the destination track, paste (Ctrl V). Useful for call-and-response or doubling.
• Comment out a section: Select lines in the editor and press Ctrl / to mute them with % — then apply. The notes disappear but remain editable.
• BPM automation: The Q: header can appear multiple times in a file; each occurrence changes tempo at that point. The editor supports multiple Q: lines mid-song.
• Undo history is per-session. It covers piano-roll edits, track mutations, mixer changes, and transport changes. The editor has its own separate undo stack.
• Long songs: Turn off Auto-Apply in the toolbar and only press Apply when ready, to avoid expensive re-parses on every keystroke.
• Previewing drum patterns: Channel 10 note C2 = Bass Drum 1, D2 = Acoustic Snare, E2 = Hand Clap, F#2 = Closed Hi-hat, A2 = Open Hi-hat, B2 = Ride Cymbal.
• Export at a specific mix: Mute tracks you don't want, set the faders, enable FX chain, then click ⬇ Audio to capture exactly that balance.