Chris@56: '''A high-level interface to the vampyhost extension module, for quickly and easily running Vamp audio analysis plugins on audio files and buffers.'''
Chris@56: 
Chris@56: import vampyhost
Chris@56: 
Chris@79: def list_plugins():
Chris@98:     """Obtain a list of plugin keys for all currently installed Vamp plugins.
Chris@98: 
Chris@98:     The returned value is a list of strings, each of which is the key
Chris@98:     for one plugin. (Note that a plugin may have multiple outputs, if
Chris@98:     it computes more than one type of feature.)
Chris@98: 
Chris@98:     To query the available outputs and category of a plugin, you may
Chris@98:     use vamp.get_outputs_of() and vamp.get_category_of(). Further
Chris@98:     information may be retrieved by loading the plugin and querying
Chris@98:     its info dictionary using the low-level functions in the
Chris@98:     vamp.vampyhost extension module.
Chris@98: 
Chris@98:     To make use of a plugin to extract features from audio data, pass
Chris@98:     the plugin key and optionally an output identifier to
Chris@98:     vamp.process() or vamp.collect().
Chris@98:     """
Chris@79:     return vampyhost.list_plugins()
Chris@56: 
Chris@98: def get_outputs_of(key):
Chris@98:     """Obtain a list of the output identifiers for the given plugin key.
Chris@98:     """
Chris@98:     return vampyhost.get_outputs_of(key)
Chris@98: 
Chris@98: def get_category_of(key):
Chris@98:     """Obtain the category descriptor, if any, for the given plugin key.
Chris@98: 
Chris@98:     The returned value is a list of descriptor terms, from least
Chris@98:     specific to most specific. The list may be empty if no category
Chris@98:     information is found for the plugin.
Chris@98:     """
Chris@98:     return vampyhost.get_category_of(key)
Chris@98: 
Chris@84: def load_and_configure(data, sample_rate, key, parameters):
Chris@98:     """Load the plugin with the given key at a given sample rate,
Chris@98:     configure it with the parameter keys and values in the given
Chris@98:     parameter dictionary, and initialise it with its preferred step
Chris@98:     and block size. The channel count is taken from the shape of the
Chris@98:     data array provided.
Chris@98:     """
Chris@82: 
Chris@84:     plug = vampyhost.load_plugin(key, sample_rate,
Chris@82:                                  vampyhost.ADAPT_INPUT_DOMAIN +
Chris@82:                                  vampyhost.ADAPT_CHANNEL_COUNT)
Chris@64: 
Chris@80:     plug.set_parameter_values(parameters)
Chris@68: 
Chris@84:     step_size = plug.get_preferred_step_size()
Chris@84:     block_size = plug.get_preferred_block_size()
Chris@68: 
Chris@84:     if block_size == 0:
Chris@84:         block_size = 1024
Chris@84:     if step_size == 0:
Chris@84:         step_size = block_size ##!!! or block_size/2, but check this with input domain adapter
Chris@68: 
Chris@68:     channels = 1
Chris@68:     if data.ndim > 1:
Chris@68:         channels = data.shape[0]
Chris@68: 
Chris@95:     if plug.initialise(channels, step_size, block_size):
Chris@95:         return (plug, step_size, block_size)
Chris@95:     else:
Chris@95:         raise "Failed to initialise plugin"