feat(downloads): local file upload ingest — media library backend (E7 S5a)

Add the non-yt-dlp ingest path so a user-uploaded file joins the same download
library and inherits its function set. Any file type is accepted: media
(video/audio) gets the full set (metadata, share, play/edit), a generic file
(pdf/zip/docx/…) is download-only.

- MediaAsset.media_kind ("video"|"audio"|"file") — the stored discriminator that
  gates library actions. Set at every finalize (download probe, editor carries the
  source's kind, upload probe); consolidates the ad-hoc audio-detect that lived only
  in links.py into one invariant (downloads.mediakind.derive). Migration 0076 adds
  the column + backfills existing rows.
- downloads/upload.py: ingest_upload probes the file (ffprobe → codecs/dims/duration),
  places it in a per-user .uploads tree, and creates an already-ready asset + done job
  (the same cache-hit shortcut enqueue uses). Uploads never expire (irreplaceable).
- POST /api/downloads/upload: streaming multipart with the per-file cap
  (download_upload_max_bytes, default 500 MiB) enforced on actual bytes read; quota
  charges the known size up front (quota.check_upload).
- Security: a generic file is always served force-download (attachment +
  application/octet-stream) on both the in-app and public endpoints, so uploaded
  HTML/SVG can't execute inline. Edit + redownload reject non-media / upload sources.
- python-multipart added (first multipart endpoint in the app).

backend/app/downloads/links.py

@@ -80,13 +80,13 @@ def public_meta(
 
     Resolves the owner's per-download display overrides (custom title/channel) over the asset's
     auto-extracted values, and surfaces the source + any extra reference links as clickable URLs."""
-    from app.downloads import service
+    from app.downloads import mediakind, service
 
     source_url = service.reference_url(job, asset)
-    # Audio-only assets (mp3 rips, extracted audio) carry a codec but no video stream. WebKit (all
-    # iOS browsers) refuses to play them inside a <video> element, so the watch page must render a
-    # native <audio> instead — flag it here from the recorded codecs (a real video always has vcodec).
-    is_audio = asset.vcodec is None and asset.acodec is not None
+    # Audio-only assets (mp3 rips, extracted audio) can't play inside a <video> element on WebKit
+    # (all iOS browsers), so the watch page renders a native <audio> instead. A generic uploaded
+    # file (media_kind='file') has no player at all — the watch page shows file info + a download.
+    # Both branches read the stored media_kind (the single source), not a re-derived codec check.
     return {
         "title": (job and job.display_name) or asset.title,
         "uploader": (job and job.display_uploader) or asset.uploader,
@@ -96,7 +96,10 @@ def public_meta(
         "duration_s": asset.duration_s,
         "width": asset.width,
         "height": asset.height,
-        "audio": is_audio,
+        "audio": asset.media_kind == mediakind.AUDIO,
+        "media_kind": asset.media_kind,
+        "size_bytes": asset.size_bytes,
+        "container": asset.container,
         "allow_download": link.allow_download,
         "file_url": file_url,
         "poster_url": poster_url,

backend/app/downloads/mediakind.py

@@ -0,0 +1,23 @@
+"""The media-kind discriminator for a library asset — the single home of one invariant.
+
+`MediaAsset.media_kind` is `"video" | "audio" | "file"`. It decides which library actions apply:
+media (video/audio) gets play/edit/share; a generic uploaded file gets download + share only, and
+is never rendered inline (see the force-download serving in the file/watch routes). Every finalize
+path computes it HERE — the download worker + the upload ingest via `derive`, the editor by
+carrying the source's kind over — so the rule lives in code, not in a comment that can drift (an
+earlier ad-hoc `vcodec is None and acodec is not None` audio check lived only in links.py).
+"""
+
+VIDEO = "video"
+AUDIO = "audio"
+FILE = "file"
+
+
+def derive(vcodec: str | None, acodec: str | None) -> str:
+    """Media kind from the probed codecs: a video stream -> video, audio-only -> audio, neither
+    (a non-media upload: pdf/zip/docx/…) -> file."""
+    if vcodec:
+        return VIDEO
+    if acodec:
+        return AUDIO
+    return FILE

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, service, storage
+from app.downloads import adapters, credentials, formats, mediakind, service, storage
 from app.downloads.jobdb import (
     _edit_staging_dir,
     _job_status,
@@ -484,6 +484,7 @@ def _download(
                 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
                 asset.uploader_url = adapter.uploader_url(info)

backend/app/downloads/quota.py

@@ -122,6 +122,22 @@ def check_enqueue(db: Session, user_id: int) -> None:
         raise QuotaExceeded("max_bytes", lim.max_bytes, used)
 
 
+def check_upload(db: Session, user_id: int, add_bytes: int) -> None:
+    """Like check_enqueue, but for an upload whose size is KNOWN at ingest: also reject when adding
+    this file would push the footprint over max_bytes. A download can't pre-check its size (unknown
+    until the worker finishes) so check_enqueue only compares the current footprint; an upload can,
+    so it's charged against the cap before it lands. Raises QuotaExceeded(max_jobs|max_bytes)."""
+    lim = resolve(db, user_id)
+    if lim.unlimited:
+        return
+    n = active_jobs(db, user_id)
+    if n >= lim.max_jobs:
+        raise QuotaExceeded("max_jobs", lim.max_jobs, n)
+    projected = footprint(db, user_id) + add_bytes
+    if projected > lim.max_bytes:
+        raise QuotaExceeded("max_bytes", lim.max_bytes, projected)
+
+
 def usage(db: Session, user_id: int) -> dict:
     """Compact usage snapshot for the UI (footprint + counts vs limits)."""
     lim = resolve(db, user_id)

