loudgain

Imortant note: I don’t currently have enough time to work on loudgain, but I intend to come back and take care of all the great suggestions and PR’s you made! In the meantime, I’d be happy if someone really knowledgeable could help, ideally someone who could explain a) how to set up a co-maintainership here, b) would take care of some issues & PR’s, and c) probably be able to make this an official Debian/Ubuntu/Mint package. Thanks for all your support!

loudgain is a versatile ReplayGain 2.0 loudness normalizer, based on the EBU R128/ITU BS.1770 standard (-18 LUFS) and supports FLAC/Ogg/MP2/MP3/MP4/M4A/ALAC/Opus/ASF/WMA/WAV/WavPack/AIFF/APE audio files. It uses the well-known mp3gain commandline syntax but will never modify the actual audio data.

Just what you ever wanted: The best of mp3gain, ReplayGain 2.0 and Linux combined. Spread the word!

Note: There is a »runnable« version for 64-bit systems in the bin folder, called loudgain.static. Read loudgain.static. You can use this if you only want to try out loudgain, cannot or don’t wish to compile it yourself. It starts much slower, but brings all its dependencies with it, and thus can even be used on older systems.

Mac users: Read Installation using Homebrew (Mac & Linux).

Windows 10 users: Read Installation on Windows 10 (Linux bash).

Table of Contents
MAIN FEATURES
NEWS, CHANGELOG
GETTING STARTED
Installation using Homebrew (Mac & Linux)
Installation on Windows 10 (Linux bash)
DEPENDENCIES
BUILDING
Mass tagging
- Avoiding recalculation
- User example script
TECHNICAL DETAILS (advanced users stuff)
loudgain makes it easy following the »Gold Standard«
Quality over speed
AUTHORS
COPYRIGHT

MAIN FEATURES

loudgain is a loudness normalizer that scans music files and calculates loudness-normalized gain and loudness peak values according to the EBU R128 standard, and can optionally write ReplayGain-compatible metadata.

EBU R128 is a set of recommendations regarding loudness normalisation based on the algorithms to measure audio loudness and true-peak audio level defined in the ITU BS.1770 standard, and is used in the (currently under construction) ReplayGain 2.0 specification.

loudgain implements a subset of mp3gain's command-line options, which means that it can be used as a drop-in replacement in some situations.

Note: loudgain will not modify the actual audio data, but instead just write ReplayGain tags if so requested. It is up to the player to interpret these. (Hint: In some players, you need to enable this feature.)

Note: loudgain can be used instead of mp3gain, vorbisgain, metaflac, aacgain and others in order to write ReplayGain 2.0 compatible loudness tags into MP2, MP3, Ogg, FLAC, M4A/MP4 (AAC/ALAC audio), Opus, ASF/WMA, WAV, AIFF, WavPack and APE files, respectively.

Note: EBU R128 recommends a program (integrated) target loudness of -23 LUFS and uses LU and LUFS units. The proposed ReplayGain 2.0 standard tries to stay compatible with older software and thus uses EBU R128 loudness measuring but at a target of -18 LUFS (estimated to be equal to the old "89 dB" reference loudness). The generated tags also still use the "dB" suffix (except for '-s l' tag-mode which uses "LU"; 1 dB = 1 LU).

loudgain defaults to the ReplayGain 2.0 standard (-18 LUFS, "dB" units, uppercase tags). Peak values are measured using the True Peak algorithm. The only exception are Opus files which are 'nailed' to -23 LUFS by design.

Standing on the shoulders of giants: loudgain wouldn’t be possible without Linux and the fantastic FFmpeg, taglib and libebur128 libraries. Thank you!

Also my heartfelt thanks to Alessandro Ghedini who had the original idea back in 2014 and gave us his v0.1 repo from which I forked.

NEWS, CHANGELOG

2019-09-06 – v0.6.8 released:

