Configuration Settings File

Configuration Settings File

EXPLANATION OF THIS SECTION

This section describes the jSymbolic configuration file, which specifies various processing settings, and can be used with the GUI, command line interface and API. Sample valid and invalid configuration file transcripts are also provided.

OVERVIEW OF THE CONFIGURATION SETTINGS FILE

The key advantage of the configuration settings file is that it allows users to preserve feature extraction settings between sessions. It can also be used to keep a record of extraction settings that were used, and can also be transmitted to other researchers for the purpose of complete feature extraction transparency.

The optional jSymbolic configuration settings file is a simple text file that allows the user to specify jSymbolic settings related to:

Which features are to be extracted.
What kinds of output files are to be generated.
Whether windowed feature extraction is to be used and, if so, using what window duration and overlap.
Input file paths of symbolic files from which features are to be extracted.
Output file paths for saving extracted feature values and feature metadata.

The input file paths and output file paths are optional, and may be omitted if desired. However, if one is to be used, then both must be present (only having input paths without output paths is considered invalid, and vice versa).

In fact, the configuration settings file itself is entirely optional. jSymbolic's functionality may be accessed via the GUI, command line interface or API without a configuration file if desired. In such a case, default feature extraction settings will be used, unless otherwise specified by the user (e.g. the user may still certainly enable or disable certain features for extraction without a configuration file using the GUI). However, a configuration file is required if the user wishes to use the command line interface or API with any selection of features other than the default.

USING THE CONFIGURATION SETTINGS FILE

The user may place a configuration settings file anywhere and name it anything he or she chooses (although it must have a .txt extension in order to work). This file can then be loaded into the GUI, either during execution or as a pre-loaded file using command line arguments. The path to a configuration settings file may also be specified using the pure command line interface, and can also be specified functionally using the API.

CREATING AND EDITING A CONFIGURATION SETTINGS FILE

Users may create and edit a configuration settings file using any text editor. However, it is generally more convenient and safer (due to the avoided risk of human error) to simply choose the settings one wishes using the GUI, and then save these settings as a configuration settings file directly from the GUI.

OVERALL BREAKDOWN OF THE CONFIGURATION SETTINGS FILE FORMAT

A jSymbolic configuration settings file is a simple text file with four main sections, as specified below. These sections may be inidcated in any order. It is important to note that it is perfectly valid to omit the Input File section and the Output File section if one wishes to choose input and/or output paths at execution, and simply use the configuration settings file to store extraction settings.

Feature Section
A list of all the jSymbolic features one wishes to extract. The names of implemented features must be reproduced exactly, of course, and can be seen in the GUI feature list, in the feature implementations or in the manual's feature explanations. All features listed in this section will be extracted from all input files from which they can be extracted..
Option Section
This section specifies settings for the following:

window_size: The duration in seconds of analysis windows to break input music into for analysis. This option is only meaningful if windowed selection is enabled via the save_features_for_each_window option below.

window_overlap: This fractional value (which should have a value of 0 (for no overlap) or above and below 1) specifies the amount of overlap between consecutive windows. For example, for a window_size value of 10 and a window_overlap: value of 0.1, the windows will be from 0 sec to 10 sec, 9 sec to 19 sec, etc. This option is only meaningful if windowed selection is enabled via the save_features_for_each_window option below.

save_features_for_each_window: Whether or not to break each input file into analysis windows (of duration window_size and overlap window_overlap) and extract and save features separately for each such window. Must have a value of either "true" or "false".

save_overall_recording_features: Whether or not to save the feature for entire indput files only (i.e. no windowing is used). Must have a value of either "true" or "false"

convert_to_arff: Whether or not to save extracted features in a Weka ARFF file, in addition to saving them as an ACE XML 1.1 Features Values File. Must have a value of either "true" or "false".

convert_to_csv: Whether or not to save extracted features in a CSV text file, in addition to saving them as an ACE XML 1.1 Features Values File. Must have a value of either "true" or "false".

Output File Section
This section specifies the paths to save extracted feature values and feature metadata to. All file paths must be absolute or relative to the directory holding the jSymbolic.jar file. Only file paths for the two ACE XML output files are specified here; if Weka ARFF or CSV files are selected to be saved as well, they will be given the same path and file name as the ACE XML Feature Values File, but with the extension changed automatically. As mentioned above, this section may optionally be omitted from valid configuration files. This section includes the following two settings which should be specified.

feature_values_save_path: The path of the ACE XML Feature Values File to save extracted feature values to.

