slim-embedded-art: recompress oversized embedded covers across the library

iOS AVPlayer reads a streamed file head in ~32 KB range requests and cannot
reach audio until it is past the ID3 tag - a 955 KB embedded JPEG cost ~30
sequential round trips, a two-second silence Android never feels. 28% of the
library (20,487 files, 1,488 albums) carries art that size.

Keeps an embedded front cover (other users of these files see it) but at
600px/JPEG stepped to fit 80 KB, ~3 chunks. Audio region is hashed before
and after; any mismatch keeps the original. Rescues art to cover.jpg first
when the folder has none.

scripts/slim-embedded-art.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+Slim the embedded cover art across the music library.
+
+WHY. iOS AVPlayer fetches the head of a streamed file in ~32 KB range requests, one round trip
+each, and it cannot reach audio until it has read past the whole ID3 tag. A 955 KB embedded JPEG
+(Ben Harper, 2026-08-29) therefore cost ~30 sequential round trips - a two-second silence on the
+iPhone that Android (ExoPlayer, one connection) never feels. 28% of the library rips carry art
+this size.
+
+THE LIMIT, AND WHY. Every track KEEPS an embedded front cover - the folder cover.jpg is this
+plugin's primary art, but embedded art is what any OTHER player/user of the files sees, so it
+stays. It is recompressed to fit the transport: 600x600 max (the iTunes standard, plenty for any
+lock screen), JPEG, quality stepped down from 85 until it fits in EMBED_TARGET = 80 KB. 80 KB
+plus the text frames keeps the whole tag within ~3 range-request chunks - imperceptible - while
+staying visually indistinguishable at the sizes any UI renders it.
+
+Only files whose picture frames total more than PROCESS_OVER = 100 KB are touched at all; a file
+already carrying reasonable art is left byte-identical.
+
+SAFETY. Work happens on a temp copy; the post-tag byte region (the audio, verbatim) is hashed
+before and after and must match or the original is kept. If an album folder has NO cover.jpg or
+folder.jpg, the original full-resolution embedded art is rescued to cover.jpg before compression.
+
+Usage:
+  slim-embedded-art.py                                 dry-run over ~/Music
+  slim-embedded-art.py "Albums/Ben Harper/[1994] ..."  dry-run, one directory
+  slim-embedded-art.py [subpath] --apply               actually rewrite
+"""
+import hashlib
+import io
+import os
+import shutil
+import sys
+
+from mutagen.id3 import ID3, APIC, ID3NoHeaderError
+from PIL import Image
+
+ROOT = os.path.expanduser("~/Music")
+EMBED_TARGET = 80_000
+PROCESS_OVER = 100_000
+
+
+def audio_region_hash(path):
+    """SHA-256 of everything after the ID3v2 tag - the audio, byte-for-byte."""
+    with open(path, "rb") as f:
+        head = f.read(10)
+        off = 0
+        if head[:3] == b"ID3":
+            off = 10 + ((head[6] << 21) | (head[7] << 14) | (head[8] << 7) | head[9])
+            if head[5] & 0x10:  # v2.4 footer
+                off += 10
+        f.seek(off)
+        h = hashlib.sha256()
+        while chunk := f.read(1 << 20):
+            h.update(chunk)
+        return h.hexdigest()
+
+
+def pictures(tag):
+    return tag.getall("APIC") + tag.getall("PIC")
+
+
+def compress_cover(data):
+    """(jpeg_bytes, note) at <= EMBED_TARGET, stepping quality then size down."""
+    img = Image.open(io.BytesIO(data))
+    if img.mode != "RGB":
+        img = img.convert("RGB")
+    for side in (600, 500, 400):
+        work = img.copy()
+        work.thumbnail((side, side))
+        for q in (85, 80, 70, 60, 50):
+            buf = io.BytesIO()
+            work.save(buf, "JPEG", quality=q, optimize=True)
+            if buf.tell() <= EMBED_TARGET:
+                return buf.getvalue(), f"{side}px q{q}"
+    return buf.getvalue(), f"{side}px q{q} OVER"  # pathological; still vastly smaller
+
+
+def rescue_cover(dirpath, data):
+    """Write the original art to cover.jpg when the folder has no art file at all."""
+    for name in ("cover.jpg", "folder.jpg"):
+        if os.path.exists(os.path.join(dirpath, name)):
+            return False
+    img = Image.open(io.BytesIO(data))
+    if img.mode != "RGB":
+        img = img.convert("RGB")
+    img.save(os.path.join(dirpath, "cover.jpg"), "JPEG", quality=90)
+    return True
+
+
+def process(path, apply):
+    try:
+        tag = ID3(path)
+    except ID3NoHeaderError:
+        return None
+    pics = pictures(tag)
+    total = sum(len(p.data) for p in pics)
+    if total <= PROCESS_OVER:
+        return None
+    largest = max(pics, key=lambda p: len(p.data))
+    if not apply:
+        return f"would slim {total // 1024} KB of art"
+
+    before = audio_region_hash(path)
+    tmp = path + ".slimtmp"
+    shutil.copy2(path, tmp)
+    try:
+        rescued = rescue_cover(os.path.dirname(path), largest.data)
+        jpeg, note = compress_cover(largest.data)
+        t = ID3(tmp)
+        t.delall("APIC")
+        t.delall("PIC")
+        t.add(APIC(encoding=0, mime="image/jpeg", type=3, desc="", data=jpeg))
+        v2 = 4 if tag.version >= (2, 4, 0) else 3
+        t.save(v2_version=v2, padding=lambda info: 0)
+        if audio_region_hash(tmp) != before:
+            raise RuntimeError("audio bytes changed - keeping original")
+        os.replace(tmp, path)
+        note_out = f"{total // 1024} KB -> {len(jpeg) // 1024} KB ({note})"
+        return note_out + (" +rescued cover.jpg" if rescued else "")
+    except Exception as e:
+        if os.path.exists(tmp):
+            os.remove(tmp)
+        return f"FAILED: {e}"
+
+
+def main():
+    args = [a for a in sys.argv[1:] if a != "--apply"]
+    apply = "--apply" in sys.argv
+    base = os.path.join(ROOT, args[0]) if args else ROOT
+    done = failed = skipped = 0
+    for dirpath, _, files in os.walk(base):
+        for name in sorted(files):
+            if not name.lower().endswith(".mp3"):
+                continue
+            result = process(os.path.join(dirpath, name), apply)
+            rel = os.path.join(dirpath, name)[len(ROOT) + 1 :]
+            if result is None:
+                skipped += 1
+            elif result.startswith("FAILED"):
+                failed += 1
+                print(f"  !! {rel}  {result}", flush=True)
+            else:
+                done += 1
+                if done % 250 == 0 or not apply:
+                    print(f"  {rel}  {result}", flush=True)
+    print(f"{'applied' if apply else 'dry-run'}: {done} slimmed, {skipped} already fine, {failed} failed", flush=True)
+
+
+if __name__ == "__main__":
+    main()