Installing and Running Bodhidharma

See the Installation Instructions section.

Starting a New Project

The first thing you will see when you run the software will be the Configure File Locations dialog box. This dialog box allows you to open projects and set their associated configuration file. We will start a new project for this tutorial based on an existing project. Click on the Load Project button, go into the Projects directory and open the T_9_Untrained_With_Recordings.xml file. This fills the Configure File Locations fields with the configuration files associated with this project. If we wanted to open this project, we would simply click on the OK button. However, we wish to start a new project, so click on the Start New Project button. Go into the Projects directory in the resulting file chooser and save the new project file there as TutorialProject.xml. When asked if you wish to copy over the previous configuration files, answer yes. You have now created a new project called TutorialProject with the same settings as the existing T_9_Untrained_With_Recordings project. To load this new project, click on the OK button of the Configure File Locations dialog box.

Exploring the Main Window

You will now see the main window of the Bodhidharma software. Notice the File and Help menus at the top of the screen. These are explained in the Menu Commands section of this manual. The Set Project Paths command of the File menu would return you to the Configure File Locations dialog box if you chose it.

Also notice the tabs under the menus. These let you access the Taxonomy Panel, Features Panel, Preferences Panel, Recordings Panel and Classification Panel. These are the main work areas of the software.

The Taxonomy Panel is the active tab when you first reach the main window. This contains the taxonomy that is used to train classifiers and that recordings are classified into. You can click on the switch to the left of one of the root categories that you see in order to see its descendant categories. Although this taxonomy can be altered, we will leave it for now.

Press on the Feature Settings tab next. The resulting panel displays all of the features which can be extracted from MIDI recordings and used to perform classifications. Double click on the name of any of the features in order to see a description of it. We will not alter any of these settings for now.

Press on the Preferences tab next. The resulting panel allows you to change the way in which training and classifications are performed and the types of reports which the software produces. For the purposes of this tutorial, we will not want to perform long trainings. For this reason, we will select preferences that cause training to be relatively quick. Under the Training Preferences heading, turn off the Find 1-D Feature Selection and Classify Using Round Robin Ensembles options. Under the Training Termination Preferences heading, set Max Number NN Iterations to 300.

Adding Recordings

Press the Recordings tab next. You will now see the list of loaded recordings. The Leaf Categories and Ancestor Categories columns show the model classifications of each recording. These are used to train and test the performance of the classifiers. If you wish to add some MIDI recordings that you have to these recordings, then copy them to the MIDI_Files directory in the Bodhidharma directory using your usual file utility. Now click on the Add New Recordings button. After a moment or two, a file chooser dialog box will appear that displays all MIDI files not already loaded into the Recordings Panel. Select the files you copied into the folder from this file chooser and click on the Add button.

An Edit Recording Properties dialog box will now appear for each recording that you selected. You may fill in the name and artist fields if you wish. More importantly, however, choose the genre from the combo box next to the Add Category button that most closely matches the recording and press the Add Category button. You may add multiple categories if you wish by doing this repeatedly. There are only a limited number of categories available under this taxonomy, but you may design your own larger taxonomy later or use the 38 leaf category taxonomy provided in some of the other sample projects in the future. When you have added a category for the recording, press on the OK button. Repeat this process until you have entered the data for all of the recordings that you added.

Extracting Features

You will now be returned to the Recordings Panel. The recording or recordings you added should now be at the bottom of the table. The next step is to extract the features from these recordings so that they may be used for training and classification. Click on the Extract Features button. This will only extract features from the recording or recordings that you added, as the features from the other recordings have already been extracted and saved.

After clicking on the Extract Features button, you will see a progress bar dialog appear. It may take a few moments to extract the features. If you get an out of memory error, you must either quit Bodhidharma and start over using a greater amount of memory assigned to the JRE (see the Installation Instructions) or choose a different recording. Once feature extraction has finished, click on the Accept button. You will now be returned to the Recordings Panel.

Training the Classifiers

It is now time to train the classifiers. Click on the Classification tab to bring up the Classification Panel. This is where the classifiers are trained and where classifications are performed. Notice that there is a combo box under the Train button that says Randomly Partitioned Recs. Leave this as it is. This means that, when you press on the Train button, only a subset of the loaded recordings will be used for training. The remaining recordings will be reserved for testing how well the classifiers were trained. Click on the Train button now. This will bring up a multi-level progress bar. Wait until training is complete. This may take a few minutes.

Once training is complete, you will see a report on screen showing how long, in seconds, it took to train each classifier ensemble and each of the classifiers in each ensemble.

Classifying Recordings

You are now ready to see how well the training performed. Results will likely not be spectacular, of course, since such a reduced training configuration was used to reduce training times. Under realistic conditions, a more sophisticated set of training preferences with more neural network epochs would have been chosen in the Preferences Panel.

Note that there is a combo box under the Classify button with the Reserved Recs option selected. Leave this as it is, as we now wish to classify recordings that were reserved for testing during training. Click on the Classify button.

Classification should only take a moment or two. Once classification is complete, you will see a report. This shows the overall performance of the test recording classification over all classified recordings, as well as the individual results for each recording. These results are the combined results for the entire classification system. Reports having to do with training progress, classification success and feature/classifier selection/weighting for individual classifier ensembles and their classifiers can be viewed by using the Report Training Progress, Report Classification Results and Report Selections / Weightings buttons and their associated combo boxes.

Saving Your Work

You can save all of the work that you have done by choosing the Save Project command from the File menu. This will save the new recordings you added and their extracted features, the changes to the preferences you made and the newly trained classifiers to disk. You will be given a file chooser dialog box to specify the name of the file to use for saving the classifiers, as this was not specified in the Configure File Locations dialog box. Type Tutorial_Test_Classifiers.xml as the file name for the classifiers. Saving the classifiers may take a few moments.

End of Tutorial

You have now performed a number of the basic tasks that Bodhidharma is used for. There are, however, many more advanced aspects of the software that have not been covered yet. The remainder of this manual explains the remaining functionality of the software in a reference format. Cory McKay's master's thesis, available at www.music.mcgill.ca/~cmckay, contains the details of how this software works. Please contact him at cory.mckay@mail.mcgill.ca if you have any questions.