← QMK song player

QMK song syntax

Here is ODE_TO_JOY, which comes predefined in QMK:

#define ODE_TO_JOY Q__NOTE(_E4), Q__NOTE(_E4), Q__NOTE(_F4), \
  Q__NOTE(_G4), Q__NOTE(_G4), Q__NOTE(_F4), Q__NOTE(_E4),    \
  Q__NOTE(_D4), Q__NOTE(_C4), Q__NOTE(_C4), Q__NOTE(_D4),    \
  Q__NOTE(_E4), QD_NOTE(_E4), E__NOTE(_D4), H__NOTE(_D4)

You can find more predefined songs in quantum/audio/song_list.h.

A song is a comma-separated sequence of notes. Each note has a pitch frequency and a duration, represented using C preprocessor macros. For example, Q__NOTE(_E4) is a quarter note on the E key, 4th octave.

Note pitch is one of the twelve semitones _C, _CS, _D, _DS, _E, _F, _FS, _G, _GS, _A, _AS, _B followed by an octave 0 through 8, such as _CS3 for C♯, 3rd octave. Flats can be written similarly with F, for instance, _DF3 is the same as _CS3. Specially, _REST in place of the pitch creates a rest.

Note duration (quarter note, whole note, etc.) is represented with the following:

Macro Duration
B__NOTE 2 beats, breve note
W__NOTE 1 beat, whole note
H__NOTE 1/2 beat, half note
Q__NOTE 1/4 beat, quarter note
E__NOTE 1/8 beat, eighth note
S__NOTE 1/16 beat, sixteenth note
T__NOTE 1/32 beat, thirty-second note

Dotted notes are written with a D as QD_NOTE for a 3/8 beat note, and similarly for other durations. For full flexibility, a note of any duration may be defined with the syntax M__NOTE(pitch, duration), where pitch is a pitch and duration is a number in units of 1/64ths of a beat. For instance M__NOTE(_C4, 64) is longhand for W__NOTE(_C4).

Under the hood, song data is stored as a float[][2] array, using pair of floats per note. The first float stores the pitch frequency in Hz and the second stores the duration in units of 1/64ths of a beat.