Rsgain

rsgain

{{{logo}}}
Default help screen in a Linux terminal
Developer(s)	complexlogic
Release information
Initial release	10 May 2022
Stable release	3.1.1 (November 15, 2022)
Preview release	{{{preview_release}}}
Compatibility
Operating system	Windows, macOS, Linux, BSD
Additional information
Use	ReplayGain tagging
License	BSD license
Website	[1]

rsgain (really simple gain) is a free and open source ReplayGain 2.0 tagging utility for Windows, macOS, and Linux. rsgain applies loudness metadata tags to your files, while leaving the audio stream untouched. A ReplayGain-compatible player will dynamically adjust the volume of your tagged files during playback.

rsgain is designed with a "batteries included" philosophy, allowing a user to scan their entire music library without requiring external scripts or other tools. It aims to strike the perfect balance between power and simplicity by providing multiple user interfaces. See Usage for more information.

rsgain is the backend for the MusicBrainz Picard ReplayGain 2.0 plugin. Users that are not comfortable with command line interfaces may prefer this method since the plugin provides a GUI frontend to rsgain. See MusicBrainz Picard Plugin for more information.

Installation

rsgain is available in source form on all platforms, and executable form on some platforms.

Windows

rsgain is compatible with Windows 10 and later. Download the win64 .zip file from the latest release on GitHub, and extract its contents to a directory of your choice.

It is recommended to add the directory to your Path system environment variable so you can invoke the program with the rsgain command instead of the path to its .exe file. In the Windows taskbar search, type "env", then select "Edit the system environment variables". In the resulting window, click the "Environment variables" button. In the next window under "System variables", select "Path", then press Edit. Add the folder that you extracted rsgain.exe to in the previous step.

macOS

There is a Homebrew formula available for macOS users. Make sure you have Homebrew and the latest available Xcode installed. Execute the following command to install:

brew install complexlogic/tap/rsgain

Linux

An amd64 .deb package is provided on the GitHub release page. It is installable on Debian Bullseye and later, Ubuntu 21.04 and later. There is also a .rpm package for Fedora users. An AUR package is available for Arch/Manjaro users.

Users of other distros will need to build from source. See the build instructions on GitHub.

FreeBSD

Available via ports tree or using packages (2023Q1 and later) as listed below: cd /usr/ports/audio/rsgain && make install clean pkg install rsgain

Format Support

rsgain has support for the following file formats:

• MP2/MP3
• FLAC
• Ogg (Vorbis, Speex)
• Opus
• M4A (AAC, ALAC)
• WMA
• Musepack
• WAV
• AIFF
• Wavpack
• Monkey's Audio

Usage

rsgain contains two separate user interfaces: Easy Mode and Custom Mode. The distinction between the two modes is rooted in the history of ReplayGain utilities.

Legacy ReplayGain tagging utilities such as mp3gain did not support recursive directory-based scanning. The user was required to manually specify a list of files on the command line, preceded by options which were numerous and complex. This interface provided a lot of power and flexibility, but it wasn't particularly user friendly. Performing a full library scan typically required the user to supplement the program with a wrapper script that traversed the directory tree and detected the files.

rsgain's Easy Mode is that wrapper script; the functionality is built-in to the program. In Easy Mode, the user simply points the program to their library and it will be recursively scanned with all recommended settings enabled by default.

The legacy-style interface has been retained as "Custom Mode" for users that require a higher level of control.

Easy Mode

Easy Mode recursively scans your entire music library using the recommended settings for each file type. You can use Easy Mode if the following conditions apply:

• Your music library is organized by album, i.e. each album has its own folder
• In each album folder, all audio files are of the same type. It is acceptable to have non-audio files mixed in such as log files or artwork, but if multiple audio file types are detected, the folder will not be scanned.

Easy Mode is invoked with the command rsgain easy followed by the root of the directory you want to scan, e.g.:

rsgain easy /path/to/music/library

rsgain easy "C:\path\to\music library"

