🎚️ rgain3

ReplayGain tools and Python library

This Python package provides APIs to read, calculate and write ReplayGain usingPython as well as two scripts that utilize these APIs to apply ReplayGaininformation on audio files.

This is a Python 3 fork of Felix Krull's rgain repository on Bitbucket.

What is ReplayGain?

ReplayGain is a proposed standard published by David Robinson in 2001 to measure and normalize the perceived loudness of audio in computer audio formats such as MP3 and Ogg Vorbis. It allows media players to normalize loudness for individual tracks or albums. This avoids the common problem of having to manually adjust volume levels between tracks when playing audio files from albums that have been mastered at different loudness levels.

-- Source: Wikipedia

ReplayGain is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the perceived loudness of audio data.

-- Source: hydrogenaud.io

Requirements

• Python >= 3.6 -- http://python.org/
• GStreamer -- http://gstreamer.org/
• PyGObject -- https://pygobject.readthedocs.io/en/latest/

To install these dependencies on Debian or Ubuntu (16.10 or newer):

$ apt install \     gir1.2-gstreamer-1.0 \     gstreamer1.0-plugins-base \     gstreamer1.0-plugins-good \     gstreamer1.0-plugins-bad \     gstreamer1.0-plugins-ugly \     python3 \     python3-gi

(Or if you prefer to install the latest PyGObject from source code,replace python3-gi with libcairo2-dev libgirepository1.0-dev.)

You will also need GStreamer decoding plugins for any audio formats you want touse.

Installation

Just install it like any other Python package using pip:

$ python3 -m pip install --user rgain3

Usage

replaygain

This is a program like, say, vorbisgain or mp3gain, the differencebeing that instead of supporting a mere one format, it supports several:

• Ogg Vorbis (or probably anything you can put into an Ogg container)
• Flac
• WavPack
• MP4 (commonly using the AAC codec)
• MP3

The basic usage of the program is simple:

$ replaygain AUDIOFILE1 AUDIOFILE2 ...

There are various options; see them by running:

$ replaygain --help

collectiongain

This program is designed to apply Replay Gain to whole music collections, plusthe ability to simply add new files, run collectiongain and have itreplay-gain those files without asking twice.

To use it, simply run:

$ collectiongain PATH_TO_MUSIC

and re-run it whenever you add new files. Run:

$ collectiongain --help

to see possible options.

If, however, you want to find out how exactly collectiongain works, read on(but be warned: It's long, boring, technical, incomprehensible and awesome).collectiongain runs in two phases: The file collecting phase and the actualrun. Prior to analyzing any audio data, collectiongain gathers all audiofiles in the directory and determines a so-called album ID for each from thefile's tags:

• If the file contains a Musicbrainz album ID, that is used.

• Otherwise, if the file contains an album tag, it is joined with either

  • a MusicBrainz album artist ID, if that exists
  • an albumartist tag, if that exists,
  • or the artist tag
  • or nothing if none of the above tags exist.

  The resulting artist-album combination is the album ID for that file.

• If the file doesn't contain a Musicbrainz album ID or an album tag, it ispresumed to be a single track without album; it will only get track gain, noalbum gain.

Since this step takes a relatively long time, the album IDs are cached betweenseveral runs of collectiongain. If a file was modified or a new file wasadded, the album ID will be (re-)calculated for that file only.The program will also cache an educated guess as to whether a file was alreadyprocessed and had ReplayGain added -- if collectiongain thinks so, thatfile will totally ignored for the actual run. This flag is set whenever the fileis processed in the actual run phase (save for dry runs, which you can enablewith the --dry-run switch) and is cleared whenever a file was changed. Youcan pass the --ignore-cache switch to make collectiongain totally ignorethe cache; in that case, it will behave as if no cache was present and read yourcollection from scratch.

For the actual run, collectiongain will simply look at all files that havesurvived the cleansing described above; for files that don't contain ReplayGaininformation, collectiongain will calculate it and write it to the files (usethe --force flag to calculate gain even if the file already has gain data).Here comes the big moment of the album ID: files that have the same album ID areconsidered to be one album (duh) for the calculation of album gain. If only onefile of an album is missing gain information, the whole album will berecalculated to make sure the data is up-to-date.

MP3 formats

Proper ReplayGain support for MP3 files is a bit of a mess: on the one hand,there is the mp3gain application which was relatively widely used (Idon't know if it still is) -- it directly modifies the audio data which has theadvantage that it works with pretty much any player, but it also means you haveto decide ahead of time whether you want track gain or album gain. Besides, it'sjust not very elegant. On the other hand, there are at least two commonly usedways to store proper ReplayGain information in ID3v2 tags.

Now, in general you don't have to worry about this when using this package: bydefault, replaygain and collectiongain will read and write ReplayGaininformation in the two most commonly used formats. However, if for whateverreason you need more control over the MP3 ReplayGain information, you can usethe --mp3-format option (supported by both programs) to change thebehaviour.

Possible choices with this switch are:

Development

Fork and clone this repository. Inside the checkout create a virtualenv and install rgain3 in develop mode:

Note that developing from source requires the Python headers and therefore thepython3.x-dev system package to be installed.

$ python3 -m venv env$ source env/bin/activate(env) $ python -m pip install -Ue .

Running Tests

To run the tests with the Python version of your current virtualenv, simplyinvoke pytest installing test extras:

(env) $ python -m pip install -Ue ".[test]"(env) $ pytest

You can run tests for all supported Python version using tox like so:

(env) $ tox

Copyright

With the exception of the manpages, all files are::

• Copyright (c) 2009-2015 Felix Krull [email protected]
• Copyright (c) 2019-2020 Christian Haudum [email protected]

The manpages were originally written for the Debian project and are::

• Copyright (c) 2011 Simon Chopin [email protected]
• Copyright (c) 2012-2015 Felix Krull [email protected]