Adds support for Monkey’s Audio (APE) files. Read How I handle APE (.ape) audio files.
Fixes "You have different file types in the same album" bug (#9).
Real case-independent ReplayGain tag removal code (#10).
Updated rgbpm to v0.13 (adds APE).

2019-09-04 – v0.6.7 released:

Adds support for AIFF files. The "Audio Interchange File Format" is mostly used on Apple Macs.
Updated rgbpm to version 0.12.

2019-09-03 – v0.6.6 released:

Add support for more codecs in the Ogg container. Loudgain now supports Ogg Vorbis, Ogg FLAC, Speex and Opus.
Add experimental support for WavPack (.wv) files. Read How I handle WavPack (.wv) audio files.
Updated the program’s help (loudgain -h) and the man page (man loudgain).
Updated rgbpm to handle the new file types.

2019-09-03 – v0.6.5 released:

Rework file type detection: Add container format, since relying on the codec alone isn’t safe enough to determine which tag type to write. This will also handle files with incorrect extensions correctly.

2019-09-02 – v0.6.4 released:

Some code cleanup in the tagger.
Added rudimentary WAV file tagging support (by writing ID3v2 tags into the "ID3 " chunk). This is a format understood by foobar2000, VLC, Mp3tag and others. Read How I handle WAV (.wav) audio files.

2019-09-01 – v0.6.3 released:

Added experimental (!) ASF/WMA (.asf, .wma) support. Please read How I handle ASF/WMA (.asf, .wma) audio files and give feedback on GitHub!

2019-08-23 – v0.6.2 released:

Album gain for Opus albums now calculated correctly. Fixes #6. Thanks to pr0m3th3u5 for intensive testing!
loudgain will now issue a warning if you mix files of different types (=codecs) in the same album.
loudgain now aborts with an error if you try to mix Opus and non-Opus files in the same album (it’s not possible to calculate a correct album gain in this case).

2019-08-17 – v0.6.1 released:

Can now show data for .wav and other files (albeit not tag them). You could use that for a quick check or to write a (tab-separated) .csv file using loudgain -O … > result.csv. Or even with awk for further custom processing.
Fixed some channel layout and memory issues for files with more than 2 channels (i.e., 5.0, 5.1).

2019-08-16 – v0.6.0 released:

Rework the scanner module to work with the newer FFmpeg API (needed for FFmpeg 4.2+). Tested ok with FFmpeg 3.4.6, 4.1.4, 4.2.
Now officially provides the former rgbpm.sh as an updated and MacOS-compatible rgbpm command. After installing, type rgbpm -h for help. This is for mass-tagging (1 album per folder).
Now provides a [sudo] make uninstall target, should you wish to uninstall it again.
Tested on Linux Mint 19.2, Ubuntu 18.04, Manjaro 18.0.4, MacOS 10.14.4 Mojave.

2019-08-13 – v0.5.4 released:

Make loudgain compile & run on MacOS X, with lots of help from @classicjazz.
Support for installation using Homebrew (Apple) and Linuxbrew (Linux).

2019-08-06 – v0.5.3 released:

Added experimental (!) Opus (.opus) support. Please read How I handle Opus (.opus) audio files and give feedback on GitHub!

2019-08-05 – v0.5.2 released:

Add support for MPEG-1 Layer 2 (.mp2) audio files: Much like MP3, uses ID3v2 tags and the same options. These can be used with many taggers/players like MusicBrainz Picard, IDJC, Audacious and many more.
rgbpm.sh also updated for *.mp2 support.

2019-08-02 – v0.5.1 released:

Speedup: Eliminate unneccessary double file writes (deleting+rewriting RG tags). Should help with low-speed disks and network mounts.
Error handling: loudgain now complains when unable to write to a file (instead of silently ignoring it).
Cosmetic changes: Update man page, help text and version info.

2019-08-01 – v0.5.0 released:

loudgain now uses FFmpeg’s libswresample instead of the deprecated libavresample. Fixes #1. Tested on Ubuntu 18.04, Linux Mint 19.1, Manjaro 18.0.4, Arch.

2019-07-31 – v0.4.1 released:

Added support for ALAC (Apple Lossless Audio Codec) audio in MPEG-4 containers (.m4a, .mp4, .alac). -L (--lowercase) option is supported. ReplayGain tags are written to ----:com.apple.iTunes:REPLAYGAIN_*.
Note: I do not care about any »iTunes Soundcheck« (a.k.a »iTunNORM«) tags. If such should exist, they will stay untouched. Software outside Apple’s iTunes diaspora usually ignores these tags anyway.

2019-07-31 – v0.4.0 released:

Added support for AAC audio in MPEG-4 containers (.m4a, .mp4). -L (--lowercase) option is supported. ReplayGain tags are written to ----:com.apple.iTunes:REPLAYGAIN_*.
loudgain was never intended for video files, but it actually does work on .mp4 video files, although only one audio track is respected. Go figure!

2019-07-17 — v0.3.2 released:

Work around bug #913 in taglib: If both APEv2 and ID3v1 tags present and due to be stripped, sometimes ID3v1 tags would be left over.

2019-07-17 — v0.3.1 released:

"Delete tags" -s d (--tagmode=d) now respects "strip" -S (--striptags) and "ID3v2 version" -I (--id3v2version) settings for MP3 files. Thus, when removing ReplayGain tags, unwanted tag types like ID3v1 or APE can also be removed, and the the resultant ID3v2 tag version be specified.

2019-07-13 — v0.3.0 released:

Much better clipping prevention logic.
Breaking change: Some long options slightly renamed.
Breaking change: -k now obeys EBU -1 dBTP maximum true peak level (as opposed to 0 dBTP before). Read Clipping prevention.
New option -K n (--maxtpl=n) switches on clipping prevention like -k and allows manually setting the max. true peak level (i.e., -K 0 to limit at digital full scale, or -K -2 if later processing includes lossy encoding).
Breaking change: Reordered and extended -O (--output-new) output. It now adds the fields New_Peak and New_Peak_dBTP so one can see what will happen in the playout/post-processing chain after the replay gain has been applied. Read Analyze audio files and output to CSV.

2019-07-12 — Temporary solution to the taglib problem:

If you need to loudgain Ogg Vorbis files, you can use the provided loudgain.static in the bin/ folder. I have built it against taglib 1.11.1-3 on Manjaro, a version that doesn’t show the bug. Read loudgain.static.

2019-07-10 — Warning:

There seems to be an open bug in taglib (which loudgain uses) that also affects lots of other programs: Upon writing Ogg Vorbis files, they can possibly get corrupted.

I advise not to save tags to Ogg Vorbis files right now, until this issue is resolved upstream and you can compile a bugfree taglib or the distros provide one!

Analyzing Ogg files is fine, as well as analyzing and saving to MP3 and FLAC.

2019-07-10 — v0.2.7 released:

Add option to strip ID3v1/APEv2 tags from MP3 files: -S (--striptags).
Add option to select between ID3v2.3 & ID3v2.4 for MP3 files: -I 3 (--id3v2version 3).
Much more technical documentation here.
Great new tab-delimited list output format: -O (--output-new). For a usage example, read Analyze audio files and output to CSV.

2019-07-09 — v0.2.6 released:

Reverted back to default uppercase REPLAYGAIN_* tags in MP3 files. The ReplayGain 2.0 spec requires this.
Added -L (--lowercase) option for those who need lowercase replaygain_* tags (MP3/IDv2 only; doesn’t affect FLAC/Ogg). Read Uppercase or lowercase 'REPLAYGAIN_*' tags?.

2019-07-08 — v0.2.5 released:

Clipping warning & clipping prevention (-k) now work correctly, for both track and album.

2019-07-08 — v0.2.4 and v0.2.4-1 released:

Add "extra tags" mode -s e (--tag-mode e). Writes REPLAYGAIN_REFERENCE_LOUDNESS, REPLAYGAIN_TRACK_RANGE and REPLAYGAIN_ALBUM_RANGE tags (same that bs1770gain uses).
Add "LU" units mode ss l (--tag-mode l). Like above but uses "LU" instead of "dB" units in the tags.
Update README.md and program help.

2019-07-07 — v0.2.3 released:

Fix broken album peak (again).
MP3/ID3v2 now get lowercase replaygain_* tags.
Better versioning.

2019-07-07 — v0.2.2 released:

Fixed album peak calculation.
Write REPLAYGAIN_ALBUM_* tags only when in album mode.
Better versioning (CMakeLists.txt → config.h).
TODO: Clipping calculations still wrong.

2019-06-30 — v0.2.1 released:

Added version and -v (--version) option.
Added writing tags to Ogg Vorbis files (now supports MP3, FLAC, Ogg Vorbis).
Always remove REPLAYGAIN_REFERENCE_LOUDNESS, wrong value might confuse players.
Added notice in help on which file types can be written.
Added album summary in output.

2019-06 – v0.1 (2014-06-13) forked from https://github.com/ghedo/loudgain.

GETTING STARTED

loudgain is (mostly) compatible with mp3gain's command-line arguments (the -r option is always implied). Here are a few examples:

$ loudgain *.mp3                       # scan some mp3 files without tagging
$ loudgain -s i *.mp3                  # scan and tag some mp3 files with ReplayGain 2.0 tags
$ loudgain -d 13 -k *.mp3              # add a pre-amp gain and prevent clipping
$ loudgain -s d *.mp3                  # remove ReplayGain tags from the files
$ loudgain -a -s i *.flac              # scan & tag an album of FLAC files
$ loudgain -a -s e *.flac              # scan & tag an album of FLAC files, add extra tags (reference, ranges)
$ loudgain -d -5 -a -s l *.flac        # apply -5 LU pregain to reach -23 LUFS target for EBU compatibility, add reference & range information, use 'LU' units in tags
$ loudgain -I 3 -S -L -a -k -s e *.mp3 # scan & tag an MP3 album, recommended settings
$ loudgain -L -a -k -s e *.m4a         # scan & tag an MP4 AAC/ALAC audio album, recommended settings
$ loudgain -a -k -s i *.opus           # scan & tag an Opus album
$ loudgain -L -a -k -s e *.wma         # scan & tag a WMA album

See the man page for more information.
See loudgain makes it easy following the »Gold Standard« for quickstart recommended settings.

Installation using Homebrew (Mac & Linux)

loudgain can now be installed on MacOS X (and Linux, too) using Homebrew.

Homebrew is updated extremely often (a good thing!), and I therefore recommend performing a

brew update
brew upgrade

very often, and in any case before installing something new.

Since taglib (libtag) hasn’t had a new release since 24 Oct 2016 (v1.11.1) but they have fixed a lot of nasty bugs, it is mandatory to update libtag to the HEAD version first:

brew uninstall --ignore-dependencies libtag
brew install --HEAD libtag

Then simply install loudgain (stable version):

brew install Moonbase59/tap/loudgain

or even the latest development version using:

brew install --HEAD Moonbase59/tap/loudgain

Enjoy!

Installation on Windows 10 (Linux bash)

Yes, we can! Install the Linux bash first (I recommend the Ubuntu version). There are many tutorials available, like these two in English and German.

Then continue with DEPENDENCIES.

loudgain running under Windows 10’s Linux shell

DEPENDENCIES

libavcodec
libavformat
libavutil
libswresample
libebur128 (v1.2.4+ recommended)
libtag

You might want to upgrade your system before you start. This is especially important if you are using the Windows 10 Linux bash:

$ sudo apt-get update
$ sudo apt-get upgrade

If you plan to use loudgain.static and rgbpm from your personal ~/bin folder, I recommend to create ~/bin first (if not already done):

$ mkdir ~/bin

If you freshly created this, you might need to log out and log in again to make your system recognize your personal ~/bin folder.

On Ubuntu 18.04, Linux Mint 19 or the Windows 10 Linux bash, install the build environment like this:

$ sudo apt-get install build-essential cmake pkg-config git

Then you can install the needed libraries using

$ sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev libswresample-dev libebur128-dev libtag1-dev

BUILDING

loudgain is distributed as source code. Install with:

$ git clone https://github.com/Moonbase59/loudgain.git
$ cd loudgain
$ mkdir build && cd build
$ cmake ..
$ make
$ [sudo] make install

If you modified docs/loudgain.1.md (the man page source), get ronn, move to the docs/ folder and type:

$ ronn loudgain.1.md

This will generate new loudgain.1 and loudgain.1.html files (man page and readable HTML, respectively).

If you need to recreate bin/loudgain.static, get staticx, install loudgain on your system, move to the bin/ folder and type:

$ staticx --strip `which loudgain` loudgain.static
$ ln -s loudgain.static loudgain

You can then move loudgain, loudgain.static and rgbpm to your target user’s ~/bin folder.

Beware this is a kludge only to be used if all else fails. (For example, you can build on Ubuntu 18.04/Linux Mint 19 but really need loudgain to work on Ubuntu 14.04/Linux Mint 17.3. That’s what I used it for.)

Mass tagging

You may want to (re-)tag a whole collection, or at least all folders beneath a certain folder. Most people follow a "one album = one folder" approach.

Loudgain itself doesn’t do any kind of folder traversal internally—it just takes all files given on the commandline and works on them. But it is quite easy to write a little wrapper script in Python or bash to handle tagging many folders. One such script, rgbpm, is included as an example you can build upon.

Simply copy it over to a feasible place like /usr/local/bin or your personal ~/bin folder, study the code and modify to your heart’s content. As delivered, rgbpm follows my tagging recommendations.

Personally, I also have quite a strict workflow, so mass-tagging is never needed:

Buy or rip files, one folder per release.
In case of MP3, use MP3 Diags to repair them.
Use rgbpm to store ReplayGain and BPM data into the files.
Use MusicBrainz Picard to correctly tag the files and move them into my final library.
Never touch them again using any tools whatsoever. (Well, except read-only playout, of course.)

Avoiding recalculation

Loudgain does deliberately not provide a means to avoid re-calculation, because doing that safely and reliably is almost impossible. For example, just checking for REPLAYGAIN_TRACK_GAIN would be unsafe, because we wouldn’t know about missing peaks, we wouldn’t know what algorithm was used to arrive at the stored value, we wouldn’t know about album gain, we wouldn’t know if clipping prevention or pre-gain had been used to arrive at these values. Ditto for checking REPLAYGAIN_ALBUM_GAIN: We don’t know if a single track has been added or removed in the meantime, so the values needed to be recalculated, file types in a folder might be mixed, and whatever else. The user could also wish to store the extended tags (loudness range and reference), so we also needed to check for these and compare to what has been specified on the commandline. Same for peak values: We don’t know if the stored values were sample peak, RMS peak, or true peak values, and what algorithm was used to calculate them.

So all in all, we could never be sure the stored values are correct in any way. That’s why loudgain (and rgbpm) don’t provide a means for "skipping" and thus gaining a little performance advantage at the cost of possibly having wrong values in the files.

This is why loudgain insists on recalculation every time: To give you the most exact results. Every time.

There is a discussion going on about this in issue #7.

User example script

There might be the case that you always use loudgain in a consistent manner, have a large collection, and somehow still want to skip unneeded recalculations.

User @flittermice uses small hidden "flag" files in each folder to prevent recalculating. He has modified rgbpm for his needs and shared it with us. Maybe you can use this or adapt it for your needs. More about this script in issue #7.

TECHNICAL DETAILS (advanced users stuff)

Not an expert? Don’t worry, loudgain comes with sensible default settings. You might never need the "special options".

But if you do, you might need them badly. Welcome to the expert sessions—read on!

Things in the `bin`folder

These are meant for testing, and to get you going FAST. You can simply copy these files into your user’s $HOME/bin folder and make them executable. On most Linuxes, they should be available as commands in the path when opening the next shell. Maybe you need to log off and back on again to make it work.

rgbpm – Folder-based loudness and BPM scanning

This is a little bash script to invoke loudgain (well, and a BPM scanner) and have it scan album folders, starting from a top folder, recursively. I use this almost every day.

$ rgbpm folder [...]

rgbpm is now officially provided with loudgain, as an executable installed script. No guarantees, though. ;-)

Please study the code and adapt as needed for your situation. rgbpm does ReplayGain mass-tagging according to my needs, your mileage may vary.

loudgain.static

This is a kludge, really. A prebuilt statically-linked runnable version of loudgain only to be used if you really really have no other option (i.e., needed libraries uncompilable under older Linuxes).

It’s a 64-bit ELF made using staticx that brings the needed libraries with it. I tested it with Ubuntu versions 14.04–18.04, Linux Mint 17.3–19.1, and Manjaro 18.0.4. It works but it’s slooow to start.

If you don’t have a "real" loudgain, you can create a symlink to it in your ~/bin directory as follows (assuming you have copied loudgain.static to there):

$ cd ~/bin
$ chmod +x loudgain.static
$ ln -s loudgain.static loudgain

Verify that it’s available as a normal command by trying either of the following:

$ which loudgain
$ loudgain -h

Uppercase or lowercase 'REPLAYGAIN_*' tags?

Uppercase vs. lowercase tags still seems to be a never-ending battle—when will players finally learn to handle these case-insensitively?

This has been a problem ever since, most notably in MP3 ID3v2, MP4, WMA, WAV, AIFF, WavPack and APE tags, because these are case-sensitive. FLAC, Ogg, WavPack and APE use tags that can be upper-, lower- or mixed case but MUST be treated equal.

The ReplayGain 1 and 2.0 specs clearly state that the tags should be UPPERCASE but many taggers still write lowercase tags (foobar2000, metamp3, taggers using pre-1.2.2 Mutagen like older MusicBrainz Picard versions, and others).

Unfortunately, there are lots of audio players out there that only respect one case. For instance, VLC only respects uppercase, IDJC and KODI only respect lowercase. Only a very few go the extra effort to check for both variants of tags.

It seems that out in the field, there are more players that respect the lowercase tags than players respecting the uppercase variant, maybe due to the fact that the majority of MP3 and MP4/M4A files seem to be tagged using the lowercase ReplayGain tags—they simply adopted.

Now all this can lead to lots of problems and seems to be an unsolvable issue. In my opinion, all players should respect all variants of tags.

Since we don’t live in an ideal world, my approach to the problem is as follows:

loudgain uses the ReplayGain 2.0 "standard" as its default, in order not to confuse newbies. (That means: -18 LUFS reference, "dB" units, and uppercase 'REPLAYGAIN_*' tags.)
Upon deleting ReplayGain tags (using -s d or before writing new tags using -s i, -s e or -s l), loudgain will delete all variants of the old tags. Thus, if you have like (may be due to mis-tagging):
```
REPLAYGAIN_TRACK_GAIN -7.02 dB
replaygain_track_gain -7.50 dB
```
loudgain will remove both then write one new tag (of each sort), usually like:
```
REPLAYGAIN_TRACK_GAIN -7.02 dB
```
For the seemingly unavoidable cases where you do indeed need lowercase ReplayGain tags in MP3 ID3v2, MP4/M4A, ASF/WMA, WAV or AIFF tags, I introduced a new option -L (--lowercase) that will force writing the lowercase variant (but only in MP3 ID3v2, MP4/M4A, ASF/WMA, WAV, AIFF; FLAC, Ogg, WavPack and APE will still get standard uppercase tags):
```
replaygain_track_gain -7.02 dB
```
There’s only one way to get rid of the problem: File bug reports for any player you use that doesn’t handle ReplayGain tags at all or in a case-sensitive manner! (Not here, but on the player’s bug tracker sites or forums.) If a player respects ReplayGain tags at all, it should do so in a case-insensitive manner, for as many file types as possible!

Tags written (and/or deleted)

Default mode `-s i` (`--tag-mode i`)

In its simplest, mp3gain-compatible, tag writing mode -s i (--tag-mode i), loudgain will only produce the bare minimum required by the ReplayGain 2.0 standard:

REPLAYGAIN_TRACK_GAIN [-]a.bb dB
REPLAYGAIN_TRACK_PEAK c.dddddd

If "album mode" -a is specified, these additional album tags will be produced:

REPLAYGAIN_ALBUM_GAIN [-]a.bb dB
REPLAYGAIN_ALBUM_PEAK c.dddddd

All other known ReplayGain tags (no matter what case) will be deleted, in order not to confuse other software. These are (if present):

REPLAYGAIN_TRACK_GAIN
REPLAYGAIN_TRACK_PEAK
REPLAYGAIN_TRACK_RANGE
REPLAYGAIN_ALBUM_GAIN
REPLAYGAIN_ALBUM_PEAK
REPLAYGAIN_ALBUM_RANGE
REPLAYGAIN_REFERENCE_LOUDNESS

For MPEG-4 containers (.mp4, .m4a), these are stored under ----:com.apple.iTunes:… but the names are the same.

Enhanced mode `-s e` (`--tag-mode e`)

In its "enhanced" tag-writing mode s e (--tag-mode e), loudgain will work like above but in addition write the following tags:

REPLAYGAIN_TRACK_RANGE a.bb dB
REPLAYGAIN_REFERENCE_LOUDNESS [-]a.bb LUFS

If "album mode" -a is specified, this additional album tag will be produced:

REPLAYGAIN_ALBUM_RANGE a.bb dB

Since ReplayGain 2.0 works using the EBU R128 recommendation (but at the different target -18 LUFS), and -18 LUFS has been estimated to be "equal" to the old 89 dB SPL ReplayGain 1 standard, it would make no sense to give pseudo-dB values as a reference loudness. This is possibly the reason why the RG2 spec dropped this tag altogether, and this is the reason why I stick with real LUFS units in the REPLAYGAIN_REFERENCE_LOUDNESS tag, even when writing "dB" units elsewhere for compatibility with the ReplayGain 2.0 standard and older software.

For MPEG-4 containers (.mp4, .m4a), these are stored under ----:com.apple.iTunes:… but the names are the same.

"LU" units mode `-s l` (`--tag-mode l`)

There is a third tag-writing mode in loudgain, that will probably not be used by many: -s l (--tag-mode l). It behaves like above (-s e mode), but uses "LU" units instead of "dB" (fortunately, 1 dB = 1 LU). This might not be of interest for many, but the few who need it, need it badly. :-)

