Using the Command Line Interface

EXPLANATION OF THIS SECTION

This section of the manual explains all of the command line arguments that may be used with jSymbolic and provides usage examples.

RUNNING JSYMBOLIC GRAPHICALLY

The simplest way of using jSymbolic is to simply run the jSymbolic GUI by double clicking the jSymbolic2.jar file's icon on a graphical disk interface, such as Windows or OS X. However, a greater range of options are made available by running jSymbolic through a terminal interface using command line arguments, as described below. Also, running jSymbolic simply by double clicking its icon could, in rare cases, result in running out of memory in the case of particularly large and complex files (see below), so in such cases it may be safer to run jSymbolic from the command line.

ACCESSING JSYMBOLIC VIA A TERMINAL INTERFACE

One way of using jSymbolic is via a terminal prompt, such as a Windows DOS command prompt, or a terminal prompt on OS X, Linux, UNIX, etc. Although such a command line approach can be less intuitive for some initially relative to using the jSymbolic GUI, it can also sometimes be faster and easier. If you are unsure how to access a terminal prompt on your computer, please consult instructions for your particular operating system on-line for details on how to access and use it.

Once you have accessed a terminal prompt, navigate to the jSymbolic folder and locate the file named "jSymbolic2.jar", which is included in the jSymbolic distribution. A folder called "lib" should also be present in the same folder (it contains other .jar files jSymbolic needs to run properly). You must run this "jSymbolic2.jar" file (using the Java Runtime Environment), as shown below, in order to access jSymbolic's functionality. The particular command line arguments that you use when running jSymbolic in this way will determine exactly what jSymbolic does.

COMMAND LINE ARGUMENTS THAT INCLUDE ONE OR MORE SPACES

Note that any command line arguments you use that contain a space (such as file paths) must be fully enclosed in quotation marks, otherwise jSymbolic will not work properly. This is standard Java practice. So, for example, if one were using jSymbolic with a configuration file (see below) called "My Config File.txt", then this would NOT work:

java -Xmx6g -jar jSymbolic2.jar -configrun My Config File.txt

Instead, correct usage would be:

java -Xmx6g -jar jSymbolic2.jar -configrun "My Config File.txt"

RUNNING JSYMBOLIC WITH A SUFFICIENTLY HIGH MEMORY CEILING

By its nature, the Java Virtual Machine is always assigned a maximum amount of memory at runtime. If a specific maximum is not assigned manually at runtime, then this will be the smaller of 1/4 the computer's physical memory or 1 GB. jSymbolic's processing can sometimes require quite a bit of memory, so it is best to manually specify a large maximum when running jSymbolic just to be safe. This can be done by using the "-Xmx" flag when running Java, as shown in the examples below.

It is suggested that a maximum of six gigabytes be used, which is why "-Xmx6g" is specified below. Of course, the vast majority of processing jobs will require much, much less than this amount of memory, but it is suggested that a high maximum such as this be assigned if possible, as jSymbolic will quit processing (with an explanatory error message) if the maximum assigned memory is exceeded while processing a particularly large or complex piece of music. In the very unlikely event that an out-of-memory error does occur, jSymbolic should be rerun with a larger maximum specified.

Users are advised not to assign a greater amount of memory greater than the amount of physical memory that they have on their systems, however, as virtual memory processing can be quite slow.

RUNNING JSYMBOLIC FROM A TERMINAL INTERFACE

The simplest way to run jSymbolic from a terminal prompt is to type the following at your terminal prompt (after you have navigated to the directory containing the jSymbolic2.jar file): 
java -Xmx6g -jar jSymbolic2.jar

This will run the jSymbolic GUI set up with default settings.

One must add jSymbolic command line arguments if one wishes to instigate jSymbolic processing directly from the command line. Some of these command line arguments consist of flag/value pairs, where the flag comes first and is preceded with a "-". Essentially, the flag indicates the type of option, and the value indicates its particular setting.

Other command line arguments simply consist of values, with no flags, of flags with no values. For example, a lone flag of "-help" will print to the terminal a list of valid flags with explanations of what they are. This can be run as follows:

java -jar jSymbolic2.jar -help

Invalid command line arguments will also result in the list of legitimate command line arguments being printed out to the terminal.

Important General Notes:

SPEEDING UP PROCESSING BY EXTRACTING FEATURES IN PARALLEL WITH MULTIPLE INSTANCES

