Chris@117: Chris@117: Python Vamp plugin host Chris@117: ======================= Chris@117: Chris@126: This module allows Python code to load and use native-code Vamp Chris@126: plugins (http://vamp-plugins.org) for audio feature analysis. Chris@117: Chris@126: The module consists of a native-code extension ("vampyhost") that Chris@126: provides a low-level wrapper for the Vamp plugin SDK, along with a Chris@126: Python wrapper ("vamp") that provides a higher-level abstraction. Chris@117: Chris@126: No code for loading audio files is included; you'll need to use some Chris@126: other module for that. This code expects to receive decoded audio data Chris@126: of one or more channels, either as a series of frames or as a single Chris@126: whole buffer. Chris@117: Chris@123: Written by Chris Cannam and George Fazekas at the Centre for Digital Chris@123: Music, Queen Mary University of London. Copyright 2008-2015 Queen Chris@123: Mary, University of London. Refer to COPYING.rst for licence details. Chris@123: Chris@123: See home page at https://code.soundsoftware.ac.uk/projects/vampy-host Chris@123: for more details. Chris@123: Chris@117: Chris@117: A simple example Chris@117: ---------------- Chris@117: Chris@126: Using librosa (http://bmcfee.github.io/librosa/) to read an audio Chris@126: file, and the NNLS Chroma Vamp plugin Chris@126: (https://code.soundsoftware.ac.uk/projects/nnls-chroma/) for Chris@126: analysis:: Chris@117: Chris@123: >>> import vamp Chris@123: >>> import librosa Chris@123: >>> data, rate = librosa.load("example.wav") Chris@126: >>> chroma = vamp.collect(data, rate, "nnls-chroma:nnls-chroma") Chris@126: >>> chroma Chris@123: {'matrix': ( 0.092879819, array([[ 61.0532608 , 60.27478409, 59.3938446 , ..., 182.13394165, Chris@123: 42.40084457, 116.55457306], Chris@123: [ 68.8901825 , 63.98115921, 60.77633667, ..., 245.88218689, Chris@123: 68.51251984, 164.70120239], Chris@123: [ 58.59794617, 50.3429184 , 45.44804764, ..., 258.02362061, Chris@123: 83.95749664, 179.91200256], Chris@123: ..., Chris@123: [ 0. , 0. , 0. , ..., 0. , Chris@123: 0. , 0. ], Chris@123: [ 0. , 0. , 0. , ..., 0. , Chris@123: 0. , 0. ], Chris@123: [ 0. , 0. , 0. , ..., 0. , Chris@123: 0. , 0. ]], dtype=float32))} Chris@126: >>> stepsize, chromadata = chroma["matrix"] Chris@123: >>> import matplotlib.pyplot as plt Chris@123: >>> plt.imshow(chromadata) Chris@123: Chris@123: >>> plt.show() Chris@117: Chris@126: And a pitch-chroma plot appears. Chris@117: Chris@126: Chris@126: High-level interface (vamp) Chris@126: --------------------------- Chris@126: Chris@126: This module contains three sorts of function: Chris@126: Chris@132: 1. Basic info and lookup functions Chris@132: """""""""""""""""""""""""""""""""" Chris@126: Chris@129: * ``vamp.list_plugins`` Chris@129: * ``vamp.get_outputs_of`` Chris@129: * ``vamp.get_category_of`` Chris@126: Chris@129: These retrieve the installed plugin keys and get basic information Chris@129: about each plugin. (For more detailed information, load a plugin Chris@129: and inspect it using the low-level interface described below.) Chris@129: Chris@132: 2. Process functions Chris@132: """""""""""""""""""" Chris@129: Chris@129: * ``vamp.process_audio`` Chris@129: * ``vamp.process_frames`` Chris@129: * ``vamp.process_audio_multiple_outputs`` Chris@129: * ``vamp.process_frames_multiple_outputs`` Chris@126: Chris@126: These accept audio input, and produce output in the form of a list Chris@126: of feature sets structured similarly to those in the C++ Vamp Chris@129: plugin SDK. The plugin to be used is specified by its key (the Chris@129: identifier as returned by ``vamp.list_plugins``). A dictionary of Chris@129: plugin parameter settings may optionally be supplied. Chris@126: Chris@126: The ``_audio`` versions take a single (presumably long) array of Chris@126: audio samples as input, and chop it into frames according to the Chris@126: plugin's preferred step and block sizes. The ``_frames`` versions Chris@126: instead accept an enumerable sequence of audio frame arrays. Chris@126: Chris@132: 3. The process-and-collect function Chris@132: """"""""""""""""""""""""""""""""""" Chris@132: Chris@129: * ``vamp.collect`` Chris@126: Chris@126: This accepts a single array of audio samples as input, and returns Chris@126: an output structure that reflects the underlying structure of the Chris@126: feature output (depending on whether it is a curve, grid, etc). The Chris@129: plugin to be used is specified by its key. A dictionary of plugin Chris@129: parameter settings may optionally be supplied. Chris@126: Chris@126: The ``collect`` function processes the whole input before returning Chris@126: anything; if you need to supply a streamed input, or retrieve Chris@126: results as they are calculated, then you must use one of the Chris@126: ``process`` functions (above) or else the low-level interface Chris@126: (below). Chris@126: Chris@126: Chris@126: Low-level interface (vampyhost) Chris@126: ------------------------------- Chris@126: Chris@126: This extension contains facilities that operate on Vamp plugins in a Chris@126: way analogous to the existing C++ Vamp Host SDK: ``list_plugins``, Chris@126: ``get_plugin_path``, ``get_category_of``, ``get_library_for``, Chris@126: ``get_outputs_of``, ``load_plugin``, and a utility function Chris@126: ``frame_to_realtime``. Chris@126: Chris@126: Calling ``load_plugin`` gets you a ``vampyhost.Plugin`` object, which Chris@126: then exposes all of the methods found in the Vamp SDK Plugin class. Chris@126: Chris@126: (Note that methods wrapped directly from the Vamp SDK are named using Chris@126: camelCase, so as to match the names found in the C++ SDK. Elsewhere Chris@126: this module follows Python PEP8 naming.) Chris@126: Chris@126: See the individual module and function documentation for further Chris@126: details. Chris@126: