Song Format

A song is a JSON file with a few settings and one or more parts. Each part is one instrument playing a list of notes, and all the parts play at the same time.

{
  "title": "Twinkle Twinkle Little Star",
  "author": "Traditional",
  "tempo": 4,
  "parts": [
    {
      "instrument": "harp",
      "notes": ["C4", "C4", "G4", "G4", "A4", "A4", "G4:2"]
    }
  ]
}

Fields

Field	Required	What it does
title	No	The name shown in the menu. Without it, the file name is used (my_song for my_song.json).
author	No	Shown under the title in the menu. Songs without an author go last when sorting by author.
tempo	Yes	How many game ticks one step lasts, at least 1. There are 20 ticks in a second.
parts	Yes	The list of parts, at least one.

Each part has:

Field	Required	What it does
instrument	Yes	Which sound to use, see Instruments.
notes	Yes	The list of notes, played one after the other.

Steps and tempo

Time in a song is counted in steps. A note lasts 1 step by default, and tempo says how long a step is:

tempo	One step lasts	Steps per second
1	1 tick (0.05 s)	20
2	2 ticks (0.1 s)	10
4	4 ticks (0.2 s)	5
5	5 ticks (0.25 s)	4
10	10 ticks (0.5 s)	2

A trick to pick it: decide which note value is your shortest one (for example an eighth note) and give it 1 step. Then a quarter note is :2, a half note :4, and so on.

The song ends when its longest part ends.

Writing notes

Every entry of notes is a text with this shape:

<note>[:<steps>]

The note

A note is a name and an octave:

• Names: C, D, E, F, G, A, B, in uppercase.
• Sharps with #: C#, D#, F#, G#, A#.
• Flats with b: Db, Eb, Gb, Ab, Bb.
• The octave is the number after it: C4 is middle C.

Note blocks can only play 2 octaves, so notes go from F#3 to F#5:

F#3 G3 G#3 A3 A#3 B3 C4 C#4 D4 D#4 E4 F4 F#4 G4 G#4 A4 A#4 B4 C5 C#5 D5 D#5 E5 F5 F#5

E#, B#, Cb and Fb are not accepted, write F, C, B and E instead.

You can also write a number from 0 to 24, like the number of clicks on a vanilla note block: 0 is F#3, 12 is F#4 and 24 is F#5.

How long it lasts

Add : and a number of steps after the note. Without it, the note lasts 1 step.

"notes": ["C4", "D4:2", "E4:4"]

C4 lasts 1 step, D4 2 steps and E4 4 steps. The length only moves the next note further, the sound itself is the same short note block sound.

Rests

A - is a rest: nothing plays. It can have a length too.

"notes": ["C4", "-", "E4", "-:3", "G4"]

Chords

Join notes with + to play them at the same time. The length goes at the end.

"notes": ["C4+E4+G4:4", "F4+A4+C5:4"]

Several parts

Add more parts to play several instruments together, or several voices with the same instrument. Each part counts its own steps from the start of the song, so use rests to start a part later.

"parts": [
  { "instrument": "harp", "notes": ["C4", "E4", "G4", "C5"] },
  { "instrument": "bass", "notes": ["C4:4"] }
]

See Examples for complete songs.

Mistakes

If something is wrong in a file, the song is skipped and the reason is written in the log. See Checking your songs.