BeatRoot Version 0.5.7 User Documentation

Simon Dixon
Centre for Digital Music,
School of Electronic Engineering and Computer Science,
Queen Mary, University of London.

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

BeatRoot Usage

Command Line Options

java -cp beatroot-0.5.7.jar [ 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:
doc/at/ofai/music/beatroot/BeatRoot.html#processArgs(java.lang.String[]) . Other parameters and preferences can only be adjusted by modifying the source code.

File formats

The range of accepted audio file types are those accepted by the JavaSound implementation, including any installed extension libraries. In any case, standard WAV format files, 1 or 2 channel 16-bit linear PCM encoded, at any sampling rate, are accepted. If BeatRoot doesn't accept your file format, convert it with a utility like sox.

Text output

BeatRoot can output the beat times in text format (see the "-o" command line option), or in text-MIDI format (the format produced by the program mf2t which is available here. If using the debugging output, each line contains the beat number, the inter-beat interval in parentheses, the beat time (in square brackets if there was no event on the beat), and finally the remaining event times (if any) up to (but not including) the next beat.

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

The graphical user interface consists of a data panel with a menu bar above it, and a scroll bar and button panel below it. The data display consists of the following components: The mouse is used to edit the beat times on the data display as follows: The control panel consists of the following components:


Please mail any bug reports to Simon Dixon


Simon Dixon, London: updated 23 July 2010