Skip navigation links
  • SEARCH: 
 
Package org.vamp_plugins

Class Plugin

  • java.lang.Object
    • org.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

      Nested Classes 
      Modifier and Type Class and Description
      static class  Plugin.InputDomain 

    • Constructor Summary

      Constructors 
      Modifier Constructor and Description
      protected Plugin(long handle) 

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      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.
Skip navigation links