SampleType » History » Version 16

Chris Cannam, 2014-02-10 01:31 PM

1 1 Chris Cannam
h1. Output Sample Type and Sample Rate
2 1 Chris Cannam
3 15 Chris Cannam
{{>toc}}
4 15 Chris Cannam
5 12 Chris Cannam
A Vamp plugin receives audio and produces a series of descriptive feature structures.
6 1 Chris Cannam
7 12 Chris Cannam
The audio input is provided as a series of fixed-length sample blocks, equally spaced in time, provided to successive calls to the plugin's @process@ function. The plugin may return any number of features from each @process@ call, and may also return any number of features from @getRemainingFeatures@ after all the audio has been received.
8 11 Chris Cannam
9 11 Chris Cannam
Features are each associated with a particular output of the plugin. The plugin declares that each output has certain properties, which constrain the sort of feature data the host can expect to see. (See diagram.)
10 10 Chris Cannam
11 7 Chris Cannam
!/attachments/download/980/feature-structures-20pc.png!
12 9 Chris Cannam
13 9 Chris Cannam
A feature may or may not have a timestamp. Whether a timestamp is provided -- and, if it is provided, what it means -- are determined by the @SampleType@ and @SampleRate@ properties of the plugin output on which the feature is returned.
14 7 Chris Cannam
15 8 Chris Cannam
h2. SampleType
16 1 Chris Cannam
17 8 Chris Cannam
A plugin output's @SampleType@ property may be either @OneSamplePerStep@, @FixedSampleRate@, or @VariableSampleRate@. Here's what they mean.
18 8 Chris Cannam
19 1 Chris Cannam
h3. OneSamplePerStep
20 1 Chris Cannam
21 12 Chris Cannam
This is the simplest option. If an output is declared as having a @SampleType@ of @OneSamplePerStep@, then any features returned from a @process@ call are assumed to match up with the audio block provided to that @process@ call.
22 12 Chris Cannam
23 14 Chris Cannam
h4. What this means
24 1 Chris Cannam
25 14 Chris Cannam
For any features returned through an output declared with @OneSamplePerStep@ type,
26 14 Chris Cannam
27 14 Chris Cannam
 * The plugin _should not_ set timestamps on these features
28 14 Chris Cannam
 * If the plugin does set timestamps, the host _must_ ignore them
29 14 Chris Cannam
 * The host _must_ treat all such features returned from a given @process@ call as if they had the same timestamp as it passed to that @process@ call
30 16 Chris Cannam
 * The host _must_ treat all such features returned from @getRemainingFeatures@ as if they were immediately following the final @process@ block (i.e. with the same time as the next equally-spaced @process@ block would have had if the input had not ended).
31 14 Chris Cannam
32 14 Chris Cannam
h4. Examples
33 14 Chris Cannam
34 14 Chris Cannam
@OneSamplePerStep@ type is most often used for simple measurements and visualisations, in which an output is updated on each process call and a new result returned. For example, envelope trackers, power calculations, spectrograms.
35 14 Chris Cannam
36 14 Chris Cannam
@OneSamplePerStep@ is often used for intermediate results calculated during processing of a more sophisticated feature. For example, a beat tracker might have an auxiliary output with @OneSamplePerStep@ type returning its internal onset detection function value.