music-mirror/README.md

music-mirror

Maintain a lossy MP3 mirror of a lossless music library.

Walks a source library and reproduces it, path for path, as MP3 in a separate tree. Tags and cover art are carried across; sources that are already MP3 are copied rather than re-encoded; mirror files whose source has been deleted are removed. The source library is never written to — it is mounted read-only in the supplied compose file, and nothing in the code opens it for writing.

The intended use is an iPod. Apple's Music app cannot read FLAC at all, so a converted copy has to exist somewhere; this keeps that copy next to the library on a NAS instead of on a laptop, and keeps it current without a human remembering to do anything.

How it decides what to do

Situation	Action
No mirror file	encode
Source modified since the mirror	re-encode (a Lidarr quality upgrade)
Mirror up to date	skip
Source is already MP3	copy verbatim
Source gone	delete the mirror file, prune empty dirs

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 fall out of step with the library, which matters when something else — Lidarr, in this case — is the thing that owns and reorganises it.

Encodes are written to a temporary file and renamed into place, so an interrupted run cannot leave a truncated MP3 that the next run mistakes for finished work. A lock file in the mirror root stops two passes overlapping.

Usage

music-mirror --source /music --mirror /music-mp3            # one pass
music-mirror --source /music --mirror /music-mp3 --interval 6h   # keep running
music-mirror --source /music --mirror /music-mp3 --dry-run  # report only
music-mirror --source /music --mirror /music-mp3 --subdir "Artist/Album"

Option	Environment variable	Default	Meaning
--source	MUSIC_MIRROR_SOURCE	—	Root of the lossless library, read-only
--mirror	MUSIC_MIRROR_MIRROR	—	Root of the MP3 mirror
--quality	MUSIC_MIRROR_QUALITY	V0	LAME VBR level V0–V9, or kbps e.g. 256
--jobs	MUSIC_MIRROR_JOBS	CPU count	Concurrent encodes
--interval	MUSIC_MIRROR_INTERVAL	unset	Repeat forever, e.g. 45m, 6h, 1d
--subdir	—	unset	Limit the pass to one directory; skips pruning
--no-prune	—	off	Keep mirror files whose source has gone
--dry-run	—	off	Report what would change, write nothing

--subdir never prunes: a partial pass cannot tell an orphan from a file outside its own scope.

Requires ffmpeg and ffprobe on PATH. The container and the Nix package both provide them.

Running it on TrueNAS Scale

compose.yaml is a Custom App definition. Adjust the two host paths and the user: to match your pool, then add it as a custom app. The image is published to this Gitea's registry on every release:

code.emmathe.dev/lyrathorpe/music-mirror:latest

Tags are latest, the full version, and the truncated major.minor and major forms; builds that are not releases are published as sha-<short>.

Point the mirror at its own dataset rather than a directory inside the music dataset — it is derived data, so it wants its own snapshot policy, its own quota, and its own SMB share. The tool refuses to run with a mirror inside the source tree.

New Lidarr imports are picked up on the next pass. With MUSIC_MIRROR_INTERVAL at 6h that is the worst case; run --subdir by hand if you want an album immediately.

Nix

nix run .#music-mirror -- --source ./flac --mirror ./mp3
nix build .#music-mirror   # the test suite runs as part of the build
nix develop                # python, pytest and ffmpeg

overlays.default provides pkgs.music-mirror.

Tests

pytest

The tests run 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. They skip if ffmpeg is absent.

Getting the result onto an iPod

The mirror is just a directory of MP3s, so any client will do:

• macOS. Add the mirror's SMB share to the Music app with Copy files to Music Media folder and Keep Media folder organised both off. The Mac then stores a library database and nothing else. Keep the share mounted at a stable path — if it is missing when Music opens, every track shows !.
• Linux. Rhythmbox links libgpod and handles iPod sync. An iPod Video (5th generation) predates the models whose database has to be signed, so no firmware-hash trickery is needed.

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.