Wiki » History » Version 13

Gyorgy Fazekas, 2015-08-10 02:36 AM

1 1 Mi Tian
h1. Wiki
2 1 Mi Tian
3 1 Mi Tian
h2. Vamp environment for feature extraction
4 1 Mi Tian
5 4 Mi Tian
_Vamp_ is an audio processing plugin system for plugins that extract descriptive information from audio data — typically referred to as audio analysis plugins or audio feature extraction plugins. The _vamp plugins_ are distributed in shared library files with extension _.dll_, _.so_, or _.dylib_ depending on the platform.  
6 1 Mi Tian
7 4 Mi Tian
Several common audio file formats are supported, including MP3, Ogg, and a number of PCM formats such as WAV and AIFF. AAC is supported on OS/X only, and only if not DRM protected. WMA is not supported.
8 1 Mi Tian
9 10 Gyorgy Fazekas
See http://vamp-plugins.org/ for more introduction about Vamp environment and the plugins.
10 1 Mi Tian
11 12 Gyorgy Fazekas
h2. Vampy wrapper plugin (for running plugin written in Python)
12 10 Gyorgy Fazekas
13 11 Gyorgy Fazekas
Vamp plugins are typically written in C++. To use Vamp plugins written in Python you need to install the "Vampy wrapper plugin":http://www.vamp-plugins.org/vampy.html. 
14 11 Gyorgy Fazekas
Then, any python script following some simple conventions will be presented to a vamp host as it was an ordinary Vamp plugin.
15 10 Gyorgy Fazekas
16 10 Gyorgy Fazekas
Download Vampy: http://www.vamp-plugins.org/vampy.html
17 10 Gyorgy Fazekas
Tutorial: http://isophonics.net/content/getting-started-vampy
18 10 Gyorgy Fazekas
19 10 Gyorgy Fazekas
Put the plugins in your Vamp plugin folder or any other designated directory. You may set an environment variable to tell
20 10 Gyorgy Fazekas
your system where to look for Vampy plugins. On Linux/Unix or OS/X: $ export VAMPY_PATH="/your/vampy/plugin/directory"
21 10 Gyorgy Fazekas
22 10 Gyorgy Fazekas
Optionally, you may need to tell your system where to find Python for Vampy to work correctly:
23 1 Mi Tian
To do this, set the VAMPY_PYLIB environment variable to the location of the python shared library (.dylib / .so).
24 10 Gyorgy Fazekas
25 11 Gyorgy Fazekas
For more information see "this readme file in the Vampy package":https://code.soundsoftware.ac.uk/projects/vampy/repository/entry/README
26 10 Gyorgy Fazekas
27 6 Mi Tian
h2. Host applications
28 1 Mi Tian
29 1 Mi Tian
A vamp plugin cannot be used on its own, but only with a conforming _host_ application which loads the plugin from its shared library and calls functions within the plugin code to configure it, supply it with data, and run it.
30 1 Mi Tian
31 10 Gyorgy Fazekas
* "Sonic Visualiser":http://www.sonicvisualiser.org/ -- An interactive audio analysis and visualisation tool using Vamp plugins
32 6 Mi Tian
33 10 Gyorgy Fazekas
* "Sonic Annotator":https://code.soundsoftware.ac.uk/projects/sonic-annotator -- A command line tool facilitating facilitating feature extraction, parameter configuration and output manipulation for a large bunch of audio files.
34 6 Mi Tian
35 1 Mi Tian
* "Audacity":http://audacityteam.org/ -- An audio editor which enables recording, labelling and editing the audio.
36 13 Gyorgy Fazekas
37 13 Gyorgy Fazekas
Note: If you are developing new plugins in Python it is customary to use a command line host such as Sonic Annotator or the Vamp Simple Host
38 13 Gyorgy Fazekas
available in the Vamp Plugin SDK. This will allow you to see error messages printed to the terminal, which would otherwise be invisible.
39 13 Gyorgy Fazekas
Vampy plugins can be used in any GUI host like Sonic Visualiser, but errors reported by plugin scripts will be more difficult to see.
40 6 Mi Tian
41 6 Mi Tian
42 1 Mi Tian
h2. Plugin installation
43 4 Mi Tian
44 10 Gyorgy Fazekas
The vamp plugins need to be put in a directory where the host can locate, i.e., the _VAMP_PATH_. See http://vamp-plugins.org/download.html#install for installation instructions. 
45 1 Mi Tian
46 1 Mi Tian
Alternatively, you can set your own VAMP_PATH environment variable to list the locations a host should look in for Vamp plugins. For example, the following command will set @/homes/mitian/hg/onset-fusion@ as an alternative VAMP_PATH. Plugins placed in this directory will also be locatable for the hosts besides those under the system specified vamp directories.
47 10 Gyorgy Fazekas
48 4 Mi Tian
<pre>
49 5 Mi Tian
mitian$ export VAMP_PATH=$VAMP_PATH:/homes/mitian/hg/onset-fusion
50 4 Mi Tian
</pre>
51 4 Mi Tian
52 4 Mi Tian
Once the plugins are installed in the Vamp path, they will show themselves under the _Transform_ tab in Sonic Visualiser, or the _Analyze_ tab in Audacity, or in the terminal when you list them using Sonic Annotator (@ sonic-annotator -l@). 
53 4 Mi Tian
54 1 Mi Tian
h2. Parameters and outputs of this plugin set
55 4 Mi Tian
56 4 Mi Tian
h3. Parameters
57 4 Mi Tian
<pre>
58 5 Mi Tian
    **Adjustable parameters**