This is all that is required for most users. Advanced users should see the Scan Presets section for more information about the default settings and how to override them, if desired.

Multithreaded Scanning

Easy Mode includes optional multithreaded operation to speed up the duration of a scan. Use the -m option, followed by the number of threads to create. The number of threads must not exceed the number that your CPU supports. For example, if you have a CPU with 4 threads:

rsgain easy -m 4 /path/to/music/library

If you don't know how many threads your CPU has, you can also specify -m MAX and rsgain will use the number provided by your operating system. This is useful for writing scripts where the hardware properties of the target machine are unknown.

Parallel scan jobs are generated on a per-directory basis, not a per-file basis. If you request 4 threads but there is only 1 directory to scan, a single thread will be working and the other 3 will sit idle the entire time. Multithreaded mode is optimized for scanning a very large number of directories. It is recommended to use multithreaded mode for full library scans and the default single threaded mode when incrementally adding 1 or 2 albums to your library.

The speed gains offered by multithreaded scanning are significant. With -m 4 or higher, you can typically expect to see a 50-80% reduction in total scan time, depending on your hardware, settings, and library composition.

Skip Files with Existing Tags

rsgain has an option which will skip files with existing ReplayGain information, invoked by passing -S or --skip-existing. When enabled, rsgain will check whether the given file has a REPLAYGAIN_TRACK_GAIN tag, and skip scanning any files that do. If album tags are enabled, the files in the list will be judged collectively, i.e. if a single file is missing ReplayGain info, then all of them will be scanned.

This feature merely checks for the existence of the tags, and does not verify that the tags are complete, and are compatible with your current settings, e.g. target loudness. You should use this feature only if you are confident in the integrity of the files in the directory to be scanned. It's generally not a good idea to run this on files that you've recently download from the internet, which may have pre-existing ReplayGain information that was tagged by a different scanner.

Logging

You can use the -O option to enable scan logs. The program will save a tab-delimited file titled replaygain.csv with the scan results for every directory it scans. The log files can be viewed in a spreadsheet application such as Microsoft Excel or LibreOffice Calc.

Scan Presets

Easy Mode scans files with the following settings by default:

• -18 LUFS target loudness
• Album tags enabled
• Sample peak calculations for peak tags
• Clipping protection enabled for positive gain values only (0 dB max peak)
• Standard uppercase tags for all formats
• ID3v2.3 tags for ID3 formats
• Standard ReplayGain tags for Opus files

These settings are recommended for maximum compatibility with modern players. However, if you need one or more of the settings changed, you can use a preset file.

A preset file is an INI-formatted configuration file that contains sections enclosed in square brackets, and each section contains key=value pairs that correspond to settings. The first section in a presets file is titled "Global" and contains settings that will be applied to every format. The remaining sections pertain to a particular audio format, and the settings within them will only be applied to that format. This allows the user to define settings on a per-format basis. If a setting in the "Global" section is in conflict with one in the format-specific section, the format-specific value will always take precedence.

A preset is specified with the -p option, followed by the path to a preset file or a preset name. A preset name is the filename of a preset without the directory or .ini file extension; rsgain will search the default preset location(s) for the file based on your platform:

