Beats runs from the command-line. The syntax:
beats [options] INPUT [OUTPUT]
INPUT is the YAML file for your song.
OUTPUT is the
*.wav file where Beats will place the generated sound. If omitted, it will default to
INPUT but with a
.wav extension. (For example, the sound for
my_song.txt would be saved to
beats example_song.txt beat.wav
Beats supports the following command-line options, which can be used together or separately:
-s, --split Save each track to a separate Wave file, instead of combining them into one. -p, --pattern PATTERN_NAME Only generate the pattern PATTERN_NAME, instead of the entire song. --path BASE_PATH Look for song files with relative paths relative to BASE_PATH, instead of relative to the song file's path. -v, --version Displays the Beats version number, and exits. -h, --help Displays a list of possible command-line options, and exits. beats -s example_song.txt beats -p Verse example_song.txt beats --path ~/drum_sounds example_song.txt
Songs are notated using YAML, so each song file is just a plain text file you can edit in TextEdit, VIM, or whatever. The file extension doesn’t matter.
Each song is divided into one or more patterns. A pattern represents a section of the song, such as a verse, chorus, or bridge. Each pattern in turn has one or more tracks. Each track represents an individual sound, such as a bass drum, snare, or hi-hat.
Songs should start with a header indicating the tempo, the flow of the song, and aliases for commonly used sounds. Here’s an example below. Since this is YAML, lines must be indented correctly. Also, each row in the Flow or Kit should be preceded by a dash.
Song: Tempo: 120 Flow: - Verse: x4 - Chorus: x2 - Bridge: x1 - Verse: x4 - Chorus: x2 Kit: - bass: sounds/808bass.wav - hh_closed: sounds/hihat_awesome.wav - hh_open: sounds/hh_open.wav
The Kit section is optional, but the Flow is required.
One or more patterns should follow the header. (If there are no patterns, there is nothing to play!) Each pattern definition starts with the pattern name, followed by the rhythm for each track on separate lines.
Verse: - bass: X.......X....... - sounds/snare.wav: ....X.......X... - hh_closed: X.X.X.X.X.X.X... - hh_open: ..............X. - sounds/ride.wav: X...............
Each track line starts with the *.wav sound file to use. You can either use a sound defined in the Kit section of the header, or alternately use a specific file name. (The example above mixes and matches). File paths can be relative or absolute; relative paths are relative from the path of the song file, unless the
--path command line option is given. Track lines must be indented properly and start with a dash (once again, due to this being YAML).
The track rhythm follows the sound name. An
X means that the sound should be triggered, and a
. indicates a “rest” between triggers. Each
. represents a 16th note. You only need to indicate the downbeat of each sound, since sounds will play their full duration (unless cut off by another trigger). For example, to play a quarter note rhythm,
X...X...X...X... will do the trick.
You can also use
| as a bar line, or the
SPACE character to mark measures or sections. These are optional, but can make patterns easier to read. Beats ignores these, and you can put them wherever you want in the pattern (except as the first character) – they don’t have to line up with a measure or anything like that.
As a final note, patterns and the song header can come in any order. If you want to put the song header at the end of the file, you can. You can also mix up the order that patterns are defined.
© 2010-2020 Joel Strait