yading@11: yading@11: Sonic Annotator yading@11: =============== yading@11: yading@11: Sonic Annotator is a utility program for batch feature extraction from yading@11: audio files. It runs Vamp audio analysis plugins on audio files, and yading@11: can write the result features in a selection of formats. yading@11: yading@11: For more information, see yading@11: yading@11: http://www.omras2.org/SonicAnnotator yading@11: yading@11: More documentation follows further down this README file, after the yading@11: credits. yading@11: yading@11: yading@11: Credits yading@11: ------- yading@11: yading@11: Sonic Annotator was developed at the Centre for Digital Music, yading@11: Queen Mary, University of London. yading@11: yading@11: http://www.elec.qmul.ac.uk/digitalmusic/ yading@11: yading@11: The main program is by Mark Levy, Chris Cannam, and Chris Sutton. yading@11: Sonic Annotator incorporates library code from the Sonic Visualiser yading@11: application by Chris Cannam. Code copyright 2005-2007 Chris Cannam, yading@11: copyright 2006-2011 Queen Mary, University of London, except where yading@11: indicated in the individual source files. yading@11: yading@11: This work was funded by the Engineering and Physical Sciences Research yading@11: Council through the OMRAS2 project EP/E017614/1. yading@11: yading@11: Sonic Annotator is free software; you can redistribute it and/or yading@11: modify it under the terms of the GNU General Public License as yading@11: published by the Free Software Foundation; either version 2 of the yading@11: License, or (at your option) any later version. See the file COPYING yading@11: included with this distribution for more information. yading@11: yading@11: Sonic Annotator may also make use of the following libraries: yading@11: yading@11: * Qt4 -- Copyright Nokia Corporation, distributed under the GPL yading@11: * Ogg decoder -- Copyright CSIRO Australia, BSD license yading@11: * MAD mp3 decoder -- Copyright Underbit Technologies Inc, GPL yading@11: * libsamplerate -- Copyright Erik de Castro Lopo, GPL yading@11: * libsndfile -- Copyright Erik de Castro Lopo, LGPL yading@11: * FFTW3 -- Copyright Matteo Frigo and MIT, GPL yading@11: * Vamp plugin SDK -- Copyright Chris Cannam, BSD license yading@11: * Redland RDF libraries -- Copyright Dave Beckett and the University of Bristol, LGPL/Apache license yading@11: yading@11: (Some distributions of Sonic Annotator may have one or more of these yading@11: libraries statically linked.) Many thanks to their authors. yading@11: yading@11: Sonic Annotator can also use QuickTime for audio file import on OS/X. yading@11: For licensing reasons, you may not distribute binaries of Sonic yading@11: Annotator with QuickTime support included for any platform that does yading@11: not include QuickTime as part of the platform itself (see section 3 of yading@11: version 2 of the GNU General Public License). yading@11: yading@11: yading@11: Compiling Sonic Annotator yading@11: -------------------------- yading@11: yading@11: If you are planning to compile Sonic Annotator from source code, yading@11: please read the file INSTALL. yading@11: yading@11: yading@11: A Quick Tutorial yading@11: ================ yading@11: yading@11: To use Sonic Annotator, you need to tell it three things: what audio yading@11: files to extract features from; what features to extract; and how and yading@11: where to write the results. You can also optionally tell it to yading@11: summarise the features. yading@11: yading@11: yading@11: 1. What audio files to extract features from yading@11: yading@11: Sonic Annotator accepts a list of audio files on the command line. yading@11: Any argument that is not understood as a supported command-line option yading@11: will be taken to be the name of an audio file. Any number of files yading@11: may be listed. yading@11: yading@11: Several common audio file formats are supported, including MP3, Ogg, yading@11: and a number of PCM formats such as WAV and AIFF. AAC is supported on yading@11: OS/X only, and only if not DRM protected. WMA is not supported. yading@11: yading@11: File paths do not have to be local; you can also provide remote HTTP yading@11: or FTP URLs for Sonic Annotator to retrieve. yading@11: yading@11: Sonic Annotator also accepts the names of playlist files (.m3u yading@11: extension) and will process every file found in the playlist. yading@11: yading@11: Finally, you can provide a local directory path instead of a file, yading@11: together with the -r (recursive) option, for Sonic Annotator to yading@11: process every audio file found in that directory or any of its yading@11: subdirectories. yading@11: yading@11: yading@11: 2. What features to extract yading@11: yading@11: Sonic Annotator applies "transforms" to its input audio files, where a yading@11: transform (in this terminology) consists of a Vamp plugin together yading@11: with a certain set of parameters and a specified execution context: yading@11: step and block size, sample rate, etc. yading@11: yading@11: (See http://www.vamp-plugins.org/ for more information about Vamp yading@11: plugins.) yading@11: yading@11: To use a particular transform, specify its filename on the command yading@11: line with the -t option. yading@11: yading@11: Transforms are usually described in RDF, following the transform part yading@11: of the Vamp plugin ontology (http://purl.org/ontology/vamp/). A yading@11: Transform may use any Vamp plugin that is currently installed and yading@11: available on the system. You can obtain a list of available plugin yading@11: outputs by running Sonic Annotator with the -l option, and you can yading@11: obtain a skeleton transform description for one of these plugins with yading@11: the -s option. yading@11: yading@11: For example, if the example plugins from the Vamp plugin SDK are yading@11: available and no other plugins are installed, you might have an yading@11: exchange like this: yading@11: yading@11: $ sonic-annotator -l yading@11: vamp:vamp-example-plugins:amplitudefollower:amplitude yading@11: vamp:vamp-example-plugins:fixedtempo:acf yading@11: vamp:vamp-example-plugins:fixedtempo:detectionfunction yading@11: vamp:vamp-example-plugins:fixedtempo:filtered_acf yading@11: vamp:vamp-example-plugins:fixedtempo:tempo yading@11: vamp:vamp-example-plugins:fixedtempo:candidates yading@11: vamp:vamp-example-plugins:percussiononsets:detectionfunction yading@11: vamp:vamp-example-plugins:percussiononsets:onsets yading@11: vamp:vamp-example-plugins:powerspectrum:powerspectrum yading@11: vamp:vamp-example-plugins:spectralcentroid:linearcentroid yading@11: vamp:vamp-example-plugins:spectralcentroid:logcentroid yading@11: vamp:vamp-example-plugins:zerocrossing:counts yading@11: vamp:vamp-example-plugins:zerocrossing:zerocrossings yading@11: $ sonic-annotator -s vamp:vamp-example-plugins:fixedtempo:tempo yading@11: @prefix xsd: . yading@11: @prefix vamp: . yading@11: @prefix : <#> . yading@11: yading@11: :transform a vamp:Transform ; yading@11: vamp:plugin ; yading@11: vamp:step_size "64"^^xsd:int ; yading@11: vamp:block_size "256"^^xsd:int ; yading@11: vamp:parameter_binding [ yading@11: vamp:parameter [ vamp:identifier "maxbpm" ] ; yading@11: vamp:value "190"^^xsd:float ; yading@11: ] ; yading@11: vamp:parameter_binding [ yading@11: vamp:parameter [ vamp:identifier "maxdflen" ] ; yading@11: vamp:value "10"^^xsd:float ; yading@11: ] ; yading@11: vamp:parameter_binding [ yading@11: vamp:parameter [ vamp:identifier "minbpm" ] ; yading@11: vamp:value "50"^^xsd:float ; yading@11: ] ; yading@11: vamp:output . yading@11: $ yading@11: yading@11: The output of -s is an RDF/Turtle document describing the default yading@11: settings for the Tempo output of the Fixed Tempo Estimator plugin in yading@11: the Vamp plugin SDK. yading@11: yading@11: (The exact format of the RDF printed may differ -- e.g. if the yading@11: plugin's RDF description is not installed and so its "home" URI is not yading@11: known -- but the result should be functionally equivalent to this.) yading@11: yading@11: You could run this transform by saving the RDF to a file and yading@11: specifying that file with -t: yading@11: yading@11: $ sonic-annotator -s vamp:vamp-example-plugins:fixedtempo:tempo > test.n3 yading@11: $ sonic-annotator -t test.n3 audio.wav -w csv --csv-stdout yading@11: (... logging output on stderr, then ...) yading@11: "audio.wav",0.002902494,5.196916099,68.7916,"68.8 bpm" yading@11: $ yading@11: yading@11: The single line of output above consists of the audio file name, the yading@11: timestamp and duration for a single feature, the value of that feature yading@11: (the estimated tempo of the given region of time from that file, in yading@11: bpm -- the plugin in question performs a single tempo estimation and yading@11: nothing else) and the feature's label. yading@11: yading@11: A quicker way to achieve the above is to use the -d (default) option yading@11: to tell Sonic Annotator to use directly the default configuration for yading@11: a named transform: yading@11: yading@11: $ sonic-annotator -d vamp:vamp-example-plugins:fixedtempo:tempo audio.wav -w csv --csv-stdout yading@11: (... some log output on stderr, then ...) yading@11: "audio.wav",0.002902494,5.196916099,68.7916,"68.8 bpm" yading@11: $ yading@11: yading@11: Although handy for experimentation, the -d option is inadvisable in yading@11: any "production" situation because the plugin configuration is not yading@11: guaranteed to be the same each time (for example if an updated version yading@11: of a plugin changes some of its defaults). It's better to save a yading@11: well-defined transform to file and refer to that, even if it is simply yading@11: the transform created by the skeleton option. yading@11: yading@11: To run more than one transform on the same audio files, just put more yading@11: than one set of transform RDF descriptions in the same file, or give yading@11: the -t option more than once with separate transform description yading@11: files. Remember that if you want to specify more than one transform yading@11: in the same file, they will need to have distinct URIs (that is, the yading@11: ":transform" part of the example above, which may be any arbitrary yading@11: name, must be distinct for each described transform). yading@11: yading@11: yading@11: 3. How and where to write the results yading@11: yading@11: Sonic Annotator supports various different output modules (and it is yading@11: fairly easy for the developer to add new ones). You have to choose at yading@11: least one output module; use the -w (writer) option to do so. Each yading@11: module has its own set of parameters which can be adjusted on the yading@11: command line, as well as its own default rules about where to write yading@11: the results. yading@11: yading@11: The following writers are currently supported. (Others exist, but are yading@11: not properly implemented or not supported.) yading@11: yading@11: * csv yading@11: yading@11: Writes the results into comma-separated data files. yading@11: yading@11: One file is created for each transform applied to each input audio yading@11: file, named after the input audio file and transform name with .csv yading@11: suffix and ":" replaced by "_" throughout, placed in the same yading@11: directory as the audio file. yading@11: yading@11: To instruct Sonic Annotator to place the output files in another yading@11: location, use --csv-basedir with a directory name. yading@11: yading@11: To write a single file with all data in it, use --csv-one-file. yading@11: yading@11: To write all data to stdout instead of to a file, use --csv-stdout. yading@11: yading@11: Sonic Annotator will not write to an output file that already yading@11: exists. If you want to make it do this, use --csv-force to yading@11: overwrite or --csv-append to append to it. yading@11: yading@11: The data generated consists of one line for each result feature, yading@11: containing the feature timestamp, feature duration if present, all yading@11: of the feature's bin values in order, followed by the feature's yading@11: label if present. If the --csv-one-file or --csv-stdout option is yading@11: specified, then an additional column will appear before any of the yading@11: above, containing the audio file name from which the feature was yading@11: extracted, if it differs from that of the previous row. yading@11: yading@11: The default column separator is a comma; you can specify a yading@11: different one with the --csv-separator option. yading@11: yading@11: * rdf yading@11: yading@11: Writes the results into RDF/Turtle documents following the Audio yading@11: Features ontology (http://purl.org/ontology/af/). yading@11: yading@11: One file is created for each input audio file containing the yading@11: features extracted by all transforms applied to that file, named yading@11: after the input audio file with .n3 extension, placed in the same yading@11: directory as the audio file. yading@11: yading@11: To instruct Sonic Annotator to place the output files in another yading@11: location, use --rdf-basedir with a directory name. yading@11: yading@11: To write a single file with all data (from all input audio files) yading@11: in it, use --rdf-one-file. yading@11: yading@11: To write one file for each transform applied to each input audio yading@11: file, named after the input audio file and transform name with .n3 yading@11: suffix and ":" replaced by "_" throughout, use --rdf-many-files. yading@11: yading@11: To write all data to stdout instead of to a file, use --rdf-stdout. yading@11: yading@11: Sonic Annotator will not write to an output file that already yading@11: exists. If you want to make it do this, use --rdf-force to yading@11: overwrite or --rdf-append to append to it. yading@11: yading@11: Sonic Annotator will use plugin description RDF if available to yading@11: enhance its output (for example identifying note onset times as yading@11: note onset times, if the plugin's RDF says that is what it yading@11: produces, rather than writing them as plain events). Best results yading@11: will be obtained if an RDF document is provided with your plugins yading@11: (for example, vamp-example-plugins.n3) and you have this installed yading@11: in the same location as the plugins. To override this enhanced yading@11: output and write plain events for all features, use --rdf-plain. yading@11: yading@11: The output RDF will include an available_as property linking the yading@11: results to the original audio signal URI. By default, this will yading@11: point to the URI of the file or resource containing the audio that yading@11: Sonic Annotator processed, such as the file:/// location on disk. yading@11: To override this, for example to process a local copy of a file yading@11: while generating RDF that describes a copy of it available on a yading@11: network, you can use the --rdf-signal-uri option to specify an yading@11: alternative signal URI. yading@11: yading@11: yading@11: 4. Optionally, how to summarise the features yading@11: yading@11: Sonic Annotator can also calculate and write summaries of features, yading@11: such as mean and median values. yading@11: yading@11: To obtain a summary as well as the feature results, just use the -S yading@11: option, naming the type of summary you want (min, max, mean, median, yading@11: mode, sum, variance, sd or count). You can also tell it to produce yading@11: only the summary, not the individual features, with --summary-only. yading@11: yading@11: Alternatively, you can specify a summary in a transform description. yading@11: The following example tells Sonic Annotator to write both the times of yading@11: note onsets estimated by the simple percussion onset detector example yading@11: plugin, and the variance of the plugin's onset detection function. yading@11: (It will only process the audio file and run the plugin once.) yading@11: yading@11: @prefix rdf: . yading@11: @prefix vamp: . yading@11: @prefix examples: . yading@11: @prefix : <#>. yading@11: yading@11: :transform1 a vamp:Transform; yading@11: vamp:plugin examples:percussiononsets ; yading@11: vamp:output examples:percussiononsets_output_onsets . yading@11: yading@11: :transform0 a vamp:Transform; yading@11: vamp:plugin examples:percussiononsets ; yading@11: vamp:output examples:percussiononsets_output_detectionfunction ; yading@11: vamp:summary_type "variance" . yading@11: yading@11: Sonic Annotator can also summarise in segments -- if you provide a yading@11: comma-separated list of times as an argument to the --segments option, yading@11: it will calculate one summary for each segment bounded by the times yading@11: you provided. For example, yading@11: yading@11: $ sonic-annotator -d vamp:vamp-example-plugins:percussiononsets:detectionfunction -S variance --sumary-only --segments 1,2,3 -w csv --csv-stdout audio.wav yading@11: (... some log output on stderr, then ...) yading@11: ,0.000000000,1.000000000,variance,1723.99,"(variance, continuous-time average)" yading@11: ,1.000000000,1.000000000,variance,1981.75,"(variance, continuous-time average)" yading@11: ,2.000000000,1.000000000,variance,1248.79,"(variance, continuous-time average)" yading@11: ,3.000000000,7.031020407,variance,1030.06,"(variance, continuous-time average)" yading@11: yading@11: Here the first row contains a summary covering the time period from 0 yading@11: to 1 second, the second from 1 to 2 seconds, the third from 2 to 3 yading@11: seconds and the fourth from 3 seconds to the end of the (short) audio yading@11: file. yading@11: