Bodhidharma

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 java.sun.com 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 Bodhidharma.zip 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:

MIDI_Files: A directory holding MIDI files. Will be empty for copyright reasons under the standard Bodhidharma distribution.
ProgramFiles: A directory holding files used by the Bodhidharma software, including the html files for the on-line manual, the Xerces XML file parser and graphics files used by the software.
Projects: Contains several sample projects. See below for more details. Not available in all Bodhidharma distributions.
Source_Code: Contains the Java source code for the Bodhidharma main class as well as the Bodhidharma package. Also includes Javadoc API documentation.
Bodhidharma.jar: The Bodhidharma classes in a jar archive.
default_file_locations.xml: An XML file holding the file path of the default project that is loaded at startup of the Bodhidharma software.
Manual.html: The manual for the Bodhidharma software.
README.txt: Basic installation and running instructions.

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:

-extract features: Extract features from MIDID files.
-tran "path": Train on all currently loaded recordings and save to the given path.
-classify "path": Classify all currently loaded recordings and output results to the given path.

The command line settings are as follows:

-proj "path": Specify the path of a project file to load.
-tax "path": Specify the path of a taxonomy file to load.
-feat "path": Specify the path of a feature settings file to load.
-rec "path": Specify the path of a recordings file to load.
-clas "path": Specify the path of a trained classifiers file to load.
-pref "path": Specify the path of a preferences file to load.
-dir "path": Specify the path of the directory to use as the current directory.

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:

java -mx500M -jar Bodhidharma.jar -tax Projects\Command_Line_Test\SimpleTaxonomy.xml -feat Projects\Command_Line_Test\AllFeatures.xml -pref Projects\Command_Line_Test\CommandLinePreferences.xml -rec Projects\Command_Line_Test\CommandLineTestingRecordings.xml -extract features and

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 http://java.sun.com/j2se/1.4/docs/api -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:

C:\Bodhidharma\Source_Code;C:\Bodhidharma\Source_Code\bodhidharma;C:\Bodhidharma\ProgramFiles\xerces.jar;

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.

T_9_No_Recordings.xml: A basic nine leaf category taxonomy with no MIDI recordings or classifiers loaded yet.
T_9_Trained_With_Recorings.xml: A basic nine leaf category with trained classifiers and the 225 recordings that were used to train them. The recordings may be used even if the MIDI files are not included with this distribution, as the features have been extracted from the MIDI files and saved. The user may load his or her own recordings and classify them into the nine leaf category taxonomy using the trained classifiers.
T_9_Untrained_With_Recordings: A basic nine leaf category 225 recordings divided between them. The recordings may be used even if the MIDI files are not included with this distribution, as the features have been extracted from the MIDI files and saved. The user may experiment with training and testing classifiers using these recordings.
T_38_No_Recordings.xml: A thirty-eight leaf category taxonomy with no MIDI recordings or classifiers loaded yet.
T_38_Trained_With_Recorings.xml: A thirty-eight leaf category with trained classifiers and the 950 recordings that were used to train them. The recordings may be used even if the MIDI files are not included with this distribution, as the features have been extracted from the MIDI files and saved. The user may load his or her own recordings and classify them into the nine leaf category taxonomy using the trained classifiers.
T_38_Untrained_With_Recordings: A thirty-eight leaf category 950 recordings divided between them. The recordings may be used even if the MIDI files are not included with this distribution, as the features have been extracted from the MIDI files and saved. The user may experiment with training and testing classifiers using these recordings.

Current Limitations

All MIDI files must be placed in the same directory if recording lists are be saved in XML format. This limitation does not hold true if the tab-delimited format is used.
No taxonomy may have a leaf class at the root level.