release: 0.78.1 (bug/download-mediakind-probe)

Deep-review round 1 on bug/download-mediakind-probe found a real HIGH the prior
review missed:

- resolve_media_facts used a per-field `probe or info` fallback, so a probe that
  RAN and deliberately found no video track (cover-art-only audio: attached_pic
  skipped; a still image: format-guarded) had its None video overridden by
  yt-dlp's stale vcodec. An audio-mode download from a progressive source (info
  carries the source's video codec, embed-thumbnail on) was then classified VIDEO
  -> a Play button + a broken in-app <video> with no video track. Only the
  download path regressed (upload calls probe_media directly).

  Fix: gate precedence on whether ffprobe RAN, not per-field. If the probe read
  the file, its codec verdict wins outright (a None means 'no such track'); only a
  full ffprobe failure falls back to info. Dimensions still gap-fill from info.
  Refactored the parsing into _facts_from_probe so resolve_media_facts can see the
  raw probe-ran signal; probe_media keeps its 5-tuple (upload + TestProbeClassifier
  unchanged).

- tests: the cover-art-audio and still-image resurrection cases, a differing
  populated-info precedence case (the prior-flagged gap), and the ffprobe-failed
  info fallback — now stubbing run_ffprobe_json so the real parsing + precedence
  run together.

Backend gate green (ruff + full pytest).

VERSION

@@ -1 +1 @@
-0.78.0
+0.78.1

backend/app/downloads/edit.py

