Vamp Plugin SDK

h1. Output Sample Type and Sample Rate

{{>toc}}

h2. Who should read this document

This is a detailed document about the "sample type" and "sample rate" properties of a Vamp plugin's output descriptor.

 * If you are new to the Vamp plugin API, read the "Programmer's Guide":http://vamp-plugins.org/guide.pdf first. The section "Sample Types and Timestamps" starting on page 9 introduces this subject.

 * If you are writing a plugin, read the "Rules of Thumb" section (below) after the Programmer's Guide. You probably won't need to read the rest of this document. You should use the "Vamp Plugin Tester":/projects/vamp-plugin-tester to test your plugin.

 * If you are writing a host, you should probably read the whole of this as well as the Guide. You should also use the "Vamp Test Plugin":/projects/vamp-test-plugin to test your host's interpretation of the feature structures.

h2. Rules of Thumb for Plugin Developers

The tl;dr summary:

 * If your output returns things that are always regularly-spaced in time, and there is one such thing returned for every @process@ block, and the calculation is causal so that results are available immediately, and there is no latency added beyond the length of the processing block, then you probably want to use @OneSamplePerStep@ sample type and omit the feature timestamps.

 * If your output returns things that are regularly-spaced in time but the other limitations above are not true, use @FixedSampleRate@ sample type, set the output sample rate to the (perhaps fractional) number of returned features per second, and use a timestamp for each feature.

 * If your output returns anything else, use @VariableSampleRate@ sample type, set the output sample rate to zero unless you know better, and use a timestamp for each feature.

h2. Introduction

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 output's @sampleType@ property may be either @OneSamplePerStep@, @FixedSampleRate@, or @VariableSampleRate@. Here's what they mean.

h2. 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.

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@;

 * The host _must_ ignore any timestamps or durations that the plugin may set on these features;

 * 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. 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. 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.

h3. 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_ obtain the features' start times from their timestamps rather than calculating them itself.

h3. 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 @duration@ property;

 * If a feature's @hasDuration@ property is true, then the host _must_ use the feature's @duration@ property as the feature duration; otherwise the host _must_ treat the feature as having "minimal" duration (see "Sample Rate" below).

If the output's @hasDuration@ property is @false@, then

 * The plugin _should not_ set the @duration@ property of that output's features;

 * The host _must_ ignore the @hasDuration@ and @duration@ properties of the features, and treat them as having "minimal" duration (see below).

h3. Sample rate and "minimal" duration

The plugin may optionally set a @sampleRate@ property for each @VariableSampleRate@ output. A @sampleRate@ of zero indicates no value.

If a @sampleRate@ is set,

 * The host _must_ use 1/@sampleRate@ seconds as the "minimal" duration assigned to features that have no duration supplied.

If no @sampleRate@ is set, i.e. if the @sampleRate@ property is zero,

 * The host _must_ use zero as the "minimal" duration used for features with no duration supplied.

h2. FixedSampleRate

This is a more complex case than @OneSamplePerStep@ or @VariableSampleRate@.

There are two use cases for @FixedSampleRate@:

 # Essentially the same as @VariableSampleRate@, but with limitations on the timings available. The features have timestamps, but they are all "snapped to a grid" defined by the sample rate 

According to the Vamp Plugin Programmers' Guide, "The host may round the timestamp according to the sample rate given in the output descriptor's sampleRate field". In my view this is the right thing for a host to do, although it's technically optional. The guide doesn't say whether timestamps should be rounded down or to the closest sample; this plugin assumes rounding to the closest sample. It also isn't clear whether a half-way point should round down or up; I would expect up.

If an output is declared as having a @SampleType@ of @FixedSampleRate@

h3. Examples