Song Format

Songs are JSON files. One file contains everything — instruments, patterns, arrangement, and metadata.

Example Song

json +

{
  "title": "My Song",
  "tempo": 122,
  "rows_per_beat": 4,
  "order": [0, 0, 1, 1, 2, 3],
  "instruments": {
    "stab": {
      "waveform": "pulse",
      "duty_cycle": 0.25,
      "attack": 0.001,
      "decay": 0.04,
      "sustain": 0.0,
      "release": 0.03,
      "volume": 0.13
    }
  },
  "patterns": {
    "0": [
      [{ "channel": 0, "note": "C-1", "instrument": "kick" }],
      [],
      [{ "channel": 2, "note": "C-5", "instrument": "hat" }],
      []
    ]
  }
}

Top-Level Fields

Field	Description
title	Song name (display only)
tempo	BPM (beats per minute)
rows_per_beat	Rows per beat. 4 = 16th note resolution
order	Pattern play sequence, loops when finished
instruments	Named instrument definitions
patterns	Numbered patterns, each a list of rows

Pattern Events

Each row is a list of events (or empty [] for silence):

json +

{ "channel": 0, "note": "C-5", "instrument": "lead", "volume": 0.8 }

Field	Description
channel	Voice channel (0-7)
note	Single `"C-5"`, chord `["C-4","E-4","G-4"]`, or `"---"` for note off
instrument	Instrument name
volume	Optional, 0.0-1.0

Note Format

C-5 — C in octave 5
C#4 — C sharp in octave 4
--- — note off (releases all voices on channel)

Timing

text +

seconds_per_row = 60 / tempo / rows_per_beat

| Tempo | Rows/beat | Row duration |
|-------|-----------|-------------|
|   120 |         4 |       125ms |
|   122 |         4 |       123ms |
|   140 |         4 |       107ms |

Start Composing

Getting Started Provider Reference