Mercurial > hg > vamp-website

comparison plugin-doc/vamp-example-plugins.html @ 6:73f05249ac60 website

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Update Vamp example plugins RDF, add user doc
author cannam
date Fri, 14 Nov 2008 11:55:26 +0000
parents
children 60ee9a026a62
comparison
equal deleted inserted replaced
5:3bb2cfd86a2f 6:73f05249ac60
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <link rel="stylesheet" media="screen" type="text/css" href="/screen.css"/>
5 <link rel="icon" type="image/png" href="/images/waveform.png"/>
6 <link rel="shortcut" type="image/png" href="/images/waveform.png"/>
7 <title>Vamp Example Plugins: User Documentation</title>
8 <meta name="robots" content="index"/>
9 </head>
10 <body>
11 <h1 id="header"><span>Vamp Example Plugins</span></h1>
12
13 <p>The <code>vamp-example-plugins</code> library contains a number of
14 <a href="http://www.vamp-plugins.org/">Vamp audio analysis
15 plugins</a> provided as part of the Vamp plugin SDK.
16
17 </p>
18 <p>These are simple, but sometimes useful, plugins whose source code you
19 are free to study and reuse in any proprietary or non-proprietary
20 plugins of your own without any licensing obligation.
21 </p>
22 <p>User documentation for the individual plugins in this library follows.
23 </p>
24 <div class="toc2">1. &nbsp;<a href="#amplitudefollower">Amplitude Follower</a></div>
25 <div class="toc2">2. &nbsp;<a href="#fixedtempo">Simple Fixed Tempo Estimator</a></div>
26 <div class="toc2">3. &nbsp;<a href="#percussiononsets">Simple Percussion Onset Detector</a></div>
27 <div class="toc2">4. &nbsp;<a href="#powerspectrum">Simple Power Spectrum</a></div>
28 <div class="toc2">5. &nbsp;<a href="#spectralcentroid">Spectral Centroid</a></div>
29 <div class="toc2">6. &nbsp;<a href="#zerocrossing">Zero Crossings</a></div>
30
31 <div class="oddcontent"><a name="amplitudefollower"></a><h2>1. &nbsp;Amplitude Follower</h2>
32
33 <p><b>System identifier</b> &ndash; <code>vamp-example-plugins:amplitudefollower</code><br>
34 <b>RDF URI</b> &ndash; <a href="http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#amplitudefollower">http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#amplitudefollower</a>
35 </p>
36 <p>Amplitude Follower tracks and returns the amplitude of the audio
37 signal sample by sample, returning peak values block by block.
38 </p>
39 </div><div class="evencontent"><a name="toc2"></a><h3>1.1. &nbsp;Parameters</h3>
40
41 <p><b>Attack time</b> (seconds) &ndash; The 60dB convergence time for an increase in amplitude.<br>
42 <b>Release time</b> (seconds) &ndash; The 60dB convergence time for a decrease in amplitude.
43 </p>
44 <p>For example, if you feed the plugin with a simple step function that
45 jumps from level A to level B, then the output will start off as A,
46 then at the moment of stepping it will start to converge exponentially
47 to B, reaching with 60dB of the actual value within the time specified
48 by the Attack time parameter.
49 </p>
50 <p>Similarly, if the plugin's input then steps down from B to A, the
51 output will start converging at the moment of stepping, reaching
52 within 60dB of the new value within the time specified by the Release
53 time parameter.
54 </p>
55 </div><div class="oddcontent"><a name="toc3"></a><h3>1.2. &nbsp;Outputs</h3>
56
57 </div><div class="evencontent"><a name="toc4"></a><h4>1.2.1. &nbsp;Amplitude</h4>
58
59 <p>The peak tracked amplitude (in volts) for the current processing block.
60 </p>
61 </div><div class="oddcontent"><a name="toc5"></a><h3>1.3. &nbsp;References and Credits</h3>
62
63 <p>Amplitude Follower uses a method from the SuperCollider audio
64 processing language. It was implemented as a Vamp plugin by Dan
65 Stowell.
66 </p>
67 </div><div class="evencontent"><a name="fixedtempo"></a><h2>2. &nbsp;Simple Fixed Tempo Estimator</h2>
68
69 <p><b>System identifier</b> &ndash; <code>vamp-example-plugins:fixedtempo</code><br>
70 <b>RDF URI</b> &ndash; <a href="http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#fixedtempo">http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#fixedtempo</a>
71 </p>
72 <p>Simple Fixed Tempo Estimator analyses a fragment of audio and
73 estimates its tempo. It assumes that its input is of fixed tempo, and
74 it analyses only the first (small but configurable number of) seconds
75 before returning a result, discarding all subsequent input.
76 </p>
77 <p>The plugin calculates an overall energy rise function across a series
78 of short frequency-domain input frames, takes the autocorrelation of
79 this function, filters it to stress possible metrical patterns,
80 locates peaks, and converts from autocorrelation lag to the
81 corresponding tempo.
82 </p>
83 <p>The filtering process involves searching for peaks at simple
84 metrically related intervals (at a given autocorrelation lag as well
85 as at 0.5, 2, and 4 times that lag), boosting each peak that shows
86 strong related peaks. A simplistic perceptual curve is also applied
87 in order to increase the probability of detecting a "likely" tempo.
88 For improved tempo precision, each tempo with strong related peaks is
89 averaged with the tempi calculated from those peaks.
90 </p>
91 <p>The method is best suited for 4/4 pop and dance rhythms.
92 </p>
93 <p>This plugin returns many of its intermediate calculations as
94 additional outputs, as well as the most favoured tempo. Although as a
95 tempo estimator it's still fairly primitive, it is intended to provide
96 a useful example of a slightly more complex feature extraction plugin
97 than the other examples, as well as one that returns several different
98 types of output at a time.
99 </p>
100 </div><div class="oddcontent"><a name="toc7"></a><h3>2.1. &nbsp;Parameters</h3>
101
102 <p><b>Minimum estimated tempo</b>, <b>Maximum estimated tempo</b> (bpm) &ndash; These
103 parameters control the range of values within which the tempo
104 estimator will return its estimate.
105 </p>
106 <p><b>Input duration to study</b> (seconds) &ndash; The tempo estimator uses only the
107 first part of its input, discarding any that follows. This parameter
108 controls how much input it will use. There is no value in increasing
109 this beyond 8x the duration of the slowest returned beat. The default
110 of 10 seconds is likely to be appropriate for most purposes.
111 </p>
112 </div><div class="evencontent"><a name="toc8"></a><h3>2.2. &nbsp;Outputs</h3>
113
114 </div><div class="oddcontent"><a name="toc9"></a><h4>2.2.1. &nbsp;Tempo</h4>
115
116 <p>The tempo estimator's best guess at the tempo of its input, in beats
117 per minute.
118 </p>
119 <p>This is returned as a feature whose timestamp and duration cover the
120 range of the input which was used in estimating the tempo, with a
121 single value containing the tempo.
122 </p>
123 </div><div class="evencontent"><a name="toc10"></a><h4>2.2.2. &nbsp;Tempo candidates</h4>
124
125 <p>Several guesses at the possible tempo. This output is returned as a
126 single feature whose timestamp and duration cover the range of the
127 input which was used in estimating the tempo, with up to 10 bins
128 containing one tempo value in each bin, with the "best guess" tempo in
129 bin 0.
130 </p>
131 </div><div class="oddcontent"><a name="toc11"></a><h4>2.2.3. &nbsp;Detection function</h4>
132
133 <p>The basic onset detection function used in tempo estimation.
134 </p>
135 </div><div class="evencontent"><a name="toc12"></a><h4>2.2.4. &nbsp;Autocorrelation function</h4>
136
137 <p>The autocorrelation of the onset detection function.
138 </p>
139 </div><div class="oddcontent"><a name="toc13"></a><h4>2.2.5. &nbsp;Filtered Autocorrelation</h4>
140
141 <p>The autocorrelation after filtering to boost values with possible
142 metrically related peaks and to apply perceptual weighting. The peak
143 value of this function is the one that will be used as the "best
144 guess".
145 </p>
146 </div><div class="evencontent"><a name="toc14"></a><h3>2.3. &nbsp;References and Credits</h3>
147
148 <p>Simple Fixed Tempo Estimator uses a method derived from work by
149 Matthew Davies: see for example M. E. P. Davies and M. D. Plumbley,
150 <i>Beat Tracking With A Two State Model</i>, in Proceedings of the IEEE
151 International Conference on Acoustics, Speech and Signal Processing
152 2005. This plugin, made by Chris Cannam, is only an unsubtle
153 simplification of a small part of the published method.
154 </p>
155 <p>The Queen Mary plugin set
156 (<a href="http://www.elec.qmul.ac.uk/digitalmusic/downloads/index.html#qm-vamp-plugins">http://www.elec.qmul.ac.uk/digitalmusic/downloads/index.html#qm-vamp-plugins</a>)
157 contains a Tempo and Beat Tracker plugin by Matthew Davies providing a
158 more realistic implementation.
159 </p>
160 </div><div class="oddcontent"><a name="percussiononsets"></a><h2>3. &nbsp;Simple Percussion Onset Detector</h2>
161
162 <p><b>System identifier</b> &ndash; <code>vamp-example-plugins:percussiononsets</code><br>
163 <b>RDF URI</b> &ndash; <a href="http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#percussiononsets">http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#percussiononsets</a>
164 </p>
165 <p>Simple Percussion Onset Detector estimates the locations of percussive
166 onsets in the audio signal.
167 </p>
168 <p>The principle is to exploit the broadband nature of noisy percussive
169 onsets by identifying only those frames in which the energy rise shows
170 a broadband profile.
171 </p>
172 <p>The plugin takes a series of frequency domain frames, and examines
173 each frame to count the number of bins whose energy content has
174 increased by more than a certain threshold since the prior frame.
175 Frames in which this number is at a peak relative to prior and
176 following frames and also exceeds another threshold value are
177 classified as percussive onsets.
178 </p>
179 </div><div class="evencontent"><a name="toc16"></a><h3>3.1. &nbsp;Parameters</h3>
180
181 <p><b>Energy rise threshold</b> (dB) &ndash; The rise in energy within a bin from one
182 frame to the next that is required for a bin to be counted toward the
183 detection function's bin count. This roughly corresponds to how
184 "loud" a percussive sound must be in order to be detected.
185 </p>
186 <p><b>Sensitivity</b> (%) &ndash; The proportion of bins that must exceed the energy
187 rise threshold in order for an onset to be detected (at frames in
188 which the detection function peaks). This roughly corresponds to how
189 "noisy" a percussive sound must be in order to be detected.
190 </p>
191 </div><div class="oddcontent"><a name="toc17"></a><h3>3.2. &nbsp;Outputs</h3>
192
193 </div><div class="evencontent"><a name="toc18"></a><h4>3.2.1. &nbsp;Onsets</h4>
194
195 <p>The estimated onset locations.
196 </p>
197 </div><div class="oddcontent"><a name="toc19"></a><h4>3.2.2. &nbsp;Detection Function</h4>
198
199 <p>The energy rise detection function whose peaks were used to estimate
200 onset locations.
201 </p>
202 </div><div class="evencontent"><a name="toc20"></a><h3>3.3. &nbsp;References and Credits</h3>
203
204 <p>The method used in Simple Percussion Onset Detector was described in
205 Dan Barry, Derry Fitzgerald, Eugene Coyle and
206 Bob Lawlor, <i>Drum Source Separation using Percussive Feature Detection and
207 Spectral Modulation</i>, ISSC 2005. The plugin was made by Chris Cannam.
208 </p>
209 </div><div class="oddcontent"><a name="powerspectrum"></a><h2>4. &nbsp;Simple Power Spectrum</h2>
210
211 <p><b>System identifier</b> &ndash; <code>vamp-example-plugins:powerspectrum</code><br>
212 <b>RDF URI</b> &ndash; <a href="http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#powerspectrum">http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#powerspectrum</a>
213 </p>
214 <p>Simple Power Spectrum returns a power spectrum calculated from
215 windowed short-time Fourier transforms of the input audio. (The power
216 spectrum for a frame consists of a sequence of the squares of the
217 magnitudes of the complex values for each frequency bin in the result
218 of the Fourier transform.)
219 </p>
220 <p>This very simple plugin is an illustration of the fact that if a
221 plugin requests frequency-domain input, its input will already be in
222 the form needed for a spectrum such as this. The plugin has no work
223 left to do except to calculate the squared magnitude from the
224 cartesian complex representation.
225 </p>
226 <p>This plugin also illustrates how to return "grid-type" visualisation
227 data from a Vamp plugin.
228 </p>
229 </div><div class="evencontent"><a name="toc22"></a><h3>4.1. &nbsp;Parameters</h3>
230
231 <p>None.
232 </p>
233 </div><div class="oddcontent"><a name="toc23"></a><h3>4.2. &nbsp;Outputs</h3>
234
235 </div><div class="evencontent"><a name="toc24"></a><h4>4.2.1. &nbsp;Power Spectrum</h4>
236
237 <p>The power spectrum calculated from the input frame. This output
238 returns a single feature per processing block, containing
239 blocksize/2+1 power values corresponding to the FFT bins from DC to
240 Nyquist inclusive. The DC bin is always returned.
241 </p>
242 </div><div class="oddcontent"><a name="spectralcentroid"></a><h2>5. &nbsp;Spectral Centroid</h2>
243
244 <p><b>System identifier</b> &ndash; <code>vamp-example-plugins:spectralcentroid</code><br>
245 <b>RDF URI</b> &ndash; <a href="http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#spectralcentroid">http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#spectralcentroid</a>
246 </p>
247 <p>Spectral Centroid calculates the "centre of gravity" of the frequency
248 spectrum for each input frame.
249 </p>
250 </div><div class="evencontent"><a name="toc26"></a><h3>5.1. &nbsp;Parameters</h3>
251
252 <p>None.
253 </p>
254 </div><div class="oddcontent"><a name="toc27"></a><h3>5.2. &nbsp;Outputs</h3>
255
256 </div><div class="evencontent"><a name="toc28"></a><h4>5.2.1. &nbsp;Log Frequency Centroid</h4>
257
258 <p>The centroid of the log-weighted frequency spectrum. That is, the sum
259 across Fourier transform output bins of the logarithm of the bin
260 frequency multiplied by the bin magnitude, divided by the sum of the
261 bin magnitudes, and the inverse logarithm taken so as to give the
262 result as a frequency in Hz.
263 </p>
264 </div><div class="oddcontent"><a name="toc29"></a><h4>5.2.2. &nbsp;Linear Frequency Centroid</h4>
265
266 <p>The centroid of the linear-weighted frequency spectrum. That is, the
267 sum across Fourier transform output bins of the bin frequency
268 multiplied by the bin magnitude, divided by the sum of the bin
269 magnitudes. The result is a frequency in Hz.
270 </p>
271 </div><div class="evencontent"><a name="zerocrossing"></a><h2>6. &nbsp;Zero Crossings</h2>
272
273 <p><b>System identifier</b> &ndash; <code>vamp-example-plugins:zerocrossing</code><br>
274 <b>RDF URI</b> &ndash; <a href="http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#zerocrossing">http://vamp-plugins.org/rdf/plugins/vamp-example-plugins#zerocrossing</a>
275 </p>
276 <p>Zero Crossings calculates the positions and density of "zero-crossing"
277 points in an audio waveform. For the purposes of this plugin, that
278 means those positions at which the sampled value switches from
279 zero-or-less to greater-than-zero, or vice versa.
280 </p>
281 </div><div class="oddcontent"><a name="toc31"></a><h3>6.1. &nbsp;Parameters</h3>
282
283 <p>None.
284 </p>
285 </div><div class="evencontent"><a name="toc32"></a><h3>6.2. &nbsp;Outputs</h3>
286
287 </div><div class="oddcontent"><a name="toc33"></a><h4>6.2.1. &nbsp;Zero Crossing Counts</h4>
288
289 <p>The number of zero-crossing points found in the current block of
290 samples, as a single-valued feature returned per processing block.
291 </p>
292 </div><div class="evencontent"><a name="toc34"></a><h4>6.2.2. &nbsp;Zero Crossings</h4>
293
294 <p>The locations of zero-crossing points, returning one feature
295 timestamped to the zero-crossing location, without values, for each
296 crossing point.
297 </p>
298 <p></p>
299
300 </div>
301 </body>
302 </html>