From ebd0e70012f7e7d55e6fd9cbb564b9e4a5fdab1a Mon Sep 17 00:00:00 2001
From: m_igashi <@M_Igashi>
Date: Wed, 14 Jan 2026 01:37:55 +0100
Subject: [PATCH] Add mp3rgain support to ReplayGain command backend

mp3rgain is a modern Rust rewrite of mp3gain that provides:
- CLI-compatible drop-in replacement for mp3gain
- Support for both MP3 and AAC/M4A formats (like aacgain)
- Fixes for CVE-2021-34085 (Critical, CVSS 9.8) and CVE-2019-18359 (Medium)
- Memory-safe implementation in Rust
- Works on modern systems (Windows 11, macOS Apple Silicon)

Changes:
- Add mp3rgain to the command search list (prioritized first)
- Update format_supported() with more robust command name detection
  using os.path.basename() and startswith() instead of substring matching
- Update documentation with installation instructions

See: https://github.com/M-Igashi/mp3rgain
---
 beetsplug/replaygain.py     | 20 ++++++++++++++------
 docs/plugins/replaygain.rst | 32 +++++++++++++++++++++-----------
 2 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/beetsplug/replaygain.py b/beetsplug/replaygain.py
index 4e8b429ea..af5dcd001 100644
--- a/beetsplug/replaygain.py
+++ b/beetsplug/replaygain.py
@@ -565,7 +565,7 @@ class CommandBackend(Backend):
                 )
         else:
             # Check whether the program is in $PATH.
-            for cmd in ("mp3gain", "aacgain"):
+            for cmd in ("mp3rgain", "mp3gain", "aacgain"):
                 try:
                     call([cmd, "-v"], self._log)
                     self.command = cmd
@@ -573,7 +573,7 @@ class CommandBackend(Backend):
                     pass
         if not self.command:
             raise FatalReplayGainError(
-                "no replaygain command found: install mp3gain or aacgain"
+                "no replaygain command found: install mp3rgain, mp3gain, or aacgain"
             )
 
         self.noclip = config["noclip"].get(bool)
@@ -608,10 +608,18 @@ class CommandBackend(Backend):
 
     def format_supported(self, item: Item) -> bool:
         """Checks whether the given item is supported by the selected tool."""
-        if "mp3gain" in self.command and item.format != "MP3":
-            return False
-        elif "aacgain" in self.command and item.format not in ("MP3", "AAC"):
-            return False
+        # Get the base name of the command for comparison
+        cmd_name = os.path.basename(self.command).lower()
+        
+        if cmd_name.startswith("mp3rgain"):
+            # mp3rgain supports MP3 and AAC/M4A formats
+            return item.format in ("MP3", "AAC")
+        elif cmd_name.startswith("aacgain"):
+            # aacgain supports MP3 and AAC formats
+            return item.format in ("MP3", "AAC")
+        elif cmd_name.startswith("mp3gain"):
+            # mp3gain only supports MP3
+            return item.format == "MP3"
         return True
 
     def compute_gain(
diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst
index c7e51d25d..16f4e3088 100644
--- a/docs/plugins/replaygain.rst
+++ b/docs/plugins/replaygain.rst
@@ -10,9 +10,9 @@ Installation
 ------------
 
 This plugin can use one of many backends to compute the ReplayGain values:
-GStreamer, mp3gain (and its cousin, aacgain), Python Audio Tools or ffmpeg.
-ffmpeg and mp3gain can be easier to install. mp3gain supports less audio formats
-than the other backend.
+GStreamer, mp3gain (and its cousins, aacgain and mp3rgain), Python Audio Tools
+or ffmpeg. ffmpeg and mp3gain can be easier to install. mp3gain supports fewer
+audio formats than the other backends.
 
 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
@@ -51,16 +51,24 @@ configuration file:
 
 The GStreamer backend does not support parallel analysis.
 
-mp3gain and aacgain
-~~~~~~~~~~~~~~~~~~~
+mp3gain, aacgain, and mp3rgain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to use this backend, you will need to install the mp3gain_ command-line
-tool or the aacgain_ fork thereof. Here are some hints:
+tool, the aacgain_ fork, or mp3rgain_. Here are some hints:
 
-- On Mac OS X, you can use Homebrew_. Type ``brew install aacgain``.
+- On Mac OS X, you can use Homebrew_. Type ``brew install aacgain`` or
+  ``brew install mp3rgain``.
 - 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_.
+  example, you can run ``apt-get install mp3gain``. Alternatively, mp3rgain is
+  available via Nix (``nix-env -iA nixpkgs.mp3rgain``) or AUR for Arch Linux.
+- On Windows, download and install mp3rgain_ (recommended) or the original
+  mp3gain_.
+
+mp3rgain_ is a modern Rust rewrite of mp3gain that also supports AAC/M4A files.
+It addresses security vulnerabilities (CVE-2021-34085, CVE-2019-18359) present
+in the original mp3gain and works on modern systems including Windows 11 and
+macOS with Apple Silicon.
 
 .. _aacgain: https://aacgain.altosdesign.com
 
@@ -68,6 +76,8 @@ tool or the aacgain_ fork thereof. Here are some hints:
 
 .. _mp3gain: http://mp3gain.sourceforge.net/download.php
 
+.. _mp3rgain: https://github.com/M-Igashi/mp3rgain
+
 Then, enable the plugin (see :ref:`using-plugins`) and specify the "command"
 backend in your configuration file:
 
@@ -144,8 +154,8 @@ file. The available options are:
 
 These options only work with the "command" backend:
 
-- **command**: The path to the ``mp3gain`` or ``aacgain`` executable (if beets
-  cannot find it by itself). For example:
+- **command**: The path to the ``mp3rgain``, ``mp3gain``, or ``aacgain``
+  executable (if beets cannot find it by itself). For example:
   ``/Applications/MacMP3Gain.app/Contents/Resources/aacgain``. Default: Search
   in your ``$PATH``.
 - **noclip**: Reduce the amount of ReplayGain adjustment to whatever amount