SampleType » History » Version 21

Chris Cannam, 2014-02-10 01:42 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 18 Chris Cannam
A feature may or may not have a timestamp (as well as, optionally, a duration). Whether a timestamp is needed -- 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 19 Chris Cannam
 * The plugin _should not_ set timestamps on these features;
28 19 Chris Cannam
 * The plugin _should not_ set durations on these features;
29 19 Chris Cannam
 * If the plugin does set timestamps or durations, the host _must_ ignore them;
30 19 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;
31 19 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);
32 19 Chris Cannam
 * The host _must_ treat all such features has having duration equal to the spacing between process blocks.
33 14 Chris Cannam
34 14 Chris Cannam
h4. Examples
35 14 Chris Cannam
36 17 Chris Cannam
@OneSamplePerStep@ is most often used for simple measurements and visualisations, in which some internal calculation is updated on each process call and a new result returned. For example: envelope trackers; power calculations; spectrograms. These outputs are typically visualised using line graphs or colour matrix plots.
37 14 Chris Cannam
38 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.
39 20 Chris Cannam
40 20 Chris Cannam
h3. VariableSampleRate
41 20 Chris Cannam
42 21 Chris Cannam
If the @OneSamplePerStep@ output type essentially means that the plugin leaves all time calculations up to the host, @VariableSampleRate@ is the opposite.
43 21 Chris Cannam
44 21 Chris Cannam
If an output is declared as having a @SampleType@ of @VariableSampleRate@, that means all of the features returned through it will have timestamps set by the plugin, and they won't necessarily have any relationship to the process block timestamps provided by the host.
45 21 Chris Cannam
46 21 Chris Cannam
47 20 Chris Cannam
48 20 Chris Cannam
h3. FixedSampleRate
49 20 Chris Cannam
50 20 Chris Cannam
If an output is declared as having a @SampleType@ of @FixedSampleRate@