Scanner: flag files with import-time problems that break playback

[benders]

Problem

Some files in the library have embedded-metadata pathologies that cause subtle playback failures — stalls, skips, or transcode breakage — that look like network or server bugs but are actually file-level issues. We need scanner-side detection so we can see how widespread the problem is before deciding whether to mitigate at stream time, rewrite on disk, or just hand-fix the offenders.

Known cases

1. Oversized embedded cover art

• Example: /music/Other/Led Zeppelin/Led Zeppelin [Box Set]/4-13 I'm Gonna Crawl.mp3
  • Audio: MP3 256kbps, 5:31 (~10.6 MB expected)
  • Actual file: 60 MB
  • Embedded PNG: 3195×3111, 16-bit RGB, 49.6 MB
• Same album, 2-09 D'yer Mak'er.mp3: 58 MB file, ~50 MB PNG.
• Symptom: track skips during Vibrdrome playback over cellular. Navidrome must seek past the giant ID3v2 frame; client buffer underruns and gives up.
• Heuristic: file_size / (duration * audio_bitrate/8) > 1.5, or embedded_art_bytes > 2 MB.

2. MJPEG (video-stream) cover art

• Example: /music/Other/The Crystal Method/Vegas/*.mp3 — cover is a mjpeg 600×600 video stream, not a png/mjpeg image attachment.
• Example: /music/CD Rips/Various Artists/Fear & Loathing in Las Vegas [Original Soundtrack]/*.flac — same pattern, 500×500 mjpeg.
• Symptom: transcode pipelines that don't explicitly -map 0:a try to re-encode the cover too, breaking the stream.
• Heuristic: any non-audio stream with codec_type=video and codec_name=mjpeg (or png embedded as video stream).

3. Other candidate checks worth including

• Bit-rate / duration mismatch: declared duration doesn't match audio frame count (the FLAC end-early class, issue FLAC songs end early #34).
• Multiple audio streams in one container.
• Missing or malformed ID3 (no title/artist tags).
• Sample-rate / channel-layout oddities that break opus transcode (e.g. >2 channels, non-44.1/48kHz).
• Truncated files — last-frame decode fails.

Proposal

1. Extend the scanner to compute per-file metadata via ffprobe and record:
   • embedded_art_bytes, embedded_art_codec, embedded_art_dimensions
   • extra_video_streams count
   • declared_vs_decoded_duration_delta
   • audio_stream_count
2. Persist a media_file_problems table (or column flags on media_file) with one row per detected issue + severity.
3. Surface a "Library health" admin view listing affected files grouped by issue type.
4. No runtime mitigation in this issue — visibility first. Mitigation (stream-time strip vs. on-disk rewrite) is a follow-up once we know the blast radius.

Acceptance

• Re-scanning the live library surfaces the two Zeppelin Box Set tracks (oversized PNG), The Crystal Method Vegas, and the Fear & Loathing soundtrack (mjpeg cover) as flagged.
• Admin UI lists problem files with the specific issue and a one-line remediation hint.
• Docs: add a section to docs/pitfalls.md linking the detector to the symptoms it explains.

Refs

• Investigation that surfaced this: cellular playback skips on I'm Gonna Crawl and D'yer Mak'er 2026-05-22, traced to ~50 MB embedded PNGs.
• Related: FLAC songs end early #34 (FLAC songs end early) — duration/decoded-length mismatch fits this detector.

[benders]

FROM @claude:

Investigation notes & implementation hand-off

Below are the artifacts and findings from the diagnostic session that produced this issue, written so a future agent can implement scanner-side detection without re-deriving them.

Companion scripts (live in scripts/, not yet committed)

• scripts/scan-cover-art.py — walks a library root, runs ffprobe on each audio file, flags problems. Supports --csv, --threshold-mb, --max-dim, --flag-mjpeg, and --navidrome-container NAME for the duration cross-check (see class Stream player: show source instance, format, and bitrate #2 below). Implementation reference for the scanner-side detector.
• scripts/resize-cover-art.py — remediation. Shrinks oversized embedded art to ≤1024px JPEG @ q85 via mutagen + Pillow. Dry-run by default; --apply --backup-dir PATH to commit. Handles MP3 / FLAC / M4A.

Class 1: oversized embedded cover art

Live numbers (scanned 7,419 audio files in /Volumes/BigWolf/Music, May 2026):

Flag combo	Files
huge-dim,oversized (>2000px AND >2MB embedded)	236
huge-dim only (big dim, small bytes)	232
oversized only (big bytes, small dim)	54
Total actionable	522

Across 34 albums. Worst single offender: Led Zeppelin Box Set — 54 tracks each carry the same 3195×3111 16-bit RGB PNG, ~50MB per track, ~2.7GB of duplicated art across the album. Causes cellular playback skips on Vibrdrome: client buffer underruns while waiting on bloated Content-Length from the hub's /federation/stream (or Subsonic stream) response.

Other heavily-hit albums (top 10 by flagged track count): Pixies Death to the Pixies (38), Meat Beat Manifesto Subliminal Sandwich (28), The Byrds Very Best Of (27), Elvis White Christmas (25), TMBG Flood (19), Massive Attack Mezzanine (19), Cowboy Bebop OST2 (18), Hendrix Are You Experienced (17), Beatles Abbey Road (17).

Detection heuristic (from scan-cover-art.py):

probe = ffprobe(file)
audio_bytes_est = audio_stream.bit_rate * format.duration / 8
art_bytes_est = file.size - audio_bytes_est
oversized = art_bytes_est > 2_000_000 (default; tunable)
huge_dim  = attached_pic.width > 2000 OR attached_pic.height > 2000

Caveat: a bare codec_name=mjpeg check is noise — JPEG cover art is reported as mjpeg by ffprobe (JPEG = single-frame Motion JPEG). It fires on ~89% of properly-tagged CD rips. Only flag mjpeg in conjunction with the duration-mismatch check below.

Class 2: cover-art stream corrupts Navidrome's duration probe

Symptom: Navidrome stores a wildly wrong duration. Breaks next-track handoff in Sonos / Subsonic clients that rely on the stored duration to schedule the transition.

Surfacing case: Crystal Method Vegas album. Pre-fix Navidrome DB values:

Track	Stored	Actual	Inflation
Trip Like I Do	3098.99s (51:39)	7:34	6.82×
Busy Child	444.92s	7:25	correct
Cherry Twist	447.87s (7:28)	4:26	1.68×
High Roller	2060.45s (34:20)	5:30	6.24×
Comin' Back	2375.35s (39:35)	5:39	7.01×

Three different inflation ratios on three different tracks — not a clean math error. ffprobe / mutagen / VBRI / Xing headers all read the correct ~445s duration. Investigations that turned out NOT to be the root cause: first-frame bitrate (would give consistent ~609s), time-base confusion, VBR header type, MPEG-2 vs MPEG-1 misdetection. The actual cause is something specific to Navidrome's multi-stream probe — likely codec/version dependent, possibly fixed in a future Navidrome version.

Fix recipe (applied to all 10 Vegas tracks + 3 unrelated outliers found during library audit):

ffmpeg -i input.mp3 -map 0:a:0 -c:a copy -id3v2_version 3 output.mp3

Strips the embedded MJPEG video stream (the cover art lives as a real video stream in the MP3 container), keeps the audio, rewrites ID3. Other 3 outliers found by library audit using the same detection: Thrill Kill Kult — Starmartyr (11:22 → 5:47), Rolling Stones — Rip This Joint (3:57 → 2:23), Eon — Spice (was a WAV-wrapped MP3, unwrapped separately).

Detection heuristic — the file alone doesn't carry a clean signature; the only reliable check is cross-reference against Navidrome's stored duration:

-- inside Navidrome container: sqlite3 /data/navidrome.db
SELECT path, duration FROM media_file

Then in the scanner:

stored = navidrome_durations[relpath]
actual = ffprobe.format.duration
wrong_duration = abs(stored - actual) / actual > 0.05  (5% skew threshold)

See scan-cover-art.py --navidrome-container poutine-navidrome-1. Currently returns 0 hits across the library (post-fix); detector will fire on any new occurrence.

Backup artifacts

Originals from the Vegas re-mux: /tmp/vegas-backup/ (tracks 02–10) and /tmp/01-trip-backup.mp3 (track 1, kept separate). These are useful test fixtures for any future automated test of class-2 detection — /tmp/01-trip-backup.mp3 is a known-bad file with a 6.8× inflation when scanned by Navidrome.

Suggested implementation for in-product scanner

1. Schema: add media_file_problems table or JSON column on media_file with (file_id, issue_type, severity, detected_at, details_json).
2. Detection during ingest (per file):
   • Run ffprobe → parse JSON.
   • Compute art_bytes_est, attached_pic.dims, presence of non-attached_pic video streams.
   • Flag thresholds matching the heuristics above.
   • After the duration is committed, compare against ffprobe's container duration — if skew > 5%, flag wrong-duration.
3. Admin view: list problem files grouped by issue_type with a one-line remediation hint per issue.
4. No runtime mitigation yet — visibility first. The 522-file blast radius (90% in one album) and the existence of the standalone remediation script (resize-cover-art.py) argue against complex stream-time stripping; hand-fixing on disk is the right scope.
5. Add to docs/pitfalls.md: link these two failure modes to their symptoms (cellular skips → class 1; broken Sonos next-track / wrong Subsonic durations → class 2). Note that "track skipped on cellular" almost always means the file, not the network.