Although it is not yet possible to run jSymbolic feature extraction using multiple internal threads to speed up processing, if processing speed is a concern then multiple instances of jSymbolic may be spawned from separate terminal windows, and each such jSymbolic instance may be run in parallel without danger to extract features from separate portions of a large dataset. This is rarely necessary in practice, however, since jSymbolic is generally quite fast when even just a single instance is used.

JSYMBOLIC'S COMMAND LINE ARGUMENTS (WITH NO NON-DEFAULT CONFIGURATION FILE SPECIFIED)

JSYMBOLIC'S COMMAND LINE ARGUMENTS (WITH A NON-DEFAULT CONFIGURATION FILE SPECIFIED)

The following command line arguments can be used together with a jSymbolic configuration settings file:

USAGE EXAMPLES

These examples demonstrate a few sample ways that jSymbolic can be run from the command line. These examples all make use of the command line flags and values explained above.

Example 1: Run the jSymbolic GUI under default settings.

java -Xmx6g -jar jSymbolic2.jar

Example 2: Extract features from a single music file called "test.mid" in the current directory, and output the results to "feature_values_1.xml", "feature_values_1.csv" and "feature_descriptions_1.xml", to be created in the current directory.

java -Xmx6g -jar jSymbolic2.jar -csv ./test.mid ./feature_values_1.xml ./feature_descriptions_1.xml

Example 3: Extract features from all symbolic feature files in the directory called "test" (and its recursively searched sub-directories) with recognized extentions, and output the results to "feature_values_1.xml", "feature_values_1.csv" and "feature_descriptions_1.xml" files, to be created in the current directory.

java -Xmx6g -jar jSymbolic2.jar -csv ./test/ ./feature_values_1.xml ./feature_descriptions_1.xml

Example 4: Extract features from all symbolic feature files in the directory called "test" (and its recursively searched sub-directories) with recognized extensions, and output the results to "feature_values_1.xml" and "feature_descriptions_1.xml" files, to be created in the current directory. A window size of 10 seconds will be used with an overlap fraction of 0.1 (i.e. 1 second, in this case).

java -Xmx6g -jar jSymbolic2.jar -window ./test/ ./feature_values_1.xml ./feature_descriptions_1.xml 10 0.1

Example 5: Extract features from a single music file called "test.mid" in the current directory, and output the results to "feature_values_1.xml" and "feature_descriptions_1.xml", to be created in the current directory. Also output the extracted feature values in the form of a CSV file and an ARFF file, saved in the current directory as as "feature_values_1.csv" and "feature_values_1.arff", respectively.

java -Xmx6g -jar jSymbolic2.jar -arff -csv ./test.mid ./feature_values_1.xml ./feature_descriptions_1.xml

Example 6: Extract features from all symbolic feature files in the directory called "test" (and its recursively searched sub-directories) with recognized extensions, and output the results to "feature_values_1.xml" and "feature_descriptions_1.xml" files, to be created in the current directory. The feature extraction is done using the configuration settings specified in the configuration file called "jsymbolic_configurations.txt" found in the current directory (and which should not itself specify input and output file paths).

java -Xmx6g -jar jSymbolic2.jar -configrun ./jsymbolic_configurations.txt ./test/ ./feature_values_1.xml ./feature_descriptions_1.xml

Example 7: Extract features from all symbolic files referred to in the configurations file called "jsymbolic_configurations.txt", using the output paths and settings specified in this configuration file.

java -Xmx6g -jar jSymbolic2.jar -configrun ./jsymbolic_configurations.txt

Example 8: Run the jSymbolic GUI pre-loaded with the settings (including, optionally, input and output paths) specified in the configuration file called "jsymbolic_configurations.txt" in the current directory.

java -Xmx6g -jar jSymbolic2.jar -configgui ./jsymbolic_configuration.txt

Example 9: Display detailed intraconsistency and interconsistency reports on all MIDI and MEI files with recognized extentions that are found in the "TestingFolder" directory (and its recursively searched sub-directories).

java -Xmx6g -jar jSymbolic2.jar -consistencycheck ./TestingFolder

Example 10: Display a detailed report on the MIDI file called "test.mid" in the current directory, including a breakdown of the MIDI messages it contains.

java -Xmx6g -jar jSymbolic2.jar -mididump ./test.mid

-top of page-