59 9 Gyorgy Fazekas
	Fusion Type                         Fusion type [0: early fusion, 1: linear fusion, 2: decision fusion]
60 9 Gyorgy Fazekas
	Detection Sensitivity               Sensitivity level for peak detection in the onset likelihood function.
61 9 Gyorgy Fazekas
                                            The higher the sensitivity, the more onsets will (rightly or wrongly) be detected.
62 9 Gyorgy Fazekas
	Delta Threshold                     Constant offset used for adaptive theresholding using the median of the detection function.
63 9 Gyorgy Fazekas
	Backtracking Threshold              Backtracking threshold used determine the stopping condition for backtracking the detected onset location to an earlier 'perceived' location.
64 9 Gyorgy Fazekas
	Tolerance window                    Tolerance window to combine events from different detection functions for decision fusion.
65 9 Gyorgy Fazekas
	Linear combination coefficient      Combination coefficient for linear fusion.
66 9 Gyorgy Fazekas
	Median filter window                Median filter window size.
67 9 Gyorgy Fazekas
	Cutoff frequency                    Cutoff frequency for the low pass filter.
68 8 Mi Tian
	
69 9 Gyorgy Fazekas
	**bool parameters**                 [0: off, 1: on]
70 9 Gyorgy Fazekas
	Polynomial fitting                  Use polynomial fitting to evaluate detection function peaks.
71 9 Gyorgy Fazekas
	Median filtering                    Use median filter based adaptive thresholding.
72 4 Mi Tian
	Low-pass filtering                  Use low pass filtering to smooth onset detection functions.
73 4 Mi Tian
	Adaptive whitening                  Use adaptive whitening. It evens out the temporal and frequency variation in the signal.
74 4 Mi Tian
</pre>
75 4 Mi Tian
76 1 Mi Tian
h3. Outputs
77 6 Mi Tian
78 6 Mi Tian
79 6 Mi Tian
# *Note Onsets* – The detected note onset times, returned as a single feature with timestamp.
80 1 Mi Tian
# *Smoothed Detection Function* – The smoothed onset detection function.
81 1 Mi Tian
# *Note Onsets* – The detected note onset times, returned as a single feature with timestamp.
82 5 Mi Tian
83 1 Mi Tian
84 1 Mi Tian
NOTE: The last two outputs are not available in fusion based onset detectors. Please check individual plugins for specific output types.
85 1 Mi Tian
 
86 1 Mi Tian
h2. Example usages of the onset detectors
87 1 Mi Tian
88 1 Mi Tian
To use these onset detector plugins in Sonic Visualiser and Audacity is quite straightforward. Load your audio file first, then select a feature extractor/plugin from the transform list. You will also find a set of adjustable parameters in the pop-out box associated with each transform. The extracted features, whether it is onset locations or detection functions, will be visualised in the pane on top of the waveform, synchronised with time.
89 5 Mi Tian
 
90 5 Mi Tian
For comprehensive user manuals, see
91 10 Gyorgy Fazekas
http://www.sonicvisualiser.org/doc/reference/2.1/en/index.html
92 10 Gyorgy Fazekas
http://wiki.audacityteam.org/wiki/Category:Tutorial
93 5 Mi Tian
94 5 Mi Tian
Rather than for visualisation purpose, Sonic Annotator lets you to extract and store audio features efficiently. Here we give a quick tutorial of how to detect onset for a given audio file and save the results to local folder using Sonic Annotator.
95 10 Gyorgy Fazekas
96 3 Mi Tian
<pre>
97 3 Mi Tian
mitian$ sonic-annotator -l | grep vampy-onsets
98 3 Mi Tian
vamp:vampy:vampy-onsets-bersf:vampy-onsets-bersf-onsets
99 3 Mi Tian
vamp:vampy:vampy-onsets-cdsf:vampy-onsets-cdsf-onsets
100 3 Mi Tian
vamp:vampy:vampy-onsets-ber:vampy-onsets-ber-df
101 3 Mi Tian
vamp:vampy:vampy-onsets-ber:vampy-onsets-ber-onsets
102 3 Mi Tian
vamp:vampy:vampy-onsets-ber:vampy-onsets-ber-sdf
103 3 Mi Tian
vamp:vampy:vampy-onsets-cd:vampy-onsets-cd-df
104 3 Mi Tian
vamp:vampy:vampy-onsets-cd:vampy-onsets-cd-onsets
105 3 Mi Tian
vamp:vampy:vampy-onsets-cd:vampy-onsets-cd-sdf
106 3 Mi Tian
vamp:vampy:vampy-onsets-hfc:vampy-onsets-hfc-df
107 3 Mi Tian
vamp:vampy:vampy-onsets-hfc:vampy-onsets-hfc-onsets
108 3 Mi Tian
vamp:vampy:vampy-onsets-hfc:vampy-onsets-hfc-sdf
109 3 Mi Tian
vamp:vampy:vampy-onsets-pd:vampy-onsets-pd-df
110 3 Mi Tian
vamp:vampy:vampy-onsets-pd:vampy-onsets-pd-onsets
111 3 Mi Tian
vamp:vampy:vampy-onsets-pd:vampy-onsets-pd-sdf
112 1 Mi Tian
vamp:vampy:vampy-onsets-sd:vampy-onsets-sd-df
113 3 Mi Tian
vamp:vampy:vampy-onsets-sd:vampy-onsets-sd-onsets
114 3 Mi Tian
vamp:vampy:vampy-onsets-sd:vampy-onsets-sd-sdf
115 3 Mi Tian
vamp:vampy:vampy-onsets-sf:vampy-onsets-sf-df
116 3 Mi Tian
vamp:vampy:vampy-onsets-sf:vampy-onsets-sf-onsets
117 3 Mi Tian
vamp:vampy:vampy-onsets-sf:vampy-onsets-sf-sdf
118 1 Mi Tian
mitian$
119 1 Mi Tian
mitian$ sonic-annotator -d vamp:vampy:vampy-onsets-cdsf:vampy-onsets-cdsf-onsets -w csv test.wav --csv-basedir /homes/mitian/hg/workspace/onsetdetection
120 3 Mi Tian
Extracting and writing features... Done
121 4 Mi Tian
122 3 Mi Tian
Vampy::~PyExtensionManager: Extension module cleaned.
123 3 Mi Tian
mitian$
124 1 Mi Tian
mitian$
125 3 Mi Tian
</pre>
126 3 Mi Tian
127 6 Mi Tian
Each line of the output csv file consists of the timestamp (and duration where applicable) for a single feature, the value of that feature and the feature's label (where applicable), separated by comma.
128 1 Mi Tian
129 3 Mi Tian
Sonic Anntator also allows for batch processing in one go. 
130 3 Mi Tian
<pre>
131 11 Gyorgy Fazekas
132 1 Mi Tian
mitian$ sonic-annotator -d vamp:vampy:vampy-onsets-cdsf:vampy-onsets-cdsf-onsets -w csv /homes/mitian/documents/audio/*.wav --csv-basedir /homes/mitian/hg/workspace/onsetdetection
133 1 Mi Tian
Extracting and writing features... Done
134 3 Mi Tian
135 3 Mi Tian
Vampy::~PyExtensionManager: Extension module cleaned.
136 11 Gyorgy Fazekas
137 11 Gyorgy Fazekas
138 3 Mi Tian
</pre>
139 3 Mi Tian
140 4 Mi Tian
h2. Play around with your vamp plugin feature extractors
141 1 Mi Tian
142 4 Mi Tian
We may want use parameter settings other the default. With Sonic Visualiser or Audacity, you can easily access the GUI to modify them. Whiles with Sonic Annotator, you would need to interact with 
143 3 Mi Tian
144 4 Mi Tian
Firstly, we can check the current parameter configurations in the skeleton transform description using Sonic Annotator's @-s@ command.
145 3 Mi Tian
146 3 Mi Tian
<pre>
147 11 Gyorgy Fazekas
148 3 Mi Tian
mitian$ sonic-annotator -s vamp:vampy:vampy-onsets-cdsf:vampy-onsets-cdsf-onsets
149 3 Mi Tian
@prefix xsd:      <http://www.w3.org/2001/XMLSchema> .
150 3 Mi Tian
  @prefix vamp:     <http://purl.org/ontology/vamp/> .
151 3 Mi Tian
  @prefix :         <#> .
152 3 Mi Tian
153 3 Mi Tian
 
154 3 Mi Tian
:transform_plugin a vamp:Plugin ;
155 3 Mi Tian
    vamp:identifier "vampy-onsets-cdsf" .
156 3 Mi Tian
157 3 Mi Tian
:transform_library a vamp:PluginLibrary ;
158 3 Mi Tian
    vamp:identifier "vampy" ;
159 3 Mi Tian
    vamp:available_plugin :transform_plugin .
160 3 Mi Tian
161 3 Mi Tian
:transform a vamp:Transform ;
162 3 Mi Tian
    vamp:plugin :transform_plugin ;
163 3 Mi Tian
    vamp:step_size "512"^^xsd:int ;
164 3 Mi Tian
    vamp:block_size "1024"^^xsd:int ;
165 3 Mi Tian
    vamp:parameter_binding [
166 3 Mi Tian
        vamp:parameter [ vamp:identifier "bt-threshold" ] ;
167 3 Mi Tian
        vamp:value "0.9"^^xsd:float ;
168 3 Mi Tian
    ] ;
169 3 Mi Tian
    vamp:parameter_binding [
170 3 Mi Tian
        vamp:parameter [ vamp:identifier "cut-off" ] ;
171 3 Mi Tian
        vamp:value "0.34"^^xsd:float ;
172 3 Mi Tian
    ] ;
173 3 Mi Tian
    vamp:parameter_binding [
174 3 Mi Tian
        vamp:parameter [ vamp:identifier "dthreshold" ] ;
175 3 Mi Tian
        vamp:value "0"^^xsd:float ;
176 3 Mi Tian
    ] ;
177 3 Mi Tian
    vamp:parameter_binding [
178 3 Mi Tian
        vamp:parameter [ vamp:identifier "filtfilt" ] ;
179 3 Mi Tian
        vamp:value "1"^^xsd:float ;
180 3 Mi Tian
    ] ;
181 3 Mi Tian
    vamp:parameter_binding [
182 3 Mi Tian
        vamp:parameter [ vamp:identifier "fusion-type" ] ;
183 3 Mi Tian
        vamp:value "2"^^xsd:float ;
184 3 Mi Tian
    ] ;
185 3 Mi Tian
    vamp:parameter_binding [
186 3 Mi Tian
        vamp:parameter [ vamp:identifier "lin-threshold" ] ;
187 3 Mi Tian
        vamp:value "0.5"^^xsd:float ;
188 3 Mi Tian
    ] ;
189 3 Mi Tian
    vamp:parameter_binding [
190 3 Mi Tian
        vamp:parameter [ vamp:identifier "med-threshold" ] ;
191 3 Mi Tian
        vamp:value "7"^^xsd:float ;
192 3 Mi Tian
    ] ;
193 3 Mi Tian
    vamp:parameter_binding [
194 3 Mi Tian
        vamp:parameter [ vamp:identifier "medfilt" ] ;
195 3 Mi Tian
        vamp:value "1"^^xsd:float ;
196 3 Mi Tian
    ] ;
197 3 Mi Tian
    vamp:parameter_binding [
198 3 Mi Tian
        vamp:parameter [ vamp:identifier "polyfit" ] ;
199 3 Mi Tian
        vamp:value "1"^^xsd:float ;
200 3 Mi Tian
    ] ;
201 3 Mi Tian
    vamp:parameter_binding [
202 3 Mi Tian
        vamp:parameter [ vamp:identifier "threshold" ] ;
203 3 Mi Tian
        vamp:value "50"^^xsd:float ;
204 3 Mi Tian
    ] ;
205 3 Mi Tian
    vamp:parameter_binding [
206 1 Mi Tian
        vamp:parameter [ vamp:identifier "tol-threshold" ] ;
207 1 Mi Tian
        vamp:value "0.03"^^xsd:float ;
208 1 Mi Tian
    ] ;
209 1 Mi Tian
    vamp:parameter_binding [
210 1 Mi Tian
        vamp:parameter [ vamp:identifier "whitening" ] ;
211 1 Mi Tian
        vamp:value "0"^^xsd:float ;
212 1 Mi Tian
    ] ;
213 1 Mi Tian
    vamp:output [ vamp:identifier "vampy-onsets-cdsf-onsets" ] .
214 1 Mi Tian
mitian$
215 1 Mi Tian
</pre>
216 1 Mi Tian
217 6 Mi Tian
Transforms are usually described in _RDF_, following the transform part of the [["Vamp plugin ontology":http://www.omras2.org/VampOntology]]. Now, how can be change the parameter settings in the transform specification file? 
218 1 Mi Tian
219 1 Mi Tian
The solution is to save this RDF file and modify any content in it as we wish, then to run this transform by specifying the saved file with the @-t@ option. Let's see an example.
220 1 Mi Tian
221 6 Mi Tian
<pre>
222 11 Gyorgy Fazekas
223 4 Mi Tian
mitian$ sonic-annotator -s vamp:vampy:vampy-onsets-cdsf:vampy-onsets-cdsf-onsets >param_config.n3
224 11 Gyorgy Fazekas
225 4 Mi Tian
</pre>
226 11 Gyorgy Fazekas
227 4 Mi Tian
Now the transform file has been saved to the .n3 (RDF) file. Say, we want to use a higher threshold and change it from 50 to 70. Open an text editor, simple modify the corresponding lines in the saved n3 file
228 11 Gyorgy Fazekas
229 4 Mi Tian
<pre>
230 4 Mi Tian
        vamp:parameter [ vamp:identifier "threshold" ] ;
231 4 Mi Tian
        vamp:value "50"^^xsd:float ;
232 4 Mi Tian
</pre>
233 1 Mi Tian
into 
234 4 Mi Tian
<pre>
235 4 Mi Tian
        vamp:parameter [ vamp:identifier "threshold" ] ;
236 1 Mi Tian
        vamp:value "70"^^xsd:float ;
237 1 Mi Tian
</pre>
238 1 Mi Tian
and save it.
239 1 Mi Tian
240 1 Mi Tian
Now we can run the same plugin using the modified parameter settings.
241 1 Mi Tian
<pre>
242 11 Gyorgy Fazekas
243 4 Mi Tian
mitian$ sonic-annotator -t param_config.n3 -w csv test.wav --csv-basedir /homes/mitian/hg/workspace/onsetdetection
244 4 Mi Tian
Extracting and writing features... Done
245 4 Mi Tian
246 4 Mi Tian
Vampy::~PyExtensionManager: Extension module cleaned.
247 11 Gyorgy Fazekas
248 4 Mi Tian
</pre>
249 4 Mi Tian
250 6 Mi Tian
This example only involves a couple of operations for Sonic Annotator. You may also want to type
251 6 Mi Tian
@sonic-annotator -h@
252 7 Mi Tian
for a helpbook. Also your working directory should be where Sonic Annotator is installed. 
253 6 Mi Tian
  
254 6 Mi Tian
h2. That's all guys! Happy hacking with Vamp plugins :)