This plugin adds support for ReplayGain, a technique for normalizing audio playback levels.
This plugin can use one of four backends to compute the ReplayGain values: GStreamer, mp3gain (and its cousin, aacgain), Python Audio Tools and bs1770gain. mp3gain can be easier to install but GStreamer, Audio Tools and bs1770gain support more audio formats.
Once installed, this plugin analyzes all files during the import process. This
can be a slow process; to instead analyze after the fact, disable automatic
analysis and use the
beet replaygain command (see below).
To use GStreamer for ReplayGain analysis, you will of course need to install GStreamer and plugins for compatibility with your audio files. You will need at least GStreamer 1.0 and PyGObject 3.x (a.k.a. python-gi).
Then, enable the
replaygain plugin (see Using Plugins) and specify
the GStreamer backend by adding this to your configuration file:
replaygain: backend: gstreamer
mp3gain and aacgain¶
- On Mac OS X, you can use Homebrew. Type
brew install aacgain.
- On Linux, mp3gain is probably in your repositories. On Debian or Ubuntu,
for example, you can run
apt-get install mp3gain.
- On Windows, download and install the original mp3gain.
Then, enable the plugin (see Using Plugins) and specify the “command” backend in your configuration file:
replaygain: backend: command
If beets doesn’t automatically find the
you can configure the path explicitly like so:
replaygain: command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain
Python Audio Tools¶
This backend uses the Python Audio Tools package to compute ReplayGain for a range of different file formats. The package is not available via PyPI; it must be installed manually (only versions preceding 3.x are compatible).
On OS X, most of the dependencies can be installed with Homebrew:
brew install mpg123 mp3gain vorbisgain faad2 libvorbis
Then, enable the plugin (see Using Plugins) and specify the backend in your configuration file:
replaygain: backend: bs1770gain
For Windows users: the tool currently has issues with long and non-ASCII path names. You may want to use the asciify_paths configuration option until this is resolved.
To configure the plugin, make a
replaygain: section in your
configuration file. The available options are:
- auto: Enable ReplayGain analysis during import.
- backend: The analysis backend; either
- overwrite: Re-analyze files that already have ReplayGain tags.
- targetlevel: A number of decibels for the target loudness level. Default: 89.
- r128: A space separated list of formats that will use
R128_tags with integer values instead of the common
REPLAYGAIN_tags with floating point values. Requires the “bs1770gain” backend. Default:
These options only work with the “command” backend:
- command: The path to the
aacgainexecutable (if beets cannot find it by itself). For example:
/Applications/MacMP3Gain.app/Contents/Resources/aacgain. Default: Search in your
- noclip: Reduce the amount of ReplayGain adjustment to whatever amount
would keep clipping from occurring.
These options only works with the “bs1770gain” backend:
- method: The loudness scanning standard: either replaygain for ReplayGain 2.0, ebu for EBU R128, or atsc for ATSC A/85. This dictates the reference level: -18, -23, or -24 LUFS respectively. Default: replaygain
- chunk_at: Splits an album in groups of tracks of this amount. Usefull when running into memory problems when analysing albums with an exceptionally large amount of tracks. Default:5000
By default, the plugin will analyze all items an albums as they are implemented.
However, you can also manually analyze files that are already in your library.
beet replaygain command:
$ beet replaygain [-Waf] [QUERY]
-a flag analyzes whole albums instead of individual tracks. Provide a
query (see Queries) to indicate which items or albums to
analyze. Files that already have ReplayGain values are skipped unless
-w (write tags) or
-W (don’t write tags) to control
whether ReplayGain tags are written into the music files, or stored in the
beets database only (the default is to use the importer’s configuration).
ReplayGain analysis is not fast, so you may want to disable it during import.
auto config option to control this:
replaygain: auto: no