EXPLANATION OF THIS SECTION

This section explains how to use the jSymbolic GUI.

RUNNING THE JSYMBOLIC GUI

A file named "jSymbolic.jar" is included in the jSybmolic distribution. jSymbolic can be run simply by double clicking on this file. However, in rare cases running jSymbolic simply by double clicking its icon could result in running out of memory when features are extracted from particularly large and complex files (see the section of the manual on the command line interface), so in such cases it may be safer to instead run jSymbolic from the command line, as shown below.

The jSybmolic GUI can also be run by typing the following at a terminal prompt (after navigating to the directory holding the jSymbolic.jar file):

java -Xmx6g -jar jSymbolic2.jar

Running jSymbolic like this (or double clicking on the jSymbolic.jar file) will cause the GUI to be loaded set up with default settings, as defined by a configuration settings file in the same folder as the jSymbolic2.jar file, and with the file name jSymbolicDefaultConfigs.txt. If no such file exists, or if it is not a valid jSymbolic configuration settings file, then the GUI is loaded with hard-coded default settings.

Users wishing to pre-load the GUI with alternative settings stored in any given configuration settings file they wish may enter the following at a terminal prompt (again, after navigating to the directory holding the jSymbolic.jar file):

java -Xmx6g -jar jSymbolic2.jar -configgui <ConfigurationFilePath>

More information on using jSymbolic's command line interface is available here.

OVERVIEW OF JSYMBOLIC'S GUI

The jSymbolic GUI consists of several component panels, all of which can be seen on Figure 1 below:

• Music File Selector Panel: This panel, on the top left of the jSymbolic GUI shown in Figure 1 below, contains a table listing all symbolic music files from which features are to be extracted. The first column indicates the name of each file, and the second indicates its file path. Double clicking on a given row provides additional metadata about its associated file. Buttons are included for adding or removing files from the table, as well as for sonifying them. The table may be sorted by clicking on either of the column headings.
• Feature Selector Panel: This panel, on the top right of the jSymbolic GUI shown in Figure 1 below, contains a table containing one row for each feature, and whose first column contains check boxes allowing users to select which features to save during feature extraction. This feature table also allows users to view additional metadata about each feature, and still further metadata can be seen for a feature (including its feature dependencies) by double clicking on its row. Buttons are included for auto-selecting all features, no features or just the default features.
• Processing Information Panel: This panel, on the middle left of the jSymbolic GUI shown in Figure 1 below, is a space where processing updates are posted during feature extraction. Summary information is also posted here at startup relating to feature breakdowns, and additional updates are written here relating to configuration files and symbolic music files selected to have features extracted from them.
• Error Reports Panel: This panel, on the middle right of the jSymbolic GUI shown in Figure 1 below, is a space where any problems encountered during feature extraction processing are posted (such problems typically relate to invalid files).
• Configuration File and Windowing Settings Panel: This panel, on the bottom left of the jSymbolic GUI shown in Figure 1 below, allows the user to save and load configuration settings files. The user can also specify settings related to windowed feature extraction.
• Feature Extraction and Saving Settings Panel: This panel, on the bottom right of the jSymbolic GUI shown in Figure 1 below, allows the user to specify the kinds and paths of output files to be generated by jSymbolic when feature extraction is complete, and to initiate feature extraction.

More details on some of these panels are provided in the following sections. There is also a section below on the GUI's menu.

Figure 1: The jSymbolic GUI.

THE MUSIC FILE SELECTOR PANEL

This panel contains a table listing all symbolic music files from which features are to be extracted. The first column indicates the name of each file, and the second indicates its file path. The following buttons are contained on this panel:

• Add Files: Brings up a file chooser dialog box allowing the user to select one or more symbolic music files to add to the table. An error message will be displayed if invalid or nonexistent files are chosen. Files chosen are already on the table will be ignored. A report is written to the Processing Information Panel.
• Add Directory: Brings up a file chooser dialog box that allows the user to choose one (and only one) directory, whose contents are added to the table (the user must click on the "Open" button in order to select a directory, not just double click a directory). Any files that do not have a file extension associated with a compatible symbolic music file are filtered out from consideration. Sub-directories are also explored, recursively. If an entered path corresponds to a directory that does not exist, or that contains an invalid symbolic music file, then an error message dialog box is displayed. Files chosen that are already on the table will be ignored. Prints a report to the Processing Information text area.
• Remove Files: Removes all selected files from the table.
• Consistency Report: Brings up a new window holding a formatted consistency report on those symbolic music files that the user has selected on the table (i.e. the particular ones that are selected, not necessarily all of the ones that appear on the table). This report begins by providing, for each file separately, an intraconsistenccy report that indicates whether the given file has more than one value for a range of quantities (e.g. more than one tempo, more than one meter, etc.). Then, if more than one file has been selected by the user, an interconsistency is provided that indicates, for all files considered as a whole, whether all the files share the same value or set of values for each of the quantities being tested for (e.g. all the files have the same tempo, or the same set of tempos).
• Contents Report: Brings up a new window holding a report on those symbolic music files that the user has selected on the symbolic_music_files_table table (i.e. the particular ones that are selected, not necessarily all of the ones that appear on the table). This report indicates, separately for each file selected by the user, a structured transcription of all the relevant MIDI messages that the given file contains. If a given file is an MEI file rather than a MIDI file, then it is converted to MIDI before the report on it is generated.
• Play Sonification: Plays the selected symbolic music file on the table (MEI files are converted to MIDI).
• Stop Sonification: Stops any currently ongoing playback.

Double clicking on a given row will bring up a dialog box providing additional metadata on the row's associated file. The table may be sorted by clicking on either of the column headings.

