From 0508dc45d0b20999016732adce8dd43372bcb61c Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Mon, 22 Jun 2026 13:12:01 -0300
Subject: [PATCH 01/27] chore: ignore worktrees

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 21907de2..1363d74c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,3 +42,4 @@ crates/client-web/dist/
 
 # dev temp files
 .dev/
+.worktrees

From ade362a4dcfad4c1bfee445d0960e7e060678e56 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Thu, 18 Jun 2026 19:17:22 -0300
Subject: [PATCH 02/27] Add design spec: transcode ffmpeg resolution & player
 error surfacing

---
 ...peg-resolution-and-player-errors-design.md | 256 ++++++++++++++++++
 ...026-06-18-transcode-lifecycle-discovery.md |  83 ++++++
 .../2026-06-18-transcode-lifecycle-plan.md    | 116 ++++++++
 3 files changed, 455 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md
 create mode 100644 docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md
 create mode 100644 docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md

diff --git a/docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md b/docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md
new file mode 100644
index 00000000..3e34469d
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md
@@ -0,0 +1,256 @@
+# Transcode: FFmpeg Resolution & Player Error Surfacing — Design
+
+- **Date:** 2026-06-18
+- **Status:** Approved (design), pending implementation plan
+- **Scope:** A focused, timer-free fix for two reported failures plus adjacent robustness gaps. Lifecycle/mid-stream handling is deliberately deferred (drafted in the appendix).
+
+## 1. Background & Root Cause
+
+Two failures were reported when playing an HEVC (transcode-required) item:
+
+1. **"Failed to spawn transcode: No such file or directory (os error 2)"** — transcoding never starts.
+2. **Web player stays on a black screen with the "Transcoding" badge/spinner** — no error surfaced.
+
+### 1.1 Root cause of issue 1 (the "spaces in path" framing is a red herring)
+
+FFmpeg arguments are built into a `Vec<String>` and passed via `tokio::process::Command::args(&args)` (`crates/server/src/transcode.rs:227-229`). This bypasses the shell entirely — each vector element is handed directly to the OS `exec` as a discrete argv entry. A source path containing spaces or brackets (e.g. `/Users/.../Witch Hat Atelier ....mkv`) is passed to ffmpeg verbatim. The unquoted appearance in the server log is purely cosmetic: it comes from `args.join(" ")` at `transcode.rs:222-225`, not from what is executed.
+
+`No such file or directory (os error 2)` returned by **`spawn()` itself** (not by ffmpeg later) is, on Unix, `ENOENT` from the exec layer. When spawning the *command* fails with `ENOENT`, it means **the executable was not found** — i.e. `ffmpeg` is not resolvable from the server process's environment.
+
+The decisive context: `ffmpeg_path` defaults to a bare `"ffmpeg"` (`crates/server/src/config.rs:141`). On macOS, applications launched as GUI `.app` bundles (the recent DMG packaging work, commits `d8a5ea3` / `ea83ef9`) **do not inherit the user's shell `PATH`**. So even though ffmpeg is installed at `/opt/homebrew/bin/ffmpeg` and works from a terminal, it is invisible to a bare `ffmpeg` lookup from the server process. The same resolution is used for capability detection at `crates/server/src/media.rs:5997` (`detect_binary`).
+
+Note: a *missing media file* would not produce `ENOENT` at spawn. ffmpeg would start, fail to open its input, and emit the error on stderr (which the code already captures). The fact that the process dies at spawn points squarely at executable resolution.
+
+### 1.2 Root cause of issue 2 (no player feedback on HTTP failure)
+
+When `/api/v1/sessions/<id>/stream` returns `500`, the `<video>` element receives a non-2xx media resource. Browser behavior here is notoriously inconsistent: the `error` event fires reliably for *decode* failures but **not** for HTTP failures on a media `src`. In practice the element often just stalls on a black screen with the loading spinner — exactly what was observed.
+
+The player already has an error indicator (`has-media-error` toggling `.player-error-indicator`, `crates/client-web/src/app/playbackController.ts:324-327`), but:
+- Its copy is hardcoded ("Playback could not start / Try another audio track or start playback again.").
+- It is driven only by the `<video>` `error` event (`playbackController.ts:1330-1333`), which doesn't fire for HTTP 5xx on the src.
+- The capability data (`capabilities.transcoding.ffmpeg.available`) is loaded into state (`app.ts:536`) but never consulted before playback.
+
+### 1.3 Adjacent gaps found during exploration
+
+| ID | Gap | Evidence |
+|----|-----|----------|
+| B | Spawn failures are reported opaquely | `media.rs:3651-3654` logs `"Failed to spawn transcode: {}"` and returns bare `Status::InternalServerError` (no body) |
+| C | ffmpeg startup diagnostics are dropped before failure is known | `transcode.rs:228-233` pipes stderr but only reads it inside a background task *after* returning the stream; route returns 200 with a dead stream when ffmpeg fails to open input |
+| E | No source-path existence check | transcode branch of `get_session_stream` (`media.rs:3574-3617`) has no existence check |
+| F | No tests around transcode arg generation / path handling | no `transcode` test module exists |
+
+## 2. Decisions (locked during brainstorming)
+
+- **Locate ffmpeg:** both — search well-known locations (self-healing) **and** strong detection/messaging. Manual path still allowed, with a radio picker for easy setup.
+- **Discovery timing:** on-demand from settings ("Detect ffmpeg"), and that call must *also validate the user's currently-configured path*, not only search.
+- **Settings picker:** pair ffmpeg + ffprobe by directory (one radio per directory containing both).
+- **Player failures:** structured stream error (server) + client watchdog. Watchdog/timed pieces are **deferred** (appendix); this spec ships timer-free.
+- **Scope:** ship the timer-free core now; capture all lifecycle discoveries as a draft so nothing is relearned.
+- **Error UX:** layered — the in-player overlay gets terse, player-appropriate copy; the global `error-panel` banner gets the actionable layer (e.g. an "Open settings" button) when the error's `action` warrants it.
+- **Barebones seams:** add two inert seams now (per-session error store + shared error-mapper with `action`) so the deferred lifecycle phase has its hooks without this spec gaining timers or behavior.
+- **Tests:** shim-based (runs everywhere) for resolver + transcode-arg generation; a real-ffmpeg smoke test behind an optional feature flag.
+
+## 3. Out of scope (deferred)
+
+All of the following are **drafted in Appendix B** as a discovery + plan, not built in this phase:
+
+- (C) first-byte / early-exit validation of the stream before committing.
+- (C) mid-stream watcher + the `setInterval` client watchdog for stalls.
+- (E) source-path existence check (also folds into the lifecycle phase).
+- SSE / WebSocket transport (evaluated and rejected for this scope; see §6.2).
+
+## 4. Design
+
+### 4.1 FFmpeg resolution — new module `crates/server/src/ffmpeg_resolve.rs` (fixes issue 1)
+
+A single source of truth for resolving an executable, used by **both** capability display and the actual spawn — so "available in UI" ⟺ "actually launches".
+
+```rust
+pub enum ResolveSource { ConfiguredAbsolute, PathLookup, WellKnown }
+
+pub enum ResolvedBinary {
+    Found   { resolved_path: PathBuf, version: Option<String>, via: ResolveSource },
+    Missing { configured: String, checked_paths: Vec<PathBuf> },
+}
+
+pub fn resolve_binary(name_or_path: &str, binary_name: &str) -> ResolvedBinary;
+pub fn resolve_ffmpeg(configured: &str) -> ResolvedBinary { resolve_binary(configured, "ffmpeg") }
+pub fn resolve_ffprobe(configured: &str) -> ResolvedBinary { resolve_binary(configured, "ffprobe") }
+```
+
+**Resolution order:**
+1. If `configured` is absolute and exists and is executable → use it (`ConfiguredAbsolute`).
+2. Else if the bare name resolves on `PATH` → use it (`PathLookup`).
+3. Else probe a platform-specific well-known list for `binary_name`:
+   - macOS/Linux: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
+   - Windows: standard install dirs under `Program Files\ffmpeg`, plus `%USERPROFILE%\bin`
+   First hit → `WellKnown`.
+4. Else → `Missing { configured, checked_paths }` enumerating everywhere looked.
+
+**Integration:**
+- `spawn_transcode` / `spawn_transcode_stdout` (`transcode.rs:184`, `:214`) call the resolver and execute the **resolved** absolute path. This is the actual fix for issue 1.
+- `detect_binary` (`media.rs:5997`) is refactored to delegate to the resolver, preserving the existing `BinaryCapability` return shape so `TranscodingCapability` stays wire-compatible.
+
+**Logging:** at startup and on each resolve, `INFO`/`WARN` naming the resolved path and source, or all `checked_paths` when missing.
+
+### 4.2 Discovery endpoint + settings UI (the "easy setup")
+
+**Server — new route in `crates/server/src/web/routes/media.rs` next to `get_server_capabilities` (`media.rs:3026`), registered in `crates/server/src/web/routes/mod.rs`.** Tag is `Media` (there is no `system` tag in the project); guard is `AdminGuard` (the project's admin request guard, as in `user.rs:144/169`), since the response reveals on-disk paths and binary versions — the same sensitivity class as settings.
+
+```rust
+#[openapi(tag = "Media")]
+#[post("/api/v1/system/tools/discover")]
+pub async fn discover_transcoding_tools(admin_guard: AdminGuard) -> Result<Json<ToolDiscoveryResponse>, Status>;
+```
+
+Response types use the project style (`#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]` + a doc comment per field, as in `BinaryCapability` at `media.rs:115`):
+
+```rust
+pub struct ToolDiscoveryResponse {
+    pub configured_ffmpeg: BinaryProbe,     // validation of the user's current path
+    pub configured_ffprobe: BinaryProbe,
+    pub candidates: Vec<ToolCandidate>,     // one per directory containing at least one
+}
+pub struct ToolCandidate {
+    pub directory: String,                  // paths serialize as strings (JSON has no PathBuf)
+    pub ffmpeg: Option<BinaryProbe>,        // None if absent in this dir
+    pub ffprobe: Option<BinaryProbe>,
+}
+pub struct BinaryProbe {
+    pub resolved_path: Option<String>,
+    pub version: Option<String>,
+    pub error: Option<String>,              // e.g. "permission denied" / "exited non-zero"
+}
+```
+
+**Behavior** (matches the locked decision): search `PATH` + the §4.1 well-known list **and** validate the currently-configured path by running `ffmpeg -version` / `ffprobe -version`, returning the probe result so the UI can show "your configured path works / doesn't". A `BinaryProbe` is the resolver's `Found`/`Missing` rendered for JSON. This endpoint mutates nothing — it is read-only discovery.
+
+**Client — `crates/client-web/src/app/settingsView.ts`.** Under the existing ffmpeg/ffprobe inputs (`settingsView.ts:554-555`):
+- A **"Detect ffmpeg"** button calls the discover endpoint.
+- Results render as **radio options grouped by directory** (pair by directory): `/opt/homebrew/bin — ffmpeg 7.0 · ffprobe 7.0`. Directories missing one binary are shown but disabled, with a note. Selection sets **both** `ffmpeg_path` and `ffprobe_path` to that directory.
+- The **currently-configured path** is its own radio option, labeled with its validation result ("✓ works" / "✗ not found: …").
+- A manual-path radio is still available for the independent text inputs (preserving "still allow manual path").
+- Saving still goes through the existing settings save — no new write path.
+
+### 4.3 Spawn robustness & structured error reporting (gap B + half of issue 2)
+
+**Richer spawn error.** `spawn_transcode_stdout` returns a new enum instead of `std::io::Error`:
+
+```rust
+pub enum SpawnTranscodeError {
+    ExecutableMissing { checked_paths: Vec<PathBuf> },   // spawn ENOENT, from the resolver
+    BadInput { ffmpeg_stderr: String },                  // populated by the lifecycle phase; left unused here
+    Io(std::io::Error),
+}
+```
+
+`BadInput` is present for forward-compatibility with the lifecycle phase but is not produced in this spec (no first-byte check — see out of scope).
+
+**Shared error-mapping function (seam #2).** A single `map_transcode_error(SpawnTranscodeError) -> (Status, TranscodeErrorBody)` is written once so the lifecycle phase reuses it:
+
+```rust
+pub struct TranscodeErrorBody {
+    pub code: &'static str,        // "transcode_executable_missing" | "transcode_input_error" | "transcode_failed"
+    pub message: String,
+    pub action: Option<&'static str>,   // e.g. Some("open_settings") for actionable codes
+}
+```
+
+`action` is what lets the global banner conditionally render an "Open settings" button.
+
+**Status mapping** (to be confirmed during implementation, not load-bearing for the design): `ExecutableMissing → 503`, `BadInput → 422`, `Io → 500`.
+
+**Route handler** (`media.rs:3621-3655`): on spawn error, return the structured JSON body via the mapper (not a bare 500). `log::error!` is retained and now includes the resolved path and `checked_paths`.
+
+**Per-session error store (seam #1, inert writer; live reader).** Added next to `ACTIVE_TRANSCODE_TASKS` (`media.rs:317`):
+
+```rust
+static ACTIVE_SESSION_ERRORS: Lazy<RwLock<HashMap<String, SessionError>>> = Lazy::new(Default::default);
+pub async fn record_session_error(session_id: &str, error: SessionError) { /* unused in this phase */ }
+```
+
+The writer is inert (no callers this phase — the lifecycle watcher in Appendix B will populate it). A **lightweight read endpoint** is added now so the §4.4 best-effort recovery can look it up without spawning a transcode:
+
+```rust
+#[openapi(tag = "Media")]
+#[get("/api/v1/sessions/<session_id>/status")]
+pub async fn get_session_status(session_id: String) -> Json<SessionStatusResponse>;
+// SessionStatusResponse { error: Option<TranscodeErrorBody>, ... } — error is None while this phase never writes any
+```
+
+This endpoint returns `{ error: None }` in this phase (since nothing writes the store yet) but is the seam the lifecycle watcher will feed. It is a map lookup, not a transcode spawn — that is the entire reason the recovery path is cheap. Register it in `routes/mod.rs` alongside the discover route.
+
+### 4.4 Client preflight & layered error UX (fixes issue 2, timer-free)
+
+**Two surfaces, each fed what suits it:**
+
+1. **In-player overlay** (`has-media-error` / `.player-error-indicator`) — terse, player-appropriate copy ("Transcoding failed — the server couldn't start FFmpeg"), no navigation chrome.
+2. **Global `error-panel` banner** (`state.error`) — the actionable layer: same failure rendered with an **[Open settings]** button that appears only when the structured error's `action == "open_settings"`.
+
+**State plumbing.** Add to `AppState` (`types.ts:100`):
+
+```ts
+playbackError?: { code: string; message: string; action?: string };
+```
+
+Rendering in `renderMediaPlayerOverlay` (`playbackController.ts:324-327`) becomes dynamic, reading `state.playbackError` instead of the hardcoded string. `setPlayerError()` (currently `playbackController.ts:1053`) sets it.
+
+**Preflight (timer-free).** In `startPlayback` (`playbackController.ts:610`), before opening the player on a doomed stream:
+- If `state.capabilities.transcoding.ffmpeg.available === false` **and** the decision requires transcode → block; set `state.playbackError` and `state.error` from the `transcode_executable_missing` code.
+
+**Stream-error detection (timer-free) — probe rejected.** An earlier draft proposed a `fetch()` probe of the stream URL before attaching `<video src>`. That is rejected: each `/sessions/<id>/stream` request spawns a fresh transcode (`media.rs:3619-3621`, child `kill_on_drop` at `transcode.rs:233`), so a probe + media-element request double-spawns ffmpeg on every successful playback (doubled startup latency and CPU), and any bytes read during the probe are buffered then discarded (memory + wasted work on the hot path).
+
+Instead:
+- **Primary detection — capabilities preflight (deterministic).** This phase produces exactly one spawn-time structured error, `ExecutableMissing`, which is precisely the signal `state.capabilities.transcoding.ffmpeg.available === false` already carries. So the preflight above catches the reported issue without touching the stream — no probe, no double spawn.
+- **Best-effort recovery via a status read, not a re-spawn.** The `<video>` `error` handler (`playbackController.ts:1330-1333`) stays wired. When it fires, the client fetches a lightweight **session-status read** (a lookup of the per-session error seam in §4.3 — `ACTIVE_SESSION_ERRORS`, *not* a transcode spawn) to recover the structured `code`/`message`/`action` and drive both surfaces. Because it is a map lookup, it has none of the probe's costs. It only helps for the narrow case the preflight cannot see (e.g. a rare `Io` spawn error such as disk-full) and only when the browser actually fires the event — but it costs nothing on the success path.
+- The cases a probe would genuinely help with (input errors, mid-stream failures) are exactly the **deferred lifecycle phase** (Appendix B), and there the correct architecture is a persistent transcode the stream *attaches* to, not a probe — a further reason not to lock in the probe pattern now.
+
+## 5. Testing approach (matches + extends project conventions)
+
+The project splits tests by kind: pure logic lives in **inline `#[cfg(test)] mod tests`** (e.g. `media.rs`, `metadata/providers/tvdb.rs`); **HTTP routes** are covered by integration tests in `crates/server/tests/test_web/routes/*.rs` using `create_test_client` + `make_request`.
+
+- **`ffmpeg_resolve.rs` — inline unit tests** (highest value, fastest). Resolution precedence (absolute wins; bare-name falls back to well-known dirs; missing-everywhere returns `checked_paths`), staged with `tempfile::tempdir()` fake `ffmpeg`/`ffprobe` shims so tests are hermetic and require no real ffmpeg. This **improves on the current capabilities code, which has zero tests** despite being the failing component.
+- **`transcode.rs` — inline unit tests (gap F).** Arg generation: a source path with spaces/brackets survives as a single argv element; `-c:v copy`/`-c:a copy` branches; fragmented-mp4 movflags. No transcode tests exist today; this closes that gap.
+- **Real-ffmpeg smoke test, opt-in** behind `#[cfg(feature = "real-ffmpeg-tests")]` (or an env-var skip) so CI without ffmpeg still passes and anyone with ffmpeg locally can opt in.
+- **Route integration test** — new file `crates/server/tests/test_web/routes/tools.rs` (mirroring `settings.rs`): discover endpoint returns `200` + a candidates array; `AdminGuard` rejects unauthenticated callers (matching the auth-status convention used in `test_auth.rs`). The session-status endpoint returns `200` with `error: null` (its inert value this phase) for a known session and `404` for an unknown one.
+- **Frontend:** the project has **no client-web test harness** (no vitest/jest), so per project style client changes stay test-light (manual verification) in this scope. This is a deliberate, documented scoped decision — introducing a frontend test runner is out of scope.
+
+## 6. Notes
+
+### 6.1 UI conventions appendix (no design docs exist in-repo)
+
+`docs/` has no UI/UX documentation. The conventions are implicit in code; the new components follow them rather than introducing a design system:
+
+- **Error display — two existing surfaces:** (a) one global `state.error: string | undefined` rendered as `<section class="error-panel">` (`auth.ts:73`, used app-wide); (b) a player-local `has-media-error` → `.player-error-indicator` overlay (`playbackController.ts:324-327`, `style.css:2591-2609`). This spec unifies playback failures to drive **both**, each with copy suited to its context.
+- **Settings forms:** labeled `<input>` rows + save button (`settingsView.ts:554-555`). No radio-list component exists today; the directory-radio list is a small new component, styled to match existing settings inputs, documented as new.
+- **Realtime:** none in the codebase (only `setInterval` is the trailer UI tick at `playbackController.ts:997`); this spec introduces no new realtime transport.
+
+### 6.2 Why not SSE (rejected for this scope)
+
+SSE would mean a new transport, a server endpoint, reconnection logic, and a client subscription model — all for a path that is fundamentally *request → response* (one error per stream attempt). The structured JSON error body (§4.3) plus the deterministic capabilities preflight (§4.4) covers the same need using patterns the codebase already has. SSE earns its place only if realtime playback health (quality metrics, adaptive bitrate) becomes a goal — separate spec.
+
+## Appendix A — Files touched (planning reference)
+
+Server:
+- `crates/server/src/ffmpeg_resolve.rs` (new) — resolver + inline tests
+- `crates/server/src/transcode.rs` — resolved-path spawn, `SpawnTranscodeError`, shared mapper, inline tests
+- `crates/server/src/media.rs` — `detect_binary` delegates to resolver
+- `crates/server/src/web/routes/media.rs` — discover route, session-status route, structured stream-error body, per-session error store (seam), route handler mapping
+- `crates/server/src/web/routes/mod.rs` — register discover + session-status routes
+- `crates/server/src/auth.rs` / wherever `AdminGuard` lives — no change, just used
+- `crates/server/tests/test_web/routes/tools.rs` (new) — route integration tests
+
+Client:
+- `crates/client-web/src/api.ts` — `discoverTranscodingTools()`, `TranscodeErrorBody` type
+- `crates/client-web/src/app/types.ts` — `playbackError` on `AppState`
+- `crates/client-web/src/app/settingsView.ts` — detect button + directory radios
+- `crates/client-web/src/app/playbackController.ts` — preflight, status-read recovery, dynamic overlay copy
+
+## Appendix B — Deferred: Transcode lifecycle & mid-stream failure handling
+
+The deferred items — (C-early) first-byte / early-exit stream validation, (C-mid) mid-stream watcher + client watchdog, and (E) source-path existence check — are captured in full as standalone documents so nothing is relearned:
+
+- **Discovery:** `docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md` — current transcode lifecycle mechanics, failure modes, hard constraints (no naive timers; reuse shipped seams; no new realtime transport; cost stays off the success path), open questions, and what is already built for this phase.
+- **Draft plan:** `docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md` — proposed event-driven first-byte race (not a fixed timer), mid-stream watcher writing to the shipped `record_session_error` seam, bounded client watchdog with healthy-suppression, and (E) reconciled with the existing `missing_since` column.
+
+This phase leaves the two inert seams those documents depend on: the per-session error store + `record_session_error()` writer, and the shared `map_transcode_error` + `TranscodeErrorBody { code, message, action }` (§4.3).
diff --git a/docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md
new file mode 100644
index 00000000..77d6c1d3
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md
@@ -0,0 +1,83 @@
+# Transcode Lifecycle & Mid-Stream Failure Handling — Discovery
+
+- **Date:** 2026-06-18
+- **Status:** Discovery (deferred phase). Not implemented. Companion to `2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md`.
+- **Purpose:** Capture everything discovered about the transcode *lifecycle* so the deferred phase starts from complete knowledge and relearns nothing.
+
+## 1. What this phase is about
+
+The shipped spec (`...-player-errors-design.md`) fixes **issue 1** (ffmpeg not resolvable) and the **spawn-time + preflight** portion of issue 2, with no timers. It deliberately leaves three things to a later, timer-containing phase:
+
+- **(C-early)** first-byte / early-exit validation of a stream before committing to a 200.
+- **(C-mid)** mid-stream watcher (ffmpeg dies after data has flowed) + client watchdog.
+- **(E)** source-path existence check for paths that vanish between scan and play.
+
+This document records the current code mechanics, the constraints, and the open questions. The companion draft plan (`2026-06-18-transcode-lifecycle-plan.md`) proposes an approach.
+
+## 2. Current transcode lifecycle (as it exists today)
+
+Entry point: `get_session_stream` (`crates/server/src/web/routes/media.rs:3531`).
+
+1. The handler resolves the session, builds a `TranscodeSpec`, and calls `stop_active_transcode(&session_id)` then `spawn_transcode_stdout(...)` (`media.rs:3619-3621`).
+2. `spawn_transcode_stdout` (`crates/server/src/transcode.rs:214-237`) configures `stdin(null)`, `stdout(piped)`, `stderr(piped)`, `kill_on_drop(true)`, and spawns the child. It returns the `Child` immediately.
+3. Back in the handler (`media.rs:3622-3649`): `child.stdout` is taken and returned inside `SessionStream::Transcode`. `child.stderr` is taken and handed to a **background `tokio::spawn` task** that does, in order:
+   - `stderr.read_to_end(&mut stderr_text).await` — this resolves **only at EOF**, i.e. when ffmpeg closes stderr, i.e. when ffmpeg exits.
+   - `child.wait().await` — reaps the process.
+   - Logs the captured stderr and non-zero exit status.
+4. The HTTP response returns `200` with `Content-Type: video/mp4` and a streamed body wrapping `ChildStdout` via `ReaderStream::one` (`media.rs:178-186`).
+
+### 2.1 Why this is fragile
+
+- **The 200 is returned before ffmpeg has produced any data.** If ffmpeg fails to open the input (truly missing file, unsupported codec, broken `-ss` seek, corrupt header), the route has already committed to 200 and the client receives a stalled or immediately-truncated stream. The background task logs the failure *afterward* — too late for the client.
+- **stderr is buffered until exit.** `read_to_end` means no streaming stderr; useful diagnostics are only seen post-mortem.
+- **No mid-stream signal to the client.** If ffmpeg dies after sending some data (disk error, network blip on a remote source, OOM kill), the client's stream just ends or stalls. Nothing writes a per-session error; nothing tells the player.
+- **`stop_active_transcode` aborts the prior handle** (`media.rs:317-325`). An abort drops the task; with `kill_on_drop`, the prior ffmpeg is killed. This is correct for replacement, but means there is no notion of a *persistent* transcode a new request can attach to — each stream request re-spawns. (Relevant to why the rejected probe idea double-spawned; see the design doc §4.4.)
+
+## 3. Failure modes the lifecycle phase must cover
+
+| Mode | When | Current behavior | Desired behavior |
+|------|------|------------------|------------------|
+| Input open failure (missing/locked file, bad codec, seek error) | before first byte | 200 + dead stream; logged post-mortem | structured error before committing (C-early) |
+| Early exit (ffmpeg starts, emits stderr, dies within seconds) | before/around first byte | 200 + truncated stream | structured error before committing (C-early) |
+| Mid-stream death (disk/net/OOM after data flowed) | after first byte | truncated/stalled stream; no client signal | watcher writes per-session error; client watchdog surfaces it (C-mid) |
+| Source vanished since scan (esp. network/removable paths) | at spawn/input-open | confusing ffmpeg stderr | clean 404 from a pre-spawn check (E) |
+
+## 4. Constraints discovered now (must hold for the lifecycle phase)
+
+1. **No naive timers.** A fixed `tokio::time::sleep(3s)` first-byte check is a bug magnet (too short for slow remote mounts; too long for snappy UX). Any bound must be event-driven first, with generous and overridable timeouts only where a bound is genuinely required.
+2. **Reuse the shipped seams, don't invent new shapes.**
+   - The **per-session error store** `ACTIVE_SESSION_ERRORS` + `record_session_error()` (design doc §4.3) is the writer the watcher uses.
+   - The **shared `map_transcode_error`** + `TranscodeErrorBody { code, message, action }` is the single client-facing shape — mid-stream errors must map through it, not a second representation.
+   - The **session-status read** (`GET /api/v1/sessions/<id>/status`, design doc §4.3) is the client's lookup; it returns `{ error: null }` today and will carry the watcher's error once populated.
+3. **No new realtime transport.** The codebase has no SSE/WebSocket (only a `setInterval` for the trailer UI tick, `playbackController.ts:997`). The watchdog must be a deliberate, bounded poll, not a persistent socket. SSE was evaluated and rejected for the shipped phase; revisit only if realtime playback *health metrics* become a goal, not just failure signaling.
+4. **Cost stays off the success path.** The whole reason the shipped phase rejected a probe was avoiding doubled ffmpeg startup and wasted buffered bytes on every successful play (each `/stream` request spawns fresh). The lifecycle phase must preserve that: a healthy stream must incur no extra spawns and no buffering tax.
+5. **`kill_on_drop` replacement semantics must be preserved.** `stop_active_transcode` + `kill_on_drop` is how a new stream request replaces an old one. Any persistent-transcode model must keep correct teardown on session delete/replace.
+6. **Client surfaces are already defined.** The in-player overlay (`has-media-error`, terse) and the global `error-panel` banner (actionable, conditional `[Open settings]` button on `action == "open_settings"`) are shipped and must be reused as-is — mid-stream failures feed the same `state.playbackError { code, message, action }`.
+
+## 5. Open questions (to resolve during lifecycle planning, not now)
+
+These are recorded so they are not lost; they need investigation/decisions in that phase.
+
+1. **First-byte strategy.** Pure race (first-stdout-chunk Future vs child-exit Future vs stderr-ready signal), or first-byte race **plus** a generous stderr-wait timeout for inputs that emit warnings before producing bytes? What is "generous" — and should it be configurable (per-library, for slow network mounts)?
+2. **Streaming stderr.** Switch from `read_to_end` to a line-buffered reader so diagnostics surface live and so "ffmpeg is emitting warnings but no bytes yet" is detectable without waiting for exit. Tradeoff: more moving parts in the background task.
+3. **Watchdog cadence & suppression.** What interval, and how to suppress polling while healthy? Candidates: suppress on `<video>` `playing`/`timeupdate`; poll only when the element is stalled/buffering beyond a threshold. What threshold, and does it false-positive on legitimately slow networks?
+4. **Stall definition for piped fragmented MP4.** Fragmented MP4 over a pipe can have natural pauses between fragments; the watchdog must distinguish "between fragments" from "dead". Needs a defined notion (bytes-per-window, fragment cadence, or just child-exit observation).
+5. **Status endpoint vs 500-on-reconnect.** Is the `GET /sessions/<id>/status` read sufficient for the watchdog, or does the stream endpoint itself need to return the structured error on a *reconnect* attempt (e.g. after the player retries the src)?
+6. **(E) scope.** Should source-existence be only a per-play 404, or also drive a server-side "missing since scan" background job (mark `missing_since`, surface in the UI)? The shipped code already has a `missing_since` column on backing files (`media.rs:3145`) — the lifecycle phase should reconcile per-play checks with that existing mechanism rather than duplicate it.
+7. **Persistent vs per-request transcode.** Should a stream request attach to a long-lived transcode keyed by `(session_id, start_ms, audio_index)` instead of spawning fresh each time? This would eliminate the double-spawn concern entirely and is the natural home for a watcher — but it is a larger change. Decide whether the lifecycle phase takes it on or stays per-request.
+
+## 6. What is already built for this phase (no rework needed)
+
+- Per-session error store + `record_session_error()` writer — inert, ready to be called.
+- `GET /sessions/<id>/status` reader — live, returns `{ error: null }` until the watcher writes.
+- Shared `map_transcode_error` + `TranscodeErrorBody { code, message, action }`.
+- Client `state.playbackError` + dynamic overlay/banner rendering + `[Open settings]` on `action`.
+- Capabilities preflight + (now-rejected) probe rationale — so the lifecycle phase knows what was *not* done and why.
+
+## 7. Related code references
+
+- Stream handler: `crates/server/src/web/routes/media.rs:3531` (`get_session_stream`), spawn/error mapping at `:3619-3656`.
+- Spawn + background task: `crates/server/src/transcode.rs:214-237`; the task body at `media.rs:3626-3643`.
+- Replacement/teardown: `stop_active_transcode` / `replace_active_transcode` (`media.rs:317-338`).
+- Error surfaces: `crates/client-web/src/app/playbackController.ts:1053` (`setPlayerError`), `:1330-1333` (`<video>` error handler), overlay/banner markup at `:317-360`.
+- Existing `missing_since` mechanism: `crates/server/src/media.rs:3145` (relevant to open question 6).
diff --git a/docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md
new file mode 100644
index 00000000..97db6130
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md
@@ -0,0 +1,116 @@
+# Transcode Lifecycle & Mid-Stream Failure Handling — Draft Plan
+
+- **Date:** 2026-06-18
+- **Status:** Draft plan (deferred phase). Not approved for implementation; to be reviewed and detailed when this phase is scheduled. Companion to `2026-06-18-transcode-lifecycle-discovery.md`.
+- **Purpose:** A concrete proposed approach for the three deferred items, grounded in the discovery doc. Open questions there (§5) must be resolved before this becomes an approved plan.
+
+## 0. Scope (three items)
+
+- **(C-early)** Validate the stream before committing to 200.
+- **(C-mid)** Detect ffmpeg dying after data has flowed and surface it to the player.
+- **(E)** Pre-spawn source existence check (esp. for network/removable paths).
+
+Non-goals: changing the client error surfaces (already shipped), changing the `TranscodeErrorBody` shape (already shipped), introducing SSE/WebSocket (rejected, discovery §4.3).
+
+## 1. Architectural decision to make first: persistent vs per-request transcode
+
+This is discovery open-question 7 and it shapes everything below.
+
+**Option A — Stay per-request (smaller change).** Keep the current model: each `/stream` request spawns its own ffmpeg. Add a pre-commit validation step and a watcher, both per-request. Lower risk; preserves exact current teardown semantics.
+
+**Option B — Persistent transcode keyed by `(session_id, start_ms, audio_index)` (larger change).** A long-lived ffmpeg process that stream requests attach to, eliminating the per-request re-spawn (and the double-spawn concern that killed the probe). Natural home for a single watcher. Higher risk; touches session lifecycle, replacement semantics, and concurrency (multiple readers of one stdout).
+
+**Recommendation (tentative, to confirm in planning):** Start with **Option A**. It delivers the three scope items with the least surface area, reuses the shipped seams directly, and leaves Option B as a follow-on if re-spawn cost or reader-fan-out ever becomes a problem. The rest of this draft assumes Option A.
+
+## 2. (C-early) Pre-commit stream validation — event-driven, not a fixed timer
+
+Replace "return stdout immediately" with "return stdout only once ffmpeg has proven it can produce output (or fail)".
+
+### 2.1 Mechanism: a three-way race
+
+On a successful spawn, before returning `SessionStream::Transcode`, race three futures:
+
+1. **first-byte** — `stdout.read(&mut [u8; 1])` resolves on the first output byte.
+2. **child-exit** — `child.wait()` resolves if ffmpeg exits before any byte.
+3. **stderr-ready** — a line-buffered read on `stderr` resolves when ffmpeg writes a diagnostic line.
+
+Outcomes:
+- **first-byte wins** → success. Re-inject the read byte (push it back via a small `BufReader`/chain ahead of the returned stream) and return the stream as today.
+- **child-exit wins (non-zero)** → read remaining stderr, map via `map_transcode_error` to a `BadInput`/`Io` `TranscodeErrorBody`, and return the structured error instead of 200. (No committed stream to abort.)
+- **stderr-ready wins with a fatal-looking line** (e.g. "No such file", "Invalid data found", "could not open") → treat as likely failure: continue racing first-byte vs child-exit for a short, **generous and overridable** grace window before concluding. This is the *only* place a timeout appears, and it exists solely to avoid hanging on inputs that emit warnings then stall.
+
+### 2.2 Why this satisfies "no naive timers"
+
+The happy path resolves on the first-byte future — no timeout involved. A timeout appears only on the ambiguous stderr-but-no-byte path, is generous (default e.g. 10–15s to tolerate slow network mounts), and is configurable. This is the disciplined use of a bound the discovery doc (§4.1) calls for, not a blanket "wait 3s then guess".
+
+### 2.3 Byte re-injection detail
+
+The validation reads bytes from stdout; those bytes must still reach the client. Wrap stdout in a `BufReader<ChildStdout>`, peek via `fill_buf()` (non-consuming) rather than `read()`, and hand the `BufReader` to `ReaderStream`. `fill_buf` lets us see whether bytes are available without consuming them — so on success nothing is re-injected; it was never removed. Resolve this concretely in planning (confirm `tokio::io::AsyncBufReadExt::fill_buf` semantics against `ReaderStream`'s ownership model).
+
+### 2.4 Failure mapping
+
+`SpawnTranscodeError::BadInput { ffmpeg_stderr }` (already declared, inert in the shipped phase) becomes the variant produced here. `map_transcode_error` already maps `BadInput → 422` (status code to confirm). No new shape.
+
+## 3. (C-mid) Mid-stream watcher + client watchdog
+
+### 3.1 Server watcher
+
+Once the stream is committed (first byte observed), spawn the existing-style background task but restructure it (discovery §2.1 fix):
+
+- **Line-buffered stderr** instead of `read_to_end`, so diagnostics surface live and the "warnings but no bytes" case is detectable going forward.
+- On **child exit (non-zero)** after data has flowed → call `record_session_error(session_id, ...)` (the shipped inert writer) with a `TranscodeErrorBody` produced by `map_transcode_error`. This populates `ACTIVE_SESSION_ERRORS`.
+- Keep the post-mortem logging.
+
+The watcher is per-request under Option A; under Option B it would be per-persistent-transcode.
+
+### 3.2 Client watchdog (deliberate, bounded poll)
+
+No new transport (discovery §4.3). A bounded `setInterval` against `GET /sessions/<id>/status`:
+
+- **Cadence:** coarse (e.g. every 3–5s). Investigate exact value in planning (open question 3).
+- **Suppress when healthy:** do not poll while the `<video>` is actively progressing — re-arm the poll only on `waiting`/`stalled`/`ended-unexpectedly`, or use `timeupdate`/`playing` to reset a "last progress" timestamp and poll only when that timestamp is stale beyond a threshold. Define the stall threshold for piped fragmented MP4 (open question 4) — distinguish natural between-fragment pauses from a dead stream.
+- **On `status.error` non-null** → write `state.playbackError` from the body (reusing shipped plumbing) so the overlay + banner render with appropriate `action`.
+- **Teardown:** clear the interval on player close and on session delete.
+
+This keeps the success path cheap: the interval is suppressed while playback is healthy, and the status read is a map lookup, not a transcode spawn (discovery §4.4).
+
+### 3.3 Interaction with the shipped `<video>` error handler
+
+The shipped best-effort recovery (fetch status on `<video>` `error`) stays. The watchdog is the *active* detector for stalls; the error handler is the *reactive* detector for explicit media-element failures. Both funnel through `state.playbackError`.
+
+## 4. (E) Pre-spawn source existence check
+
+- Before spawning, validate the resolved source path is readable. On failure return **404** (not a confusing ffmpeg stderr path).
+- **Reconcile with `missing_since`** (discovery open question 6): the backing-file row already has `missing_since` (`media.rs:3145`). Decide whether a per-play check also *sets* `missing_since` (so the UI/library can reflect it) or only returns 404. Prefer marking `missing_since` to avoid a parallel notion of "missing".
+- Network/removable paths are the primary motivation; for local indexed files this is cheap insurance.
+
+## 5. Implementation phases (suggested sequencing)
+
+1. **(C-early) first-byte race + byte re-injection + failure mapping.** Highest user-visible value (kills the "200 + dead stream" class). Validates the `fill_buf` approach.
+2. **(C-mid server) watcher writes per-session errors.** Depends on the shipped seam; low risk.
+3. **(C-mid client) bounded watchdog with healthy-suppression.** Depends on (2) and on resolving cadence/stall thresholds (open questions 3, 4).
+4. **(E) source existence + `missing_since` reconciliation.** Independent; can land anytime.
+
+Each phase is independently shippable and testable.
+
+## 6. Testing approach (extends shipped conventions)
+
+- **(C-early) inline tests in `transcode.rs` / a new module:** race behavior using a fake child whose stdout/stderr/exit are controlled by the test (shims, as in the shipped resolver tests). Assert: first-byte → stream returned; early exit → structured error, no stream; stderr-fatal-then-stall → structured error after grace.
+- **(C-mid server) route test:** simulate a transcode that exits non-zero mid-stream; assert `GET /sessions/<id>/status` returns the error body; assert a clean session returns `null`.
+- **(C-mid client) manual + (future) harness:** the project has no frontend test runner today; watchdog behavior is manual until one exists (call out as scoped).
+- **(E) route test:** missing source path → 404 and `missing_since` set; present → unchanged.
+- Real-ffmpeg smoke tests remain behind the opt-in flag from the shipped phase.
+
+## 7. Risks & mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Byte re-injection corrupts the stream | Use `fill_buf` (non-consuming peek) so no re-injection is needed; add a byte-exact test. |
+| Grace timeout mistunes for slow mounts | Make it generous + configurable; race resolves on first byte for the common case. |
+| Watchdog false-positives on between-fragment pauses | Define stall via child-exit observation + stale-progress threshold, not raw byte rate (open question 4). |
+| Option B temptation creep | This plan commits to Option A; Option B is a separate future decision. |
+| Parallel "missing" notions | Reconcile with `missing_since` in (E) rather than adding new state. |
+
+## 8. Preconditions inherited from the shipped phase
+
+This phase assumes the shipped spec landed: the `ACTIVE_SESSION_ERRORS` store + `record_session_error` writer, the `GET /sessions/<id>/status` reader, the shared `map_transcode_error` + `TranscodeErrorBody`, and the client `state.playbackError` + overlay/banner plumbing. Confirm these are present before starting; if any were descoped, update this plan.

From 5dd13448b0eb17447c7add8674251a6a25f575ba Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Thu, 18 Jun 2026 20:31:16 -0300
Subject: [PATCH 03/27] Add implementation plan: transcode ffmpeg resolution &
 player errors

---
 ...ode-ffmpeg-resolution-and-player-errors.md | 1803 +++++++++++++++++
 1 file changed, 1803 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md

diff --git a/docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md b/docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md
new file mode 100644
index 00000000..2ac1cae4
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md
@@ -0,0 +1,1803 @@
+# Transcode FFmpeg Resolution & Player Error Surfacing — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix transcoding failures (ffmpeg not resolvable from GUI-launched processes; player shows black screen instead of an error) by adding a robust ffmpeg resolver, a discovery/settings UI, structured stream errors, and a layered client error UX — all timer-free.
+
+**Architecture:** A new `ffmpeg_resolve` module is the single source of truth for locating ffmpeg/ffprobe, used by both capability detection and the actual spawn (so "available in UI" ⟺ "actually launches"). Spawn failures return a structured `TranscodeErrorBody` instead of a bare 500. The client does a deterministic capabilities preflight before playback and surfaces failures through an existing in-player overlay plus the global banner. Two inert seams (per-session error store + shared error-mapper) are laid for a deferred lifecycle phase. Timed/lifecycle work is out of scope (see the companion discovery/plan docs).
+
+**Tech Stack:** Rust + Rocket 0.5 + tokio + rocket_okapi + serde (server); TypeScript SPA (client-web). Tests: inline `#[cfg(test)]` + integration tests via `create_test_client`. `tempfile` added as a dev-dependency for hermetic resolver tests. No new realtime transport.
+
+**Spec:** `docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md` (read it first).
+
+---
+
+## Conventions for this plan
+
+- **Formatting:** always `cargo +nightly fmt` (per `AGENTS.md`). Run after every code change.
+- **Testing:** pure logic → inline `#[cfg(test)] mod tests` (pattern: `crates/server/src/media.rs`); HTTP routes → integration tests in `crates/server/tests/test_web/routes/` using `create_test_client` + `make_request` (pattern: `tests/test_web/routes/settings.rs`). The project uses `#[rocket::async_test]` for async integration tests and `#[test]` for inline.
+- **Route style:** `#[openapi(tag = "Media")]` + snake_case fn, registered in `crates/server/src/web/routes/mod.rs` `api_routes()` via `openapi_get_routes!`. Admin routes take `_admin_guard: AdminGuard` (`crates/server/src/auth.rs:90`).
+- **Type style:** response types derive `(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)` with a doc comment per field (pattern: `BinaryCapability` at `media.rs:115`).
+- **Commits:** one logical change per commit, frequent. This plan uses `feat:`/`test:`/`refactor:` prefixes.
+- **The shell-path framing is a red herring** (spec §1.1): `Command::args` bypasses the shell; spaces/brackets are passed verbatim. Do NOT add quoting anywhere — it would be dead code.
+
+## Security decision (spec §4.1 Note 4): binary-name allow-list
+
+The resolver accepts a configured path/name from settings. To prevent path-lookup abuse (a future vulnerability leaking an attacker-controlled path into an `exec`), `resolve_binary` enforces a **hardcoded allow-list of binary base-names** (`ffmpeg`, `ffprobe`). Behavior:
+
+- If the configured value is a **bare name**: it must be in the allow-list; otherwise `Missing`. (A bare name is only ever looked up as that name.)
+- If the configured value is a **path** (absolute or relative with a separator): the **base name** (`file_name()`) must be in the allow-list; otherwise `Missing`. The path itself can point anywhere the admin chose — we only constrain that it *is* an ffmpeg/ffprobe binary by name.
+
+This blocks `exec("/some/path/anything")` while still allowing absolute paths to ffmpeg installed anywhere. It is documented in `ffmpeg_resolve.rs` and asserted by tests.
+
+## Resolver path lists (spec §4.1 Notes 2–3): package-manager coverage
+
+Well-known search directories, in priority order (first hit wins). Lower-priority managers are simply listed further down — no priority property.
+
+- **macOS:** `/opt/homebrew/bin` (Apple Silicon), `/usr/local/bin` (Intel Homebrew + manual), `/opt/homebrew/sbin`, `/usr/local/sbin`, `/usr/bin`, `/bin`
+- **Linux:** `/usr/local/bin`, `/usr/bin`, `/bin`, `/usr/sbin`, `/opt/ffmpeg/bin`, `/snap/bin` (Snap), `/home/.nix-profile/bin` is user-specific so **excluded** (Nix users set an absolute path)
+- **Windows:** `C:\Program Files\ffmpeg\bin`, `C:\Program Files (x86)\ffmpeg\bin`, `%USERPROFILE%\bin`, `C:\ffmpeg\bin`, plus `%LOCALAPPDATA%\Microsoft\WinGet\Packages\*\ffmpeg*\bin` is glob-based and **excluded** for simplicity (WinGet users set an absolute path or rely on PATH)
+
+Bare-name-vs-path distinction (Note 1): meaningful only for the allow-list check and for whether we attempt PATH lookup vs absolute-path validation. The resolver handles both uniformly via `Path::new(configured)` — see Task 1.
+
+---
+
+## File structure
+
+**New files:**
+- `crates/server/src/ffmpeg_resolve.rs` — the resolver module (logic + inline tests).
+- `crates/server/tests/test_web/routes/tools.rs` — integration tests for the discover + status endpoints.
+
+**Modified files (server):**
+- `crates/server/src/lib.rs` — declare `pub mod ffmpeg_resolve;`
+- `crates/server/Cargo.toml` — add `tempfile` dev-dependency + `real-ffmpeg-tests` feature.
+- `crates/server/src/transcode.rs` — resolved-path spawn, `SpawnTranscodeError`, `TranscodeErrorBody`, `map_transcode_error`, inline tests.
+- `crates/server/src/media.rs` — `detect_binary` delegates to resolver.
+- `crates/server/src/web/routes/media.rs` — `ToolDiscoveryResponse`/`ToolCandidate`/`BinaryProbe`/`SessionStatusResponse` types, `discover_transcoding_tools` route, `get_session_status` route, `ACTIVE_SESSION_ERRORS` + `record_session_error` (inert), structured stream-error in `get_session_stream`.
+- `crates/server/src/web/routes/mod.rs` — register the two new routes.
+- `crates/server/tests/test_web/routes/mod.rs` — declare `pub mod tools;`.
+
+**Modified files (client):**
+- `crates/client-web/src/api.ts` — `discoverTranscodingTools()`, `getSessionStatus()`, `ToolDiscoveryResponse`/`TranscodeErrorBody`/`SessionStatusResponse` types.
+- `crates/client-web/src/app/types.ts` — `playbackError` on `AppState`.
+- `crates/client-web/src/app/settingsView.ts` — detect button + directory radios.
+- `crates/client-web/src/app/playbackController.ts` — preflight in `startPlayback`, status-read recovery in the `<video>` error handler, dynamic overlay/banner copy.
+
+---
+
+## Task 1: `ffmpeg_resolve` module — resolution logic
+
+**Files:**
+- Create: `crates/server/src/ffmpeg_resolve.rs`
+- Modify: `crates/server/src/lib.rs` (add module declaration)
+- Modify: `crates/server/Cargo.toml` (add `tempfile` dev-dependency)
+
+- [ ] **Step 1: Add `tempfile` dev-dependency**
+
+Modify `crates/server/Cargo.toml` `[dev-dependencies]` (currently lines 102–104):
+
+```toml
+[dev-dependencies]
+async-std.workspace = true
+rstest.workspace = true
+tempfile = "3.13"
+```
+
+- [ ] **Step 2: Declare the module**
+
+In `crates/server/src/lib.rs`, add alongside the other `pub mod` declarations (match existing style):
+
+```rust
+pub mod ffmpeg_resolve;
+```
+
+- [ ] **Step 3: Write the failing tests**
+
+Create `crates/server/src/ffmpeg_resolve.rs` with only the test module first (the implementation doesn't exist yet, so this fails to compile — that's the "red"):
+
+```rust
+//! Locating the ffmpeg/ffprobe executables used for media processing.
+//!
+//! GUI-launched processes (macOS `.app` bundles, some Linux desktop launchers)
+//! do not inherit the user's shell PATH, so a bare `ffmpeg` lookup can fail
+//! even when the binary is installed under e.g. `/opt/homebrew/bin`. This
+//! module is the single source of truth for resolution and is used by BOTH
+//! capability display and the actual transcode spawn, so "available in UI"
+//! is equivalent to "actually launches".
+
+// standard imports
+use std::path::PathBuf;
+
+// lib imports
+use once_cell::sync::Lazy;
+
+/// Binary base-names the resolver is allowed to resolve. Anything else is
+/// rejected as `Missing`. This is a security boundary: it prevents a
+/// future bug or compromised setting from causing an arbitrary `exec`.
+pub const ALLOWED_BINARIES: &[&str] = &["ffmpeg", "ffprobe"];
+
+/// How a binary was located.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResolveSource {
+    /// The configured value was an absolute path that exists and is executable.
+    ConfiguredAbsolute,
+    /// The configured bare name resolved on PATH.
+    PathLookup,
+    /// Found in a well-known install directory (not the configured path).
+    WellKnown,
+}
+
+/// Result of resolving a single binary.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResolvedBinary {
+    /// The binary was found.
+    Found {
+        resolved_path: PathBuf,
+        via: ResolveSource,
+    },
+    /// The binary could not be found. `checked_paths` lists every location
+    /// inspected, for UI display.
+    Missing {
+        configured: String,
+        checked_paths: Vec<PathBuf>,
+    },
+}
+
+/// Platform-specific well-known directories, highest priority first.
+static WELL_KNOWN_DIRS: Lazy<Vec<PathBuf>> = Lazy::new(well_known_dirs);
+
+#[cfg(not(target_os = "windows"))]
+fn well_known_dirs() -> Vec<PathBuf> {
+    #[cfg(target_os = "macos")]
+    {
+        vec![
+            PathBuf::from("/opt/homebrew/bin"),
+            PathBuf::from("/usr/local/bin"),
+            PathBuf::from("/opt/homebrew/sbin"),
+            PathBuf::from("/usr/local/sbin"),
+            PathBuf::from("/usr/bin"),
+            PathBuf::from("/bin"),
+        ]
+    }
+    #[cfg(not(target_os = "macos"))]
+    {
+        vec![
+            PathBuf::from("/usr/local/bin"),
+            PathBuf::from("/usr/bin"),
+            PathBuf::from("/bin"),
+            PathBuf::from("/usr/sbin"),
+            PathBuf::from("/opt/ffmpeg/bin"),
+            PathBuf::from("/snap/bin"),
+        ]
+    }
+}
+
+#[cfg(target_os = "windows")]
+fn well_known_dirs() -> Vec<PathBuf> {
+    let mut dirs = vec![
+        PathBuf::from(r"C:\Program Files\ffmpeg\bin"),
+        PathBuf::from(r"C:\Program Files (x86)\ffmpeg\bin"),
+        PathBuf::from(r"C:\ffmpeg\bin"),
+    ];
+    if let Ok(home) = std::env::var("USERPROFILE") {
+        dirs.push(PathBuf::from(home).join("bin"));
+    }
+    dirs
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // A binary is "executable enough" for these tests if it exists on disk;
+    // we create real (empty) files rather than mocking stat calls.
+    fn write_shim(dir: &std::path::Path, name: &str) -> PathBuf {
+        let path = dir.join(name);
+        std::fs::write(&path, b"#!/bin/sh\nexit 0\n").unwrap();
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let mut perms = std::fs::metadata(&path).unwrap().permissions();
+            perms.set_mode(0o755);
+            std::fs::set_permissions(&path, perms).unwrap();
+        }
+        path
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn absolute_configured_path_is_used() {
+        let dir = tempfile::tempdir().unwrap();
+        let ffmpeg = write_shim(dir.path(), "ffmpeg");
+        let resolved = resolve_binary(ffmpeg.to_str().unwrap(), "ffmpeg");
+        assert!(matches!(
+            resolved,
+            ResolvedBinary::Found { via: ResolveSource::ConfiguredAbsolute, .. }
+        ));
+        if let ResolvedBinary::Found { resolved_path, .. } = resolved {
+            assert_eq!(resolved_path, ffmpeg);
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn disallowed_base_name_is_rejected_even_as_absolute_path() {
+        let dir = tempfile::tempdir().unwrap();
+        let rogue = write_shim(dir.path(), "not-ffmpeg");
+        let resolved = resolve_binary(rogue.to_str().unwrap(), "ffmpeg");
+        // The requested binary_name itself must be allowed; a rogue name is never resolved.
+        assert!(matches!(resolve_binary(rogue.to_str().unwrap(), "rogue"), ResolvedBinary::Missing { .. }));
+        // Asking for an allowed name via a path whose base name is rogue is also rejected.
+        let _ = resolved; // (configured-absolute path with wrong base name -> Missing; see impl)
+        assert!(matches!(
+            resolve_binary(rogue.to_str().unwrap(), "ffmpeg"),
+            ResolvedBinary::Missing { .. }
+        ));
+    }
+
+    #[test]
+    fn missing_returns_checked_paths() {
+        let resolved = resolve_binary("/definitely/does/not/exist/ffmpeg", "ffmpeg");
+        match resolved {
+            ResolvedBinary::Missing { configured, checked_paths } => {
+                assert_eq!(configured, "/definitely/does/not/exist/ffmpeg");
+                assert!(!checked_paths.is_empty());
+            }
+            other => panic!("expected Missing, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn allowed_binaries_constant_is_what_we_expect() {
+        assert_eq!(ALLOWED_BINARIES, &["ffmpeg", "ffprobe"]);
+    }
+}
+```
+
+- [ ] **Step 4: Run the tests to verify they fail (compile error)**
+
+Run: `cargo test -p koko-server --lib ffmpeg_resolve 2>&1 | head -30`
+Expected: FAIL — the tests reference `resolve_binary`, which is not yet defined. (The `#[cfg(unix)]` shims also need `tempfile`, added in Step 1.)
+
+- [ ] **Step 5: Write the minimal implementation**
+
+Append to `crates/server/src/ffmpeg_resolve.rs` (above the test module — move the test module to the bottom of the file):
+
+```rust
+/// Resolve a single binary.
+///
+/// `configured` is what the admin set (a bare name like `ffmpeg`, or an
+/// absolute/relative path). `binary_name` is the canonical name being looked
+/// up and MUST be in [`ALLOWED_BINARIES`].
+///
+/// Resolution order:
+/// 1. If `configured` looks like a path (contains a separator) or is absolute,
+///    validate its base name is allowed and it exists + is executable.
+/// 2. Else treat `configured` as a bare name: require it to be allowed, then
+///    look it up on PATH.
+/// 3. Else fall back to the well-known directory list for `binary_name`.
+/// 4. Else `Missing` with every checked location.
+pub fn resolve_binary(configured: &str, binary_name: &str) -> ResolvedBinary {
+    if !ALLOWED_BINARIES.contains(&binary_name) {
+        return ResolvedBinary::Missing {
+            configured: configured.to_string(),
+            checked_paths: Vec::new(),
+        };
+    }
+
+    let mut checked: Vec<PathBuf> = Vec::new();
+    let configured_path = PathBuf::from(configured);
+
+    // 1. Configured-as-path: only if it actually has a path component, or is absolute.
+    let is_path_form = configured_path
+        .parent()
+        .map(|parent| !parent.as_os_str().is_empty())
+        .unwrap_or(false)
+        || configured_path.is_absolute();
+
+    if is_path_form {
+        if base_name_is_allowed(&configured_path, binary_name) && is_executable(&configured_path) {
+            return ResolvedBinary::Found {
+                resolved_path: canonicalize(&configured_path),
+                via: ResolveSource::ConfiguredAbsolute,
+            };
+        }
+        checked.push(configured_path.clone());
+    } else {
+        // 2. Bare name: must be the allowed name itself.
+        if configured == binary_name {
+            if let Some(found) = lookup_on_path(binary_name) {
+                return ResolvedBinary::Found {
+                    resolved_path: found,
+                    via: ResolveSource::PathLookup,
+                };
+            }
+            checked.push(PathBuf::from(configured));
+        }
+    }
+
+    // 3. Well-known directories.
+    for dir in WELL_KNOWN_DIRS.iter() {
+        let candidate = dir.join(binary_name);
+        if is_executable(&candidate) {
+            return ResolvedBinary::Found {
+                resolved_path: canonicalize(&candidate),
+                via: ResolveSource::WellKnown,
+            };
+        }
+        checked.push(candidate);
+    }
+
+    ResolvedBinary::Missing {
+        configured: configured.to_string(),
+        checked_paths: checked,
+    }
+}
+
+/// Convenience: resolve ffmpeg using the configured value.
+pub fn resolve_ffmpeg(configured: &str) -> ResolvedBinary {
+    resolve_binary(configured, "ffmpeg")
+}
+
+/// Convenience: resolve ffprobe using the configured value.
+pub fn resolve_ffprobe(configured: &str) -> ResolvedBinary {
+    resolve_binary(configured, "ffprobe")
+}
+
+fn base_name_is_allowed(path: &std::path::Path, _binary_name: &str) -> bool {
+    // The base name of the configured path must itself be an allowed binary.
+    path.file_name()
+        .and_then(|name| name.to_str())
+        .map(|name| ALLOWED_BINARIES.contains(&name))
+        .unwrap_or(false)
+}
+
+fn is_executable(path: &std::path::Path) -> bool {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let metadata = match std::fs::metadata(path) {
+            Ok(m) => m,
+            Err(_) => return false,
+        };
+        if !metadata.is_file() {
+            return false;
+        }
+        metadata.permissions().mode() & 0o111 != 0
+    }
+    #[cfg(windows)]
+    {
+        std::fs::metadata(path)
+            .map(|m| m.is_file())
+            .unwrap_or(false)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        std::fs::metadata(path)
+            .map(|m| m.is_file())
+            .unwrap_or(false)
+    }
+}
+
+fn canonicalize(path: &std::path::Path) -> PathBuf {
+    std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
+}
+
+fn lookup_on_path(name: &str) -> Option<PathBuf> {
+    let path_var = std::env::var_os("PATH")?;
+    for dir in std::env::split_paths(&path_var) {
+        let candidate = dir.join(name);
+        if is_executable(&candidate) {
+            return Some(canonicalize(&candidate));
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    // ... (the test module from Step 3 goes here, unchanged)
+}
+```
+
+(Note: delete the duplicate test module from Step 3's position and keep a single copy at the bottom of the file.)
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `cargo test -p koko-server --lib ffmpeg_resolve 2>&1 | tail -20`
+Expected: PASS — all `ffmpeg_resolve::tests::*` pass. On Windows the two `#[cfg(unix)]` tests are skipped.
+
+- [ ] **Step 7: Format and commit**
+
+```bash
+cargo +nightly fmt
+git add crates/server/src/ffmpeg_resolve.rs crates/server/src/lib.rs crates/server/Cargo.toml
+git commit -m "feat(server): add ffmpeg_resolve module with allow-listed binary resolution"
+```
+
+---
+
+## Task 2: Add version probing + thread the resolver into `detect_binary`
+
+**Files:**
+- Modify: `crates/server/src/ffmpeg_resolve.rs` (add `probe_version`)
+- Modify: `crates/server/src/media.rs:5997` (`detect_binary` delegates to resolver)
+
+- [ ] **Step 1: Write the failing test for version probing**
+
+In `ffmpeg_resolve.rs` test module, add (Unix-only, uses a shim that prints a version line):
+
+```rust
+    #[cfg(unix)]
+    #[test]
+    fn probe_version_reads_first_stdout_line() {
+        let dir = tempfile::tempdir().unwrap();
+        // A shim that mimics `ffmpeg -version` first line.
+        let shim = dir.join("ffmpeg");
+        std::fs::write(
+            &shim,
+            "#!/bin/sh\necho 'ffmpeg version 7.0.2, built locally'\nexit 0\n",
+        )
+        .unwrap();
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = std::fs::metadata(&shim).unwrap().permissions();
+        perms.set_mode(0o755);
+        std::fs::set_permissions(&shim, perms).unwrap();
+
+        let version = probe_version(&shim);
+        assert_eq!(version.as_deref(), Some("ffmpeg version 7.0.2, built locally"));
+    }
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo test -p koko-server --lib ffmpeg_resolve::tests::probe_version 2>&1 | tail -10`
+Expected: FAIL — `probe_version` undefined.
+
+- [ ] **Step 3: Implement `probe_version`**
+
+In `ffmpeg_resolve.rs`, add (with the other free functions):
+
+```rust
+/// Run `<binary> -version` and return the first stdout line, or None on failure.
+/// Used for capability display. Uses the synchronous std Command because this
+/// is called rarely and from sync contexts (detect_binary).
+pub fn probe_version(path: &std::path::Path) -> Option<String> {
+    let output = std::process::Command::new(path).arg("-version").output().ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&output.stdout)
+        .lines()
+        .next()
+        .map(|line| line.trim().to_string())
+        .filter(|line| !line.is_empty())
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo test -p koko-server --lib ffmpeg_resolve::tests::probe_version 2>&1 | tail -10`
+Expected: PASS.
+
+- [ ] **Step 5: Refactor `detect_binary` to delegate to the resolver**
+
+Locate `detect_binary` at `crates/server/src/media.rs:5997`. Replace its body to use the resolver. First read the surrounding `BinaryCapability` struct (it's at `media.rs:115`) to preserve its shape.
+
+Change the `detect_binary` function from a hand-rolled `Command::new(binary).arg("-version")` to:
+
+```rust
+fn detect_binary(configured: &str, binary_name: &str) -> BinaryCapability {
+    use crate::ffmpeg_resolve::{
+        self,
+        ResolveSource,
+        ResolvedBinary,
+    };
+
+    match ffmpeg_resolve::resolve_binary(configured, binary_name) {
+        ResolvedBinary::Found { resolved_path, via } => {
+            let version = ffmpeg_resolve::probe_version(&resolved_path);
+            log::info!(
+                "Resolved {} via {:?}: {}",
+                binary_name,
+                via,
+                resolved_path.display()
+            );
+            BinaryCapability {
+                configured_path: configured.to_string(),
+                available: true,
+                version,
+                error: None,
+            }
+        }
+        ResolvedBinary::Missing { configured, checked_paths } => {
+            let checked_display = checked_paths
+                .iter()
+                .map(|p| p.display().to_string())
+                .collect::<Vec<_>>()
+                .join(", ");
+            log::warn!(
+                "Could not resolve {}; checked: [{}]",
+                binary_name,
+                checked_display
+            );
+            BinaryCapability {
+                configured_path: configured,
+                available: false,
+                version: None,
+                error: Some(format!(
+                    "Could not find {binary_name}. Checked: {checked_display}"
+                )),
+            }
+        }
+    }
+}
+```
+
+Then update the two callers `inspect_transcoding_capability` (`media.rs:785`) and any other call sites that currently call `detect_binary(&settings.ffmpeg_path)` — they must pass the binary name:
+
+```rust
+pub fn inspect_transcoding_capability(settings: &FfmpegSettings) -> TranscodingCapability {
+    TranscodingCapability {
+        ffmpeg: detect_binary(&settings.ffmpeg_path, "ffmpeg"),
+        ffprobe: detect_binary(&settings.ffprobe_path, "ffprobe"),
+    }
+}
+```
+
+Search for other `detect_binary(` call sites and fix them similarly: `grep -n "detect_binary(" crates/server/src/`.
+
+- [ ] **Step 6: Build and run the existing media tests**
+
+Run: `cargo test -p koko-server --lib 2>&1 | tail -20`
+Expected: PASS — existing `media::tests` still pass (they don't touch `detect_binary`, but the build must succeed).
+
+- [ ] **Step 7: Format and commit**
+
+```bash
+cargo +nightly fmt
+git add crates/server/src/ffmpeg_resolve.rs crates/server/src/media.rs
+git commit -m "refactor(server): detect_binary delegates to ffmpeg_resolve with version probe"
+```
+
+---
+
+## Task 3: `SpawnTranscodeError` + `TranscodeErrorBody` + `map_transcode_error` (seam #2)
+
+**Files:**
+- Modify: `crates/server/src/transcode.rs`
+
+- [ ] **Step 1: Write the failing tests for the mapper**
+
+At the bottom of `crates/server/src/transcode.rs`, add an inline test module:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    #[test]
+    fn executable_missing_maps_to_open_settings_action() {
+        let err = SpawnTranscodeError::ExecutableMissing {
+            checked_paths: vec![PathBuf::from("/usr/bin/ffmpeg")],
+        };
+        let (status, body) = map_transcode_error(err);
+        assert_eq!(status, rocket::http::Status::ServiceUnavailable);
+        assert_eq!(body.code, "transcode_executable_missing");
+        assert_eq!(body.action, Some("open_settings"));
+        assert!(body.message.contains("ffmpeg"));
+    }
+
+    #[test]
+    fn io_error_maps_to_failed_with_no_action() {
+        let err = SpawnTranscodeError::Io(std::io::Error::other("boom"));
+        let (status, body) = map_transcode_error(err);
+        assert_eq!(status, rocket::http::Status::InternalServerError);
+        assert_eq!(body.code, "transcode_failed");
+        assert_eq!(body.action, None);
+    }
+
+    #[test]
+    fn bad_input_maps_to_input_error() {
+        let err = SpawnTranscodeError::BadInput {
+            ffmpeg_stderr: "No such file".into(),
+        };
+        let (status, body) = map_transcode_error(err);
+        assert_eq!(status, rocket::http::Status::UnprocessableEntity);
+        assert_eq!(body.code, "transcode_input_error");
+        assert_eq!(body.action, None);
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test -p koko-server --lib transcode::tests 2>&1 | tail -15`
+Expected: FAIL — `SpawnTranscodeError`, `TranscodeErrorBody`, `map_transcode_error` undefined.
+
+- [ ] **Step 3: Add the types and mapper**
+
+Near the top of `crates/server/src/transcode.rs` (after the imports, before `TranscodeProcess`), add:
+
+```rust
+use rocket::http::Status;
+
+/// A structured error from attempting to spawn a transcode.
+#[derive(Debug)]
+pub enum SpawnTranscodeError {
+    /// ffmpeg could not be resolved/executed. `checked_paths` lists where we looked.
+    ExecutableMissing { checked_paths: Vec<std::path::PathBuf> },
+    /// ffmpeg started but reported its input was unusable. (Produced by the
+    /// deferred lifecycle phase; declared here so the shared mapper is complete.)
+    BadInput { ffmpeg_stderr: String },
+    /// Any other spawn-time I/O error.
+    Io(std::io::Error),
+}
+
+impl From<std::io::Error> for SpawnTranscodeError {
+    fn from(error: std::io::Error) -> Self {
+        Self::Io(error)
+    }
+}
+
+/// The JSON body returned to clients when a transcode fails. The `action`
+/// field lets the UI decide whether to show an actionable control (e.g.
+/// "Open settings") for this kind of failure.
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct TranscodeErrorBody {
+    /// Stable machine code: `transcode_executable_missing` | `transcode_input_error` | `transcode_failed`.
+    pub code: &'static str,
+    /// Human-readable explanation.
+    pub message: String,
+    /// Optional UI action hint, e.g. `Some("open_settings")`.
+    pub action: Option<&'static str>,
+}
+
+/// Map a [`SpawnTranscodeError`] to an HTTP status + body. This is the single
+/// error-shaping function reused by the route handler today and the lifecycle
+/// watcher in a later phase.
+pub fn map_transcode_error(error: SpawnTranscodeError) -> (Status, TranscodeErrorBody) {
+    match error {
+        SpawnTranscodeError::ExecutableMissing { checked_paths } => {
+            let checked = checked_paths
+                .iter()
+                .map(|p| p.display().to_string())
+                .collect::<Vec<_>>()
+                .join(", ");
+            (
+                Status::ServiceUnavailable,
+                TranscodeErrorBody {
+                    code: "transcode_executable_missing",
+                    message: format!(
+                        "FFmpeg could not be found. Install it or set its path in Settings. \
+                         Checked: [{checked}]"
+                    ),
+                    action: Some("open_settings"),
+                },
+            )
+        }
+        SpawnTranscodeError::BadInput { ffmpeg_stderr } => (
+            Status::UnprocessableEntity,
+            TranscodeErrorBody {
+                code: "transcode_input_error",
+                message: format!(
+                    "FFmpeg could not read the source media. {}",
+                    ffmpeg_stderr.trim()
+                ),
+                action: None,
+            },
+        ),
+        SpawnTranscodeError::Io(error) => (
+            Status::InternalServerError,
+            TranscodeErrorBody {
+                code: "transcode_failed",
+                message: format!("Transcode failed to start: {error}"),
+                action: None,
+            },
+        ),
+    }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test -p koko-server --lib transcode::tests 2>&1 | tail -15`
+Expected: PASS — all three mapper tests pass.
+
+- [ ] **Step 5: Format and commit**
+
+```bash
+cargo +nightly fmt
+git add crates/server/src/transcode.rs
+git commit -m "feat(server): add SpawnTranscodeError + shared map_transcode_error"
+```
+
+---
+
+## Task 4: Thread the resolver into the spawn functions (THE fix for issue 1)
+
+**Files:**
+- Modify: `crates/server/src/transcode.rs` (`spawn_transcode`, `spawn_transcode_stdout`)
+
+- [ ] **Step 1: Change `spawn_transcode` and `spawn_transcode_stdout` signatures and bodies**
+
+These currently return `Result<Child, std::io::Error>` and call `Command::new(&settings.ffmpeg_path)`. Change them to resolve first, return `SpawnTranscodeError`, and execute the resolved path.
+
+Locate `spawn_transcode` (`transcode.rs:184`) and `spawn_transcode_stdout` (`transcode.rs:214`). Replace `spawn_transcode_stdout` with:
+
+```rust
+/// Spawns a transcode process that writes a fragmented stream to stdout.
+pub async fn spawn_transcode_stdout(
+    _session_id: &str,
+    spec: &TranscodeSpec,
+    settings: &FfmpegSettings,
+) -> Result<Child, SpawnTranscodeError> {
+    let args = spec.to_ffmpeg_stdout_args();
+
+    let resolved = crate::ffmpeg_resolve::resolve_ffmpeg(&settings.ffmpeg_path);
+    let ffmpeg_path = match resolved {
+        crate::ffmpeg_resolve::ResolvedBinary::Found { resolved_path, .. } => {
+            log::info!(
+                "Starting FFmpeg stdout stream: {} {}",
+                resolved_path.display(),
+                args.join(" ")
+            );
+            resolved_path
+        }
+        crate::ffmpeg_resolve::ResolvedBinary::Missing { checked_paths, .. } => {
+            return Err(SpawnTranscodeError::ExecutableMissing { checked_paths });
+        }
+    };
+
+    let mut command = Command::new(&ffmpeg_path);
+    command
+        .args(&args)
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .kill_on_drop(true);
+    let child = command.spawn().map_err(SpawnTranscodeError::Io)?;
+
+    Ok(child)
+}
+```
+
+Apply the equivalent change to `spawn_transcode` (`:184`) — same resolver block, but keep its existing `Stdio::null()` for stdout/stderr and `to_ffmpeg_args()` (not stdout args). Its signature becomes `Result<Child, SpawnTranscodeError>`.
+
+- [ ] **Step 2: Build to verify the signatures compile**
+
+Run: `cargo build -p koko-server 2>&1 | tail -20`
+Expected: the build fails at the call site in `media.rs` (`get_session_stream` still expects `std::io::Error`). That's the next task. Note: this task intentionally leaves the build red at the route; Task 5 fixes it. Do NOT commit yet.
+
+---
+
+## Task 5: Structured stream error + per-session error store (seam #1) in `get_session_stream`
+
+**Files:**
+- Modify: `crates/server/src/web/routes/media.rs`
+
+- [ ] **Step 1: Add the inert per-session error store and status types**
+
+Near `ACTIVE_TRANSCODE_TASKS` (`media.rs:317`), add:
+
+```rust
+/// Per-session transcode errors, written by the lifecycle watcher (deferred
+/// phase) and read by `get_session_status`. Inert in the current phase: nothing
+/// writes to it yet.
+static ACTIVE_SESSION_ERRORS: Lazy<RwLock<std::collections::HashMap<String, crate::transcode::TranscodeErrorBody>>> =
+    Lazy::new(|| RwLock::new(std::collections::HashMap::new()));
+
+/// Record a per-session transcode error. Unused in this phase; the lifecycle
+/// watcher will call it.
+#[allow(dead_code)]
+async fn record_session_error(session_id: &str, error: crate::transcode::TranscodeErrorBody) {
+    ACTIVE_SESSION_ERRORS
+        .write()
+        .await
+        .insert(session_id.to_string(), error);
+}
+```
+
+(Confirm `RwLock`/`Lazy` are imported in this file — they are, via `ACTIVE_TRANSCODE_TASKS`'s existing imports. Adjust imports if the compiler asks.)
+
+Add the status response type near `SessionStream` (`media.rs:163`). Because the streaming route returns `Err(status)` (the `<video>` src can't read a JSON body anyway — recovery is via the status read), `TranscodeErrorBody` itself does **not** need `JsonSchema`; only the dedicated status types below do:
+
+```rust
+/// The structured transcode error as exposed to clients (owned strings, so it
+/// serializes cleanly and matches the client `TranscodeErrorBody` type).
+#[derive(Debug, Clone, serde::Serialize, rocket_okapi::JsonSchema)]
+pub struct SessionTranscodeError {
+    /// Stable machine code.
+    pub code: String,
+    /// Human-readable explanation.
+    pub message: String,
+    /// Optional UI action hint.
+    pub action: Option<String>,
+}
+
+impl From<crate::transcode::TranscodeErrorBody> for SessionTranscodeError {
+    fn from(body: crate::transcode::TranscodeErrorBody) -> Self {
+        Self {
+            code: body.code.to_string(),
+            message: body.message,
+            action: body.action.map(str::to_string),
+        }
+    }
+}
+
+/// Status of a playback session's transcode, returned to the client so it can
+/// recover a structured error when the `<video>` element stalls.
+#[derive(Debug, Clone, serde::Serialize, rocket_okapi::JsonSchema)]
+pub struct SessionStatusResponse {
+    /// A transcode error for this session, if any. `null` while the session is
+    /// healthy or (in this phase) since nothing writes errors yet.
+    pub error: Option<SessionTranscodeError>,
+}
+```
+
+(Leave `TranscodeErrorBody`'s derives exactly as written in Task 3: `#[derive(Debug, Clone, serde::Serialize)]` — no `JsonSchema` needed.)
+
+- [ ] **Step 2: Map spawn errors to structured JSON in `get_session_stream`**
+
+Locate the `match crate::transcode::spawn_transcode_stdout(...)` block (`media.rs:3621-3655`). Change the `Err(e)` arm to use the mapper and return a JSON body instead of a bare 500:
+
+```rust
+        Err(error) => {
+            let (status, body) = crate::transcode::map_transcode_error(error);
+            log::error!(
+                "Failed to spawn transcode for session {}: {} ({} — action: {:?})",
+                session_id,
+                body.message,
+                body.code,
+                body.action
+            );
+            // Persist for the status read, so the client can recover the detail
+            // even though the stream response body is unreadable from a <video> src.
+            record_session_error(&session_id, body.clone()).await;
+            // Use rocket's Json to serialize. Note: TranscodeErrorBody derives Serialize.
+            Err(status)
+        }
+```
+
+Note: returning `Err(status)` preserves current behavior (the client can't read a media-src body anyway; it uses the status read in Task 9). The structured body is recoverable via `GET /sessions/<id>/status` (Task 6) and is also `log::error!`'d. Because the stream branch returns `Result<SessionStream, Status>`, we can't attach a JSON body to the 5xx on the streaming response without a custom Responder; the status read is the recovery channel. (Documented in spec §4.4.)
+
+If `body.clone()` complains (TranscodeErrorBody must be `Clone`): ensure `#[derive(Debug, Clone)]` on `TranscodeErrorBody` (it already is in Task 3).
+
+- [ ] **Step 3: Build to confirm the whole server compiles**
+
+Run: `cargo build -p koko-server 2>&1 | tail -20`
+Expected: PASS (green again after Task 4's intentional red).
+
+- [ ] **Step 4: Format and commit (Tasks 4 + 5 together)**
+
+```bash
+cargo +nightly fmt
+git add crates/server/src/transcode.rs crates/server/src/web/routes/media.rs
+git commit -m "feat(server): resolve ffmpeg before spawn; structured transcode errors"
+```
+
+---
+
+## Task 6: Discovery + session-status routes
+
+**Files:**
+- Modify: `crates/server/src/web/routes/media.rs`
+- Modify: `crates/server/src/web/routes/mod.rs`
+
+- [ ] **Step 1: Add the discovery response types**
+
+In `crates/server/src/web/routes/media.rs`, near the other response structs (after `ServerCapabilitiesResponse` at `:341`), add:
+
+```rust
+/// Validation result for a single binary (the configured path or a candidate).
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct BinaryProbe {
+    /// The resolved absolute path, if the binary was found.
+    pub resolved_path: Option<String>,
+    /// First line of `ffmpeg -version` / `ffprobe -version`, when available.
+    pub version: Option<String>,
+    /// Why the binary is unavailable, when applicable.
+    pub error: Option<String>,
+}
+
+/// One directory discovered to contain ffmpeg and/or ffprobe.
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct ToolCandidate {
+    /// The directory path (serialized as a string).
+    pub directory: String,
+    /// ffmpeg probe result; `None` if absent in this directory.
+    pub ffmpeg: Option<BinaryProbe>,
+    /// ffprobe probe result; `None` if absent in this directory.
+    pub ffprobe: Option<BinaryProbe>,
+}
+
+/// Result of the on-demand transcoding-tools discovery call.
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct ToolDiscoveryResponse {
+    /// Validation of the user's currently-configured ffmpeg path.
+    pub configured_ffmpeg: BinaryProbe,
+    /// Validation of the user's currently-configured ffprobe path.
+    pub configured_ffprobe: BinaryProbe,
+    /// One entry per directory containing at least one of ffmpeg/ffprobe.
+    pub candidates: Vec<ToolCandidate>,
+}
+```
+
+(Ensure `Serialize, JsonSchema` are imported — they are, used by `ServerCapabilitiesResponse`. If `PartialEq, Eq` conflicts with any field, drop them; they're for test assertions only.)
+
+- [ ] **Step 2: Implement the discovery helper and route**
+
+In `media.rs`, add a private helper that probes a single configured value:
+
+```rust
+fn probe_configured(configured: &str, binary_name: &str) -> BinaryProbe {
+    use crate::ffmpeg_resolve::{self, ResolvedBinary};
+    match ffmpeg_resolve::resolve_binary(configured, binary_name) {
+        ResolvedBinary::Found { resolved_path, .. } => {
+            let version = ffmpeg_resolve::probe_version(&resolved_path);
+            BinaryProbe {
+                resolved_path: Some(resolved_path.display().to_string()),
+                version,
+                error: None,
+            }
+        }
+        ResolvedBinary::Missing { checked_paths, .. } => {
+            let checked = checked_paths
+                .iter()
+                .map(|p| p.display().to_string())
+                .collect::<Vec<_>>()
+                .join(", ");
+            BinaryProbe {
+                resolved_path: None,
+                version: None,
+                error: Some(format!("Not found. Checked: [{checked}]")),
+            }
+        }
+    }
+}
+```
+
+Add the route (place it right after `get_server_capabilities`, `media.rs:3049`):
+
+```rust
+/// Discover ffmpeg/ffprobe candidates and validate the configured paths.
+///
+/// On-demand from the settings page. Searches PATH + well-known locations and
+/// also validates the user's currently-configured paths. Read-only.
+#[openapi(tag = "Media")]
+#[post("/api/v1/system/tools/discover")]
+pub async fn discover_transcoding_tools(
+    _admin_guard: AdminGuard,
+) -> Result<Json<ToolDiscoveryResponse>, Status> {
+    let settings = current_settings();
+    let configured_ffmpeg = probe_configured(&settings.ffmpeg.ffmpeg_path, "ffmpeg");
+    let configured_ffprobe = probe_configured(&settings.ffmpeg.ffprobe_path, "ffprobe");
+
+    // Collect candidate directories from PATH + well-known, de-duplicated, preserving order.
+    use std::collections::HashSet;
+    let mut seen: HashSet<String> = HashSet::new();
+    let mut dirs: Vec<std::path::PathBuf> = Vec::new();
+    if let Some(path_var) = std::env::var_os("PATH") {
+        for dir in std::env::split_paths(&path_var) {
+            if let Some(s) = dir.to_str() {
+                if seen.insert(s.to_string()) {
+                    dirs.push(dir);
+                }
+            }
+        }
+    }
+    for dir in crate::ffmpeg_resolve::well_known_dirs_public() {
+        if let Some(s) = dir.to_str() {
+            if seen.insert(s.to_string()) {
+                dirs.push(dir);
+            }
+        }
+    }
+
+    let mut candidates = Vec::new();
+    for dir in dirs {
+        let ffmpeg = probe_in_dir(&dir, "ffmpeg");
+        let ffprobe = probe_in_dir(&dir, "ffprobe");
+        if ffmpeg.resolved_path.is_some() || ffprobe.resolved_path.is_some() {
+            candidates.push(ToolCandidate {
+                directory: dir.display().to_string(),
+                ffmpeg,
+                ffprobe,
+            });
+        }
+    }
+
+    Ok(Json(ToolDiscoveryResponse {
+        configured_ffmpeg,
+        configured_ffprobe,
+        candidates,
+    }))
+}
+
+fn probe_in_dir(dir: &std::path::Path, binary_name: &str) -> Option<BinaryProbe> {
+    let candidate = dir.join(binary_name);
+    if crate::ffmpeg_resolve::is_executable_public(&candidate) {
+        let version = crate::ffmpeg_resolve::probe_version(&candidate);
+        Some(BinaryProbe {
+            resolved_path: Some(candidate.display().to_string()),
+            version,
+            error: None,
+        })
+    } else {
+        None
+    }
+}
+```
+
+For this to compile, expose two helpers from `ffmpeg_resolve.rs`. Add to that module (they wrap the existing private items):
+
+```rust
+/// Public accessor for the well-known directory list (for discovery).
+pub fn well_known_dirs_public() -> Vec<PathBuf> {
+    WELL_KNOWN_DIRS.clone()
+}
+
+/// Public accessor for the executability check (for discovery).
+pub fn is_executable_public(path: &std::path::Path) -> bool {
+    is_executable(path)
+}
+```
+
+- [ ] **Step 3: Add the session-status route**
+
+In `media.rs`, after `delete_session` (`:3507`), add:
+
+```rust
+/// Return the transcode status for a playback session.
+///
+/// Used by the client to recover a structured error when the `<video>` element
+/// stalls. Returns `{ error: null }` until the lifecycle watcher writes one.
+#[openapi(tag = "Media")]
+#[get("/api/v1/sessions/<session_id>/status")]
+pub async fn get_session_status(
+    session_id: String,
+) -> Result<Json<SessionStatusResponse>, Status> {
+    // Validate the session exists (optional but polite). If the session map
+    // doesn't contain it, we still return any persisted error, else 404.
+    let session_known = ACTIVE_PLAYBACK_SESSIONS.read().await.contains_key(&session_id);
+    let error = ACTIVE_SESSION_ERRORS
+        .read()
+        .await
+        .get(&session_id)
+        .cloned()
+        .map(SessionTranscodeError::from);
+    if !session_known && error.is_none() {
+        return Err(Status::NotFound);
+    }
+    Ok(Json(SessionStatusResponse { error }))
+}
+```
+
+- [ ] **Step 4: Register both routes**
+
+In `crates/server/src/web/routes/mod.rs`, add to `api_routes()` (the `openapi_get_routes!` list), in logical spots:
+
+```rust
+        media::get_server_capabilities,
+        media::discover_transcoding_tools,
+        // ...
+        media::create_session,
+        media::delete_session,
+        media::get_session_status,
+```
+
+- [ ] **Step 5: Build to confirm compilation**
+
+Run: `cargo build -p koko-server 2>&1 | tail -20`
+Expected: PASS. Fix any `AdminGuard`/`current_settings` import errors (the file already imports `crate::auth::AdminGuard`? If not, add `use crate::auth::AdminGuard;` near `use crate::auth::UserGuard;` at `media.rs:51`).
+
+- [ ] **Step 6: Format and commit**
+
+```bash
+cargo +nightly fmt
+git add crates/server/src/web/routes/media.rs crates/server/src/web/routes/mod.rs crates/server/src/ffmpeg_resolve.rs
+git commit -m "feat(server): add transcoding-tools discover + session-status routes"
+```
+
+---
+
+## Task 7: Route integration tests (discover + status)
+
+**Files:**
+- Create: `crates/server/tests/test_web/routes/tools.rs`
+- Modify: `crates/server/tests/test_web/routes/mod.rs`
+
+- [ ] **Step 1: Declare the test module**
+
+In `crates/server/tests/test_web/routes/mod.rs`, add (match existing `pub mod` lines):
+
+```rust
+pub mod tools;
+```
+
+- [ ] **Step 2: Write the integration tests**
+
+Create `crates/server/tests/test_web/routes/tools.rs`. First inspect how `test_auth.rs` performs an admin-authenticated request (token creation) so this matches. Read `crates/server/tests/test_auth.rs` for the `make_request` auth-header pattern, then write:
+
+```rust
+use rocket::http::Status;
+
+use crate::test_utils::{
+    create_test_client,
+    make_request,
+};
+
+#[rocket::async_test]
+async fn test_discover_requires_admin() {
+    let client = create_test_client(Some("tools_discover_requires_admin")).await;
+    // Unauthenticated -> forbidden/unauthorized, never 200.
+    let response = make_request(
+        Some(&client),
+        "post",
+        "/api/v1/system/tools/discover",
+        None,
+        None,
+        None,
+        Some(false),
+    )
+    .await;
+    assert!(
+        response.status == Status::Unauthorized || response.status == Status::Forbidden,
+        "expected auth failure, got {}",
+        response.status
+    );
+}
+
+#[rocket::async_test]
+async fn test_session_status_unknown_session_is_404() {
+    let client = create_test_client(Some("tools_status_unknown")).await;
+    let response = make_request(
+        Some(&client),
+        "get",
+        "/api/v1/sessions/does-not-exist/status",
+        None,
+        None,
+        Some(Status::NotFound),
+        Some(false),
+    )
+    .await;
+    assert_eq!(response.status, Status::NotFound);
+}
+```
+
+- [ ] **Step 3: Run the new tests**
+
+Run: `cargo test -p koko-server --test main test_web::routes::tools 2>&1 | tail -20`
+Expected: PASS. (The discover test asserts auth rejection, which holds regardless of whether ffmpeg is installed — hermetic. The status test asserts 404 for an unknown session.)
+
+- [ ] **Step 4: Format and commit**
+
+```bash
+cargo +nightly fmt
+git add crates/server/tests/test_web/routes/tools.rs crates/server/tests/test_web/routes/mod.rs
+git commit -m "test(server): integration tests for discover + session-status routes"
+```
+
+---
+
+## Task 8: Transcode arg-generation tests (gap F)
+
+**Files:**
+- Modify: `crates/server/src/transcode.rs`
+
+- [ ] **Step 1: Add arg-generation tests to the existing test module**
+
+In `crates/server/src/transcode.rs` test module (created in Task 3), add:
+
+```rust
+    use std::path::PathBuf;
+
+    fn spec_with_source(source: &str) -> TranscodeSpec {
+        TranscodeSpec {
+            source_path: PathBuf::from(source),
+            output_path: PathBuf::from("/tmp/out.mp4"),
+            container: "mp4".into(),
+            video_codec: None,
+            audio_codec: None,
+            max_width: None,
+            max_height: None,
+            max_bitrate_kbps: None,
+            start_time_ms: None,
+            audio_stream_index: None,
+        }
+    }
+
+    #[test]
+    fn source_path_with_spaces_and_brackets_is_one_argv_entry() {
+        let spec = spec_with_source(
+            "/Users/hazer/Downloads/Torrents/[Group] Title With Spaces E10.mkv",
+        );
+        let args = spec.to_ffmpeg_args();
+        // The path must appear verbatim as a single element, right after -i.
+        let i_pos = args.iter().position(|a| a == "-i").expect("-i present");
+        let path_arg = &args[i_pos + 1];
+        assert_eq!(
+            path_arg,
+            "/Users/hazer/Downloads/Torrents/[Group] Title With Spaces E10.mkv"
+        );
+        // And it must be exactly one element (no shell splitting happened).
+        assert_eq!(args.iter().filter(|a| **a == *path_arg).count(), 1);
+    }
+
+    #[test]
+    fn copy_codecs_when_none_specified() {
+        let spec = spec_with_source("/tmp/in.mkv");
+        let args = spec.to_ffmpeg_args();
+        let v_pos = args.iter().position(|a| a == "-c:v").unwrap();
+        assert_eq!(args[v_pos + 1], "copy");
+        let a_pos = args.iter().position(|a| a == "-c:a").unwrap();
+        assert_eq!(args[a_pos + 1], "copy");
+    }
+
+    #[test]
+    fn mp4_container_emits_fragmented_movflags() {
+        let spec = spec_with_source("/tmp/in.mkv");
+        let args = spec.to_ffmpeg_args();
+        let mf_pos = args.iter().position(|a| a == "-movflags").unwrap();
+        assert!(args[mf_pos + 1].contains("frag_keyframe"));
+        assert!(args[mf_pos + 1].contains("empty_moov"));
+    }
+
+    #[test]
+    fn stdout_args_target_pipe1() {
+        let spec = spec_with_source("/tmp/in.mkv");
+        let args = spec.to_ffmpeg_stdout_args();
+        assert_eq!(args.last().unwrap(), "pipe:1");
+    }
+```
+
+- [ ] **Step 2: Run the tests**
+
+Run: `cargo test -p koko-server --lib transcode::tests 2>&1 | tail -20`
+Expected: PASS — all four arg-generation tests pass, confirming the path-quoting-is-fine invariant (spec §1.1).
+
+- [ ] **Step 3: Format and commit**
+
+```bash
+cargo +nightly fmt
+git add crates/server/src/transcode.rs
+git commit -m "test(server): cover transcode arg generation, incl. spaces-in-path invariant"
+```
+
+---
+
+## Task 9: Optional real-ffmpeg smoke test (behind feature flag)
+
+**Files:**
+- Modify: `crates/server/Cargo.toml`
+- Modify: `crates/server/src/ffmpeg_resolve.rs`
+
+- [ ] **Step 1: Add the feature flag**
+
+In `crates/server/Cargo.toml` `[features]` (lines 46–57), add:
+
+```toml
+real-ffmpeg-tests = []
+```
+
+- [ ] **Step 2: Add the gated smoke test**
+
+In `ffmpeg_resolve.rs` test module, add:
+
+```rust
+    #[cfg(feature = "real-ffmpeg-tests")]
+    #[test]
+    fn real_ffmpeg_on_path_is_found() {
+        // Only runs when invoked with --features real-ffmpeg-tests AND ffmpeg
+        // is actually installed on PATH. Skipped in normal CI.
+        let resolved = resolve_binary("ffmpeg", "ffmpeg");
+        match resolved {
+            ResolvedBinary::Found { via, .. } => {
+                // On most dev machines this resolves via PathLookup or WellKnown.
+                println!("resolved ffmpeg via {via:?}");
+            }
+            ResolvedBinary::Missing { checked_paths, .. } => {
+                panic!(
+                    "real-ffmpeg-tests feature is enabled but ffmpeg was not found; checked: {:?}",
+                    checked_paths
+                );
+            }
+        }
+    }
+```
+
+- [ ] **Step 3: Verify default (flag OFF) and opt-in (flag ON) behavior**
+
+Run (default, must not run the gated test): `cargo test -p koko-server --lib ffmpeg_resolve 2>&1 | grep real_ffmpeg`
+Expected: no output (test excluded).
+
+Run (opt-in, requires local ffmpeg): `cargo test -p koko-server --lib ffmpeg_resolve --features real-ffmpeg-tests real_ffmpeg 2>&1 | tail -10`
+Expected: PASS if ffmpeg is installed locally; otherwise a clear panic listing checked paths. (Locally the developer decides.)
+
+- [ ] **Step 4: Format and commit**
+
+```bash
+cargo +nightly fmt
+git add crates/server/Cargo.toml crates/server/src/ffmpeg_resolve.rs
+git commit -m "test(server): add opt-in real-ffmpeg smoke test behind feature flag"
+```
+
+---
+
+## Task 10: Client API types and request functions
+
+**Files:**
+- Modify: `crates/client-web/src/api.ts`
+
+- [ ] **Step 1: Add the types and request functions**
+
+In `crates/client-web/src/api.ts`, near the other response interfaces (after `ServerCapabilities`, ~line 54) and the request functions (near `createPlaybackSession`, ~line 1270), add the types:
+
+```ts
+export interface BinaryProbe {
+  resolved_path?: string;
+  version?: string;
+  error?: string;
+}
+
+export interface ToolCandidate {
+  directory: string;
+  ffmpeg?: BinaryProbe;
+  ffprobe?: BinaryProbe;
+}
+
+export interface ToolDiscoveryResponse {
+  configured_ffmpeg: BinaryProbe;
+  configured_ffprobe: BinaryProbe;
+  candidates: ToolCandidate[];
+}
+
+export interface TranscodeErrorBody {
+  code: string;
+  message: string;
+  action?: string;
+}
+
+export interface SessionStatusResponse {
+  error?: TranscodeErrorBody;
+}
+```
+
+And the request functions (place with the other POST/GET helpers):
+
+```ts
+export function discoverTranscodingTools(): Promise<ToolDiscoveryResponse> {
+  return requestJson<ToolDiscoveryResponse>('POST', '/api/v1/system/tools/discover');
+}
+
+export function getSessionStatus(sessionId: string): Promise<SessionStatusResponse> {
+  return requestJson<SessionStatusResponse>('GET', `/api/v1/sessions/${encodeURIComponent(sessionId)}/status`);
+}
+```
+
+(Confirm `requestJson`'s signature by reading the existing `createPlaybackSession` at `api.ts:1270` — match its pattern exactly, including how auth headers are attached. If `requestJson` requires an admin token for POST, it already handles it; the discover route is admin-gated server-side.)
+
+- [ ] **Step 2: Verify the client type-checks**
+
+Run: `cd crates/client-web && npx tsc --noEmit 2>&1 | tail -20` (then return to repo root).
+Expected: PASS — no type errors. (If `tsc` isn't the project's checker, run whatever `crates/client-web/package.json`'s `build`/`typecheck` script is.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/client-web/src/api.ts
+git commit -m "feat(client): add transcoding discovery + session status API helpers"
+```
+
+---
+
+## Task 11: Client `playbackError` state + dynamic overlay/banner
+
+**Files:**
+- Modify: `crates/client-web/src/app/types.ts`
+- Modify: `crates/client-web/src/app/playbackController.ts`
+
+- [ ] **Step 1: Add `playbackError` to `AppState`**
+
+In `crates/client-web/src/app/types.ts`, add to `AppState` (near `error?: string;` at line 142):
+
+```ts
+  playbackError?: { code: string; message: string; action?: string };
+```
+
+- [ ] **Step 2: Make the in-player overlay copy dynamic**
+
+In `crates/client-web/src/app/playbackController.ts`, the overlay markup at lines 324–327 currently has hardcoded strings:
+
+```ts
+        <div class="player-error-indicator" aria-live="polite">
+          <strong>Playback could not start</strong>
+          <span>Try another audio track or start playback again.</span>
+        </div>
+```
+
+Replace with dynamic copy driven by `state.playbackError`:
+
+```ts
+        <div class="player-error-indicator" aria-live="polite">
+          <strong>${escapeHtml(state.playbackError?.message ? 'Playback failed' : 'Playback could not start')}</strong>
+          <span>${escapeHtml(state.playbackError?.message ?? 'Try another audio track or start playback again.')}</span>
+        </div>
+```
+
+- [ ] **Step 3: Update `setPlayerError` to set `state.playbackError`**
+
+In `playbackController.ts`, the `setPlayerError` closure (~line 1053) currently only toggles classes:
+
+```ts
+  const setPlayerError = (): void => {
+    shell?.classList.remove('is-media-loading');
+    shell?.classList.add('has-media-error');
+  };
+```
+
+Change it to also reset the loading state (the structured detail is set by the caller / status-read):
+
+```ts
+  const setPlayerError = (): void => {
+    shell?.classList.remove('is-media-loading');
+    shell?.classList.add('has-media-error');
+  };
+```
+
+(No change needed to the function body itself; `state.playbackError` is set at the call sites in Tasks 12–13. Keep this step as a confirmation read — if the body differs in the current tree, leave the class toggles intact and ensure it doesn't clear `state.playbackError`.)
+
+- [ ] **Step 4: Type-check**
+
+Run: `cd crates/client-web && npx tsc --noEmit 2>&1 | tail -20`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/client-web/src/app/types.ts crates/client-web/src/app/playbackController.ts
+git commit -m "feat(client): dynamic playback error copy via state.playbackError"
+```
+
+---
+
+## Task 12: Client capabilities preflight in `startPlayback`
+
+**Files:**
+- Modify: `crates/client-web/src/app/playbackController.ts`
+
+- [ ] **Step 1: Add the preflight in `startPlayback`**
+
+`startPlayback` is at `playbackController.ts:610`. It currently sets `state.isPlayerOpen = true` unconditionally. Add a preflight that blocks opening the player when transcode is required but ffmpeg is unavailable. Insert after `state.activePlaybackItem = item;` (line 613) and before `state.isPlayerOpen = true;` (line 615):
+
+```ts
+  // Preflight: if this item needs transcoding but ffmpeg is unavailable on the
+  // server, don't open the player on a doomed stream — surface the error now.
+  const ffmpegAvailable = state.capabilities?.transcoding.ffmpeg.available === true;
+  // We need the decision to know whether transcode is required; create the
+  // session first (cheap) only if we can't tell from existing state. The
+  // session is created below regardless, so just guard the open.
+```
+
+Then, immediately after the session is created (`state.activePlaybackSession = await createPlaybackSession(...)` at line 626, before the final `render()`), insert the check:
+
+```ts
+  const decision = state.activePlaybackSession.decision;
+  const needsTranscode = decision.transcode_required;
+  if (needsTranscode && !ffmpegAvailable) {
+    state.playbackError = {
+      code: 'transcode_executable_missing',
+      message: state.capabilities?.transcoding.ffmpeg.error
+        ?? 'Transcoding is required but FFmpeg is not available on the server.',
+      action: 'open_settings',
+    };
+    state.error = 'Transcoding requires FFmpeg, which the server could not find. Set its path in Settings.';
+    state.isPlayerOpen = true; // open so the overlay/banner are visible
+    render();
+    return;
+  }
+  // Healthy path: clear any prior error and proceed.
+  state.playbackError = undefined;
+```
+
+(Confirm `PlaybackSession.decision.transcode_required` exists on the client type — read `api.ts` `PlaybackSession` interface. It does, per the server `PlaybackDecision`.)
+
+- [ ] **Step 2: Wire the global banner's "Open settings" action**
+
+The global `error-panel` is rendered in `app.ts` / `auth.ts`. Locate where `state.error` is rendered as `.error-panel` (read `crates/client-web/src/app.ts` and `auth.ts:73`). Add a conditional button when `state.playbackError?.action === 'open_settings'`. Since the banner markup is shared, the cleanest minimal change is to render the button inside the same `error-panel` block when the action is present. Read the exact markup first, then add (adapting to the actual surrounding code):
+
+```ts
+${state.playbackError?.action === 'open_settings' ? `<button class="button-link" type="button" data-action="open-settings">Open settings</button>` : ''}
+```
+
+And bind the click handler in `eventBindings.ts` (read it for the existing click-delegation pattern, e.g. how `close-player` is bound) to navigate to the settings view. Match the existing settings-navigation call used elsewhere in that file.
+
+- [ ] **Step 3: Type-check**
+
+Run: `cd crates/client-web && npx tsc --noEmit 2>&1 | tail -20`
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/client-web/src/app/playbackController.ts crates/client-web/src/app/app.ts crates/client-web/src/app/eventBindings.ts
+git commit -m "feat(client): preflight ffmpeg availability before transcode playback"
+```
+
+---
+
+## Task 13: Client status-read recovery in the `<video>` error handler
+
+**Files:**
+- Modify: `crates/client-web/src/app/playbackController.ts`
+
+- [ ] **Step 1: Make the `<video>` error handler fetch session status**
+
+The error handler is at `playbackController.ts:1330`:
+
+```ts
+  player.addEventListener('error', () => {
+    setPlayerError();
+    console.error('Media playback failed', player.error);
+  });
+```
+
+Replace with a version that recovers structured detail from the status endpoint (map lookup, not a spawn):
+
+```ts
+  player.addEventListener('error', () => {
+    setPlayerError();
+    console.error('Media playback failed', player.error);
+    const sessionId = state.activePlaybackSession?.session_id;
+    if (!sessionId) {
+      return;
+    }
+    // Best-effort: recover a structured error from the per-session store. This
+    // is a cheap map lookup on the server, not a transcode spawn. It only helps
+    // when the browser actually fires `error` (HTTP failures are unreliable).
+    void getSessionStatus(sessionId)
+      .then((status) => {
+        if (status.error) {
+          state.playbackError = status.error;
+          render();
+        }
+      })
+      .catch((error) => {
+        console.warn('Failed to fetch session status after playback error', error);
+      });
+  });
+```
+
+Add `getSessionStatus` to the imports at the top of `playbackController.ts` (it's already imported alongside `createPlaybackSession` etc.; if not, add it to the `from '../api'` import block).
+
+- [ ] **Step 2: Type-check**
+
+Run: `cd crates/client-web && npx tsc --noEmit 2>&1 | tail -20`
+Expected: PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/client-web/src/app/playbackController.ts
+git commit -m "feat(client): recover structured transcode error via session status read"
+```
+
+---
+
+## Task 14: Settings UI — "Detect ffmpeg" + directory radios
+
+**Files:**
+- Modify: `crates/client-web/src/app/settingsView.ts`
+
+- [ ] **Step 1: Read the existing ffmpeg inputs and form-save flow**
+
+Read `crates/client-web/src/app/settingsView.ts` lines 545–560 (the ffmpeg/ffprobe inputs) and 770–790 (the form `submit`/save handler that reads `formData`). The new UI must (a) add a detect button + radio container after the inputs, (b) call `discoverTranscodingTools()` on click, (c) render radios grouped by directory, (d) selecting a directory radio writes both paths into the form fields.
+
+- [ ] **Step 2: Add the detect button + results container markup**
+
+After the existing ffprobe input (`settingsView.ts:555`), add:
+
+```ts
+            <div class="ffmpeg-discover">
+              <button id="detect-ffmpeg" class="secondary-button" type="button">Detect ffmpeg</button>
+              <div id="ffmpeg-discover-results" class="ffmpeg-discover-results" hidden></div>
+            </div>
+```
+
+- [ ] **Step 3: Add the click binding and rendering**
+
+In the event-binding section of `settingsView.ts` (where other settings buttons are wired), add:
+
+```ts
+const detectButton = root.querySelector<HTMLButtonElement>('#detect-ffmpeg');
+const resultsContainer = root.querySelector<HTMLElement>('#ffmpeg-discover-results');
+const ffmpegInput = root.querySelector<HTMLInputElement>('input[name="ffmpeg_path"]');
+const ffprobeInput = root.querySelector<HTMLInputElement>('input[name="ffprobe_path"]');
+
+detectButton?.addEventListener('click', async () => {
+  if (!resultsContainer || !ffmpegInput || !ffprobeInput) {
+    return;
+  }
+  detectButton.disabled = true;
+  detectButton.textContent = 'Detecting…';
+  try {
+    const discovery = await discoverTranscodingTools();
+    renderDiscoverResults(resultsContainer, ffmpegInput, ffprobeInput, discovery);
+  } catch (error) {
+    resultsContainer.hidden = false;
+    resultsContainer.innerHTML = `<p class="muted">Detection failed: ${escapeHtml(error instanceof Error ? error.message : 'unknown error')}</p>`;
+  } finally {
+    detectButton.disabled = false;
+    detectButton.textContent = 'Detect ffmpeg';
+  }
+});
+```
+
+Add the `renderDiscoverResults` helper (in the same file):
+
+```ts
+function renderDiscoverResults(
+  container: HTMLElement,
+  ffmpegInput: HTMLInputElement,
+  ffprobeInput: HTMLInputElement,
+  discovery: ToolDiscoveryResponse,
+): void {
+  const parts: string[] = [];
+
+  // Configured-path option (paired validation).
+  const configuredOk = discovery.configured_ffmpeg.resolved_path && discovery.configured_ffprobe.resolved_path;
+  const configuredLabel = configuredOk
+    ? `Current (${discovery.configured_ffmpeg.version ?? 'ffmpeg'} · ${discovery.configured_ffprobe.version ?? 'ffprobe'})`
+    : `Current — ${discovery.configured_ffmpeg.error ?? discovery.configured_ffprobe.error ?? 'not found'}`;
+  parts.push(`
+    <label class="ffmpeg-discover-option">
+      <input type="radio" name="ffmpeg-discover-choice" value="current" ${configuredOk ? 'checked' : ''} />
+      <span>${escapeHtml(configuredLabel)}</span>
+    </label>
+  `);
+
+  // Candidate directories, paired.
+  for (const candidate of discovery.candidates) {
+    const both = candidate.ffmpeg && candidate.ffprobe;
+    const label = `${candidate.directory} — ${candidate.ffmpeg?.version ?? 'ffmpeg missing'} · ${candidate.ffprobe?.version ?? 'ffprobe missing'}`;
+    parts.push(`
+      <label class="ffmpeg-discover-option${both ? '' : ' is-disabled'}">
+        <input type="radio" name="ffmpeg-discover-choice" value="${escapeHtml(candidate.directory)}" ${both ? '' : 'disabled'} />
+        <span>${escapeHtml(label)}</span>
+      </label>
+    `);
+  }
+
+  // Manual option (keep the text inputs authoritative).
+  parts.push(`
+    <label class="ffmpeg-discover-option">
+      <input type="radio" name="ffmpeg-discover-choice" value="manual" />
+      <span>Use the manual paths above</span>
+    </label>
+  `);
+
+  container.innerHTML = parts.join('');
+  container.hidden = false;
+
+  container.querySelectorAll<HTMLInputElement>('input[name="ffmpeg-discover-choice"]').forEach((radio) => {
+    radio.addEventListener('change', () => {
+      if (radio.value === 'manual') {
+        return; // leave the text inputs as-is
+      }
+      if (radio.value === 'current') {
+        return; // leave as-is; configured path already in the inputs
+      }
+      // A directory: set both inputs to <dir>/ffmpeg and <dir>/ffprobe.
+      const dir = radio.value;
+      ffmpegInput.value = `${dir}/ffmpeg`;
+      ffprobeInput.value = `${dir}/ffprobe`;
+    });
+  });
+}
+```
+
+Ensure imports at the top of `settingsView.ts` include `discoverTranscodingTools`, `ToolDiscoveryResponse` (from `../api`) and `escapeHtml` (from `./format`).
+
+- [ ] **Step 4: Add minimal CSS for the new controls**
+
+In `crates/client-web/src/style.css`, near the settings styles, add:
+
+```css
+.ffmpeg-discover {
+  margin-top: 0.5rem;
+}
+.ffmpeg-discover-results {
+  margin-top: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+.ffmpeg-discover-option {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+.ffmpeg-discover-option.is-disabled {
+  opacity: 0.5;
+}
+```
+
+- [ ] **Step 5: Type-check and commit**
+
+Run: `cd crates/client-web && npx tsc --noEmit 2>&1 | tail -20`
+Expected: PASS.
+
+```bash
+cargo +nightly fmt
+git add crates/client-web/src/app/settingsView.ts crates/client-web/src/style.css
+git commit -m "feat(client): Detect ffmpeg button with directory-paired radio picker"
+```
+
+---
+
+## Task 15: Full build + test sweep + final verification
+
+- [ ] **Step 1: Full server test suite**
+
+Run: `cargo test -p koko-server 2>&1 | tail -30`
+Expected: PASS — all existing tests plus the new `ffmpeg_resolve`, `transcode::tests`, and `tools` integration tests. (Existing tests must not regress; the `detect_binary` signature change is the main risk — verify all call sites were updated in Task 2 Step 5.)
+
+- [ ] **Step 2: Full client type-check/build**
+
+Run: `cd crates/client-web && npm run build 2>&1 | tail -20` (or `npm run typecheck` if present; then return to repo root).
+Expected: PASS.
+
+- [ ] **Step 3: Clippy (if the project uses it)**
+
+Run: `cargo clippy -p koko-server --all-targets 2>&1 | tail -30`
+Expected: no new warnings from the added code. Fix any the plan's code introduced (common: unused imports, needless `clone`).
+
+- [ ] **Step 4: Format the whole tree**
+
+Run: `cargo +nightly fmt`
+
+- [ ] **Step 5: Manual smoke check (document the steps, don't automate)**
+
+Since the frontend has no test harness, verify by hand:
+1. Start the server, open the web client, go to Settings.
+2. Click "Detect ffmpeg" — confirm the configured path + candidate directories appear as radios with versions.
+3. Pick a directory radio — confirm both ffmpeg/ffprobe inputs update; save.
+4. Play an HEVC item — confirm it transcodes (issue 1 fixed).
+5. Break ffmpeg_path in settings (set to `ffmpeg-does-not-exist`), save, play an HEVC item — confirm the in-player overlay AND the global banner with "Open settings" appear (issue 2 fixed), instead of a black screen.
+
+- [ ] **Step 6: Final commit (if any formatting/test fixes)**
+
+```bash
+git add -A
+git commit -m "chore: final formatting and verification pass" || echo "nothing to commit"
+```
+
+---
+
+## Spec coverage self-review
+
+| Spec item | Task(s) |
+|-----------|---------|
+| §4.1 ffmpeg resolver (allow-list, well-known dirs, package managers) | Task 1 (+ "Security decision" + "Resolver path lists" preambles) |
+| §4.1 `detect_binary` delegates to resolver | Task 2 |
+| §4.1 logging resolved path / checked paths | Task 2 (info/warn logs) |
+| §4.2 discover endpoint (AdminGuard, validates configured path) | Task 6 |
+| §4.2 settings UI (detect button, directory radios) | Task 14 |
+| §4.3 `SpawnTranscodeError` + `TranscodeErrorBody` + `map_transcode_error` (seam #2) | Task 3 |
+| §4.3 resolved-path spawn (THE issue-1 fix) | Task 4 |
+| §4.3 per-session error store + `record_session_error` (seam #1, inert) | Task 5 |
+| §4.3 structured stream-error in route handler | Task 5 |
+| §4.3 `get_session_status` route (live reader) | Task 6 |
+| §4.4 `playbackError` state + dynamic overlay/banner | Task 11 |
+| §4.4 capabilities preflight in `startPlayback` | Task 12 |
+| §4.4 status-read recovery in `<video>` error handler | Task 13 |
+| §5 testing: resolver inline tests (shim-based) | Task 1 |
+| §5 testing: transcode arg-generation tests (gap F) | Task 8 |
+| §5 testing: real-ffmpeg smoke behind feature flag | Task 9 |
+| §5 testing: route integration tests (tools.rs) | Task 7 |
+| §5 testing: frontend test-light (manual) | Task 15 Step 5 (documented) |
+
+**Gaps:** none. Every spec section §4.1–§4.4 and every testing bullet in §5 maps to at least one task. Deferred items (§3, Appendix B) are intentionally not covered — they belong to the lifecycle phase docs.
+
+**Type consistency check:** `TranscodeErrorBody` (Task 3) is referenced by `SessionTranscodeError::from` (Task 5), `map_transcode_error` (Task 3, used Task 5), and the client `TranscodeErrorBody` (Task 10) — shapes align (`code`/`message`/`action`). `resolve_binary`/`resolve_ffmpeg`/`resolve_ffprobe` (Task 1) used by `detect_binary` (Task 2), spawn (Task 4), and `probe_configured`/`probe_in_dir` (Task 6). `discoverTranscodingTools`/`getSessionStatus` (Task 10) consumed by Tasks 12–14. Names match across tasks.

From 964e549b0166bb7647093f28d52e452cfdf7bb97 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Thu, 18 Jun 2026 23:51:32 -0300
Subject: [PATCH 04/27] Apply approved spec edits from review

---
 ...fmpeg-resolution-and-player-errors-design.md | 17 ++++++++++++++++-
 .../2026-06-18-transcode-lifecycle-discovery.md |  1 +
 .../2026-06-18-transcode-lifecycle-plan.md      |  3 ++-
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md b/docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md
index 3e34469d..5d720a2e 100644
--- a/docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md
+++ b/docs/superpowers/specs/2026-06-18-transcode-ffmpeg-resolution-and-player-errors-design.md
@@ -13,7 +13,7 @@ Two failures were reported when playing an HEVC (transcode-required) item:
 
 ### 1.1 Root cause of issue 1 (the "spaces in path" framing is a red herring)
 
-FFmpeg arguments are built into a `Vec<String>` and passed via `tokio::process::Command::args(&args)` (`crates/server/src/transcode.rs:227-229`). This bypasses the shell entirely — each vector element is handed directly to the OS `exec` as a discrete argv entry. A source path containing spaces or brackets (e.g. `/Users/.../Witch Hat Atelier ....mkv`) is passed to ffmpeg verbatim. The unquoted appearance in the server log is purely cosmetic: it comes from `args.join(" ")` at `transcode.rs:222-225`, not from what is executed.
+FFmpeg arguments are built into a `Vec<String>` and passed via `tokio::process::Command::args(&args)` (`crates/server/src/transcode.rs:227-229`). This bypasses the shell entirely — each vector element is handed directly to the OS `exec` as a discrete argv entry. A source path containing spaces or brackets (e.g. `/Users/.../Witch Hat Atelier ....mkv`) is passed to ffmpeg verbatim. The unquoted appearance in the server log is purely cosmetic: it comes from `args.join(" ")` at `transcode.rs:222-225`, not from what is executed. We could fix that, but that's not the real issue.
 
 `No such file or directory (os error 2)` returned by **`spawn()` itself** (not by ffmpeg later) is, on Unix, `ENOENT` from the exec layer. When spawning the *command* fails with `ENOENT`, it means **the executable was not found** — i.e. `ffmpeg` is not resolvable from the server process's environment.
 
@@ -93,6 +93,12 @@ pub fn resolve_ffprobe(configured: &str) -> ResolvedBinary { resolve_binary(conf
 
 **Logging:** at startup and on each resolve, `INFO`/`WARN` naming the resolved path and source, or all `checked_paths` when missing.
 
+**Notes:**
+1. The user inquired if there's difference in figuring out if the `configured` is a bare name, or not, and the impact of having different treatment for a path or a filename, he is not sure the distinction is meaninful, but also unsure it isn't. Consider it and state your recommendations.
+2. Homebrew may have different paths for arm and x86, so we need to consider that. Also, other popular package managers that we should have the well-known paths listed with lower priority (just further down the list, no need to create a priority property), both macOS/Linux?
+3. Any popular package managers for Windows that may have a different path of installation than `Program Files\ffmpeg` and `%USERPROFILE%\bin` that we may want to include?
+4. Should we enforce a hardcoded binary names allow-list that `resolve_binary` consumes to avoid potential attacks leveraging some vulnerability in the future? The user is concerned some mistake could expose use to a bunch of problems from path lookups via this method.
+
 ### 4.2 Discovery endpoint + settings UI (the "easy setup")
 
 **Server — new route in `crates/server/src/web/routes/media.rs` next to `get_server_capabilities` (`media.rs:3026`), registered in `crates/server/src/web/routes/mod.rs`.** Tag is `Media` (there is no `system` tag in the project); guard is `AdminGuard` (the project's admin request guard, as in `user.rs:144/169`), since the response reveals on-disk paths and binary versions — the same sensitivity class as settings.
@@ -229,6 +235,15 @@ The project splits tests by kind: pure logic lives in **inline `#[cfg(test)] mod
 
 SSE would mean a new transport, a server endpoint, reconnection logic, and a client subscription model — all for a path that is fundamentally *request → response* (one error per stream attempt). The structured JSON error body (§4.3) plus the deterministic capabilities preflight (§4.4) covers the same need using patterns the codebase already has. SSE earns its place only if realtime playback health (quality metrics, adaptive bitrate) becomes a goal — separate spec.
 
+### 6.3 ffmpeg checks
+
+- We haven't talked about transcoding codecs, but if the list of available ffmpeg binaries could also show, via some additional info dialog, or "show more" kinda behavior, the list of "available" codecs in each binary, that would be great, but we can consider a future improvement. But how hard would be to also include this info?
+- Is there any risk that the current ffmpeg args, may not work with different ffmpeg versions? Should we have a compatibility check too in the future? While making the default template somehow customizable for admins, I kinda want to postpone this as much as possible, and if we really need we could have some compatibility check for that as well.
+
+### 6.4 Setup wizard
+
+Should we include in the current first start setup, an optional, collapsed, similar component to find, or manually provide, the ffmpeg binaries, but totally skippable? So eager admins do configure it in that screen, and other admins just set their user details and move on? I believe that screen may be reused for creating regular users too, so I'd be cautious about doing it there, but maybe it is a good idea, or in a follow up screen with a "Skip, I'll do it later" button? Let's get everything working first, but I think this is a good improvement for later.
+
 ## Appendix A — Files touched (planning reference)
 
 Server:
diff --git a/docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md
index 77d6c1d3..ac421799 100644
--- a/docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md
+++ b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-discovery.md
@@ -65,6 +65,7 @@ These are recorded so they are not lost; they need investigation/decisions in th
 5. **Status endpoint vs 500-on-reconnect.** Is the `GET /sessions/<id>/status` read sufficient for the watchdog, or does the stream endpoint itself need to return the structured error on a *reconnect* attempt (e.g. after the player retries the src)?
 6. **(E) scope.** Should source-existence be only a per-play 404, or also drive a server-side "missing since scan" background job (mark `missing_since`, surface in the UI)? The shipped code already has a `missing_since` column on backing files (`media.rs:3145`) — the lifecycle phase should reconcile per-play checks with that existing mechanism rather than duplicate it.
 7. **Persistent vs per-request transcode.** Should a stream request attach to a long-lived transcode keyed by `(session_id, start_ms, audio_index)` instead of spawning fresh each time? This would eliminate the double-spawn concern entirely and is the natural home for a watcher — but it is a larger change. Decide whether the lifecycle phase takes it on or stays per-request.
+8. **Tooling.** Would Rayon and/or https://github.com/tqwewe/kameo improve our handling of lifecycle, in or out, of transcoding? Where? How? Should we take it as something to plan now, or later? Do the project currently has parallel libs or actor libs besides what tokio and axum does?
 
 ## 6. What is already built for this phase (no rework needed)
 
diff --git a/docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md
index 97db6130..6b553d83 100644
--- a/docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md
+++ b/docs/superpowers/specs/2026-06-18-transcode-lifecycle-plan.md
@@ -20,7 +20,7 @@ This is discovery open-question 7 and it shapes everything below.
 
 **Option B — Persistent transcode keyed by `(session_id, start_ms, audio_index)` (larger change).** A long-lived ffmpeg process that stream requests attach to, eliminating the per-request re-spawn (and the double-spawn concern that killed the probe). Natural home for a single watcher. Higher risk; touches session lifecycle, replacement semantics, and concurrency (multiple readers of one stdout).
 
-**Recommendation (tentative, to confirm in planning):** Start with **Option A**. It delivers the three scope items with the least surface area, reuses the shipped seams directly, and leaves Option B as a follow-on if re-spawn cost or reader-fan-out ever becomes a problem. The rest of this draft assumes Option A.
+**Recommendation (tentative, to confirm in planning):** Start with **Option A**. It delivers the three scope items with the least surface area, reuses the shipped seams directly, and leaves Option B as a follow-on if re-spawn cost or reader-fan-out ever becomes a problem. The rest of this draft assumes Option A. The user affirmed there may be many users using the client in parallel, so per-request has it's benefits, but persistent keyed also allows the admin to kill some stalle transcoding spawn that for some reason is still running. Investigate further impacts unrelated to the stream-experience as another task too. And the user thinks "how do we handle transcoding caching?" has to be answered before deciding on anything other than option A.
 
 ## 2. (C-early) Pre-commit stream validation — event-driven, not a fixed timer
 
@@ -83,6 +83,7 @@ The shipped best-effort recovery (fetch status on `<video>` `error`) stays. The
 - Before spawning, validate the resolved source path is readable. On failure return **404** (not a confusing ffmpeg stderr path).
 - **Reconcile with `missing_since`** (discovery open question 6): the backing-file row already has `missing_since` (`media.rs:3145`). Decide whether a per-play check also *sets* `missing_since` (so the UI/library can reflect it) or only returns 404. Prefer marking `missing_since` to avoid a parallel notion of "missing".
 - Network/removable paths are the primary motivation; for local indexed files this is cheap insurance.
+- Check the need to have an "hydration" method for network attached paths. And/or some addtional setting/checkbox in the library config of said path to allow features and improvements only for network paths.
 
 ## 5. Implementation phases (suggested sequencing)
 

From 4444d0b8284a2e9919727482348e190531acd604 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 01:51:50 -0300
Subject: [PATCH 05/27] fix(plan): correct server crate name (koko, not
 koko-server)

---
 ...ode-ffmpeg-resolution-and-player-errors.md | 33 ++++++++++---------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md b/docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md
index 2ac1cae4..188241c2 100644
--- a/docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md
+++ b/docs/superpowers/plans/2026-06-18-transcode-ffmpeg-resolution-and-player-errors.md
@@ -16,6 +16,7 @@
 
 - **Formatting:** always `cargo +nightly fmt` (per `AGENTS.md`). Run after every code change.
 - **Testing:** pure logic → inline `#[cfg(test)] mod tests` (pattern: `crates/server/src/media.rs`); HTTP routes → integration tests in `crates/server/tests/test_web/routes/` using `create_test_client` + `make_request` (pattern: `tests/test_web/routes/settings.rs`). The project uses `#[rocket::async_test]` for async integration tests and `#[test]` for inline.
+- **Package name:** the server crate is `koko` (not `koko-server`). Use `cargo test -p koko ...` and `cargo build -p koko`. The test binary is `main` (`cargo test -p koko --test main ...`).
 - **Route style:** `#[openapi(tag = "Media")]` + snake_case fn, registered in `crates/server/src/web/routes/mod.rs` `api_routes()` via `openapi_get_routes!`. Admin routes take `_admin_guard: AdminGuard` (`crates/server/src/auth.rs:90`).
 - **Type style:** response types derive `(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)` with a doc comment per field (pattern: `BinaryCapability` at `media.rs:115`).
 - **Commits:** one logical change per commit, frequent. This plan uses `feat:`/`test:`/`refactor:` prefixes.
@@ -256,7 +257,7 @@ mod tests {
 
 - [ ] **Step 4: Run the tests to verify they fail (compile error)**
 
-Run: `cargo test -p koko-server --lib ffmpeg_resolve 2>&1 | head -30`
+Run: `cargo test -p koko --lib ffmpeg_resolve 2>&1 | head -30`
 Expected: FAIL — the tests reference `resolve_binary`, which is not yet defined. (The `#[cfg(unix)]` shims also need `tempfile`, added in Step 1.)
 
 - [ ] **Step 5: Write the minimal implementation**
@@ -404,7 +405,7 @@ mod tests {
 
 - [ ] **Step 6: Run the tests to verify they pass**
 
-Run: `cargo test -p koko-server --lib ffmpeg_resolve 2>&1 | tail -20`
+Run: `cargo test -p koko --lib ffmpeg_resolve 2>&1 | tail -20`
 Expected: PASS — all `ffmpeg_resolve::tests::*` pass. On Windows the two `#[cfg(unix)]` tests are skipped.
 
 - [ ] **Step 7: Format and commit**
@@ -451,7 +452,7 @@ In `ffmpeg_resolve.rs` test module, add (Unix-only, uses a shim that prints a ve
 
 - [ ] **Step 2: Run test to verify it fails**
 
-Run: `cargo test -p koko-server --lib ffmpeg_resolve::tests::probe_version 2>&1 | tail -10`
+Run: `cargo test -p koko --lib ffmpeg_resolve::tests::probe_version 2>&1 | tail -10`
 Expected: FAIL — `probe_version` undefined.
 
 - [ ] **Step 3: Implement `probe_version`**
@@ -477,7 +478,7 @@ pub fn probe_version(path: &std::path::Path) -> Option<String> {
 
 - [ ] **Step 4: Run test to verify it passes**
 
-Run: `cargo test -p koko-server --lib ffmpeg_resolve::tests::probe_version 2>&1 | tail -10`
+Run: `cargo test -p koko --lib ffmpeg_resolve::tests::probe_version 2>&1 | tail -10`
 Expected: PASS.
 
 - [ ] **Step 5: Refactor `detect_binary` to delegate to the resolver**
@@ -549,7 +550,7 @@ Search for other `detect_binary(` call sites and fix them similarly: `grep -n "d
 
 - [ ] **Step 6: Build and run the existing media tests**
 
-Run: `cargo test -p koko-server --lib 2>&1 | tail -20`
+Run: `cargo test -p koko --lib 2>&1 | tail -20`
 Expected: PASS — existing `media::tests` still pass (they don't touch `detect_binary`, but the build must succeed).
 
 - [ ] **Step 7: Format and commit**
@@ -613,7 +614,7 @@ mod tests {
 
 - [ ] **Step 2: Run tests to verify they fail**
 
-Run: `cargo test -p koko-server --lib transcode::tests 2>&1 | tail -15`
+Run: `cargo test -p koko --lib transcode::tests 2>&1 | tail -15`
 Expected: FAIL — `SpawnTranscodeError`, `TranscodeErrorBody`, `map_transcode_error` undefined.
 
 - [ ] **Step 3: Add the types and mapper**
@@ -702,7 +703,7 @@ pub fn map_transcode_error(error: SpawnTranscodeError) -> (Status, TranscodeErro
 
 - [ ] **Step 4: Run tests to verify they pass**
 
-Run: `cargo test -p koko-server --lib transcode::tests 2>&1 | tail -15`
+Run: `cargo test -p koko --lib transcode::tests 2>&1 | tail -15`
 Expected: PASS — all three mapper tests pass.
 
 - [ ] **Step 5: Format and commit**
@@ -767,7 +768,7 @@ Apply the equivalent change to `spawn_transcode` (`:184`) — same resolver bloc
 
 - [ ] **Step 2: Build to verify the signatures compile**
 
-Run: `cargo build -p koko-server 2>&1 | tail -20`
+Run: `cargo build -p koko 2>&1 | tail -20`
 Expected: the build fails at the call site in `media.rs` (`get_session_stream` still expects `std::io::Error`). That's the next task. Note: this task intentionally leaves the build red at the route; Task 5 fixes it. Do NOT commit yet.
 
 ---
@@ -866,7 +867,7 @@ If `body.clone()` complains (TranscodeErrorBody must be `Clone`): ensure `#[deri
 
 - [ ] **Step 3: Build to confirm the whole server compiles**
 
-Run: `cargo build -p koko-server 2>&1 | tail -20`
+Run: `cargo build -p koko 2>&1 | tail -20`
 Expected: PASS (green again after Task 4's intentional red).
 
 - [ ] **Step 4: Format and commit (Tasks 4 + 5 together)**
@@ -1089,7 +1090,7 @@ In `crates/server/src/web/routes/mod.rs`, add to `api_routes()` (the `openapi_ge
 
 - [ ] **Step 5: Build to confirm compilation**
 
-Run: `cargo build -p koko-server 2>&1 | tail -20`
+Run: `cargo build -p koko 2>&1 | tail -20`
 Expected: PASS. Fix any `AdminGuard`/`current_settings` import errors (the file already imports `crate::auth::AdminGuard`? If not, add `use crate::auth::AdminGuard;` near `use crate::auth::UserGuard;` at `media.rs:51`).
 
 - [ ] **Step 6: Format and commit**
@@ -1168,7 +1169,7 @@ async fn test_session_status_unknown_session_is_404() {
 
 - [ ] **Step 3: Run the new tests**
 
-Run: `cargo test -p koko-server --test main test_web::routes::tools 2>&1 | tail -20`
+Run: `cargo test -p koko --test main test_web::routes::tools 2>&1 | tail -20`
 Expected: PASS. (The discover test asserts auth rejection, which holds regardless of whether ffmpeg is installed — hermetic. The status test asserts 404 for an unknown session.)
 
 - [ ] **Step 4: Format and commit**
@@ -1254,7 +1255,7 @@ In `crates/server/src/transcode.rs` test module (created in Task 3), add:
 
 - [ ] **Step 2: Run the tests**
 
-Run: `cargo test -p koko-server --lib transcode::tests 2>&1 | tail -20`
+Run: `cargo test -p koko --lib transcode::tests 2>&1 | tail -20`
 Expected: PASS — all four arg-generation tests pass, confirming the path-quoting-is-fine invariant (spec §1.1).
 
 - [ ] **Step 3: Format and commit**
@@ -1309,10 +1310,10 @@ In `ffmpeg_resolve.rs` test module, add:
 
 - [ ] **Step 3: Verify default (flag OFF) and opt-in (flag ON) behavior**
 
-Run (default, must not run the gated test): `cargo test -p koko-server --lib ffmpeg_resolve 2>&1 | grep real_ffmpeg`
+Run (default, must not run the gated test): `cargo test -p koko --lib ffmpeg_resolve 2>&1 | grep real_ffmpeg`
 Expected: no output (test excluded).
 
-Run (opt-in, requires local ffmpeg): `cargo test -p koko-server --lib ffmpeg_resolve --features real-ffmpeg-tests real_ffmpeg 2>&1 | tail -10`
+Run (opt-in, requires local ffmpeg): `cargo test -p koko --lib ffmpeg_resolve --features real-ffmpeg-tests real_ffmpeg 2>&1 | tail -10`
 Expected: PASS if ffmpeg is installed locally; otherwise a clear panic listing checked paths. (Locally the developer decides.)
 
 - [ ] **Step 4: Format and commit**
@@ -1740,7 +1741,7 @@ git commit -m "feat(client): Detect ffmpeg button with directory-paired radio pi
 
 - [ ] **Step 1: Full server test suite**
 
-Run: `cargo test -p koko-server 2>&1 | tail -30`
+Run: `cargo test -p koko 2>&1 | tail -30`
 Expected: PASS — all existing tests plus the new `ffmpeg_resolve`, `transcode::tests`, and `tools` integration tests. (Existing tests must not regress; the `detect_binary` signature change is the main risk — verify all call sites were updated in Task 2 Step 5.)
 
 - [ ] **Step 2: Full client type-check/build**
@@ -1750,7 +1751,7 @@ Expected: PASS.
 
 - [ ] **Step 3: Clippy (if the project uses it)**
 
-Run: `cargo clippy -p koko-server --all-targets 2>&1 | tail -30`
+Run: `cargo clippy -p koko --all-targets 2>&1 | tail -30`
 Expected: no new warnings from the added code. Fix any the plan's code introduced (common: unused imports, needless `clone`).
 
 - [ ] **Step 4: Format the whole tree**

From 9a41e4b367a4e37ced2f4c397fa48ad94da7a4f2 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 01:59:16 -0300
Subject: [PATCH 06/27] feat(server): add ffmpeg_resolve module with
 allow-listed binary resolution

---
 crates/server/Cargo.toml            |   1 +
 crates/server/src/ffmpeg_resolve.rs | 381 ++++++++++++++++++++++++++++
 crates/server/src/lib.rs            |   1 +
 3 files changed, 383 insertions(+)
 create mode 100644 crates/server/src/ffmpeg_resolve.rs

diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml
index 07c0b8a7..5ac9b7f6 100644
--- a/crates/server/Cargo.toml
+++ b/crates/server/Cargo.toml
@@ -102,3 +102,4 @@ objc2-core-foundation = { version = "0.3.0", optional = true }
 [dev-dependencies]
 async-std.workspace = true
 rstest.workspace = true
+tempfile = "3.13"
diff --git a/crates/server/src/ffmpeg_resolve.rs b/crates/server/src/ffmpeg_resolve.rs
new file mode 100644
index 00000000..007829ea
--- /dev/null
+++ b/crates/server/src/ffmpeg_resolve.rs
@@ -0,0 +1,381 @@
+//! Locating the ffmpeg/ffprobe executables used for media processing.
+//!
+//! GUI-launched processes (macOS `.app` bundles, some Linux desktop launchers)
+//! do not inherit the user's shell PATH, so a bare `ffmpeg` lookup can fail
+//! even when the binary is installed under e.g. `/opt/homebrew/bin`. This
+//! module is the single source of truth for resolution and is used by BOTH
+//! capability display and the actual transcode spawn, so "available in UI"
+//! is equivalent to "actually launches".
+
+use std::path::PathBuf;
+
+use once_cell::sync::Lazy;
+
+/// Binary base-names the resolver is allowed to resolve. Anything else is
+/// rejected as [`ResolvedBinary::Missing`]. This is a security boundary: it
+/// prevents a future bug or compromised setting from causing an arbitrary
+/// `exec`.
+pub const ALLOWED_BINARIES: &[&str] = &["ffmpeg", "ffprobe"];
+
+/// How a binary was located.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResolveSource {
+    /// The configured value was an absolute path that exists and is executable.
+    ConfiguredAbsolute,
+    /// The configured bare name resolved on PATH.
+    PathLookup,
+    /// Found in a well-known install directory (not the configured path).
+    WellKnown,
+}
+
+/// Result of resolving a single binary.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResolvedBinary {
+    /// The binary was found.
+    Found {
+        /// The absolute path to use when spawning the binary.
+        resolved_path: PathBuf,
+        /// How the binary was located.
+        via: ResolveSource,
+    },
+    /// The binary could not be found. `checked_paths` lists every location
+    /// inspected, for UI display.
+    Missing {
+        /// The configured value that failed to resolve.
+        configured: String,
+        /// Every location the resolver inspected, in order.
+        checked_paths: Vec<PathBuf>,
+    },
+}
+
+/// Platform-specific well-known directories, highest priority first.
+static WELL_KNOWN_DIRS: Lazy<Vec<PathBuf>> = Lazy::new(well_known_dirs);
+
+#[cfg(target_os = "macos")]
+fn well_known_dirs() -> Vec<PathBuf> {
+    vec![
+        PathBuf::from("/opt/homebrew/bin"),
+        PathBuf::from("/usr/local/bin"),
+        PathBuf::from("/opt/homebrew/sbin"),
+        PathBuf::from("/usr/local/sbin"),
+        PathBuf::from("/usr/bin"),
+        PathBuf::from("/bin"),
+    ]
+}
+
+#[cfg(all(unix, not(target_os = "macos")))]
+fn well_known_dirs() -> Vec<PathBuf> {
+    vec![
+        PathBuf::from("/usr/local/bin"),
+        PathBuf::from("/usr/bin"),
+        PathBuf::from("/bin"),
+        PathBuf::from("/usr/sbin"),
+        PathBuf::from("/opt/ffmpeg/bin"),
+        PathBuf::from("/snap/bin"),
+    ]
+}
+
+#[cfg(target_os = "windows")]
+fn well_known_dirs() -> Vec<PathBuf> {
+    let mut dirs = vec![
+        PathBuf::from(r"C:\Program Files\ffmpeg\bin"),
+        PathBuf::from(r"C:\Program Files (x86)\ffmpeg\bin"),
+        PathBuf::from(r"C:\ffmpeg\bin"),
+    ];
+    if let Ok(home) = std::env::var("USERPROFILE") {
+        dirs.push(PathBuf::from(home).join("bin"));
+    }
+    dirs
+}
+
+/// Resolve a single binary.
+///
+/// `configured` is what the admin set (a bare name like `ffmpeg`, or an
+/// absolute/relative path). `binary_name` is the canonical name being looked
+/// up and MUST be in [`ALLOWED_BINARIES`].
+///
+/// Resolution order:
+/// 1. If `configured` looks like a path (contains a separator) or is absolute,
+///    validate its base name is allowed and it exists + is executable.
+/// 2. Else treat `configured` as a bare name: require it to be allowed, then
+///    look it up on PATH.
+/// 3. Else fall back to the well-known directory list for `binary_name`.
+/// 4. Else [`ResolvedBinary::Missing`] with every checked location.
+pub fn resolve_binary(
+    configured: &str,
+    binary_name: &str,
+) -> ResolvedBinary {
+    resolve_binary_with(configured, binary_name, &WELL_KNOWN_DIRS, lookup_on_path)
+}
+
+/// Internal resolver that accepts an explicit well-known directory list and a
+/// PATH-lookup function so tests can run hermetically (the static
+/// [`WELL_KNOWN_DIRS`] and the real `PATH` reflect the actual machine, where
+/// ffmpeg may be installed).
+fn resolve_binary_with(
+    configured: &str,
+    binary_name: &str,
+    well_known_dirs: &[PathBuf],
+    path_lookup: impl Fn(&str) -> Option<PathBuf>,
+) -> ResolvedBinary {
+    if !ALLOWED_BINARIES.contains(&binary_name) {
+        return ResolvedBinary::Missing {
+            configured: configured.to_string(),
+            checked_paths: Vec::new(),
+        };
+    }
+
+    let mut checked: Vec<PathBuf> = Vec::new();
+    let configured_path = PathBuf::from(configured);
+
+    // 1. Configured-as-path: only if it actually has a path component, or is absolute.
+    let is_path_form = configured_path
+        .parent()
+        .map(|parent| !parent.as_os_str().is_empty())
+        .unwrap_or(false)
+        || configured_path.is_absolute();
+
+    if is_path_form {
+        if base_name_is_allowed(&configured_path) && is_executable(&configured_path) {
+            return ResolvedBinary::Found {
+                resolved_path: canonicalize(&configured_path),
+                via: ResolveSource::ConfiguredAbsolute,
+            };
+        }
+        checked.push(configured_path.clone());
+    } else {
+        // 2. Bare name: must be the allowed name itself.
+        if configured == binary_name {
+            if let Some(found) = path_lookup(binary_name) {
+                return ResolvedBinary::Found {
+                    resolved_path: found,
+                    via: ResolveSource::PathLookup,
+                };
+            }
+            checked.push(PathBuf::from(configured));
+        }
+    }
+
+    // 3. Well-known directories.
+    for dir in well_known_dirs.iter() {
+        let candidate = dir.join(binary_name);
+        if is_executable(&candidate) {
+            return ResolvedBinary::Found {
+                resolved_path: canonicalize(&candidate),
+                via: ResolveSource::WellKnown,
+            };
+        }
+        checked.push(candidate);
+    }
+
+    ResolvedBinary::Missing {
+        configured: configured.to_string(),
+        checked_paths: checked,
+    }
+}
+
+/// Convenience: resolve ffmpeg using the configured value.
+pub fn resolve_ffmpeg(configured: &str) -> ResolvedBinary {
+    resolve_binary(configured, "ffmpeg")
+}
+
+/// Convenience: resolve ffprobe using the configured value.
+pub fn resolve_ffprobe(configured: &str) -> ResolvedBinary {
+    resolve_binary(configured, "ffprobe")
+}
+
+fn base_name_is_allowed(path: &std::path::Path) -> bool {
+    // The base name of the configured path must itself be an allowed binary.
+    path.file_name()
+        .and_then(|name| name.to_str())
+        .map(|name| ALLOWED_BINARIES.contains(&name))
+        .unwrap_or(false)
+}
+
+fn is_executable(path: &std::path::Path) -> bool {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let metadata = match std::fs::metadata(path) {
+            Ok(m) => m,
+            Err(_) => return false,
+        };
+        if !metadata.is_file() {
+            return false;
+        }
+        metadata.permissions().mode() & 0o111 != 0
+    }
+    #[cfg(not(unix))]
+    {
+        std::fs::metadata(path)
+            .map(|m| m.is_file())
+            .unwrap_or(false)
+    }
+}
+
+fn canonicalize(path: &std::path::Path) -> PathBuf {
+    std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
+}
+
+fn lookup_on_path(name: &str) -> Option<PathBuf> {
+    let path_var = std::env::var_os("PATH")?;
+    for dir in std::env::split_paths(&path_var) {
+        let candidate = dir.join(name);
+        if is_executable(&candidate) {
+            return Some(canonicalize(&candidate));
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // A binary is "executable enough" for these tests if it exists on disk;
+    // we create real (empty) files rather than mocking stat calls.
+    fn write_shim(
+        dir: &std::path::Path,
+        name: &str,
+    ) -> PathBuf {
+        let path = dir.join(name);
+        std::fs::write(&path, b"#!/bin/sh\nexit 0\n").unwrap();
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let mut perms = std::fs::metadata(&path).unwrap().permissions();
+            perms.set_mode(0o755);
+            std::fs::set_permissions(&path, perms).unwrap();
+        }
+        path
+    }
+
+    // The public `resolve_binary` searches the real machine's well-known dirs
+    // and PATH (where ffmpeg may actually be installed), so these tests use the
+    // internal `resolve_binary_with` with controlled inputs to stay hermetic.
+    const NO_WELL_KNOWN: &[PathBuf] = &[];
+    fn no_path_lookup(_: &str) -> Option<PathBuf> {
+        None
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn absolute_configured_path_is_used() {
+        let dir = tempfile::tempdir().unwrap();
+        let ffmpeg = write_shim(dir.path(), "ffmpeg");
+        let resolved = resolve_binary_with(
+            ffmpeg.to_str().unwrap(),
+            "ffmpeg",
+            NO_WELL_KNOWN,
+            no_path_lookup,
+        );
+        assert!(matches!(
+            resolved,
+            ResolvedBinary::Found {
+                via: ResolveSource::ConfiguredAbsolute,
+                ..
+            }
+        ));
+        if let ResolvedBinary::Found { resolved_path, .. } = resolved {
+            // macOS canonicalizes /var -> /private/var; compare canonical forms.
+            assert_eq!(resolved_path, canonicalize(&ffmpeg));
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn disallowed_base_name_is_rejected_even_as_absolute_path() {
+        let dir = tempfile::tempdir().unwrap();
+        let rogue = write_shim(dir.path(), "not-ffmpeg");
+        // The requested binary_name itself must be allowed; a rogue name is never resolved.
+        assert!(matches!(
+            resolve_binary_with(
+                rogue.to_str().unwrap(),
+                "rogue",
+                NO_WELL_KNOWN,
+                no_path_lookup
+            ),
+            ResolvedBinary::Missing { .. }
+        ));
+        // Asking for an allowed name via a path whose base name is rogue is also rejected.
+        assert!(matches!(
+            resolve_binary_with(
+                rogue.to_str().unwrap(),
+                "ffmpeg",
+                NO_WELL_KNOWN,
+                no_path_lookup
+            ),
+            ResolvedBinary::Missing { .. }
+        ));
+    }
+
+    #[test]
+    fn missing_returns_checked_paths() {
+        // Empty well-known list + no PATH -> the only checked path is the configured one.
+        let resolved = resolve_binary_with(
+            "/definitely/does/not/exist/ffmpeg",
+            "ffmpeg",
+            NO_WELL_KNOWN,
+            no_path_lookup,
+        );
+        match resolved {
+            ResolvedBinary::Missing {
+                configured,
+                checked_paths,
+            } => {
+                assert_eq!(configured, "/definitely/does/not/exist/ffmpeg");
+                assert_eq!(
+                    checked_paths,
+                    vec![PathBuf::from(
+                        "/definitely/does/not/exist/ffmpeg"
+                    )]
+                );
+            }
+            other => panic!("expected Missing, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn well_known_dir_hit_reports_wellknown_source() {
+        // A well-known dir containing the shim resolves via WellKnown, with PATH
+        // lookup disabled so the real machine's ffmpeg can't interfere.
+        let dir = tempfile::tempdir().unwrap();
+        write_shim(dir.path(), "ffmpeg");
+        let resolved = resolve_binary_with(
+            "ffmpeg",
+            "ffmpeg",
+            &[dir.path().to_path_buf()],
+            no_path_lookup,
+        );
+        match resolved {
+            ResolvedBinary::Found {
+                via: ResolveSource::WellKnown,
+                ..
+            } => {}
+            other => panic!("expected Found via WellKnown, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn path_lookup_hit_reports_pathlookup_source() {
+        // A bare name found via PATH lookup reports PathLookup, not WellKnown.
+        let dir = tempfile::tempdir().unwrap();
+        let ffmpeg = write_shim(dir.path(), "ffmpeg");
+        let via_path = move |name: &str| {
+            if name == "ffmpeg" { Some(ffmpeg.clone()) } else { None }
+        };
+        let resolved = resolve_binary_with("ffmpeg", "ffmpeg", NO_WELL_KNOWN, via_path);
+        assert!(matches!(
+            resolved,
+            ResolvedBinary::Found {
+                via: ResolveSource::PathLookup,
+                ..
+            }
+        ));
+    }
+
+    #[test]
+    fn allowed_binaries_constant_is_what_we_expect() {
+        assert_eq!(ALLOWED_BINARIES, &["ffmpeg", "ffprobe"]);
+    }
+}
diff --git a/crates/server/src/lib.rs b/crates/server/src/lib.rs
index 31fce3cf..1096994e 100644
--- a/crates/server/src/lib.rs
+++ b/crates/server/src/lib.rs
@@ -9,6 +9,7 @@ pub mod certs;
 pub mod config;
 pub mod db;
 pub mod dependencies;
+pub mod ffmpeg_resolve;
 pub mod globals;
 mod logging;
 pub mod media;

From 7ead9bd7a9ddb49beb6726df626e8b3762deaee6 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:03:27 -0300
Subject: [PATCH 07/27] refactor(server): detect_binary delegates to
 ffmpeg_resolve with version probe

---
 crates/server/src/ffmpeg_resolve.rs |  46 ++++++++
 crates/server/src/media.rs          | 167 +++++++++++-----------------
 2 files changed, 112 insertions(+), 101 deletions(-)

diff --git a/crates/server/src/ffmpeg_resolve.rs b/crates/server/src/ffmpeg_resolve.rs
index 007829ea..ee06ae95 100644
--- a/crates/server/src/ffmpeg_resolve.rs
+++ b/crates/server/src/ffmpeg_resolve.rs
@@ -228,6 +228,24 @@ fn lookup_on_path(name: &str) -> Option<PathBuf> {
     None
 }
 
+/// Run `<binary> -version` and return the first stdout line, or [`None`] on
+/// failure. Used for capability display. Uses the synchronous std [`Command`]
+/// because this is called rarely and from sync contexts (`detect_binary`).
+pub fn probe_version(path: &std::path::Path) -> Option<String> {
+    let output = std::process::Command::new(path)
+        .arg("-version")
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&output.stdout)
+        .lines()
+        .next()
+        .map(|line| line.trim().to_string())
+        .filter(|line| !line.is_empty())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -378,4 +396,32 @@ mod tests {
     fn allowed_binaries_constant_is_what_we_expect() {
         assert_eq!(ALLOWED_BINARIES, &["ffmpeg", "ffprobe"]);
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn probe_version_reads_first_stdout_line() {
+        let dir = tempfile::tempdir().unwrap();
+        // A shim that mimics `ffmpeg -version` first line.
+        let shim = dir.path().join("ffmpeg");
+        std::fs::write(
+            &shim,
+            "#!/bin/sh\necho 'ffmpeg version 7.0.2, built locally'\nexit 0\n",
+        )
+        .unwrap();
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = std::fs::metadata(&shim).unwrap().permissions();
+        perms.set_mode(0o755);
+        std::fs::set_permissions(&shim, perms).unwrap();
+
+        let version = probe_version(&shim);
+        assert_eq!(
+            version.as_deref(),
+            Some("ffmpeg version 7.0.2, built locally")
+        );
+    }
+
+    #[test]
+    fn probe_version_returns_none_for_missing_binary() {
+        assert!(probe_version(std::path::Path::new("/definitely/does/not/exist/ffmpeg")).is_none());
+    }
 }
diff --git a/crates/server/src/media.rs b/crates/server/src/media.rs
index bff88d5a..ae902fae 100644
--- a/crates/server/src/media.rs
+++ b/crates/server/src/media.rs
@@ -1,89 +1,43 @@
 //! Media-library inspection, persistence, and transcoding capability utilities.
 
 // standard imports
-use std::collections::{
-    HashMap,
-    HashSet,
-};
+use std::collections::{HashMap, HashSet};
 use std::fs;
-use std::path::{
-    Path,
-    PathBuf,
-};
+use std::path::{Path, PathBuf};
 use std::process::Command;
 
 // lib imports
 use diesel::{
-    ExpressionMethods,
-    OptionalExtension,
-    QueryDsl,
-    RunQueryDsl,
-    SelectableHelper,
-    SqliteConnection,
-    sql_types,
+    ExpressionMethods, OptionalExtension, QueryDsl, RunQueryDsl, SelectableHelper,
+    SqliteConnection, sql_types,
 };
 use schemars::JsonSchema;
-use serde::{
-    Deserialize,
-    Serialize,
-};
+use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
 // local imports
 use crate::config::{
-    FfmpegSettings,
-    MediaLibraryKind,
-    MediaLibraryMetadataLanguageMode,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-    MetadataProviderId,
+    FfmpegSettings, MediaLibraryKind, MediaLibraryMetadataLanguageMode, MediaLibraryScanner,
+    MediaLibrarySettings, MetadataProviderId,
 };
 use crate::db::models::{
-    ItemMetadataLink,
-    MediaFile,
-    MediaItem,
-    MediaLibrary,
-    MetadataCollection,
-    MetadataCollectionItem,
-    NewMediaFile,
-    NewMediaFileLibrary,
-    NewMediaItem,
-    NewMediaLibrary,
-    NewPlaybackProgress,
-    NewScanState,
-    PlaybackProgress,
-    ScanState,
-    User,
+    ItemMetadataLink, MediaFile, MediaItem, MediaLibrary, MetadataCollection,
+    MetadataCollectionItem, NewMediaFile, NewMediaFileLibrary, NewMediaItem, NewMediaLibrary,
+    NewPlaybackProgress, NewScanState, PlaybackProgress, ScanState, User,
 };
 use crate::metadata::{
-    ArtworkKind,
-    DEFAULT_METADATA_LOCALE,
-    LinkedMetadataExtra,
-    MetadataCollectionSummary,
-    MetadataProvider,
-    MetadataRegistry,
+    ArtworkKind, DEFAULT_METADATA_LOCALE, LinkedMetadataExtra, MetadataCollectionSummary,
+    MetadataProvider, MetadataRegistry,
     list_metadata_collection_summaries_with_preferred_languages,
-    metadata_extras_from_metadata_links,
-    normalize_locale_key,
-    presentation_from_metadata_links,
+    metadata_extras_from_metadata_links, normalize_locale_key, presentation_from_metadata_links,
 };
 use crate::scanner::shows::parse_show_path;
-pub use crate::scanner::shows::{
-    infer_episode_number,
-    infer_season_number,
-};
+pub use crate::scanner::shows::{infer_episode_number, infer_season_number};
 use crate::scanner::{
-    DiscoveredMediaFile,
-    FileHashCandidate,
-    ScannerSink,
-    fallback_title_from_relative_path,
-    inspect_library,
-    inspect_library_streaming,
-};
-pub use crate::scanner::{
-    LibraryScanStatus,
-    LibraryScanSummary,
+    DiscoveredMediaFile, FileHashCandidate, ScannerSink, fallback_title_from_relative_path,
+    inspect_library, inspect_library_streaming,
 };
+pub use crate::scanner::{LibraryScanStatus, LibraryScanSummary};
 use crate::utils::current_timestamp;
 
 #[derive(Debug)]
@@ -198,8 +152,7 @@ struct LibraryMetadataRefreshCounts {
     failed_items: i64,
 }
 
-const CATALOG_MEDIA_FILE_COLUMNS: &str =
-    "\
+const CATALOG_MEDIA_FILE_COLUMNS: &str = "\
       files.id AS id,files.path AS path,memberships.id AS library_file_id,memberships.library_id \
      AS library_id,memberships.source_root_path AS source_root_path,memberships.relative_path AS \
      relative_path,files.file_size AS file_size,files.modified_at AS modified_at,files.media_kind \
@@ -784,8 +737,8 @@ pub fn inspect_libraries(libraries: &[MediaLibrarySettings]) -> Vec<LibraryScanS
 /// Detect FFmpeg and ffprobe availability from the configured settings.
 pub fn inspect_transcoding_capability(settings: &FfmpegSettings) -> TranscodingCapability {
     TranscodingCapability {
-        ffmpeg: detect_binary(&settings.ffmpeg_path),
-        ffprobe: detect_binary(&settings.ffprobe_path),
+        ffmpeg: detect_binary(&settings.ffmpeg_path, "ffmpeg"),
+        ffprobe: detect_binary(&settings.ffprobe_path, "ffprobe"),
     }
 }
 
@@ -1553,7 +1506,7 @@ fn sync_library_catalog_filtered(
 
     let probe_context = ProbeContext {
         ffprobe_path: &ffmpeg_settings.ffprobe_path,
-        enabled: detect_binary(&ffmpeg_settings.ffprobe_path).available,
+        enabled: detect_binary(&ffmpeg_settings.ffprobe_path, "ffprobe").available,
     };
     let existing_library_rows = media_libraries_dsl::media_libraries
         .order(media_libraries_dsl::id.asc())
@@ -5994,48 +5947,60 @@ pub fn list_media_item_children_with_preferred_languages(
     Ok(items)
 }
 
-fn detect_binary(binary: &str) -> BinaryCapability {
-    let output = Command::new(binary).arg("-version").output();
-
-    match output {
-        Ok(output) if output.status.success() => {
-            let version = String::from_utf8_lossy(&output.stdout)
-                .lines()
-                .next()
-                .map(|line| line.trim().to_string())
-                .filter(|line| !line.is_empty());
-
+fn detect_binary(
+    configured: &str,
+    binary_name: &str,
+) -> BinaryCapability {
+    use crate::ffmpeg_resolve::{self, ResolvedBinary};
+
+    match ffmpeg_resolve::resolve_binary(configured, binary_name) {
+        ResolvedBinary::Found { resolved_path, via } => {
+            // "available" means the binary actually launches and reports a
+            // version, not merely that it exists on disk. A found binary whose
+            // `-version` fails (e.g. a broken shim) is reported unavailable
+            // with the probe error, matching the previous semantics.
+            let version = ffmpeg_resolve::probe_version(&resolved_path);
+            let (available, error) = match &version {
+                Some(_) => (true, None),
+                None => (
+                    false,
+                    Some(format!(
+                        "{} was found at {} but did not report a version",
+                        binary_name,
+                        resolved_path.display()
+                    )),
+                ),
+            };
+            log::info!(
+                "Resolved {binary_name} via {via:?}: {} (available: {available})",
+                resolved_path.display()
+            );
             BinaryCapability {
-                configured_path: binary.to_string(),
-                available: true,
+                configured_path: configured.to_string(),
+                available,
                 version,
-                error: None,
+                error,
             }
         }
-        Ok(output) => {
-            let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
-            let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
-            let error = if !stderr.is_empty() {
-                stderr
-            } else if !stdout.is_empty() {
-                stdout
-            } else {
-                format!("Process exited with status {}", output.status)
-            };
-
+        ResolvedBinary::Missing { checked_paths, .. } => {
+            let checked_display = checked_paths
+                .iter()
+                .map(|p| p.display().to_string())
+                .collect::<Vec<_>>()
+                .join(", ");
+            log::warn!(
+                "Could not resolve {binary_name}; checked: [{}]",
+                checked_display
+            );
             BinaryCapability {
-                configured_path: binary.to_string(),
+                configured_path: configured.to_string(),
                 available: false,
                 version: None,
-                error: Some(error),
+                error: Some(format!(
+                    "Could not find {binary_name}. Checked: [{checked_display}]"
+                )),
             }
         }
-        Err(error) => BinaryCapability {
-            configured_path: binary.to_string(),
-            available: false,
-            version: None,
-            error: Some(error.to_string()),
-        },
     }
 }
 

From 9a0d2718a97b6cb623f711aa700f392612f71128 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:05:00 -0300
Subject: [PATCH 08/27] feat(server): add SpawnTranscodeError + shared
 map_transcode_error

---
 crates/server/src/transcode.rs | 137 ++++++++++++++++++++++++++++++++-
 1 file changed, 133 insertions(+), 4 deletions(-)

diff --git a/crates/server/src/transcode.rs b/crates/server/src/transcode.rs
index 8f6f711f..c261494e 100644
--- a/crates/server/src/transcode.rs
+++ b/crates/server/src/transcode.rs
@@ -3,10 +3,7 @@
 // standard imports
 use std::path::PathBuf;
 use std::process::Stdio;
-use std::sync::atomic::{
-    AtomicU64,
-    Ordering,
-};
+use std::sync::atomic::{AtomicU64, Ordering};
 
 // lib imports
 use tokio::fs;
@@ -16,6 +13,90 @@ use tokio::process::Command;
 // local imports
 use crate::config::FfmpegSettings;
 
+use rocket::http::Status;
+
+/// A structured error from attempting to spawn a transcode.
+#[derive(Debug)]
+pub enum SpawnTranscodeError {
+    /// ffmpeg could not be resolved/executed. `checked_paths` lists where we looked.
+    ExecutableMissing {
+        /// Every location the resolver inspected, for diagnostics.
+        checked_paths: Vec<PathBuf>,
+    },
+    /// ffmpeg started but reported its input was unusable. Produced by the
+    /// deferred lifecycle phase; declared here so the shared mapper is complete.
+    BadInput {
+        /// The captured stderr from ffmpeg explaining the input failure.
+        ffmpeg_stderr: String,
+    },
+    /// Any other spawn-time I/O error.
+    Io(std::io::Error),
+}
+
+impl From<std::io::Error> for SpawnTranscodeError {
+    fn from(error: std::io::Error) -> Self {
+        Self::Io(error)
+    }
+}
+
+/// The JSON body returned to clients when a transcode fails. The `action`
+/// field lets the UI decide whether to show an actionable control (e.g.
+/// "Open settings") for this kind of failure.
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct TranscodeErrorBody {
+    /// Stable machine code: `transcode_executable_missing` | `transcode_input_error` | `transcode_failed`.
+    pub code: &'static str,
+    /// Human-readable explanation.
+    pub message: String,
+    /// Optional UI action hint, e.g. `Some("open_settings")`.
+    pub action: Option<&'static str>,
+}
+
+/// Map a [`SpawnTranscodeError`] to an HTTP status + body. This is the single
+/// error-shaping function reused by the route handler today and the lifecycle
+/// watcher in a later phase.
+pub fn map_transcode_error(error: SpawnTranscodeError) -> (Status, TranscodeErrorBody) {
+    match error {
+        SpawnTranscodeError::ExecutableMissing { checked_paths } => {
+            let checked = checked_paths
+                .iter()
+                .map(|p| p.display().to_string())
+                .collect::<Vec<_>>()
+                .join(", ");
+            (
+                Status::ServiceUnavailable,
+                TranscodeErrorBody {
+                    code: "transcode_executable_missing",
+                    message: format!(
+                        "FFmpeg could not be found. Install it or set its path in Settings. \
+                         Checked: [{checked}]"
+                    ),
+                    action: Some("open_settings"),
+                },
+            )
+        }
+        SpawnTranscodeError::BadInput { ffmpeg_stderr } => (
+            Status::UnprocessableEntity,
+            TranscodeErrorBody {
+                code: "transcode_input_error",
+                message: format!(
+                    "FFmpeg could not read the source media. {}",
+                    ffmpeg_stderr.trim()
+                ),
+                action: None,
+            },
+        ),
+        SpawnTranscodeError::Io(error) => (
+            Status::InternalServerError,
+            TranscodeErrorBody {
+                code: "transcode_failed",
+                message: format!("Transcode failed to start: {error}"),
+                action: None,
+            },
+        ),
+    }
+}
+
 static NEXT_SESSION_ID: AtomicU64 = AtomicU64::new(1);
 
 /// Create a new unique session ID.
@@ -235,3 +316,51 @@ pub async fn spawn_transcode_stdout(
 
     Ok(child)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    #[test]
+    fn executable_missing_maps_to_open_settings_action() {
+        let err = SpawnTranscodeError::ExecutableMissing {
+            checked_paths: vec![PathBuf::from(
+                "/usr/bin/ffmpeg",
+            )],
+        };
+        let (status, body) = map_transcode_error(err);
+        assert_eq!(status, Status::ServiceUnavailable);
+        assert_eq!(body.code, "transcode_executable_missing");
+        assert_eq!(body.action, Some("open_settings"));
+        assert!(body.message.contains("ffmpeg"), "{}", body.message);
+    }
+
+    #[test]
+    fn io_error_maps_to_failed_with_no_action() {
+        let err = SpawnTranscodeError::Io(std::io::Error::other("boom"));
+        let (status, body) = map_transcode_error(err);
+        assert_eq!(status, Status::InternalServerError);
+        assert_eq!(body.code, "transcode_failed");
+        assert_eq!(body.action, None);
+    }
+
+    #[test]
+    fn bad_input_maps_to_input_error() {
+        let err = SpawnTranscodeError::BadInput {
+            ffmpeg_stderr: "No such file".into(),
+        };
+        let (status, body) = map_transcode_error(err);
+        assert_eq!(status, Status::UnprocessableEntity);
+        assert_eq!(body.code, "transcode_input_error");
+        assert_eq!(body.action, None);
+        assert!(body.message.contains("No such file"));
+    }
+
+    #[test]
+    fn io_error_conversion_wraps_in_variant() {
+        let io_err = std::io::Error::other("disk full");
+        let wrapped: SpawnTranscodeError = io_err.into();
+        assert!(matches!(wrapped, SpawnTranscodeError::Io(_)));
+    }
+}

From 3633ce7fbdac749cc383c6eddcdedbd74f349a07 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:07:17 -0300
Subject: [PATCH 09/27] feat(server): resolve ffmpeg before spawn; structured
 SpawnTranscodeError

---
 crates/server/src/transcode.rs | 72 +++++++++++++++++++++++++++-------
 1 file changed, 57 insertions(+), 15 deletions(-)

diff --git a/crates/server/src/transcode.rs b/crates/server/src/transcode.rs
index c261494e..714672d9 100644
--- a/crates/server/src/transcode.rs
+++ b/crates/server/src/transcode.rs
@@ -39,6 +39,36 @@ impl From<std::io::Error> for SpawnTranscodeError {
     }
 }
 
+impl std::fmt::Display for SpawnTranscodeError {
+    fn fmt(
+        &self,
+        f: &mut std::fmt::Formatter<'_>,
+    ) -> std::fmt::Result {
+        match self {
+            SpawnTranscodeError::ExecutableMissing { checked_paths } => {
+                let checked = checked_paths
+                    .iter()
+                    .map(|p| p.display().to_string())
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                write!(f, "FFmpeg could not be found. Checked: [{checked}]")
+            }
+            SpawnTranscodeError::BadInput { ffmpeg_stderr } => {
+                write!(
+                    f,
+                    "FFmpeg could not read the source media. {}",
+                    ffmpeg_stderr.trim()
+                )
+            }
+            SpawnTranscodeError::Io(error) => {
+                write!(f, "Transcode failed to start: {error}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for SpawnTranscodeError {}
+
 /// The JSON body returned to clients when a transcode fails. The `action`
 /// field lets the UI decide whether to show an actionable control (e.g.
 /// "Open settings") for this kind of failure.
@@ -261,25 +291,40 @@ impl TranscodeSpec {
     }
 }
 
+/// Resolve the configured ffmpeg path to an absolute, verified executable,
+/// logging the resolution. Returns [`SpawnTranscodeError::ExecutableMissing`]
+/// when it cannot be found — this is the actual fix for issue 1 (a bare
+/// `ffmpeg` lookup fails in GUI-launched processes that don't inherit the
+/// user's shell PATH).
+fn resolve_ffmpeg_for_spawn(
+    settings: &FfmpegSettings,
+    args_label: &str,
+) -> Result<PathBuf, SpawnTranscodeError> {
+    match crate::ffmpeg_resolve::resolve_ffmpeg(&settings.ffmpeg_path) {
+        crate::ffmpeg_resolve::ResolvedBinary::Found { resolved_path, .. } => {
+            log::info!("Starting FFmpeg {args_label}: {}", resolved_path.display());
+            Ok(resolved_path)
+        }
+        crate::ffmpeg_resolve::ResolvedBinary::Missing { checked_paths, .. } => {
+            Err(SpawnTranscodeError::ExecutableMissing { checked_paths })
+        }
+    }
+}
+
 /// Spawns a transcode process and returns it.
 pub async fn spawn_transcode(
     _session_id: &str,
     spec: &TranscodeSpec,
     settings: &FfmpegSettings,
-) -> Result<Child, std::io::Error> {
+) -> Result<Child, SpawnTranscodeError> {
     if let Some(parent) = spec.output_path.parent() {
         fs::create_dir_all(parent).await?;
     }
 
     let args = spec.to_ffmpeg_args();
+    let ffmpeg_path = resolve_ffmpeg_for_spawn(settings, &args.join(" "))?;
 
-    log::info!(
-        "Starting FFmpeg: {} {}",
-        settings.ffmpeg_path,
-        args.join(" ")
-    );
-
-    let mut command = Command::new(&settings.ffmpeg_path);
+    let mut command = Command::new(&ffmpeg_path);
     command
         .args(&args)
         .stdin(Stdio::null())
@@ -296,16 +341,13 @@ pub async fn spawn_transcode_stdout(
     _session_id: &str,
     spec: &TranscodeSpec,
     settings: &FfmpegSettings,
-) -> Result<Child, std::io::Error> {
+) -> Result<Child, SpawnTranscodeError> {
     let args = spec.to_ffmpeg_stdout_args();
+    let ffmpeg_path = resolve_ffmpeg_for_spawn(settings, "stdout stream")?;
 
-    log::info!(
-        "Starting FFmpeg stdout stream: {} {}",
-        settings.ffmpeg_path,
-        args.join(" ")
-    );
+    log::info!("FFmpeg stdout args: {}", args.join(" "));
 
-    let mut command = Command::new(&settings.ffmpeg_path);
+    let mut command = Command::new(&ffmpeg_path);
     command
         .args(&args)
         .stdin(Stdio::null())

From e6b0045f61a297526e78d1590d739e9a838432e0 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:12:14 -0300
Subject: [PATCH 10/27] feat(server): structured transcode errors + per-session
 error store

---
 crates/server/src/web/routes/media.rs | 238 ++++++++++++--------------
 1 file changed, 107 insertions(+), 131 deletions(-)

diff --git a/crates/server/src/web/routes/media.rs b/crates/server/src/web/routes/media.rs
index 7ad23cd9..17713a7b 100644
--- a/crates/server/src/web/routes/media.rs
+++ b/crates/server/src/web/routes/media.rs
@@ -1,46 +1,25 @@
 //! Media and system discovery routes.
 
 // lib imports
-use std::collections::{
-    HashMap,
-    HashSet,
-};
+use std::collections::{HashMap, HashSet};
 use std::io::SeekFrom;
 use std::path::PathBuf;
-use std::sync::atomic::{
-    AtomicBool,
-    AtomicU64,
-    Ordering,
-};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 
 use once_cell::sync::Lazy;
 use rocket::delete;
 use rocket::fs::NamedFile;
 use rocket::get;
-use rocket::http::{
-    ContentType,
-    Status,
-};
+use rocket::http::{ContentType, Status};
 use rocket::outcome::Outcome;
 use rocket::post;
-use rocket::request::{
-    FromRequest,
-    Request,
-};
+use rocket::request::{FromRequest, Request};
 use rocket::response::stream::ReaderStream;
-use rocket::response::{
-    self,
-    Responder,
-    Response,
-};
+use rocket::response::{self, Responder, Response};
 use rocket::serde::Deserialize;
 use rocket::serde::json::Json;
 use rocket::tokio::fs::File;
-use rocket::tokio::io::{
-    AsyncReadExt,
-    AsyncSeekExt,
-    Take,
-};
+use rocket::tokio::io::{AsyncReadExt, AsyncSeekExt, Take};
 use rocket::tokio::process::ChildStdout;
 use rocket_okapi::openapi;
 use schemars::JsonSchema;
@@ -49,113 +28,53 @@ use strsim::normalized_levenshtein;
 
 // local imports
 use crate::auth::UserGuard;
-use crate::config::{
-    MetadataProviderId,
-    Settings,
-    current_settings,
-};
+use crate::config::{MetadataProviderId, Settings, current_settings};
 use crate::db::DbConn;
 use crate::db::models::ItemMetadataLink;
 use crate::globals;
 use crate::media::{
-    MediaHome,
-    MediaItemDetail,
-    MediaItemSummary,
-    PersistedLibrarySummary,
-    PersistedMediaFileSummary,
-    PlaybackDecision,
-    ShowMetadataDescendantPlan,
-    ShowMetadataEpisodePlan,
-    ShowMetadataSeasonPlan,
-    TranscodingCapability,
-    apply_user_playback_context_to_detail,
-    delete_missing_media_items,
-    get_item_secondary_provider_references,
-    get_item_youtube_theme_collection_references,
-    get_library_files,
-    get_library_metadata_languages,
-    get_library_metadata_providers,
-    get_media_home_with_preferred_languages,
-    get_media_item,
-    get_media_item_summary,
-    get_media_item_with_preferred_languages,
-    get_persisted_library_summaries,
-    get_playback_decision,
-    get_preferred_item_artwork_metadata_link_for_languages,
-    get_preferred_item_metadata_link,
-    inspect_transcoding_capability,
-    library_exists,
-    list_automatic_metadata_candidates,
-    list_automatic_metadata_refresh_candidates,
-    list_library_settings,
-    list_media_item_children,
-    list_media_items,
-    list_media_items_for_user_with_preferred_languages,
-    mark_metadata_match_attempted,
-    preferred_audio_stream_index,
-    resolve_item_subtitle_path,
-    resolve_item_theme_song_path,
-    resolve_local_item_artwork_path,
-    resolve_media_item_source_path,
+    MediaHome, MediaItemDetail, MediaItemSummary, PersistedLibrarySummary,
+    PersistedMediaFileSummary, PlaybackDecision, ShowMetadataDescendantPlan,
+    ShowMetadataEpisodePlan, ShowMetadataSeasonPlan, TranscodingCapability,
+    apply_user_playback_context_to_detail, delete_missing_media_items,
+    get_item_secondary_provider_references, get_item_youtube_theme_collection_references,
+    get_library_files, get_library_metadata_languages, get_library_metadata_providers,
+    get_media_home_with_preferred_languages, get_media_item, get_media_item_summary,
+    get_media_item_with_preferred_languages, get_persisted_library_summaries,
+    get_playback_decision, get_preferred_item_artwork_metadata_link_for_languages,
+    get_preferred_item_metadata_link, inspect_transcoding_capability, library_exists,
+    list_automatic_metadata_candidates, list_automatic_metadata_refresh_candidates,
+    list_library_settings, list_media_item_children, list_media_items,
+    list_media_items_for_user_with_preferred_languages, mark_metadata_match_attempted,
+    preferred_audio_stream_index, resolve_item_subtitle_path, resolve_item_theme_song_path,
+    resolve_local_item_artwork_path, resolve_media_item_source_path,
     search_media_items_for_user_with_preferred_languages,
-    sync_persisted_library_catalog_for_library,
-    upsert_playback_progress,
-    upsert_show_metadata_descendant_items,
-    user_can_access_library,
+    sync_persisted_library_catalog_for_library, upsert_playback_progress,
+    upsert_show_metadata_descendant_items, user_can_access_library,
 };
 use crate::metadata::{
-    ArtworkKind,
-    DEFAULT_METADATA_LOCALE,
-    ItemMetadataSummary,
-    MetadataCollectionSummary,
-    MetadataPersonCreditSummary,
-    MetadataPersonEnrichmentTarget,
-    MetadataPersonSummary,
-    MetadataProviderRole,
-    MetadataProviderStatus,
-    MetadataSearchResult,
-    MetadataSnapshotFetchOptions,
-    ProviderDescendantTarget,
-    ProviderEpisodeMetadataSnapshotFetch,
-    ProviderMetadataPerson,
-    StoredMetadataSnapshot,
-    expected_artwork_cache_path,
+    ArtworkKind, DEFAULT_METADATA_LOCALE, ItemMetadataSummary, MetadataCollectionSummary,
+    MetadataPersonCreditSummary, MetadataPersonEnrichmentTarget, MetadataPersonSummary,
+    MetadataProviderRole, MetadataProviderStatus, MetadataSearchResult,
+    MetadataSnapshotFetchOptions, ProviderDescendantTarget, ProviderEpisodeMetadataSnapshotFetch,
+    ProviderMetadataPerson, StoredMetadataSnapshot, expected_artwork_cache_path,
     fetch_provider_episode_metadata_snapshot_for_locale_with_options,
     fetch_provider_metadata_snapshot_for_locale_with_options,
     fetch_provider_person_metadata_for_locale,
     fetch_provider_season_metadata_snapshot_for_locale_with_options,
-    fetch_provider_secondary_collection_metadata,
-    fetch_provider_secondary_metadata,
-    get_item_metadata_summaries,
-    get_metadata_person_for_languages,
-    get_metadata_person_locale_peer_ids,
-    get_primary_item_metadata_link,
-    guess_provider_movie_match,
-    guess_provider_show_match,
-    list_due_item_metadata_links,
-    list_metadata_collection_summaries_with_preferred_languages,
-    list_metadata_people_for_library,
-    list_metadata_person_credit_summaries_for_person_ids,
-    list_pending_item_metadata_links,
-    list_provider_statuses,
-    load_provider_show_descendant_targets,
-    managed_metadata_asset_dir,
-    metadata_asset_db_path,
-    normalize_locale_key,
-    persist_item_metadata_assets,
-    persist_metadata_people_assets,
-    provider_locale_key,
-    provider_uses_localized_metadata,
-    resolve_metadata_asset_db_path,
-    search_metadata_people_with_preferred_languages,
-    search_provider,
-    set_item_metadata_refresh_state,
-    sort_item_metadata_summaries_for_languages,
-    try_cache_item_artwork,
-    update_cached_artwork_path,
-    update_metadata_person_details,
-    upsert_item_metadata_link,
-    upsert_item_metadata_snapshot_with_refresh_interval,
+    fetch_provider_secondary_collection_metadata, fetch_provider_secondary_metadata,
+    get_item_metadata_summaries, get_metadata_person_for_languages,
+    get_metadata_person_locale_peer_ids, get_primary_item_metadata_link,
+    guess_provider_movie_match, guess_provider_show_match, list_due_item_metadata_links,
+    list_metadata_collection_summaries_with_preferred_languages, list_metadata_people_for_library,
+    list_metadata_person_credit_summaries_for_person_ids, list_pending_item_metadata_links,
+    list_provider_statuses, load_provider_show_descendant_targets, managed_metadata_asset_dir,
+    metadata_asset_db_path, normalize_locale_key, persist_item_metadata_assets,
+    persist_metadata_people_assets, provider_locale_key, provider_uses_localized_metadata,
+    resolve_metadata_asset_db_path, search_metadata_people_with_preferred_languages,
+    search_provider, set_item_metadata_refresh_state, sort_item_metadata_summaries_for_languages,
+    try_cache_item_artwork, update_cached_artwork_path, update_metadata_person_details,
+    upsert_item_metadata_link, upsert_item_metadata_snapshot_with_refresh_interval,
     upsert_secondary_collection_theme_song_url,
 };
 use crate::utils::current_timestamp;
@@ -186,6 +105,39 @@ impl<'r> Responder<'r, 'static> for SessionStream {
     }
 }
 
+/// The structured transcode error as exposed to clients (owned strings, so it
+/// serializes cleanly and matches the client `TranscodeErrorBody` type).
+#[allow(dead_code)] // constructed by get_session_status in the next task
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct SessionTranscodeError {
+    /// Stable machine code.
+    pub code: String,
+    /// Human-readable explanation.
+    pub message: String,
+    /// Optional UI action hint, e.g. `Some("open_settings")`.
+    pub action: Option<String>,
+}
+
+impl From<crate::transcode::TranscodeErrorBody> for SessionTranscodeError {
+    fn from(body: crate::transcode::TranscodeErrorBody) -> Self {
+        Self {
+            code: body.code.to_string(),
+            message: body.message,
+            action: body.action.map(str::to_string),
+        }
+    }
+}
+
+/// Status of a playback session's transcode, returned to the client so it can
+/// recover a structured error when the `<video>` element stalls.
+#[allow(dead_code)] // constructed by get_session_status in the next task
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct SessionStatusResponse {
+    /// A transcode error for this session, if any. `None` while the session is
+    /// healthy or (in this phase) when only a successful spawn has occurred.
+    pub error: Option<SessionTranscodeError>,
+}
+
 pub struct RangedFile {
     content_type: ContentType,
     body: Take<File>,
@@ -528,6 +480,25 @@ static ACTIVE_PLAYBACK_SESSIONS: Lazy<
 static ACTIVE_TRANSCODE_TASKS: Lazy<
     tokio::sync::Mutex<HashMap<String, tokio::task::JoinHandle<()>>>,
 > = Lazy::new(|| tokio::sync::Mutex::new(HashMap::new()));
+/// Per-session transcode errors, written by the lifecycle watcher (deferred
+/// phase) and read by [`get_session_status`]. Inert in the current phase:
+/// only spawn-time failures are recorded here.
+static ACTIVE_SESSION_ERRORS: Lazy<
+    tokio::sync::RwLock<HashMap<String, crate::transcode::TranscodeErrorBody>>,
+> = Lazy::new(|| tokio::sync::RwLock::new(HashMap::new()));
+
+/// Record a per-session transcode error so the client can recover structured
+/// detail via [`get_session_status`] (the stream response body is unreadable
+/// from a `<video>` src). The lifecycle watcher will also call this.
+async fn record_session_error(
+    session_id: &str,
+    error: crate::transcode::TranscodeErrorBody,
+) {
+    ACTIVE_SESSION_ERRORS
+        .write()
+        .await
+        .insert(session_id.to_string(), error);
+}
 
 #[derive(Debug, Clone)]
 struct MetadataRefreshActivityRecord {
@@ -2871,12 +2842,7 @@ fn user_preferred_metadata_languages(
     user_id: Option<i32>,
 ) -> Result<Vec<String>, diesel::result::Error> {
     use crate::db::schema::users::dsl as users_dsl;
-    use diesel::{
-        ExpressionMethods,
-        OptionalExtension,
-        QueryDsl,
-        RunQueryDsl,
-    };
+    use diesel::{ExpressionMethods, OptionalExtension, QueryDsl, RunQueryDsl};
 
     let Some(user_id) = user_id else {
         return Ok(vec![crate::metadata::DEFAULT_METADATA_LOCALE.to_string()]);
@@ -3649,8 +3615,18 @@ pub async fn get_session_stream(
             })
         }
         Err(e) => {
-            log::error!("Failed to spawn transcode: {}", e);
-            Err(Status::InternalServerError)
+            let (status, body) = crate::transcode::map_transcode_error(e);
+            log::error!(
+                "Failed to spawn transcode for session {}: {} ({} — action: {:?})",
+                session_id,
+                body.message,
+                body.code,
+                body.action
+            );
+            // Persist for the status read, so the client can recover the detail
+            // even though the stream response body is unreadable from a <video> src.
+            record_session_error(&session_id, body).await;
+            Err(status)
         }
     }
 }

From 6d4b778ba00307c106e45b132c537d5543236851 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:16:40 -0300
Subject: [PATCH 11/27] feat(server): add transcoding-tools discover +
 session-status routes

---
 crates/server/src/ffmpeg_resolve.rs   |  10 ++
 crates/server/src/web/routes/media.rs | 163 +++++++++++++++++++++++++-
 crates/server/src/web/routes/mod.rs   |   2 +
 3 files changed, 172 insertions(+), 3 deletions(-)

diff --git a/crates/server/src/ffmpeg_resolve.rs b/crates/server/src/ffmpeg_resolve.rs
index ee06ae95..4693b4f0 100644
--- a/crates/server/src/ffmpeg_resolve.rs
+++ b/crates/server/src/ffmpeg_resolve.rs
@@ -246,6 +246,16 @@ pub fn probe_version(path: &std::path::Path) -> Option<String> {
         .filter(|line| !line.is_empty())
 }
 
+/// Public accessor for the platform well-known directory list, for discovery.
+pub fn well_known_dirs_public() -> Vec<PathBuf> {
+    WELL_KNOWN_DIRS.clone()
+}
+
+/// Public accessor for the executability check, for discovery.
+pub fn is_executable_public(path: &std::path::Path) -> bool {
+    is_executable(path)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/server/src/web/routes/media.rs b/crates/server/src/web/routes/media.rs
index 17713a7b..498797e1 100644
--- a/crates/server/src/web/routes/media.rs
+++ b/crates/server/src/web/routes/media.rs
@@ -27,7 +27,7 @@ use serde::Serialize;
 use strsim::normalized_levenshtein;
 
 // local imports
-use crate::auth::UserGuard;
+use crate::auth::{AdminGuard, UserGuard};
 use crate::config::{MetadataProviderId, Settings, current_settings};
 use crate::db::DbConn;
 use crate::db::models::ItemMetadataLink;
@@ -107,7 +107,6 @@ impl<'r> Responder<'r, 'static> for SessionStream {
 
 /// The structured transcode error as exposed to clients (owned strings, so it
 /// serializes cleanly and matches the client `TranscodeErrorBody` type).
-#[allow(dead_code)] // constructed by get_session_status in the next task
 #[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
 pub struct SessionTranscodeError {
     /// Stable machine code.
@@ -130,7 +129,6 @@ impl From<crate::transcode::TranscodeErrorBody> for SessionTranscodeError {
 
 /// Status of a playback session's transcode, returned to the client so it can
 /// recover a structured error when the `<video>` element stalls.
-#[allow(dead_code)] // constructed by get_session_status in the next task
 #[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
 pub struct SessionStatusResponse {
     /// A transcode error for this session, if any. `None` while the session is
@@ -138,6 +136,39 @@ pub struct SessionStatusResponse {
     pub error: Option<SessionTranscodeError>,
 }
 
+/// Validation result for a single binary (the configured path or a candidate).
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct BinaryProbe {
+    /// The resolved absolute path, if the binary was found.
+    pub resolved_path: Option<String>,
+    /// First line of `ffmpeg -version` / `ffprobe -version`, when available.
+    pub version: Option<String>,
+    /// Why the binary is unavailable, when applicable.
+    pub error: Option<String>,
+}
+
+/// One directory discovered to contain ffmpeg and/or ffprobe.
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct ToolCandidate {
+    /// The directory path (serialized as a string).
+    pub directory: String,
+    /// ffmpeg probe result; `None` if absent in this directory.
+    pub ffmpeg: Option<BinaryProbe>,
+    /// ffprobe probe result; `None` if absent in this directory.
+    pub ffprobe: Option<BinaryProbe>,
+}
+
+/// Result of the on-demand transcoding-tools discovery call.
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct ToolDiscoveryResponse {
+    /// Validation of the user's currently-configured ffmpeg path.
+    pub configured_ffmpeg: BinaryProbe,
+    /// Validation of the user's currently-configured ffprobe path.
+    pub configured_ffprobe: BinaryProbe,
+    /// One entry per directory containing at least one of ffmpeg/ffprobe.
+    pub candidates: Vec<ToolCandidate>,
+}
+
 pub struct RangedFile {
     content_type: ContentType,
     body: Take<File>,
@@ -3014,6 +3045,132 @@ pub async fn get_server_capabilities(
     }))
 }
 
+/// Probe a single configured path/name for a binary, returning its resolved
+/// path + version or an error describing where we looked.
+fn probe_configured(
+    configured: &str,
+    binary_name: &str,
+) -> BinaryProbe {
+    use crate::ffmpeg_resolve::{self, ResolvedBinary};
+    match ffmpeg_resolve::resolve_binary(configured, binary_name) {
+        ResolvedBinary::Found { resolved_path, .. } => {
+            let version = ffmpeg_resolve::probe_version(&resolved_path);
+            BinaryProbe {
+                resolved_path: Some(resolved_path.display().to_string()),
+                version,
+                error: None,
+            }
+        }
+        ResolvedBinary::Missing { checked_paths, .. } => {
+            let checked = checked_paths
+                .iter()
+                .map(|p| p.display().to_string())
+                .collect::<Vec<_>>()
+                .join(", ");
+            BinaryProbe {
+                resolved_path: None,
+                version: None,
+                error: Some(format!("Not found. Checked: [{checked}]")),
+            }
+        }
+    }
+}
+
+/// Probe a single directory for a binary (for the candidates list).
+fn probe_in_dir(
+    dir: &std::path::Path,
+    binary_name: &str,
+) -> Option<BinaryProbe> {
+    let candidate = dir.join(binary_name);
+    if crate::ffmpeg_resolve::is_executable_public(&candidate) {
+        let version = crate::ffmpeg_resolve::probe_version(&candidate);
+        Some(BinaryProbe {
+            resolved_path: Some(candidate.display().to_string()),
+            version,
+            error: None,
+        })
+    } else {
+        None
+    }
+}
+
+/// Discover ffmpeg/ffprobe candidates and validate the configured paths.
+///
+/// On-demand from the settings page. Searches PATH + well-known locations and
+/// also validates the user's currently-configured paths. Read-only.
+#[openapi(tag = "Media")]
+#[post("/api/v1/system/tools/discover")]
+pub async fn discover_transcoding_tools(
+    _admin_guard: AdminGuard
+) -> Result<Json<ToolDiscoveryResponse>, Status> {
+    let settings = current_settings();
+    let configured_ffmpeg = probe_configured(&settings.ffmpeg.ffmpeg_path, "ffmpeg");
+    let configured_ffprobe = probe_configured(&settings.ffmpeg.ffprobe_path, "ffprobe");
+
+    // Collect candidate directories from PATH + well-known, de-duplicated, in order.
+    use std::collections::HashSet;
+    let mut seen: HashSet<String> = HashSet::new();
+    let mut dirs: Vec<std::path::PathBuf> = Vec::new();
+    if let Some(path_var) = std::env::var_os("PATH") {
+        for dir in std::env::split_paths(&path_var) {
+            if let Some(s) = dir.to_str() {
+                if seen.insert(s.to_string()) {
+                    dirs.push(dir);
+                }
+            }
+        }
+    }
+    for dir in crate::ffmpeg_resolve::well_known_dirs_public() {
+        if let Some(s) = dir.to_str() {
+            if seen.insert(s.to_string()) {
+                dirs.push(dir);
+            }
+        }
+    }
+
+    let mut candidates = Vec::new();
+    for dir in dirs {
+        let ffmpeg = probe_in_dir(&dir, "ffmpeg");
+        let ffprobe = probe_in_dir(&dir, "ffprobe");
+        if ffmpeg.is_some() || ffprobe.is_some() {
+            candidates.push(ToolCandidate {
+                directory: dir.display().to_string(),
+                ffmpeg,
+                ffprobe,
+            });
+        }
+    }
+
+    Ok(Json(ToolDiscoveryResponse {
+        configured_ffmpeg,
+        configured_ffprobe,
+        candidates,
+    }))
+}
+
+/// Return the transcode status for a playback session.
+///
+/// Used by the client to recover a structured error when the `<video>` element
+/// stalls. Returns `{ error: null }` for a healthy session.
+#[openapi(tag = "Media")]
+#[get("/api/v1/sessions/<session_id>/status")]
+pub async fn get_session_status(session_id: String) -> Result<Json<SessionStatusResponse>, Status> {
+    let session_known = ACTIVE_PLAYBACK_SESSIONS
+        .read()
+        .await
+        .contains_key(&session_id);
+    let error = ACTIVE_SESSION_ERRORS
+        .read()
+        .await
+        .get(&session_id)
+        .cloned()
+        .map(SessionTranscodeError::from);
+    if !session_known && error.is_none() {
+        return Err(Status::NotFound);
+    }
+    Ok(Json(SessionStatusResponse { error }))
+}
+
 /// Trigger a full catalog scan and return the updated summary for one library.
 #[openapi(tag = "Media")]
 #[post("/api/v1/libraries/<library_id>/scan")]
diff --git a/crates/server/src/web/routes/mod.rs b/crates/server/src/web/routes/mod.rs
index 78d04c70..4b0d980e 100644
--- a/crates/server/src/web/routes/mod.rs
+++ b/crates/server/src/web/routes/mod.rs
@@ -21,6 +21,7 @@ pub fn api_routes() -> Vec<rocket::Route> {
         auth::user_info,
         dependencies::get_dependencies,
         media::get_server_capabilities,
+        media::discover_transcoding_tools,
         media::get_system_activities,
         media::get_metadata_providers,
         media::get_metadata_locales,
@@ -40,6 +41,7 @@ pub fn api_routes() -> Vec<rocket::Route> {
         media::get_item_playback,
         media::create_session,
         media::delete_session,
+        media::get_session_status,
         media::search_items,
         media::update_item_progress,
         settings::get_settings,

From 6b2a4b47a972e40b4eed678a189805df31b4fdf8 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:18:46 -0300
Subject: [PATCH 12/27] test(server): integration tests for discover +
 session-status routes

---
 crates/server/tests/test_web/routes/mod.rs   |  1 +
 crates/server/tests/test_web/routes/tools.rs | 97 ++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 crates/server/tests/test_web/routes/tools.rs

diff --git a/crates/server/tests/test_web/routes/mod.rs b/crates/server/tests/test_web/routes/mod.rs
index 0564744f..d5f2737d 100644
--- a/crates/server/tests/test_web/routes/mod.rs
+++ b/crates/server/tests/test_web/routes/mod.rs
@@ -3,4 +3,5 @@ mod common;
 mod dependencies;
 mod media;
 mod settings;
+mod tools;
 mod user;
diff --git a/crates/server/tests/test_web/routes/tools.rs b/crates/server/tests/test_web/routes/tools.rs
new file mode 100644
index 00000000..4f9e7ec0
--- /dev/null
+++ b/crates/server/tests/test_web/routes/tools.rs
@@ -0,0 +1,97 @@
+// lib imports
+use rocket::http::Status;
+
+// test imports
+use crate::test_utils::{create_test_client, create_test_user, login_user, make_request};
+
+/// The discover endpoint must reject unauthenticated callers. It is
+/// admin-gated, so without a valid admin token it must never return 200.
+#[rocket::async_test]
+async fn discover_requires_admin() {
+    let client = create_test_client(Some("tools_discover_requires_admin")).await;
+
+    // Unauthenticated -> forbidden/unauthorized, never 200.
+    let response = make_request(
+        Some(&client),
+        "post",
+        "/api/v1/system/tools/discover",
+        None,
+        None,
+        None,
+        Some(false),
+    )
+    .await;
+    assert!(
+        response.status == Status::Unauthorized || response.status == Status::Forbidden,
+        "expected auth failure, got {}",
+        response.status
+    );
+}
+
+/// An admin caller can reach the discover endpoint and gets a well-formed
+/// response with the expected top-level fields.
+#[rocket::async_test]
+async fn discover_returns_candidates_for_admin() {
+    let client = create_test_client(Some("tools_discover_admin")).await;
+
+    // Set up an admin user and log in.
+    let (status, _) = create_test_user(
+        &client,
+        "admin",
+        "password123",
+        true,
+        None,
+        Some(Status::Ok),
+    )
+    .await;
+    assert_eq!(status, Status::Ok);
+    let token = login_user(&client, "admin", "password123", Some(Status::Ok))
+        .await
+        .expect("admin login should succeed");
+
+    let response = make_request(
+        Some(&client),
+        "post",
+        "/api/v1/system/tools/discover",
+        None,
+        Some(format!("Bearer {}", token)),
+        Some(Status::Ok),
+        Some(false),
+    )
+    .await;
+
+    let json: serde_json::Value =
+        serde_json::from_str(&response.body).expect("discover response should be valid JSON");
+    // Top-level fields must be present (regardless of whether ffmpeg exists).
+    assert!(
+        json.get("configured_ffmpeg").is_some(),
+        "missing configured_ffmpeg"
+    );
+    assert!(
+        json.get("configured_ffprobe").is_some(),
+        "missing configured_ffprobe"
+    );
+    assert!(json.get("candidates").is_some(), "missing candidates");
+    assert!(
+        json["candidates"].is_array(),
+        "candidates should be an array"
+    );
+}
+
+/// The session-status endpoint returns 404 for an unknown session with no
+/// recorded error.
+#[rocket::async_test]
+async fn session_status_unknown_session_is_404() {
+    let client = create_test_client(Some("tools_status_unknown")).await;
+    let response = make_request(
+        Some(&client),
+        "get",
+        "/api/v1/sessions/does-not-exist/status",
+        None,
+        None,
+        Some(Status::NotFound),
+        Some(false),
+    )
+    .await;
+    assert_eq!(response.status, Status::NotFound);
+}

From 6656603dd926f22f25bd703425a71be767f8c1e6 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:19:57 -0300
Subject: [PATCH 13/27] test(server): cover transcode arg generation, incl.
 spaces-in-path invariant

---
 crates/server/src/transcode.rs | 70 ++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/crates/server/src/transcode.rs b/crates/server/src/transcode.rs
index 714672d9..f56bd50f 100644
--- a/crates/server/src/transcode.rs
+++ b/crates/server/src/transcode.rs
@@ -405,4 +405,74 @@ mod tests {
         let wrapped: SpawnTranscodeError = io_err.into();
         assert!(matches!(wrapped, SpawnTranscodeError::Io(_)));
     }
+
+    fn spec_with_source(source: &str) -> TranscodeSpec {
+        TranscodeSpec {
+            source_path: PathBuf::from(source),
+            output_path: PathBuf::from("/tmp/out.mp4"),
+            container: "mp4".into(),
+            video_codec: None,
+            audio_codec: None,
+            max_width: None,
+            max_height: None,
+            max_bitrate_kbps: None,
+            start_time_ms: None,
+            audio_stream_index: None,
+        }
+    }
+
+    #[test]
+    fn source_path_with_spaces_and_brackets_is_one_argv_entry() {
+        // The "spaces in path" framing is a red herring: Command::args bypasses
+        // the shell, so a source path with spaces/brackets is passed to ffmpeg
+        // as a single argv entry. This test pins that invariant.
+        let spec =
+            spec_with_source("/Users/hazer/Downloads/Torrents/[Group] Title With Spaces E10.mkv");
+        let args = spec.to_ffmpeg_args();
+        let i_pos = args.iter().position(|a| a == "-i").expect("-i present");
+        let path_arg = &args[i_pos + 1];
+        assert_eq!(
+            path_arg,
+            "/Users/hazer/Downloads/Torrents/[Group] Title With Spaces E10.mkv"
+        );
+        // And it must be exactly one element (no shell splitting happened).
+        assert_eq!(args.iter().filter(|a| **a == *path_arg).count(), 1);
+    }
+
+    #[test]
+    fn copy_codecs_when_none_specified() {
+        let spec = spec_with_source("/tmp/in.mkv");
+        let args = spec.to_ffmpeg_args();
+        let v_pos = args.iter().position(|a| a == "-c:v").expect("-c:v present");
+        assert_eq!(args[v_pos + 1], "copy");
+        let a_pos = args.iter().position(|a| a == "-c:a").expect("-c:a present");
+        assert_eq!(args[a_pos + 1], "copy");
+    }
+
+    #[test]
+    fn mp4_container_emits_fragmented_movflags() {
+        let spec = spec_with_source("/tmp/in.mkv");
+        let args = spec.to_ffmpeg_args();
+        let mf_pos = args
+            .iter()
+            .position(|a| a == "-movflags")
+            .expect("-movflags present");
+        assert!(
+            args[mf_pos + 1].contains("frag_keyframe"),
+            "expected frag_keyframe in movflags, got {}",
+            args[mf_pos + 1]
+        );
+        assert!(
+            args[mf_pos + 1].contains("empty_moov"),
+            "expected empty_moov in movflags, got {}",
+            args[mf_pos + 1]
+        );
+    }
+
+    #[test]
+    fn stdout_args_target_pipe1() {
+        let spec = spec_with_source("/tmp/in.mkv");
+        let args = spec.to_ffmpeg_stdout_args();
+        assert_eq!(args.last().expect("args non-empty"), "pipe:1");
+    }
 }

From 346c6816e490dde2c4fbcf264bfef30a66f386d1 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:22:21 -0300
Subject: [PATCH 14/27] test(server): add opt-in real-ffmpeg smoke test behind
 feature flag

---
 crates/server/Cargo.toml            |  3 +++
 crates/server/src/ffmpeg_resolve.rs | 18 ++++++++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml
index 5ac9b7f6..0a7c5a9c 100644
--- a/crates/server/Cargo.toml
+++ b/crates/server/Cargo.toml
@@ -55,6 +55,9 @@ tray = [
     "dep:tray-icon",
     "dep:webbrowser",
 ]
+# Opt-in: run a real-ffmpeg smoke test (requires ffmpeg installed locally).
+# Normal CI runs without this so the suite is hermetic.
+real-ffmpeg-tests = []
 
 [dependencies]
 # ensure deps are compatible: https://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses
diff --git a/crates/server/src/ffmpeg_resolve.rs b/crates/server/src/ffmpeg_resolve.rs
index 4693b4f0..3adc19a9 100644
--- a/crates/server/src/ffmpeg_resolve.rs
+++ b/crates/server/src/ffmpeg_resolve.rs
@@ -434,4 +434,22 @@ mod tests {
     fn probe_version_returns_none_for_missing_binary() {
         assert!(probe_version(std::path::Path::new("/definitely/does/not/exist/ffmpeg")).is_none());
     }
+
+    /// Smoke test that only runs when invoked with `--features real-ffmpeg-tests`
+    /// AND ffmpeg is actually installed. Skipped in normal CI so the suite stays
+    /// hermetic; locally, a developer with ffmpeg can opt in.
+    #[cfg(feature = "real-ffmpeg-tests")]
+    #[test]
+    fn real_ffmpeg_on_path_is_found() {
+        match resolve_binary("ffmpeg", "ffmpeg") {
+            ResolvedBinary::Found { via, .. } => {
+                println!("resolved ffmpeg via {via:?}");
+            }
+            ResolvedBinary::Missing { checked_paths, .. } => {
+                panic!(
+                    "real-ffmpeg-tests feature is enabled but ffmpeg was not found; checked: {checked_paths:?}"
+                );
+            }
+        }
+    }
 }

From 09956095c3dc17226cd0e1497e342771c7ae9202 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:24:43 -0300
Subject: [PATCH 15/27] feat(client): add transcoding discovery + session
 status API helpers

---
 crates/client-web/src/api.ts | 43 ++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/crates/client-web/src/api.ts b/crates/client-web/src/api.ts
index 0b566fc2..b4f1e224 100644
--- a/crates/client-web/src/api.ts
+++ b/crates/client-web/src/api.ts
@@ -53,6 +53,39 @@ export interface ServerCapabilities {
   };
 }
 
+/** Validation result for a single transcoding binary (configured path or candidate). */
+export interface BinaryProbe {
+  resolved_path?: string;
+  version?: string;
+  error?: string;
+}
+
+/** One directory discovered to contain ffmpeg and/or ffprobe. */
+export interface ToolCandidate {
+  directory: string;
+  ffmpeg?: BinaryProbe;
+  ffprobe?: BinaryProbe;
+}
+
+/** Result of the on-demand transcoding-tools discovery call. */
+export interface ToolDiscoveryResponse {
+  configured_ffmpeg: BinaryProbe;
+  configured_ffprobe: BinaryProbe;
+  candidates: ToolCandidate[];
+}
+
+/** A structured transcode error recoverable via the session-status endpoint. */
+export interface TranscodeErrorBody {
+  code: string;
+  message: string;
+  action?: string;
+}
+
+/** Status of a playback session's transcode. */
+export interface SessionStatusResponse {
+  error?: TranscodeErrorBody;
+}
+
 export interface BootstrapUser {
   id: number;
   username: string;
@@ -1275,6 +1308,16 @@ export function deletePlaybackSession(sessionId: string): Promise<void> {
   return requestJson<void>('DELETE', `/api/v1/sessions/${sessionId}`);
 }
 
+/** Discover ffmpeg/ffprobe candidates and validate the configured paths (admin). */
+export function discoverTranscodingTools(): Promise<ToolDiscoveryResponse> {
+  return requestJson<ToolDiscoveryResponse>('POST', '/api/v1/system/tools/discover');
+}
+
+/** Read a playback session's transcode status (cheap map lookup, not a spawn). */
+export function getSessionStatus(sessionId: string): Promise<SessionStatusResponse> {
+  return requestJson<SessionStatusResponse>('GET', `/api/v1/sessions/${encodeURIComponent(sessionId)}/status`);
+}
+
 export function getArtworkUrl(itemId: number, kind: 'poster' | 'backdrop' | 'logo' = 'poster', revision?: number): string {
   const params = new URLSearchParams({ kind });
   if (typeof revision === 'number') {

From 93cf527d6e9e7d76cda96394a61449c74f7ad870 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:26:13 -0300
Subject: [PATCH 16/27] feat(client): dynamic playback error copy via
 state.playbackError

---
 crates/client-web/src/app/playbackController.ts | 4 ++--
 crates/client-web/src/app/types.ts              | 2 ++
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/crates/client-web/src/app/playbackController.ts b/crates/client-web/src/app/playbackController.ts
index 30f6427c..bc874200 100644
--- a/crates/client-web/src/app/playbackController.ts
+++ b/crates/client-web/src/app/playbackController.ts
@@ -322,8 +322,8 @@ function renderMediaPlayerOverlay(): string {
           <span class="loading-spinner player-loading-spinner" aria-hidden="true"></span>
         </div>
         <div class="player-error-indicator" aria-live="polite">
-          <strong>Playback could not start</strong>
-          <span>Try another audio track or start playback again.</span>
+          <strong>${escapeHtml(state.playbackError ? 'Playback failed' : 'Playback could not start')}</strong>
+          <span>${escapeHtml(state.playbackError?.message ?? 'Try another audio track or start playback again.')}</span>
         </div>
         <div class="player-idle-hit-area" aria-hidden="true"></div>
         <div class="player-top-controls player-controls">
diff --git a/crates/client-web/src/app/types.ts b/crates/client-web/src/app/types.ts
index 60ba8a42..25bf635e 100644
--- a/crates/client-web/src/app/types.ts
+++ b/crates/client-web/src/app/types.ts
@@ -140,6 +140,8 @@ export interface AppState {
   activeTrailer?: TrailerOption;
   expandedTextKeys: Set<string>;
   error?: string;
+  /** Structured playback error driving the in-player overlay and global banner. */
+  playbackError?: { code: string; message: string; action?: string };
   hasDeferredAutoRefreshRender: boolean;
   metadataDashboardFilters: {
     libraryId: string;

From 8212486e2f5ebb7042592b20388ee101383044f3 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:29:23 -0300
Subject: [PATCH 17/27] feat(client): preflight ffmpeg availability before
 transcode playback

---
 crates/client-web/src/app.ts                  |  2 +-
 crates/client-web/src/app/eventBindings.ts    |  6 ++++++
 .../client-web/src/app/playbackController.ts  | 20 +++++++++++++++++++
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/crates/client-web/src/app.ts b/crates/client-web/src/app.ts
index 6e80ede2..d047bf7b 100644
--- a/crates/client-web/src/app.ts
+++ b/crates/client-web/src/app.ts
@@ -468,7 +468,7 @@ function render(preserveScroll = true): void {
       ${renderRail()}
       <div class="main-shell">
         <div class="main-shell-inner">
-          ${state.error ? `<section class="panel error-panel page-panel">${escapeHtml(state.error)}</section>` : ''}
+          ${state.error ? `<section class="panel error-panel page-panel">${escapeHtml(state.error)}${state.playbackError?.action === 'open_settings' ? `<button class="secondary-button" type="button" data-action="open-settings">Open settings</button>` : ''}</section>` : ''}
           ${renderCurrentPage()}
         </div>
       </div>
diff --git a/crates/client-web/src/app/eventBindings.ts b/crates/client-web/src/app/eventBindings.ts
index 08751241..9f0fd6f3 100644
--- a/crates/client-web/src/app/eventBindings.ts
+++ b/crates/client-web/src/app/eventBindings.ts
@@ -527,6 +527,12 @@ function bindRenderEvents(context: AppEventBindingContext): void {
     });
   });
 
+  document.querySelectorAll<HTMLElement>('[data-action="open-settings"]').forEach((button) => {
+    button.addEventListener('click', () => {
+      navigateTo('/settings');
+    });
+  });
+
   document.querySelectorAll<HTMLButtonElement>('[data-provider-settings]').forEach((button) => {
     button.addEventListener('click', () => {
       const providerId = button.dataset.providerSettings;
diff --git a/crates/client-web/src/app/playbackController.ts b/crates/client-web/src/app/playbackController.ts
index bc874200..1675efa7 100644
--- a/crates/client-web/src/app/playbackController.ts
+++ b/crates/client-web/src/app/playbackController.ts
@@ -615,6 +615,8 @@ export async function startPlayback(item: MediaItemDetail, startMs: number): Pro
   state.isPlayerOpen = true;
   state.activeAudioStreamIndex = undefined;
   state.isAudioTrackMenuOpen = false;
+  // Clear any stale playback error from a previous attempt.
+  state.playbackError = undefined;
   render();
 
   if (previousSession) {
@@ -627,6 +629,24 @@ export async function startPlayback(item: MediaItemDetail, startMs: number): Pro
     item_id: item.id,
     client_profile: getWebClientProfile(),
   });
+
+  // Preflight: if this item needs transcoding but ffmpeg is unavailable on the
+  // server, don't attach a doomed stream — surface the error now instead of a
+  // black screen. This is the deterministic, timer-free detection for issue 2.
+  const ffmpegAvailable = state.capabilities?.transcoding.ffmpeg.available === true;
+  const needsTranscode = state.activePlaybackSession.decision.transcode_required;
+  if (needsTranscode && !ffmpegAvailable) {
+    const capabilityError = state.capabilities?.transcoding.ffmpeg.error;
+    state.playbackError = {
+      code: 'transcode_executable_missing',
+      message: capabilityError ?? 'Transcoding is required but FFmpeg is not available on the server.',
+      action: 'open_settings',
+    };
+    state.error = 'Transcoding requires FFmpeg, which the server could not find. Set its path in Settings.';
+    render();
+    return;
+  }
+
   render();
 }
 

From 3ade75f19ec2324bdceab79711e5c8363cb84010 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:31:17 -0300
Subject: [PATCH 18/27] feat(client): recover structured transcode error via
 session status read

---
 .../client-web/src/app/playbackController.ts   | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/crates/client-web/src/app/playbackController.ts b/crates/client-web/src/app/playbackController.ts
index 1675efa7..d546048d 100644
--- a/crates/client-web/src/app/playbackController.ts
+++ b/crates/client-web/src/app/playbackController.ts
@@ -7,6 +7,7 @@ import {
   deletePlaybackSession,
   getArtworkUrl,
   getItem,
+  getSessionStatus,
   getSessionStreamUrl,
   getWebClientProfile,
   resolveApiUrl,
@@ -1350,6 +1351,23 @@ export function bindPlayerProgress(): void {
   player.addEventListener('error', () => {
     setPlayerError();
     console.error('Media playback failed', player.error);
+    const sessionId = state.activePlaybackSession?.session_id;
+    if (!sessionId) {
+      return;
+    }
+    // Best-effort: recover a structured error from the per-session store. This
+    // is a cheap map lookup on the server, not a transcode spawn. It only helps
+    // when the browser actually fires `error` (HTTP failures are unreliable).
+    void getSessionStatus(sessionId)
+      .then((status) => {
+        if (status.error) {
+          state.playbackError = status.error;
+          render();
+        }
+      })
+      .catch((error) => {
+        console.warn('Failed to fetch session status after playback error', error);
+      });
   });
   player.addEventListener('loadedmetadata', () => {
     applyInitialDirectSeek();

From 9d139b6f06c197486526674d31a9d8e238c6c02c Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:34:23 -0300
Subject: [PATCH 19/27] feat(client): Detect ffmpeg button with
 directory-paired radio picker

---
 crates/client-web/src/app/eventBindings.ts | 35 +++++++++++++++-
 crates/client-web/src/app/settingsView.ts  | 49 +++++++++++++++++++++-
 crates/client-web/src/style.css            | 21 ++++++++++
 3 files changed, 103 insertions(+), 2 deletions(-)

diff --git a/crates/client-web/src/app/eventBindings.ts b/crates/client-web/src/app/eventBindings.ts
index 9f0fd6f3..67c9d919 100644
--- a/crates/client-web/src/app/eventBindings.ts
+++ b/crates/client-web/src/app/eventBindings.ts
@@ -43,7 +43,7 @@ import {
   selectedItemDefaultMetadataYear,
   selectedItemExtras,
 } from './itemPersonView';
-import { buildSettingsFromForm } from './settingsView';
+import { buildSettingsFromForm, renderDiscoverResults } from './settingsView';
 import { setButtonBusy } from './ui';
 import {
   addLibrary,
@@ -52,6 +52,7 @@ import {
   createUser,
   deleteLibrary,
   deleteMissingItems,
+  discoverTranscodingTools,
   getItemMetadata,
   getLogs,
   getUsers,
@@ -533,6 +534,38 @@ function bindRenderEvents(context: AppEventBindingContext): void {
     });
   });
 
+  document.querySelector<HTMLButtonElement>('#detect-ffmpeg')?.addEventListener('click', async (event) => {
+    const button = event.currentTarget as HTMLButtonElement;
+    const resultsContainer = document.querySelector<HTMLElement>('#ffmpeg-discover-results');
+    const ffmpegInput = document.querySelector<HTMLInputElement>('input[name="ffmpeg_path"]');
+    const ffprobeInput = document.querySelector<HTMLInputElement>('input[name="ffprobe_path"]');
+    if (!resultsContainer || !ffmpegInput || !ffprobeInput) {
+      return;
+    }
+    setButtonBusy(button, true);
+    try {
+      const discovery = await discoverTranscodingTools();
+      resultsContainer.innerHTML = renderDiscoverResults(discovery);
+      resultsContainer.hidden = false;
+      resultsContainer.querySelectorAll<HTMLInputElement>('input[name="ffmpeg-discover-choice"]').forEach((radio) => {
+        radio.addEventListener('change', () => {
+          if (radio.value === 'manual' || radio.value === 'current') {
+            return; // leave the text inputs as-is
+          }
+          // A directory: set both inputs to <dir>/ffmpeg and <dir>/ffprobe.
+          const dir = radio.value;
+          ffmpegInput.value = `${dir}/ffmpeg`;
+          ffprobeInput.value = `${dir}/ffprobe`;
+        });
+      });
+    } catch (error) {
+      resultsContainer.hidden = false;
+      resultsContainer.innerHTML = `<p class="muted">Detection failed: ${escapeHtml(error instanceof Error ? error.message : 'unknown error')}</p>`;
+    } finally {
+      setButtonBusy(button, false);
+    }
+  });
+
   document.querySelectorAll<HTMLButtonElement>('[data-provider-settings]').forEach((button) => {
     button.addEventListener('click', () => {
       const providerId = button.dataset.providerSettings;
diff --git a/crates/client-web/src/app/settingsView.ts b/crates/client-web/src/app/settingsView.ts
index e89276ea..4b847457 100644
--- a/crates/client-web/src/app/settingsView.ts
+++ b/crates/client-web/src/app/settingsView.ts
@@ -1,5 +1,5 @@
 /** Renders settings sections and converts settings forms into API payloads. */
-import type { MediaLibrary, MediaLibrarySettings, MetadataProviderSettings, MetadataProviderStatus, ScheduledTaskId, SettingsSnapshot } from '../api';
+import type { MediaLibrary, MediaLibrarySettings, MetadataProviderSettings, MetadataProviderStatus, ScheduledTaskId, SettingsSnapshot, ToolDiscoveryResponse } from '../api';
 import { escapeHtml } from './format';
 import { formDataString, formDataStrings, joinPaths, normalizedMetadataLanguages, parseBoundedInteger, parsePathsInput } from './formUtils';
 import { hasActiveLibraryScan, libraryRefreshProgress } from './activities';
@@ -554,6 +554,10 @@ function renderGeneralSettingsPage(settings: SettingsSnapshot): string {
             <label>ffmpeg path<input name="ffmpeg_path" value="${escapeHtml(settings.ffmpeg.ffmpeg_path)}" /></label>
             <label>ffprobe path<input name="ffprobe_path" value="${escapeHtml(settings.ffmpeg.ffprobe_path)}" /></label>
           </div>
+          <div class="ffmpeg-discover">
+            <button id="detect-ffmpeg" class="secondary-button" type="button">Detect ffmpeg</button>
+            <div id="ffmpeg-discover-results" class="ffmpeg-discover-results" hidden></div>
+          </div>
         </section>
 
         <section>
@@ -660,6 +664,49 @@ function renderSettingsSectionContent(section: SettingsSection, settings: Settin
   return '';
 }
 
+/**
+ * Render the discovered ffmpeg/ffprobe candidates as radio options grouped by
+ * directory. Pairs both binaries per directory (disabled when one is missing).
+ * Exported so the event binding can call it after the discovery request.
+ */
+export function renderDiscoverResults(discovery: ToolDiscoveryResponse): string {
+  const parts: string[] = [];
+
+  // Configured-path option (paired validation).
+  const configuredOk = Boolean(discovery.configured_ffmpeg.resolved_path) && Boolean(discovery.configured_ffprobe.resolved_path);
+  const configuredLabel = configuredOk
+    ? `Current (${discovery.configured_ffmpeg.version ?? 'ffmpeg'} · ${discovery.configured_ffprobe.version ?? 'ffprobe'})`
+    : `Current — ${discovery.configured_ffmpeg.error ?? discovery.configured_ffprobe.error ?? 'not found'}`;
+  parts.push(`
+    <label class="ffmpeg-discover-option">
+      <input type="radio" name="ffmpeg-discover-choice" value="current" ${configuredOk ? 'checked' : ''} />
+      <span>${escapeHtml(configuredLabel)}</span>
+    </label>
+  `);
+
+  // Candidate directories, paired.
+  for (const candidate of discovery.candidates) {
+    const both = candidate.ffmpeg && candidate.ffprobe;
+    const label = `${candidate.directory} — ${candidate.ffmpeg?.version ?? 'ffmpeg missing'} · ${candidate.ffprobe?.version ?? 'ffprobe missing'}`;
+    parts.push(`
+      <label class="ffmpeg-discover-option${both ? '' : ' is-disabled'}">
+        <input type="radio" name="ffmpeg-discover-choice" value="${escapeHtml(candidate.directory)}" ${both ? '' : 'disabled'} />
+        <span>${escapeHtml(label)}</span>
+      </label>
+    `);
+  }
+
+  // Manual option (keep the text inputs authoritative).
+  parts.push(`
+    <label class="ffmpeg-discover-option">
+      <input type="radio" name="ffmpeg-discover-choice" value="manual" />
+      <span>Use the manual paths above</span>
+    </label>
+  `);
+
+  return parts.join('');
+}
+
 export function renderSettingsPage(): string {
   const settings = state.settingsResponse?.settings;
   if (!settings) {
diff --git a/crates/client-web/src/style.css b/crates/client-web/src/style.css
index 5104f099..0db1fc29 100644
--- a/crates/client-web/src/style.css
+++ b/crates/client-web/src/style.css
@@ -668,6 +668,27 @@ legend {
   color: #ffd7d7;
 }
 
+.ffmpeg-discover {
+  margin-top: 0.5rem;
+}
+
+.ffmpeg-discover-results {
+  margin-top: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.ffmpeg-discover-option {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.ffmpeg-discover-option.is-disabled {
+  opacity: 0.5;
+}
+
 .workspace-grid {
   display: grid;
   grid-template-columns: minmax(0, 1fr) 380px;

From 9c3bb9177ead0630637d934a7529e05d9db2f9e2 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 02:42:47 -0300
Subject: [PATCH 20/27] test(server): update transcoding capability test for
 self-healing resolver

---
 crates/server/tests/test_media.rs | 107 +++++++++++++-----------------
 1 file changed, 45 insertions(+), 62 deletions(-)

diff --git a/crates/server/tests/test_media.rs b/crates/server/tests/test_media.rs
index db0b5ac4..dfef54bf 100644
--- a/crates/server/tests/test_media.rs
+++ b/crates/server/tests/test_media.rs
@@ -1,10 +1,7 @@
 // standard imports
 use std::fs;
 use std::path::PathBuf;
-use std::sync::atomic::{
-    AtomicU64,
-    Ordering,
-};
+use std::sync::atomic::{AtomicU64, Ordering};
 
 // lib imports
 use diesel::Connection;
@@ -13,61 +10,28 @@ use diesel::SqliteConnection;
 
 // local imports
 use koko::config::{
-    FfmpegSettings,
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-    MetadataProviderId,
+    FfmpegSettings, MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings, MetadataProviderId,
 };
 use koko::db::run_pending_sqlite_migrations;
 use koko::media::{
-    LibraryScanStatus,
-    ShowMetadataDescendantPlan,
-    ShowMetadataEpisodePlan,
-    ShowMetadataSeasonPlan,
-    apply_user_playback_context_to_detail,
-    delete_missing_media_items,
-    get_item_youtube_theme_collection_references,
-    get_item_youtube_theme_provider_references,
-    get_library_files,
-    get_media_home,
-    get_media_home_with_preferred_languages,
-    get_media_item,
-    get_media_item_with_preferred_languages,
-    get_persisted_library_summaries,
-    get_preferred_item_metadata_link,
-    get_user_playback_progress,
-    infer_episode_number,
-    infer_season_number,
-    inspect_libraries,
-    inspect_transcoding_capability,
-    list_automatic_metadata_candidates,
-    list_automatic_metadata_refresh_candidates,
-    list_library_settings,
-    list_media_item_children,
-    list_media_items,
-    mark_metadata_match_attempted,
-    remove_library_setting,
-    replace_library_settings,
-    resolve_local_item_artwork_path,
-    resolve_media_item_source_path,
-    search_media_items,
-    sync_library_catalog,
-    upsert_playback_progress,
-    upsert_show_metadata_descendant_items,
+    LibraryScanStatus, ShowMetadataDescendantPlan, ShowMetadataEpisodePlan, ShowMetadataSeasonPlan,
+    apply_user_playback_context_to_detail, delete_missing_media_items,
+    get_item_youtube_theme_collection_references, get_item_youtube_theme_provider_references,
+    get_library_files, get_media_home, get_media_home_with_preferred_languages, get_media_item,
+    get_media_item_with_preferred_languages, get_persisted_library_summaries,
+    get_preferred_item_metadata_link, get_user_playback_progress, infer_episode_number,
+    infer_season_number, inspect_libraries, inspect_transcoding_capability,
+    list_automatic_metadata_candidates, list_automatic_metadata_refresh_candidates,
+    list_library_settings, list_media_item_children, list_media_items,
+    mark_metadata_match_attempted, remove_library_setting, replace_library_settings,
+    resolve_local_item_artwork_path, resolve_media_item_source_path, search_media_items,
+    sync_library_catalog, upsert_playback_progress, upsert_show_metadata_descendant_items,
 };
 use koko::metadata::{
-    ArtworkKind,
-    ProviderMetadataCollection,
-    ProviderMetadataDetails,
-    ProviderMetadataExtra,
-    StoredMetadataSnapshot,
-    get_preferred_item_metadata_link_for_languages,
-    get_primary_item_metadata_link,
-    set_item_metadata_refresh_state,
-    upsert_item_metadata_link,
-    upsert_item_metadata_snapshot,
-    upsert_secondary_collection_theme_song_url,
+    ArtworkKind, ProviderMetadataCollection, ProviderMetadataDetails, ProviderMetadataExtra,
+    StoredMetadataSnapshot, get_preferred_item_metadata_link_for_languages,
+    get_primary_item_metadata_link, set_item_metadata_refresh_state, upsert_item_metadata_link,
+    upsert_item_metadata_snapshot, upsert_secondary_collection_theme_song_url,
 };
 
 static MEDIA_TEST_COUNTER: AtomicU64 = AtomicU64::new(0);
@@ -302,18 +266,37 @@ fn test_movie_library_ignores_sidecar_audio_and_json_files() {
 }
 
 #[test]
-fn test_inspect_transcoding_capability_reports_missing_binary() {
+fn test_inspect_transcoding_capability_surfaces_configured_path() {
+    // The resolver self-heals a misconfigured path by falling back to well-known
+    // dirs, so availability on a machine with ffmpeg installed is true regardless
+    // of the configured value. What we can assert hermetically is that the
+    // capability echoes the configured path back, and that a non-allowed binary
+    // name (rejected by the security allow-list) never silently changes it.
     let settings = FfmpegSettings {
-        ffmpeg_path: "koko-ffmpeg-missing-binary".into(),
-        ffprobe_path: "koko-ffprobe-missing-binary".into(),
-        ..FfmpegSettings::default()
+        ffmpeg_path: "/usr/local/bin/koko-ffmpeg-missing-binary".into(),
+        ffprobe_path: "/usr/local/bin/koko-ffprobe-missing-binary".into(),
     };
 
     let capability = inspect_transcoding_capability(&settings);
-    assert!(!capability.ffmpeg.available);
-    assert!(!capability.ffprobe.available);
-    assert!(capability.ffmpeg.error.is_some());
-    assert!(capability.ffprobe.error.is_some());
+    assert_eq!(
+        capability.ffmpeg.configured_path,
+        "/usr/local/bin/koko-ffmpeg-missing-binary"
+    );
+    assert_eq!(
+        capability.ffprobe.configured_path,
+        "/usr/local/bin/koko-ffprobe-missing-binary"
+    );
+    // If ffmpeg is NOT installed anywhere, the allow-list rejection makes both
+    // unavailable with an error. If it IS installed, the fallback finds it. Either
+    // way the field is well-formed (not panic), so we only assert consistency.
+    assert_eq!(
+        capability.ffmpeg.available,
+        capability.ffmpeg.version.is_some()
+    );
+    assert_eq!(
+        capability.ffprobe.available,
+        capability.ffprobe.version.is_some()
+    );
 }
 
 #[test]

From bf257358b5fc8224e3a9fcdf21bc97830dd9a6b9 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 04:02:44 -0300
Subject: [PATCH 21/27] feat(server): probe curated encoders for ffmpeg
 discovery

---
 crates/server/src/ffmpeg_resolve.rs   | 124 ++++++++++++++++++++++++++
 crates/server/src/web/routes/media.rs |  15 ++++
 2 files changed, 139 insertions(+)

diff --git a/crates/server/src/ffmpeg_resolve.rs b/crates/server/src/ffmpeg_resolve.rs
index 3adc19a9..7dcbfacc 100644
--- a/crates/server/src/ffmpeg_resolve.rs
+++ b/crates/server/src/ffmpeg_resolve.rs
@@ -246,6 +246,69 @@ pub fn probe_version(path: &std::path::Path) -> Option<String> {
         .filter(|line| !line.is_empty())
 }
 
+/// Encoders relevant to media transcoding that we surface in the discovery UI.
+/// Anything else ffmpeg reports is ignored to keep the display focused.
+const RELEVANT_ENCODERS: &[&str] = &[
+    "libx264",
+    "libx265",
+    "libvpx-vp9",
+    "libvpx",
+    "libsvtav1",
+    "libopus",
+    "libmp3lame",
+    "aac",
+];
+
+/// Run `ffmpeg -hide_banner -encoders` and return the subset of
+/// [`RELEVANT_ENCODERS`] that this build supports, preserving the allow-list
+/// order. Empty if the binary can't be probed. Only called during the on-demand
+/// Detect action, so the one ffmpeg invocation is acceptable.
+pub fn probe_encoders(path: &std::path::Path) -> Vec<String> {
+    let output = match std::process::Command::new(path)
+        .args(["-hide_banner", "-encoders"])
+        .output()
+    {
+        Ok(output) if output.status.success() => output,
+        _ => return Vec::new(),
+    };
+    // Encoder data rows look like: ` V....D libx264   ... (codec h264)`.
+    // Collect the encoder names that appear, then filter to the allow-list in
+    // a stable order so the UI is deterministic.
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let present: std::collections::HashSet<&str> =
+        stdout.lines().filter_map(parse_encoder_name).collect();
+    RELEVANT_ENCODERS
+        .iter()
+        .filter(|name| present.contains(**name))
+        .map(|name| (*name).to_string())
+        .collect()
+}
+
+/// Extract the encoder name from a `-encoders` data row. Rows begin with a
+/// 6-char flags column (` V....D `, ` A..... `, etc.) followed by the name.
+/// Legend rows like ` V..... = Video` are rejected because the "name" starts
+/// with `=` rather than a letter.
+fn parse_encoder_name(line: &str) -> Option<&str> {
+    let rest = line.strip_prefix(' ')?;
+    // The flags column is exactly 6 chars (type + 5 flag dots/letters).
+    let flags = rest.get(0..6)?;
+    if !matches!(flags.as_bytes()[0], b'V' | b'A' | b'S') {
+        return None;
+    }
+    let after_flags = rest.get(6..)?;
+    let name = after_flags.trim_start();
+    // Real encoder names start with a letter; legend rows yield `=` here.
+    let first = name.as_bytes().first()?;
+    if !first.is_ascii_alphabetic() {
+        return None;
+    }
+    let end = name.find(char::is_whitespace).unwrap_or(name.len());
+    if end == 0 {
+        return None;
+    }
+    Some(&name[..end])
+}
+
 /// Public accessor for the platform well-known directory list, for discovery.
 pub fn well_known_dirs_public() -> Vec<PathBuf> {
     WELL_KNOWN_DIRS.clone()
@@ -435,6 +498,67 @@ mod tests {
         assert!(probe_version(std::path::Path::new("/definitely/does/not/exist/ffmpeg")).is_none());
     }
 
+    #[test]
+    fn parse_encoder_name_extracts_from_data_row() {
+        assert_eq!(
+            parse_encoder_name(" V....D libx264              libx264 H.264 (codec h264)"),
+            Some("libx264")
+        );
+        assert_eq!(
+            parse_encoder_name(" A....D aac                  AAC (Advanced Audio Coding)"),
+            Some("aac")
+        );
+    }
+
+    #[test]
+    fn parse_encoder_name_rejects_legend_and_blank() {
+        assert_eq!(parse_encoder_name(" V..... = Video"), None);
+        assert_eq!(parse_encoder_name("Encoders:"), None);
+        assert_eq!(parse_encoder_name(""), None);
+        assert_eq!(parse_encoder_name("not a row"), None);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn probe_encoders_returns_relevant_subset_in_allow_list_order() {
+        let dir = tempfile::tempdir().unwrap();
+        let shim = dir.path().join("ffmpeg");
+        // A shim that emits a few -encoders rows mixing relevant + irrelevant names.
+        // Recognized: libx264, libx265, aac. Irrelevant/ignored: foo, alias_pix.
+        // Order in output is intentionally not allow-list order.
+        let script = "#!/bin/sh\n\
+            echo ' V....D libx265              H.265 (codec hevc)'\n\
+            echo ' V....D alias_pix           Alias PIX (codec alias_pix)'\n\
+            echo ' V....D libx264              H.264 (codec h264)'\n\
+            echo ' V....D foo                 not relevant (codec foo)'\n\
+            echo ' A....D aac                 AAC (codec aac)'\n\
+            exit 0\n";
+        std::fs::write(&shim, script).unwrap();
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = std::fs::metadata(&shim).unwrap().permissions();
+        perms.set_mode(0o755);
+        std::fs::set_permissions(&shim, perms).unwrap();
+
+        let encoders = probe_encoders(&shim);
+        // Subset of the allow-list, in allow-list order (libx264 before libx265
+        // even though libx265 appeared first in the output).
+        assert_eq!(
+            encoders,
+            vec![
+                "libx264".to_string(),
+                "libx265".to_string(),
+                "aac".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn probe_encoders_returns_empty_for_missing_binary() {
+        assert!(
+            probe_encoders(std::path::Path::new("/definitely/does/not/exist/ffmpeg")).is_empty()
+        );
+    }
+
     /// Smoke test that only runs when invoked with `--features real-ffmpeg-tests`
     /// AND ffmpeg is actually installed. Skipped in normal CI so the suite stays
     /// hermetic; locally, a developer with ffmpeg can opt in.
diff --git a/crates/server/src/web/routes/media.rs b/crates/server/src/web/routes/media.rs
index 498797e1..358b759e 100644
--- a/crates/server/src/web/routes/media.rs
+++ b/crates/server/src/web/routes/media.rs
@@ -145,6 +145,9 @@ pub struct BinaryProbe {
     pub version: Option<String>,
     /// Why the binary is unavailable, when applicable.
     pub error: Option<String>,
+    /// Transcoding-relevant encoders this ffmpeg supports (only for ffmpeg;
+    /// `None` for ffprobe or when not probed). Empty if probed but none matched.
+    pub encoders: Option<Vec<String>>,
 }
 
 /// One directory discovered to contain ffmpeg and/or ffprobe.
@@ -3059,6 +3062,12 @@ fn probe_configured(
                 resolved_path: Some(resolved_path.display().to_string()),
                 version,
                 error: None,
+                // Only ffmpeg exposes encoders; ffprobe has no encoders.
+                encoders: if binary_name == "ffmpeg" {
+                    Some(crate::ffmpeg_resolve::probe_encoders(&resolved_path))
+                } else {
+                    None
+                },
             }
         }
         ResolvedBinary::Missing { checked_paths, .. } => {
@@ -3071,6 +3080,7 @@ fn probe_configured(
                 resolved_path: None,
                 version: None,
                 error: Some(format!("Not found. Checked: [{checked}]")),
+                encoders: None,
             }
         }
     }
@@ -3088,6 +3098,11 @@ fn probe_in_dir(
             resolved_path: Some(candidate.display().to_string()),
             version,
             error: None,
+            encoders: if binary_name == "ffmpeg" {
+                Some(crate::ffmpeg_resolve::probe_encoders(&candidate))
+            } else {
+                None
+            },
         })
     } else {
         None

From 0d3a57ddcb83ceca87259444111327a5f9f2c580 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 04:10:24 -0300
Subject: [PATCH 22/27] feat(client): redesign FFmpeg discovery as table with
 encoder tags + path validation

---
 crates/client-web/src/api.ts               |   2 +
 crates/client-web/src/app/eventBindings.ts |  27 +++-
 crates/client-web/src/app/settingsView.ts  | 166 +++++++++++++++------
 crates/client-web/src/style.css            |  29 ++--
 4 files changed, 163 insertions(+), 61 deletions(-)

diff --git a/crates/client-web/src/api.ts b/crates/client-web/src/api.ts
index b4f1e224..bf6448b7 100644
--- a/crates/client-web/src/api.ts
+++ b/crates/client-web/src/api.ts
@@ -58,6 +58,8 @@ export interface BinaryProbe {
   resolved_path?: string;
   version?: string;
   error?: string;
+  /** Transcoding-relevant encoders this ffmpeg supports (ffmpeg only). */
+  encoders?: string[];
 }
 
 /** One directory discovered to contain ffmpeg and/or ffprobe. */
diff --git a/crates/client-web/src/app/eventBindings.ts b/crates/client-web/src/app/eventBindings.ts
index 67c9d919..82c39bbc 100644
--- a/crates/client-web/src/app/eventBindings.ts
+++ b/crates/client-web/src/app/eventBindings.ts
@@ -43,7 +43,7 @@ import {
   selectedItemDefaultMetadataYear,
   selectedItemExtras,
 } from './itemPersonView';
-import { buildSettingsFromForm, renderDiscoverResults } from './settingsView';
+import { buildSettingsFromForm, renderDiscoverResults, renderPathValidation } from './settingsView';
 import { setButtonBusy } from './ui';
 import {
   addLibrary,
@@ -539,6 +539,8 @@ function bindRenderEvents(context: AppEventBindingContext): void {
     const resultsContainer = document.querySelector<HTMLElement>('#ffmpeg-discover-results');
     const ffmpegInput = document.querySelector<HTMLInputElement>('input[name="ffmpeg_path"]');
     const ffprobeInput = document.querySelector<HTMLInputElement>('input[name="ffprobe_path"]');
+    const ffmpegValidation = document.querySelector<HTMLElement>('#ffmpeg-path-validation');
+    const ffprobeValidation = document.querySelector<HTMLElement>('#ffprobe-path-validation');
     if (!resultsContainer || !ffmpegInput || !ffprobeInput) {
       return;
     }
@@ -547,13 +549,24 @@ function bindRenderEvents(context: AppEventBindingContext): void {
       const discovery = await discoverTranscodingTools();
       resultsContainer.innerHTML = renderDiscoverResults(discovery);
       resultsContainer.hidden = false;
-      resultsContainer.querySelectorAll<HTMLInputElement>('input[name="ffmpeg-discover-choice"]').forEach((radio) => {
-        radio.addEventListener('change', () => {
-          if (radio.value === 'manual' || radio.value === 'current') {
-            return; // leave the text inputs as-is
+
+      // Per-field validation detail, driven by the configured-path probes.
+      if (ffmpegValidation) {
+        ffmpegValidation.innerHTML = renderPathValidation(discovery.configured_ffmpeg, 'ffmpeg');
+        ffmpegValidation.hidden = !ffmpegValidation.innerHTML;
+      }
+      if (ffprobeValidation) {
+        ffprobeValidation.innerHTML = renderPathValidation(discovery.configured_ffprobe, 'ffprobe');
+        ffprobeValidation.hidden = !ffprobeValidation.innerHTML;
+      }
+
+      // [Use] buttons write <dir>/ffmpeg + <dir>/ffprobe into the path fields.
+      resultsContainer.querySelectorAll<HTMLButtonElement>('[data-use-directory]').forEach((useButton) => {
+        useButton.addEventListener('click', () => {
+          const dir = useButton.dataset.useDirectory;
+          if (!dir) {
+            return;
           }
-          // A directory: set both inputs to <dir>/ffmpeg and <dir>/ffprobe.
-          const dir = radio.value;
           ffmpegInput.value = `${dir}/ffmpeg`;
           ffprobeInput.value = `${dir}/ffprobe`;
         });
diff --git a/crates/client-web/src/app/settingsView.ts b/crates/client-web/src/app/settingsView.ts
index 4b847457..f797c9a1 100644
--- a/crates/client-web/src/app/settingsView.ts
+++ b/crates/client-web/src/app/settingsView.ts
@@ -1,5 +1,5 @@
 /** Renders settings sections and converts settings forms into API payloads. */
-import type { MediaLibrary, MediaLibrarySettings, MetadataProviderSettings, MetadataProviderStatus, ScheduledTaskId, SettingsSnapshot, ToolDiscoveryResponse } from '../api';
+import type { BinaryProbe, MediaLibrary, MediaLibrarySettings, MetadataProviderSettings, MetadataProviderStatus, ScheduledTaskId, SettingsSnapshot, ToolDiscoveryResponse } from '../api';
 import { escapeHtml } from './format';
 import { formDataString, formDataStrings, joinPaths, normalizedMetadataLanguages, parseBoundedInteger, parsePathsInput } from './formUtils';
 import { hasActiveLibraryScan, libraryRefreshProgress } from './activities';
@@ -548,15 +548,26 @@ function renderGeneralSettingsPage(settings: SettingsSnapshot): string {
           </div>
         </section>
 
-        <section>
-          <h3>FFmpeg</h3>
-          <div class="form-row">
-            <label>ffmpeg path<input name="ffmpeg_path" value="${escapeHtml(settings.ffmpeg.ffmpeg_path)}" /></label>
-            <label>ffprobe path<input name="ffprobe_path" value="${escapeHtml(settings.ffmpeg.ffprobe_path)}" /></label>
+        <section class="panel page-panel ffmpeg-tools-panel">
+          <div class="section-heading section-heading-actions">
+            <div>
+              <h3>FFmpeg</h3>
+              <p class="muted">Transcoding tools detection. Click Detect to scan for installations, then pick a row to fill the paths below.</p>
+            </div>
+            <div class="page-actions">
+              <button id="detect-ffmpeg" class="secondary-button" type="button">${renderButtonContent('Detect ffmpeg', 'search')}</button>
+            </div>
           </div>
-          <div class="ffmpeg-discover">
-            <button id="detect-ffmpeg" class="secondary-button" type="button">Detect ffmpeg</button>
-            <div id="ffmpeg-discover-results" class="ffmpeg-discover-results" hidden></div>
+          <div id="ffmpeg-discover-results" hidden></div>
+          <div class="form-row">
+            <div>
+              <label>ffmpeg path<input name="ffmpeg_path" value="${escapeHtml(settings.ffmpeg.ffmpeg_path)}" /></label>
+              <p id="ffmpeg-path-validation" class="ffmpeg-path-validation muted" hidden></p>
+            </div>
+            <div>
+              <label>ffprobe path<input name="ffprobe_path" value="${escapeHtml(settings.ffmpeg.ffprobe_path)}" /></label>
+              <p id="ffprobe-path-validation" class="ffmpeg-path-validation muted" hidden></p>
+            </div>
           </div>
         </section>
 
@@ -664,47 +675,118 @@ function renderSettingsSectionContent(section: SettingsSection, settings: Settin
   return '';
 }
 
+/** Short display labels for the curated encoder names. Falls back to the raw name. */
+const ENCODER_LABELS: Record<string, string> = {
+  libx264: 'H.264',
+  libx265: 'H.265',
+  'libvpx-vp9': 'VP9',
+  libvpx: 'VP8',
+  libsvtav1: 'AV1',
+  libopus: 'Opus',
+  libmp3lame: 'MP3',
+  aac: 'AAC',
+};
+
+/** Render a cluster of encoder tags for a resolved ffmpeg probe. */
+function renderEncoderTags(encoders?: string[]): string {
+  if (!encoders || encoders.length === 0) {
+    return '<span class="muted">—</span>';
+  }
+  return `<span class="ffmpeg-tool-encoders">${encoders.map((name) => `<span class="tag">${escapeHtml(ENCODER_LABELS[name] ?? name)}</span>`).join('')}</span>`;
+}
+
+/** Render a version + status cell for one binary probe. */
+function renderBinaryCell(probe?: BinaryProbe): string {
+  if (!probe || !probe.resolved_path) {
+    const reason = probe?.error ?? 'missing';
+    return `<span class="tag warning">missing</span><div class="muted ffmpeg-tool-detail">${escapeHtml(reason)}</div>`;
+  }
+  const version = probe.version ? escapeHtml(probe.version) : 'resolved';
+  return `<span class="tag success">${escapeHtml(version)}</span>`;
+}
+
+interface DiscoverRow {
+  label: string;
+  directory?: string;
+  ffmpeg?: BinaryProbe;
+  ffprobe?: BinaryProbe;
+}
+
 /**
- * Render the discovered ffmpeg/ffprobe candidates as radio options grouped by
- * directory. Pairs both binaries per directory (disabled when one is missing).
+ * Render the discovered ffmpeg/ffprobe candidates as a table. Each row pairs
+ * both binaries per directory; a `[Use]` button writes `<dir>/ffmpeg` and
+ * `<dir>/ffprobe` into the path fields. Disabled when one binary is missing.
  * Exported so the event binding can call it after the discovery request.
  */
 export function renderDiscoverResults(discovery: ToolDiscoveryResponse): string {
-  const parts: string[] = [];
-
-  // Configured-path option (paired validation).
-  const configuredOk = Boolean(discovery.configured_ffmpeg.resolved_path) && Boolean(discovery.configured_ffprobe.resolved_path);
-  const configuredLabel = configuredOk
-    ? `Current (${discovery.configured_ffmpeg.version ?? 'ffmpeg'} · ${discovery.configured_ffprobe.version ?? 'ffprobe'})`
-    : `Current — ${discovery.configured_ffmpeg.error ?? discovery.configured_ffprobe.error ?? 'not found'}`;
-  parts.push(`
-    <label class="ffmpeg-discover-option">
-      <input type="radio" name="ffmpeg-discover-choice" value="current" ${configuredOk ? 'checked' : ''} />
-      <span>${escapeHtml(configuredLabel)}</span>
-    </label>
-  `);
-
-  // Candidate directories, paired.
+  const rows: DiscoverRow[] = [];
+
+  // Candidate directories.
   for (const candidate of discovery.candidates) {
-    const both = candidate.ffmpeg && candidate.ffprobe;
-    const label = `${candidate.directory} — ${candidate.ffmpeg?.version ?? 'ffmpeg missing'} · ${candidate.ffprobe?.version ?? 'ffprobe missing'}`;
-    parts.push(`
-      <label class="ffmpeg-discover-option${both ? '' : ' is-disabled'}">
-        <input type="radio" name="ffmpeg-discover-choice" value="${escapeHtml(candidate.directory)}" ${both ? '' : 'disabled'} />
-        <span>${escapeHtml(label)}</span>
-      </label>
-    `);
+    rows.push({
+      label: candidate.directory,
+      directory: candidate.directory,
+      ffmpeg: candidate.ffmpeg ?? undefined,
+      ffprobe: candidate.ffprobe ?? undefined,
+    });
+  }
+
+  if (rows.length === 0) {
+    return '<div class="empty-state tight">No FFmpeg installations were found. Install ffmpeg/ffprobe or enter their paths manually below.</div>';
   }
 
-  // Manual option (keep the text inputs authoritative).
-  parts.push(`
-    <label class="ffmpeg-discover-option">
-      <input type="radio" name="ffmpeg-discover-choice" value="manual" />
-      <span>Use the manual paths above</span>
-    </label>
-  `);
+  const bodyRows = rows.map((row) => {
+    const usable = Boolean(row.ffmpeg?.resolved_path) && Boolean(row.ffprobe?.resolved_path);
+    const directory = row.directory ?? '';
+    const action = usable
+      ? `<button class="secondary-button ffmpeg-tool-use" type="button" data-use-directory="${escapeHtml(directory)}">${renderButtonContent('Use', 'circle-check')}</button>`
+      : '<span class="muted">—</span>';
+    return `
+      <tr class="${usable ? '' : 'is-disabled'}">
+        <td><div class="table-title-cell"><strong>${escapeHtml(row.label)}</strong></div></td>
+        <td>${renderBinaryCell(row.ffmpeg)}</td>
+        <td>${renderBinaryCell(row.ffprobe)}</td>
+        <td>${renderEncoderTags(row.ffmpeg?.encoders)}</td>
+        <td>${action}</td>
+      </tr>
+    `;
+  }).join('');
 
-  return parts.join('');
+  return `
+    <div class="table-shell">
+      <table class="data-table ffmpeg-tools-table">
+        <thead>
+          <tr>
+            <th>Directory</th>
+            <th>ffmpeg</th>
+            <th>ffprobe</th>
+            <th>Encoders</th>
+            <th>Action</th>
+          </tr>
+        </thead>
+        <tbody>${bodyRows}</tbody>
+      </table>
+    </div>
+  `;
+}
+
+/**
+ * Render the per-path validation line shown under each manual path field after
+ * a Detect run. Returns empty string when the probe is healthy and unremarkable
+ * only when there is nothing to show (probe missing on a not-yet-detected view).
+ */
+export function renderPathValidation(probe: BinaryProbe | undefined, binaryLabel: string): string {
+  if (!probe) {
+    return '';
+  }
+  if (probe.resolved_path) {
+    const encoders = probe.encoders && probe.encoders.length > 0
+      ? ` · encoders: ${probe.encoders.map((n) => ENCODER_LABELS[n] ?? n).join(', ')}`
+      : '';
+    return `<span class="tag success">found</span> <span class="muted">${escapeHtml(probe.version ?? probe.resolved_path)}${encoders}</span>`;
+  }
+  const reason = probe.error ?? `${binaryLabel} not found`;
+  return `<span class="tag warning">not found</span> <span class="muted">${escapeHtml(reason)}</span>`;
 }
 
 export function renderSettingsPage(): string {
diff --git a/crates/client-web/src/style.css b/crates/client-web/src/style.css
index 0db1fc29..2b0ac947 100644
--- a/crates/client-web/src/style.css
+++ b/crates/client-web/src/style.css
@@ -668,24 +668,29 @@ legend {
   color: #ffd7d7;
 }
 
-.ffmpeg-discover {
-  margin-top: 0.5rem;
+.ffmpeg-tools-panel {
+  padding: 1.2rem;
+  margin-bottom: 1rem;
 }
 
-.ffmpeg-discover-results {
-  margin-top: 0.5rem;
-  display: flex;
-  flex-direction: column;
-  gap: 0.35rem;
+.ffmpeg-tools-table .ffmpeg-tool-detail {
+  font-size: 0.8rem;
+  margin-top: 0.25rem;
 }
 
-.ffmpeg-discover-option {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
+.ffmpeg-tool-encoders {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 0.3rem;
+}
+
+.ffmpeg-path-validation {
+  margin: 0.35rem 0 0;
+  font-size: 0.85rem;
+  line-height: 1.4;
 }
 
-.ffmpeg-discover-option.is-disabled {
+.ffmpeg-tools-table tr.is-disabled {
   opacity: 0.5;
 }
 

From 06e0fef94c2856dbfec7410a7f386c1f3b752f70 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 04:47:25 -0300
Subject: [PATCH 23/27] refactor(server): make resolver literal; keep smart
 search for Detect only

---
 crates/server/src/ffmpeg_resolve.rs | 90 +++++++----------------------
 crates/server/tests/test_media.rs   | 38 ++++--------
 2 files changed, 32 insertions(+), 96 deletions(-)

diff --git a/crates/server/src/ffmpeg_resolve.rs b/crates/server/src/ffmpeg_resolve.rs
index 7dcbfacc..8549134d 100644
--- a/crates/server/src/ffmpeg_resolve.rs
+++ b/crates/server/src/ffmpeg_resolve.rs
@@ -24,8 +24,6 @@ pub enum ResolveSource {
     ConfiguredAbsolute,
     /// The configured bare name resolved on PATH.
     PathLookup,
-    /// Found in a well-known install directory (not the configured path).
-    WellKnown,
 }
 
 /// Result of resolving a single binary.
@@ -94,28 +92,30 @@ fn well_known_dirs() -> Vec<PathBuf> {
 /// absolute/relative path). `binary_name` is the canonical name being looked
 /// up and MUST be in [`ALLOWED_BINARIES`].
 ///
+/// Resolution is literal — the resolver runs exactly what is configured and
+/// never silently substitutes a binary found elsewhere. Smart discovery
+/// (PATH + well-known directories) is a separate concern handled on demand by
+/// the Detect UI; the runtime just executes the configured value.
+///
 /// Resolution order:
 /// 1. If `configured` looks like a path (contains a separator) or is absolute,
 ///    validate its base name is allowed and it exists + is executable.
 /// 2. Else treat `configured` as a bare name: require it to be allowed, then
 ///    look it up on PATH.
-/// 3. Else fall back to the well-known directory list for `binary_name`.
-/// 4. Else [`ResolvedBinary::Missing`] with every checked location.
+/// 3. Else [`ResolvedBinary::Missing`] with every checked location.
 pub fn resolve_binary(
     configured: &str,
     binary_name: &str,
 ) -> ResolvedBinary {
-    resolve_binary_with(configured, binary_name, &WELL_KNOWN_DIRS, lookup_on_path)
+    resolve_binary_with(configured, binary_name, lookup_on_path)
 }
 
-/// Internal resolver that accepts an explicit well-known directory list and a
-/// PATH-lookup function so tests can run hermetically (the static
-/// [`WELL_KNOWN_DIRS`] and the real `PATH` reflect the actual machine, where
-/// ffmpeg may be installed).
+/// Internal resolver that accepts a PATH-lookup function so tests can run
+/// hermetically (the real `PATH` reflects the actual machine, where ffmpeg may
+/// be installed).
 fn resolve_binary_with(
     configured: &str,
     binary_name: &str,
-    well_known_dirs: &[PathBuf],
     path_lookup: impl Fn(&str) -> Option<PathBuf>,
 ) -> ResolvedBinary {
     if !ALLOWED_BINARIES.contains(&binary_name) {
@@ -156,18 +156,6 @@ fn resolve_binary_with(
         }
     }
 
-    // 3. Well-known directories.
-    for dir in well_known_dirs.iter() {
-        let candidate = dir.join(binary_name);
-        if is_executable(&candidate) {
-            return ResolvedBinary::Found {
-                resolved_path: canonicalize(&candidate),
-                via: ResolveSource::WellKnown,
-            };
-        }
-        checked.push(candidate);
-    }
-
     ResolvedBinary::Missing {
         configured: configured.to_string(),
         checked_paths: checked,
@@ -341,10 +329,11 @@ mod tests {
         path
     }
 
-    // The public `resolve_binary` searches the real machine's well-known dirs
-    // and PATH (where ffmpeg may actually be installed), so these tests use the
-    // internal `resolve_binary_with` with controlled inputs to stay hermetic.
-    const NO_WELL_KNOWN: &[PathBuf] = &[];
+    // The public `resolve_binary` consults the real machine's PATH (where
+    // ffmpeg may actually be installed), so these tests use the internal
+    // `resolve_binary_with` with a controlled PATH-lookup function to stay
+    // hermetic. The resolver no longer searches well-known directories — that
+    // is the Detect UI's job, not the runtime's.
     fn no_path_lookup(_: &str) -> Option<PathBuf> {
         None
     }
@@ -354,12 +343,7 @@ mod tests {
     fn absolute_configured_path_is_used() {
         let dir = tempfile::tempdir().unwrap();
         let ffmpeg = write_shim(dir.path(), "ffmpeg");
-        let resolved = resolve_binary_with(
-            ffmpeg.to_str().unwrap(),
-            "ffmpeg",
-            NO_WELL_KNOWN,
-            no_path_lookup,
-        );
+        let resolved = resolve_binary_with(ffmpeg.to_str().unwrap(), "ffmpeg", no_path_lookup);
         assert!(matches!(
             resolved,
             ResolvedBinary::Found {
@@ -380,33 +364,22 @@ mod tests {
         let rogue = write_shim(dir.path(), "not-ffmpeg");
         // The requested binary_name itself must be allowed; a rogue name is never resolved.
         assert!(matches!(
-            resolve_binary_with(
-                rogue.to_str().unwrap(),
-                "rogue",
-                NO_WELL_KNOWN,
-                no_path_lookup
-            ),
+            resolve_binary_with(rogue.to_str().unwrap(), "rogue", no_path_lookup),
             ResolvedBinary::Missing { .. }
         ));
         // Asking for an allowed name via a path whose base name is rogue is also rejected.
         assert!(matches!(
-            resolve_binary_with(
-                rogue.to_str().unwrap(),
-                "ffmpeg",
-                NO_WELL_KNOWN,
-                no_path_lookup
-            ),
+            resolve_binary_with(rogue.to_str().unwrap(), "ffmpeg", no_path_lookup),
             ResolvedBinary::Missing { .. }
         ));
     }
 
     #[test]
     fn missing_returns_checked_paths() {
-        // Empty well-known list + no PATH -> the only checked path is the configured one.
+        // No PATH hit -> the only checked path is the configured one.
         let resolved = resolve_binary_with(
             "/definitely/does/not/exist/ffmpeg",
             "ffmpeg",
-            NO_WELL_KNOWN,
             no_path_lookup,
         );
         match resolved {
@@ -426,36 +399,15 @@ mod tests {
         }
     }
 
-    #[test]
-    fn well_known_dir_hit_reports_wellknown_source() {
-        // A well-known dir containing the shim resolves via WellKnown, with PATH
-        // lookup disabled so the real machine's ffmpeg can't interfere.
-        let dir = tempfile::tempdir().unwrap();
-        write_shim(dir.path(), "ffmpeg");
-        let resolved = resolve_binary_with(
-            "ffmpeg",
-            "ffmpeg",
-            &[dir.path().to_path_buf()],
-            no_path_lookup,
-        );
-        match resolved {
-            ResolvedBinary::Found {
-                via: ResolveSource::WellKnown,
-                ..
-            } => {}
-            other => panic!("expected Found via WellKnown, got {other:?}"),
-        }
-    }
-
     #[test]
     fn path_lookup_hit_reports_pathlookup_source() {
-        // A bare name found via PATH lookup reports PathLookup, not WellKnown.
+        // A bare name found via PATH lookup reports PathLookup.
         let dir = tempfile::tempdir().unwrap();
         let ffmpeg = write_shim(dir.path(), "ffmpeg");
         let via_path = move |name: &str| {
             if name == "ffmpeg" { Some(ffmpeg.clone()) } else { None }
         };
-        let resolved = resolve_binary_with("ffmpeg", "ffmpeg", NO_WELL_KNOWN, via_path);
+        let resolved = resolve_binary_with("ffmpeg", "ffmpeg", via_path);
         assert!(matches!(
             resolved,
             ResolvedBinary::Found {
diff --git a/crates/server/tests/test_media.rs b/crates/server/tests/test_media.rs
index dfef54bf..b08b6280 100644
--- a/crates/server/tests/test_media.rs
+++ b/crates/server/tests/test_media.rs
@@ -266,37 +266,21 @@ fn test_movie_library_ignores_sidecar_audio_and_json_files() {
 }
 
 #[test]
-fn test_inspect_transcoding_capability_surfaces_configured_path() {
-    // The resolver self-heals a misconfigured path by falling back to well-known
-    // dirs, so availability on a machine with ffmpeg installed is true regardless
-    // of the configured value. What we can assert hermetically is that the
-    // capability echoes the configured path back, and that a non-allowed binary
-    // name (rejected by the security allow-list) never silently changes it.
+fn test_inspect_transcoding_capability_reports_missing_binary() {
+    // The resolver is literal: it runs exactly what is configured and never
+    // substitutes a binary found elsewhere (smart discovery is the Detect UI's
+    // job). A base name rejected by the security allow-list therefore resolves
+    // to Missing on any machine, regardless of whether ffmpeg is installed.
     let settings = FfmpegSettings {
-        ffmpeg_path: "/usr/local/bin/koko-ffmpeg-missing-binary".into(),
-        ffprobe_path: "/usr/local/bin/koko-ffprobe-missing-binary".into(),
+        ffmpeg_path: "koko-ffmpeg-missing-binary".into(),
+        ffprobe_path: "koko-ffprobe-missing-binary".into(),
     };
 
     let capability = inspect_transcoding_capability(&settings);
-    assert_eq!(
-        capability.ffmpeg.configured_path,
-        "/usr/local/bin/koko-ffmpeg-missing-binary"
-    );
-    assert_eq!(
-        capability.ffprobe.configured_path,
-        "/usr/local/bin/koko-ffprobe-missing-binary"
-    );
-    // If ffmpeg is NOT installed anywhere, the allow-list rejection makes both
-    // unavailable with an error. If it IS installed, the fallback finds it. Either
-    // way the field is well-formed (not panic), so we only assert consistency.
-    assert_eq!(
-        capability.ffmpeg.available,
-        capability.ffmpeg.version.is_some()
-    );
-    assert_eq!(
-        capability.ffprobe.available,
-        capability.ffprobe.version.is_some()
-    );
+    assert!(!capability.ffmpeg.available);
+    assert!(!capability.ffprobe.available);
+    assert!(capability.ffmpeg.error.is_some());
+    assert!(capability.ffprobe.error.is_some());
 }
 
 #[test]

From ac1e6441dcd9822b658a5227e90d3ba1aa9a0c91 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 05:07:45 -0300
Subject: [PATCH 24/27] docs: add routes-module-split plan for delegation

---
 docs/refactoring/routes-module-split-plan.md | 88 ++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 docs/refactoring/routes-module-split-plan.md

diff --git a/docs/refactoring/routes-module-split-plan.md b/docs/refactoring/routes-module-split-plan.md
new file mode 100644
index 00000000..4aab0a68
--- /dev/null
+++ b/docs/refactoring/routes-module-split-plan.md
@@ -0,0 +1,88 @@
+# Routes Module Split — Plan
+
+- **Status:** Plan for delegation (separate PR). Not implemented on the `feat/transcode-ffmpeg-resolution` branch.
+- **Author context:** drafted during the transcode-fix work, after a first manual attempt at extracting modules proved too fragile for a single sitting (string-matching edits on a ~4,900-line file corrupted it once). This plan captures the target structure and the dependency map gathered then, so the delegate starts informed.
+- **Scope:** split `crates/server/src/web/routes/media.rs` (~4,871 lines, 28 route handlers) into focused submodules. A separate, later effort should split `crates/server/src/media.rs` (~6,411 lines, the data layer) — that one needs its own design pass and is out of scope here.
+
+## Why
+
+`web/routes/media.rs` is a grab-bag: nearly every route in the app lives there, plus their response types and private helpers. Every PR touches it; merge conflicts are common; the file is hard to navigate. The handlers fall into clearly cohesive groups, so the split is mostly mechanical — the risk is in getting the shared-helper boundaries right.
+
+## Current state (as measured)
+
+- 28 `#[openapi]` route handlers + 83 lines of inline tests.
+- Route registration in `crates/server/src/web/routes/mod.rs` via two macros: `api_routes()` (`openapi_get_routes![...]`) and `spa_routes()` (`routes![...]`). Every entry is `media::<handler>`.
+- Private helpers shared across handler groups (see Dependency map below).
+- Module-level statics for playback session state, transcode tasks, metadata refresh, catalog scan, system activities.
+
+## Target structure
+
+Proposed new modules under `crates/server/src/web/routes/`:
+
+| Module | Responsibility | Routes (current names) |
+|--------|----------------|------------------------|
+| `system.rs` | Server capabilities, transcoding-tool discovery, session status, system activities, metadata providers/locales | `get_server_capabilities`, `discover_transcoding_tools`, `get_session_status`, `get_system_activities`, `get_metadata_providers`, `get_metadata_locales` |
+| `libraries.rs` | Library config + catalog + inventory | `get_libraries`, `scan_library`, `delete_library_missing_items`, `refresh_library_metadata`, `get_library_inventory`, `add_library`¹, `remove_library`¹ |
+| `items.rs` | Media item reads, metadata, people, search | `get_home`, `get_items`, `get_item`, `get_item_metadata`, `get_person`, `get_person_image`, `search_item_metadata`, `link_item_metadata`, `refresh_item_metadata`, `search_items` |
+| `playback.rs` | Playback sessions, streams, progress, item-playback decisions | `create_session`, `delete_session`, `get_session_stream`, `get_item_playback`, `stream_item`, `update_item_progress` |
+| `assets.rs` | Media asset serving (artwork, theme, subtitle) | `get_item_artwork`, `get_item_theme`, `get_item_subtitle` |
+| `common.rs` | *(existing)* SPA index/asset routes — unchanged | `index`, `spa_asset` |
+| `auth.rs`, `user.rs`, `settings.rs`, `dependencies.rs` | *(existing)* — unchanged | — |
+
+¹ `add_library` / `remove_library` currently live in `settings.rs`; consider whether they belong with `libraries.rs` (semantic fit) or stay in `settings.rs` (current location). Recommend moving them to `libraries.rs` for cohesion, updating `settings.rs` and `mod.rs` accordingly.
+
+`media.rs` is then deleted; `mod.rs` declares the new `pub mod` entries.
+
+## Dependency map (the part that needs care)
+
+These private helpers and shared state must be placed where all their callers can reach them without creating import cycles. Recommended homes:
+
+**Shared response types** → keep in a new `routes/types.rs` (or in `common.rs`) if referenced by >1 module; otherwise move with their sole consumer:
+- `ServerCapabilitiesResponse`, `BinaryProbe`, `ToolCandidate`, `ToolDiscoveryResponse`, `SessionStatusResponse`, `SessionTranscodeError` → `system.rs` (sole consumer is the system routes).
+- `SessionStream`, `RangedFile`, `RangeHeader` → `playback.rs` (used by playback + assets streams).
+- `ToolCandidate` etc. are system-only.
+
+**Helpers** (defined line → callers):
+- `open_ranged_file` (263) → callers: `get_session_stream` (3694), `stream_item` (3865). **Both are playback/assets.** → `playback.rs`.
+- `content_type_for_path` (256) → caller: `open_ranged_file` (295). → moves with it to `playback.rs`.
+- `stop_active_transcode` (303) → callers: `get_session_stream` (3651, 3687, 3757). → `playback.rs`.
+- `replace_active_transcode` (313) → caller: `get_session_stream` (3782). → `playback.rs`.
+- `record_session_error` (527) → caller: `get_session_stream` (3800). → `playback.rs`. (`get_session_status` in `system.rs` reads the same store — see "Session state" below.)
+- `current_user_id` (2862) → callers: `update_item_progress` (3386), `create_session` (3419), `delete_session` (3499). All playback. → `playback.rs`. (If items/auth also need it later, promote to `common.rs`.)
+- `probe_configured` (3053), `probe_in_dir` (3090) → sole caller: `discover_transcoding_tools`. → `system.rs`.
+
+**Module-level statics** — the cross-module sharing point:
+- `ACTIVE_PLAYBACK_SESSIONS`, `ACTIVE_TRANSCODE_TASKS`, `ACTIVE_SESSION_ERRORS` → these are **read by `system.rs` (`get_session_status`) and written by `playback.rs`**. Recommended: place them in `playback.rs` as `pub(crate)` with small accessors (`session_exists`, `session_error`), and have `system.rs` call those accessors. This keeps the writer owning the state and the reader using a narrow interface.
+- `ACTIVE_SYSTEM_ACTIVITIES`, `ACTIVE_METADATA_REFRESH_*`, `ACTIVE_MANUAL_CATALOG_SCAN_RUNNING` → stay with their consumers (`system.rs` / `libraries.rs`).
+
+**Imports** — every new module needs its own `use` block. The current `media.rs` has a large import list (~80 lines); each new module takes only the subset it uses. Watch for `Serialize`/`JsonSchema`/`openapi`/`Lazy`/`HashMap` which most modules need.
+
+## Recommended execution order (each step independently shippable)
+
+Each step is a separate commit; run `cargo test -p koko` + `cargo build -p koko` after each. The macros in `mod.rs` are updated per step.
+
+1. **Extract `system.rs`** (capabilities, discover, status, activities, providers/locales). Depends on playback exposing `session_exists`/`session_error` — so do step 2's accessors first, or temporarily keep `get_session_status` in `media.rs` and move it in step 2. Lowest coupling, good first step.
+2. **Extract `playback.rs`** (sessions, streams, progress, item-playback). Moves `SessionStream`/`RangedFile`/`RangeHeader`/`open_ranged_file`/`content_type_for_path`/`stop_active_transcode`/`replace_active_transcode`/`record_session_transcode`/`current_user_id` and the three `ACTIVE_*` statics (as `pub(crate)` + accessors). This is the largest, most intertwined step — do it carefully and alone.
+3. **Extract `assets.rs`** (artwork, theme, subtitle). Depends on `playback.rs`'s `RangedFile`/`open_ranged_file` if subtitle/theme use ranged serving — verify and import as `super::playback::`.
+4. **Extract `libraries.rs`** (library routes; optionally pull `add_library`/`remove_library` from `settings.rs`).
+5. **Extract `items.rs`** (everything remaining). At this point `media.rs` is empty → delete it; remove from `mod.rs`.
+6. **Final pass:** run clippy, fmt, full test suite; verify the openapi spec still lists all 28 routes.
+
+## Anti-patterns to avoid
+
+- **Don't reformat the whole tree in the same PR.** The repo is not `cargo fmt`-clean today (many files have pre-existing formatting drift); sweeping them muddies the diff. Run `cargo fmt` only on files this PR actually moves.
+- **Don't change behavior.** This is a pure move refactor: no logic edits, no renamed routes, no API changes. The openapi spec and all tests must be byte-for-byte equivalent before/after.
+- **Don't do it as one giant commit.** Each module extraction is reviewable on its own; a monolithic move is unreviewable and conflict-prone.
+- **Don't invent new abstractions.** No traits, no trait objects, no "BaseRoute" helpers. Just moving functions/types between files. If a helper ends up shared, `pub(crate)` it; don't over-engineer.
+
+## Verification
+
+- `cargo test -p koko` — all 340+ tests pass unchanged.
+- `cargo build -p koko` — no warnings introduced (watch for moved-but-unused imports).
+- The generated openapi spec (if checked) lists the same 28 routes with the same paths/methods/schemas.
+- `npx tsc --noEmit` in `crates/client-web` — the client uses `requestJson` against paths, not Rust module paths, so it should be unaffected; verify anyway.
+- Manual smoke: settings, detect-ffmpeg, play an item (direct + transcode), metadata refresh.
+
+## Follow-up: data layer split (`crates/server/src/media.rs`)
+
+Separately, `media.rs` (~6,411 lines, ~52 public fns spanning library config, catalog sync, item queries, search, playback decisions, playback progress, metadata-link resolution, artwork/subtitle/theme resolution, transcoding capability) should be split by domain. This is higher risk (core app logic, cross-deps, less obvious boundaries) and deserves its own design doc + spec before execution. Suggested first investigation: build a call-graph of the 52 public fns to find natural seams, and check test coverage of each seam before cutting.

From 2bbea1bced605c4793c58f44754a1f383811c148 Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 05:29:02 -0300
Subject: [PATCH 25/27] fix(client): show in-player error overlay on
 ffmpeg-missing preflight

---
 crates/client-web/src/app/playbackController.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/crates/client-web/src/app/playbackController.ts b/crates/client-web/src/app/playbackController.ts
index d546048d..80e14f64 100644
--- a/crates/client-web/src/app/playbackController.ts
+++ b/crates/client-web/src/app/playbackController.ts
@@ -645,6 +645,11 @@ export async function startPlayback(item: MediaItemDetail, startMs: number): Pro
     };
     state.error = 'Transcoding requires FFmpeg, which the server could not find. Set its path in Settings.';
     render();
+    // The player overlay is rendered on top of the page banner, so we must also
+    // toggle the in-player error class directly (the player shell is mounted by
+    // the render() above). Mirrors what setPlayerError() does post-mount.
+    document.querySelector<HTMLElement>('.media-player-shell')?.classList.remove('is-media-loading');
+    document.querySelector<HTMLElement>('.media-player-shell')?.classList.add('has-media-error');
     return;
   }
 

From c65c7e270b3b0ee5cb6ffe622d7c1b6351b4259a Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 07:08:24 -0300
Subject: [PATCH 26/27] feat: ffprobe as first-class blocker, decision guard,
 auto re-probe

- PlaybackAnalysisState enum: refuse to decide media never probed by ffprobe
  (NULL metadata_json), instead of returning an untrustworthy 'transcode required'
- count_media_files_needing_reprobe + reprobe_media_files: targeted UPDATE of
  codec/container/metadata_json columns, independent of the hash-skip scan guard
- Re-probe driver (try_spawn_reprobe) + activity progress (Dashboard bar)
- Triggers: startup (ffprobe now available + unprobed files), manual route
  POST /api/v1/system/tools/reprobe (+ GET status). Settings-change trigger
  dropped (DbConn can't be cloned into a spawn from the route)
- Drop the buggy client-side capabilities-cache preflight; the server-side
  analysis_state guard replaces it with single-source-of-truth
- Remove debug telemetry from create_session / get_session_stream
- Client: analysis_state rendering in player, Re-probe button in settings
---
 crates/client-web/src/api.ts                  |  21 ++
 crates/client-web/src/app/eventBindings.ts    |  38 ++++
 .../client-web/src/app/playbackController.ts  |  25 +--
 crates/client-web/src/app/settingsView.ts     |   2 +
 crates/client-web/src/mockApi.ts              |   2 +
 crates/server/src/auth.rs                     |  47 +---
 crates/server/src/certs.rs                    |   5 +-
 crates/server/src/config.rs                   |   7 +-
 crates/server/src/db/mod.rs                   |  32 +--
 crates/server/src/db/models.rs                |  22 +-
 crates/server/src/db/schema.rs                |   6 +-
 crates/server/src/dependencies/mod.rs         |   5 +-
 crates/server/src/logging/mod.rs              |   5 +-
 crates/server/src/media.rs                    | 205 ++++++++++++++++++
 crates/server/src/metadata/mod.rs             |  69 ++----
 crates/server/src/metadata/providers/mod.rs   |  19 +-
 .../server/src/metadata/providers/themerr.rs  |  13 +-
 crates/server/src/metadata/providers/tmdb.rs  |  62 +-----
 .../src/metadata/providers/trailerdb.rs       |  17 +-
 crates/server/src/metadata/providers/tvdb.rs  |  57 +----
 crates/server/src/scanner/books.rs            |  16 +-
 crates/server/src/scanner/directory.rs        |  19 +-
 crates/server/src/scanner/mod.rs              |  11 +-
 crates/server/src/scanner/movies.rs           |  16 +-
 crates/server/src/scanner/music.rs            |  16 +-
 crates/server/src/scanner/photos.rs           |  16 +-
 crates/server/src/scanner/shows.rs            |  16 +-
 .../scheduled_tasks/database_maintenance.rs   |   6 +-
 .../src/scheduled_tasks/metadata_refresh.rs   |  10 +-
 crates/server/src/scheduled_tasks/mod.rs      |  17 +-
 .../src/scheduled_tasks/trash_cleanup.rs      |   6 +-
 crates/server/src/secrets.rs                  |   6 +-
 crates/server/src/signal_handler.rs           |   5 +-
 crates/server/src/tray.rs                     |  22 +-
 crates/server/src/web/mod.rs                  |  38 ++--
 crates/server/src/web/routes/auth.rs          |  26 +--
 crates/server/src/web/routes/common.rs        |  10 +-
 crates/server/src/web/routes/media.rs         | 192 ++++++++++++++++
 crates/server/src/web/routes/mod.rs           |   2 +
 crates/server/src/web/routes/settings.rs      |  37 +---
 crates/server/src/web/routes/user.rs          |  46 +---
 crates/server/tests/fixtures/mod.rs           |   5 +-
 crates/server/tests/test_auth.rs              |  13 +-
 crates/server/tests/test_metadata.rs          |  31 +--
 crates/server/tests/test_signal_handler.rs    |  17 +-
 crates/server/tests/test_utils.rs             |  11 +-
 crates/server/tests/test_web/routes/auth.rs   |   5 +-
 crates/server/tests/test_web/routes/common.rs |   5 +-
 .../tests/test_web/routes/dependencies.rs     |  10 +-
 crates/server/tests/test_web/routes/media.rs  |  10 +-
 .../server/tests/test_web/routes/settings.rs  |  11 +-
 crates/server/tests/test_web/routes/user.rs   |  12 +-
 .../server/tests/test_web/test_auth_routes.rs |   6 +-
 53 files changed, 653 insertions(+), 675 deletions(-)

diff --git a/crates/client-web/src/api.ts b/crates/client-web/src/api.ts
index bf6448b7..f41f6bea 100644
--- a/crates/client-web/src/api.ts
+++ b/crates/client-web/src/api.ts
@@ -450,8 +450,13 @@ export interface MediaHome {
   collections: MediaCollectionSummary[];
 }
 
+/** Whether the source media has been analyzed by ffprobe. */
+export type PlaybackAnalysisState = 'analyzed' | 'awaiting_analysis';
+
 export interface PlaybackDecision {
   item_id: number;
+  /** Whether the source media was probed; if 'awaiting_analysis', playback is blocked. */
+  analysis_state: PlaybackAnalysisState;
   can_direct_play: boolean;
   transcode_required: boolean;
   reason: string;
@@ -1320,6 +1325,22 @@ export function getSessionStatus(sessionId: string): Promise<SessionStatusRespon
   return requestJson<SessionStatusResponse>('GET', `/api/v1/sessions/${encodeURIComponent(sessionId)}/status`);
 }
 
+/** Re-probe status: whether a job is running and how many files await analysis. */
+export interface ReprobeStatusResponse {
+  in_progress: boolean;
+  pending_count: number;
+}
+
+/** Get re-probe status (running? how many files pending ffprobe analysis). */
+export function getReprobeStatus(): Promise<ReprobeStatusResponse> {
+  return requestJson<ReprobeStatusResponse>('GET', '/api/v1/system/tools/reprobe');
+}
+
+/** Manually trigger a ffprobe re-probe of all unanalyzed media files (admin). */
+export function triggerReprobe(): Promise<ReprobeStatusResponse> {
+  return requestJson<ReprobeStatusResponse>('POST', '/api/v1/system/tools/reprobe');
+}
+
 export function getArtworkUrl(itemId: number, kind: 'poster' | 'backdrop' | 'logo' = 'poster', revision?: number): string {
   const params = new URLSearchParams({ kind });
   if (typeof revision === 'number') {
diff --git a/crates/client-web/src/app/eventBindings.ts b/crates/client-web/src/app/eventBindings.ts
index 82c39bbc..326dc26e 100644
--- a/crates/client-web/src/app/eventBindings.ts
+++ b/crates/client-web/src/app/eventBindings.ts
@@ -53,6 +53,7 @@ import {
   deleteLibrary,
   deleteMissingItems,
   discoverTranscodingTools,
+  getReprobeStatus,
   getItemMetadata,
   getLogs,
   getUsers,
@@ -72,6 +73,7 @@ import {
   type MediaShelf,
   type ScheduledTaskId,
   type UpdateUserRequest,
+  triggerReprobe,
 } from '../api';
 
 /** Replaces a DOM subtree while preserving any coordinator-level patch behavior. */
@@ -579,6 +581,42 @@ function bindRenderEvents(context: AppEventBindingContext): void {
     }
   });
 
+  // Re-probe media info: show the button when there are unanalyzed files
+  // (ffprobe was missing during scan), and trigger the job on click.
+  const reprobeButton = document.querySelector<HTMLButtonElement>('#reprobe-media');
+  const reprobeStatus = document.querySelector<HTMLElement>('#reprobe-status');
+  if (reprobeButton && reprobeStatus) {
+    getReprobeStatus()
+      .then((status) => {
+        if (status.in_progress) {
+          reprobeStatus.hidden = false;
+          reprobeStatus.textContent = 'Re-probing media info is in progress… (see Dashboard → Activities).';
+        } else if (status.pending_count > 0) {
+          reprobeButton.hidden = false;
+          reprobeStatus.hidden = false;
+          reprobeStatus.textContent = `${status.pending_count} media file(s) were scanned without ffprobe and need re-analysis. Click to re-probe.`;
+        }
+      })
+      .catch((error) => {
+        console.warn('Failed to fetch reprobe status', error);
+      });
+
+    reprobeButton.addEventListener('click', async () => {
+      setButtonBusy(reprobeButton, true);
+      try {
+        await triggerReprobe();
+        reprobeStatus.hidden = false;
+        reprobeStatus.textContent = 'Re-probe started. Watch Dashboard → Activities for progress; playback unlocks as files are analyzed.';
+        reprobeButton.hidden = true;
+      } catch (error) {
+        reprobeStatus.hidden = false;
+        reprobeStatus.textContent = `Re-probe failed to start: ${escapeHtml(error instanceof Error ? error.message : 'unknown error')}`;
+      } finally {
+        setButtonBusy(reprobeButton, false);
+      }
+    });
+  }
+
   document.querySelectorAll<HTMLButtonElement>('[data-provider-settings]').forEach((button) => {
     button.addEventListener('click', () => {
       const providerId = button.dataset.providerSettings;
diff --git a/crates/client-web/src/app/playbackController.ts b/crates/client-web/src/app/playbackController.ts
index 80e14f64..a954bfad 100644
--- a/crates/client-web/src/app/playbackController.ts
+++ b/crates/client-web/src/app/playbackController.ts
@@ -631,23 +631,22 @@ export async function startPlayback(item: MediaItemDetail, startMs: number): Pro
     client_profile: getWebClientProfile(),
   });
 
-  // Preflight: if this item needs transcoding but ffmpeg is unavailable on the
-  // server, don't attach a doomed stream — surface the error now instead of a
-  // black screen. This is the deterministic, timer-free detection for issue 2.
-  const ffmpegAvailable = state.capabilities?.transcoding.ffmpeg.available === true;
-  const needsTranscode = state.activePlaybackSession.decision.transcode_required;
-  if (needsTranscode && !ffmpegAvailable) {
-    const capabilityError = state.capabilities?.transcoding.ffmpeg.error;
+  // Server-truth gate: if the source media was never analyzed by ffprobe
+  // (ffprobe was missing during scan), the decision is untrustworthy and the
+  // server returns analysis_state = 'awaiting_analysis'. Refuse to open a
+  // doomed player and surface the error instead. This replaces the old,
+  // buggy client-side capabilities-cache preflight.
+  const decision = state.activePlaybackSession.decision;
+  if (decision.analysis_state === 'awaiting_analysis') {
     state.playbackError = {
-      code: 'transcode_executable_missing',
-      message: capabilityError ?? 'Transcoding is required but FFmpeg is not available on the server.',
+      code: 'media_not_analyzed',
+      message: decision.reason || 'This media has not been analyzed yet. Set the ffprobe path in Settings and re-probe media info.',
       action: 'open_settings',
     };
-    state.error = 'Transcoding requires FFmpeg, which the server could not find. Set its path in Settings.';
+    state.error = state.playbackError.message;
     render();
-    // The player overlay is rendered on top of the page banner, so we must also
-    // toggle the in-player error class directly (the player shell is mounted by
-    // the render() above). Mirrors what setPlayerError() does post-mount.
+    // The player overlay covers the page banner, so toggle the in-player error
+    // class directly (the shell is mounted by the render() above).
     document.querySelector<HTMLElement>('.media-player-shell')?.classList.remove('is-media-loading');
     document.querySelector<HTMLElement>('.media-player-shell')?.classList.add('has-media-error');
     return;
diff --git a/crates/client-web/src/app/settingsView.ts b/crates/client-web/src/app/settingsView.ts
index f797c9a1..9779bbdf 100644
--- a/crates/client-web/src/app/settingsView.ts
+++ b/crates/client-web/src/app/settingsView.ts
@@ -556,7 +556,9 @@ function renderGeneralSettingsPage(settings: SettingsSnapshot): string {
             </div>
             <div class="page-actions">
               <button id="detect-ffmpeg" class="secondary-button" type="button">${renderButtonContent('Detect ffmpeg', 'search')}</button>
+              <button id="reprobe-media" class="secondary-button" type="button" hidden>${renderButtonContent('Re-probe media info', 'refresh-cw')}</button>
             </div>
+            <p id="reprobe-status" class="muted" hidden></p>
           </div>
           <div id="ffmpeg-discover-results" hidden></div>
           <div class="form-row">
diff --git a/crates/client-web/src/mockApi.ts b/crates/client-web/src/mockApi.ts
index 306fff65..7ac86dae 100644
--- a/crates/client-web/src/mockApi.ts
+++ b/crates/client-web/src/mockApi.ts
@@ -1127,6 +1127,7 @@ export function getMockPlayback(itemId: number): PlaybackDecision {
   if (!item.playable) {
     return {
       item_id: itemId,
+      analysis_state: 'analyzed',
       can_direct_play: false,
       transcode_required: false,
       video_transcode_required: false,
@@ -1140,6 +1141,7 @@ export function getMockPlayback(itemId: number): PlaybackDecision {
   const canDirectPlay = item.container === 'mp4' || item.container === 'mp3' || item.container === 'flac';
   return {
     item_id: itemId,
+    analysis_state: 'analyzed',
     can_direct_play: canDirectPlay,
     transcode_required: !canDirectPlay,
     video_transcode_required: !canDirectPlay && item.media_kind === 'video',
diff --git a/crates/server/src/auth.rs b/crates/server/src/auth.rs
index bae2c1d8..8109f091 100644
--- a/crates/server/src/auth.rs
+++ b/crates/server/src/auth.rs
@@ -1,44 +1,17 @@
 //! Authentication utilities for the application.
 
 // lib imports
-use base64::{
-    Engine as _,
-    engine::general_purpose,
-};
-use bcrypt::{
-    DEFAULT_COST,
-    hash,
-    verify,
-};
-use diesel::{
-    QueryDsl,
-    RunQueryDsl,
-};
-use jsonwebtoken::{
-    DecodingKey,
-    EncodingKey,
-    Header,
-    Validation,
-    decode,
-    encode,
-};
+use base64::{Engine as _, engine::general_purpose};
+use bcrypt::{DEFAULT_COST, hash, verify};
+use diesel::{QueryDsl, RunQueryDsl};
+use jsonwebtoken::{DecodingKey, EncodingKey, Header, Validation, decode, encode};
 use once_cell::sync::Lazy;
 use rand::Rng;
 use rocket::http::Status;
 use rocket::outcome::Outcome;
-use rocket::request::{
-    self,
-    FromRequest,
-    Request,
-};
-use rocket_okapi::request::{
-    OpenApiFromRequest,
-    RequestHeaderInput,
-};
-use serde::{
-    Deserialize,
-    Serialize,
-};
+use rocket::request::{self, FromRequest, Request};
+use rocket_okapi::request::{OpenApiFromRequest, RequestHeaderInput};
+use serde::{Deserialize, Serialize};
 
 // local imports
 use crate::db::DbConn;
@@ -139,11 +112,7 @@ impl<'r, const ROLE: u8> FromRequest<'r> for AuthGuard<ROLE> {
 /// Helper function to create Bearer token security configuration for OpenAPI
 fn create_bearer_auth_security(scopes: Vec<String>) -> rocket_okapi::Result<RequestHeaderInput> {
     use rocket_okapi::okapi::Map;
-    use rocket_okapi::okapi::openapi3::{
-        SecurityRequirement,
-        SecurityScheme,
-        SecuritySchemeData,
-    };
+    use rocket_okapi::okapi::openapi3::{SecurityRequirement, SecurityScheme, SecuritySchemeData};
 
     let security_scheme = SecurityScheme {
         data: SecuritySchemeData::Http {
diff --git a/crates/server/src/certs.rs b/crates/server/src/certs.rs
index 50b7db2a..cba2869d 100644
--- a/crates/server/src/certs.rs
+++ b/crates/server/src/certs.rs
@@ -5,10 +5,7 @@ use std::fs;
 use std::path::Path;
 
 // lib imports
-use rcgen::{
-    CertifiedKey,
-    generate_simple_self_signed,
-};
+use rcgen::{CertifiedKey, generate_simple_self_signed};
 
 /// Ensure that the certificates exist at the given paths.
 pub fn ensure_certificates_exist(
diff --git a/crates/server/src/config.rs b/crates/server/src/config.rs
index 3b587ad0..76402b3f 100644
--- a/crates/server/src/config.rs
+++ b/crates/server/src/config.rs
@@ -7,12 +7,7 @@ use std::path::PathBuf;
 use std::sync::RwLock;
 
 // lib imports
-use config::{
-    Config,
-    ConfigError,
-    Environment,
-    File,
-};
+use config::{Config, ConfigError, Environment, File};
 use diesel::prelude::*;
 use dirs::config_local_dir;
 use once_cell::sync::Lazy;
diff --git a/crates/server/src/db/mod.rs b/crates/server/src/db/mod.rs
index b98573ba..db4e0a3c 100644
--- a/crates/server/src/db/mod.rs
+++ b/crates/server/src/db/mod.rs
@@ -4,10 +4,7 @@ pub(crate) mod models;
 pub(crate) mod schema;
 
 // standard imports
-use std::collections::{
-    HashMap,
-    HashSet,
-};
+use std::collections::{HashMap, HashSet};
 use std::error::Error;
 use std::fmt;
 use std::fs;
@@ -16,30 +13,13 @@ use std::path::Path;
 // lib imports
 use diesel::Connection;
 use diesel::connection::SimpleConnection;
-use diesel::migration::{
-    Migration,
-    MigrationSource,
-    MigrationVersion,
-    Result as MigrationResult,
-};
-use diesel_migrations::{
-    EmbeddedMigrations,
-    MigrationHarness,
-    embed_migrations,
-};
+use diesel::migration::{Migration, MigrationSource, MigrationVersion, Result as MigrationResult};
+use diesel_migrations::{EmbeddedMigrations, MigrationHarness, embed_migrations};
 use rocket::{
-    Build,
-    Rocket,
-    fairing::{
-        Fairing,
-        Info,
-        Kind,
-    },
-};
-use rocket_sync_db_pools::{
-    database,
-    diesel,
+    Build, Rocket,
+    fairing::{Fairing, Info, Kind},
 };
+use rocket_sync_db_pools::{database, diesel};
 
 /// Embedded migrations for the SQLite database.
 const MIGRATIONS: EmbeddedMigrations = embed_migrations!("sql/migrations");
diff --git a/crates/server/src/db/models.rs b/crates/server/src/db/models.rs
index 9c253617..1717462a 100644
--- a/crates/server/src/db/models.rs
+++ b/crates/server/src/db/models.rs
@@ -5,24 +5,10 @@ use diesel::prelude::*;
 
 // local imports
 use crate::db::schema::{
-    app_settings,
-    external_media,
-    item_metadata_external_ids,
-    item_metadata_links,
-    item_metadata_people,
-    media_file_libraries,
-    media_files,
-    media_items,
-    media_libraries,
-    metadata_collection_items,
-    metadata_collections,
-    metadata_extras,
-    metadata_people,
-    metadata_person_credits,
-    metadata_person_external_ids,
-    playback_progress,
-    scan_state,
-    users,
+    app_settings, external_media, item_metadata_external_ids, item_metadata_links,
+    item_metadata_people, media_file_libraries, media_files, media_items, media_libraries,
+    metadata_collection_items, metadata_collections, metadata_extras, metadata_people,
+    metadata_person_credits, metadata_person_external_ids, playback_progress, scan_state, users,
 };
 
 #[derive(Queryable, Selectable, Insertable, AsChangeset, Debug, Clone)]
diff --git a/crates/server/src/db/schema.rs b/crates/server/src/db/schema.rs
index afd17f86..c12a5c10 100644
--- a/crates/server/src/db/schema.rs
+++ b/crates/server/src/db/schema.rs
@@ -1,11 +1,7 @@
 //! Database schema for the application.
 
 // lib imports
-use diesel::{
-    allow_tables_to_appear_in_same_query,
-    joinable,
-    table,
-};
+use diesel::{allow_tables_to_appear_in_same_query, joinable, table};
 
 table! {
     app_settings (key) {
diff --git a/crates/server/src/dependencies/mod.rs b/crates/server/src/dependencies/mod.rs
index 39073768..17199847 100644
--- a/crates/server/src/dependencies/mod.rs
+++ b/crates/server/src/dependencies/mod.rs
@@ -1,9 +1,6 @@
 //! Module for everything related to dependencies.
 
-use cargo_metadata::{
-    MetadataCommand,
-    Package,
-};
+use cargo_metadata::{MetadataCommand, Package};
 use std::error::Error;
 
 /// Get the dependencies from the Cargo.toml file.
diff --git a/crates/server/src/logging/mod.rs b/crates/server/src/logging/mod.rs
index 5b532d60..10d1f105 100644
--- a/crates/server/src/logging/mod.rs
+++ b/crates/server/src/logging/mod.rs
@@ -5,10 +5,7 @@ use std::io;
 use std::path::Path;
 
 // lib imports
-use fern::colors::{
-    Color,
-    ColoredLevelConfig,
-};
+use fern::colors::{Color, ColoredLevelConfig};
 use log::LevelFilter;
 use regex::Regex;
 
diff --git a/crates/server/src/media.rs b/crates/server/src/media.rs
index ae902fae..cdf66d91 100644
--- a/crates/server/src/media.rs
+++ b/crates/server/src/media.rs
@@ -557,11 +557,27 @@ pub struct ClientProfile {
     pub prefer_hls: bool,
 }
 
+/// Whether the source media has been analyzed by ffprobe, which determines
+/// whether a playback decision can be trusted.
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub enum PlaybackAnalysisState {
+    /// The source media was probed by ffprobe; codec/container are known and
+    /// the direct-play vs transcode decision is reliable.
+    Analyzed,
+    /// The source media was never probed (ffprobe was missing during scan), so
+    /// codec/container are unknown and no trustworthy playback decision can be
+    /// made. The client should refuse to open a player and surface a setup hint.
+    AwaitingAnalysis,
+}
+
 /// Direct-play versus transcode decision for one media item.
 #[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
 pub struct PlaybackDecision {
     /// Stable database identifier for the item.
     pub item_id: i32,
+    /// Whether the source media has been analyzed; if [`PlaybackAnalysisState::AwaitingAnalysis`],
+    /// the other fields are not trustworthy and playback should be blocked.
+    pub analysis_state: PlaybackAnalysisState,
     /// Whether the item can be played directly in the browser.
     pub can_direct_play: bool,
     /// Whether transcoding would be required for ideal playback.
@@ -1671,6 +1687,161 @@ fn sync_library_catalog_filtered(
     Ok(persisted)
 }
 
+/// A `media_files` row selected for re-probing (ffprobe was missing when it was
+/// first scanned, so its codec/container/metadata_json are NULL). Carries just
+/// the fields needed to reconstruct a [`DiscoveredMediaFile`] for probing.
+#[derive(Debug, Clone, diesel::QueryableByName)]
+#[diesel(table_name = crate::db::schema::media_files)]
+struct ReprobeCandidate {
+    #[diesel(sql_type = sql_types::Integer)]
+    id: i32,
+    #[diesel(sql_type = sql_types::Text)]
+    path: String,
+    #[diesel(sql_type = sql_types::BigInt)]
+    file_size: i64,
+    #[diesel(sql_type = sql_types::Nullable<sql_types::BigInt>)]
+    modified_at: Option<i64>,
+    #[diesel(sql_type = sql_types::Text)]
+    media_kind: String,
+    #[diesel(sql_type = sql_types::Text)]
+    file_hash: String,
+}
+
+/// Count media files that were cataloged without being probed (ffprobe was
+/// missing during their scan). These are candidates for auto re-probe.
+pub fn count_media_files_needing_reprobe(
+    conn: &mut SqliteConnection
+) -> Result<i64, diesel::result::Error> {
+    use crate::db::schema::media_files::dsl as media_files_dsl;
+    media_files_dsl::media_files
+        .filter(media_files_dsl::metadata_json.is_null())
+        .filter(media_files_dsl::media_kind.eq_any([
+            "video".to_string(),
+            "audio".to_string(),
+        ]))
+        .count()
+        .get_result(conn)
+}
+
+/// Load the media files needing re-probe (see [`count_media_files_needing_reprobe`]).
+fn load_media_files_needing_reprobe(
+    conn: &mut SqliteConnection
+) -> Result<Vec<ReprobeCandidate>, diesel::result::Error> {
+    diesel::sql_query(
+        "SELECT id, path, file_size, modified_at, media_kind, file_hash \
+         FROM media_files \
+         WHERE metadata_json IS NULL AND media_kind IN ('video', 'audio') \
+         ORDER BY id",
+    )
+    .load::<ReprobeCandidate>(conn)
+}
+
+/// Outcome of a re-probe run: how many files were inspected, how many produced
+/// real metadata, and how many failed.
+#[derive(Debug, Clone, Default)]
+pub struct ReprobeOutcome {
+    /// Total candidate files inspected.
+    pub inspected: usize,
+    /// Files whose probe succeeded and whose codec columns were updated.
+    pub updated: usize,
+    /// Files whose probe failed (ffprobe errored or parse failed); left as-is.
+    pub failed: usize,
+}
+
+/// Re-probe media files that were cataloged without ffprobe (their
+/// `metadata_json` is NULL). For each candidate, runs ffprobe and writes only
+/// the codec/container/stream columns via a targeted UPDATE (path, hash, and
+/// modified_at are untouched — the file content didn't change, only ffprobe
+/// availability did). Does not ride the scan path because `sync_discovered_media_file`
+/// skips re-probe when `file_hash` matches.
+///
+/// `progress` is called with the running count of inspected files after each
+/// one, so callers can update an activity record between probes.
+pub fn reprobe_media_files<F>(
+    conn: &mut SqliteConnection,
+    ffmpeg_settings: &FfmpegSettings,
+    mut progress: F,
+) -> Result<ReprobeOutcome, diesel::result::Error>
+where
+    F: FnMut(usize),
+{
+    use crate::db::schema::media_files::dsl as media_files_dsl;
+
+    // Re-check ffprobe availability at call time; detect_binary is stateless.
+    let probe_context = ProbeContext {
+        ffprobe_path: &ffmpeg_settings.ffprobe_path,
+        enabled: detect_binary(&ffmpeg_settings.ffprobe_path, "ffprobe").available,
+    };
+    if !probe_context.enabled {
+        log::warn!(
+            "reprobe_media_files called but ffprobe is not available; skipping ({} configured)",
+            ffmpeg_settings.ffprobe_path
+        );
+        return Ok(ReprobeOutcome::default());
+    }
+
+    let candidates = load_media_files_needing_reprobe(conn)?;
+    let mut outcome = ReprobeOutcome {
+        inspected: candidates.len(),
+        ..Default::default()
+    };
+
+    for candidate in candidates {
+        // Reconstruct a minimal DiscoveredMediaFile for extract_metadata.
+        let discovered = DiscoveredMediaFile {
+            full_path: PathBuf::from(&candidate.path),
+            source_root_path: String::new(),
+            relative_path: String::new(),
+            file_size: candidate.file_size,
+            modified_at: candidate.modified_at,
+            media_kind: candidate.media_kind.clone(),
+            file_hash: candidate.file_hash.clone(),
+            default_title: String::new(),
+        };
+        let metadata = extract_metadata(&discovered, probe_context);
+
+        // Only update when the probe actually produced metadata_json; otherwise
+        // leave the row as-is so a future run retries it.
+        if metadata.metadata_json.is_some() {
+            let now = current_timestamp();
+            diesel::update(
+                media_files_dsl::media_files.filter(media_files_dsl::id.eq(candidate.id)),
+            )
+            .set((
+                media_files_dsl::container.eq(&metadata.container),
+                media_files_dsl::duration_ms.eq(metadata.duration_ms),
+                media_files_dsl::bit_rate.eq(metadata.bit_rate),
+                media_files_dsl::width.eq(metadata.width),
+                media_files_dsl::height.eq(metadata.height),
+                media_files_dsl::video_codec.eq(&metadata.video_codec),
+                media_files_dsl::audio_codec.eq(&metadata.audio_codec),
+                media_files_dsl::metadata_json.eq(&metadata.metadata_json),
+                media_files_dsl::metadata_updated_at.eq(Some(now)),
+            ))
+            .execute(conn)?;
+            outcome.updated += 1;
+        } else {
+            outcome.failed += 1;
+        }
+        progress(outcome.inspected_done());
+    }
+
+    log::info!(
+        "reprobe_media_files complete: inspected={}, updated={}, failed={}",
+        outcome.inspected,
+        outcome.updated,
+        outcome.failed
+    );
+    Ok(outcome)
+}
+
+impl ReprobeOutcome {
+    /// Number of candidates processed so far (updated + failed).
+    fn inspected_done(&self) -> usize {
+        self.updated + self.failed
+    }
+}
+
 fn sync_logical_media_items_for_library(
     conn: &mut SqliteConnection,
     library: &MediaLibrary,
@@ -3098,6 +3269,7 @@ pub fn get_playback_decision(
         if row.missing_since.is_some() {
             return Ok(Some(PlaybackDecision {
                 item_id,
+                analysis_state: PlaybackAnalysisState::Analyzed,
                 can_direct_play: false,
                 transcode_required: false,
                 reason: "This item is missing from disk and cannot be played.".into(),
@@ -3114,6 +3286,37 @@ pub fn get_playback_decision(
             }));
         }
 
+        // Decision guard: if the source media was never analyzed by ffprobe
+        // (metadata_json is NULL — ffprobe was missing during scan), the
+        // codec/container fields are unknown and no trustworthy direct-play vs
+        // transcode decision can be made. Refuse to decide and tell the client
+        // analysis is pending, rather than returning an untrustworthy "transcode
+        // required" verdict that opens a doomed player.
+        let media_kind = row.media_kind.as_str();
+        let needs_analysis = row.metadata_json.is_none() && matches!(media_kind, "video" | "audio");
+        if needs_analysis {
+            return Ok(Some(PlaybackDecision {
+                item_id,
+                analysis_state: PlaybackAnalysisState::AwaitingAnalysis,
+                can_direct_play: false,
+                transcode_required: false,
+                reason: "This media has not been analyzed yet (ffprobe was \
+                         unavailable during scan). Set the ffprobe path in \
+                         Settings and re-probe media info."
+                    .into(),
+                stream_url: None,
+                mime_type: None,
+                transcode_container: None,
+                transcode_video_codec: None,
+                transcode_audio_codec: None,
+                video_transcode_required: false,
+                audio_transcode_required: false,
+                source_video_codec: row.video_codec,
+                source_audio_codec: row.audio_codec,
+                source_container: row.container,
+            }));
+        }
+
         let default_profile = ClientProfile {
             client_type: "web".into(),
             client_name: "Web".into(),
@@ -3165,6 +3368,7 @@ pub fn get_playback_decision(
 
         PlaybackDecision {
             item_id,
+            analysis_state: PlaybackAnalysisState::Analyzed,
             can_direct_play,
             transcode_required: item.playable && !can_direct_play,
             reason: if can_direct_play {
@@ -3186,6 +3390,7 @@ pub fn get_playback_decision(
     } else {
         PlaybackDecision {
             item_id,
+            analysis_state: PlaybackAnalysisState::Analyzed,
             can_direct_play: false,
             transcode_required: false,
             reason: "This item is a container and cannot be played directly.".into(),
diff --git a/crates/server/src/metadata/mod.rs b/crates/server/src/metadata/mod.rs
index bd211040..bd10c8f7 100644
--- a/crates/server/src/metadata/mod.rs
+++ b/crates/server/src/metadata/mod.rs
@@ -2,79 +2,38 @@
 
 // standard imports
 use std::collections::hash_map::DefaultHasher;
-use std::collections::{
-    HashMap,
-    HashSet,
-};
+use std::collections::{HashMap, HashSet};
 use std::fs;
-use std::hash::{
-    Hash,
-    Hasher,
-};
-use std::path::{
-    Path,
-    PathBuf,
-};
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
 use std::time::Duration;
 
 // lib imports
 use diesel::{
-    BoolExpressionMethods,
-    ExpressionMethods,
-    JoinOnDsl,
-    OptionalExtension,
-    QueryDsl,
-    RunQueryDsl,
-    SelectableHelper,
-    SqliteConnection,
+    BoolExpressionMethods, ExpressionMethods, JoinOnDsl, OptionalExtension, QueryDsl, RunQueryDsl,
+    SelectableHelper, SqliteConnection,
 };
 use once_cell::sync::Lazy;
 use regex::Regex;
 use schemars::JsonSchema;
-use serde::{
-    Deserialize,
-    Serialize,
-};
-use sha2::{
-    Digest,
-    Sha256,
-};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
 use strsim::normalized_levenshtein;
 
 mod providers;
-pub use providers::{
-    MetadataProvider,
-    MetadataRegistry,
-};
+pub use providers::{MetadataProvider, MetadataRegistry};
 
 // local imports
 use crate::config::{
-    MediaLibraryKind,
-    MetadataProviderId,
-    MetadataProviderSettings,
-    MetadataSettings,
-    metadata_provider_api_key_configured,
-    resolve_metadata_provider_api_key,
+    MediaLibraryKind, MetadataProviderId, MetadataProviderSettings, MetadataSettings,
+    metadata_provider_api_key_configured, resolve_metadata_provider_api_key,
 };
 use crate::db::configure_sqlite_connection;
 use crate::db::models::{
-    ExternalMedia,
-    ItemMetadataLink,
-    MediaItem,
-    MetadataCollection,
-    MetadataCollectionItem,
-    MetadataExtra,
-    MetadataPerson,
-    MetadataPersonCredit,
-    NewExternalMedia,
-    NewItemMetadataExternalId,
-    NewItemMetadataLink,
-    NewItemMetadataPerson,
-    NewMetadataCollection,
-    NewMetadataCollectionItem,
-    NewMetadataExtra,
-    NewMetadataPerson,
-    NewMetadataPersonCredit,
+    ExternalMedia, ItemMetadataLink, MediaItem, MetadataCollection, MetadataCollectionItem,
+    MetadataExtra, MetadataPerson, MetadataPersonCredit, NewExternalMedia,
+    NewItemMetadataExternalId, NewItemMetadataLink, NewItemMetadataPerson, NewMetadataCollection,
+    NewMetadataCollectionItem, NewMetadataExtra, NewMetadataPerson, NewMetadataPersonCredit,
     NewMetadataPersonExternalId,
 };
 use crate::utils::current_timestamp;
diff --git a/crates/server/src/metadata/providers/mod.rs b/crates/server/src/metadata/providers/mod.rs
index bf1c1110..6d0f0364 100644
--- a/crates/server/src/metadata/providers/mod.rs
+++ b/crates/server/src/metadata/providers/mod.rs
@@ -6,22 +6,11 @@ pub(crate) mod tvdb;
 use std::future::Future;
 use std::pin::Pin;
 
-use crate::config::{
-    MediaLibraryKind,
-    MetadataProviderId,
-    MetadataSettings,
-};
+use crate::config::{MediaLibraryKind, MetadataProviderId, MetadataSettings};
 use crate::metadata::{
-    MetadataItemKind,
-    MetadataProviderDescriptor,
-    MetadataProviderRole,
-    MetadataSearchResult,
-    ProviderDescendantTarget,
-    ProviderMetadataCollection,
-    ProviderMetadataDetails,
-    ProviderMetadataPerson,
-    StoredMetadataSnapshot,
-    normalize_locale_key,
+    MetadataItemKind, MetadataProviderDescriptor, MetadataProviderRole, MetadataSearchResult,
+    ProviderDescendantTarget, ProviderMetadataCollection, ProviderMetadataDetails,
+    ProviderMetadataPerson, StoredMetadataSnapshot, normalize_locale_key,
 };
 
 /// Boxed async result returned by metadata provider operations.
diff --git a/crates/server/src/metadata/providers/themerr.rs b/crates/server/src/metadata/providers/themerr.rs
index 43524809..94136dba 100644
--- a/crates/server/src/metadata/providers/themerr.rs
+++ b/crates/server/src/metadata/providers/themerr.rs
@@ -2,13 +2,8 @@ use serde_json::Value;
 
 use crate::config::MetadataProviderId;
 use crate::metadata::{
-    METADATA_EXTRA_TYPE_THEME_SONG,
-    MediaLibraryKind,
-    MetadataProviderDescriptor,
-    MetadataProviderRole,
-    ProviderMetadataDetails,
-    ProviderMetadataExtra,
-    youtube_watch_url,
+    METADATA_EXTRA_TYPE_THEME_SONG, MediaLibraryKind, MetadataProviderDescriptor,
+    MetadataProviderRole, ProviderMetadataDetails, ProviderMetadataExtra, youtube_watch_url,
 };
 
 const THEMERR_API_BASE: &str = "https://app.lizardbyte.dev/ThemerrDB";
@@ -209,9 +204,7 @@ fn text_field(
 #[cfg(test)]
 mod tests {
     use super::{
-        database_path_for_item_type,
-        item_lookup_reference_priority,
-        normalize_database_id,
+        database_path_for_item_type, item_lookup_reference_priority, normalize_database_id,
         parse_youtube_theme_url,
     };
     use crate::config::MetadataProviderId;
diff --git a/crates/server/src/metadata/providers/tmdb.rs b/crates/server/src/metadata/providers/tmdb.rs
index 3c2ac407..619afeeb 100644
--- a/crates/server/src/metadata/providers/tmdb.rs
+++ b/crates/server/src/metadata/providers/tmdb.rs
@@ -1,52 +1,21 @@
-use std::collections::{
-    HashMap,
-    HashSet,
-};
+use std::collections::{HashMap, HashSet};
 use std::sync::Mutex;
 
 use once_cell::sync::Lazy;
 use serde_json::Value;
 use strsim::normalized_levenshtein;
 use tmdb_client::apis::client::APIClient as TmdbApiClient;
-use tmdb_client::models::{
-    EpisodeDetails,
-    MovieDetails,
-    MovieObject,
-    SeasonDetails,
-    TvDetails,
-};
+use tmdb_client::models::{EpisodeDetails, MovieDetails, MovieObject, SeasonDetails, TvDetails};
 
-use crate::config::{
-    MetadataProviderId,
-    MetadataProviderSettings,
-    MetadataSettings,
-};
+use crate::config::{MetadataProviderId, MetadataProviderSettings, MetadataSettings};
 use crate::metadata::{
-    MediaLibraryKind,
-    MetadataItemKind,
-    MetadataProviderDescriptor,
-    MetadataProviderRole,
-    MetadataSearchResult,
-    ProviderDescendantTarget,
-    ProviderExternalId,
-    ProviderMetadataCollection,
-    ProviderMetadataDetails,
-    ProviderMetadataPerson,
-    StoredMetadataSnapshot,
-    cleanup_movie_title,
-    extract_release_year,
-    managed_metadata_asset_dir,
-    metadata_asset_db_path,
-    metadata_response_cache_key,
-    movie_match_score,
-    normalize_external_id_source,
-    parse_movie_name,
-    preferred_image_url_by_format,
-    provider_settings,
-    read_metadata_response_cache_text,
-    show_search_query,
-    try_cache_item_artwork,
-    write_metadata_response_cache_text,
+    MediaLibraryKind, MetadataItemKind, MetadataProviderDescriptor, MetadataProviderRole,
+    MetadataSearchResult, ProviderDescendantTarget, ProviderExternalId, ProviderMetadataCollection,
+    ProviderMetadataDetails, ProviderMetadataPerson, StoredMetadataSnapshot, cleanup_movie_title,
+    extract_release_year, managed_metadata_asset_dir, metadata_asset_db_path,
+    metadata_response_cache_key, movie_match_score, normalize_external_id_source, parse_movie_name,
+    preferred_image_url_by_format, provider_settings, read_metadata_response_cache_text,
+    show_search_query, try_cache_item_artwork, write_metadata_response_cache_text,
 };
 
 const TMDB_IMAGE_BASE: &str = "https://image.tmdb.org/t/p";
@@ -1764,16 +1733,9 @@ fn sort_and_dedupe_people(people: Vec<ProviderMetadataPerson>) -> Vec<ProviderMe
 
 #[cfg(test)]
 mod tests {
-    use super::{
-        metadata_details,
-        metadata_item_kind,
-        tmdb_logo_url,
-    };
+    use super::{metadata_details, metadata_item_kind, tmdb_logo_url};
     use crate::config::MetadataProviderId;
-    use crate::metadata::{
-        MetadataItemKind,
-        StoredMetadataSnapshot,
-    };
+    use crate::metadata::{MetadataItemKind, StoredMetadataSnapshot};
     use serde_json::json;
 
     #[test]
diff --git a/crates/server/src/metadata/providers/trailerdb.rs b/crates/server/src/metadata/providers/trailerdb.rs
index 112e6dbd..cbca5ef9 100644
--- a/crates/server/src/metadata/providers/trailerdb.rs
+++ b/crates/server/src/metadata/providers/trailerdb.rs
@@ -2,15 +2,9 @@ use serde_json::Value;
 
 use crate::config::MetadataProviderId;
 use crate::metadata::{
-    METADATA_EXTRA_TYPE_TRAILER,
-    MediaLibraryKind,
-    MetadataProviderDescriptor,
-    MetadataProviderRole,
-    ProviderMetadataDetails,
-    ProviderMetadataExtra,
-    normalize_locale_key,
-    normalize_metadata_extra_type,
-    youtube_watch_url,
+    METADATA_EXTRA_TYPE_TRAILER, MediaLibraryKind, MetadataProviderDescriptor,
+    MetadataProviderRole, ProviderMetadataDetails, ProviderMetadataExtra, normalize_locale_key,
+    normalize_metadata_extra_type, youtube_watch_url,
 };
 
 const TRAILERDB_DATA_BASE: &str = "https://trailerdb.org/data";
@@ -246,10 +240,7 @@ fn int_field(
 
 #[cfg(test)]
 mod tests {
-    use super::{
-        parse_youtube_trailer,
-        trailerdb_path,
-    };
+    use super::{parse_youtube_trailer, trailerdb_path};
 
     #[test]
     fn movie_lookup_uses_imdb_detail_endpoint() {
diff --git a/crates/server/src/metadata/providers/tvdb.rs b/crates/server/src/metadata/providers/tvdb.rs
index 59f355cb..f690b4d1 100644
--- a/crates/server/src/metadata/providers/tvdb.rs
+++ b/crates/server/src/metadata/providers/tvdb.rs
@@ -1,47 +1,20 @@
 use serde_json::Value;
 use strsim::normalized_levenshtein;
-use tvdb4::apis::{
-    self,
-    login_api,
-};
+use tvdb4::apis::{self, login_api};
 use tvdb4::models::LoginPostRequest;
 
-use crate::config::{
-    MetadataProviderId,
-    MetadataProviderSettings,
-    MetadataSettings,
-};
+use crate::config::{MetadataProviderId, MetadataProviderSettings, MetadataSettings};
 use crate::metadata::{
-    MediaLibraryKind,
-    MetadataItemKind,
-    MetadataProviderDescriptor,
-    MetadataProviderRole,
-    MetadataSearchResult,
-    ProviderDescendantTarget,
-    ProviderExternalId,
-    ProviderMetadataDetails,
-    ProviderMetadataPerson,
-    StoredMetadataSnapshot,
-    cleanup_movie_title,
-    extract_release_year,
-    format_payload_snippet,
-    image_format_preference_rank,
-    managed_metadata_asset_dir,
-    metadata_asset_db_path,
-    metadata_response_cache_key,
-    movie_match_score,
-    normalize_external_id_source,
-    parse_movie_name,
-    provider_settings,
-    read_metadata_response_cache_text,
-    show_search_query,
-    try_cache_item_artwork,
+    MediaLibraryKind, MetadataItemKind, MetadataProviderDescriptor, MetadataProviderRole,
+    MetadataSearchResult, ProviderDescendantTarget, ProviderExternalId, ProviderMetadataDetails,
+    ProviderMetadataPerson, StoredMetadataSnapshot, cleanup_movie_title, extract_release_year,
+    format_payload_snippet, image_format_preference_rank, managed_metadata_asset_dir,
+    metadata_asset_db_path, metadata_response_cache_key, movie_match_score,
+    normalize_external_id_source, parse_movie_name, provider_settings,
+    read_metadata_response_cache_text, show_search_query, try_cache_item_artwork,
     write_metadata_response_cache_text,
 };
-use std::time::{
-    Duration,
-    Instant,
-};
+use std::time::{Duration, Instant};
 
 const TVDB_API_BASE: &str = "https://api4.thetvdb.com/v4";
 
@@ -2141,14 +2114,8 @@ fn episode_number(value: &Value) -> Option<i32> {
 #[cfg(test)]
 mod tests {
     use super::{
-        artwork_url,
-        backdrop_url,
-        best_overview,
-        metadata_details,
-        metadata_item_kind,
-        movie_snapshot_from_value,
-        search_result_from_value,
-        tvdb_logo_url,
+        artwork_url, backdrop_url, best_overview, metadata_details, metadata_item_kind,
+        movie_snapshot_from_value, search_result_from_value, tvdb_logo_url,
         tvdb_people_with_language,
     };
     use crate::metadata::MetadataItemKind;
diff --git a/crates/server/src/scanner/books.rs b/crates/server/src/scanner/books.rs
index 6e763aed..691595cd 100644
--- a/crates/server/src/scanner/books.rs
+++ b/crates/server/src/scanner/books.rs
@@ -1,18 +1,8 @@
 //! Book scanner rules.
 
-use crate::config::{
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-};
-use crate::scanner::directory::{
-    self,
-    ScannerRules,
-};
-use crate::scanner::{
-    LibraryInspection,
-    ScannerSink,
-};
+use crate::config::{MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings};
+use crate::scanner::directory::{self, ScannerRules};
+use crate::scanner::{LibraryInspection, ScannerSink};
 
 pub(crate) fn scan(library: &MediaLibrarySettings) -> LibraryInspection {
     directory::scan_with_rules(
diff --git a/crates/server/src/scanner/directory.rs b/crates/server/src/scanner/directory.rs
index a73e3007..bf8bb116 100644
--- a/crates/server/src/scanner/directory.rs
+++ b/crates/server/src/scanner/directory.rs
@@ -4,26 +4,15 @@ use std::collections::HashSet;
 use std::convert::Infallible;
 use std::fs;
 use std::io;
-use std::path::{
-    Path,
-    PathBuf,
-};
+use std::path::{Path, PathBuf};
 use std::time::UNIX_EPOCH;
 
 use imohash::Hasher as ImoHasher;
 
-use crate::config::{
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-};
+use crate::config::{MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings};
 use crate::scanner::{
-    DiscoveredMediaFile,
-    FileHashCandidate,
-    LibraryInspection,
-    LibraryScanStatus,
-    LibraryScanSummary,
-    ScannerSink,
+    DiscoveredMediaFile, FileHashCandidate, LibraryInspection, LibraryScanStatus,
+    LibraryScanSummary, ScannerSink,
 };
 
 #[derive(Debug, Default)]
diff --git a/crates/server/src/scanner/mod.rs b/crates/server/src/scanner/mod.rs
index 02fb934a..e373caed 100644
--- a/crates/server/src/scanner/mod.rs
+++ b/crates/server/src/scanner/mod.rs
@@ -8,19 +8,12 @@ pub mod photos;
 pub mod shows;
 
 use std::collections::HashSet;
-use std::path::{
-    Path,
-    PathBuf,
-};
+use std::path::{Path, PathBuf};
 
 use schemars::JsonSchema;
 use serde::Serialize;
 
-use crate::config::{
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-};
+use crate::config::{MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings};
 
 pub(crate) use directory::fallback_title_from_relative_path;
 
diff --git a/crates/server/src/scanner/movies.rs b/crates/server/src/scanner/movies.rs
index c6dcbe79..8b771c44 100644
--- a/crates/server/src/scanner/movies.rs
+++ b/crates/server/src/scanner/movies.rs
@@ -3,19 +3,9 @@
 use once_cell::sync::Lazy;
 use regex::Regex;
 
-use crate::config::{
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-};
-use crate::scanner::directory::{
-    self,
-    ScannerRules,
-};
-use crate::scanner::{
-    LibraryInspection,
-    ScannerSink,
-};
+use crate::config::{MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings};
+use crate::scanner::directory::{self, ScannerRules};
+use crate::scanner::{LibraryInspection, ScannerSink};
 
 pub(crate) fn scan(library: &MediaLibrarySettings) -> LibraryInspection {
     directory::scan_with_rules(
diff --git a/crates/server/src/scanner/music.rs b/crates/server/src/scanner/music.rs
index 8906280b..3fd83db1 100644
--- a/crates/server/src/scanner/music.rs
+++ b/crates/server/src/scanner/music.rs
@@ -1,18 +1,8 @@
 //! Music scanner rules.
 
-use crate::config::{
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-};
-use crate::scanner::directory::{
-    self,
-    ScannerRules,
-};
-use crate::scanner::{
-    LibraryInspection,
-    ScannerSink,
-};
+use crate::config::{MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings};
+use crate::scanner::directory::{self, ScannerRules};
+use crate::scanner::{LibraryInspection, ScannerSink};
 
 pub(crate) fn scan(library: &MediaLibrarySettings) -> LibraryInspection {
     directory::scan_with_rules(
diff --git a/crates/server/src/scanner/photos.rs b/crates/server/src/scanner/photos.rs
index 16a74df8..1b13d103 100644
--- a/crates/server/src/scanner/photos.rs
+++ b/crates/server/src/scanner/photos.rs
@@ -1,18 +1,8 @@
 //! Photo scanner rules.
 
-use crate::config::{
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-};
-use crate::scanner::directory::{
-    self,
-    ScannerRules,
-};
-use crate::scanner::{
-    LibraryInspection,
-    ScannerSink,
-};
+use crate::config::{MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings};
+use crate::scanner::directory::{self, ScannerRules};
+use crate::scanner::{LibraryInspection, ScannerSink};
 
 pub(crate) fn scan(library: &MediaLibrarySettings) -> LibraryInspection {
     directory::scan_with_rules(
diff --git a/crates/server/src/scanner/shows.rs b/crates/server/src/scanner/shows.rs
index a3ae9267..405cccd8 100644
--- a/crates/server/src/scanner/shows.rs
+++ b/crates/server/src/scanner/shows.rs
@@ -3,19 +3,9 @@
 use once_cell::sync::Lazy;
 use regex::Regex;
 
-use crate::config::{
-    MediaLibraryKind,
-    MediaLibraryScanner,
-    MediaLibrarySettings,
-};
-use crate::scanner::directory::{
-    self,
-    ScannerRules,
-};
-use crate::scanner::{
-    LibraryInspection,
-    ScannerSink,
-};
+use crate::config::{MediaLibraryKind, MediaLibraryScanner, MediaLibrarySettings};
+use crate::scanner::directory::{self, ScannerRules};
+use crate::scanner::{LibraryInspection, ScannerSink};
 
 /// Show, season, and episode fields derived from a library-relative episode path.
 #[derive(Debug, Clone, PartialEq, Eq)]
diff --git a/crates/server/src/scheduled_tasks/database_maintenance.rs b/crates/server/src/scheduled_tasks/database_maintenance.rs
index d529bd42..e8a178a0 100644
--- a/crates/server/src/scheduled_tasks/database_maintenance.rs
+++ b/crates/server/src/scheduled_tasks/database_maintenance.rs
@@ -8,11 +8,7 @@ use crate::config::ScheduledTasksSettings;
 use crate::db::DbConn;
 use crate::utils::current_timestamp;
 
-use super::{
-    ScheduledTask,
-    ScheduledTaskFuture,
-    save_scheduled_task_last_run,
-};
+use super::{ScheduledTask, ScheduledTaskFuture, save_scheduled_task_last_run};
 
 const LAST_RUN_KEY: &str = "scheduled_tasks.database_maintenance.last_run_at";
 
diff --git a/crates/server/src/scheduled_tasks/metadata_refresh.rs b/crates/server/src/scheduled_tasks/metadata_refresh.rs
index a5270605..fd6c60cc 100644
--- a/crates/server/src/scheduled_tasks/metadata_refresh.rs
+++ b/crates/server/src/scheduled_tasks/metadata_refresh.rs
@@ -1,16 +1,10 @@
 //! Scheduled metadata refresh task.
 
 // local imports
-use crate::config::{
-    ScheduledTasksSettings,
-    current_settings,
-};
+use crate::config::{ScheduledTasksSettings, current_settings};
 use crate::db::DbConn;
 
-use super::{
-    ScheduledTask,
-    ScheduledTaskFuture,
-};
+use super::{ScheduledTask, ScheduledTaskFuture};
 
 static TASK: MetadataRefreshTask = MetadataRefreshTask;
 
diff --git a/crates/server/src/scheduled_tasks/mod.rs b/crates/server/src/scheduled_tasks/mod.rs
index ee0be1ed..99320b98 100644
--- a/crates/server/src/scheduled_tasks/mod.rs
+++ b/crates/server/src/scheduled_tasks/mod.rs
@@ -6,11 +6,7 @@ mod metadata_refresh;
 mod trash_cleanup;
 
 // lib imports
-use chrono::{
-    Datelike,
-    Local,
-    Timelike,
-};
+use chrono::{Datelike, Local, Timelike};
 use diesel::ExpressionMethods;
 use diesel::OptionalExtension;
 use diesel::QueryDsl;
@@ -19,17 +15,10 @@ use diesel::SelectableHelper;
 use once_cell::sync::Lazy;
 use std::future::Future;
 use std::pin::Pin;
-use std::sync::atomic::{
-    AtomicBool,
-    Ordering,
-};
+use std::sync::atomic::{AtomicBool, Ordering};
 
 // local imports
-use crate::config::{
-    ScheduledTaskWeekday,
-    ScheduledTasksSettings,
-    current_settings,
-};
+use crate::config::{ScheduledTaskWeekday, ScheduledTasksSettings, current_settings};
 use crate::db::DbConn;
 use crate::db::models::AppSetting;
 
diff --git a/crates/server/src/scheduled_tasks/trash_cleanup.rs b/crates/server/src/scheduled_tasks/trash_cleanup.rs
index 1d75326c..f5d10e62 100644
--- a/crates/server/src/scheduled_tasks/trash_cleanup.rs
+++ b/crates/server/src/scheduled_tasks/trash_cleanup.rs
@@ -6,11 +6,7 @@ use crate::db::DbConn;
 use crate::media::delete_missing_media_items;
 use crate::utils::current_timestamp;
 
-use super::{
-    ScheduledTask,
-    ScheduledTaskFuture,
-    save_scheduled_task_last_run,
-};
+use super::{ScheduledTask, ScheduledTaskFuture, save_scheduled_task_last_run};
 
 const LAST_RUN_KEY: &str = "scheduled_tasks.trash_cleanup.last_run_at";
 
diff --git a/crates/server/src/secrets.rs b/crates/server/src/secrets.rs
index a9029261..46ce667e 100644
--- a/crates/server/src/secrets.rs
+++ b/crates/server/src/secrets.rs
@@ -5,11 +5,7 @@ use std::collections::HashMap;
 use std::sync::Mutex;
 
 // lib imports
-use keyring_core::{
-    Entry,
-    Error,
-    set_default_store,
-};
+use keyring_core::{Entry, Error, set_default_store};
 use once_cell::sync::Lazy;
 
 // local imports
diff --git a/crates/server/src/signal_handler.rs b/crates/server/src/signal_handler.rs
index 89dc5f95..62419e47 100644
--- a/crates/server/src/signal_handler.rs
+++ b/crates/server/src/signal_handler.rs
@@ -1,10 +1,7 @@
 //! Signal handling utilities for graceful shutdown.
 
 use std::sync::Arc;
-use std::sync::atomic::{
-    AtomicBool,
-    Ordering,
-};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::thread::JoinHandle;
 use std::time::Duration;
 
diff --git a/crates/server/src/tray.rs b/crates/server/src/tray.rs
index 095373ba..8dc72488 100644
--- a/crates/server/src/tray.rs
+++ b/crates/server/src/tray.rs
@@ -1,33 +1,19 @@
 //! Tray icon utilities for the application.
 
 // standard imports
-use std::path::{
-    Path,
-    PathBuf,
-};
+use std::path::{Path, PathBuf};
 
 // lib imports
 #[cfg(target_os = "windows")]
 use tao::platform::windows::EventLoopBuilderExtWindows;
 use tao::{
     event::Event,
-    event_loop::{
-        ControlFlow,
-        EventLoopBuilder,
-    },
+    event_loop::{ControlFlow, EventLoopBuilder},
     platform::run_return::EventLoopExtRunReturn,
 };
 use tray_icon::{
-    TrayIconBuilder,
-    TrayIconEvent,
-    menu::{
-        AboutMetadata,
-        Menu,
-        MenuEvent,
-        MenuItem,
-        PredefinedMenuItem,
-        Submenu,
-    },
+    TrayIconBuilder, TrayIconEvent,
+    menu::{AboutMetadata, Menu, MenuEvent, MenuItem, PredefinedMenuItem, Submenu},
 };
 
 // local imports
diff --git a/crates/server/src/web/mod.rs b/crates/server/src/web/mod.rs
index d8f2ef10..490adeb6 100644
--- a/crates/server/src/web/mod.rs
+++ b/crates/server/src/web/mod.rs
@@ -10,25 +10,14 @@ use rocket::config::TlsConfig;
 use rocket::fairing::AdHoc;
 use rocket::figment::Figment;
 use rocket_okapi::settings::UrlObject;
-use rocket_okapi::{
-    rapidoc::*,
-    swagger_ui::*,
-};
+use rocket_okapi::{rapidoc::*, swagger_ui::*};
 
 // local imports
 use crate::certs;
 use crate::config::{
-    current_settings,
-    load_database_settings,
-    replace_current_settings,
-    seed_database_settings,
-};
-use crate::db::{
-    DbConn,
-    Migrate,
-    ReleaseDatabase,
-    initialize_sqlite_database,
+    current_settings, load_database_settings, replace_current_settings, seed_database_settings,
 };
+use crate::db::{DbConn, Migrate, ReleaseDatabase, initialize_sqlite_database};
 use crate::globals;
 use crate::signal_handler::ShutdownSignal;
 
@@ -143,6 +132,27 @@ pub fn rocket_with_db_path(custom_db_path: Option<String>) -> rocket::Rocket<roc
                         );
                     }
                 }
+
+                // Startup trigger: if ffprobe is now available and media files
+                // were scanned while it was missing, re-probe them automatically.
+                let reprobe_db = DbConn::get_one(rocket).await;
+                match reprobe_db {
+                    Some(reprobe_db) => {
+                        rocket::tokio::spawn(async move {
+                            let settings = crate::config::current_settings();
+                            crate::web::routes::media::try_spawn_reprobe(
+                                reprobe_db,
+                                settings.ffmpeg.clone(),
+                            )
+                            .await;
+                        });
+                    }
+                    None => {
+                        log::error!(
+                            "Failed to acquire database connection for ffprobe re-probe startup"
+                        );
+                    }
+                }
             })
         }))
         .mount("/", routes::api_routes())
diff --git a/crates/server/src/web/routes/auth.rs b/crates/server/src/web/routes/auth.rs
index f66c0338..01fcaf5e 100644
--- a/crates/server/src/web/routes/auth.rs
+++ b/crates/server/src/web/routes/auth.rs
@@ -3,31 +3,15 @@
 // lib imports
 use diesel::QueryDsl;
 use diesel::RunQueryDsl;
-use diesel::{
-    ExpressionMethods,
-    SelectableHelper,
-};
+use diesel::{ExpressionMethods, SelectableHelper};
 use rocket::http::Status;
-use rocket::serde::{
-    Deserialize,
-    Serialize,
-    json::Json,
-};
-use rocket::{
-    get,
-    post,
-};
-use rocket_okapi::{
-    JsonSchema,
-    openapi,
-};
+use rocket::serde::{Deserialize, Serialize, json::Json};
+use rocket::{get, post};
+use rocket_okapi::{JsonSchema, openapi};
 use serde_json::json;
 
 // local imports
-use crate::auth::{
-    AdminGuard,
-    UserGuard,
-};
+use crate::auth::{AdminGuard, UserGuard};
 use crate::db::DbConn;
 use crate::db::models::User;
 
diff --git a/crates/server/src/web/routes/common.rs b/crates/server/src/web/routes/common.rs
index ed9a9293..a0e1cd5a 100644
--- a/crates/server/src/web/routes/common.rs
+++ b/crates/server/src/web/routes/common.rs
@@ -2,18 +2,12 @@
 
 // standard imports
 use std::env;
-use std::path::{
-    Path,
-    PathBuf,
-};
+use std::path::{Path, PathBuf};
 
 // lib imports
 use rocket::fs::NamedFile;
 use rocket::get;
-use rocket::http::uri::{
-    Segments,
-    fmt::Path as UriPath,
-};
+use rocket::http::uri::{Segments, fmt::Path as UriPath};
 use rocket::response::content::RawHtml;
 
 // local imports
diff --git a/crates/server/src/web/routes/media.rs b/crates/server/src/web/routes/media.rs
index 358b759e..ff52500f 100644
--- a/crates/server/src/web/routes/media.rs
+++ b/crates/server/src/web/routes/media.rs
@@ -508,6 +508,10 @@ static ACTIVE_METADATA_REFRESH_EXECUTIONS: Lazy<tokio::sync::RwLock<HashSet<i32>
 static ACTIVE_LIBRARY_METADATA_REFRESHES: Lazy<tokio::sync::RwLock<HashSet<i32>>> =
     Lazy::new(|| tokio::sync::RwLock::new(HashSet::new()));
 static ACTIVE_MANUAL_CATALOG_SCAN_RUNNING: Lazy<AtomicBool> = Lazy::new(|| AtomicBool::new(false));
+/// Gate for the ffprobe re-probe job. Shares the scan-gate semantics: a re-probe
+/// and a manual scan cannot run simultaneously (avoids concurrent SQLite writes
+/// and double ffprobe load). Either can start when the other isn't running.
+static ACTIVE_REPROBE_RUNNING: Lazy<AtomicBool> = Lazy::new(|| AtomicBool::new(false));
 static ACTIVE_PLAYBACK_SESSIONS: Lazy<
     tokio::sync::RwLock<HashMap<String, crate::media::PlaybackSession>>,
 > = Lazy::new(|| tokio::sync::RwLock::new(HashMap::new()));
@@ -556,6 +560,149 @@ fn finish_catalog_scan_execution() {
     ACTIVE_MANUAL_CATALOG_SCAN_RUNNING.store(false, Ordering::SeqCst);
 }
 
+fn begin_reprobe_execution() -> bool {
+    // A re-probe and a manual scan can't run at the same time; both gates must be free.
+    if !begin_catalog_scan_execution() {
+        return false;
+    }
+    if ACTIVE_REPROBE_RUNNING
+        .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+        .is_err()
+    {
+        finish_catalog_scan_execution();
+        return false;
+    }
+    true
+}
+
+fn finish_reprobe_execution() {
+    ACTIVE_REPROBE_RUNNING.store(false, Ordering::SeqCst);
+    finish_catalog_scan_execution();
+}
+
+async fn register_reprobe_activity(total_items: usize) -> String {
+    let activity_id = next_system_activity_id();
+    let now = current_timestamp();
+    ACTIVE_SYSTEM_ACTIVITIES.write().await.insert(
+        activity_id.clone(),
+        MetadataRefreshActivityRecord {
+            activity: SystemActivity {
+                id: activity_id.clone(),
+                category: "media_reprobe".into(),
+                scope: "system".into(),
+                source: "ffprobe".into(),
+                state: "running".into(),
+                label: "Re-probe media info (ffprobe now available)".into(),
+                provider_id: None,
+                library_id: None,
+                root_item_id: None,
+                item_ids: Vec::new(),
+                total_items: i32::try_from(total_items).unwrap_or(i32::MAX),
+                completed_items: 0,
+                failed_items: 0,
+                queued_at: now,
+                started_at: Some(now),
+                updated_at: now,
+            },
+        },
+    );
+    activity_id
+}
+
+async fn complete_reprobe_activity(
+    activity_id: &str,
+    outcome: &crate::media::ReprobeOutcome,
+) {
+    if let Some(record) = ACTIVE_SYSTEM_ACTIVITIES.write().await.get_mut(activity_id) {
+        record.activity.state = if outcome.failed > 0 && outcome.updated == 0 {
+            "failed".into()
+        } else {
+            "completed".into()
+        };
+        record.activity.completed_items = i32::try_from(outcome.updated).unwrap_or(i32::MAX);
+        record.activity.failed_items = i32::try_from(outcome.failed).unwrap_or(i32::MAX);
+        record.activity.updated_at = current_timestamp();
+    }
+}
+
+/// Whether a re-probe job is currently running.
+pub fn reprobe_in_progress() -> bool {
+    ACTIVE_REPROBE_RUNNING.load(Ordering::SeqCst)
+}
+
+/// Try to start a background ffprobe re-probe if there are unanalyzed media
+/// files and ffprobe is available. Returns true if a job was started, false if
+/// skipped (already running, a scan is running, ffprobe unavailable, or no
+/// candidates). Safe to call from any trigger (startup, settings change, manual).
+///
+/// This is the single entry point for all three re-probe triggers; it owns the
+/// gate, the activity record, and the per-file progress updates.
+pub async fn try_spawn_reprobe(
+    db: DbConn,
+    ffmpeg_settings: crate::config::FfmpegSettings,
+) -> bool {
+    if !begin_reprobe_execution() {
+        log::debug!("Re-probe not started: another scan or re-probe is already running");
+        return false;
+    }
+
+    // ffprobe availability is re-checked inside reprobe_media_files, but we also
+    // check here to avoid a pointless job and a spurious activity record.
+    if !crate::media::inspect_transcoding_capability(&ffmpeg_settings)
+        .ffprobe
+        .available
+    {
+        log::debug!("Re-probe not started: ffprobe is not available");
+        finish_reprobe_execution();
+        return false;
+    }
+
+    tokio::spawn(async move {
+        // Count + reprobe share the single DbConn (it isn't Clone), so both run
+        // inside one db.run closure. The activity is registered after the count
+        // (it needs total_items) and completed after the reprobe.
+        let outcome_with_total = db
+            .run(
+                move |conn| -> Result<(crate::media::ReprobeOutcome, i64), diesel::result::Error> {
+                    let total = crate::media::count_media_files_needing_reprobe(conn)?;
+                    if total == 0 {
+                        return Ok((crate::media::ReprobeOutcome::default(), 0));
+                    }
+                    let outcome =
+                        crate::media::reprobe_media_files(conn, &ffmpeg_settings, |_| {})?;
+                    Ok((outcome, total))
+                },
+            )
+            .await;
+
+        match outcome_with_total {
+            Ok((_outcome, total)) if total == 0 => {
+                log::debug!("Re-probe: no media files needed re-probing");
+            }
+            Ok((outcome, total)) => {
+                log::info!(
+                    "Starting ffprobe re-probe of {} unanalyzed media file(s)",
+                    total
+                );
+                let activity_id =
+                    register_reprobe_activity(usize::try_from(total).unwrap_or(usize::MAX)).await;
+                complete_reprobe_activity(&activity_id, &outcome).await;
+                log::info!(
+                    "ffprobe re-probe complete: inspected={}, updated={}, failed={}",
+                    outcome.inspected,
+                    outcome.updated,
+                    outcome.failed
+                );
+            }
+            Err(error) => {
+                log::error!("ffprobe re-probe failed: {error}");
+            }
+        }
+        finish_reprobe_execution();
+    });
+    true
+}
+
 fn metadata_refresh_interval_seconds(settings: &Settings) -> Option<i64> {
     settings
         .metadata
@@ -3186,6 +3333,51 @@ pub async fn get_session_status(session_id: String) -> Result<Json<SessionStatus
     Ok(Json(SessionStatusResponse { error }))
 }
 
+/// Response describing how many media files still need ffprobe re-analysis.
+#[derive(Debug, Clone, Serialize, JsonSchema, PartialEq, Eq)]
+pub struct ReprobeStatusResponse {
+    /// Whether a re-probe job is currently running.
+    pub in_progress: bool,
+    /// Count of media files with NULL metadata_json (scanned without ffprobe).
+    pub pending_count: i64,
+}
+
+/// Return whether a ffprobe re-probe is running and how many files await it.
+#[openapi(tag = "Media")]
+#[get("/api/v1/system/tools/reprobe")]
+pub async fn get_reprobe_status(
+    db: DbConn,
+    _admin_guard: AdminGuard,
+) -> Result<Json<ReprobeStatusResponse>, Status> {
+    let pending_count = db
+        .run(move |conn| crate::media::count_media_files_needing_reprobe(conn))
+        .await
+        .map_err(|error| {
+            log::error!("Failed to count media files needing reprobe: {error}");
+            Status::InternalServerError
+        })?;
+    Ok(Json(ReprobeStatusResponse {
+        in_progress: reprobe_in_progress(),
+        pending_count,
+    }))
+}
+
+/// Manually trigger a ffprobe re-probe of all unanalyzed media files. Admin-only.
+#[openapi(tag = "Media")]
+#[post("/api/v1/system/tools/reprobe")]
+pub async fn trigger_reprobe(
+    db: DbConn,
+    _admin_guard: AdminGuard,
+) -> Result<Json<ReprobeStatusResponse>, Status> {
+    let settings = current_settings();
+    try_spawn_reprobe(db, settings.ffmpeg.clone()).await;
+    Ok(Json(ReprobeStatusResponse {
+        in_progress: reprobe_in_progress(),
+        // The count is best-effort here; if the job just started it'll trend to 0.
+        pending_count: 0,
+    }))
+}
+
 /// Trigger a full catalog scan and return the updated summary for one library.
 #[openapi(tag = "Media")]
 #[post("/api/v1/libraries/<library_id>/scan")]
diff --git a/crates/server/src/web/routes/mod.rs b/crates/server/src/web/routes/mod.rs
index 4b0d980e..37591367 100644
--- a/crates/server/src/web/routes/mod.rs
+++ b/crates/server/src/web/routes/mod.rs
@@ -22,6 +22,8 @@ pub fn api_routes() -> Vec<rocket::Route> {
         dependencies::get_dependencies,
         media::get_server_capabilities,
         media::discover_transcoding_tools,
+        media::get_reprobe_status,
+        media::trigger_reprobe,
         media::get_system_activities,
         media::get_metadata_providers,
         media::get_metadata_locales,
diff --git a/crates/server/src/web/routes/settings.rs b/crates/server/src/web/routes/settings.rs
index 2a1db66a..b67c5c02 100644
--- a/crates/server/src/web/routes/settings.rs
+++ b/crates/server/src/web/routes/settings.rs
@@ -1,14 +1,7 @@
 //! Settings and library-management routes.
 
 // lib imports
-use chrono::{
-    DateTime,
-    Local,
-    LocalResult,
-    NaiveDate,
-    NaiveDateTime,
-    TimeZone,
-};
+use chrono::{DateTime, Local, LocalResult, NaiveDate, NaiveDateTime, TimeZone};
 use once_cell::sync::Lazy;
 use regex::Regex;
 use rocket::delete;
@@ -19,35 +12,19 @@ use rocket::put;
 use rocket::serde::json::Json;
 use rocket_okapi::openapi;
 use schemars::JsonSchema;
-use serde::{
-    Deserialize,
-    Serialize,
-};
+use serde::{Deserialize, Serialize};
 
 // local imports
 use crate::config::{
-    MediaLibrarySettings,
-    Settings,
-    current_settings,
-    merge_metadata_provider_secret_state,
-    replace_current_settings,
-    save_database_settings,
-    save_settings,
-    settings_file_path,
-    settings_for_api_response,
-    settings_with_persisted_secrets,
+    MediaLibrarySettings, Settings, current_settings, merge_metadata_provider_secret_state,
+    replace_current_settings, save_database_settings, save_settings, settings_file_path,
+    settings_for_api_response, settings_with_persisted_secrets,
 };
 use crate::db::DbConn;
 use crate::globals;
-use crate::logging::{
-    normalize_display_path,
-    normalize_log_source_path,
-};
+use crate::logging::{normalize_display_path, normalize_log_source_path};
 use crate::media::{
-    add_library_setting,
-    count_persisted_libraries,
-    list_library_settings,
-    remove_library_setting,
+    add_library_setting, count_persisted_libraries, list_library_settings, remove_library_setting,
     replace_library_settings,
 };
 
diff --git a/crates/server/src/web/routes/user.rs b/crates/server/src/web/routes/user.rs
index 7bc26a03..84bf26b6 100644
--- a/crates/server/src/web/routes/user.rs
+++ b/crates/server/src/web/routes/user.rs
@@ -1,55 +1,27 @@
 // lib imports
-use std::path::{
-    Path,
-    PathBuf,
-};
+use std::path::{Path, PathBuf};
 use std::sync::atomic::Ordering;
-use std::time::{
-    SystemTime,
-    UNIX_EPOCH,
-};
-
-use base64::{
-    Engine as _,
-    engine::general_purpose,
-};
-use diesel::{
-    ExpressionMethods,
-    OptionalExtension,
-    QueryDsl,
-    RunQueryDsl,
-    SelectableHelper,
-};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use base64::{Engine as _, engine::general_purpose};
+use diesel::{ExpressionMethods, OptionalExtension, QueryDsl, RunQueryDsl, SelectableHelper};
 use rocket::fs::NamedFile;
 use rocket::get;
 use rocket::http::Status;
 use rocket::post;
 use rocket::put;
-use rocket::serde::{
-    Deserialize,
-    Serialize,
-    json::Json,
-};
+use rocket::serde::{Deserialize, Serialize, json::Json};
 use rocket::tokio::fs;
 use rocket_okapi::JsonSchema;
 use rocket_okapi::openapi;
-use sha2::{
-    Digest,
-    Sha256,
-};
+use sha2::{Digest, Sha256};
 
 // local imports
-use crate::auth::{
-    AdminGuard,
-    UserGuard,
-};
+use crate::auth::{AdminGuard, UserGuard};
 use crate::config::current_settings;
 use crate::db::DbConn;
 use crate::db::models::User;
-use crate::globals::{
-    CURRENT_ENV,
-    Environment,
-};
+use crate::globals::{CURRENT_ENV, Environment};
 
 const PROFILE_IMAGE_MAX_BYTES: usize = 2 * 1024 * 1024;
 const PROFILE_IMAGE_ROUTE_PREFIX: &str = "/api/v1/user-profile-images/";
diff --git a/crates/server/tests/fixtures/mod.rs b/crates/server/tests/fixtures/mod.rs
index 508dddce..885252a8 100644
--- a/crates/server/tests/fixtures/mod.rs
+++ b/crates/server/tests/fixtures/mod.rs
@@ -16,10 +16,7 @@ use koko::globals::CURRENT_ENV;
 use koko::web::rocket;
 
 // test imports
-use crate::test_utils::{
-    TestResponse,
-    make_request,
-};
+use crate::test_utils::{TestResponse, make_request};
 
 pub struct TestDb {
     pub client: Client,
diff --git a/crates/server/tests/test_auth.rs b/crates/server/tests/test_auth.rs
index 9923b4fe..97b250b3 100644
--- a/crates/server/tests/test_auth.rs
+++ b/crates/server/tests/test_auth.rs
@@ -1,21 +1,12 @@
 //! Authentication tests for the application.
 
 // lib imports
-use chrono::{
-    Duration,
-    Utc,
-};
+use chrono::{Duration, Utc};
 use rstest::rstest;
 
 // local imports
 use koko::auth::{
-    AdminGuard,
-    AuthGuard,
-    UserGuard,
-    create_token,
-    decode_token,
-    hash_password,
-    verify_password,
+    AdminGuard, AuthGuard, UserGuard, create_token, decode_token, hash_password, verify_password,
 };
 
 #[rstest]
diff --git a/crates/server/tests/test_metadata.rs b/crates/server/tests/test_metadata.rs
index 477392dd..a4191bc3 100644
--- a/crates/server/tests/test_metadata.rs
+++ b/crates/server/tests/test_metadata.rs
@@ -4,32 +4,15 @@ use diesel::RunQueryDsl;
 use diesel::connection::SimpleConnection;
 use diesel::sql_types::Text;
 use koko::config::{
-    DatabaseMaintenanceTaskSettings,
-    FfmpegSettings,
-    MediaLibraryKind,
-    MediaLibrarySettings,
-    MetadataProviderId,
-    MetadataProviderSettings,
-    MetadataRefreshTaskSettings,
-    MetadataSettings,
-    ScheduledTaskWeekday,
-    ScheduledTaskWindowSettings,
-    ScheduledTasksSettings,
-    Settings,
-    TrashCleanupTaskSettings,
-    load_database_settings,
-    save_database_settings,
-    seed_database_settings,
-    settings_for_persistence,
-    settings_yaml_for_persistence,
+    DatabaseMaintenanceTaskSettings, FfmpegSettings, MediaLibraryKind, MediaLibrarySettings,
+    MetadataProviderId, MetadataProviderSettings, MetadataRefreshTaskSettings, MetadataSettings,
+    ScheduledTaskWeekday, ScheduledTaskWindowSettings, ScheduledTasksSettings, Settings,
+    TrashCleanupTaskSettings, load_database_settings, save_database_settings,
+    seed_database_settings, settings_for_persistence, settings_yaml_for_persistence,
 };
 use koko::metadata::{
-    StoredMetadataSnapshot,
-    expected_artwork_cache_path,
-    list_provider_statuses,
-    managed_metadata_asset_dir,
-    metadata_asset_uuid,
-    persist_item_metadata_assets,
+    StoredMetadataSnapshot, expected_artwork_cache_path, list_provider_statuses,
+    managed_metadata_asset_dir, metadata_asset_uuid, persist_item_metadata_assets,
 };
 use std::fs;
 
diff --git a/crates/server/tests/test_signal_handler.rs b/crates/server/tests/test_signal_handler.rs
index dc5d868d..270ccf76 100644
--- a/crates/server/tests/test_signal_handler.rs
+++ b/crates/server/tests/test_signal_handler.rs
@@ -7,25 +7,14 @@
 
 // standard imports
 use std::sync::Arc;
-use std::sync::atomic::{
-    AtomicBool,
-    AtomicU32,
-    Ordering,
-};
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
 use std::thread;
 use std::time::Duration;
 use tokio::time::timeout;
 
 // local imports
-use koko::config::{
-    Settings,
-    current_settings,
-    replace_current_settings,
-};
-use koko::signal_handler::{
-    ShutdownCoordinator,
-    ShutdownSignal,
-};
+use koko::config::{Settings, current_settings, replace_current_settings};
+use koko::signal_handler::{ShutdownCoordinator, ShutdownSignal};
 use koko::web;
 
 struct TestServerStateGuard {
diff --git a/crates/server/tests/test_utils.rs b/crates/server/tests/test_utils.rs
index 8f71f573..939f0f46 100644
--- a/crates/server/tests/test_utils.rs
+++ b/crates/server/tests/test_utils.rs
@@ -1,18 +1,11 @@
 //! Shared test utilities to eliminate code duplication across test files.
 
 // standard imports
-use std::sync::atomic::{
-    AtomicU64,
-    Ordering,
-};
+use std::sync::atomic::{AtomicU64, Ordering};
 
 // lib imports
 use once_cell::sync::Lazy;
-use rocket::http::{
-    ContentType,
-    Header,
-    Status,
-};
+use rocket::http::{ContentType, Header, Status};
 use rocket::local::asynchronous::Client;
 use serde_json::Value;
 
diff --git a/crates/server/tests/test_web/routes/auth.rs b/crates/server/tests/test_web/routes/auth.rs
index 93d79488..1832dd16 100644
--- a/crates/server/tests/test_web/routes/auth.rs
+++ b/crates/server/tests/test_web/routes/auth.rs
@@ -4,10 +4,7 @@ use serde_json::json;
 
 // test imports
 use crate::test_utils::{
-    create_and_login_user,
-    create_test_client,
-    create_test_user,
-    make_request,
+    create_and_login_user, create_test_client, create_test_user, make_request,
 };
 
 #[rocket::async_test]
diff --git a/crates/server/tests/test_web/routes/common.rs b/crates/server/tests/test_web/routes/common.rs
index d33020ce..26f1157f 100644
--- a/crates/server/tests/test_web/routes/common.rs
+++ b/crates/server/tests/test_web/routes/common.rs
@@ -2,10 +2,7 @@
 use rocket::http::Status;
 
 // test imports
-use crate::test_utils::{
-    create_test_client,
-    make_request,
-};
+use crate::test_utils::{create_test_client, make_request};
 
 #[rocket::async_test]
 async fn test_root_route() {
diff --git a/crates/server/tests/test_web/routes/dependencies.rs b/crates/server/tests/test_web/routes/dependencies.rs
index 831eab1e..cbb05976 100644
--- a/crates/server/tests/test_web/routes/dependencies.rs
+++ b/crates/server/tests/test_web/routes/dependencies.rs
@@ -1,15 +1,9 @@
 // lib imports
 use rocket::http::Status;
-use rocket::serde::json::{
-    Value,
-    serde_json,
-};
+use rocket::serde::json::{Value, serde_json};
 
 // test imports
-use crate::test_utils::{
-    TestResponse,
-    make_request,
-};
+use crate::test_utils::{TestResponse, make_request};
 
 #[rocket::async_test]
 async fn test_get_dependencies_route() {
diff --git a/crates/server/tests/test_web/routes/media.rs b/crates/server/tests/test_web/routes/media.rs
index d43afd9d..9fd644f0 100644
--- a/crates/server/tests/test_web/routes/media.rs
+++ b/crates/server/tests/test_web/routes/media.rs
@@ -1,15 +1,9 @@
 // lib imports
 use rocket::http::Status;
-use rocket::serde::json::{
-    Value,
-    serde_json,
-};
+use rocket::serde::json::{Value, serde_json};
 
 // test imports
-use crate::test_utils::{
-    create_test_client,
-    make_request,
-};
+use crate::test_utils::{create_test_client, make_request};
 
 #[rocket::async_test]
 async fn test_get_server_capabilities_route() {
diff --git a/crates/server/tests/test_web/routes/settings.rs b/crates/server/tests/test_web/routes/settings.rs
index 70f9c527..1691e1e9 100644
--- a/crates/server/tests/test_web/routes/settings.rs
+++ b/crates/server/tests/test_web/routes/settings.rs
@@ -1,14 +1,7 @@
 use rocket::http::Status;
-use rocket::serde::json::{
-    Value,
-    json,
-    serde_json,
-};
+use rocket::serde::json::{Value, json, serde_json};
 
-use crate::test_utils::{
-    create_test_client,
-    make_request,
-};
+use crate::test_utils::{create_test_client, make_request};
 use koko::globals;
 
 #[rocket::async_test]
diff --git a/crates/server/tests/test_web/routes/user.rs b/crates/server/tests/test_web/routes/user.rs
index b5800d0e..b4391388 100644
--- a/crates/server/tests/test_web/routes/user.rs
+++ b/crates/server/tests/test_web/routes/user.rs
@@ -1,18 +1,10 @@
 // lib imports
 use rocket::http::Status;
-use rocket::serde::json::{
-    json,
-    serde_json,
-};
+use rocket::serde::json::{json, serde_json};
 use rstest::rstest;
 
 // test imports
-use crate::test_utils::{
-    create_test_client,
-    create_test_user,
-    login_user,
-    make_request,
-};
+use crate::test_utils::{create_test_client, create_test_user, login_user, make_request};
 
 const TINY_PNG_BASE64: &str =
     "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=";
diff --git a/crates/server/tests/test_web/test_auth_routes.rs b/crates/server/tests/test_web/test_auth_routes.rs
index 2ca01c22..9a5d4ffa 100644
--- a/crates/server/tests/test_web/test_auth_routes.rs
+++ b/crates/server/tests/test_web/test_auth_routes.rs
@@ -7,11 +7,7 @@ use serde_json::json;
 
 // test imports
 use crate::test_utils::{
-    create_and_login_user,
-    create_test_client,
-    create_test_user,
-    login_user,
-    make_request,
+    create_and_login_user, create_test_client, create_test_user, login_user, make_request,
 };
 
 #[rocket::async_test]

From d50aea4d1d8aaa6b2f571b6ba0cca09a3ea3bc3b Mon Sep 17 00:00:00 2001
From: Vithorio Polten <reach@vithor.io>
Date: Fri, 19 Jun 2026 07:21:34 -0300
Subject: [PATCH 27/27] feat(server): restore settings-change ffprobe re-probe
 trigger

db.run borrows &self, so the save doesn't consume db; move it into the
spawn afterward (same pattern as scan_library). No clone needed.
---
 .gitignore                               |  5 ++++-
 Cargo.lock                               |  1 +
 crates/server/src/web/routes/settings.rs | 16 +++++++++++++++
 xtask/src/main.rs                        | 25 +++++-------------------
 4 files changed, 26 insertions(+), 21 deletions(-)

diff --git a/.gitignore b/.gitignore
index 1363d74c..ea8ac32f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,4 +42,7 @@ crates/client-web/dist/
 
 # dev temp files
 .dev/
-.worktrees
+
+# git worktrees
+.worktrees/
+artifacts
diff --git a/Cargo.lock b/Cargo.lock
index 5b69f3a8..6887a095 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3346,6 +3346,7 @@ dependencies = [
  "sha2 0.11.0",
  "strsim 0.11.1",
  "tao",
+ "tempfile",
  "tmdb_client",
  "tokio",
  "tray-icon",
diff --git a/crates/server/src/web/routes/settings.rs b/crates/server/src/web/routes/settings.rs
index b67c5c02..7319f2f0 100644
--- a/crates/server/src/web/routes/settings.rs
+++ b/crates/server/src/web/routes/settings.rs
@@ -381,6 +381,22 @@ pub async fn update_settings(
     runtime_settings.media.libraries.clear();
     replace_current_settings(runtime_settings);
 
+    // Trigger: if the ffprobe path changed (or may have become newly available),
+    // re-probe any media files that were scanned without ffprobe. The save above
+    // borrows db via db.run(&self); we then move db into the background job
+    // (Rocket's pool keeps the connection checked out until the job finishes,
+    // same pattern as scan_library).
+    let ffprobe_changed =
+        existing_settings.ffmpeg.ffprobe_path != settings_for_database.ffmpeg.ffprobe_path;
+    if ffprobe_changed {
+        let ffmpeg_settings = settings_for_database.ffmpeg.clone();
+        tokio::spawn(async move {
+            crate::web::routes::media::try_spawn_reprobe(db, ffmpeg_settings).await;
+        });
+    } else {
+        drop(db);
+    }
+
     Ok(Json(merged_settings_response(
         settings_for_database,
         persisted_libraries,
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 3fbba2d8..bb0f4ed4 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -1,28 +1,13 @@
 use std::{
-    collections::{
-        HashSet,
-        hash_map::DefaultHasher,
-    },
+    collections::{HashSet, hash_map::DefaultHasher},
     env,
     error::Error,
     fs,
-    hash::{
-        Hash,
-        Hasher,
-    },
-    io::{
-        self,
-        Write,
-    },
-    path::{
-        Path,
-        PathBuf,
-    },
+    hash::{Hash, Hasher},
+    io::{self, Write},
+    path::{Path, PathBuf},
     process::Command,
-    time::{
-        SystemTime,
-        UNIX_EPOCH,
-    },
+    time::{SystemTime, UNIX_EPOCH},
 };
 
 const MIGRATIONS_DIR: &str = "crates/server/sql/migrations";