Skip to content

Latest commit

 

History

History
49 lines (44 loc) · 3.45 KB

README.md

File metadata and controls

49 lines (44 loc) · 3.45 KB
Raw

audiopyle Build Status

audiopyle

Docker-based app extracting features from audio files (preferably, music). Makes use of standard VAMP plugins for feature extraction.

Quick start

To start the app, follow these steps:

  • make sure directories with music files (.mp3, .flac formats) and VAMP plugins (.so files in case of Linux) are mapped correctly in scripts/docker-compose.yml under sections:
    • api/volumes
    • worker/volumes
  • do make run from the directory with Makefile
  • docker should pull the audiopyle images now
  • there's simple UI available on port at http://localhost:8008/

App REST API description

YOu can use REST API of an app that is available at http://localhost:8080/ Hosted audiopyle API documentation is available from GitHub Pages Alternative way is to paste open_api_docs.yml (OpenAPI / Swagger 2.0 compliant spec) file contents into Swagger editor

How it works (mental model)

  • Extraction takes as input:
    • filename of an audio file (those are listed in /audio endpoint)
    • VAMP plugin full key - including plugin output (those are listen under /plugin endpoint)
    • optional: VAMP plugin config (if empty, defaults from /config/plugin for this plugin will be used)
    • optional: Metric config (if empty, defaults from /config/metric for this plugin will be used)
  • Extraction outputs:
    • id3tag of an audio file, if included in the file
    • raw feature data; might be 1-, 2- or 3-dimensional; in constant or variable step format; see see VAMP docs for details
    • Metric values, if included in the request
  • What is Metric?
    • Metric value is a bunch of statistics (mean, min, max, sum, variance etc.) over a vector of data selected from raw feature
    • Metric definition is a description of how to calculate vector mentioned above from raw feature data
    • Default metric definitions are defined in audiopyle/scripts/resources/config/metric.json
    • Example: bbc_intensity_lo_bass
      • it's a Metric telling about sub-bass intensity of the track
      • Metric value is calculated from raw feature data produced by bbc-vamp-plugins:bbc-intensity:intensity-ratio VAMP plugin output
      • the input vector is a first row of a 3-dimensional raw feature produced by the VAMP plugin output
      • standards statistics functions are applied over the vector, producing Metric value
  • Automated extraction
    • /request/automation endpoint is triggered by empty POST request (see OpenAPI documentation for details)
    • the API creates Cartesian product of all available audio files and all available VAMP plugins excluding those blacklisted (/config/blacklist endpoint, audiopyle/scripts/resources/config/blacklist.json file))
    • plugin config and metric config are taken from their respective /config endpoints
    • all the requests are queued for execution, API responds with UUIDs (task_id) for each generated request

Building from source

To build Docker images, follow these steps:

  • do one-time setup: make config
  • then, to trigger full-build and test procedure, do make all
  • take a look at Makefile to see what build steps are doing