@@ -447,9 +447,9 @@ def run_ffprobe_json(
 ) -> dict | None:
     """One ffprobe call → its parsed JSON dict, or None on any failure (timeout, non-zero exit,
     missing binary, unparseable output). The SINGLE ffprobe-JSON-invocation point in the downloads
-    package: the browser-playability codec probe here and the upload-ingest probe (`upload._probe`)
-    both go through it, so the subprocess flags/timeout/error handling live in one place instead of
-    two drifting copies."""
+    package: the browser-playability codec probe here and the shared media probe (`probe.probe_media`,
+    used by both the download worker's finalize and the upload ingest) both go through it, so the
+    subprocess flags/timeout/error handling live in one place instead of drifting copies."""
     args = ["ffprobe", "-v", "error"]
     if show_streams:
         args.append("-show_streams")

backend/app/downloads/pipeline.py

@@ -15,7 +15,7 @@ from app.config import settings
 from app.db import SessionLocal
 from app.downloads import edit as editmod
 from app.downloads import errors as dlerrors
-from app.downloads import adapters, credentials, formats, mediakind, service, storage
+from app.downloads import adapters, credentials, formats, mediakind, probe, service, storage
 from app.downloads.jobdb import (
     _edit_staging_dir,
     _job_status,
@@ -475,15 +475,14 @@ def _download(
                 asset.rel_path = rel
                 asset.size_bytes = size
                 asset.duration_s = meta.duration_s
-                asset.width = int(info["width"]) if info.get("width") else None
-                asset.height = int(info["height"]) if info.get("height") else None
+                # Codecs/dims come from a PROBE of the finished file — the ground truth — NOT yt-dlp's
+                # `info` dict, whose codec fields are absent for some sources (Facebook among them):
+                # deriving media_kind from those nulls misclassified a real H.264 video as a
+                # download-only 'file' with no in-app play/edit. Same probe the upload ingest uses.
+                asset.vcodec, asset.acodec, asset.width, asset.height = probe.resolve_media_facts(
+                    final, info
+                )
                 asset.container = ext
-                asset.vcodec = (
-                    info.get("vcodec") if info.get("vcodec") not in (None, "none") else None
-                )
-                asset.acodec = (
-                    info.get("acodec") if info.get("acodec") not in (None, "none") else None
-                )
                 asset.media_kind = mediakind.derive(asset.vcodec, asset.acodec)
                 asset.title = meta.title
                 asset.uploader = meta.uploader

backend/app/downloads/probe.py

@@ -0,0 +1,107 @@
+"""Ground-truth media probe for a produced library file — the SINGLE place both ingest paths ask
+"what is actually on disk?".
+
+`media_kind` (and the stored `vcodec`/`acodec`/`width`/`height`) must reflect the real file, not an
+extractor's metadata: yt-dlp's `info` dict omits codec fields for some sources (e.g. Facebook), and
+deriving the kind from those nulls misclassified a genuine H.264 video as a download-only `file`
+(no in-app play). So the download worker (`pipeline`) and the local upload ingest (`upload`) both
+probe the finished file here; `mediakind.derive` then turns the probed codecs into the kind.
+"""
+
+from pathlib import Path
+
+from app.downloads import edit as editmod
+
+# ffprobe container formats that mean "this is a still image / image sequence", NOT playable media.
+# A standalone jpg/png/gif/webp/bmp reports a real video stream (codec mjpeg/png/…) with no
+# `attached_pic` flag, so without this guard it would classify as media_kind='video' and get a Play
+# button + a broken in-app <video> player (and inline serving on the public share). Keyed on the
+# container format so an animated gif/webp also lands as a generic 'file' (no browser plays those in
+# a <video> either). SVG and anything else ffprobe can't decode already fails the probe → 'file'.
+_IMAGE_FORMATS = {
+    "image2",
+    "image2pipe",
+    "png_pipe",
+    "mjpeg",
+    "mjpeg_pipe",
+    "jpeg_pipe",
+    "gif",
+    "webp_pipe",
+    "bmp_pipe",
+    "tiff_pipe",
+    "ico",
+    "svg_pipe",
+}
+
+
+def _facts_from_probe(
+    data: dict,
+) -> tuple[str | None, str | None, int | None, int | None, int | None]:
+    """(vcodec, acodec, width, height, duration_s) parsed from a NON-None ffprobe JSON dict. A still
+    image / image-sequence container yields no vcodec (→ generic 'file'); a video stream flagged
+    `attached_pic` (embedded cover art in an mp3/m4a) is skipped — it's a thumbnail, not a real video
+    track, so an audio file with album art still classifies as audio."""
+    fmt = data.get("format") or {}
+    fmt_names = {n.strip() for n in (fmt.get("format_name") or "").split(",")}
+    if fmt_names & _IMAGE_FORMATS:
+        return None, None, None, None, None
+
+    vcodec = acodec = None
+    width = height = None
+    for stream in data.get("streams", []):
+        kind = stream.get("codec_type")
+        if kind == "video" and vcodec is None:
+            if (stream.get("disposition") or {}).get("attached_pic"):
+                continue  # cover art, not a video track
+            vcodec = stream.get("codec_name")
+            width = stream.get("width")
+            height = stream.get("height")
+        elif kind == "audio" and acodec is None:
+            acodec = stream.get("codec_name")
+
+    duration = None
+    try:
+        raw = fmt.get("duration")
+        if raw is not None:
+            duration = int(float(raw))
+    except (TypeError, ValueError):
+        duration = None
+    return vcodec, acodec, width, height, duration
+
+
+def probe_media(path: Path) -> tuple[str | None, str | None, int | None, int | None, int | None]:
+    """(vcodec, acodec, width, height, duration_s) from one ffprobe call; all None if ffprobe fails
+    or the file isn't playable media (an unprobeable file — or a still image — is treated as a generic
+    non-media file, so it becomes a download-only 'file' rather than a broken 'video')."""
+    data = editmod.run_ffprobe_json(path, show_streams=True, show_format=True)
+    if data is None:
+        return None, None, None, None, None
+    return _facts_from_probe(data)
+
+
+def resolve_media_facts(
+    path: Path, info: dict
+) -> tuple[str | None, str | None, int | None, int | None]:
+    """(vcodec, acodec, width, height) for the stored download asset: PROBE the finished file on disk
+    (the ground truth). yt-dlp's `info` omits codec/dimension fields for some sources (Facebook among
+    them), so deriving media_kind from it there labelled a real H.264 video a download-only 'file'.
+
+    Precedence is by whether the probe RAN, not per-field: if ffprobe read the file, its codec verdict
+    is authoritative — INCLUDING a deliberate None (cover-art-only audio, a still image). A per-field
+    `probe or info` fallback would let `info`'s stale vcodec resurrect a video track the file doesn't
+    have (yt-dlp reports a progressive `vcodec` for an audio-mode download whose video it then strips),
+    mislabelling an audio download as a broken in-app 'video'. Only when ffprobe could NOT read the
+    file at all do we fall back to `info` (the pre-probe behaviour, a safety net); the cosmetic
+    dimensions still gap-fill from `info` in either case."""
+    data = editmod.run_ffprobe_json(path, show_streams=True, show_format=True)
+    info_v = info.get("vcodec") if info.get("vcodec") not in (None, "none") else None
+    info_a = info.get("acodec") if info.get("acodec") not in (None, "none") else None
+    info_w = int(info["width"]) if info.get("width") else None
+    info_h = int(info["height"]) if info.get("height") else None
+    if data is None:
+        # ffprobe could not read the file — fall back to the extractor's info entirely.
+        return info_v, info_a, info_w, info_h
+    pv, pa, pw, ph, _dur = _facts_from_probe(data)
+    # Probe ran → its codecs win outright (a None means "no such track", not "unknown"); info only
+    # gap-fills the cosmetic width/height the probe couldn't read.
+    return pv, pa, pw if pw is not None else info_w, ph if ph is not None else info_h

backend/app/downloads/upload.py

@@ -24,70 +24,9 @@ from sqlalchemy.orm import Session
 
 from app.config import settings
 from app.downloads import edit as editmod
-from app.downloads import mediakind, quota, service, storage
+from app.downloads import mediakind, probe, quota, service, storage
 from app.models import DownloadJob, MediaAsset
 
-# ffprobe container formats that mean "this is a still image / image sequence", NOT playable media.
-# A standalone jpg/png/gif/webp/bmp reports a real video stream (codec mjpeg/png/…) with no
-# `attached_pic` flag, so without this guard it would classify as media_kind='video' and get a Play
-# button + a broken in-app <video> player (and inline serving on the public share). Keyed on the
-# container format so an animated gif/webp also lands as a generic 'file' (no browser plays those in
-# a <video> either). SVG and anything else ffprobe can't decode already fails the probe → 'file'.
-_IMAGE_FORMATS = {
-    "image2",
-    "image2pipe",
-    "png_pipe",
-    "mjpeg",
-    "mjpeg_pipe",
-    "jpeg_pipe",
-    "gif",
-    "webp_pipe",
-    "bmp_pipe",
-    "tiff_pipe",
-    "ico",
-    "svg_pipe",
-}
-
-
-def _probe(path: Path) -> tuple[str | None, str | None, int | None, int | None, int | None]:
-    """(vcodec, acodec, width, height, duration_s) from one ffprobe call; all None if ffprobe fails
-    or the file isn't playable media (an unprobeable file — or a still image — is treated as a generic
-    non-media upload, so it becomes a download-only 'file' rather than broken 'video').
-
-    A video stream flagged `attached_pic` (embedded cover art in an mp3/m4a) is skipped — it's a
-    thumbnail, not a real video track, so an audio file with album art still classifies as audio."""
-    data = editmod.run_ffprobe_json(path, show_streams=True, show_format=True)
-    if data is None:
-        return None, None, None, None, None
-
-    fmt = data.get("format") or {}
-    fmt_names = {n.strip() for n in (fmt.get("format_name") or "").split(",")}
-    if fmt_names & _IMAGE_FORMATS:
-        # A still image / image sequence is a generic file, not video — no vcodec means media_kind='file'.
-        return None, None, None, None, None
-
-    vcodec = acodec = None
-    width = height = None
-    for stream in data.get("streams", []):
-        kind = stream.get("codec_type")
-        if kind == "video" and vcodec is None:
-            if (stream.get("disposition") or {}).get("attached_pic"):
-                continue  # cover art, not a video track
-            vcodec = stream.get("codec_name")
-            width = stream.get("width")
-            height = stream.get("height")
-        elif kind == "audio" and acodec is None:
-            acodec = stream.get("codec_name")
-
-    duration = None
-    try:
-        raw = fmt.get("duration")
-        if raw is not None:
-            duration = int(float(raw))
-    except (TypeError, ValueError):
-        duration = None
-    return vcodec, acodec, width, height, duration
-
 
 def _title_from_filename(filename: str) -> str:
     """A human display title from the original upload name: the stem with separators tidied to
