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
- 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
java -cp beatroot-0.5.7.jar at.ofai.music.beatroot.BeatRoot [ 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:
- 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.
The mouse is used to edit the beat times on the data display as follows:
- 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.
The control panel consists of the following components:
- 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
Please mail any bug reports to Simon Dixon
Links
Simon Dixon, London: updated 23 July 2010