The generated tags look like this:

REPLAYGAIN_TRACK_GAIN [-]a.bb LU
REPLAYGAIN_TRACK_PEAK c.dddddd
REPLAYGAIN_TRACK_RANGE a.bb LU
REPLAYGAIN_ALBUM_GAIN [-]a.bb LU
REPLAYGAIN_ALBUM_PEAK c.dddddd
REPLAYGAIN_ALBUM_RANGE a.bb LU
REPLAYGAIN_REFERENCE_LOUDNESS [-]a.bb LUFS

This is a variant that is handled perfectly by IDJC (the Internet DJ Console), and others. Fully EBU-compliant (-23 LUFS target) files can be made by adding a -5 LU pregain to loudgain’s commandline arguments: -d -5 (--db-gain -5).

Interestingly enough, I found that many players can actually handle the "LU" format, because they simply use something like C’s atof() in their code, thus ignoring whatever comes after the numeric value!

For MPEG-4 containers (.mp4, .m4a), these are stored under ----:com.apple.iTunes:… but the names are the same.

Track and Album Peak

When comparing to other (older) tools, you might find the peak values are often higher than what you were used to.

This is due to the fact that loudgain uses true peak (not RMS or sample peak) values, which are much more appropriate in the digital world, especially when using lossy audio formats.