backend/app/downloads/service.py

@@ -17,7 +17,7 @@ from app.config import settings
 from app.downloads import adapters
 from app.downloads import credentials
 from app.downloads import edit as editmod
-from app.downloads import formats, quota, storage
+from app.downloads import formats, mediakind, quota, storage
 from app.downloads.status import HOLDING, JobStatus
 from app.models import Channel, DownloadJob, MediaAsset, Video
 
@@ -216,6 +216,10 @@ def enqueue_edit(
     src_asset = db.get(MediaAsset, source_job.asset_id) if source_job.asset_id else None
     if src_asset is None or src_asset.status != "ready" or not src_asset.rel_path:
         raise EditError("source_not_ready")
+    # A generic uploaded file (media_kind='file') has no timeline to trim/crop — the editor path is
+    # media-only. Reject here so an upload's file never reaches the ffmpeg edit worker.
+    if src_asset.media_kind == mediakind.FILE:
+        raise EditError("not_media")
 
     spec = editmod.normalize_edit_spec(edit_spec)
     if not spec:
@@ -232,6 +236,9 @@ def enqueue_edit(
         asset.thumbnail_url = src_asset.thumbnail_url
         asset.upload_date = src_asset.upload_date
         asset.duration_s = editmod.clip_duration(spec, src_asset.duration_s)
+        # A clip inherits its source's kind (a video edit stays video, an audio trim stays audio);
+        # the ffmpeg edit worker doesn't re-probe codecs, so set it here where the source is known.
+        asset.media_kind = src_asset.media_kind or mediakind.VIDEO
 
     job = DownloadJob(
         user_id=user_id,

backend/app/downloads/storage.py

@@ -147,6 +147,28 @@ def edit_rel_path(user_id: int, asset_id: int, ext: str) -> str:
     return f".edits/{user_id}/clip_{asset_id}.{ext}"
 
 
+def upload_rel_path(user_id: int, asset_id: int, filename: str) -> str:
+    """On-disk path (relative to DOWNLOAD_ROOT) for a locally-uploaded file.
+
+    Kept in a per-user `.uploads/` tree — device-downloadable via the file endpoint, but NOT part of
+    the Plex library (an upload is arbitrary user content, not a canonical episode; no .nfo/poster
+    episode sidecars). The name is system-decided and bound to the asset id (`_a{id}` keeps two
+    same-named uploads apart); the original filename is display metadata only. The extension is
+    preserved (shell-safe, bounded) so the served file + its Content-Disposition carry a correct
+    suffix; an extensionless upload stays extensionless."""
+    stem = sanitize(Path(filename).stem, 80)
+    ext = _UNSAFE.sub("", Path(filename).suffix.lstrip(".")).lower()[:16]
+    suffix = f".{ext}" if ext else ""
+    return f".uploads/{user_id}/{stem}_a{asset_id}{suffix}"
+
+
+def upload_ext(filename: str) -> str | None:
+    """The stored `container` for an uploaded file: its shell-safe lowercased extension, or None when
+    the upload has no extension (a bare name)."""
+    ext = _UNSAFE.sub("", Path(filename).suffix.lstrip(".")).lower()[:16]
+    return ext or None
+
+
 def download_filename(display_name: str, container: str | None, path: Path) -> str:
     """The Content-Disposition filename for a served download: the cleaned display name carrying a single
     correct extension — the asset container, else the file's own suffix — without doubling it when the

backend/app/downloads/upload.py

@@ -0,0 +1,158 @@
+"""Local file ingest for the download center (E7 S5) — the non-yt-dlp path into the media library.
+
+A user-uploaded file joins the SAME library as a downloaded one, so it inherits the whole function
+set already built (metadata chips, share links, and — for media — in-app play/edit). Unlike a
+download it bypasses yt-dlp AND the worker entirely: the file is already on the host, so ingest
+probes it, places it on disk, and creates an already-`ready` MediaAsset + `done` DownloadJob in one
+step — the same "the file exists, mark it done now" shortcut `service.enqueue` takes on a cache hit.
+
+Kinds (the invariant lives in `mediakind`): a probe with a real video stream -> video, audio-only
+-> audio, neither -> a generic 'file' (pdf/zip/docx/…) that is download-only and never rendered
+inline (see the force-download serving in the file/watch routes). This module is the ingest seam a
+future sub-function (e.g. convert) plugs a new adapter into, mirroring how it sidesteps the worker.
+
+An upload does NOT get an `expires_at`: it's user-provided and may be irreplaceable (there's no
+source to re-download), so it doesn't age out on the retention clock the way a re-fetchable download
+does — it lives until the user deletes it.
+"""
+
+import json
+import secrets
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+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.models import DownloadJob, MediaAsset
+
+
+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 media (a file we can't probe is treated as a generic non-media upload).
+
+    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."""
+    try:
+        out = subprocess.run(
+            [
+                "ffprobe",
+                "-v",
+                "error",
+                "-show_streams",
+                "-show_format",
+                "-of",
+                "json",
+                str(path),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=True,
+        ).stdout
+        data = json.loads(out)
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, OSError, ValueError):
+        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 = (data.get("format") or {}).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
+    spaces (kept as-is otherwise — this is display metadata, not the shell-safe on-disk name)."""
+    stem = Path(filename).stem.replace("_", " ").replace(".", " ").strip()
+    return (stem or "Upload")[:255]
+
+
+def ingest_upload(
+    db: Session,
+    user_id: int,
+    *,
+    filename: str,
+    src_path: Path,
+    size: int,
+    display_name: str | None = None,
+) -> DownloadJob:
+    """Ingest an already-uploaded file at `src_path` into `user_id`'s library and return the `done`
+    job. `src_path` is MOVED into place on success (the caller stages it to a temp file first).
+
+    Raises quota.QuotaExceeded (holdings/footprint cap) — checked BEFORE any disk write, so a
+    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)
+    kind = mediakind.derive(vcodec, acodec)
+
+    # An upload never dedups (each file is its own asset): a random ref makes the cache key unique,
+    # so `format_sig` is a constant marker rather than a format hash.
+    ref = f"{user_id}:{secrets.token_hex(8)}"[:512]
+    asset = MediaAsset(
+        source_kind="upload", source_ref=ref, format_sig="upload", status="pending", ref_count=0
+    )
+    db.add(asset)
+    db.flush()  # need asset.id for the on-disk path
+
+    rel = storage.upload_rel_path(user_id, asset.id, filename)
+    storage.place_file(src_path, settings.download_root, rel)
+    final = storage.abs_path(settings.download_root, rel)
+    actual_size = final.stat().st_size if final.exists() else size
+
+    asset.status = "ready"
+    asset.rel_path = rel
+    asset.size_bytes = actual_size
+    asset.container = storage.upload_ext(filename)
+    asset.vcodec = vcodec
+    asset.acodec = acodec
+    asset.width = width
+    asset.height = height
+    asset.duration_s = duration
+    asset.media_kind = kind
+    asset.title = (display_name or "").strip() or _title_from_filename(filename)
+    asset.last_access_at = datetime.now(timezone.utc)
+    # No expires_at — see the module docstring (an upload is irreplaceable, so it doesn't age out).
+    if kind == mediakind.VIDEO:
+        # A frame poster gives the library row a thumbnail + the share link an og:image. Audio has no
+        # frame and a generic file no player, so neither gets one. Best-effort (ffmpeg decodes server
+        # side even for a codec the browser can't play).
+        asset.poster_path = editmod.ensure_poster(asset, settings.download_root)
+
+    job = DownloadJob(
+        user_id=user_id,
+        asset_id=asset.id,
+        job_kind="upload",
+        source_kind="upload",
+        source_ref=ref,
+        profile_snapshot={},
+        display_name=(display_name or "").strip() or None,
+        status="done",
+        progress=100,
+        queue_pos=service.next_queue_pos(db),
+    )
+    db.add(job)
+    service.incr_ref_count(db, asset.id)
+    db.commit()
+    db.refresh(job)
+    return job