EXPLANATION OF THIS SECTION

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

OVERVIEW OF JSONGMINER'S COMMAND LINE ARGUMENTS

A file named "jSongMiner.jar" is produced upon installation. jSongMiner is used by running this file using command line arguments specifying what kind of processing is to be performed.

All of the command line arguments accepted by jSongMiner consist of flag/value pairs, where the flag comes first and is preceded with a "-". The one exception to this is that a lone flag of "-help" will print a list of valid flags with explanations of what they are. Invalid command line arguments will also result in the printing out of a list of valid flags with explanations of what they are.

Most of the jSongMiner command line flags are used to choose the piece of music which is to be identified and labeled with metadata, and to specify how this information is to be output. In addition, a few of the flags provide access to jSongMiner's utility functions, which is to say that they allow the jSongMiner software to be used to perform basic functions distinct from its central function of identifying songs and extracting metadata associated with them. These utility flags may not be used in combination with any other flags, as they provide functionality that is neither directly related to jSongMiner's core functionality, nor to the functionality offered by other utility flags.

jSongMiner's operation is also governed by its configuration settings file. However, command line arguments can in some cases override these configuration file settings, as described in the configuration settings file section of the manual.

COMMAND LINE FLAGS FOR ACCESSING JSONGMINER'S CORE FUNCTIONALITY

The following is a list of the flags that may be used to access jSongMiner's core functionality of identifying songs and extracting associated metadata:

• -audio: The path of an audio file to identify and extract metadata for, if available.
• -title: The suspected title of the song to extract metadata for, if known.
• -artist: The suspected name of the artist associated with the song to extract metadata for, if known.
• -album: The suspected title of the album most associated with the song to extract metadata for, if known.
• -savedir: The directory to save extracted metadata in. This overrides any and all output directories specified in the configuration file, and applies to both text and ACE XML output. Only a directory should be specified, as file names will be auto-generated based on content. May not be used in conjunction with any of the -savefile, -saveacexmlfile or -savetxtfile flags.
• -savefile: The file path to save extracted metadata to. This overrides configuration settings relating to output directories, and sets the package_song_artist_album configuration setting to true so that song, artist and album metadata are combined into one file. If the value specified here has a .xml extension, then the output will be saved as ACE XML. If it has a .txt extension, then the output will be saved as text. May not be used in conjunction with any of the -savedir, -saveacexmlfile or -savetxtfile flags.
• -saveacexmlfile: The file path of the ACE XML file to save extracted metadata to. This overrides configuration settings relating to output directories, sets the save_output_as_ace_xml configuration setting to true, and sets the package_song_artist_album setting to true so that song, artist and album metadata are combined into one file. This flag may be used either alone or in conjunction with the -savetxtfile flag.
• -savetxtfile: The file path of the text file to save extracted metadata to. This overrides configuration settings relating to output directories, sets the save_output_as_txt configuration setting to true, and sets the package_song_artist_album setting to true so that song, artist and album metadata are combined into one file. This flag may be used either alone or in conjunction with the -saveacexmlfile flag.
• -eraselogs: Erases the logs of previously extracted artists and/or albums, if any. This does not alter the reextract_known_artist_metadata or reextract_known_album_metadata configuration settings, but it does erase any existing logs before the new processing begins. The value following this flag must be "artist", "album" or "all", and specifies which log(s) are erased.

COMMAND LINE FLAGS FOR ACCESSING JSONGMINER'S UTILITY FUNCTIONS

• -urldecode: URL decodes the text following this flag and prints the results to standard out. Uses UTF-8 decoding. This is a terminal utility function, so no other processing is performed other than this, and this flag cannot be used in combination with any other flags.
• -acexmltotxt: Converts the ACE XML 1.1 Classifications file whose path is specified after this flag into the type of text produced by jSongMiner, which is to say field names are printed to odd lines and field values are printed to the following even lines. This is output to standard out. URL decoding is not performed. This is a terminal utility function, so no other processing is performed other than this, and this flag cannot be used in combination with any other flags.
• -acexmltotxtud: Converts the ACE XML 1.1 Classifications file whose path is specified after this flag into the type of text produced by jSongMiner, which is to say field names are printed to odd lines and field values are printed to the following even lines. This is output to standard out. URL decoding is performed (UTF-8). This is a terminal utility function, so no other processing is performed other than this, and this flag cannot be used in combination with any other flags.
• -help: Will print to standard out a list of valid flags with explanations of what they are.

USAGE CONSTRAINTS

There are certain limitations on which command line flags may be used in combination:

• The -urldecode, -acexmltotxt and -acexmltotxtud terminal utility flags may not be used in combination with any other flags.
• The command line arguments must contain one or both of the -audio or -title flags, unless terminal utility flags are being used.
• If the -savedir flag is used in the command line arguments, then none of the -savefile, -saveacexmlfile or -savetxtfile flags flags may be used.
• If the -savefileflag is used in the command line arguments, then none of the -savedir, -saveacexmlfile or -savetxtfile flags flags may be used.
• The file path following the -savefile command line switch must have an extension of either ".txt" or ".xml".
• The value following the -eraselogs command line switch must have a value of "artist", "album" or "all".

