|
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||
org.vamp_plugins
Class Plugin
java.lang.Objectorg.vamp_plugins.Plugin
public class Plugin
- extends java.lang.Object
A Java wrapper for a native-code Vamp plugin. Plugins are obtained using PluginLoader and must be freed by calling dispose() after use (being native code they cannot be garbage collected). The plugin lifecycle looks roughly like this, from the host's perspective: - Plugin is loaded using PluginLoader - Host may query the plugin's available outputs with getOutputDescriptors(). This will report what outputs exist, but their properties (e.g. resolution, value count, extents) are not yet fixed - Host may query and set the plugin's programs and parameters with getPrograms(), getParameterDescriptors(), setParameter() etc - After all parameters are set, host queries the plugin's preferred step size, block size, and channel count (which may depend on the parameter settings) - Host initialises plugin by calling initialise(). If it returns false, initialise failed -- most likely because the step size, block size, or channel count was rejected - Host may now get final values for the output properties using getOutputDescriptors() - Host calls process() repeatedly to process data. This may return some results as it goes along (if the plugin is causal) - Host calls getRemainingFeatures() exactly once when all input has been processed, to obtain any non-causal or leftover features. - At any point after initialise() has been called, host may call reset() to restart processing. Parameter values remain fixed across reset() calls. - When host is finished with plugin, it calls dispose(). The host may not change any parameter or program settings after calling initialise(), and may not call initialise() more than once on any given plugin. See the PluginBase and Plugin classes in the C++ Vamp plugin SDK for further documentation.
| Nested Class Summary | |
|---|---|
static class |
Plugin.InputDomain
|
| Constructor Summary | |
|---|---|
protected |
Plugin(long handle)
|
| Method Summary | |
|---|---|
void |
dispose()
Dispose of this Plugin. |
java.lang.String |
getCopyright()
Get the copyright statement or licensing summary for the plugin. |
java.lang.String |
getCurrentProgram()
Get the current program (if any). |
java.lang.String |
getDescription()
Get a human-readable description for the plugin, typically a line of text that may optionally be displayed in addition to the plugin's "name". |
java.lang.String |
getIdentifier()
Get the computer-usable name of the plugin. |
Plugin.InputDomain |
getInputDomain()
Get the plugin's required input domain. |
java.lang.String |
getMaker()
Get the name of the author or vendor of the plugin in human-readable form. |
int |
getMaxChannelCount()
Get the maximum supported number of input channels. |
int |
getMinChannelCount()
Get the minimum supported number of input channels. |
java.lang.String |
getName()
Get a human-readable name or title of the plugin. |
OutputDescriptor[] |
getOutputDescriptors()
Get the outputs of this plugin. |
float |
getParameter(java.lang.String identifier)
Get the value of a named parameter. |
ParameterDescriptor[] |
getParameterDescriptors()
Get the controllable parameters of this plugin. |
int |
getPluginVersion()
Get the version number of the plugin. |
int |
getPreferredBlockSize()
Get the preferred block size (window size -- the number of sample frames passed in each block to the process() function). |
int |
getPreferredStepSize()
Get the preferred step size (window increment -- the distance in sample frames between the start frames of consecutive blocks passed to the process() function) for the plugin. |
java.lang.String[] |
getPrograms()
Get the program settings available in this plugin. |
java.util.Map<java.lang.Integer,java.util.List<Feature>> |
getRemainingFeatures()
After all blocks have been processed, calculate and return any remaining features derived from the complete input. |
int |
getVampApiVersion()
Get the Vamp API compatibility level of the plugin. |
boolean |
initialise(int inputChannels,
int stepSize,
int blockSize)
Initialise a plugin to prepare it for use with the given number of input channels, step size (window increment, in sample frames) and block size (window size, in sample frames). |
java.util.Map<java.lang.Integer,java.util.List<Feature>> |
process(float[][] inputBuffers,
int offset,
RealTime timestamp)
As process() above, but taking input data starting at the given offset from within each of the channel arrays. |
java.util.Map<java.lang.Integer,java.util.List<Feature>> |
process(float[][] inputBuffers,
RealTime timestamp)
Process a single block of input data. |
void |
reset()
Reset the plugin after use, to prepare it for another clean run. |
void |
selectProgram(java.lang.String program)
Select a program. |
void |
setParameter(java.lang.String identifier,
float value)
Set a named parameter. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
Plugin
protected Plugin(long handle)
| Method Detail |
|---|
dispose
public void dispose()
- Dispose of this Plugin. Call this when you have finished using
it to ensure the native code object is released.
getVampApiVersion
public int getVampApiVersion()
- Get the Vamp API compatibility level of the plugin.
getIdentifier
public java.lang.String getIdentifier()
- Get the computer-usable name of the plugin. This will contain
only the characters [a-zA-Z0-9_-]. This is the authoritative
way for a host to identify a plugin within a given library, but
it is not the primary label shown to the user (that will be the
name, below).
getName
public java.lang.String getName()
- Get a human-readable name or title of the plugin. This is the
main identifying label shown to the user.
getDescription
public java.lang.String getDescription()
- Get a human-readable description for the plugin, typically
a line of text that may optionally be displayed in addition
to the plugin's "name". May be empty if the name has said
it all already.
getMaker
public java.lang.String getMaker()
- Get the name of the author or vendor of the plugin in
human-readable form. This should be short enough to be used to
label plugins from the same source in a tree or menu if
appropriate.
getCopyright
public java.lang.String getCopyright()
- Get the copyright statement or licensing summary for the
plugin.
getPluginVersion
public int getPluginVersion()
- Get the version number of the plugin.
getParameterDescriptors
public ParameterDescriptor[] getParameterDescriptors()
- Get the controllable parameters of this plugin.
getParameter
public float getParameter(java.lang.String identifier)
- Get the value of a named parameter. The argument is the identifier
field from that parameter's descriptor.
setParameter
public void setParameter(java.lang.String identifier,
float value)
- Set a named parameter. The first argument is the identifier field
from that parameter's descriptor.
getPrograms
public java.lang.String[] getPrograms()
- Get the program settings available in this plugin. A program
is a named shorthand for a set of parameter values; changing
the program may cause the plugin to alter the values of its
published parameters (and/or non-public internal processing
parameters). The host should re-read the plugin's parameter
values after setting a new program.
The programs must have unique names.
getCurrentProgram
public java.lang.String getCurrentProgram()
- Get the current program (if any).
selectProgram
public void selectProgram(java.lang.String program)
- Select a program. (If the given program name is not one of the
available programs, do nothing.)
initialise
public boolean initialise(int inputChannels,
int stepSize,
int blockSize)
- Initialise a plugin to prepare it for use with the given number
of input channels, step size (window increment, in sample
frames) and block size (window size, in sample frames).
The input sample rate should have been already specified when
loading the plugin.
Return true for successful initialisation, false if the number
of input channels, step size and/or block size cannot be
supported.
reset
public void reset()
- Reset the plugin after use, to prepare it for another clean
run.
getInputDomain
public Plugin.InputDomain getInputDomain()
- Get the plugin's required input domain.
If this is TimeDomain, the samples provided to the process()
function (below) must be in the time domain, as for a
traditional audio processing plugin.
If this is FrequencyDomain, the host must carry out a windowed
FFT of size equal to the negotiated block size on the data
before passing the frequency bin data in to process(). The
input data for the FFT will be rotated so as to place the
origin in the centre of the block. The plugin does not get to
choose the window type -- the host will either let the user do
so, or will use a Hanning window.
getPreferredBlockSize
public int getPreferredBlockSize()
- Get the preferred block size (window size -- the number of
sample frames passed in each block to the process() function).
This should be called before initialise().
A plugin that can handle any block size may return 0. The
final block size will be set in the initialise() call.
getPreferredStepSize
public int getPreferredStepSize()
- Get the preferred step size (window increment -- the distance
in sample frames between the start frames of consecutive blocks
passed to the process() function) for the plugin. This should
be called before initialise().
A plugin may return 0 if it has no particular interest in the
step size. In this case, the host should make the step size
equal to the block size if the plugin is accepting input in the
time domain. If the plugin is accepting input in the frequency
domain, the host may use any step size. The final step size
will be set in the initialise() call.
getMinChannelCount
public int getMinChannelCount()
- Get the minimum supported number of input channels.
getMaxChannelCount
public int getMaxChannelCount()
- Get the maximum supported number of input channels.
getOutputDescriptors
public OutputDescriptor[] getOutputDescriptors()
- Get the outputs of this plugin. An output's index in this list
is used as its numeric index when looking it up in the
FeatureSet returned from the process() call.
process
public java.util.Map<java.lang.Integer,java.util.List<Feature>> process(float[][] inputBuffers, RealTime timestamp)
- Process a single block of input data.
If the plugin's inputDomain is TimeDomain, inputBuffers must
contain one array of floats per input channel, and each of
these arrays will contain blockSize consecutive audio samples
(the host will zero-pad as necessary). The timestamp in this
case will be the real time in seconds of the start of the
supplied block of samples.
If the plugin's inputDomain is FrequencyDomain, inputBuffers
must contain one array of floats per input channel, and each of
these arrays will contain blockSize/2+1 consecutive pairs of
real and imaginary component floats corresponding to bins
0..(blockSize/2) of the FFT output. That is, bin 0 (the first
pair of floats) contains the DC output, up to bin blockSize/2
which contains the Nyquist-frequency output. There will
therefore be blockSize+2 floats per channel in total. The
timestamp will be the real time in seconds of the centre of the
FFT input window (i.e. the very first block passed to process
might contain the FFT of half a block of zero samples and the
first half-block of the actual data, with a timestamp of zero).
Return any features that have become available after this
process call. (These do not necessarily have to fall within
the process block, except for OneSamplePerStep outputs.)
process
public java.util.Map<java.lang.Integer,java.util.List<Feature>> process(float[][] inputBuffers, int offset, RealTime timestamp)
- As process() above, but taking input data starting at the given
offset from within each of the channel arrays. Provided to
avoid potentially having to extract a set of sub-arrays from
longer arrays (fiddly in Java).
getRemainingFeatures
public java.util.Map<java.lang.Integer,java.util.List<Feature>> getRemainingFeatures()
- After all blocks have been processed, calculate and return any
remaining features derived from the complete input.
|
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||