loudgain uses the libebur128 library for this. It currently (v1.2.4) provides a true peak calculated using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96000 Hz, 2x for sample rates < 192000 Hz and leave the signal unchanged for 192000 Hz.

MP3 ID3v2.3, ID3v2.4, and APE tags

MP3 files can come with lots of tagging versions: ID3v1, ID3v1.1, ID3v2.2, ID3v2.3 and ID3v2.4. If people have been using mp3gain on the files, they might even contain an additional APEv2 set of tags. It’s a mess, really.

Fortunately, nowadays, all older standards are obsolete and ID3v2.3 and ID3v2.4 are almost universally used.

Older players usually don’t understand ID3v2.4, and ID3v2.3 doesn’t know about UTF-8 encoding. Important frames like TYER, TDAT, and TDRC have also changed. A mess again.

My current solution to this (and loudgain’s default behaviour) is as follows:

The overall philosophy is: "The user might know what he is doing. So try not to touch more than needed."
loudgain will try to read important information from all of the above mentioned tag types, preferring ID3v2 variants.
Upon saving, loudgain will preserve ID3v1/ID3v1.1 and APE tags, but upgrade IDv2.x tags to version ID3v2.4.

I realize that a) people might need ID3v2.3 and b) some of us want to strip unneccessary ID3v1 and APE tags from MP3 files. There is a solution to that:

Force writing ID3v2.3 or ID3v2.4 tags

The default tag type loudgain writes to MP3 files is ID3v2.4 which is the most modern and UTF-8-capable version. There might be reasons to force loudgain to write ID3v2.3 tags instead (maybe for an older audio player that doesn’t handle ID3v2.4).

Using the options -I 3 (--id3v2version 3) or -I 4 (--id3v2version 4), you can force loudgain to write ID3v2.3 or ID3v2.4 tags, respectively.

This option has no effect on FLAC or Ogg vorbis files.

Strip unwanted ID3v1/APEv2 tags `-S` (`--striptags`)

More than one kind of tags in an MP3 file is generally a bad idea. It might confuse other tagging software and audio players. Historically, mp3gain used APEv2 tags to "hide" ReplayGain data from normal ID3 taggers—a bad idea. ID3v1, ID3v1.1 and ID3v2.2 are obsolete due to their restricted possibilities and lack of support.

Using loudgain’s -S (--striptags) option, these other tag types can be removed from MP3 files when writing new ReplayGain tags, and a clean ID3v2-only file is left. In this process, loudgain will try to keep content from other tag types as far as possible (like 'MP3GAIN_MINMAX', for instance) and transport it over into appropriate ID3v2 tags. For tags that are a duplicate of existing ID3v2 tags, the ID3v2 tag content is preferred.

This option has no effect on FLAC or Ogg Vorbis files.

Analyze audio files and output to CSV

Using the new output mode -O (--output-new) in combination with quiet mode -q (--quiet) allows you to analyze audio files without modifying anything, and write the results to a .csv file for later examination with LibreOffice Calc (or Excel).

Example: Mary Black’s album »No Frontiers« (1989)

As an example, let’s examine a folder that contains Mary Black’s album »No Frontiers« (1989) in FLAC format. This is an album produced before the loudness wars started and has a wide dynamic range. Unfortunately, it was also produced near the full digital range, at that time of course disregarding the EBU R128 recommendation of a maximum peak at -1 dBTP. (This album is actually a good example of why the EBU R128 recommendation to use a -23 LUFS target makes much sense!)

Take a peek at the peaks (»Mary Black - Columbus«):

Write a simple analysis to a CSV file

Well, we want to analyze the album first, into test-1.csv:

$ loudgain -a -O -q *.flac > test-1.csv

Hint: Select tab-delimited when opening the .csv file with LibreOffice Calc or Excel, not semicolon- or comma-delimited.

We get the following table (example):

Watch the Will_clip column. Oops! Due to the high true peaks, tracks will clip when being replaygained at -18 LUFS and played with an audio player that doesn’t do clipping prevention!

Analyze again, using clipping prevention

Now let’s see what would happen if we used loudgain’s clipping prevention mechanism (effectively reducing the gain just below the clipping point). We simply add the -k option to the commandline and write the results to test-2.csv for analysis:

$ loudgain -a -O -q -k *.flac > test-2.csv

See what we get:

By correcting the album gain from 0.12 dB to -1.15 dB, we could ensure that nothing clips when using a player in album RG mode. Furthermore, seven tracks needed a track gain adjustment to prevent clipping (check the Clip_prevent column).

Just for fun: What if we really followed the EBU R128 recommendation?

Just for fun, let’s see what would happen if we followed the EBU R128 recommendation and use a loudness target of -23 LUFS instead of ReplayGain’s -18 LUFS. We simply tell loudgain to use an extra -5 LU pre-gain (-d -5, thus effectively going from -18 to -23 LUFS):

$ loudgain -a -O -q -k -d -5 *.flac > test-3.csv

Et voilà!

At -23 LUFS, we have ample headroom, no gain shifts are needed to prevent clipping, a good thing. Apparently the EBU knew what they were doing. 8-)

Time to save the tags and listen to the music!

Anyway, back to the ReplayGain 2.0 world. I will now let loudgain apply what we found (add -s e to the commandline), then sit back before the big hi-fi set and enjoy one of my favourite albums—totally clipping-free.

$ loudgain -a -k -s e *.flac

(Since we don’t need to write a CSV file anymore, I dropped the -O and -q commands and the redirection from the above.)

… And this was just one example of what you can do with loudgain.

Have fun, experiment, give me feedback, and SPREAD THE WORD!

Clipping prevention

loudgain can help prevent clipping in the playout/post-processing stage by using the -k (--noclip) or -K (--maxtpl) options. It will use the measured track/album true peak values to reduce the calculated replay gain to a "safe" value, so that no clipping should occur after the replay gain has been applied by the player or post-processing software.

Old-style programs (like mp3gain and others) and CD producers often used algorithms that would lower the gain so that the maximum peak value reached was 0 dBTP (digital full scale, 1.000000). Furthermore, all this was often based on sample amplitudes, or at most a RMS peak value.

Now we all learned that this is not enough. Lossy encoding and loudness war type productions have shown us true peak levels far above digital 1.0. This is why we nowadays (hopefully) all use True Peak meters with usually 4x oversampling up to 48 kHz and can thus see the real peaks much better. But even a good True Peak meter can have an under-reading of up to about 0.5 dB/LU! This is why the EBU decided that we should leave a "headroom" of -1 dBTP (or even -2 dBTP if we know that later on lossy encoding will happen). See EBU Tech 3343, page 42.

This is why I changed the default setting of loudgain’s -k option away from 0 dBFS to -1 dBTP. Even with ReplayGain 2.0’s -18 LUFS target, this should give us a safe default for best reproduction.

If, for some reason, you really need to emulate the (bad) old behaviour, you can use -K 0 instead which will force loudgain’s clipping prevention to use a 0 dBTP limit.

You could also use this option to set a max. true peak level of -2 dBTP, i.e. for two data reduction systems commonly used in Europe—MPEG1 Layer2 and Dolby AC-3. Simply use -K -2 in this case.