USAGE EXAMPLES

Examples are provided below showing sample ways in which jSongMiner can be run from the command line. Note that, as is standard practice, flag values containing spaces are enclosed in quotation marks. Note also that the "-mx500M" Java Virtual Machine option is also used in these examples to reserve 500 MB of memory for the virtual machine to operate. Although this is not strictly necessary for jSongMiner processing, it is a good idea in general to ensure that the VM does not run out of memory.

There are three sets of examples (A, B and C) specified below. The first two sets involve using jSongMiner to identify and/or extract metadata for a song. In the first set, no output sink is specified, so the output is saved in the default save directories, as set by the songs_save_directory, artists_save_directory and/or albums_save_directory configuration settings. File names are auto-generated based on the results of metadata extraction. In the second set, output sink(s) are specified manually. jSongMiner utility functionality is demonstrated in the third set of examples.

Example A-1) Identify and extract metadata for the audio file unknown.mp3 found in the current directory:

java -mx500M -jar jSongMiner.jar -audio ./unknown.mp3

Example A-2) Extract metadata for the audio file unknown.mp3 found in the current directory, with the assumption that it is the song "Wandering Star" by Portishead from the album "Dummy". This approach should only be used if it can be assumed that this information comes from a reliable source, otherwise the approach shown in Example A-1 should be used:

java -mx500M -jar jSongMiner.jar -audio ./unknown.mp3 -title "Wandering Star" -artist Portishead -album Dummy

Example A-3) Extract metadata for the song "Freedom" by Charles Mingus from the album "Mingus Mingus Mingus Mingus Mingus", even though access to an audio recording is unavailable:

java -mx500M -jar jSongMiner.jar -title Freedom -artist "Charles Mingus" -album "Mingus Mingus Mingus Mingus Mingus"

Example A-4) Extract metadata for the song "Dr. Greenthumb", even though an audio recording is unavailable and one does not know the artist or album title. Note that this approach can be problematic, as there can be ambiguity between multiple versions of the song with the same title:

java -mx500M -jar jSongMiner.jar -title "Dr. Greenthumb"

Example A-5) Extract metadata for the song "Les Bourgeois" by Jacques Brel. Because the "-eraselogs artist" option is used, logs of those artists for whom metadata has already been extracted will be erased before processing begins, thus forcing reextraction of artist metadata for this and other songs processed in the future that are associated with artists for whom metadata has already been extracted:

java -mx500M -jar jSongMiner.jar -title "Les Bourgeois" -artist "Jacques Brel" -eraselogs artist

As noted above, it is possible to override the output settings specified in the configuration file so that the output is saved in a way that is specified at the command line. This is demonstrated in the examples below. The -audio flag, as demonstrated in Example A-1 above, is used in these examples, although in practice one could use any of the approaches demonstrated above to specify the song to be processed.

Example B-1) Identify and extract metadata for the audio file unknown.mp3, and save the song, artist and/or album metadata in the current directory using file names that are auto-generated based on the metadata extracted:

java -mx500M -jar jSongMiner.jar -audio ./unknown.mp3 -savedir ./

Example B-2) Identify and extract metadata for the audio file unknown.mp3, and save the song, artist and/or album metadata in a single ACE XML file called unknown_out.xml in the current directory. Note that the output file would be in text format if a .txt extension were specified instead of a .xml extension:

java -mx500M -jar jSongMiner.jar -audio ./unknown.mp3 -savefile ./unknown_out.xml

Example B-3) Identify and extract metadata for the audio file unknown.mp3, and save the song, artist and/or album metadata first as a single ACE XML file called unknown_out.xml, and then as a single text file called "unknown_out.txt", both in the current directory:

java -mx500M -jar jSongMiner.jar -audio ./unknown.mp3 -saveacexmlfile ./unknown_out.xml -savetxtfile ./unknown_out.txt

As noted above, jSongMiner may also be run using utility flags that provide types of functionality separate from the main jSongMiner song identification and metadata extraction functionality. Examples of such usage are provided below:

Example C-1) Decode the "metal+%28Count%3A+63%29+%28Last.FM+Tag+URL%3A+http%3A%2F%2Fwww.last.fm%2Ftag%2Fmetal%29" string of URL-encoded text and print the results to standard out. This is useful for manually interpreting URL-encoded text output by jSongMiner:

java -jar jSongMiner.jar -urldecode metal+%28Count%3A+63%29+%28Last.FM+Tag+URL%3A+http%3A%2F%2Fwww.last.fm%2Ftag%2Fmetal%29

Example C-2) Convert the unknown_out.xml ACE XML 1.1 Classifications file in the current directory into return-delimited text that is printed to standard out. URL-encoding is preserved:

java -jar jSongMiner.jar -acexmltotxt ./unknown_out.xml

Example C-3) Convert the unknown_out.xml ACE XML 1.1 Classifications file in the current directory into a URL-decoded return-delimited text that is printed to standard out:

java -jar jSongMiner.jar -acexmltotxtud ./unknown_out.xml

-top of page-