Chris@117: #!/usr/bin/env python Chris@117: Chris@117: # Python Vamp Host Chris@117: # Copyright (c) 2008-2015 Queen Mary, University of London Chris@117: # Chris@117: # Permission is hereby granted, free of charge, to any person Chris@117: # obtaining a copy of this software and associated documentation Chris@117: # files (the "Software"), to deal in the Software without Chris@117: # restriction, including without limitation the rights to use, copy, Chris@117: # modify, merge, publish, distribute, sublicense, and/or sell copies Chris@117: # of the Software, and to permit persons to whom the Software is Chris@117: # furnished to do so, subject to the following conditions: Chris@117: # Chris@117: # The above copyright notice and this permission notice shall be Chris@117: # included in all copies or substantial portions of the Software. Chris@117: # Chris@117: # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, Chris@117: # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF Chris@117: # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND Chris@117: # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY Chris@117: # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF Chris@117: # CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION Chris@117: # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Chris@117: # Chris@117: # Except as contained in this notice, the names of the Centre for Chris@117: # Digital Music and Queen Mary, University of London shall not be Chris@117: # used in advertising or otherwise to promote the sale, use or other Chris@117: # dealings in this Software without prior written authorization. Chris@117: Chris@129: ''' Chris@129: Python Vamp plugin host Chris@129: ======================= Chris@129: Chris@129: This module allows Python code to load and use native-code Vamp Chris@129: plugins (http://vamp-plugins.org) for audio feature analysis. Chris@129: Chris@129: The module consists of a native-code extension ("vampyhost") that Chris@129: provides a low-level wrapper for the Vamp plugin SDK, along with a Chris@129: Python wrapper ("vamp") that provides a higher-level abstraction. Chris@129: Chris@129: No code for loading audio files is included; you'll need to use some Chris@129: other module for that. This code expects to receive decoded audio data Chris@129: of one or more channels, either as a series of frames or as a single Chris@129: whole buffer. Chris@129: Chris@129: Written by Chris Cannam and George Fazekas at the Centre for Digital Chris@129: Music, Queen Mary University of London. Copyright 2008-2015 Queen Chris@129: Mary, University of London. Refer to COPYING.rst for licence details. Chris@129: Chris@129: See home page at https://code.soundsoftware.ac.uk/projects/vampy-host Chris@129: for more details. Chris@129: Chris@129: Chris@129: A simple example Chris@129: ---------------- Chris@129: Chris@129: Using librosa (http://bmcfee.github.io/librosa/) to read an audio Chris@129: file, and the NNLS Chroma Vamp plugin Chris@129: (https://code.soundsoftware.ac.uk/projects/nnls-chroma/) for Chris@129: analysis:: Chris@129: Chris@129: >>> import vamp Chris@129: >>> import librosa Chris@129: >>> data, rate = librosa.load("example.wav") Chris@129: >>> chroma = vamp.collect(data, rate, "nnls-chroma:nnls-chroma") Chris@129: >>> chroma Chris@129: {'matrix': ( 0.092879819, array([[ 61.0532608 , 60.27478409, 59.3938446 , ..., 182.13394165, Chris@129: 42.40084457, 116.55457306], Chris@129: [ 68.8901825 , 63.98115921, 60.77633667, ..., 245.88218689, Chris@129: 68.51251984, 164.70120239], Chris@129: [ 58.59794617, 50.3429184 , 45.44804764, ..., 258.02362061, Chris@129: 83.95749664, 179.91200256], Chris@129: ..., Chris@129: [ 0. , 0. , 0. , ..., 0. , Chris@129: 0. , 0. ], Chris@129: [ 0. , 0. , 0. , ..., 0. , Chris@129: 0. , 0. ], Chris@129: [ 0. , 0. , 0. , ..., 0. , Chris@129: 0. , 0. ]], dtype=float32))} Chris@129: >>> stepsize, chromadata = chroma["matrix"] Chris@129: >>> import matplotlib.pyplot as plt Chris@129: >>> plt.imshow(chromadata) Chris@129: Chris@129: >>> plt.show() Chris@129: Chris@129: And a pitch-chroma plot appears. Chris@129: Chris@129: Chris@129: High-level interface (vamp) Chris@129: --------------------------- Chris@129: Chris@129: This module contains three sorts of function: Chris@129: Chris@132: 1. Basic info and lookup functions Chris@132: """""""""""""""""""""""""""""""""" Chris@129: Chris@129: * ``vamp.list_plugins`` Chris@129: * ``vamp.get_outputs_of`` Chris@144: * ``vamp.get_parameters_of`` Chris@129: * ``vamp.get_category_of`` Chris@129: 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@129: Chris@129: These accept audio input, and produce output in the form of a list Chris@129: 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@129: Chris@129: The ``_audio`` versions take a single (presumably long) array of Chris@129: audio samples as input, and chop it into frames according to the Chris@129: plugin's preferred step and block sizes. The ``_frames`` versions Chris@129: instead accept an enumerable sequence of audio frame arrays. Chris@129: Chris@132: 3. The process-and-collect function Chris@132: """"""""""""""""""""""""""""""""""" Chris@132: Chris@129: * ``vamp.collect`` Chris@129: Chris@129: This accepts a single array of audio samples as input, and returns Chris@129: an output structure that reflects the underlying structure of the Chris@129: 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@129: Chris@129: The ``collect`` function processes the whole input before returning Chris@129: anything; if you need to supply a streamed input, or retrieve Chris@129: results as they are calculated, then you must use one of the Chris@129: ``process`` functions (above) or else the low-level interface Chris@129: (below). Chris@129: Chris@129: Chris@129: Low-level interface (vampyhost) Chris@129: ------------------------------- Chris@129: Chris@129: This extension contains facilities that operate on Vamp plugins in a Chris@129: way analogous to the existing C++ Vamp Host SDK: ``list_plugins``, Chris@129: ``get_plugin_path``, ``get_category_of``, ``get_library_for``, Chris@129: ``get_outputs_of``, ``load_plugin``, and a utility function Chris@129: ``frame_to_realtime``. Chris@129: Chris@129: Calling ``load_plugin`` gets you a ``vampyhost.Plugin`` object, which Chris@129: then exposes all of the methods found in the Vamp SDK Plugin class. Chris@129: Chris@129: (Note that methods wrapped directly from the Vamp SDK are named using Chris@129: camelCase, so as to match the names found in the C++ SDK. Elsewhere Chris@129: this module follows Python PEP8 naming.) Chris@129: Chris@129: See the individual module and function documentation for further Chris@129: details. Chris@129: Chris@124: ''' Chris@56: Chris@75: import vampyhost Chris@68: Chris@144: from vamp.load import list_plugins, get_outputs_of, get_parameters_of, get_category_of Chris@117: from vamp.process import process_audio, process_frames, process_audio_multiple_outputs, process_frames_multiple_outputs Chris@112: from vamp.collect import collect Chris@95: