Language Reference

A BeatBax song is a sequence of top-level statements: chip and tempo, instruments, named patterns and sequences, channel wiring, then play. This reference documents the grammar as implemented by @beatbax/engine — not planned or retired design notes.

For a narrative walkthrough that builds one Game Boy song, start with the Tutorial.

Boxes are clickable topics. Rounded pills are statement keywords; square boxes are related syntax groups.

Program / Statement

chip|bpm|volume|stepsPerBar|scale|song|play|import|inst|subpat|effect|pat|seq|channel|export

Pattern RHS

notes|rests|groups|inst(…)|effects|modifiers

Sequence RHS

pat refs|*N|groups|:modifiers

Channel RHS

inst|pat / seq|speed=|lock=

Pattern atom

NoteToken|RestToken|DurationSuffix|EffectSuffix|TempInst

Statement map

Topic	Covers
Global directives	chip, bpm, volume, stepsPerBar, scale, song, play, comments
Notes	Pitches, durations, rests, sustains
Patterns	pat / shorthand, groups, inline inst, effect suffixes
Sequences	seq, refs, repeats, groups
Channels	channel N => …, speed=, lock=
Instruments	inst, macros, note mapping, subpat, imports
Modifiers	Colon-chained sequence/pattern transforms
Effects	Named effect presets and inline <…>
Export	Deprecated in-file export format "path"
Appendix	Statement index, reserved words, lexical notes

Typical song shape

song name "Example"
chip gameboy
bpm 120

inst lead type=pulse1 duty=50 env=gb:12,down,1
pat phrase = C5 E5 G5 C6
seq lead_seq = phrase*2

channel 1 => inst lead seq lead_seq
play

Order is flexible in the parser, but most songs follow metadata → instruments → patterns/sequences → channels → play.