feat: level the mirror's volume with ReplayGain tags

Rockbox applies the offset a ReplayGain tag carries but has no loudness
analysis of its own, so an untagged mirror plays every album at whatever
level it was mastered to.

Albums are measured with rsgain once their tracks are in place, album gain
and track gain both, leaving the device to choose between them. An album is
re-measured as a whole whenever it gains, loses or replaces a track, because
album gain is a property of all of its tracks and one new track makes the
value stored on every sibling wrong.

rsgain runs with --preserve-mtimes. Staleness here is an mtime comparison
and tagging rewrites the file, so without it every levelled track would look
newer than its source and the next pass would re-encode the whole library.

Whether a file has already been levelled is decided by walking its ID3v2
frame headers and seeking over the bodies. Cover art is embedded in every
mirror file, so reading the tag whole would turn an idle pass into a full
read of the library.

A missing rsgain is reported and then left alone rather than failing the
pass: the mirror is still correct audio in the right place.

Two existing tests move with the change. ffprobe's csv writer renders the
ReplayGain side data as a trailing empty field, and a copied MP3 now differs
from its source in the container while carrying identical audio.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -22,6 +22,7 @@ remembering to do anything.
 | Mirror up to date                | skip                                     |
 | Source is already MP3            | copy verbatim                            |
 | Source gone                      | delete the mirror file, prune empty dirs |
+| An album gained or lost a track  | re-measure its ReplayGain, tags only     |
 
 Freshness is modification time: an encoded file is stamped with its source's
 mtime, so a file is stale exactly when the two differ. There is no database to
@@ -94,6 +95,7 @@ music-mirror --source /music --mirror /music-mp3 --subdir "Artist/Album"
 | `--interval` | `MUSIC_MIRROR_INTERVAL` | unset     | Repeat forever, e.g. `45m`, `6h`, `1d`         |
 | `--subdir`   | —                       | unset     | Limit the pass to one directory; skips pruning |
 | `--fat32-safe` | `MUSIC_MIRROR_FAT32_SAFE` | off     | Name files so a FAT32 device accepts them      |
+| `--no-replaygain` | `MUSIC_MIRROR_REPLAYGAIN` | on   | Write ReplayGain tags; set the variable to `0` to skip |
 | `--no-prune` | —                       | off       | Keep mirror files whose source has gone        |
 | `--dry-run`  | —                       | off       | Report what would change, write nothing        |
 
@@ -114,7 +116,9 @@ The first full pass is the expensive one; after that only new and changed files
 are touched. Lower `MUSIC_MIRROR_JOBS` if you would rather the NAS stayed
 responsive than finished sooner.
 
-Requires `ffmpeg` and `ffprobe` on `PATH`. The container image provides both.
+Requires `ffmpeg` and `ffprobe` on `PATH`, and `rsgain` for volume levelling.
+The container image provides all three. A missing `rsgain` is reported once per
+pass and costs the ReplayGain tags; everything else still runs.
 
 ## Running it on TrueNAS Scale
 
@@ -347,6 +351,8 @@ docker build --target test .   # what CI runs
 pytest                         # needs ffmpeg and pytest on PATH
 ```
 
+The ReplayGain tests need `rsgain` as well and skip without it.
+
 The suite runs real ffmpeg encodes rather than mocking them. The interesting
 failures are in what ffmpeg actually does with tags, cover art and container
 formats, and a mock cannot fail that way — which is also why CI runs the tests
@@ -358,7 +364,7 @@ Run them directly instead if you prefer; they skip when ffmpeg is absent. On a
 Nix machine:
 
 ```sh
-nix shell nixpkgs#python3Packages.pytest nixpkgs#ffmpeg -c pytest
+nix shell nixpkgs#python3Packages.pytest nixpkgs#ffmpeg nixpkgs#rsgain -c pytest
 ```
 
 ## FAT32 and Rockbox
@@ -448,6 +454,40 @@ firmware reads the embedded one; Rockbox reads the file. Both are satisfied.
 A cover left behind in a directory whose tracks have all gone is pruned, or the
 directory would never look empty and never be removed.
 
+### Volume levelling
+
+Rockbox can level the volume between tracks, but only from tags. It applies the
+offset a ReplayGain tag carries and has no loudness analysis of its own, so a
+mirror without those tags plays every album at whatever level it was mastered
+to — and a 2008 remaster next to a 1972 pressing is a reach for the volume
+wheel on every track change.
+
+The tags are therefore written here, with `rsgain`, once an album's tracks are
+in place. Both album gain and track gain are measured: album gain preserves the
+quiet track that a record is supposed to have, track gain is the one that makes
+sense on shuffle, and which of them is used is the device's decision, not this
+one.
+
+Turn it on at the player end under **Settings → Playback Settings →
+Replaygain**:
+
+| Setting          | Suggested            | Why                                                       |
+| ---------------- | -------------------- | --------------------------------------------------------- |
+| Replaygain type  | `Album Gain`, or `Track Gain if Shuffling` | Keeps a record's own dynamics; the second switches per mode |
+| Prevent clipping | `Yes`                | Uses the peak tags to back off rather than distort         |
+| Pre-amp          | `0 dB`               | The reference level is already −18 LUFS; move it only if the result is too quiet |
+
+Measuring costs a full decode of every track, so the first pass after enabling
+it takes roughly as long as the original encode did. After that only albums
+that gained, lost or replaced a track are re-measured. An album is re-measured
+as a whole, because album gain is a property of all of its tracks and one new
+track makes the value stored on every sibling wrong.
+
+Tagging rewrites the file, and staleness here is an mtime comparison, so
+`rsgain` is run with `--preserve-mtimes`. Without it every levelled track would
+look newer than its source and the next pass would re-encode the entire
+library.
+
 ## Getting the result onto an iPod
 
 The mirror is just a directory of MP3s, so any client will do:
@@ -487,6 +527,6 @@ The mirror is just a directory of MP3s, so any client will do:
 Neither client transcodes at sync time; they copy finished MP3s.
 
 Two device-side details worth knowing: the iPod reads cover art from the file's
-tags and ignores `folder.jpg`, which is why art is embedded here; and volume
-levelling on the device uses iTunes' Soundcheck tag, not ReplayGain, so
-ReplayGain tags in the source are not carried over as such.
+tags and ignores `folder.jpg`, which is why art is embedded here; and the Apple
+firmware levels volume from iTunes' Soundcheck tag rather than ReplayGain, so
+the tags written here do nothing until the iPod is running Rockbox.