@@ -112,7 +51,7 @@ def ingest_upload(
     rejected upload leaves nothing behind and the caller just cleans up its temp file."""
     quota.check_upload(db, user_id, size)  # the file's size is known → charge it up front
 
-    vcodec, acodec, width, height, duration = _probe(src_path)
+    vcodec, acodec, width, height, duration = probe.probe_media(src_path)
     kind = mediakind.derive(vcodec, acodec)
 
     # An upload never dedups (each file is its own asset): a random ref makes the cache key unique,

backend/tests/test_download_output.py

@@ -144,7 +144,7 @@ class TestCodecsFromStreams:
 
 
 class TestRunFfprobeJson:
-    """The single ffprobe-JSON invocation point (shared by probe_codecs + upload._probe). A failed
+    """The single ffprobe-JSON invocation point (shared by probe_codecs + probe.probe_media). A failed
     probe or unparseable output must degrade to None, not raise — the malformed-input safety the old
     parse_probe_streams string parser used to own now lives here."""
 

backend/tests/test_upload.py

@@ -7,9 +7,9 @@ guards that keep an upload out of paths that assume a re-fetchable source (edit
 
 DB-backed (real Postgres) — skipped when no database is reachable. `settings.download_root` is
 pointed at a per-test tmp dir so ingest's on-disk moves are isolated. The ingest/route tests
-monkeypatch `_probe` so they don't shell out to ffprobe; the classifier's OWN parsing (image →
-file, cover-art skip, dims, duration) is covered directly by `TestProbeClassifier` below, which
-stubs one level down (`run_ffprobe_json`) and exercises the real `_probe`.
+monkeypatch the shared `probe.probe_media` so they don't shell out to ffprobe; the classifier's OWN
+parsing (image → file, cover-art skip, dims, duration) is covered directly by `TestProbeClassifier`
+below, which stubs one level down (`run_ffprobe_json`) and exercises the real `probe_media`.
 """
 
 from pathlib import Path
@@ -18,6 +18,7 @@ import pytest
 
 from app.config import settings
 from app.downloads import mediakind, quota, storage
+from app.downloads import probe as probemod
 from app.downloads import upload as uploadmod
 from app.models import DownloadQuota, MediaAsset
 
@@ -42,7 +43,9 @@ def _root(tmp_path, monkeypatch):
 
 
 def _probe(monkeypatch, result):
-    monkeypatch.setattr(uploadmod, "_probe", lambda _p: result)
+    # upload ingest now calls the shared `probe.probe_media` (same ground-truth ffprobe the download
+    # worker uses); patch it at that shared home.
+    monkeypatch.setattr(probemod, "probe_media", lambda _p: result)
 
 
 def test_ingest_generic_file_is_download_only(db, make_user, _root, monkeypatch):
@@ -325,16 +328,16 @@ def test_ingest_cleans_up_placed_files_on_commit_failure(db, make_user, _root, m
     assert db.query(MediaAsset).count() == 0  # the flushed asset rolled back — no dangling row
 
 
-# --- classifier: the REAL _probe parsing (stubs ffprobe one level down) ----------------------
-# The ingest/route tests above stub _probe wholesale; these exercise _probe's OWN logic — image
+# --- classifier: the REAL probe_media parsing (stubs ffprobe one level down) ------------------
+# The ingest/route tests above stub probe_media wholesale; these exercise its OWN logic — image
 # detection, the cover-art skip, dimension/duration parsing — by faking only run_ffprobe_json, so a
 # regression in the classifier the force-download guarantee leans on is actually caught.
 
 
 class TestProbeClassifier:
     def _probe_with(self, monkeypatch, data):
-        monkeypatch.setattr(uploadmod.editmod, "run_ffprobe_json", lambda *a, **k: data)
-        return uploadmod._probe(Path("x"))
+        monkeypatch.setattr(probemod.editmod, "run_ffprobe_json", lambda *a, **k: data)
+        return probemod.probe_media(Path("x"))
 
     def test_probe_failure_is_a_generic_file(self, monkeypatch):
         # run_ffprobe_json returns None (ffprobe failed / not media) → all None → derive() == FILE.
@@ -392,3 +395,109 @@ class TestProbeClassifier:
         }
         v, a, w, h, d = self._probe_with(monkeypatch, data)
         assert d is None and mediakind.derive(v, a) == mediakind.AUDIO
+
+
+# --- resolve_media_facts: probe-of-the-file wins over yt-dlp's info (the FB regression fix) ---------
+# The download worker's finalize must classify from the ACTUAL file, not the extractor's `info` dict.
+# yt-dlp omits vcodec/acodec/dims for some sources (Facebook), and deriving media_kind from those
+# nulls turned a real H.264 video into a download-only 'file' (no in-app play). These pin that the
+# probe is authoritative and `info` is only a gap-filler.
+
+
+class TestResolveMediaFacts:
+    # These stub run_ffprobe_json (one level below probe_media) so the REAL probe parsing + the
+    # probe-vs-info precedence are exercised together — the precedence keys off whether ffprobe RAN.
+    @staticmethod
+    def _ffprobe(monkeypatch, data):
+        monkeypatch.setattr(probemod.editmod, "run_ffprobe_json", lambda *a, **k: data)
+
+    def test_probe_wins_when_info_lacks_codecs(self, monkeypatch):
+        # THE original regression: info has no vcodec/acodec/dims (Facebook), but the file probes as
+        # h264/aac.
+        self._ffprobe(
+            monkeypatch,
+            {
+                "format": {"format_name": "mov,mp4,m4a"},
+                "streams": [
+                    {"codec_type": "video", "codec_name": "h264", "width": 720, "height": 1280},
+                    {"codec_type": "audio", "codec_name": "aac"},
+                ],
+            },
+        )
+        v, a, w, h = probemod.resolve_media_facts(Path("x"), {"width": None, "height": None})
+        assert (v, a, w, h) == ("h264", "aac", 720, 1280)
+        assert mediakind.derive(v, a) == mediakind.VIDEO  # NOT 'file'
+
+    def test_probe_wins_over_a_DIFFERING_populated_info(self, monkeypatch):
+        # Both the probe AND info are populated but DISAGREE (info carries a pre-remux/pre-merge codec).
+        # The finished file on disk is ground truth, so the probe wins outright — pins the precedence a
+        # `info or probe` inversion would silently break.
+        self._ffprobe(
+            monkeypatch,
+            {
+                "format": {"format_name": "mov,mp4,m4a"},
+                "streams": [
+                    {"codec_type": "video", "codec_name": "h264", "width": 1920, "height": 1080},
+                    {"codec_type": "audio", "codec_name": "aac"},
+                ],
+            },
+        )
+        v, a, w, h = probemod.resolve_media_facts(
+            Path("x"), {"vcodec": "vp9", "acodec": "opus", "width": 640, "height": 480}
+        )
+        assert (v, a, w, h) == ("h264", "aac", 1920, 1080)  # probe, not info
+
+    def test_cover_art_audio_download_is_not_resurrected_to_video_by_info(self, monkeypatch):
+        # THE bug this fix targets: an audio-mode download from a progressive source embeds cover art,
+        # and yt-dlp's info still carries the source's video codec. The probe correctly finds only audio
+        # (the attached_pic is skipped); info's vcodec must NOT resurrect a video track → media_kind
+        # stays audio, not a broken in-app 'video'.
+        self._ffprobe(
+            monkeypatch,
+            {
+                "format": {"format_name": "mp3", "duration": "180.0"},
+                "streams": [
+                    {
+                        "codec_type": "video",
+                        "codec_name": "mjpeg",
+                        "disposition": {"attached_pic": 1},
+                    },
+                    {"codec_type": "audio", "codec_name": "mp3"},
+                ],
+            },
+        )
+        v, a, w, h = probemod.resolve_media_facts(
+            Path("x"), {"vcodec": "avc1", "acodec": "mp4a", "width": 1280, "height": 720}
+        )
+        assert v is None and a == "mp3"  # info's avc1 did NOT win
+        assert mediakind.derive(v, a) == mediakind.AUDIO  # NOT VIDEO
+
+    def test_still_image_download_is_not_resurrected_to_video_by_info(self, monkeypatch):
+        # A downloaded still image: the probe returns no vcodec (image-format guard). info's image
+        # "vcodec" must not turn it into a broken 'video' → stays a generic file.
+        self._ffprobe(
+            monkeypatch,
+            {
+                "format": {"format_name": "png_pipe"},
+                "streams": [{"codec_type": "video", "codec_name": "png", "width": 8, "height": 8}],
+            },
+        )
+        v, a, w, h = probemod.resolve_media_facts(
+            Path("x"), {"vcodec": "png", "width": 8, "height": 8}
+        )
+        assert v is None and mediakind.derive(v, a) == mediakind.FILE
+
+    def test_info_fills_in_only_when_ffprobe_could_not_read_the_file(self, monkeypatch):
+        # ffprobe failed entirely (None) → fall back to info so we never regress the working path.
+        self._ffprobe(monkeypatch, None)
+        v, a, w, h = probemod.resolve_media_facts(
+            Path("x"), {"vcodec": "vp9", "acodec": "opus", "width": 1920, "height": 1080}
+        )
+        assert (v, a, w, h) == ("vp9", "opus", 1920, 1080)
+
+    def test_info_none_codec_string_is_treated_as_absent(self, monkeypatch):
+        # yt-dlp writes the literal "none" for a missing stream — it must not become a codec name.
+        self._ffprobe(monkeypatch, None)  # probe failed → info path, where the "none" scrub applies
+        v, a, w, h = probemod.resolve_media_facts(Path("x"), {"vcodec": "none", "acodec": "aac"})
+        assert (v, a) == (None, "aac")
+        assert mediakind.derive(v, a) == mediakind.AUDIO

frontend/src/lib/releaseNotes.ts

@@ -14,6 +14,18 @@ export interface ReleaseEntry {
 }
 
 export const RELEASE_NOTES: ReleaseEntry[] = [
+  {
+    version: "0.78.1",
+    date: "2026-08-30",
+    summary:
+      "A fix for how downloads and uploads are recognised: an audio file with embedded cover art (or a still image) is no longer mistaken for a video, so it gets the right player and the right controls.",
+    fixes: [
+      "A downloaded audio track that carries album art — and some files from sites that report a video stream that isn't really there — were sometimes classified as video, giving a Play button that opened a broken, picture-less player. Siftlode now decides what a finished file actually is by inspecting the file itself, so audio stays audio, images stay files, and only real videos get the video player.",
+    ],
+    chores: [
+      "The media-kind classifier now trusts the on-disk probe over the source site's metadata whenever the probe could read the file, so stale metadata can't resurrect a video track the file doesn't have. Went through multi-agent deep-review, findings fixed and re-reviewed until clean.",
+    ],
+  },
   {
     version: "0.78.0",
     date: "2026-08-30",