THE FEATURE SELECTOR PANEL

This panel contains a table containing one row for each feature. Users may select which of these features they would like to have saved after feature extraction is complete by selecting or deselecting the checkbox for each feature in the first column of the table. The columns of this table are as follows:

• Save: Whether or not to save the value of a feature after feature extraction is complete.
• Feature Name: The unique name of each feature.
• Code: The unique code of each feature. This consists of the feature group letter followed by the numerical identifier within the group.
• Values: The number of dimensions (i.e. independent values) associated with the feature. Any feature with a Values entry greater than 1 is a feature vector rather than a single-value feature.
• MEI-Only: Whether a given feature can only be extracted from MEI files. Such features should only be used if features are exclusively being extracted from MEI files.

This panel also includes the following buttons:

• Select Default Features: Sets the Save checkboxes to match the default features to save hard-coded into jSymbolic.
• Select All Features: Sets the Save checkboxes such that all features are set to be saved.
• Deselect All Features: Sets the Save checkboxes such that no features are set to be saved.

Users may also double click on any row to see metadata for the associated feature, including a brief description of the feature and the names of any other features that it is dependant on for calculation.

More details on each of these features are provided here. A breakdown summary of both the features set to be extracted at startup and of all implemented features is printed to the Processing Information Panel at startup.

Note that some features need other features to first be calculated in order to be extracted themselves. So, even if a given feature is not explicitly selected for saving on this table, it will still be automatically extracted (but not saved) if another feature that is calculated based on it is in fact selected for saving.

CONFIGURATION FILE AND WINDOWING SETTINGS PANEL

This panel allows the user to save and load configuration settings files. The user can also specify settings related to windowed feature extraction. This panel consists of the following components:

• Load New Settings from a Config File Button: Brings up a file chooser dialog box that allows the user to load the contents of a specified jSymbolic configuration settings file into the GUI. Note that all input symbolic music file paths specified in the input config file should ideally exist and be valid. Note also that any settings currently entered on the GUI will be lost.
• Save These Settings to a Config File Button: Brings up a file chooser dialog box that allows the user to select a path to save a configuration settings file holding all the settings currently entered on the GUI. Note that this file must be saved with a .txt extension (it will be given one automatically if one is not specified). Note that, as specified in the configuration settings files part of the manual, ACE XML save paths are only saved in the resultant config file if input symbolic music files have been loaded onto the the music file selector table (config files must contain both of these elements or neither). The default path specified in the file chooser dialog box will be a file in the jSymbolic working directory called jSymbolicDefaultConfigs.txt (jSymbolic looks for such a file at startup, and automatically loads settings from it).
• Extract Features from Entire Files Radio Button: Causes features to only be extracted from symbolic files in their entirety (i.e. without windowing). Selecting this option will grey out the Window Duration and Window Overlap text areas.
• Extract Features from Windows Radio Button: Causes features to be extracted from windows only (i.e. not from files in their entirety). Each window will have a duration equal to the number of seconds specified in the Window Duration Text Area, and the windows will have a factional overlap specified in the Window Overlap Fraction Text Area (a value of 0 indicates no overlap). For example, for a window duration value of 10 and a window overlap fraction value of 0.1, the windows will be from 0 sec to 10 sec, 9 sec to 19 sec, etc.

FEATURE EXTRACTION AND SAVING SETTINGS PANEL

This panel allows the user to specify the kinds and paths of output files to be generated by jSymbolic when feature extraction is complete, and to initiate feature extraction. This panel consists of the following components:

• Set ACE XML Feature Values Save Path Button: Brings up a file chooser dialog box allowing the user to select a path to save extracted feature values to as an ACE XML Feature Values file after feature extraction is complete. This path must have a .xml extension (it will automatically be given one if one is not specified). The selected path will automatically be entered in the text area to the right of this button. Users may enter or change the save path directly in this text box if they prefer, rather than using the button.
• Set ACE XML Feature Definitions Save Path Button: Brings up a file chooser dialog box allowing the user to select a path to save extracted feature definitions to as an ACE XML Feature Definitions file after feature extraction is complete. This path must have a .xml extension (it will automatically be given one if one is not specified). The selected path will be automatically entered in the text area to the right of this button. Users may enter or change the save path directly in this text box if they prefer, rather than using the button.
• Also Save Features in a Weka ARFF File Check Box: Will, if selected, cause features to be saved as a WEKA ARFF file after feature extraction is complete (features will still also be saved as ACE XML Feature Values file as well). The path of this ARFF file will be the same as that entered in the Feature Values File text area above, but the extension will be changed from .xml to .arff.
• Also Save Features in a CSV File Check Box: Will, if selected, cause features to be saved as a CSV text file after feature extraction is complete (features will still also be saved as ACE XML Feature Values File as well). The path of this CSV file will be the same as that entered in the Feature Values file text area, but the extension will be changed from .xml to .csv.
• EXTRACT AND SAVE FEATURES Button: Causes feature extraction to be carried out (and features saved) based on the settings specified on all components of the GUI. The Processing Information Panel and Error Reports Panel text areas will be updated to indicate progress. A beep will sound and a confirmation dialog box will appear when feature extraction is complete (the GUI settings may not be changed while feature extraction is occurring).

OVERVIEW OF JSYMBOLIC'S GUI

The jSymbolic GUI includes a single Information menu, with the following commands:

• About: Displays a small window showing basic information about jSymbolic.
• Help: Brings up a browsable window permitting access to this manual.
• Tutorial: Brings up a browsable window permitting access to the jSymbolic tutorial.

-top of page-