YYMMdd 20050731


beatrix is based on the philosophy of representing and manipulating music as text. beatrix borrows heavily from emacs' philosophy. beyond the basic text foundation, commands and keyboard bindings, it has parallel notions of buffers and windows (called patterns and browsers). it separates itself from emacs by rendering using scalable vector graphics and using configurable browsers that afford beauty, flexibility, and power.


start beatrix from a shell or by double clicking on it. you can put it into full screen mode using the keystrokes "C-x f" (aka 'Ctrl-x' followed by 'f'). when you first start up beatrix you are in pattern playing mode and are presented with a single browser containing pattern A. within the beatrix window, you will see three major regions: the browser region at the top, the message/input region on the bottom left, and the mode/state region on the bottom right:

within the browser region, beats are organized horizontally into tracks which are in turn organized vertically into patterns. in other words, tracks are horizontal sequences of beats, and patterns are vertical collections of tracks. tracks in a pattern are played simultaneously and synchronously while beats in a track are played sequentially at the given tempo. tracks are meant to represent what a single drum can produce and are targetted towards drums such as djembe's that can produce multiple tones but only one particular tone at any given time.

beatrix represents rhythms as text and as such beatrix can be thought of as a text editor for beats. you can add beats by simply typing characters. each character represents a particular kind of sound, called a tone. the association between characters and tones is called a mapping. beatrix starts out with an african mapping where for instance B, T, and S represent the bass, tone, slap sounds of a djembe. try typing 'T' with some spaces interspersed within. feel free to use the delete key to erase characters:

beatrix uses key strokes and chords (aka key bindings) for most of its commands heavily borrowing from emacs key bindings. the keyboard notation used is M-c for Alt-c, C-c for Ctrl-c, S-c for Shift-c etc. the full key bindings and their bound commands are shown after typing M-0 and are arranged based on command categories:

the keyboard notation is shown at the bottom right of the page.

beatrix browsers have a circular ring of ten pages. each time you ask for another page, for instance when you show the key/command documentation using M-0, beatrix uses the next available page. the previous page is accessible using the backspace key and the next page is available using M-backspace. just like web browsers, you can follow a line of inquiry down a path and then pop back up to earlier pages. unlike, web browsers, beatrix has a finite ring of ten pages.

you can navigate within a pattern moving up, down, left, right with C-p, C-n, C-b, C-f (for previous, next, backwards, and forwards), to the beginning and end of a track with C-a and C-e, and to the beginning and end of a pattern with M-a and M-e. alternatively, you can use the arrow, Home and End keys to navigate. in general, C- (Ctrl) key chords designate beats (and tracks), while M- (Alt) chords designate tracks and patterns.

you can add a track above the current track with C-o or below with C-j. you can kill tracks with C-k and clear a track with C-d. specific beats can be moved left and right with C-x C-b and C-x C-f and specific tracks can be moved up and down with C-x C-p and C-x C-n. you can copy and paste tracks by moving to the source track and typing C-w and then moving to the destination track and typing C-y. finally, tracks can be muted with C-m. pattern editing can be undone with C-z and redone with M-z.

beatrix is implemented with a custom scalable vector font, called the 3x3 font, allowing characters to easily change size, thickness, and rotation. the alphabet is shown using M-7 and M-8 keys for lower and upper case respectively:

before we get too far, you can quit beatrix with C-x C-c. feel free to quit at any point. beatrix is not for everyone! if you instead just want to abort the current command type C-g.


the current pattern can be saved by typing C-x C-s followed by the filename, and a pattern file can be loaded into the current pattern by typing C-x C-v followed by the filename. patterns that are loaded from or saved to files are said to be associated with a file. once pattern files are associated, then C-x C-s will save to that associated file, and C-x C-w will be needed to save to a new filename. pattern files are written out as files ending in ".rtm" and containing one line per track and one character per beat, where dashes are used to represent silent beats. optional comments can be added at the end of each track following a '#' character. for example, the following is a simple pattern with a clave and djundjun track:

C---C---C---C--- # clave
D--D--D-----D--- # bass line

the base pathname for patterns is "../rhythms/". a few example patterns are provided in that directory such as "kuku.rtm" and "dansah.rtm". try loading "kuku.rtm" with C-x C-v kuku:


when entering filenames in the input region (as well as entering other strings), filenames can be completed by hitting the tab key. if there is only one matching filename then it will be filled in, otherwise a completion page will pop up in the current browser with filenames matching the given filename prefix, and the filename input will be completed to the first point of ambiguity. filenames can be chosen in the completion page by moving the cursor using the navigation keys (C-n, C-p, C-f, C-n, etc) and hitting return.

directories (including the parent directory "..") can be browsed by hitting return on a directory name resulting in the contents of the directory being placed in the file browser. hitting tab before any filename characters are typed produces an unconstrained file browser:

alternatively, more characters can be typed to the input region and completion can be requested again. finally, once you are happy with your filename, hit return.

particular commands can be executed by name using M-x name. as in filename completion, command names can be tab completed and selected with navigation.


property forms are used to control aspects of the music. property forms are displayed when C-i is typed followed by an aspect specific character. for example, the global property form can be generated by typing C-i g:

where n-beats and n-tracks are the default pattern dimensions. properties can be adjusted by navigating to the property of interest and either adjusting or editing the value. in order to adjust the value use '-' to decrement and '=' to increment. numbers are adjusted by a property specific amount (e.g., 0.1 for volume and 10 for tempo) and multiple choice properties cycle through possible values (e.g., true and false):

for more complete editing of the value hit return and type in a fresh value in the input region:

invalid input values are indicated with a yellow prompt line, otherwise the property value will be updated with the entered value.

the beat, track, and pattern forms describe the current object of interest defined by where the pink cursor resides. the read-only coordinates of the object are shown at the top in gray. pattern properties can be browsed by typing C-i p:

a track property form can be generated with C-i t:

where channel controls the output to which the track sounds go. for example, with a standard stereo configuration, channel 0 is left and channel 1 is right.

beat properties can be browsed by typing C-i b:

command properties can be browsed by typing C-i c:

where sub properties (in this case commands) are indicated in red. hitting return on sub properties creates another property form with their name / values, in this case the properties of the track-inverse command:

command properties include command documentation and categories. as before, hitting backspace at any time returns you to the previous property page. a category based view of the commands can be browsed by typing C-i i:

where digging down produces the members of a particular category:

finally, C-i k allows you to get key documentation by typing a key sequence. C-i a (for apropos) returns all commands containing a given string.


mappings are associations between characters and sounds. you can manipulate these mappings in an info page generated by typing C-i m:

hit return on a particular letter and then you will be able to edit the letter or wave file pathname:

for sound files, the base sound file pathname is "../samples/". currently only wave files are supported. a number of samples are provided in samples subdirectories.

you can also change the current mapping by loading/replacing or adding a mapping file (using mapping-load or mapping-add). a mapping can also be saved to a file using mapping-save. the mapping file format is a sequence of "c: filename"'s, one per line, where c is a character and filename is a pathname to a sound file. for example, a simple mapping file is:

C: african/C.WAV
A: african/A.WAV
B: african/B.WAV

where key C maps to the african/C.WAV sound file etc. the base mapping pathname is "../mappings/". two builtin mappings are provided: "" and "". try changing the mapping by typing M-x mapping-load rock.


beatrix provides multiple track page styles: horizontal and circular tracks. within a pattern page, the page can be changed between bar and radar styles with keys 1 and 2:

beatrix provides multiple beat page styles: letters shown above and rectangles shown below:

the beat rendering substyle can be changed between rectangles and letters with S-1 and S-2, respectively. each time the page style is changed, the page is pushed. previous pages can be retrieved using backspace.

beatrix provides 26 beat patterns, one song, and one clipboard pattern. you can select the pattern the browser is showing by using C-x p followed by the pattern letter. patterns are named A-Z with special song and clipboard patterns named 0 and *. the clipboard is the destination of copies and the source of pastes. in each pattern page, the pattern letter is shown in the lower right hand corner.

beatrix supports multiple browsers, with a maximum of one per pattern. initially beatrix presents one browser with additional browsers being automatically laid out into a square tiling. you can adjust the number of browsers by hitting M-LF and M-RT for incrementing and decrementing the one:

you can add another browser above or below the current one by hitting M-o or M-j. you can kill the current browser by hitting M-k. you can switch between browsers with TAB and C-TAB and with the navigation keys M-f, M-b, M-p, M-n, M-S-a, M-S-e for moving the focus right, left, up, down, top left, and bottom right respectively. the pink cursor will highlight the active browser. the browser number is shown in the upper right hand corner. you can organize browsers by moving them with C-x M-f, C-x M-b, C-x M-p, and C-x M-n for moving browsers right, left, up, and down. finally, you can flip between single browser and multiple browsers layouts with C-x z for zoom in and out.

multiple browsers give you much power and flexibility. you can edit one pattern while another pattern is soloing:

and then you can solo the newly edited one and switch. you can also view the same pattern with two different styles:

finally you can use another browser for showing the command documentation using M-0 or you can browse an info page on one and a pattern page on the other:


beatrix can also be used to sequence patterns using a song. the song is in pattern 0. currently, it only has one track. out of the box, the song consists of one pattern, A. you can switch to the song pattern by typing C-x p 0:

you can add to that using C-RT to add space a single pattern letter, and then by typing the pattern name, say B:

pattern names use the same letters as beats.

in order to better work with songs it is useful to simultaneously see the patterns and song. first switch browser 0 back to pattern A by typing C-x p a. you can show four browsers with patterns A, B, 0, and 1 by incrementing the number of browsers up to four using M-RT three times. out of the box this is how the browsers are mapped. you enter song mode by typing C-x g which sequences between the patterns specified in the song track. if you make the song be AB, then you will see beatrix loop between pattern A and B as follows:


This is a very early release of BEATRIX and as such it has a good list of things to do and known issues. Here are a few that you will probably run into:


good luck. have patience. ask questions to jrb at