Installation Instructions

Compatibility Issues

The Bodhidharma software is written in Java, which means that it can theoretically be run on any system that has the Java Runtime Environment (JRE) installed on it. It is recommended that the software be used with Windows XP, however, as it was developed and tested under the Windows XP operating system and the interface’s appearance is optimized for Windows. Although the software will theoretically run under earlier versions of Windows, OS X, Linux, Solaris or any other operating system with the JRE installed on it, users should be advised that the Bodhidharma software has not yet been tested on other platforms, so difficulties may be encountered.

This software was developed with version 1.4.1 of the JDK (Java Development Kit), so it is suggested that the corresponding version or higher of the JRE be installed on the user's computer.

Installing the Java Runtime Environment

If your system already has the JRE installed, you may skip this section. If not, you will need to install it in order to run Bodhidharma. It can be downloaded for free from the web site. The JDK includes the JRE.

When the download is complete, follow the installation instructions that come with it. In particular, be sure to follow the steps needed to make it possible to run the JRE in arbitrary directories. Under Windows XP, this means adding an entry such as C:\j2sdk1.4.1\bin to the system PATH variable.

Installing the Bodhidharma Software

All of the Bodhidharma files are contained in the file. The files contained in this file can be unpacked using WinZip, Stuffit Expander or any other archive expansion utility. The files must be unpacked to the C:\Bodhidharma directory (under windows). Although the software will still work if it is placed in another directory, some of the sample project files will not function properly.

Guide to Bundled Files

After unpacking, the C:\Bodhidharma directory should contain the following items:

Running the Bodhidharma Software

One of the files that is extracted is called Bodhidharma.jar. This is the file that should be run in order to use the Bodhidharma software. You can run it either by double clicking on it or by typing the following line at a command prompt, such as the DOS prompt, in the Bodhidharma directory:

java -jar Bodhidharma.jar

It should be noted that the JRE does not always allocate sufficient memory for Bodhidharma to extract features from long MIDI files or perform lengthy classifications. Running Bodhidharma using the above method could result in an out of memory error if particularly long MIDI recordings are processed.

It is therefore preferable to manually allocate a greater amount of memory. 500 to 700 MB should be more than enough for any realistic situation, but one should be careful to leave at least 300MB unallocated under Windows XP. If you have 512 MB of RAM, you should run the Bodhidharma software as follows at the command prompt:

java -mx300M -jar Bodhidharma.jar

If you have 1 GB or more of RAM, you should run Bodhidharma as follows:

java -mx700M -jar Bodhidharma.jar

Running the Bodhidharma Software Through the Command Line

If you already have Bodhidharma configuration files set up and do not want to use the GUI, then command line arguments may be used to run the software. This approach is only recommended for those with significant experience with Bodhidharma, however.

The command line action options are as follows:

The command line settings are as follows:

Note that if a project file is specified at the command line, then this overrides other specified files (e.g. taxonomy file, feature settings file, etc.).

For example, if one wished to extract features from a training and a testing set of MIDI recordings (given a pre-defined taxonomy, set of features to use and preferences settings), one could type:

and Training could then be performed by typing: And finally, classifications could be printed to standard out by typing:

Using Tab-Deliminted Formats Instead of Bodhidharma Formats

Bodhidharma uses custom XML files to store settings. However, some users may wish to use tab-delimited text files as alternatives to the taxonomy and recording list XML file formats. So, in addition to the XML formats, the following two file formats may be used as alternatives:

For the recording list file, each line denotes a different MIDI file, and each line should consist of:

(example path and filename)\t(leaf genre label)( ... )\n

where the ( and ) characters are not included and \t denotes a tab, \n denotes a new line and ( ... ) denotes the possible inclusion of further \t(leaf genre label)'s to denote membership to multiple genres. If no (leaf genre label), then an automatic classification fo Unknown will be provided.

For the taxonomy file, each line denotes a different leaf genre, and each line should consist of:

(subcategory)\t(parentcategory)\t( ... )\n

where the ( and ) characters are not included and \t denotes a tab, \n denotes a new line and ( ... ) includes further parents (in order from low position in the genre hierarchy to the root).

Note that Bodhidharma automatically determines if a text file or XML file is being used.

Recompiling the Software

Those who wish to edit and recompile the Java code may do so by simply typing:

javac *.java

in the Source_Code directory. The Javadocs may be rebuilt by typing:

javadoc -tag author:a:"Author:" -link -d JavaDocs C:\Bodhidharma\Source_Code\*.java C:\Bodhidharma\Source_Code\bodhidharma\*.java C:\Bodhidharma\Source_Code\bodhidharma\classifiers\*.java C:\Bodhidharma\Source_Code\bodhidharma\classifiers\bio_k_nearest_neighbour\*.java C:\Bodhidharma\Source_Code\bodhidharma\classifiers\feedforward_neural_networks\*.java C:\Bodhidharma\Source_Code\bodhidharma\classifiers\genetic_algorithms\*.java C:\Bodhidharma\Source_Code\bodhidharma\data_structures\*.java C:\Bodhidharma\Source_Code\bodhidharma\midi_parsing\*.java C:\Bodhidharma\Source_Code\bodhidharma\midi_parsing\multi_dimensional_features\*.java C:\Bodhidharma\Source_Code\bodhidharma\midi_parsing\one_dimensional_features\*.java C:\Bodhidharma\Source_Code\bodhidharma\utilities\*.java C:\Bodhidharma\Source_Code\bodhidharma\xml_parsing\*.java

If you have recompiled the software into class files, you can run the software simply by typing:

java Bodhidharma

Although modifications to the system CLASSPATH variable are not necessary if the user is simply using the Bodhidharma.jar file as is, users who recompile the software so that the Bodhidharma class and bodhidharma package are in the C:\Bodhidharma directory will need to add the following entry to the CLASSPATH:


The class files may be repackaged into a jar by typing:

jar cfm0 Bodhidharma.jar MANIFEST.MF Bodhidharma.class bodhidharma

where the MANIFEST.MF file can be taken from the existing Bodhidharma.jar file.

Users who recompile the code and place it in a new jar file must place the jar file in the Bodhidharma directory.

Guide to Sample Projects

The following sample projects are found in the Projects directory. They can be opened from inside Bodhidharma.

Current Limitations