COLLECTIONGAIN(1)

📦 version 1.1.1, in ubuntu jammy

💖 COLLECTIONGAIN 💖

okay bestie, gather round, because this is the glow-up your music library has been waiting for. this is collectiongain from the rgain manual, section 1, and she is that girl. 🎀

✨ NAME ✨

collectiongain — the large scale Replay Gain calculating tool. she does the most, for your whole collection, at once. periodt. 👑

🌸 SYNOPSIS 🌸

collectiongain [options] music_dir
collectiongain --help
collectiongain --version

like, you point her at a music_dir and hand her some options, or you just ask for --help / --version if you're feeling lowkey and just want the tea. 🫶

🦋 DESCRIPTION 🦋

so here's the vibe: collectiongain is a script that calculates the Replay Gain values for a large set of music files sitting inside music_dir. not one song, not two songs — the whole thing, no cap. 💅

the way she works: files that belong to the same album get identified by their file tags, and then album Replay Gain data gets calculated for them. album-level accuracy, bestie. it's giving organized. ✨

🎀 OPTIONS 🎀

  • --version — shows you the version of the software. short, sweet, iconic. 🌈
  • -h, --help — prints a short summary of all the available options. your little cheat sheet. 🍓
  • -f, --force — recalculates Replay Gain even if the file already has gain info in it. sometimes you just gotta start over, bestie. 🔥
  • -d, --dry-run — does not actually modify any files. a look-but-don't-touch moment. 🙈
  • -r REF, --reference-loudness=REF — sets the reference loudness to REF dB. default is 89 dB. ⭐
  • --mp3-format=MP3_FORMAT — picks the Replay Gain data format used for MP3 files. the default setting should play nice with most decent software music players, so honestly you generally do not need to mess with this one. more deets down below. 👇
  • --ignore-cache — do not use the file cache at all. zero cache, all vibes. 💀
  • --regain — fully reprocesses everything. it's literally the same as --force --ignore-cache. 👑
  • -j JOBS, --jobs=JOBS — runs JOBS jobs simultaneously. must be >= 1. by default it's set to the number of CPU cores in your system, because she wants to give you the best performance possible. main character energy fr fr. 🔥

🌈 MP3 FORMATS 🌈

okay so, proper Replay Gain support for MP3 files? it's a bit of a mess, ngl. let me explain.

on one hand, there's the mp3gain application [1], which was relatively widely used back in the day (honestly, no clue if it still is). it works by directly modifying the audio data — which has the upside that it works with pretty much any player, but the downside that you have to decide ahead of time whether you want track gain or album gain. also it's just not very elegant. 😭

on the other hand, there are at least two commonly used ways to store proper Replay Gain information in ID3v2 tags [2].

now here's the good part: in general you don't have to worry about any of this when you use this package. by default, replaygain and collectiongain will read and write Replay Gain information in the two most commonly used formats. but if for whatever reason you need more control over the MP3 Replay Gain info, you can use the --mp3-format option (both programs support it) to change the behaviour. the possible choices are:

  • replaygain.org (alias: fb2k) — Replay Gain information is stored in ID3v2 TXXX frames. this format is specified on the replaygain.org website as the recommended format for MP3 files. notably, it's also the format used by the foobar2000 music player for Windows [3]. ✨
  • legacy (alias: ql) — Replay Gain information is stored in ID3v2.4 RVA2 frames. replaygain.org describes this one as "legacy"; however, it's still the primary format for at least the Quod Libet music player [4] and possibly others too. ⚠️ heads up though: this format does not support volume adjustments of more than 64 dB. if the calculated gain value is smaller than -64 dB or greater than or equal to +64 dB, it gets clamped to those limit values. so yeah, know that going in. 💀
  • default — this is the default implementation used by both replaygain and collectiongain. when writing Replay Gain data, both the replaygain.org format and the legacy format get written. as for reading: if a file contains data in both formats, both data sets are read and then compared. if they match up, that Replay Gain information is returned for the file. but if they don't match, no Replay Gain data is returned at all — which is the signal that this file does not contain valid (read: consistent) Replay Gain information. consistency check, bestie. she's not playing. 👑
  • [1] http://mp3gain.sourceforce.net
  • [2] http://wiki.hydrogenaudio.org/index.php?title=ReplayGain_specification#ID3v2
  • [3] http://foobar2000.org
  • [4] http://code.google.com/p/quodlibet

💜 SEE ALSO 💜

replaygain(1) — her sister, for when you're doing one thing at a time instead of the whole collection. 🫶

and that's the whole page, bestie!! 🌸 this was version 1.1.1, and it's the COLLECTIONGAIN(1) page from the rgain manual. go calculate some gains, you absolute icon. 💅✨

📦 where this page comes from