Skip to main content

Harmonizes your audio media: converts, normalizes, enriches and validates.

Project description


PyPI version PyPI - Python Version

This library helps you to convert, normalize, enrich and validate your music library. It fullfills the need we have at to harmonize the music library of our webradio.

The library comes shipped with a CLI tools which allow you to process audio files in a directory to create normalized mp3 versions of all files, enrich their metadata from various sources (Discogs, Spotify).

What it does

  • Audio conversion: Converts FLAC, MP3, AAC (m4a) to MP3 (128k, 192k, 320k).
  • Audio normalization: Peak normalize your input audio. Normalization is expressed in headroom ratio (0.1 means max peak will me 90% of the maximum volume).
  • Metadata extraction :
    • Audio tags: extracted from the audio and written to the JSON metadata results.
    • Audio fingerprinting: Chromaprint fingerprinting extracted from the audio and written to the JSON metadata results.
  • Metadata enrichment:
    • Use Discogs API to find the releases related to the audio track. Get your tokens here
    • Use Spotify API to find the audio track in their catalog. Get your API secrets here
  • Covert Art extraction (MP3 only) : extract the covert art to an image file.
  • Validation : run various integrity check to assert the input audio respects the rules you defined in the your config.
    • Minimum input bit rate (MP3 only)
    • Mandatory audio tags
    • Accepted input mime types


All file processing will create 2 or 3 files :

  • The mp3 converted and normalized audio version of the input audio file.
  • A metadata json file (check metadata_output.json)
  • A cover art image file if present in the original file


System dependency

OS X : $ brew install ffmpeg
Linux: $ sudo apt install ffmpeg

OS X : $ brew install libmagic
Linux: $ sudo apt install libmagic-dev

Install Chromaprint and add the executable to your path.


$ pip install harmonizer

CLI usage


  Please provide an audio_input_dir path and an audio_output_dir path to
  launch harmonization of your files.

  --json-out DIRECTORY  Path to directory to which  JSON metadata will be
                        written to.
  --img-out DIRECTORY   Path to directory to which extracted cover arts will
                        be written to.
  --help                Show this message and exit.

Config file structure

Checkout example_config.yml.


$ python test


  • Docstrings
  • More documentation
  • Better discogs search and match algorithm
  • More pipeline control through the config

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for harmonizer, version 0.1.31
Filename, size File type Python version Upload date Hashes
Filename, size harmonizer-0.1.31-py3-none-any.whl (22.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size harmonizer-0.1.31.tar.gz (21.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page