Home and semi-professional users should usually just use -k. This will give perfect results with almost any ReplayGain-aware player as well as hi-fi systems like Logitech Media Server (ex SqueezeServer/SqueezeBox) and internet broadcasting software like IDJC, ices 0.4.5+, LiquidSoap, Airtime, AzuraCast, Centova Cast and so on.

Here be dragons: A word on MP3 files and ID3 tags

The good news: If you work with FLAC or Ogg Vorbis files, all of this doesn’t apply to you. Then again, no dragons. FLAC and Ogg Vorbis files use "Vorbis Comment" type tags which are easy-going, straightforward and have supported UTF-8 ever since.

MP3 files can have more than one kind of tags: ID3v1, ID3v1.1, ID3v2.2, ID3v2.3, ID3v2.4, and APEv2. To make it even more complicated, ID3v1, ID3v2 and APEv2 tags can co-exist in the same file. Plus, the encoder (like LAME) can set gaining info in its header. It’s a mess, really.

Some basic recommendations

Here are some recommendations to keep things easy:

Throw away (or convert) ID3v1, ID3v1.1, ID3v2.2 and APEv2 tags. They are obsolete and make things unneccessarily complicated. loudgain can do this for you: Use the -S (--striptags) option on the commandline. Nothing is worse than having different tag types in one file that specify different values. One player would pick one, another player the other info, and you’d wonder about the errors!
Then try to stick with either ID3v2.3 or ID3v2.4 type tags throughout your collection. loudgain’s default is to convert existing tags to ID3v2.4 but you can specify -I 3 (--id3v2version=3) on the commandline to get ID3v2.3 tags instead.
ID3v2.4 is the more modern standard and handles UTF-8 encoding in text frames (like Artist, Title, Album, …). This is also the default on most Linux systems. Unfortunately, older players (most notably Windows Media Player and older Apple products) cannot handle this format.
Therefore, ID3v2.3 is still the most commonly used tag format for MP3 files, due to its widest compatibility.
Over the past decades, replay gain tags like REPLAYGAIN_TRACK_GAIN have evolved. These are stored in so-called "text frames" (TXXX). Both the ReplayGain 1 and ReplayGain 2.0 standards specify these tags to be UPPERCASE, but in reality most software in the field (like foobar2000) store these in lowercase (replaygain_track_gain) and most files I’ve come across actually have these tags in lowercase.

In theory, players should handle these in a case-insensitive manner, but some don’t. For instance, the famous IDJC (Internet DJ Console, a broadcasting software) does only respect the lowercase variant.

So if you live in a mixed Windows/Linux environment (maybe using foobar2000 on Windows, IDJC on Linux), my recommendation for the time being is: Use the (non-standard) lowercase ReplayGain tags. You can force loudgain to write lowercase tags by using the -L (--lowercase) option on the commandline.

A zillion ways to store loudness/gaining information

In MP3 files, there are many ways to store loudness/gaining information:
- The LAME header (RGAD_album, RGAD_track, mp3_gain, and others).
- Apple’s non-standard "Soundcheck" tags.
- ID3v2.2 RVA frames.
- ID3v2.3 RVAD frames.
- ID3v2.4 RVA2 frames.
- APEv2 tags like REPLAYGAIN_TRACK_GAIN (and others).
- ID3v2.2 TXX frames like REPLAYGAIN_TRACK_GAIN (and others).
- ID3v2.3/ID3v2.4 TXXX frames like REPLAYGAIN_TRACK_GAIN (and others).
Disregarding Apple, a modern player should (but often doesn’t!) check for these in order of priority (lowest priority → top priority):
- LAME header (I don’t know of any player who uses this)
- APEv2 REPLAYGAIN_* tags
- RVA tag in ID3v2.2
- TXX REPLAYGAIN_* tags in ID3v2.2
- RVAD tag in ID3v2.3
- RVA2 tag in ID3v2.4
- TXXX REPLAYGAIN_* tags in ID3v2.3 and ID3v2.4
Thus, if a file is tagged with ReplayGain data in TXXX frames, this information should always "win" if others are present.
loudgain concentrates on these TXXX REPLAYGAIN_* tags, and it won’t read, write or delete any of the others. (Well, except when deleting APEv2 tags, if so instructed.)
loudgain will also only write the two most modern ID3v2.3 or ID3v2.4 tag types (converting older tag types into the new format if needed).

Character encoding, or: Why does my smørrebrød look like "smÃ¸rrebrÃ¸d"?

Traditionally, character (text) encoding was complicated. Different operating systems used different encodings in different countries to represent national characters, and they would all be incompatible, or you’d have to transcode the text. Fortunately, Unicode and better encodings came along. Now we even have a character for a pile of poo: 💩!

The most widely used character encoding nowadays is UTF-8, an encoding that can represent all Unicode characters using 1–4 bytes each. This encoding is possible when using ID3v2.4 tags. But, alas, not on older operating systems and players. ID3v2.3 also doesn’t support UTF-8 encoding.

Fortunately, since the days of ID3v2.2, Unicode characters could be stored using other, more complicated ways:

ID3v2.2: UCS-2 (now obsolete old standard, 2 bytes/character, like in Windows/NT)
ID3v2.3: UTF-16 with BOM (byte order mark; $FF FE or $FE FF, like Windows 2000 and newer)
ID3v2.4: UTF-16 with BOM, UTF-16BE (big-endian) without BOM, or UTF-8

Additionally, all ID3 tag formats support ISO-8859-1 encoding, also known as Latin-1, a small superset of ASCII that supports a few extra European characters, 191 different characters in total.

To make things even more complicated, in ID3v2 type tags, each field (so-called "frame") can have a different encoding. So you could end up with a ID3v2.4-tagged MP3 file where the artist is encoded as UTF-8, the title encoded as UTF-16 and the REPLAYGAIN_TRACK_GAIN value encoded as ISO-8859-1, while the tags would still be valid. Imagine dragons …

Here’s the answer to above question, by the way: Either the (UTF-8-encoded) text "smørrebrød" was stored in a frame that was specified as having ISO-8859-1 encoding, or your player can’t handle the UTF-8 character set.

Since loudgain has to convert some tags when storing in ID3v2.3 or ID3v2.4 format, it follows some simple rules:

Don’t change more than needed.
When converting from ID3v1/ID3v1.1 tags:
- If there are ID3v2 tags of the same name in the file, those shall be preferred over the ID3v1 tags (due to length restrictions).
- Assume ID3v1 tags were stored with ISO-8859-1 encoding (the only legal encoding for ID3v1) and leave the resultant ID3v2.3/ID3v2.4 tag frame encoded as ISO-8859-1.
- Note: If you do not specify -S (--striptags) on the commandline, the old ID3v1 tags will be kept besides the new ID3v2 tags! I recommend using -S (--striptags) to avoid confusion.
When converting to ID3v2.4:
- Leave tag frame encodings as they are (ISO-8859-1 → ISO-8859-1, UTF-16 → UTF-16).
- Convert TYER (year) and TDAT (date) frames to TDRC (recording time).
- Convert TORY (original release year) to TDOR (original release time).
- Convert RVAD (relative volume adjustment) to RVA2.
When converting to ID3v2.3:
- If possible, leave tag frame encodings as they are (ISO-8859-1 → ISO-8859-1, UTF-16 → UTF-16).
- Convert UTF-16BE and UTF-8 encoded frames to UTF-16 with BOM.
- Convert TDRC (recording time) to TYER (year) and TDAT (date).
- Convert TDOR (original release time) to TORY (original release year).
- Convert RVA2 (relative volume adjustment 2) to RVAD.
REPLAYGAIN_* tags written by loudgain:
- Always stored with ISO-8859-1 encoding.

