BeatRoot Version 0.5.7 User Documentation

Disclaimer: This document is work in progress. It has not been fully checked for consistency with the current version, and doesn't cover all of the functionality of the system.

BeatRoot is a musical beat tracking and visualisation system. The original description of the beat tracking algorithms appears in the paper:
Automatic Extraction of Tempo and Beat from Expressive Performances, Journal of New Music Research, 30 (1), 39-58, 2001.
An update on BeatRoot and report on several evaluations of the systems is found in the paper:
Evaluation of the Audio Beat Tracking System BeatRoot, Journal of New Music Research, 36 (1), 39-50, 2007.
The graphical user interface is described in the paper:
An Interactive Beat Tracking and Visualisation System, 2001 International Computer Music Conference (ICMC2001, pp 215-218).
The file you are reading now is the user documentation for BeatRoot. The software and the papers mentioned above are available for download here.

Of course, the software is supplied as is, with no claims to any functionality or fitness for any purpose. Nevertheless, I hope you find it useful.

BeatRoot Installation Instructions

• System requirements: Java Run-time Environment (at least version 1.5).
• No (other) installation is necessary.
• Download the file beatroot-0.5.7.jar, or, if you want to use the source code, beatroot-0.5.7-src.jar
• The source code is provided free under the GNU Public License (see the file gpl.txt).
• It is not neccesary to unpack the archive in order to run the program.
• If you want to unpack the jar archive, you can use the jar command line utility:
  jar xf beatroot-0.5.7.jar
• The program can be run from the command line with:
  java -jar beatroot-0.5.7.jar

BeatRoot Usage

Command Line Options

BeatRoot may be run in GUI (graphical user interface) or batch mode. The graphical mode is the default if no options are given. In graphical mode, parameter settings are adjusted with the Preferences menu item in the Edit Menu. The command line options are described in the online documentation at:
http://www.elec.qmul.ac.uk/people/simond/beatroot/doc/at/music/beatroot/BeatRoot.html#processArgs(java.lang.String[]) . Other parameters and preferences can only be adjusted by modifying the source code.

File formats

Text output

BeatRoot Graphical User Interface Overview

You might want to start by reading the ICMC paper to get an overview of the system. The user interface of the current version is quite similar.

Click on Load Audio Data and select an audio file. You should see the file in spectrogram and amplitude envelope displays when the system has finished processing the file (it will probably take about 10% of the duration of the audio). Click on Track Beats to perform beat tracking. You should then see the beats marked on the display with black vertical lines. You can listen to the beats and audio with the three different play buttons: Play with beats plays the audio with clicks at the times of each beat; Play without beats plays the original audio file, and Play beats only plays the beats without the audio.

Errors can be corrected using the mouse: the left button moves beats, the middle button adds new beats and the right button deletes beats.

Detailed description of GUI components and controls

• Time line: at the bottom of the data display is a time axis, showing the time in seconds from the beginning of the input data.
• Amplitude envelope: the amplitude envelope is shown in purple, calculated from an RMS average of a 20ms window of audio data, with 50% overlap between successive windows (default parameter settings).
• Onset times: short green vertical lines mark detected note onset times.
• Spectrogram: a spectrogram of the audio data is shown above the amplitude envelope in various shades of yellow, orange, red, white and black. If it looks too white or too black, set the lower and upper thresholds under Preferences in the Edit Menu.
• Beat times: black vertical lines mark the times of beats, as computed by BeatRoot or edited by the user.
• Inter-beat intervals: the times between pairs of beats are shown (in milliseconds) at the top of the data display. The default resolution is 5 milliseconds per pixel, although the onset detection algorithm only has a resolution of 10ms by default.

• Use the left mouse button to move beats by clicking on a beat line and dragging it to the desired location.
• Use the middle mouse button to add a new beat at the cursor location.
• Use the right mouse button to delete a beat at the cursor location.
• By clicking with the left mouse button on the time axis, you can select a region of the music. A single click will select from the current point to the end of the file. The selected region is highlighted in grey-pink in the area above the time line. A region bounded at both ends can be selected by clicking at one end and dragging to the other end. The selected region can be cleared by clicking the right mouse button on the time axis.

• Options: this field is current not used. Any options must be specified on the command line or via the Preferences in the Edit menu
• View Range: this is the number of seconds of data that are visible on the screen. It is possible to zoom in or out using the + and - buttons respectively, or by entering a value in the text field between the two buttons.
• Load Audio Data button: load a new audio file. A window will appear which allows you to select the data file. This will clear any currently loaded audio data. For large data files, you will have to wait a few seconds while the data is processed.
• Clear beats button: delete the beats in the highlighted region, or delete all beats if no region is selected.
• Load Beat Data button: load a file of beat times (assumed to be one you previously saved using BeatRoot). The format is a text version of the MIDI format (compatible with the program t2mf), containing a drum track marking the beats.
• Track beats button: performs beat tracking on the highlighted region, or on the whole file if no region is selected. If a region is selected, the tempo and phase of beats before the selected region will be used as the basis for further beats. If you plan to edit the file and re-track sections of it, it is best if manual editing is performed in chronological order, i.e. from the beginning to the end of the file.
• Undo button: restores the previous list of beats after the most recent change.
• Redo button: undoes the undo.
• Save Beat Data button: saves the beat times in text MIDI format.
• Play without beats button: plays the input audio data.
• Play beats only button: plays the beat times with a percussion instrument.
• Play with beats button: plays the input data with a percussion instrument sounding at each beat time. The percussion instrument can be selected with Edit Percussion Sounds in the Edit menu.
• Stop button: stop the playback.
• Exit button: end the program.

Bugs

Links

• Simon Dixon's home page
• Centre for Digital Music home page
• OFAI Intelligent Music Processing Group