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.