How I handle Opus (.opus) audio files

Opus only uses R128_TRACK_GAIN and (optionally) R128_ALBUM_GAIN as an additional offset to the header's 'output_gain'.
Encoders and muxes (should) set 'output_gain' to zero, so a non-zero 'output_gain' in the header is supposed to be a change after encoding/muxing.
We assume that FFmpeg's avformat does already apply 'output_gain' (???) so we get get pre-gained data and only have to calculate the difference.
Opus adheres to EBU-R128, so the loudness reference is always -23 LUFS. This means we have to adapt for possible -d n (--pregain=n) changes. This also means players have to add an extra +5 dB to reach the loudness ReplayGain 2.0 prescribes (-18 LUFS). IDJC, foobar2000 and several others already seem to handle this correctly (in newer versions).
Opus R128_* tags use ASCII-encoded Q7.8 numbers with max. 6 places including the minus sign, and no unit.
See https://en.wikipedia.org/wiki/Q_(number_format)
RFC 7845 states: "To avoid confusion with multiple normalization schemes, an Opus comment header SHOULD NOT contain any of the REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK, REPLAYGAIN_ALBUM_GAIN, or REPLAYGAIN_ALBUM_PEAK tags, […]"

So we actually remove REPLAYGAIN_* tags if any are present.
RFC 7845 states: "Peak normalizations are difficult to calculate reliably for lossy codecs because of variation in excursion heights due to decoder differences. In the authors' investigations, they were not applied consistently or broadly enough to merit inclusion here."

So we don’t store any "Peak" type tags. The (oversampled) true peak levels that libebur128 calculates for us are still used for clipping prevention if so requested. They are also shown in the output, just not stored into tags.
Tagging modes -s i, -s e, -s l all behave the same for Opus files.

If using foobar2000 (a very good player/organizer for Windows) and checking the ReplayGain 2 values, please be aware that …

foobar2000 shows Opus ReplayGain values in dB, already adjusted by +5 dB, so as to be more easily comparable to other files’ RG values.
loudgain’s values are still correct, and foobar2000 will play the files at the perfectly correct loudness.

Please give feedback on the issue tracker, so we can finalize loudgain's Opus support. Thanks!

How I handle ASF/WMA (.asf, .wma) audio files

Supported are WMAv1, WMAv2, WMA Pro and WMA Lossless formats. WMA Voice is currently not supported, since the FFmpeg libraries don’t (yet) decode it.
loudgain will neither read nor write the following Microsoft-specifc tags:
```
PeakValue
AverageLevel
WM/WMADRCAverageReference
WM/WMADRCPeakReference
WM/WMADRCAverageTarget
WM/WMADRCPeakTarget
```
These are used internally by Microsoft and the Windows Media Player.
Depending on the tagging mode, loudgain calculates and stores a selection of the following WMA tags:
```
REPLAYGAIN_TRACK_GAIN
REPLAYGAIN_TRACK_PEAK
REPLAYGAIN_TRACK_RANGE
REPLAYGAIN_ALBUM_GAIN
REPLAYGAIN_ALBUM_PEAK
REPLAYGAIN_ALBUM_RANGE
REPLAYGAIN_REFERENCE_LOUDNESS
```
The -L (--lowercase) switch will force these to be lowercase instead.

Uppercase vs. lowercase tags still seems to be a never-ending battle—when will players finally learn to handle these case-insensitively?

Here’s what I found for WMA:
- foobar2000 handles both upper- and lowercase tags correctly (tested on fb2k 1.4.6).
- Winamp handles both upper- and lowercase tags correctly (tested on Winamp 5.8).
- VLC requires uppercase tags (tested on VLC 3.0.8 "Vetinari").
- Kodi requires lowercase tags (tested on Kodi 17.6).
- Audacious seems to ignore both upper- and lowercase RG tags in WMA files (tested on Audacious 3.9).
- Clementine seems to ignore both upper- and lowercase RG tags in WMA files (tested on Clementine 1.3.1).
There’s an issue open for MusicBrainz Picard to also support these tags. Please vote for it.
Peak values are true peak values. Due to the better approximation of the real audio signal, they are expected to be larger than sample peak or RMS peak values. True peak values can be above 1.0.

How I handle WAV (.wav) audio files

Experimental support, use with care! Loudgain writes ID3v2 ReplayGain tags into the "ID3 " chunk. This is a format compatible with foobar2000, Mp3tag, VLC and some others.

Loudgain currently relies on TagLib to do the writing. In the current implementation
- the "ID3 " chunk may be after the "data" chunk (i.e., at the end of the file).
- the "ID3 " chunk may be "left over" even if all ID3v2 tags have been deleted.
Loudgain tries to keep all other chunks and tags intact, the -S (--striptags) option is ignored.
Since ID3v2 tags are written, the -L (--lowercase), -I 3 (--id3v2version=3) and -I 4 (--id3v2version=4) options function normally. For WAV files, it is recommended to use ID3v2.3 tags.
Uppercase vs. lowercase tags is still a problem:
- foobar2000 handles both upper- and lowercase tags correctly (tested on fb2k 1.4.6).
- VLC requires uppercase tags (tested on VLC 3.0.8 "Vetinari").
The Broadcast Wave File (BWF) extensions in the "bext" chunk are currently not written (but also not destroyed). This might change in a future version (at least for the loudness values of BWF v2).
ID3 vs. id3 chunk. In some cases, files might already contain an id3 (lowercase) chunk, or even both id3 and ID3 chunks. In such cases, loudgain will read ID3v2 tags from these chunks, try to merge them, and then remove the now obsolete id3 (lowercase) chunk in favour of one ID3 (uppercase) chunk.

Other potentially existing chunks like id32 or ID32 are ignored.

How I handle AIFF (.aiff, .aif, .snd) audio files

Experimental support, use with care! Loudgain writes ID3v2 ReplayGain tags into the "ID3 " chunk. This is a format compatible with foobar2000, Mp3tag, VLC and some others.

