| Using the API |
|---|
EXPLANATION OF THIS SECTION
This section describes how jSymbolic's functionality may be accesed programmatically using its API.
OVERVIEW OF JSYMBOLIC'S API
jSymbolic's API (Application Programming Interface) allows programmers to carry out jSymbolic feature extractions directly from their own code, without needing to resort to using jSymbolic's via its command line interface (which, of course, is also an option). This can be done by calling certain public methods in the jSymbolic classes, as specified below, which have been specifically designed for this purpose. jSymbolic's API can be accessed by other Java code, or using other platforms that include functionality for accessing Java APIs, such as Matlab.
USING JSYMBOLIC'S API
In order to use jSymbolic's API, a programmer need simply place the jSymbolic2.jar file and its associated lib folder in the same directory, and then point their own code to it (and potentially add the directory to their JVM CLASSPATH environment variable). It should be noted that Java 8 or higher should be used, as jSymbolic does use some functionality that was only implemented beginning starting in this version of Java.
It is recommended that programmers download the development version of jSymbolic rather than the user version. Although the API is accessible from either distribution, the developer version has the substantial advantage of providing Javadoc documentation, as well as the well-commented jSymbolic source code itself.
Potential users of the API are encouraged to first read the section of this manual on the command line interface, as this will familiarize them with how jSymbolic processing works in general. They may also wish to read the section of this manual on jSymbolic's configruation settings file format, if they wish to use this type of file in their processing (it is optional).
In order to use the API, users should look at the Javadoc documentation or source code for the jsymbolic2.api.JsymbolicProcessor class. There is also additional API code in the jsymbolic2.api.deprecated package, but this has been deprecated, and it is not suggested for use by new users (it does, however, have the advantage of providing direct programmatic access to org.ddmal.jmei2midi.meielements.meispecific.MeiSpecificStorage information for those who may wish it, which the current jSymbolic API does not).
The first thing to do is to instantiate a JsymbolicProcessor object using one of the provided constructors, at which point the user in effect supplies the extraction settings to use with all feature extractions that will be carried out by the new object. Which constructor is used depends on whether one wishes to provide extraction settings directly as arguments or using a configruation settings file, and on whether one wishes to manually specify features to be extracted or simply wishes to extract the default features. Feature extraction can then be carried by calling one of this object's extractAndSaveFeatures . . . methods, depending on how one wishes to specify the files to extract features from. Whichever method is used, extracted freatures and feature definitions will be saved in files, as specified to the JsymbolicProcessor constructor.
Once feature extraction is complete, programmers can then either use their own code to access the saved feature files directly (one of the reasons why features can be saved as CSV or ARFF files if desired), or they can use JsymbolicProcessor's getExtractedFeatureValues or getCompleteExtractedFeatureInformation methods to automatically parse the saved feature values and metadata and access them via jMIR ACE objects.
As a side note, the JsymbolicProcessor class also includes public static methods that can be used separately in order to generate reports on symbolic music files.
ADDITIONAL DETAILS ON JSYMBOLIC'S API
The constructor requires that the following be specified as arguments: whether to save features separately for analysis windows, whether to rather save features for music files as a whole, the analysis window size (if any), the analysis window overlap (if any), a list of feature names to extract (optional, see below), the save path for the ACE XML Feature Values file to be generated, the save path for the ACE XML Feature Definitions file to be generated, whether to save extraced features in ARFF and/or CSV files as well as ACE XML files, and PrintStream objects to write status and error reports to. There is one variant of this constructor that specifies the features to be extracted manually, and another that simply causes the default features to be extracted. Either windowed or overall features should be set to be extracted, but not both. If only overall file feature extraction is specified, then any specified window size and window overlap will have no effect on the processing. Each specified feature name must be a valid jSymbolic feature name, otherwise an exception will be thrown during instantiation.
The specified configuration settings file must exist and must contain all required information and be properly formatted. It is important to note that any input files specified in the configuration settings file will simply be ignored (during instantiation) if the jSymbolic API is being used. PrintStream objects to write status and error reports to must also be provided to this constructor.
There are two versions of this method: one will only extract features from a single specified file (or the contents of a single specified directory), and the other will extract features from a list of specified files and/or directories. Either way, extraction is carried out on the specified file(s) and directory contents using the extraction settings specified at instantiation, and results are saved at the specified file paths.
This method parses the files and/or directories to extract features from from a configuration settings file. Note that extraction is carried out on the specified file(s) using the extraction settings specified at instantiation, not using any contrasting settings specified in the configuration file, and results are saved at the file paths specified during instantiation.
Using the JsymbolicProcessor.getCompleteExtractedFeatureInformation method to programmatically access features and associated metadata that have already been extracted
This method parses the ACE XML feature value and feature definition files that were generacted using one of the above extractAndSaveFeatures methods and returns the information in the form of an ace.datatypes.DataBoard object. Note that this method should only be called after features have been successfully extracted and saved as an ACE XML feature values file at the path specified when the constructor of this object was called. The returned DataBoard object holds the extracted feature values as well as associated feature definitions. See the jMIR ACE project's documentation for more details.
Using the JsymbolicProcessor.getExtractedFeatureValues method to programmatically access features that have already been extracted
This method parses the ACE XML feature value and feature definition files that were generacted using one of the above extractAndSaveFeatures methods and returns the information in the form of an array of ace.datatypes.DataSet objects. Note that this method should only be called after features have been successfully extracted and saved as an ACE XML feature values file at the path specified when the constructor of this object was called. The returned array of array of DataSet objects holds the extracted feature values. Each DataSet object corresponds to a different piece of music from which features were extracted. If windowed extraction was performed, then each DataSet object in the returned array will also hold its own array of DataSet objects, one for each extracted window. Feature values are contained in the feature_values field of each DataSet object (both single and multi-dimensional features), feature names are contained in the feature_names field, and an identifier for each instance is stored in the identifier field. See the jMIR ACE project's documentation for more details.
SAMPLE USAGE CODE
The following simple code demonstrates one of the several ways in which might might use the jSymbolic API to extract and access features: jSymbolicApiDemo.java.
To compile this sample code, make sure that Java is runnable in your current directory. Then copy the jSymbolic2.jar file and its associated lib folder to this directory, as well as the jSymbolicApiDemo.java file. Also create a subdirectory here called MySymbolicMusicFiles, and put one or more valid MIDI or MEI file in it (such as this one and this one). The code can then be compiled by typing at a terminal prompt:
javac -classpath "./jSymbolic2.jar;" jSymbolicApiDemo.java
The code can then be run by typing at a terminal prompty:
java -classpath "./jSymbolic2.jar;" jSymbolicApiDemo
This will cause the following files to be generated: an ACE XML feature definitions file, an ACE XML feature values file, a CSV file holding feature values and a Weka ARFF file holding feature values. These particular files were generated using the two MIDI files generated above. The feature values will also be printed to standard out, as shown in this processing transcript.