MusicScript language guide
Write a composition as a readable .gms file, then choose the runtime that can play or export it. Desktop, Web Studio and the CLI share the language; their audio capabilities differ.
Complete reference
Read the full language and CLI manual or integrate the canonical library. The quick guide below remains a shorter starting point.
Your first score
Named blocks describe the project, patterns and arrangement. Lists use square brackets; comments start with //. Structure repetition uses the section name followed by xN.
project "First session" { bpm: 120 time: 4/4 }
beat drums {
kick: [X . . . . . . . X . . . . . . .]
snare: [. . . . X . . . . . . . X . . .]
}
melody lead {
instrument: juno106
notes: [D4:2 .:2 F4:4 A4:4 D5:4]
}
section verse { bars: 4 play: [drums lead] }
structure [verse x2]Follow the complete first-beat tutorial or browse the canonical declaration reference.
Read the timing correctly
- A beat row fills one bar according to its expanded step count. Sixteen entries in 4/4 form a sixteenth-note grid. X is a hit, a dot is a rest, and digits set velocity.
- A pitched beat entry such as D1:4 expands into four grid slots. Do not add three extra dots unless you want three additional silent slots.
- Melody and theme lengths are sixteenth notes: D4:4 lasts one quarter note. Omitted note length is two; a bare dot lasts one sixteenth, and .:2 lasts two. A rest does not inherit the previous note’s length.
- Octaves include -1: C-1 is MIDI note 0. Chords and arpeggios have their own properties in a melody block.
- Video positions and lengths are quarter-note units; offset_seconds is measured in source seconds. Video compiles through a separate picture plan.
Validate before rendering
gms validate first-session.gms
gms capabilities --engine native
gms check first-session.gms --engine native --target export
gms play first-session.gms --engine native
gms export first-session.gms --engine native -o first-session.wavValidate checks syntax; check also verifies semantics and selected-engine support. Native is the CLI’s default audio engine. Ordinary Node does not provide browser AudioContext globals, so the CLI’s web engine needs an explicitly compatible host. Unsupported features should be resolved before playback or export.
Source, assets and Studio sessions
Keep samples and rendered vocal assets beneath the project folder and use relative paths. The CLI rejects absolute paths, home aliases and parent traversal. The language also supports sections, themes, mix settings, automation, LFOs and video, with runtime-specific limits.
Composition modules are external .gmsmodule.json templates that expand into editable source; they do not add executable imports or a module keyword. Parsed let and autotune syntax does not imply supported audio output. Studio plugin hosting, MPE, recording takes and surround routing remain session or host features.
Play a score in a live session
In Desktop, load the score, join a Go Meow Server session and select MusicScript under Follow with engine. Use a finite score at one tempo in 4/4. The host supplies the playback tempo; section BPM overrides and infinite melody loops are rejected. The adapter rejects vocal declarations, so prepare vocals as local sample assets.
Re-arm after editing the score. Late joins start on a shared bar boundary and skip earlier note attacks. The server coordinates time; it does not copy source, samples or audio. CLI serve/session/daemon commands use local protocols and are not a network connection to Go Meow Server.