Note: TagLib versions before 1.12 could only write ID3v2.4 tags, albeit iTunes and dBPowerAmp may only handle ID3v2.2 or ID3v2.3 correctly. Starting with TagLib 1.12, loudgain supports selecting between ID3v2.3 and ID3v2.4 (default). Use the -I 3 (--id3v2version=3) and -I 4 (--id3v2version=4) commandline options for that.
Since ID3v2 tags are written, the -L (--lowercase) option functions normally.
The -S (--striptags) option will be ignored, even when specified.
Uppercase vs. lowercase tags is still a problem:
- foobar2000 handles both upper- and lowercase tags correctly (tested on fb2k 1.4.6).
- VLC requires uppercase tags (tested on VLC 3.0.8 "Vetinari").
ID3 vs. id3 chunk. In some cases, files might already contain an id3 (lowercase) chunk, or even both id3 and ID3 chunks. In such cases, loudgain will read ID3v2 tags from these chunks, try to merge them, and then remove the now obsolete id3 (lowercase) chunk in favour of one ID3 (uppercase) chunk.

Other potentially existing chunks like id32 or ID32 are ignored.

How I handle WavPack (.wv) audio files

Loudgain writes APEv2 ReplayGain tags to WavPack files. This is a format compatible with foobar2000, Mp3tag, VLC and nearly all others.
Per default, loudgain keeps other tags (ID3) intact, but I don’t recommend using these. The -S (--striptags) option allows to remove ID3v1 tags.
In theory, lowercase and even mixed-case tags can be written into APEv2 tags, but the WavPack authors have thankfully specified that the tags must be read in a case-insensitive manner. That’s why loudgain ignores the -L (--lowercase) option and only writes standard-compatible uppercase tags. (Existing lowercase tags will be removed to avoid confusion and potential problems.)
loudgain works on the »one file/one program« basis, and the EBU speaks of an »integrated program loudness« anyway. So possibly embedded cue sheets are ignored.

How I handle APE (.ape) audio files

Loudgain writes APEv2 ReplayGain tags to APE files. This is a format compatible with foobar2000, Mp3tag, VLC and nearly all others.
Per default, loudgain keeps other tags (ID3) intact, but I don’t recommend using these. The -S (--striptags) option allows to remove ID3v1 tags.
In theory, lowercase and even mixed-case tags can be written into APEv2 tags, but duplicates with different case aren’t allowed. Applications should read APE tags in a case-insensitive manner. That’s why loudgain ignores the -L (--lowercase) option for APE files and only writes uppercase tags. (Existing lowercase/mixed-case ReplayGain tags will be removed to avoid confusion and potential problems.)

loudgain makes it easy following the »Gold Standard«

Here are my personal recommendations for being (almost) universally compatible:

Use loudgain on a »one album per folder« basis, standard RG2 settings but lowercase ReplayGain tags, clipping prevention on, strip obsolete tag types from MP3 and WavPack files, use ID3v2.3 for MP3s, store extended tags:

$ loudgain -a -k -s e *.flac
$ loudgain -a -k -s e *.ogg
$ loudgain -I3 -S -L -a -k -s e *.mp3
$ loudgain -L -a -k -s e *.m4a
$ loudgain -a -k -s e *.opus
$ loudgain -L -a -k -s e *.wma
$ loudgain -I3 -L -a -k -s e *.wav
$ loudgain -I3 -L -a -k -s e *.aiff
$ loudgain -S -a -k -s e *.wv
$ loudgain -S -a -k -s e *.ape

I’ve been happy with these settings for many, many years now, and colleagues have been using these settings on a cumulated base of almost a million tracks.

If you want to adjust lots of files (organized in album folders), please check out rgbpm, a simple bash script file in the bin/ folder, and adjust it to your needs. (Hint: Copy this to your personal ~/bin folder and chmod +x rgbpm it so you can use it as a simple command.)

Happy replaygaining!

Quality over speed

loudgain is designed to do its thing correctly, sometimes at the sacrifice of raw speed.

Here are a few—probably non-representative—measurements from one of my machines, a Dell Optiplex 7010 from around 2013 with a 4TB built-in hard disc, still running Ubuntu 14.04 and thus using the slow-loading loudgain.static build:

Mixed sample collection of FLAC, MP3 and MP4 (1,924 files, 12.2GB): 73 minutes, averaging around 2.3 seconds/file.
Compared with early versions, version 0.5.1 sped up scanning and tagging a real huge collection of almost 150,000 titles and nearly 2TB from almost 7 days to 3 days 20 hours. Fortunately, this usually needs to be done only once.
I used the rgbpm script for these tests.

Some notes on speed which are generally true, not just for loudgain:

Preferably, use a (fast) local disc for the music to be tagged. (Later copying it somewhere else, like a NAS, is no problem.)
If anyhow possible, do not use external discs connected through USB-2.
If you need to connect an external "Music" disc, prefer (in order) eSATA – USB3+UASP – USB3.
loudgain will work on network (even Wi-Fi) mounts but chances are it’ll be brutally sloooooooow …

Your mileage may vary. Quality over speed. ;-)

AUTHORS

Alessandro Ghedini [email protected]
Matthias C. Hormann [email protected]

COPYRIGHT

See COPYING for the license.

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

Moonbase59 / loudgain

Labels

Projects that are alternatives of or similar to loudgain

loudgain

Table of Contents

MAIN FEATURES

NEWS, CHANGELOG

GETTING STARTED

Installation using Homebrew (Mac & Linux)

Installation on Windows 10 (Linux bash)

DEPENDENCIES

BUILDING

Mass tagging

Avoiding recalculation

User example script

TECHNICAL DETAILS (advanced users stuff)

Things in the binfolder

rgbpm – Folder-based loudness and BPM scanning

loudgain.static

Uppercase or lowercase 'REPLAYGAIN_*' tags?

Tags written (and/or deleted)

Default mode -s i (--tag-mode i)

Enhanced mode -s e (--tag-mode e)

"LU" units mode -s l (--tag-mode l)

Track and Album Peak

MP3 ID3v2.3, ID3v2.4, and APE tags

Force writing ID3v2.3 or ID3v2.4 tags

Strip unwanted ID3v1/APEv2 tags -S (--striptags)

Analyze audio files and output to CSV

Example: Mary Black’s album »No Frontiers« (1989)

Write a simple analysis to a CSV file

Analyze again, using clipping prevention

Just for fun: What if we really followed the EBU R128 recommendation?

Time to save the tags and listen to the music!

Clipping prevention

Here be dragons: A word on MP3 files and ID3 tags

Some basic recommendations

A zillion ways to store loudness/gaining information

Character encoding, or: Why does my smørrebrød look like "smÃ¸rrebrÃ¸d"?

How I handle Opus (.opus) audio files

How I handle ASF/WMA (.asf, .wma) audio files

How I handle WAV (.wav) audio files

How I handle AIFF (.aiff, .aif, .snd) audio files

How I handle WavPack (.wv) audio files

How I handle APE (.ape) audio files

loudgain makes it easy following the »Gold Standard«

Quality over speed

AUTHORS

COPYRIGHT

Things in the `bin`folder

Default mode `-s i` (`--tag-mode i`)

Enhanced mode `-s e` (`--tag-mode e`)

"LU" units mode `-s l` (`--tag-mode l`)

Strip unwanted ID3v1/APEv2 tags `-S` (`--striptags`)