SampleType » History » Version 20
Version 19 (Chris Cannam, 2014-02-10 01:37 PM) → Version 20/72 (Chris Cannam, 2014-02-10 01:39 PM)
h1. Output Sample Type and Sample Rate
{{>toc}}
A Vamp plugin receives audio and produces a series of descriptive feature structures.
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.
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.)
!/attachments/download/980/feature-structures-20pc.png!
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.
h2. SampleType
A plugin output's @SampleType@ property may be either @OneSamplePerStep@, @FixedSampleRate@, or @VariableSampleRate@. Here's what they mean.
h3. OneSamplePerStep
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.
h4. What this means
For any features returned through an output declared with @OneSamplePerStep@ type,
* The plugin _should not_ set timestamps on these features;
* The plugin _should not_ set durations on these features;
* If the plugin does set timestamps or durations, the host _must_ ignore them;
* 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;
* 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);
* The host _must_ treat all such features has having duration equal to the spacing between process blocks.
h4. Examples
@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.
@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.
h3. VariableSampleRate
If an output is declared as having a @SampleType@ of @VariableSampleRate@
h3. FixedSampleRate
If an output is declared as having a @SampleType@ of @FixedSampleRate@
{{>toc}}
A Vamp plugin receives audio and produces a series of descriptive feature structures.
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.
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.)
!/attachments/download/980/feature-structures-20pc.png!
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.
h2. SampleType
A plugin output's @SampleType@ property may be either @OneSamplePerStep@, @FixedSampleRate@, or @VariableSampleRate@. Here's what they mean.
h3. OneSamplePerStep
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.
h4. What this means
For any features returned through an output declared with @OneSamplePerStep@ type,
* The plugin _should not_ set timestamps on these features;
* The plugin _should not_ set durations on these features;
* If the plugin does set timestamps or durations, the host _must_ ignore them;
* 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;
* 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);
* The host _must_ treat all such features has having duration equal to the spacing between process blocks.
h4. Examples
@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.
@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.
h3. VariableSampleRate
If an output is declared as having a @SampleType@ of @VariableSampleRate@
h3. FixedSampleRate
If an output is declared as having a @SampleType@ of @FixedSampleRate@