A script for adding replaygain tags to music files
Python Shell
Latest commit e1b7e5a Dec 27, 2016 @DarwinAwardWinner Declare lxml dependency in setup.py
This was always a dependency of the bs1770gain backend, but I
previously forgot to declare it.
Failed to load latest commit information.
rganalysis Put github issue URLs on same line as "type: ignore" Nov 11, 2016
scripts Add type annotations to remaining files Nov 11, 2016
README.mkdn Fix a typo Sep 11, 2016


rganalysis.py: Add Replay Gain tags to your whole music library

To use this script, simply run it on your Music library directory. The help text (rganalysis.py --help) contains (almost) all you need to know:

usage: rganalysis [-h] [-f] [-i] [-n] [-g (track|album|auto)]
                  [-b (audiotools|bs1770gain|auto)] [-j 4] [-m] [-q] [-v]
                  [music_dir [music_dir ...]]

Add replaygain tags to your music files.

positional arguments: music_dir Directories in which to search for music files.

optional arguments: -h, --help show this help message and exit -f, --force-reanalyze Reanalyze all files and recalculate replaygain values, even if the files already have valid replaygain tags. Normally, only files missing or inconsistent replaygain tags will be analyzed. -i, --include-hidden Do not skip hidden files and directories. -n, --dry-run Don't modify any files. Only analyze and report gain. -g (track|album|auto), --gain-type (track|album|auto) Can be "album", "track", or "auto". If "track", only track gain values will be calculated, and album gain values will be erased. if "album", both track and album gain values will be calculated. If "auto", then "album" mode will be used except in directories that contain a file called "TRACKGAIN" or ".TRACKGAIN". In these directories, "track" mode will be used. The default setting is "auto". -b (audiotools|bs1770gain|auto), --backend (audiotools|bs1770gain|auto) Gain computing backend to use. Different backends have different prerequisites. -j 4, --jobs 4 Number of albums to analyze in parallel. The default is the number of cores detected on your system. -m, --low-memory Use less memory by processing directories one by one rather than pre-computing the complete list of files to be processed. This will disable progress bars, but will allow rganalysis to run on very large music collections without running out of memory. -q, --quiet Do not print informational messages. -v, --verbose Print debug messages that are probably only useful if something is going wrong.


Then you can install this package from Github using pip:

pip install https://github.com/DarwinAwardWinner/rganalysis/archive/master.zip

Note that rganalysis only works with Python 3. If you want progress bars in the output, you should also install tqdm.

Lastly, you need to install the prerequisites for at least one backend. Right now there are 2 backends available for computing replay gain: one which uses the audiotools Python module, and one which uses the command-line program bs1770gain. You'll need to install either one or the other to use this script. (If you prefer another tool for computing replay gain, feel free to let me know about it, and I will see if I can write a backend for it.)

What is an album?

When doing "album" or "audiophile" Replay Gain tags, one needs to carefully define an album. For example, if you happen to have half an album in FLAC format and the other half in MP3, they might be at different volumes to begin with, so calculating Replay Gain tags on the whole album is a bad thing -- the MP3s will end up too loud and the FLACs too quiet, or vice versa.

Anyway, this script considers two tracks to belong to the same "track set" for the purposes of calculating audiophile gain if:

  • They are in the same directory on the filesystem
  • They are both the same music format (MP3, OGG, FLAC, etc.)
  • They have the same "album" tag (preferring the "albumsort" tag if present)
  • They have the same "albumartist" (preferring the "albumartistsort" tag if present, and falling back to "artistsort" then "artist" if there is no album artist tagged)
  • They have the same "discnumber" tag (or lack thereof)

This means if you have a multi-artist album, you'll need to set the "albumartist" tag to the same value (e.g. "Various Artists") on all songs in the album in order for all the songs to be grouped as a single album. You can still set a different "artist" tag on each song.

See also

Transfercoder, a tool for transferring your music to your portable mp3 player while simultaneously transcoding music formats that the player doesn't recognize.