feature_definitions_save_path: The path of the ACE XML Feature Definitions File to save feature metadata to.

Input File Section
A list of input files to extract features from. All file paths must be absolute or relative to the directory holding the jSymbolic.jar file. These files must currently be either MIDI or MEI files. As mentioned above, this section may optionally be omitted from valid configuration files.

DETAILS OF CONFIGURATION SETTINGS FILE VALIDATION

Each section of the configuration settings file is validated as follows:

<features_to_extract>

Feature names are validated to make sure they match existing implemented jSymbolic feature names. An incorrect feature name will result in a system error and will terminate jSymbolic execution.

Each feature name checked to make sure it is only listed once. Duplicate feature names in the configuration settings file are removed silently.

<jSymbolic_options>

Options must each be of the form optionName=optionValue. An incorrect option format will result in a system error and will terminate jSymbolic execution.

All options names are verified for both existence and correct spelling.

All option values are verified for both existence and correct format.

The following is a list of all option names and values:

window_size=(double)

window_overlap=(double)

save_features_for_each_window=(boolean)

save_overall_recording_features=(boolean)

convert_to_arff=(boolean)

convert_to_csv=(boolean)

If any formatting or spelling is missing or incorrect then a system error will occur and jSymbolic execution will terminate. If any options are missing, then a system error will result and jSymbolic will terminate execution.

The save_features_for_each_window and save_overall_recording_features options cannot both have the same boolean value. If they do, then a system error will occur and jSymbolic will terminate execution.

<output_files>

Output files must be of the form outputFileVariable=outputFileName. An incorrect format will result in a system error and termination of execution.

If a path is specified, then it will be verified that a this is a valid path. An invalid path will result in a system error and termination of execution.

An output file name without a .xml extension will simply silently have .xml added to the end of it.

<input_files>

Only single input files may be specified in the configuration file, not directories.

All paths files are validated for existence before feature extraction begins. Invalid file paths are skipped and a log is printed out to the terminal. System exectution will not be interrupted, however, and features will be extracted and saved for valid files.

NOTES ON USING A CONFIGURATION SETTINGS FILE AND THE COMMAND LINE INTERFACE

If both input and output files are specified as command line arguments, and if a configuration settings file is also specified as a command line argument but does not itself specify input or output files, then jSymbolic will run appropriately. If both or neither the command line arguments and the configuration settings file specify input and output files, then this will result in a system error and jSymbolic will terminate execution.

For example, the following command line and configuration file transcript combination is valid:

java -Xmx3072m -jar jSymbolic.jar -configrun <ConfigurationFilePath> <SymbolicMusicFileInputPath> <AceXmlFeatureValuesOutputPath> <AceXmlFeatureDefinitionsOutputPath>

<features_to_extract>
Acoustic Guitar Prevalence
Duration
Beat Histogram
<jSymbolic_options>
window_size=1.5
window_overlap=0.1
save_features_for_each_window=true
save_overall_recording_features=false
convert_to_arff=false
convert_to_csv=false

TRANSCRIPT OF A SAMPLE VALID CONFIGURATION SETTINGS FILE

<features_to_extract>
Acoustic Guitar Prevalence
Duration
Beat Histogram
<jSymbolic_options>
window_size=1.5
window_overlap=0.1
save_features_for_each_window=true
save_overall_recording_features=false
convert_to_arff=false
convert_to_csv=false
<output_files>
feature_values_save_path=test_value.xml
feature_definitions_save_path=test_definition.xml
<input_files>
./test/jsymbolic/features/resources/Saint-Saens_LeCarnevalDesAnimmaux.mei

TRANSCRIPT OF A SAMPLE INVALID CONFIGURATION SETTINGS FILE

The following is an example of an invalid configuration settings file with several errors. The <features_to_extract> header is mispelled, and so is the Acoustic Guitar Prevalence feature. Also, the window_size option is missing and the feature_value_save_path variable is missing an = sign. Any one of these problems would generate an error.

<features_to_extrac>
Acoustic Guitar Fractio
Duration
Beat Histogram
<input_files>
./invalid.midi
./test/jsymbolic/features/resources/Saint-Saens_LeCarnevalDesAnimmaux.mei
<jSymbolic_options>
window_overlap=0.1
save_features_for_each_window=true
save_overall_recording_features=false
convert_to_arff=false
convert_to_csv=false
<output_files>
feature_values_save_pathtest_value.xml
feature_definitions_save_path=test_definition.xml

-top of page-