SampleType » History » Version 27
Version 26 (Chris Cannam, 2014-02-10 02:28 PM) → Version 27/72 (Chris Cannam, 2014-02-10 02:29 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 output on which the feature is returned.
An h2. SampleType
A plugin output's @sampleType@ property may be either @OneSamplePerStep@, @FixedSampleRate@, or @VariableSampleRate@. Here's what they mean.
h2. 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.
The @sampleRate@ and @hasDuration@ output properties are ignored for outputs of this type.
h4. What this means
For any features returned through an output declared with @OneSamplePerStep@ type,
* The plugin _should not_ set timestamps on these features and _should_ set their @hasTimestamp@ property to @false@;
* The plugin _should not_ set durations on these features and _should_ set their @hasDuration@ property to @false@;
* If the plugin does set either 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.
h3. 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.
h2. h3. VariableSampleRate
If the @OneSamplePerStep@ output type essentially means that the plugin leaves all time calculations up to the host, @VariableSampleRate@ is the opposite.
If an output is declared as having a @SampleType@ of @VariableSampleRate@, 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.
h4. What this means
h3. h5. Timestamps
For any features returned through an output declared with @VariableSampleRate@ type,
* The plugin _must_ set timestamps on these features and _must_ set their @hasTimestamp@ property to @true@;
* The host _must_ use the timestamps of such features as indicating their start times, independent of process block timing;
h3.
h5. Durations
Features returned through @VariableSampleRate@ outputs may optionally have durations.
If the output's @hasDuration@ property is @true@, then
* The plugin _may_ set the @hasDuration@ property of such features to @true@ and, if it does so, _must_ also set their durations;
* If a feature's @hasDuration@ property is true, then the host _must_ use the feature's duration rather than treating it as a point value.
If the output's @hasDuration@ property is @false@, then the host _must_ ignore the @hasDuration@ and @duration@ properties of the features and treat them as point values instead.
h3.
h4. Examples
h2. h3. FixedSampleRate
If an output is declared as having a @SampleType@ of @FixedSampleRate@
h3. h4. What this means
h4. Examples
{{>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 output on which the feature is returned.
An h2. SampleType
A plugin output's @sampleType@ property may be either @OneSamplePerStep@, @FixedSampleRate@, or @VariableSampleRate@. Here's what they mean.
h2. 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.
The @sampleRate@ and @hasDuration@ output properties are ignored for outputs of this type.
h4. What this means
For any features returned through an output declared with @OneSamplePerStep@ type,
* The plugin _should not_ set timestamps on these features and _should_ set their @hasTimestamp@ property to @false@;
* The plugin _should not_ set durations on these features and _should_ set their @hasDuration@ property to @false@;
* If the plugin does set either 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.
h3. 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.
h2. h3. VariableSampleRate
If the @OneSamplePerStep@ output type essentially means that the plugin leaves all time calculations up to the host, @VariableSampleRate@ is the opposite.
If an output is declared as having a @SampleType@ of @VariableSampleRate@, 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.
h4. What this means
h3. h5. Timestamps
For any features returned through an output declared with @VariableSampleRate@ type,
* The plugin _must_ set timestamps on these features and _must_ set their @hasTimestamp@ property to @true@;
* The host _must_ use the timestamps of such features as indicating their start times, independent of process block timing;
h3.
h5. Durations
Features returned through @VariableSampleRate@ outputs may optionally have durations.
If the output's @hasDuration@ property is @true@, then
* The plugin _may_ set the @hasDuration@ property of such features to @true@ and, if it does so, _must_ also set their durations;
* If a feature's @hasDuration@ property is true, then the host _must_ use the feature's duration rather than treating it as a point value.
If the output's @hasDuration@ property is @false@, then the host _must_ ignore the @hasDuration@ and @duration@ properties of the features and treat them as point values instead.
h3.
h4. Examples
h2. h3. FixedSampleRate
If an output is declared as having a @SampleType@ of @FixedSampleRate@
h3. h4. What this means
h4. Examples