Beats Drum Machine

Usage Instructions

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 my_song.wav).

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

Creating Songs

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 X or . 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.