• On Windows, the folder presets in the same folder that contains rsgain.exe
• On Unix platforms, rsgain will search first in the user home directory: ~/Library/rsgain/presets on Mac and ~/.config/rsgain/presets on Linux (you need to create these directories if they don't already exist). If the requested preset name is not found in the home directory, rsgain will search <install prefix>/share/rsgain/presets

For example, rsgain ships with a preset ebur128.ini, which will scan files based on the EBU R 128 recommendations. You can invoke this preset with -p ebur128. rsgain also ships with a preset default.ini, which is pre-populated with all of the default settings. This preset is not intended to be used directly, but rather to serve as a base for users to create their own presets. As such, it is not recommended to overwrite it. Instead, save a copy when using it as a base.

The settings in a preset file are applied in an "overrides" fashion. In other words, any settings or formats you're not interested in can simply be deleted from the preset and the defaults will be used instead.

Custom Mode

Custom Mode provides a more complex command line syntax that is similar in nature to mp3gain, loudgain, and other legacy ReplayGain scanners. Only the most basic settings are enabled by default. Unlike Easy Mode, Custom Mode works with files, not directories. If you want recursive directory-based scanning, you will need to write a wrapper script.

Custom Mode is invoked with rsgain custom followed by options and a list of files to scan. For example, scan and tag a short list of MP3 files with album tags enabled:

rsgain custom -a -s i file1.mp3 file2.mp3 file3.mp3

See the command line help for all available options:

Usage: rsgain custom [OPTIONS] FILES...
  Custom Mode allows the user to specify the options to scan the files with. The
  list of files to scan must be listed explicitly after the options.

Options:
  -h,   --help              Show this help.

  -a,   --album             Calculate album gain and peak.
  -S,   --skip-existing     Don't scan files with existing ReplayGain information.

  -s s, --tagmode=s         Scan files but don't write ReplayGain tags (default).
  -s d, --tagmode=d         Delete ReplayGain tags from files.
  -s i, --tagmode=i         Scan and write ReplayGain 2.0 tags to files.

  -l n, --loudness=n        Use n LUFS as target loudness (-30 ≤ n ≤ -5).

  -c n, --clip-mode=n       No clipping protection (default).
  -c p, --clip-mode=p       Clipping protection enabled for positive gain values only.
  -c a, --clip-mode=a       Clipping protection always enabled.
  -m n, --max-peak=n        Use max peak level n dB for clipping protection.
  -t,   --true-peak         Use true peak for peak calculations.

  -L,   --lowercase         Write lowercase tags (MP2/MP3/MP4/WMA/WAV/AIFF).
                            This is non-standard but sometimes needed.
  -I 3, --id3v2-version=3   Write ID3v2.3 tags to MP2/MP3/WAV/AIFF (default).
  -I 4, --id3v2-version=4   Write ID3v2.4 tags to MP2/MP3/WAV/AIFF.

  -o d, --opus-mode=d       Write standard ReplayGain tags, clear header output gain (default).
  -o r, --opus-mode=r       Write R128_*_GAIN tags, clear header output gain.
  -o t, --opus-mode=t       Write track gain to header output gain.
  -o a, --opus-mode=a       Write album gain to header output gain.

  -O,   --output            Output tab-delimited scan data to stdout.
  -q,   --quiet             Don't print scanning status messages.

Please report any issues to https://github.com/complexlogic/rsgain/issues

MusicBrainz Picard Plugin

MusicBrainz Picard is a free, cross-platform music tagging application. Picard features a robust plugin ecosystem that greatly extends its functionality. rsgain serves as the backend for the ReplayGain 2.0 plugin, which is available from the official plugins repository. Users that prefer a graphical interface over a command line interface can use this plugin to scan their music library.

To install the plugin, navigate to the Options menu in Picard. Select "Plugins" in the sidebar, then find "ReplayGain 2.0" and click the download button. The plugin itself does not include rsgain; you'll still need to download and install rsgain separately per the Installation section for your chosen platform.

You need to set the path to rsgain in the plugin settings. This field is pre-populated with the rsgain command. On Unix platforms, programs are typically installed into a directory that's already in your PATH, so no further action is necessary in that case. On Windows, you will need to either manually add the folder containing rsgain to your Path as per the installation instructions, or use the exact path to rsgain.exe in the plugin settings.

To use the plugin, add files to Picard and associate them with a release (so the files are in the right window). The plugin can scan albums or individual tracks. Select one or more albums or tracks, then right click and select "Plugins->Calculate ReplayGain" from the context menu. This calculates the ReplayGain information for the selected items, but does not tag the files. The new tags are available for viewing in the metadata window at the bottom. Click the save button to write the new tags to file.

See also

• ReplayGain
• ReplayGain 2.0 specification

External links

• rsgain GitHub page
• EBU R128