feat: mirror a lossless library to MP3 for iPod sync

Apple's Music app cannot read FLAC, so getting a lossless library onto an iPod requires a converted copy somewhere. This keeps that copy beside the library on a NAS rather than on a laptop, and keeps it current unattended. Walks a source tree and reproduces it path for path as MP3: tags and cover art carried across, already-MP3 sources copied rather than re-encoded, and mirror files whose source has gone deleted along with any directories they emptied. The source library is never written to. Freshness is tracked by modification time -- an encoded file is stamped with its source's mtime, so a file is stale exactly when the two differ. That keeps runs idempotent without a database that could fall out of step with whatever owns the library, which here is Lidarr. Encodes go to a temporary file and are 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 prevents overlapping passes. Ships as a Python package with a console script, a container image with a TrueNAS Scale compose file, and a Nix flake providing the package, an overlay and a dev shell. The test suite runs real ffmpeg encodes rather than mocks -- the failures worth catching are in what ffmpeg does with tags, cover art and container formats. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-21 14:32:28 +01:00
parent 38f545ac32
commit 177761bb75
14 changed files with 1133 additions and 1 deletions
@@ -0,0 +1,80 @@
+import os
+import shutil
+import subprocess
+import sys
+
+import pytest
+
+# Ensure the project root is on sys.path when running tests.
+ROOT = os.path.dirname(os.path.dirname(__file__))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+
+@pytest.fixture(scope="session", autouse=True)
+def require_ffmpeg():
+    """The tests exercise real encodes; there is little point faking them."""
+    for tool in ("ffmpeg", "ffprobe"):
+        if shutil.which(tool) is None:
+            pytest.skip(f"{tool} is not on PATH", allow_module_level=True)
+
+
+@pytest.fixture
+def make_flac():
+    """Return a factory writing a short tagged FLAC file."""
+
+    def factory(path, title="Test Title", artist="Test Artist", album="Test Album", seconds=1):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        subprocess.run(
+            [
+                "ffmpeg",
+                "-nostdin",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-y",
+                "-f",
+                "lavfi",
+                "-i",
+                f"sine=frequency=440:duration={seconds}",
+                "-metadata",
+                f"title={title}",
+                "-metadata",
+                f"artist={artist}",
+                "-metadata",
+                f"album={album}",
+                "-metadata",
+                "track=3",
+                str(path),
+            ],
+            check=True,
+            capture_output=True,
+        )
+        return path
+
+    return factory
+
+
+@pytest.fixture
+def probe_tag():
+    """Return a helper reading a single metadata tag from a file."""
+
+    def reader(path, tag):
+        completed = subprocess.run(
+            [
+                "ffprobe",
+                "-v",
+                "error",
+                "-show_entries",
+                f"format_tags={tag}",
+                "-of",
+                "default=noprint_wrappers=1:nokey=1",
+                str(path),
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return completed.stdout.strip()
+
+    return reader