#188 : regression test — a copied Graphic clip pastes at the playhead

Engine test from #205 (the shortcut half of that PR is superseded by #204). Co-Authored-By: carlitosteso3 <carlitosteso3@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge pull request #180 from SaymonMaster14/feat/windows-nvenc-h264
2026-10-07 20:36:21 -04:00 · 2026-10-07 18:17:05 -04:00 · 2026-10-07 18:16:12 -04:00 · 2026-10-07 17:58:12 -04:00 · 2026-10-07 17:56:50 -04:00 · 2026-10-07 17:56:33 -04:00
483 changed files with 43647 additions and 3674 deletions
@@ -47,6 +47,10 @@ jobs:
      - name: XML, desktop entry, AppStream, Flatpak manifest
        run: |
          xmllint --noout packaging/windows/filmcraft.wxs packaging/macos/*.plist* packaging/linux/*.xml*
+          # Windows Installer needs Icon ids ending in .ico or .exe, or shortcuts show a blank icon.
+          if grep -oE '<Icon Id="[^"]*"' packaging/windows/filmcraft.wxs | grep -vE '\.(ico|exe)"$'; then
+            echo "::error::Icon Id must end in .ico or .exe"; exit 1
+          fi
          desktop-file-validate packaging/linux/ai.storyteller.filmcraft.desktop
          sed -e 's/@VERSION@/0.0.0/' -e 's/@DATE@/2026-01-01/' packaging/linux/ai.storyteller.filmcraft.metainfo.xml.in >"$RUNNER_TEMP/ai.storyteller.filmcraft.metainfo.xml"
          appstreamcli validate --no-net --explain "$RUNNER_TEMP/ai.storyteller.filmcraft.metainfo.xml"
@@ -70,6 +70,12 @@ jobs:
      FILMCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
    steps:
      - uses: actions/checkout@v4
+      # Fonts (optional build input, required for releases): docs/contributing.md#building-with-craft-fonts
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          repository: storytold/craft-fonts
+          ref: abb83316d96aa59c1cf64784289e378fe9fa5695 # bump deliberately
+          path: craft-fonts
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-apple-darwin, x86_64-apple-darwin
@@ -90,6 +96,8 @@ jobs:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
+          CRAFT_FONTS_REQUIRED: "1"
        run: packaging/macos/package.sh --arch universal
      - uses: actions/upload-artifact@v4
        with:
@@ -112,11 +120,20 @@ jobs:
        include:
          - { arch: x64, target: x86_64-pc-windows-msvc }
          - { arch: x86, target: i686-pc-windows-msvc }
+          # Windows on ARM: cross-compiled on the x64 runner, so signing and WiX run as above.
+          # .github/workflows/windows-arm64.yml installs and runs it on ARM64 hardware.
+          - { arch: arm64, target: aarch64-pc-windows-msvc }
    env:
      FILMCRAFT_VERSION: ${{ needs.version.outputs.version }}
      FILMCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
    steps:
      - uses: actions/checkout@v4
+      # Fonts (optional build input, required for releases): docs/contributing.md#building-with-craft-fonts
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          repository: storytold/craft-fonts
+          ref: abb83316d96aa59c1cf64784289e378fe9fa5695 # bump deliberately
+          path: craft-fonts
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}
@@ -141,6 +158,8 @@ jobs:
          AZURE_SIGNING_ENDPOINT: ${{ secrets.AZURE_SIGNING_ENDPOINT }}
          AZURE_SIGNING_ACCOUNT: ${{ secrets.AZURE_SIGNING_ACCOUNT }}
          AZURE_CERT_PROFILE: ${{ secrets.AZURE_CERT_PROFILE }}
+          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
+          CRAFT_FONTS_REQUIRED: "1"
        run: ./packaging/windows/package.ps1 -Arch ${{ matrix.arch }}
      - uses: actions/upload-artifact@v4
        with:
@@ -167,6 +186,12 @@ jobs:
      NFPM_VERSION: 2.47.0
    steps:
      - uses: actions/checkout@v4
+      # Fonts (optional build input, required for releases): docs/contributing.md#building-with-craft-fonts
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          repository: storytold/craft-fonts
+          ref: abb83316d96aa59c1cf64784289e378fe9fa5695 # bump deliberately
+          path: craft-fonts
      - name: Install build and packaging tools
        run: |
          sudo apt-get update
@@ -184,6 +209,9 @@ jobs:
        if: inputs.version != ''
        run: cargo xtask version set "$FILMCRAFT_VERSION"
      - name: Build and package (AppImage, deb, rpm, tar.gz)
+        env:
+          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
+          CRAFT_FONTS_REQUIRED: "1"
        run: packaging/linux/package.sh
      - name: Check the packages
        run: |
@@ -212,6 +240,12 @@ jobs:
      WASM_BINDGEN_VERSION: 0.2.129
    steps:
      - uses: actions/checkout@v4
+      # Fonts (optional build input, required for releases): docs/contributing.md#building-with-craft-fonts
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          repository: storytold/craft-fonts
+          ref: abb83316d96aa59c1cf64784289e378fe9fa5695 # bump deliberately
+          path: craft-fonts
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown
@@ -221,13 +255,17 @@ jobs:
      - name: Install wasm-bindgen CLI
        run: |
          # Must match the wasm-bindgen crate version exactly (WASM_BINDGEN in xtask/src/main.rs).
-          command -v wasm-bindgen >/dev/null && wasm-bindgen --version | grep -q "$WASM_BINDGEN_VERSION" \
-            || cargo install wasm-bindgen-cli --version "$WASM_BINDGEN_VERSION" --locked
+          if ! { command -v wasm-bindgen >/dev/null && wasm-bindgen --version | grep -q "$WASM_BINDGEN_VERSION"; }; then
+            cargo install wasm-bindgen-cli --version "$WASM_BINDGEN_VERSION" --locked
+          fi
          wasm-bindgen --version
      - name: Apply version override
        if: inputs.version != ''
        run: cargo xtask version set "$FILMCRAFT_VERSION"
      - name: Build and zip
+        env:
+          CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
+          CRAFT_FONTS_REQUIRED: "1"
        run: packaging/web/package.sh
      - uses: actions/upload-artifact@v4
        with:
@@ -0,0 +1,95 @@
+# Windows on ARM: package the ARM64 release the way release.yml does (cross-compiled on an x64
+# runner, unsigned here), then install that MSI on a Windows 11 ARM64 runner, check the installed
+# binaries are ARM64, run the CLI natively, and uninstall. (A native ARM64 `cargo test` job is left
+# out for now: PdfCraft saw an intermittent access violation in egui UI tests there.)
+name: Windows ARM64
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - Cargo.toml
+      - Cargo.lock
+      - "**/Cargo.toml"
+      - "**/build.rs"
+      - .github/workflows/windows-arm64.yml
+      - packaging/windows/**
+  schedule:
+    - cron: "41 4 * * 1" # weekly, so drift in the runner images shows up
+  workflow_dispatch:
+
+concurrency:
+  group: windows-arm64-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  CARGO_INCREMENTAL: 0
+
+jobs:
+  package:
+    name: package (cross-compiled on x64)
+    runs-on: windows-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@89b12181fb390509a0842a86cc55eeb8eb928c1d # stable
+        with:
+          targets: aarch64-pc-windows-msvc
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+        with:
+          key: windows-arm64-package
+      - name: Install WiX
+        shell: pwsh
+        run: dotnet tool install --global wix --version 5.0.2
+      - name: Build and package (unsigned)
+        shell: pwsh
+        env:
+          DIST: ${{ github.workspace }}\dist\arm64
+        run: ./packaging/windows/package.ps1 -Arch arm64
+      - uses: actions/upload-artifact@v4
+        with:
+          name: filmcraft-windows-arm64
+          path: dist/arm64/*
+          if-no-files-found: error
+          retention-days: 7
+
+  install:
+    name: install and run on ARM64
+    needs: package
+    runs-on: windows-11-arm
+    timeout-minutes: 30
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: filmcraft-windows-arm64
+          path: dist
+      - name: Install the MSI, check it, run it, uninstall it
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $msi = (Get-ChildItem dist/*.msi | Select-Object -First 1).FullName
+          $p = Start-Process msiexec.exe -ArgumentList '/i', "`"$msi`"", '/qn', '/l*v', 'install.log' -Wait -PassThru
+          if ($p.ExitCode -ne 0) { Get-Content install.log -Tail 60; throw "msiexec /i exited $($p.ExitCode)" }
+          $dir = Join-Path $env:ProgramFiles 'FilmCraft'
+          foreach ($exe in 'filmcraft.exe', 'filmcraft-cli.exe') {
+            $path = Join-Path $dir $exe
+            if (-not (Test-Path $path)) { throw "$exe not installed in $dir" }
+            $bytes = [System.IO.File]::ReadAllBytes($path)
+            $machine = [BitConverter]::ToUInt16($bytes, [BitConverter]::ToInt32($bytes, 0x3C) + 4)
+            if ($machine -ne 0xAA64) { throw "$exe is for machine 0x$('{0:X}' -f $machine), not ARM64" }
+            Write-Output "ok $path (ARM64)"
+          }
+          # The installed CLI runs natively on ARM64.
+          $cli = Join-Path $dir 'filmcraft-cli.exe'
+          $out = & $cli --version 2>&1 | Out-String
+          if ($LASTEXITCODE -ne 0) { Write-Output $out; throw "filmcraft-cli --version exited $LASTEXITCODE" }
+          Write-Output "ok filmcraft-cli --version: $($out.Trim())"
+          $p = Start-Process msiexec.exe -ArgumentList '/x', "`"$msi`"", '/qn' -Wait -PassThru
+          if ($p.ExitCode -ne 0) { throw "msiexec /x exited $($p.ExitCode)" }
+          if (Test-Path (Join-Path $dir 'filmcraft.exe')) { throw 'uninstall left filmcraft.exe behind' }
+          Write-Output 'ok uninstalled'
@@ -3,6 +3,49 @@
 These rules apply to every human and AI contributor. `CLAUDE.md` holds the working instructions; this
 file holds the rules that must never be broken. When the two disagree, this file wins.

+## 0. Never crash
+
+People trust FilmCraft with hours of work. A malformed file, a bad command or MCP parameter, a corrupt
+preset or project, an odd keystroke or a full disk must give an error the user (or agent) can act on,
+never a crash and never lost work. **This rule outranks feature work:** don't ship a feature by adding a
+panic path, and fix a crash before building on top of it. The cross-app standard is
+[`craftrules/standards/never-crash.md`](https://github.com/storytold/craftrules/blob/main/standards/never-crash.md).
+
+1. **Fail with `Result<T, E>`.** Return the crate's error type and propagate with `?`; add context
+   (`map_err`, an error variant) instead of discarding it. In the UI, report the error (status bar, error
+   dialog) and carry on.
+2. **No panicking shortcuts outside tests:** no `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!`
+   or `unimplemented!`. Use `?`, `ok_or(..)?`, `let Some(x) = .. else { return Err(..) }`, `if let`, or a
+   fallback that is truly correct (never one that silently corrupts a project). An unfinished feature
+   returns an "unsupported" error. The only exception is a call that is provably infallible from local
+   code alone (a literal that always parses): a single-item `#[allow(clippy::expect_used)]` with the reason.
+3. **No `unsafe`** (`unsafe_code = "forbid"` for the workspace). The single exception is
+   `crates/platform`, which needs `unsafe` to call the operating system's media APIs (hardware
+   video decoding through VideoToolbox and Media Foundation / Direct3D 11; later encoding and Linux) and does nothing else. It
+   uses `unsafe_code = "deny"` with `#[allow(unsafe_code)]` only on its FFI modules, a
+   `// SAFETY:` comment on every `unsafe` block, a safe `Result`-returning public API, and the
+   pure-Rust decoder as the tested fallback ([ADR 0001](docs/adr/0001-platform-ffi.md)).
+4. **Every input-derived number is hostile.** Media files, project and interchange files, presets, fonts,
+   CLI / MCP / control-channel parameters and UI state are untrusted. Index and slice with `get()` (or
+   validate bounds once, up front, for a hot loop); slice strings only at char boundaries; use
+   `checked_*` / `saturating_*` for lengths, offsets and counts; never divide by a value that can be zero
+   (frame rates, timescales, sample rates, sizes); don't cast negative or NaN values to integers; don't
+   call `clamp` with bounds that can cross; cap allocations sized by input.
+5. **Bound recursion and loops.** Projects can be cyclic (nested sequences) or deeply nested: walk them
+   with seen-sets or depth limits.
+6. **Don't cascade.** Lock poisoning is not fatal: `lock().unwrap_or_else(PoisonError::into_inner)`.
+   Every thread or job (export, previews, proxies, decoding workers…) runs under `catch_unwind` and
+   reports a failure as an error: a dead worker leaves monitors blank or jobs "running" forever.
+7. **Last-resort guard.** The panic hook (`crates/ui-egui/src/crash.rs`) logs every panic, and the UI pass
+   runs under `catch_unwind`, so an escaped panic becomes an error window and the session (and unsaved
+   project) survives. It is a safety net, not a substitute for rules 1–6. Keep `panic = "unwind"`.
+8. **Prove it.** Every crash fix comes with a small synthetic regression test that panicked before the
+   fix. Parsers and decoders get mutation-fuzz tests (truncation, bit flips, corrupt sizes) run under
+   `catch_unwind`; new commands get hostile-parameter tests. Fuzzer findings become tests.
+9. **Enforced:** clean crates carry `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic,
+   clippy::unimplemented, clippy::todo, clippy::unreachable)]` (moving to `[workspace.lints.clippy]` once
+   every crate is clean). `clippy.toml` allows them in tests: a failing test should fail loudly.
+
 ## 1. Assets: no Adobe artwork, every asset licensed and attributed

 This rule is absolute. Breaking it is the most serious mistake a contributor can make on this project.
@@ -44,10 +87,18 @@ reproduce an image (for example, point lists traced from someone else's icon).
   and are listed in `ATTRIBUTION.md`.
 7. **When in doubt, leave it out** and draw or generate it yourself.
 8. **The one exception: first-party ArtCraft brand marks.** The ArtCraft name and logos in `docs/brand/`
-   (supplied by the ArtCraft team) are trademarks, all rights reserved, used with permission. They still
+   are trademarks of the ArtCraft Team, not open source, usable only unmodified and only in the context of
+   FilmCraft under `docs/brand/LICENSE-brand.txt`; forks and modified versions must remove them. They still
   need a sidecar and an `ATTRIBUTION.md` row (licence `LicenseRef-ArtCraft-Trademark`). No other
   non-open asset is allowed, and this exception never covers third-party marks (Adobe, Discord, GitHub
   and other logos stay out; draw a generic icon instead).
+9. **Fonts live in [storytold/craft-fonts](https://github.com/storytold/craft-fonts), never in this
+   repo.** Don't commit new font files (the small Latin UI fonts already in `assets/fonts/` stay). A
+   font FilmCraft needs is added to craft-fonts, which the app reads through the optional build input
+   `CRAFT_FONTS_DIR=<absolute path of a craft-fonts checkout>` (`crates/text/build.rs` embeds the fonts in its
+   `fonts/manifest.txt` as `filmcraft_text::fonts::CRAFT_FONTS`; unset, it is empty and the app uses its
+   bundled and system fonts). Never add craft-fonts to a `Cargo.toml`. Code using `CRAFT_FONTS` must work
+   when it is empty. Standard: [`craftrules/standards/fonts.md`](https://github.com/storytold/craftrules/blob/main/standards/fonts.md).

 ## 2. Clean-room code

@@ -67,9 +118,21 @@ reproduce an image (for example, point lists traced from someone else's icon).

 ## 3. Engineering rules

+### 3.1 Never crash
+
+See [§0](#0-never-crash). It outranks every other engineering rule.
+
+### 3.2 The rest
+
 See `CLAUDE.md`: pure Rust, dependency layering (`cargo xtask layers`), exact `Tick` time, everything is
 a command, everything is agent-drivable, and the quality gates (`cargo xtask ci`) before every commit.

+Shared real-file test corpora (Photoshop-authored PSDs, etc.) live in
+[`storytold/photocraft-corpus`](https://github.com/storytold/photocraft-corpus), explained in
+[craftrules `standards/test-corpora.md`](https://github.com/storytold/craftrules/blob/main/standards/test-corpora.md).
+Never commit large binary fixtures to this repo; fetch them pinned by commit and sha256-verified,
+as PhotoCraft does with `cargo xtask corpus`.
+
 ## See also

 - [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/contributing.md](docs/contributing.md): setup, gates, commits, how to add things
@@ -60,6 +60,8 @@ procedural demo footage (`crates/media/src/generators.rs`); no external media. R
 | `crates/golden/goldens/hdr_tone_map.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, scene `hdr_tone_map`) from procedurally generated media re-encoded as Rec. 2100 PQ | MIT OR Apache-2.0 |
 | `crates/golden/goldens/graphic_title.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, scene `graphic_title`) from procedurally generated media and bundled OFL fonts | MIT OR Apache-2.0 |
 | `crates/golden/goldens/lumetri_basic.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, scene `lumetri_basic`) from procedurally generated media | MIT OR Apache-2.0 |
+| `crates/golden/goldens/lumetri_hdr_pq.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, scene `lumetri_hdr_pq`) from procedurally generated media re-encoded as Rec. 2100 PQ | MIT OR Apache-2.0 |
+| `crates/golden/goldens/lumetri_presets_grid.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, `lumetri_presets_grid`): FilmCraft's own Lumetri presets on its procedural preview picture | MIT OR Apache-2.0 |
 | `crates/golden/goldens/text_burnin.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, scene `text_burnin`) from procedurally generated media | MIT OR Apache-2.0 |
 | `crates/golden/goldens/transform_opacity.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, scene `transform_opacity`) from procedurally generated media | MIT OR Apache-2.0 |
 | `crates/golden/goldens/transition_cross_dissolve.png` | FilmCraft contributors | Original work: golden reference rendered by FilmCraft (crates/golden/tests/golden.rs, scene `transition_cross_dissolve`) from procedurally generated media | MIT OR Apache-2.0 |
@@ -101,23 +103,50 @@ is traced or derived from Adobe artwork.
 | Demo footage (ocean sunset, aurora, city night, dunes, forest, plasma), bars and tone, counting leader, colour matte | `crates/media/src/generators.rs` |
 | Built-in graphics templates (Lower Third – Slab / Rule, Ticker – Crawl, Title – Centered / Boxed, End Credits – Roll, Callout – Pointer / Tag) and their placeholder text | `crates/project/src/gtemplate.rs` (`builtin_templates`): original designs defined in code with the bundled Inter font; thumbnails are rendered at runtime, no template, image or font files |
 | Lumetri "Look" presets (Teal & Orange, Warm Film, …) | `crates/render/src/effects.rs` (`apply_look`): procedural colour transforms, not LUT files |
+| Lumetri Presets (Effects panel: Cinematic, Film Emulation, Monochrome, Technical) and their preview picture | `crates/render/src/lumetri_presets.rs`: Lumetri parameter values chosen by contributors, descriptive names, and a procedural preview picture (dusk sky, ridges, lake, grey ramp, colour chips) |
 | Colour palette and layout metrics | `crates/ui-egui/src/theme.rs`: colour values and sizes only; no artwork |

+## Optional build input: craft-fonts
+
+These fonts are **not files in this repository**. Builds made with the optional build input
+`CRAFT_FONTS_DIR` (all official releases; see [docs/contributing.md](docs/contributing.md#building-with-craft-fonts))
+embed them from [storytold/craft-fonts](https://github.com/storytold/craft-fonts), where each file,
+its author, pinned upstream source and licence text are listed in its
+[ATTRIBUTION.md](https://github.com/storytold/craft-fonts/blob/main/ATTRIBUTION.md). Release packages
+carry each font's licence as `OFL-<family>.txt`.
+
+| Font | Use in FilmCraft | Licence |
+|---|---|---|
+| BIZ UDPGothic Regular, Bold (Morisawa) | Japanese UI text; Japanese fallback for sans titles (the web build embeds only Regular) | OFL-1.1 |
+| Shippori Mincho Regular (FONTDASU) | Japanese fallback for serif titles (native builds) | OFL-1.1 |
+| BIZ UDMincho Regular (Morisawa) | Japanese fallback for serif titles (native builds) | OFL-1.1 |
+
 ## First-party brand marks

-The ArtCraft name and logo are trademarks of the ArtCraft team, used in FilmCraft with permission. They are not
-openly licensed and are not covered by the project licence; forks must remove or replace them (AGENTS.md §1.8).
+The ArtCraft name, wordmark and logos are trademarks of the ArtCraft Team. They are not open source and
+are not covered by the project licence; they may be used only unmodified and only in the context of
+FilmCraft, under [`docs/brand/LICENSE-brand.txt`](docs/brand/LICENSE-brand.txt). Forks and modified versions must
+remove them (AGENTS.md §1.8).

 | File | Author | Source | Licence |
 |---|---|---|---|
-| `docs/brand/artcraft-logo-white.png` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark, light ink for dark backgrounds) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
-| `docs/brand/artcraft-logo-white.svg` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark, light ink for dark backgrounds) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
-| `docs/brand/artcraft-logo.png` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark (symbol + "ARTCRAFT"), dark ink for light backgrounds) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
-| `docs/brand/artcraft-logo.svg` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark (symbol + "ARTCRAFT"), dark ink for light backgrounds) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
-| `docs/brand/artcraft-mark-black.png` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), black) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
-| `docs/brand/artcraft-mark-black.svg` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), black) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
-| `docs/brand/artcraft-mark.png` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), blue) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
-| `docs/brand/artcraft-mark.svg` | ArtCraft team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), blue) | ArtCraft trademark, all rights reserved; used with permission (not MIT/Apache) |
+| `docs/brand/artcraft-logo-white.png` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark, light ink for dark backgrounds) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+| `docs/brand/artcraft-logo-white.svg` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark, light ink for dark backgrounds) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+| `docs/brand/artcraft-logo.png` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark (symbol + "ARTCRAFT"), dark ink for light backgrounds) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+| `docs/brand/artcraft-logo.svg` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft wordmark (symbol + "ARTCRAFT"), dark ink for light backgrounds) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+| `docs/brand/artcraft-mark-black.png` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), black) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+| `docs/brand/artcraft-mark-black.svg` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), black) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+| `docs/brand/artcraft-mark.png` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), blue) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+| `docs/brand/artcraft-mark.svg` | ArtCraft Team | Original work: first-party ArtCraft brand mark (ArtCraft symbol ("A" mark), blue) | ArtCraft trademark, not open source; `docs/brand/LICENSE-brand.txt` (not MIT/Apache) |
+
+## Third-party source code
+
+Source files that are transcribed from third-party code rather than written from scratch. Each keeps
+the original copyright and permission notice in its header.
+
+| File | Author | Source | Licence |
+|---|---|---|---|
+| `crates/platform/src/nvenc/ffi.rs` | NVIDIA Corporation (`nvEncodeAPI.h`); FilmCraft contributors (Rust transcription) | Structures, function table and constants transcribed from `nvEncodeAPI.h`, NVIDIA Video Codec SDK, API 12.1 (https://developer.nvidia.com/video-codec-sdk) | MIT (Copyright (c) 2010-2023 NVIDIA Corporation; notice kept in the file header) |

 ## Downloaded at runtime

@@ -1,6 +1,6 @@
 # FilmCraft — instructions for agents

-FilmCraft is a clean-room, open-source, pure-Rust non-linear video editor targeting Adobe Premiere Pro parity (and beyond). Native on macOS, Windows, Linux; web via WASM. Sibling of `../photocraft` (Photoshop), `../printcraft` (Acrobat) and `../drawcraft` (Illustrator), with the same conventions.
+FilmCraft is a clean-room, open-source, pure-Rust non-linear video editor targeting Adobe Premiere Pro parity (and beyond). Native on macOS, Windows, Linux; web via WASM. Sibling of `../photocraft` (Photoshop), `../pdfcraft` (Acrobat) and `../vectorcraft` (Illustrator; formerly DrawCraft), with the same conventions.

 ## Start every session here
 `plan/` is maintainer-local (gitignored, not in the repo). Each step names the public equivalent to use if you don't have it.
@@ -9,9 +9,11 @@ FilmCraft is a clean-room, open-source, pure-Rust non-linear video editor target
 3. Follow the autonomous operation protocol (`plan/execution-plan.md` §7; public summary: [`docs/agents.md`](docs/agents.md) §5–7). Don't stop to ask unless it lists the decision as the user's.

 ## Non-negotiables
-**Read [`AGENTS.md`](AGENTS.md) first; its rules override everything here.** In particular (§1): never use Adobe iconography, images or any other Adobe asset. Every asset must be openly licensed (OSS / public domain / Creative Commons, or original work by a contributor) and must have a `<file>.attribution` sidecar plus an entry in `ATTRIBUTION.md`. `cargo xtask assets` enforces this.
+**Read [`AGENTS.md`](AGENTS.md) first; its rules override everything here.**
+- **Never crash** ([`AGENTS.md`](AGENTS.md) §0, standard: [`craftrules/standards/never-crash.md`](https://github.com/storytold/craftrules/blob/main/standards/never-crash.md)). People depend on FilmCraft; a crash loses their work, so this outranks feature work. No `unwrap`/`expect`/`panic!`/`unreachable!`/`todo!`/`unimplemented!` or `unsafe` outside tests: return `Result<T, E>` and propagate with `?` (`ok_or`, `let … else`, `if let`). Treat every number from media, project files, presets or CLI/MCP/control params as hostile: `get()` instead of `[i]`, checked/saturating math, no division by possibly-zero values, capped allocations, bounded recursion. `lock().unwrap_or_else(PoisonError::into_inner)`; background jobs run under `catch_unwind`. The panic hook + UI `catch_unwind` (`crates/ui-egui/src/crash.rs`) are the last-resort guard, not a licence. Every crash fix gets a regression test that panicked before. In particular (§1): never use Adobe iconography, images or any other Adobe asset. Every asset must be openly licensed (OSS / public domain / Creative Commons, or original work by a contributor) and must have a `<file>.attribution` sidecar plus an entry in `ATTRIBUTION.md`. `cargo xtask assets` enforces this.
+- **Fonts** live in [storytold/craft-fonts](https://github.com/storytold/craft-fonts), never in this repo (no new font files here; [`AGENTS.md`](AGENTS.md) §1.9, standard: [`craftrules/standards/fonts.md`](https://github.com/storytold/craftrules/blob/main/standards/fonts.md)). Build with them: `git clone https://github.com/storytold/craft-fonts ../craft-fonts && CRAFT_FONTS_DIR="$PWD/../craft-fonts" cargo run -p filmcraft` (`crates/text/build.rs` embeds them as `filmcraft_text::fonts::CRAFT_FONTS`, used for Japanese in the UI and titles). Unset, `CRAFT_FONTS` is empty and everything must still build, test and run; never add craft-fonts to a `Cargo.toml`. Tests on its glyphs skip when it is empty, so run the gates with and without `CRAFT_FONTS_DIR` when you touch fonts.
 - **Clean-room.** Never read/disassemble anything inside Adobe app bundles (names/listings only). Never copy Adobe icons, presets, LUTs, fonts. Never copy GPL/LGPL/AGPL code (FFmpeg, x264, x265, MLT, Kdenlive, Shotcut, Olive, LAME…). ffmpeg/ffprobe run only as external test oracles / fixture generators — never linked or shipped.
- **Pure Rust** in the product. OS media APIs only via Rust bindings in `crates/platform` (planned; not created yet), optional, behind traits.
+- **Pure Rust** in the product. OS media APIs only via Rust bindings in `crates/platform` (hardware decoding; the one crate allowed `unsafe`, see `AGENTS.md` §0.3 and `docs/adr/0001-platform-ffi.md`), optional, behind traits, with our decoders as the fallback.
 - **Layering** ([`docs/architecture.md`](docs/architecture.md) §1, enforced by `cargo xtask layers`): nothing below L5 depends on egui/eframe/winit/rfd/cpal. L0 codec/container crates depend only on `filmcraft-bitstream`.
 - **Exact time:** all time is `filmcraft_time::Tick` (254 016 000 000/s). Never use f64 seconds for edit math.
 - **Everything is a command** (`crates/engine`): id, label, menu path, shortcut, params, enabled(), run(). UI, CLI, control channel and MCP all dispatch by id.
@@ -5,7 +5,10 @@ Thanks for helping. Before you start:
 1. Read **[AGENTS.md](AGENTS.md)**. Its rules are absolute. In particular: no Adobe assets of any
   kind, every asset openly licensed with an attribution sidecar, no GPL/LGPL code, and ffmpeg only
   as an external test oracle.
-2. Follow **[docs/contributing.md](docs/contributing.md)**: setup per OS, building and running,
+2. **Never crash.** A crash loses someone's work, so this rule outranks feature work: no `unwrap()`,
+   `expect()`, `panic!`, `unreachable!`, `todo!`, `unimplemented!` or `unsafe` in production code;
+   return `Result` and treat every input as hostile. See [AGENTS.md](AGENTS.md) §0.
+3. Follow **[docs/contributing.md](docs/contributing.md)**: setup per OS, building and running,
   the quality gates (`cargo xtask ci`), commit conventions, and how to add commands, effects,
   transitions, codecs, panels and assets.

@@ -992,6 +992,16 @@ dependencies = [
 "windows 0.54.0",
 ]

+[[package]]
+name = "cpu-time"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9e393a7668fe1fad3075085b86c781883000b4ede868f43627b34a87c8b7ded"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
@@ -1655,13 +1665,14 @@ dependencies = [

 [[package]]
 name = "filmcraft"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "chrono",
 "cpal",
 "eframe",
 "egui",
 "filmcraft-engine",
+ "filmcraft-platform",
 "filmcraft-ui-egui",
 "log",
 "muda",
@@ -1676,7 +1687,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-aac"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -1686,22 +1697,32 @@ dependencies = [

 [[package]]
 name = "filmcraft-ac3"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 "thiserror 2.0.21",
 ]

+[[package]]
+name = "filmcraft-apv"
+version = "0.2.1"
+dependencies = [
+ "filmcraft-bitstream",
+ "filmcraft-testkit",
+ "rayon",
+ "thiserror 2.0.21",
+]
+
 [[package]]
 name = "filmcraft-audio-dsp"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 ]

 [[package]]
 name = "filmcraft-automation"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "base64 0.22.1",
 "filmcraft-engine",
@@ -1717,7 +1738,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-av1"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -1728,14 +1749,14 @@ dependencies = [

 [[package]]
 name = "filmcraft-bitstream"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "proptest",
 ]

 [[package]]
 name = "filmcraft-captions"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "filmcraft-project",
@@ -1748,11 +1769,11 @@ dependencies = [

 [[package]]
 name = "filmcraft-cfb"
-version = "0.1.1"
+version = "0.2.1"

 [[package]]
 name = "filmcraft-cli"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-automation",
 "filmcraft-codecs",
@@ -1761,6 +1782,7 @@ dependencies = [
 "filmcraft-mpegts",
 "filmcraft-mxf",
 "filmcraft-ogg",
+ "filmcraft-platform",
 "filmcraft-time",
 "serde_json",
 "tokio",
@@ -1768,10 +1790,11 @@ dependencies = [

 [[package]]
 name = "filmcraft-codecs"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-aac",
 "filmcraft-ac3",
+ "filmcraft-apv",
 "filmcraft-av1",
 "filmcraft-bitstream",
 "filmcraft-color",
@@ -1800,7 +1823,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-color"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "proptest",
 "serde",
@@ -1808,7 +1831,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-dnx"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -1818,7 +1841,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-edit"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-media",
 "filmcraft-project",
@@ -1830,7 +1853,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-engine"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-audio-dsp",
 "filmcraft-captions",
@@ -1861,9 +1884,10 @@ dependencies = [

 [[package]]
 name = "filmcraft-export"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-aac",
+ "filmcraft-apv",
 "filmcraft-audio-dsp",
 "filmcraft-codecs",
 "filmcraft-color",
@@ -1890,7 +1914,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-format"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-media",
 "filmcraft-project",
@@ -1902,7 +1926,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-frame"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "filmcraft-time",
@@ -1912,7 +1936,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-geom"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "proptest",
 "serde",
@@ -1920,7 +1944,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-golden"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "filmcraft-frame",
@@ -1937,7 +1961,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-gpu"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "filmcraft-frame",
@@ -1954,7 +1978,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-h264"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -1964,7 +1988,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-h264enc"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -1974,7 +1998,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-hevc"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -1984,7 +2008,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-interchange"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-cfb",
 "filmcraft-color",
@@ -2001,7 +2025,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-isobmff"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -2012,7 +2036,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-matroska"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 "serde_json",
@@ -2020,7 +2044,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-media"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "filmcraft-frame",
@@ -2033,7 +2057,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-mpeg2v"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 "rayon",
@@ -2042,7 +2066,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-mpegts"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 "thiserror 2.0.21",
@@ -2050,28 +2074,50 @@ dependencies = [

 [[package]]
 name = "filmcraft-mxf"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 ]

 [[package]]
 name = "filmcraft-ogg"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 ]

 [[package]]
 name = "filmcraft-opus"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 ]

+[[package]]
+name = "filmcraft-platform"
+version = "0.2.1"
+dependencies = [
+ "filmcraft-codecs",
+ "filmcraft-color",
+ "filmcraft-export",
+ "filmcraft-frame",
+ "filmcraft-isobmff",
+ "filmcraft-media",
+ "filmcraft-project",
+ "filmcraft-render",
+ "filmcraft-testkit",
+ "filmcraft-time",
+ "log",
+ "objc2-core-foundation",
+ "objc2-core-media",
+ "objc2-core-video",
+ "objc2-video-toolbox",
+ "windows 0.62.2",
+]
+
 [[package]]
 name = "filmcraft-project"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "filmcraft-geom",
@@ -2085,7 +2131,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-prores"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "filmcraft-testkit",
@@ -2095,7 +2141,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-render"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-audio-dsp",
 "filmcraft-captions",
@@ -2115,7 +2161,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-scopes"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "serde",
@@ -2124,7 +2170,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-speech"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "candle-core",
 "candle-nn",
@@ -2142,14 +2188,14 @@ dependencies = [

 [[package]]
 name = "filmcraft-testkit"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "png",
 ]

 [[package]]
 name = "filmcraft-text"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-color",
 "harfrust",
@@ -2160,7 +2206,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-time"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "proptest",
 "serde",
@@ -2168,8 +2214,9 @@ dependencies = [

 [[package]]
 name = "filmcraft-ui-egui"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
+ "cpu-time",
 "eframe",
 "egui",
 "egui_kittest",
@@ -2183,6 +2230,7 @@ dependencies = [
 "filmcraft-gpu",
 "filmcraft-interchange",
 "filmcraft-media",
+ "filmcraft-platform",
 "filmcraft-project",
 "filmcraft-render",
 "filmcraft-scopes",
@@ -2200,7 +2248,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-vp9"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-bitstream",
 "rayon",
@@ -2209,7 +2257,7 @@ dependencies = [

 [[package]]
 name = "filmcraft-web"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "eframe",
 "egui",
@@ -3779,7 +3827,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
 dependencies = [
 "bitflags 2.13.2",
+ "block2 0.6.2",
 "dispatch2",
+ "libc",
 "objc2 0.6.4",
 ]

@@ -3820,6 +3870,37 @@ dependencies = [
 "objc2-foundation 0.2.2",
 ]

+[[package]]
+name = "objc2-core-media"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05ec576860167a15dd9fce7fbee7512beb4e31f532159d3482d1f9c6caedf31d"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.6.2",
+ "dispatch2",
+ "objc2 0.6.4",
+ "objc2-core-audio",
+ "objc2-core-audio-types",
+ "objc2-core-foundation",
+ "objc2-core-video",
+]
+
+[[package]]
+name = "objc2-core-video"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.6.2",
+ "objc2 0.6.4",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-io-surface",
+ "objc2-metal 0.3.2",
+]
+
 [[package]]
 name = "objc2-encode"
 version = "4.1.0"
@@ -3992,6 +4073,23 @@ dependencies = [
 "objc2-foundation 0.2.2",
 ]

+[[package]]
+name = "objc2-video-toolbox"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05bf9a3c14831a7d9641b0d81d87dd913ee238a012b2fde27db5a84b56f5df3e"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2 0.6.2",
+ "objc2 0.6.4",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-core-media",
+ "objc2-core-video",
+ "objc2-foundation 0.3.2",
+ "objc2-metal 0.3.2",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -7140,7 +7238,7 @@ checksum = "e450f9b2ed1dff33c94c12589a87338689467b9c4f5d8a5710bd09a847d2c8a7"

 [[package]]
 name = "xtask"
-version = "0.1.1"
+version = "0.2.1"
 dependencies = [
 "filmcraft-testkit",
 "serde_json",
@@ -4,7 +4,7 @@ members = ["crates/*", "apps/*", "xtask"]
 default-members = ["crates/*", "apps/*", "xtask"]

 [workspace.package]
-version = "0.1.1"
+version = "0.2.1"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 rust-version = "1.95"
@@ -29,6 +29,7 @@ filmcraft-hevc = { path = "crates/hevc" }
 filmcraft-vp9 = { path = "crates/vp9" }
 filmcraft-prores = { path = "crates/prores" }
 filmcraft-dnx = { path = "crates/dnx" }
+filmcraft-apv = { path = "crates/apv" }
 filmcraft-av1 = { path = "crates/av1" }
 filmcraft-aac = { path = "crates/aac" }
 filmcraft-opus = { path = "crates/opus" }
@@ -51,6 +52,7 @@ filmcraft-format = { path = "crates/format" }
 filmcraft-engine = { path = "crates/engine" }
 filmcraft-ui-egui = { path = "crates/ui-egui" }
 filmcraft-automation = { path = "crates/automation" }
+filmcraft-platform = { path = "crates/platform" }
 filmcraft-testkit = { path = "crates/testkit" }

 # foundation
@@ -69,7 +71,7 @@ egui_kittest = "0.36"
 rfd = "0.17"

 [workspace.lints.rust]
-unsafe_code = "deny"
+unsafe_code = "forbid"

 [workspace.lints.clippy]
 dbg_macro = "warn"
@@ -100,6 +102,9 @@ opt-level = 3
 [profile.dev.package.filmcraft-dnx]
 opt-level = 3

+[profile.dev.package.filmcraft-apv]
+opt-level = 3
+
 [profile.dev.package.filmcraft-av1]
 opt-level = 3

@@ -1,176 +1,177 @@
-                              Apache License
-                        Version 2.0, January 2004
-                     http://www.apache.org/licenses/

-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/

-1. Definitions.
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

-   "License" shall mean the terms and conditions for use, reproduction,
-   and distribution as defined by Sections 1 through 9 of this document.
+   1. Definitions.

-   "Licensor" shall mean the copyright owner or entity authorized by
-   the copyright owner that is granting the License.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.

-   "Legal Entity" shall mean the union of the acting entity and all
-   other entities that control, are controlled by, or are under common
-   control with that entity. For the purposes of this definition,
-   "control" means (i) the power, direct or indirect, to cause the
-   direction or management of such entity, whether by contract or
-   otherwise, or (ii) ownership of fifty percent (50%) or more of the
-   outstanding shares, or (iii) beneficial ownership of such entity.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.

-   "You" (or "Your") shall mean an individual or Legal Entity
-   exercising permissions granted by this License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.

-   "Source" form shall mean the preferred form for making modifications,
-   including but not limited to software source code, documentation
-   source, and configuration files.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.

-   "Object" form shall mean any form resulting from mechanical
-   transformation or translation of a Source form, including but
-   not limited to compiled object code, generated documentation,
-   and conversions to other media types.
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.

-   "Work" shall mean the work of authorship, whether in Source or
-   Object form, made available under the License, as indicated by a
-   copyright notice that is included in or attached to the work
-   (an example is provided in the Appendix below).
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.

-   "Derivative Works" shall mean any work, whether in Source or Object
-   form, that is based on (or derived from) the Work and for which the
-   editorial revisions, annotations, elaborations, or other modifications
-   represent, as a whole, an original work of authorship. For the purposes
-   of this License, Derivative Works shall not include works that remain
-   separable from, or merely link (or bind by name) to the interfaces of,
-   the Work and Derivative Works thereof.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).

-   "Contribution" shall mean any work of authorship, including
-   the original version of the Work and any modifications or additions
-   to that Work or Derivative Works thereof, that is intentionally
-   submitted to Licensor for inclusion in the Work by the copyright owner
-   or by an individual or Legal Entity authorized to submit on behalf of
-   the copyright owner. For the purposes of this definition, "submitted"
-   means any form of electronic, verbal, or written communication sent
-   to the Licensor or its representatives, including but not limited to
-   communication on electronic mailing lists, source code control systems,
-   and issue tracking systems that are managed by, or on behalf of, the
-   Licensor for the purpose of discussing and improving the Work, but
-   excluding communication that is conspicuously marked or otherwise
-   designated in writing by the copyright owner as "Not a Contribution."
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.

-   "Contributor" shall mean Licensor and any individual or Legal Entity
-   on behalf of whom a Contribution has been received by Licensor and
-   subsequently incorporated within the Work.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."

-2. Grant of Copyright License. Subject to the terms and conditions of
-   this License, each Contributor hereby grants to You a perpetual,
-   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-   copyright license to reproduce, prepare Derivative Works of,
-   publicly display, publicly perform, sublicense, and distribute the
-   Work and such Derivative Works in Source or Object form.
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.

-3. Grant of Patent License. Subject to the terms and conditions of
-   this License, each Contributor hereby grants to You a perpetual,
-   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-   (except as stated in this section) patent license to make, have made,
-   use, offer to sell, sell, import, and otherwise transfer the Work,
-   where such license applies only to those patent claims licensable
-   by such Contributor that are necessarily infringed by their
-   Contribution(s) alone or by combination of their Contribution(s)
-   with the Work to which such Contribution(s) was submitted. If You
-   institute patent litigation against any entity (including a
-   cross-claim or counterclaim in a lawsuit) alleging that the Work
-   or a Contribution incorporated within the Work constitutes direct
-   or contributory patent infringement, then any patent licenses
-   granted to You under this License for that Work shall terminate
-   as of the date such litigation is filed.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.

-4. Redistribution. You may reproduce and distribute copies of the
-   Work or Derivative Works thereof in any medium, with or without
-   modifications, and in Source or Object form, provided that You
-   meet the following conditions:
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.

-   (a) You must give any other recipients of the Work or
-       Derivative Works a copy of this License; and
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:

-   (b) You must cause any modified files to carry prominent notices
-       stating that You changed the files; and
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and

-   (c) You must retain, in the Source form of any Derivative Works
-       that You distribute, all copyright, patent, trademark, and
-       attribution notices from the Source form of the Work,
-       excluding those notices that do not pertain to any part of
-       the Derivative Works; and
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and

-   (d) If the Work includes a "NOTICE" text file as part of its
-       distribution, then any Derivative Works that You distribute must
-       include a readable copy of the attribution notices contained
-       within such NOTICE file, excluding those notices that do not
-       pertain to any part of the Derivative Works, in at least one
-       of the following places: within a NOTICE text file distributed
-       as part of the Derivative Works; within the Source form or
-       documentation, if provided along with the Derivative Works; or,
-       within a display generated by the Derivative Works, if and
-       wherever such third-party notices normally appear. The contents
-       of the NOTICE file are for informational purposes only and
-       do not modify the License. You may add Your own attribution
-       notices within Derivative Works that You distribute, alongside
-       or as an addendum to the NOTICE text from the Work, provided
-       that such additional attribution notices cannot be construed
-       as modifying the License.
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and

-   You may add Your own copyright statement to Your modifications and
-   may provide additional or different license terms and conditions
-   for use, reproduction, or distribution of Your modifications, or
-   for any such Derivative Works as a whole, provided Your use,
-   reproduction, and distribution of the Work otherwise complies with
-   the conditions stated in this License.
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.

-5. Submission of Contributions. Unless You explicitly state otherwise,
-   any Contribution intentionally submitted for inclusion in the Work
-   by You to the Licensor shall be under the terms and conditions of
-   this License, without any additional terms or conditions.
-   Notwithstanding the above, nothing herein shall supersede or modify
-   the terms of any separate license agreement you may have executed
-   with Licensor regarding such Contributions.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.

-6. Trademarks. This License does not grant permission to use the trade
-   names, trademarks, service marks, or product names of the Licensor,
-   except as required for reasonable and customary use in describing the
-   origin of the Work and reproducing the content of the NOTICE file.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.

-7. Disclaimer of Warranty. Unless required by applicable law or
-   agreed to in writing, Licensor provides the Work (and each
-   Contributor provides its Contributions) on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-   implied, including, without limitation, any warranties or conditions
-   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-   PARTICULAR PURPOSE. You are solely responsible for determining the
-   appropriateness of using or redistributing the Work and assume any
-   risks associated with Your exercise of permissions under this License.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.

-8. Limitation of Liability. In no event and under no legal theory,
-   whether in tort (including negligence), contract, or otherwise,
-   unless required by applicable law (such as deliberate and grossly
-   negligent acts) or agreed to in writing, shall any Contributor be
-   liable to You for damages, including any direct, indirect, special,
-   incidental, or consequential damages of any character arising as a
-   result of this License or out of the use or inability to use the
-   Work (including but not limited to damages for loss of goodwill,
-   work stoppage, computer failure or malfunction, or any and all
-   other commercial damages or losses), even if such Contributor
-   has been advised of the possibility of such damages.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.

-9. Accepting Warranty or Additional Liability. While redistributing
-   the Work or Derivative Works thereof, You may choose to offer,
-   and charge a fee for, acceptance of support, warranty, indemnity,
-   or other liability obligations and/or rights consistent with this
-   License. However, in accepting such obligations, You may act only
-   on Your own behalf and on Your sole responsibility, not on behalf
-   of any other Contributor, and only if You agree to indemnify,
-   defend, and hold each Contributor harmless for any liability
-   incurred by, or claims asserted against, such Contributor by reason
-   of your accepting any such warranty or additional liability.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.

-END OF TERMS AND CONDITIONS
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
@@ -1,6 +1,6 @@
 MIT License

-Copyright (c) 2026 The FilmCraft contributors
+Copyright (c) 2026 ArtCraft Team and the FilmCraft contributors

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -0,0 +1,21 @@
+FilmCraft
+Copyright (c) 2026 ArtCraft Team and the FilmCraft contributors.
+Licensed under the MIT License or the Apache License, Version 2.0, at your option
+(LICENSE-MIT, LICENSE-APACHE).
+
+The ArtCraft name, wordmark and logos in docs/brand/ are trademarks of the ArtCraft Team. They are
+not open source and are not covered by the license above; their terms are in
+docs/brand/LICENSE-brand.txt.
+
+Third-party material
+
+This product bundles third-party material under its own licenses, listed below. The per-file
+list (author, source, license) is in ATTRIBUTION.md.
+
+Inter font (assets/fonts/Inter-*.ttf) — OFL-1.1. See assets/fonts/OFL-Inter.txt.
+Noto Serif font (assets/fonts/NotoSerif-Regular.ttf) — OFL-1.1. See assets/fonts/OFL-NotoSerif.txt.
+JetBrains Mono font (assets/fonts/JetBrainsMono-Regular.ttf) — OFL-1.1. See assets/fonts/OFL-JetBrainsMono.txt.
+Builds made with craft-fonts (CRAFT_FONTS_DIR; all official releases) also embed the fonts listed in
+https://github.com/storytold/craft-fonts/blob/main/ATTRIBUTION.md (BIZ UDPGothic, Shippori Mincho,
+BIZ UDMincho) — OFL-1.1. Their licence texts ship with the packages as OFL-<family>.txt.
+Public-domain film and NASA frames and CC0 music shown in README screenshots (docs/images/) — public domain / CC0-1.0. See ATTRIBUTION.md.
@@ -20,7 +20,7 @@
 </p>

 <p align="center">
-  <a href="#license"><img alt="License: MIT or Apache-2.0" src="https://img.shields.io/badge/license-MIT%20%7C%20Apache--2.0-8b5cf6"></a>
+  <a href="#license-and-credits"><img alt="License: MIT OR Apache-2.0" src="https://img.shields.io/badge/license-MIT%20%7C%20Apache--2.0-8b5cf6"></a>
  <img alt="Written in pure Rust" src="https://img.shields.io/badge/pure-Rust-6a3fd6?logo=rust&logoColor=white">
  <img alt="Runs on macOS, Windows and Linux" src="https://img.shields.io/badge/runs%20on-macOS%20%7C%20Windows%20%7C%20Linux-8b5cf6">
  <a href="#status"><img alt="Status: young and moving fast" src="https://img.shields.io/badge/status-young%20and%20moving%20fast-6a3fd6"></a>
@@ -184,7 +184,7 @@ No FFmpeg inside. The video codecs, AAC, Opus and the containers are our own Rus
 | **Matroska / WebM** | ✓ | | Lacing, Cues, header stripping, HDR colour metadata |
 | **Stills** | ✓ | ✓ | Import PNG, JPEG, GIF, WebP, TIFF and BMP; export PNG sequences and animated GIF |

-MXF and hardware decode are next ([roadmap](ROADMAP.md)).
+Also imported: MPEG-2 / MPEG-1 video, AC-3, MP2, MXF (OP1a / OP-Atom), MPEG transport and program streams (AVCHD, broadcast, DVD), Ogg and image sequences. Not yet: HEVC and AV1 export, camera RAW, E-AC-3. Hardware decoding works on macOS (VideoToolbox) and Windows (Media Foundation), with Linux to follow; H.264 export can use NVIDIA's encoder on Windows (opt-in) ([#30](https://github.com/storytold/filmcraft/issues/30)).

 <br>

@@ -196,7 +196,7 @@ MXF and hardware decode are next ([roadmap](ROADMAP.md)).

 <p align="center"><sub>Export mode, set to write the trailer as H.264 MP4.</sub></p>

- **H.264 MP4 with AAC, using our own encoders.** A 6-second 960×540 render takes 1.3 seconds and decodes cleanly in ffmpeg with error concealment switched off.
+- **H.264 MP4 with AAC, using our own encoders.** A 6-second 960×540 render takes 1.3 seconds and decodes in ffmpeg without a single warning, with strict error detection on.
 - **Also:** Apple ProRes 422 HQ and Motion JPEG in QuickTime, MXF OP1a and Avid-style OP-Atom (DNxHR, ProRes or H.264 with PCM and start timecode), PNG sequences, animated GIF and WAV.
 - **Background jobs** with progress and cancel, so you keep editing while it renders.
 - **Render previews:** the render bar marks segments green, yellow or red; rendered previews are cached by content, so an edit only invalidates what it touches and undo brings the green back.
@@ -220,7 +220,7 @@ Import merges the document's bins, media and sequences into your project as one

 ## Built for agents

-Every menu item, button, slider and drag in FilmCraft is a **command** with an id, typed parameters and an enabled state. There are about 135 engine commands so far, with the rest of Premiere's catalogue on the way. The UI, the CLI, a JSON control channel and an **MCP server** all dispatch the same commands, so Claude or any agent can cut, trim, grade, mix and export exactly the way a person does. The UI can also be driven at the level of mouse and keyboard: every widget has an automation id, and agents can click, drag, type and take screenshots.
+Every menu item, button, slider and drag in FilmCraft is a **command** with an id, typed parameters and an enabled state. There are more than 650 engine commands (`filmcraft-cli commands` lists them), with the rest of Premiere's catalogue on the way. The UI, the CLI, a JSON control channel and an **MCP server** all dispatch the same commands, so Claude or any agent can cut, trim, grade, mix and export exactly the way a person does. The UI can also be driven at the level of mouse and keyboard: every widget has an automation id, and agents can click, drag, type and take screenshots.

 ```jsonc
 // over the control channel (JSON lines on TCP) or as MCP tool calls
@@ -238,7 +238,7 @@ The trailer and the grades in these screenshots were built exactly this way, by
 ## Everywhere

 - **Native** on macOS, Windows and Linux, with a native macOS menu bar.
- **The web:** every crate up to the engine compiles to `wasm32`; the browser front end is next.
+- **The web:** the same engine and UI run in the browser via WebAssembly (`apps/filmcraft-web`, see [docs/web.md](docs/web.md)); every release ships it as `filmcraft-web-<version>.zip`.
 - **Swappable UI.** The interface is one crate (`ui-egui`) over the engine, so a different front end can replace it without touching editing logic.

 <br>
@@ -252,6 +252,13 @@ cargo run --release -p filmcraft-cli -- commands           # list every engine c
 cargo run --release -p filmcraft-cli -- mcp                # MCP server (headless)
 ```

+Japanese text in the interface and in titles comes from [craft-fonts](https://github.com/storytold/craft-fonts), an optional build input (release builds always include it; without it FilmCraft uses its own and the system's fonts):
+
+```sh
+git clone https://github.com/storytold/craft-fonts ../craft-fonts
+CRAFT_FONTS_DIR="$PWD/../craft-fonts" cargo run --release -p filmcraft
+```
+
 The control protocol is documented in [docs/control-protocol.md](docs/control-protocol.md). Stuck, or want to show what you made? Ask in [Discord](https://discord.gg/artcraft).

 ## Documentation
@@ -266,11 +273,26 @@ The control protocol is documented in [docs/control-protocol.md](docs/control-pr
 | [docs/control-protocol.md](docs/control-protocol.md) | Control-channel and MCP reference |
 | [docs/project-files.md](docs/project-files.md) | `.fcproj` format, schema migrations, auto-save and crash recovery |
 | [docs/graphics.md](docs/graphics.md) · [docs/captions.md](docs/captions.md) | Text engine, graphic clips and tools; caption tracks and formats |
-| [ROADMAP.md](ROADMAP.md) | Milestones and estimates |
+| [ROADMAP.md](ROADMAP.md) | Honest assessment, what's missing, milestones and estimates |

 ## Status

-FilmCraft is young and moving fast: roughly 45% of the way to Premiere Pro parity, with editing, trimming, colour, keyframes, titles, captions, mixing, codecs and export working today. [ROADMAP.md](ROADMAP.md) tracks every milestone with estimates.
+FilmCraft is young and moving fast. Editing, trimming, multicam, colour, keyframes, effects, titles, captions, mixing, codecs and export work today.
+
+We track two numbers ([ROADMAP.md](ROADMAP.md#honest-assessment-2026-10-05)):
+
+- **Feature checklist: ~87%.** Premiere Pro's menu items, effects, transitions, panels and formats that exist in FilmCraft.
+- **Ready for real work: ~50–60%.** Our honest estimate of how close FilmCraft is to replacing Premiere on real projects.
+
+The biggest gaps today:
+
+- **Speed on big footage.** Hardware decoding works on macOS and Windows; Linux has no hardware path yet. Blend modes and the most common effects run on the GPU, but Lumetri, keys and export rendering still run on the CPU; H.264 encoding can use the hardware encoder on macOS and on Windows with an NVIDIA GPU (opt-in, Export ▸ Hardware encoding), and H.265 export is hardware-only there ([#30](https://github.com/storytold/filmcraft/issues/30)).
+- **No plugins.** No VST3 / Audio Units or OpenFX hosting.
+- **Delivery codecs.** H.264 is our only delivery-codec export; no HEVC or AV1 export yet.
+- **Real-world media and platforms.** Our decoders are bit-exact on conformance streams, but camera and phone files in the wild are less tested. Windows and Linux get far less testing than macOS.
+- **AI features.** Few so far; speech to text is optional and off by default.
+
+Bug reports with real footage are the most useful thing you can send us: [open an issue](https://github.com/storytold/filmcraft/issues) or tell us in [Discord](https://discord.gg/artcraft).

 ## Architecture

@@ -300,7 +322,7 @@ stand on its own.
 | <img src="https://raw.githubusercontent.com/storytold/vectorcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.vectorcraft.png" alt="" width="32" height="32"> | **VectorCraft** | Vector illustration | [GitHub](https://github.com/storytold/vectorcraft) | [Website](https://getartcraft.com/apps/vectorcraft) |
 | <img src="https://raw.githubusercontent.com/storytold/filmcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.filmcraft.png" alt="" width="32" height="32"> | **FilmCraft** | **Video editing, color and sound · you are here** | [GitHub](https://github.com/storytold/filmcraft) | [Website](https://getartcraft.com/apps/filmcraft) |
 | <img src="https://raw.githubusercontent.com/storytold/lightcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.lightcraft.png" alt="" width="32" height="32"> | **LightCraft** | Photo library and raw development | [GitHub](https://github.com/storytold/lightcraft) | [Website](https://getartcraft.com/apps/lightcraft) |
-| <img src="https://raw.githubusercontent.com/storytold/printcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.printcraft.png" alt="" width="32" height="32"> | **PrintCraft** | Reading, organizing and protecting PDFs | [GitHub](https://github.com/storytold/printcraft) | [Website](https://getartcraft.com/apps/printcraft) |
+| <img src="https://raw.githubusercontent.com/storytold/pdfcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.pdfcraft.png" alt="" width="32" height="32"> | **PdfCraft** | Reading, organizing and protecting PDFs | [GitHub](https://github.com/storytold/pdfcraft) | [Website](https://getartcraft.com/apps/pdfcraft) |
 | <img src="https://raw.githubusercontent.com/storytold/effectcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.effectcraft.png" alt="" width="32" height="32"> | **EffectCraft** | Motion graphics and visual effects | [GitHub](https://github.com/storytold/effectcraft) | [Website](https://getartcraft.com/apps/effectcraft) |
 | <img src="https://raw.githubusercontent.com/storytold/designcraft/main/assets/app-icon/hicolor/64x64/apps/ai.storyteller.designcraft.png" alt="" width="32" height="32"> | **DesignCraft** | Page layout and publishing | [GitHub](https://github.com/storytold/designcraft) | [Website](https://getartcraft.com/apps/designcraft) |

@@ -330,21 +352,34 @@ And [**ArtCraft**](https://getartcraft.com/) itself, our AI image and video stud

 <br>

-## Credits and clean room
+## License and credits
+
+FilmCraft is dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.
+Copyright (c) 2026 ArtCraft Team and the FilmCraft contributors. Required notices are in [NOTICE](NOTICE).
+
+Bundled fonts, icons, images and other assets keep their own open licenses; each one is listed
+with its author, source and license in [ATTRIBUTION.md](ATTRIBUTION.md). Builds made with
+[craft-fonts](https://github.com/storytold/craft-fonts) (all official releases) also embed its fonts
+(OFL-1.1), listed in its [ATTRIBUTION.md](https://github.com/storytold/craft-fonts/blob/main/ATTRIBUTION.md).

 **Footage and music in the screenshots:** NASA's Apollo 11 film and television footage from [images.nasa.gov](https://images.nasa.gov) (launch, Launch Control Center, lunar surface and recovery) and the Apollo 11 air-to-ground voice transcript, all US Government works in the public domain (NASA does not endorse this project); *Night of the Living Dead* (1968), *Carnival of Souls* (1962) and *Charade* (1963), all in the US public domain; *Earth Views from the ISS* by NASA; Chopin's Nocturne Op. 48 No. 1 and Ballade No. 1, performed for Musopen and released under CC0. The media itself is not in this repository. Sources and details for every asset are in [ATTRIBUTION.md](ATTRIBUTION.md).

-FilmCraft is an independent implementation. It contains no Adobe code, icons, images, presets or LUTs, and no GPL or LGPL code; every icon is drawn in code and every asset is openly licensed and attributed ([AGENTS.md](AGENTS.md)), apart from the ArtCraft name and logo, which are trademarks of the ArtCraft team used with permission. ffmpeg is used only as an external test oracle.
+FilmCraft is an independent implementation. It contains no Adobe code, icons, images, presets or LUTs, and no GPL or LGPL code; every icon is drawn in code and every asset is openly licensed and attributed ([AGENTS.md](AGENTS.md)), apart from the ArtCraft name and logos, which are trademarks of the ArtCraft Team used under [`docs/brand/LICENSE-brand.txt`](docs/brand/LICENSE-brand.txt). ffmpeg is used only as an external test oracle.
+
+The ArtCraft name, wordmark and logos in [`docs/brand/`](docs/brand/) are trademarks of the
+ArtCraft Team and are not covered by this license. They may be used only unmodified, and only as
+part of this repository and FilmCraft, under [`docs/brand/LICENSE-brand.txt`](docs/brand/LICENSE-brand.txt).
+Forks and modified versions must remove them.

 <sub>Adobe, Photoshop, Illustrator, Premiere Pro, Lightroom, Acrobat, After Effects and InDesign are trademarks or registered trademarks of Adobe Inc. in the United States and/or other countries. FilmCraft is an independent, open-source project and is not affiliated with, sponsored by or endorsed by Adobe Inc.; these names are used only to describe the workflows it is compatible with.</sub>

-## License
-
-FilmCraft is dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option. Bundled assets keep their own open licences, listed in [ATTRIBUTION.md](ATTRIBUTION.md). The ArtCraft name and logos in `docs/brand/` are trademarks of the ArtCraft team and are not covered by this licence.
-
 <br>

 <p align="center">
  <a href="https://getartcraft.com/"><img alt="ArtCraft" src="docs/brand/artcraft-mark.svg" width="28"></a><br>
  <sub>Made by the <a href="https://getartcraft.com/">ArtCraft</a> team and community.</sub>
 </p>
+
+## Star history
+
+[![Star History Chart](https://api.star-history.com/svg?repos=storytold/filmcraft&type=Date&legend=top-left)](https://www.star-history.com/?repos=storytold%2Ffilmcraft&type=date&legend=top-left)
@@ -1,10 +1,88 @@
 # FilmCraft Roadmap

-Progress toward feature parity with Adobe Premiere Pro, with estimates. Updated as milestones land.
+Progress toward parity with Adobe Premiere Pro, with estimates. Updated as milestones land.

-**Last updated:** 2026-10-02 · **Overall parity:** ~87% (measured scorecard below) · **Code:** 34 crates, 1605 tests
+**Last updated:** 2026-10-05 · **Feature checklist:** ~87% · **Ready for real work:** ~50–60% · **Code:** 35 crates, 1605+ tests

-## Parity scorecard
+Two numbers, because they answer different questions. The **feature checklist** counts whether
+Premiere's menu items, effects, panels and formats exist in FilmCraft. **Ready for real work** is
+our honest estimate of how close FilmCraft is to replacing Premiere for an editor on real
+projects: depth, correctness, robustness, speed and the pro ecosystem. The gap between the two
+is the work that matters most now. Agents: read [Where we are lacking](#where-we-are-lacking)
+before choosing work.
+
+## Honest assessment (2026-10-05)
+
+### How the checklist number is made, and what it doesn't tell you
+
+- **Partly measured.** The menu figure comes from diffing a dump of Premiere 26.5's menus against
+  `filmcraft-cli commands`. The effects, transitions and audio-effects counts are checked by unit
+  tests against Premiere's Effects panel tree (`premiere_26_video_effects_catalogue`,
+  `premiere_audio_set_is_complete_and_foldered`, `premiere_26_transition_tree`).
+- **Partly agent-reported.** The other areas' percentages are written by the agents doing the work.
+  No automated parity check runs in CI (PhotoCraft has `cargo xtask parity`; we don't yet), so
+  nothing stops a number drifting upward.
+- **Presence, not quality.** An item counts once it exists. An effect described as an
+  "approximation" counts the same as an exact one. Nothing compares our rendering with
+  Premiere's.
+- **Weights understate what users hit first.** Performance carries 5%. Plugins and AI features
+  aren't in the scorecard at all.
+
+### By dimension
+
+| Dimension | Checklist says | Honest estimate | Evidence |
+|---|---|---|---|
+| **Feature breadth** (menus, commands, panels) | ~86–95% | **~85%** | Menu diff against Premiere 26.5; effect, transition and audio-effect catalogues complete by test. The long tail is mostly there. |
+| **Correctness in depth** | not tracked | **~60–70%** | A first-time contributor found four real bugs in core paths within hours (#5–#8: AIFF import failed, Slide left linked audio behind, transitions didn't follow ripple trims, export ignored start/end times). User reports: Color Matte always grey with no picker (#29); ALSA audio error on Linux (#23). Settings are "most wired", not all. |
+| **Codecs and media** | ~90% | **~75%** | Our decoders are bit-exact on conformance streams. Real camera and phone media (variable frame rate, damaged files, unusual containers) is far less tested. No camera RAW (RED, BRAW, ARRIRAW), no E-AC-3. |
+| **Export** | ~92% | **~70%** | Delivery: H.264 only (ProRes, DNxHR and image sequences cover mastering). No HEVC or AV1 export. AAF and OMF have never been validated in Avid Media Composer or Pro Tools. Export renders and encodes on the CPU only. |
+| **Performance and hardware** | ~62% | **~35–40%** | Premiere runs effects, decoding and encoding on the GPU and the hardware media engines. Here, hardware decode works on macOS (VideoToolbox, #33; active in the desktop app only since #41, so releases up to 0.2.1 decoded in software) and Windows (Media Foundation / Direct3D 11 DXVA, H.264, HEVC Main / Main 10, VP9 and AV1 4:2:0 8/10-bit, #30). The GPU does compositing, blend modes (#32) and 31 common effects (GPU2): colour adjustments, crop/flip/transform, blurs, sharpen. Lumetri, keys, masks, the remaining effects and export rendering are CPU; H.264 encoding can use VideoToolbox on macOS (opt-in per export, no B-frames) and NVENC on Windows with an NVIDIA GPU (opt-in per export), and H.265 (HEVC) export exists there only, through the same hardware encoder. Linux has no hardware path. 8K isn't real-time (AV1 is on Windows with a hardware decoder). The effect list shows Premiere's "GPU accelerated" badge, but only 31 effect ids run on the GPU here; the rest, Lumetri included, run on the CPU. |
+| **Stability** | not tracked | **improving, unproven** | The never-crash pass (no panics in product code, last-resort guards) landed on 2026-10-04. There's no field record from real users' projects yet. |
+| **Plugins and pro ecosystem** | not tracked | **~0–10%** | No audio plugin hosting (VST3 / Audio Units) and no third-party video effects (OpenFX). For many professional editors this alone rules FilmCraft out. Team Projects and Productions are out of scope by design. |
+| **AI features** | partial | **~25–35%** | Speech to text exists but is off in default builds (the `whisper` feature). Enhance Speech is a DSP chain, not a model. Auto Reframe is approximate. No Generative Extend, and no media-intelligence search or auto colour. |
+| **Platforms** | not tracked | **macOS solid; Windows and Linux thin** | Development and testing happen on macOS. Windows and Linux are built for releases but barely exercised at runtime. The web build is a compile target; the browser app shell isn't finished. |
+| **UI fidelity** | ~85% | **~80%** | Agents compare with Premiere reference screenshots; this hasn't been checked independently. |
+
+### Where we are lacking
+
+In priority order. Agents should prefer this work over adding more checklist items.
+
+1. **Hardware acceleration** (#30), the most visible gap to users:
+   - hardware decode on Linux (VA-API);
+   - zero-copy decoded frames into wgpu;
+   - the remaining effects on the GPU: Lumetri, keys, Vignette, Video Limiter, masks (31 common effects are done);
+   - GPU export, then hardware encode: H.264 and H.265 on macOS are in (H.264 opt-in; H.265 has no other encoder), H.264 on NVENC (Windows, opt-in); HEVC on Windows and Linux remain.
+2. **A measured parity number.** Add `cargo xtask parity`, run in CI. It should cover menus,
+   commands, effects, transitions, panels, preferences and formats against the Premiere snapshot in
+   `plan/premiere/`. It should report presence and fidelity separately (exact, approximate, stub).
+3. **Real-world media corpus.** Phone, camera and screen recordings, variable frame rate, damaged
+   files, long GOPs, odd containers. Each gets an import → edit → export round-trip test with an
+   ffprobe / ffmpeg oracle.
+4. **Workflow acceptance tests.** Scripted MCP sessions that do real jobs end to end: assemble and
+   trim a scene, colour it, mix and loudness-normalise it, caption it, deliver it, round-trip
+   through XML / AAF.
+5. **Windows and Linux at runtime.** CI that runs the test suite and a headless playback/export
+   smoke test on both, not just release builds. Fix the Linux audio path (#23).
+6. **Delivery codecs.** HEVC export is in on macOS (VideoToolbox, 8-bit, no software encoder); still to do: HEVC elsewhere, 10-bit / HDR HEVC, and AV1 (`rav1e`, BSD-2).
+7. **Plugin hosting** (VST3 / Audio Units, then OpenFX). Needs FFI, so it falls under the isolated
+   `unsafe` crate rule (AGENTS.md §0.3). **Owner decision needed** before starting.
+8. **AI features** with openly licensed local models: transcription on by default, text-based
+   editing, speech enhancement, reframing.
+9. **The web app shell**: file access, WebCodecs, audio.
+
+### Where we're going
+
+**Next:** close items 1–5. Hardware acceleration fixes the gap users notice first (CPU-bound 4K playback and export). The
+parity tool, media corpus and workflow tests make the progress number trustworthy. Windows and
+Linux CI makes "runs everywhere" true.
+
+**After that:** delivery codecs, plugin hosting (pending the owner's decision) and AI features,
+measured with the same tools.
+
+**Goal:** "ready for real work" at 85%+, measured rather than estimated, on all three desktop
+platforms.
+
+## Feature checklist scorecard

 Measured against Premiere Pro 26.5 on this machine. Menu items: the native menu bar dump, minus
 Adobe-cloud-only items (Team Projects, Productions, Firefly, Stock, Dynamic Link, account/help pages),
@@ -22,11 +100,14 @@ matched against `filmcraft-cli commands` and the UI command table. Effects: the
 | Graphics and captions | 8% | text engine, shapes, per-character styles, our own graphics templates (.fcgt, 8 built-ins, export/install/edit), rolls/crawls, responsive pins + time, captions SRT/VTT/SCC/MCC/STL/TTML/DFXP, transcripts | ~85% |
 | Export | 8% | own H.264/AAC, ProRes, DNxHR, MXF OP1a/OP-Atom, image sequences, GIF, WAV, 5.1; preset library + user presets, full Export-mode settings, queue, Quick Export; AAF (Edit Protocol) import/export, OMF 2.0 export; no AAF/OMF validation against Avid/Pro Tools yet | ~92% |
 | Preferences and project management | 5% | Settings dialog with 16 categories (most settings wired), project settings, scratch disks, search bins, templates | ~80% |
-| Performance | 5% | 1080p real-time, 3×1080p; 4K H.264 real-time at load ≤140 (−23% decoder cycles, opt-in draft decoding at 1/2–1/4); HEVC 2.5× cheaper, catch-up decoding, `cargo xtask bench` + `perf.stats`; 8K and AV1 not yet real-time on a loaded machine | ~62% |
+| Performance | 5% | 1080p real-time, 3×1080p; 4K H.264 real-time at load ≤140 (−23% decoder cycles, opt-in draft decoding at 1/2–1/4); HEVC 2.5× cheaper, catch-up decoding, `cargo xtask bench` + `perf.stats`; blend modes on the GPU (#32); 8K and AV1 not yet real-time on a loaded machine; no hardware path on Linux, and on Windows only decode and opt-in NVENC H.264 export (see the honest assessment: ~35–40% against Premiere) | ~62% |
 | **Weighted total** | | | **~87%** |

 ## Estimate to parity

+This estimate is for the **feature checklist**. Closing the honest-assessment gaps (above) is the
+"Robust on real-world material" row, plus plugins and AI features, which it doesn't include.
+
 Measured throughput in the last work block (2026-10-01 night → 10-02): five Opus 5.5 agents in
 parallel for ~4.5 wall-clock hours (~18 agent-hours including integration) moved parity by ~4 points
 (≈4–5 agent-hours per point), on a machine that was heavily overloaded (load 150–300 on 14 cores) and
@@ -62,7 +143,7 @@ Status: ✅ done · 🟡 in progress · ⬜ not started. Estimates are remaining
 | M2 | H.264 decoder | ✅ | Own decoder, bit-exact on 37+ streams, 500–600 fps 1080p | — | — |
 | M3 | Editing core | 🟡 | Edit algebra (insert/overwrite/razor/lift/extract/ripple/roll/slip/slide/rate-stretch/nest/paste), tools, markers, trim mode + Trim Monitor + dynamic J/K/L trimming, Keyboard Shortcuts editor with FilmCraft/Premiere/FCP/Avid presets; Edit/Clip/File menu commands (Label colours and Select Label Group, Paste/Remove Attributes, Select All Matching, Remove Unused, Consolidate Duplicates, Sequence From Clip, Bin From Selection, Offline File, Close Project, Make/Edit Subclip, Modify Audio Channels/Timecode, Frame Hold Options/Add Frame Hold/Insert Frame Hold Segment, Time Interpolation with frame blending, Fit/Fill frame, Breakout to Mono, Extract Audio, Replace With Clip; M3.11: Scene Edit Detection (pure-Rust cut detection, background job), Normalize Mix Track, Simplify Sequence, Transcribe Sequence, Find/Find Next and search bins, Automate to Sequence, Edit Original, Edit Offline, Source Settings, Update Metadata (XMP), Generate Audio Waveform, Project Settings General/Scratch Disks, Get Media File Properties, Save as Template, Selection as FilmCraft Project, Avid Log Exchange export, Flash Cue markers, Dynamic Audio Waveforms, Reveal Log Files, System Compatibility Report); M3.12 keyboard parity: Premiere's default keyboard (~115 keyboard-only commands: edit-point navigation on targeted/any track, select clip at playhead/next/previous, extend edit to playhead, nudge/slip/slide selection, target and source-patch toggles, clip volume ±1 dB/many, frame maximize/full screen/panel cycling, monitor zoom, track heights, Project and Text panel keyboard navigation, text size/leading/alignment, Export Frame, poster frames; see docs/keyboard.md); multicam (Create Multi-Camera Source Sequence, Multi-Camera view with live switching on 1–9, angle switching, Enable/Flatten, Edit Cameras) and sync (Synchronize, Merge Clips; In/Out/timecode/marker/audio — GCC-PHAT, sample-accurate) | Multicam paging >16 angles and grid thumbnails, optical flow (renders as frame blending), 39 Premiere default shortcuts skipped with reasons in docs/keyboard.md (Productions, AI/cloud tools, work area bar, Production/Search panels) | 6–10 |
 | M4 | Playback | 🟡 | Audio-clock master, prefetch with cancellation, J/K/L, correct dropped-frame stats, playback resolution, render bar + content-hashed render previews, App Nap opt-out; 1080p H.264 and 3 stacked 1080p streams play with 0 dropped frames | 4K under load, 8K, frame-threaded AV1 decode, reduced-resolution decode for multicam grids | 6–10 |
-| M5 | Effects, keyframes, GPU | 🟡 | ~60 CPU effects, 30 transitions, keyframes + value/velocity graphs, wgpu compositor, effect + opacity masks (ellipse/polygon/pen, feather, expansion, modes; CPU/WGSL parity), mask tracking (Lucas–Kanade + RANSAC), adjustment layers, effect presets (built-in + user, JSON import/export) | Full ~150-effect catalogue, WGSL parity for all effects and masks in the live GPU path, Warp Stabilizer, Morph Cut | 20–30 |
+| M5 | Effects, keyframes, GPU | 🟡 | All 93 Premiere 26 video effects and 84 transitions (CPU), blend modes and 31 common effects on the GPU (#32, GPU2), keyframes + value/velocity graphs, wgpu compositor, effect + opacity masks (ellipse/polygon/pen, feather, expansion, modes; CPU/WGSL parity), mask tracking (Lucas–Kanade + RANSAC), adjustment layers, effect presets (built-in + user, JSON import/export) | Effects on the GPU (in progress, #30), GPU masks in the live path, GPU export, exact Warp Stabilizer (3-D) and Morph Cut | 20–30 |
 | M6 | Export | ✅ | Own H.264 encoder (High/Main/Baseline, B-frames, VBR/CBR/2-pass) → MP4 or QuickTime + own AAC; ProRes, DNxHR, MJPEG, PNG/TIFF/BMP sequences (Premiere-style numbering), GIF, WAV, AIFF; background jobs; M6.5: Export mode parity (frame size / rate / scaling / pixel aspect, profile / level, CBR / VBR 1- and 2-pass, keyframe distance, audio codec / rate / channels / bitrate / sample size, multiplexer, burn-in or sidecar captions, image / name / timecode overlays, video limiter, loudness normalization with true-peak limiter, metadata, ranges, estimated size, summary), 24 built-in presets + user presets with favourites and import/export (Preset Manager), export queue (reorder, cancel, retry, several sequences / ranges), Quick Export; `export.*` commands and `filmcraft-cli export --preset` | Interlaced encoding, 5.1 audio, smart render, publishing destinations | 6–8 |
 | M7 | Audio | 🟡 | Mixer graph (tracks → submixes → Mix, pre/post-fader inserts and sends, latency-compensated, sample-accurate, ~6× realtime for 24 tracks × 3 effects on one core), Audio Track Mixer + Audio Clip Mixer panels, track automation (Off/Read/Latch/Touch/Write, recorded live while playing, thinned to keyframes, timeline lanes with pen editing), solo/solo-safe, channel mapping basics, peak + BS.1770 loudness meters (match ffmpeg), DSP crate with 16 clip/track effects, Audio Gain (set/adjust/normalize), Constant Power / Constant Gain / Exponential Fade, Essential Sound (types, Loudness auto-match, Repair incl. DeEss/DeReverb, Clarity, Creative, Ducking keyframes, presets; full Dialogue chain 22× realtime) | Music duration remix, ML speech enhancement, 5.1 panner and multichannel buses, voice-over record, effect editor windows (EQ curve), remaining effects (multiband, convolution reverb), clip-mixer automation recording | 6–9 |
 | M8 | Colour | 🟡 | Lumetri: basic, creative + looks, RGB & hue curves, wheels, HSL secondary, vignette, section bypass; Input LUT / Look LUT (.cube 1D/3D/shaper, .3dl; tetrahedral CPU + WGSL; project LUT library; built-in camera conversions); Colour Match (Oklab tonal-range statistics, skin protection, solved in Lumetri wheels); colour management: Rec. 709 / Rec. 2100 PQ / HLG working spaces + wide gamut, Interpret Footage colour space (S-Log3, V-Log, Canon Log 2/3, LogC3/4, Apple Log, D-Log from published specs), metadata auto-detect, BT.2390 tone mapping, gamut mapping, HDR export signalling (VUI/colr/mdcv/clli/SEI, ffprobe-verified); Lumetri Scopes: Vectorscope YUV (75/100 % targets, skin-tone line) and HLS, Histogram, Parade (RGB/YUV/RGB-White), Waveform (RGB/Luma/YC/YC no Chroma), presets, Rec. 601/709/2100, 8-bit/float/HDR (cd/m²) scales, multi-scope grid, `scopes.read` | HDR-aware Lumetri maths, macOS EDR monitors, mastering metadata → tone-map peak, D-Log M (no published formula), HSL Secondary refine | 3–5 |
@@ -73,10 +154,15 @@ Status: ✅ done · 🟡 in progress · ⬜ not started. Estimates are remaining

 ## Running now

- Nothing; next: remaining Premiere menu items (Settings categories, Scene Edit Detection, Normalize Mix Track, OMF/AAF, Find), AV1 single-thread re-measure on an idle machine
+- **Hardware acceleration (#30):** landed: blend modes on the GPU (#32); VideoToolbox hardware decode + the `platform` FFI crate (#33); 31 common effects on the GPU (GPU2). Windows: Media Foundation / Direct3D 11 H.264 + HEVC decode (HW2) and VP9 + AV1 (HW3), NVENC H.264 export (HW4, opt-in). Next: VA-API (Linux) decode, zero-copy upload, Lumetri on the GPU.
+- **Next:** [Where we are lacking](#where-we-are-lacking) items 1–5. GPU export waits for the export-crate work (#19 and the never-crash follow-up) to land.

 ## Log

+- **2026-10-06:** 21 community PRs landed (#19, #28, #38, #39, #41–#60). Highlights: hardware decoding is now actually on in the desktop app (#41: `register()` sat inside a `log::info!` that never ran, so #33's VideoToolbox path only worked in the CLI and benchmarks); decode memory on long timelines cut sharply (frame pool, shared GOP-cache budget, positional file reads); exports are byte-identical across machines (#19); crash fix for odd track names over MCP (#44); ripple trim, ripple delete and speed changes move split-edit clips once (#56–#58); Japanese interface using an installed system font (#38; no fonts bundled); MCP annotations, resources, export progress and cancellation (#28).
+
+- **2026-10-05:** honest assessment added (checklist ~87% vs ready for real work ~50–60%). Hardware acceleration started (#30): blend modes on the GPU (#32); VideoToolbox decode + `platform` crate, the one crate allowed `unsafe` (#33). Community fixes landed: AIFF import, export start/end ranges, transitions following ripple trims, Slide moving linked audio (#5–#8).
+
 - **2026-10-04 (later):** interchange + MXF export (M11.4/M6.6): own compound-file container (`crates/cfb`), AAF Edit Protocol import/export (embedded/linked/consolidated audio, video mixdown, handles, breakout to mono), OMF 2.0 export (Bento), MXF OP1a/OP-Atom writer (DNxHR/ProRes/H.264/PCM) as export formats. 1605 tests.

 - **2026-10-04:** MPEG-2 (M9.15): own MPEG-2/MPEG-1 video decoder (4:2:2, interlaced, field pictures; IEEE 1180 IDCT), MPEG TS/PS demux (AVCHD .mts, .m2ts, .ts, .mpg/.vob/.mod), own AC-3 decoder (ATSC A/52), MP2, LATM AAC, Blu-ray/DVD LPCM, MPEG-2 in MXF/MOV/MP4/MKV. 1562 tests.
@@ -85,6 +171,7 @@ Status: ✅ done · 🟡 in progress · ⬜ not started. Estimates are remaining

 - **2026-10-03 (later):** graphics & captions (M10.7): `.fcgt` graphics templates (export/install/apply/edit, 8 original built-ins; Adobe .mogrt refused), Essential Graphics Browse/Edit, rolls/crawls, responsive design pins and time, per-character styles, Upgrade Caption to Graphic / to Source Graphic, MCC/EBU STL/TTML/DFXP, Replace Fonts; schema v12. 1479 tests.
 - **2026-10-03:** 4K H.264 playback (M4.9): vectorised deblocking, branch-free CABAC bins and column-parallel inverse transforms cut H.264 decoding by 23 % (cycles per frame, bit-exact; 4K cold seeks −27 % CPU); opt-in draft decoding (Settings ▸ Playback) skips deblocking of non-reference pictures and uploads decimated planes while playing at 1/2–1/4, never for paused frames or exports; conformance runs 1, 3 and all threads. 4K plays 192/0 at load 100–140 (before: only at load ~90).
+- **2026-10-03:** 4K VP9 / HEVC / AV1 playback (M4.10): VP9 frame threading (references published per superblock row, loop filter overlapping the next frames) plus a vectorised loop filter, column-parallel transforms and 16-bit MC cut VP9 work by 25 % single-threaded and 44 % with all cores (4K decode 8 → 27–34 fps at load ~200); HEVC −28 % (vectorised SAO, MC without per-block zeroing, batched bypass bins), AV1 −20 % (fixed-width MC, recycled planes); opt-in draft decoding for all three; bit-exact at 1, 3 and all threads. 4K VP9 and HEVC now play 192/0 at load ~200 (before: 0–58 of 192 shown).

 - **2026-10-03:** keyboard parity (M3.12: 143 new commands on Premiere's default keys, table validated against the registry), audio (M7.8: 5.1 tracks/submixes/Mix, 5.1 panner, BS.775 downmix, 5.1 WAV/MOV/AAC export, voice-over record with punch-in, Remix, Clip Mixer Latch/Touch/Write). 1432 tests.

@@ -115,3 +202,7 @@ Status: ✅ done · 🟡 in progress · ⬜ not started. Estimates are remaining
 - **2026-09-30 (midday):** HEVC decoder, Matroska/WebM demuxer and audio DSP merged; HEVC import wired; asset rules (AGENTS.md, ATTRIBUTION.md, `cargo xtask assets`); README with hero screenshot and the Craft family.
 - **2026-09-30 (late morning):** keyframe value/velocity graphs; xtask gates; H.264 MP4 export; Lumetri curves, wheels, looks, HSL secondary.
 - **2026-09-30 (early morning):** H.264 decoder, ProRes, AAC; GPU compositor; MCP; Premiere 26 visual fidelity pass.
+
+### Interface localization
+
+Edit > Language switches English/Japanese/Spanish/Portuguese (Brazilian) and persists in UI state. Commands `app.language.english`, `app.language.japanese`, `app.language.spanish` and `app.language.portuguese` are reachable through the control channel. Core native/in-window menu labels are translated; untranslated labels use English. Japanese text uses the Japanese fonts from [craft-fonts](https://github.com/storytold/craft-fonts) when FilmCraft is built with them (`CRAFT_FONTS_DIR`; all official releases, including the web build), otherwise a Japanese font already installed on the system; with neither, switching to Japanese is refused with a message. Dialog/panel translation coverage remains open. Existing vertical text support is preserved.
@@ -21,6 +21,7 @@ whisper = ["filmcraft-engine/whisper", "filmcraft-engine/speech-download"]
 filmcraft-engine = { workspace = true }
 filmcraft-media = { workspace = true }
 filmcraft-codecs = { workspace = true }
+filmcraft-platform = { workspace = true }
 filmcraft-mxf = { workspace = true }
 filmcraft-mpegts = { workspace = true }
 filmcraft-ogg = { workspace = true }
@@ -88,7 +88,9 @@ fn insert_dotted(m: &mut Map<String, Value>, key: &str, v: Value) {
            if !e.is_object() {
                *e = Value::Object(Map::new());
            }
-            insert_dotted(e.as_object_mut().expect("object"), tail, v);
+            if let Value::Object(child) = e {
+                insert_dotted(child, tail, v);
+            }
        }
    }
 }
@@ -2,6 +2,8 @@
 //!
 //! Run `filmcraft-cli help` for the full reference (also in docs/agents.md).

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 mod args;
 mod probe;

@@ -25,12 +27,16 @@ SUBCOMMANDS
  inspect [project|sequence]    project tree or active sequence as JSON (default: both)
  import <file>...              import media into the project
  export <out> [--preset name] [--format f] [--range r] [--start s --end s] [--settings json]
+         [--scale f] [--quality 0-100] [--no-audio] [--queue]
                                export the active sequence and wait for it to finish: with an
                                export preset (`export --list-presets`; built-in or the user's), or
-                                a format (h264|prores|dnxhr|mjpeg|mxf-op1a|mxf-opatom|png|tiff|bmp|gif|wav|aiff, guessed
+                                a format (h264|hevc|prores|dnxhr|apv|mjpeg|mxf-op1a|mxf-opatom|png|tiff|bmp|gif|wav|aiff, guessed
                                from the extension); --range entire|inOut|workArea, or a custom
                                range in seconds; --settings is ExportSettings JSON merged over the
-                                preset; --queue adds to the export queue and runs it instead
+                                preset; --scale renders at a fraction of the frame size (0.5 =
+                                half); --quality 0-100 for the formats that take one; --no-audio
+                                leaves the sound out; --queue adds to the export queue and runs it
+                                instead
  export --list-presets [query] list export presets (name, category, format) as JSON
  render --seconds S --out f.png [--scale 0.5]   render one Program frame to PNG
  probe <media> [--image-sequence]
@@ -103,7 +109,8 @@ impl Backend {
    async fn exec(&mut self, id: &str, params: Value) -> Result<Value, String> {
        match self {
            Backend::Local(s) => s.execute(id, params).map_err(|e| e.to_string()),
-            Backend::Bridge(b) => b.call("engine.execute", json!({"command": id, "params": params})).await.map_err(|e| e.to_string()),
+            // a blocking export runs as an app job polled by the client (#91, #92)
+            Backend::Bridge(b) => b.execute(id, params).await.map_err(|e| e.to_string()),
        }
    }

@@ -147,12 +154,19 @@ fn format_for(path: &str) -> Option<&'static str> {
    })
 }

+/// OS hardware video decoders (VideoToolbox on macOS, Media Foundation on Windows) in front of our
+/// own, as in the desktop app. Also what `mcp` and the headless commands decode with.
+fn register_hardware_decoders() -> filmcraft_platform::Availability {
+    filmcraft_platform::register()
+}
+
 #[tokio::main]
 async fn main() {
    if matches!(std::env::args().nth(1).as_deref(), Some("--version" | "-V")) {
        println!("filmcraft-cli {}", env!("CARGO_PKG_VERSION"));
        return;
    }
+    register_hardware_decoders();
    let a = Args::parse(std::env::args().skip(1));
    let Some(cmd) = a.pos(0) else { usage("missing subcommand") };
    match cmd {
@@ -339,7 +353,7 @@ async fn main() {
            if a.opt("--bridge").is_some() {
                usage("render is headless; with --bridge use the MCP `render_frame` tool or `exec` ui commands");
            }
-            let Backend::Local(mut s) = Backend::open(&a) else { unreachable!() };
+            let Backend::Local(mut s) = Backend::open(&a) else { usage("render is headless") };
            let secs: f64 = a.opt("--seconds").and_then(|v| v.parse().ok()).unwrap_or(0.0);
            let scale: f32 = a.opt("--scale").and_then(|v| v.parse().ok()).unwrap_or(1.0);
            let out = a.opt("--out").unwrap_or("frame.png");
@@ -356,7 +370,7 @@ async fn main() {
                Some(addr) => filmcraft_automation::FilmcraftMcp::bridge(addr).unwrap_or_else(|e| fail(e)),
                None => match Backend::open(&a) {
                    Backend::Local(s) => filmcraft_automation::FilmcraftMcp::headless(*s),
-                    Backend::Bridge(_) => unreachable!(),
+                    Backend::Bridge(_) => usage("mcp: use --bridge ADDR to drive a running app"),
                },
            };
            if let Err(e) = server.serve_stdio().await {
@@ -369,6 +383,14 @@ async fn main() {

 #[cfg(test)]
 mod format_tests {
+    /// The CLI (and MCP / headless runs, which share its entry point) registers the hardware
+    /// decoders at start-up.
+    #[test]
+    fn startup_registers_the_hardware_decoders() {
+        let hardware = super::register_hardware_decoders();
+        assert_eq!(filmcraft_platform::registered(), cfg!(any(target_os = "macos", target_os = "windows")), "{hardware:?}");
+    }
+
    #[test]
    fn export_format_from_extension() {
        assert_eq!(super::format_for("out/clip.MXF"), Some("mxf-op1a"));
@@ -170,11 +170,11 @@ pub fn install() -> Result<(), JsValue> {
        &obj,
        "readFile",
        Closure::<dyn Fn(String) -> js_sys::Promise>::new(|path: String| {
-            future_to_promise(async move {
+            future_to_promise(caught(async move {
                let blob = crate::fs::blob(&path).ok_or_else(|| JsValue::from_str(&format!("{path}: not found")))?;
                let buf = JsFuture::from(blob.array_buffer()).await?;
                Ok(js_sys::Uint8Array::new(&buf).into())
-            })
+            }))
        })
        .into_js_value(),
    )?;
@@ -191,10 +191,10 @@ pub fn install() -> Result<(), JsValue> {
        &obj,
        "importUrl",
        Closure::<dyn Fn(String, JsValue) -> js_sys::Promise>::new(|url: String, name: JsValue| {
-            future_to_promise(async move {
+            future_to_promise(caught(async move {
                let f = fetch_file(&url, name.as_string()).await?;
                Ok(to_js(&crate::import::import_files(vec![f]).await))
-            })
+            }))
        })
        .into_js_value(),
    )?;
@@ -202,13 +202,13 @@ pub fn install() -> Result<(), JsValue> {
        &obj,
        "openProject",
        Closure::<dyn Fn(JsValue) -> js_sys::Promise>::new(|src: JsValue| {
-            future_to_promise(async move {
+            future_to_promise(caught(async move {
                let file = match src.as_string() {
                    Some(url) => fetch_file(&url, None).await?,
                    None => files_of(&src).into_iter().next().ok_or("need a File or URL")?,
                };
                crate::import::open_project_file(file).await.map(|v| to_js(&v)).map_err(|e| JsValue::from(js_sys::Error::new(&e)))
-            })
+            }))
        })
        .into_js_value(),
    )?;
@@ -216,3 +216,19 @@ pub fn install() -> Result<(), JsValue> {
    js_sys::Reflect::set(&w, &"filmcraft".into(), &obj)?;
    Ok(())
 }
+
+/// `f`, rejecting with an [`as_error`] `Error`.
+async fn caught(f: impl std::future::Future<Output = Result<JsValue, JsValue>>) -> Result<JsValue, JsValue> {
+    f.await.map_err(as_error)
+}
+
+/// Every member rejects with an `Error` (#90), as `execute` and `request` do, so `e.message` and
+/// `e instanceof Error` work: a plain string (a fetch status, "not found") becomes one, and an
+/// `Error` passes through unchanged.
+fn as_error(e: JsValue) -> JsValue {
+    if e.is_instance_of::<js_sys::Error>() {
+        return e;
+    }
+    let msg = e.as_string().unwrap_or_else(|| format!("{e:?}"));
+    js_sys::Error::new(&msg).into()
+}
@@ -289,20 +289,25 @@ impl ByteReader for BlobReader {
            }
            return Err(filmcraft_media::pending::would_block());
        }
-        FS.with(|fs| {
+        let complete = FS.with(|fs| {
            let mut fs = fs.borrow_mut();
            fs.clock += 1;
            let t = fs.clock;
            let mut pos = 0usize;
            for c in c0..=c1 {
-                let (d, used) = fs.chunks.get_mut(&(self.id, c)).expect("checked above");
+                // Present (checked above); evicted in between would be a bug, reported as an error.
+                let Some((d, used)) = fs.chunks.get_mut(&(self.id, c)) else { return false };
                *used = t;
                let a = if c == c0 { (offset - c * CHUNK) as usize } else { 0 };
                let n = (d.len() - a).min(buf.len() - pos);
                buf[pos..pos + n].copy_from_slice(&d[a..a + n]);
                pos += n;
            }
+            true
        });
+        if !complete {
+            return Err(filmcraft_media::pending::would_block());
+        }
        // read-ahead for sequential access
        for c in c1 + 1..=(c1 + READ_AHEAD).min(last) {
            request(self.id, c);
@@ -16,6 +16,7 @@
 //!
 //! Everything here is `wasm32`-only; on other targets the crate is empty.
 #![cfg(target_arch = "wasm32")]
+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]

 pub mod api;
 pub mod audio;
@@ -135,7 +136,14 @@ pub async fn start(canvas_id: String) -> Result<(), JsValue> {
    import::install_drop_handlers()?;

    let demo = !query_flag("empty");
-    let web_options = eframe::WebOptions::default();
+    let mut web_options = eframe::WebOptions::default();
+    // `?webgl`: WebGL2 only. The page reloads with it when starting on WebGPU fails (an adapter
+    // whose device can't be created, a driver the browser rejects…); see `index.html`.
+    if query_flag("webgl")
+        && let eframe::egui_wgpu::WgpuSetup::CreateNew(c) = &mut web_options.wgpu_options.wgpu_setup
+    {
+        c.instance_descriptor.backends = eframe::wgpu::Backends::GL;
+    }
    let runner = eframe::WebRunner::new();
    runner
        .start(
@@ -193,14 +193,16 @@ pub fn reader_opener(name: &str, head: &[u8], reader: &SharedReader) -> Option<R
        Err(_) => return Some(Ok(inner)),
    };
    let Some(track) = file.tracks.iter().position(|t| t.kind == TrackKind::Video && !t.samples.is_empty()) else { return Some(Ok(inner)) };
-    let entry = &file.tracks[track].entries[0];
+    let Some(entry) = file.tracks[track].entries.first() else { return Some(Ok(inner)) };
    let fourcc = entry.format.to_string();
    let Some((family, codec, description)) = codec_string(&entry.codec, &fourcc) else { return Some(Ok(inner)) };
    if !SUPPORTED.with(|s| s.borrow().contains(&family)) {
        return Some(Ok(inner));
    }
    let info = inner.info().clone();
-    let (w, h) = info.video.as_ref().map(|v| (v.width, v.height)).unwrap_or((0, 0));
+    // the decoder wants the coded size; `info` reports the display size after the track's rotation
+    let rotation = file.tracks[track].display_rotation().unwrap_or(0);
+    let (w, h) = info.video.as_ref().map(|v| if rotation % 2 == 1 { (v.height, v.width) } else { (v.width, v.height) }).unwrap_or((0, 0));
    let id = NEXT_ID.with(|n| {
        let id = n.get();
        n.set(id + 1);
@@ -215,7 +217,7 @@ pub fn reader_opener(name: &str, head: &[u8], reader: &SharedReader) -> Option<R
        file,
        track,
        id,
-        config: Config { codec, description, width: w, height: h },
+        config: Config { codec, description, width: w, height: h, rotation },
        state: Mutex::new(Cache::default()),
    })))
 }
@@ -225,6 +227,8 @@ struct Config {
    description: Option<Vec<u8>>,
    width: u32,
    height: u32,
+    /// Clockwise quarter turns from the track matrix, applied to decoded frames.
+    rotation: u8,
 }

 #[derive(Default)]
@@ -455,10 +459,11 @@ impl WcSource {
            std::mem::take(&mut *s.out.borrow_mut())
        });
        for (pts, f) in out {
+            let f = if self.config.rotation != 0 { f.rotated(self.config.rotation) } else { f };
            c.frames.insert(pts, Arc::new(f));
        }
        while c.frames.len() > CACHE_FRAMES {
-            let far = c.frames.keys().copied().max_by_key(|p| (p - want).abs()).expect("non-empty");
+            let Some(far) = c.frames.keys().copied().max_by_key(|p| (p - want).abs()) else { break };
            c.frames.remove(&far);
        }
        // the session's own frame came out: other requests may restart it now
@@ -497,7 +502,8 @@ impl MediaSource for WcSource {
        }
        let t = &self.file.tracks[self.track];
        let n = t.samples.len();
-        let target = req.time.max(Tick::ZERO).to_rational_floor(1, t.timescale.max(1) as i64);
+        // nearest, as `Mp4Source` looks frames up (sample times are rounded to the timescale)
+        let target = req.time.max(Tick::ZERO).to_rational_round(1, t.timescale.max(1) as i64);
        let i = t.sample_at_presentation_time(target).unwrap_or(n - 1).min(n - 1);
        let want = t.samples[i].pts;
        self.collect(&mut c, want);
@@ -6,8 +6,9 @@
 //
 // Steps: load (timing), demo project, play 2 s (frames shown/dropped), import the media through
 // `filmcraft.importUrl`, put it on a new sequence, export H.264 (download), screenshots of each
-// step. `--media` must be reachable from the page (copy it next to index.html). Prints a JSON
-// report; exits non-zero on failure.
+// step; then every mode and a tiny window. `--media` must be reachable from the page (copy it next
+// to index.html). Prints a JSON report; exits non-zero on failure, including any Rust panic or
+// uncaught exception in the console.
 import { spawn } from "node:child_process";
 import { mkdirSync, writeFileSync, readdirSync, statSync, mkdtempSync } from "node:fs";
 import { join } from "node:path";
@@ -148,6 +149,24 @@ try {
  await sleep(1000);
  report.steps.export.downloads = readdirSync(downloads).filter((f) => !f.endsWith(".crdownload")).map((f) => ({ f, bytes: statSync(join(downloads, f)).size }));
  report.steps.export.screenshot = await shot("04-exported");
+
+  // every top-level mode and a tiny window: these used to panic (temp_dir in Export mode, a dock
+  // clamp below 40 points) and freeze the canvas
+  for (const mode of ["import", "export", "edit"]) {
+    await js(`filmcraft.request('ui.set', {mode: ${JSON.stringify(mode)}})`);
+    await sleep(500);
+  }
+  await send("Emulation.setDeviceMetricsOverride", { width: 120, height: 80, deviceScaleFactor: 1, mobile: false });
+  await sleep(500);
+  await send("Emulation.setDeviceMetricsOverride", { width: 1600, height: 1000, deviceScaleFactor: 2, mobile: false });
+  await sleep(500);
+  await send("Emulation.setDeviceMetricsOverride", { width: 1600, height: 1000, deviceScaleFactor: 1, mobile: false });
+  report.steps.modes = { screenshot: await shot("05-modes") };
+  // still alive? (a panicked app never answers)
+  await Promise.race([js("filmcraft.inspect().then(() => true)"), sleep(5000).then(() => { throw new Error("app stopped answering"); })]);
+  const fatal = logs.filter((l) => /panicked at|RuntimeError|EXCEPTION/.test(l));
+  if (fatal.length) throw new Error("panic / uncaught exception:\n" + fatal.join("\n").slice(0, 4000));
+  if (await js("window.filmcraftLoad.fatal || null")) throw new Error("fatal overlay shown");
  report.ok = true;
 } catch (e) {
  report.ok = false;
@@ -16,24 +16,78 @@
    }
    #loading img { width: 56px; height: 56px; }
    #loading .err { color: #ff8a7a; white-space: pre-wrap; max-width: 70ch; pointer-events: auto; }
+    #fatal {
+      position: absolute; inset: 0; display: none; align-items: center; justify-content: center;
+      background: rgba(20, 20, 22, 0.88); color: #e6e6e8; font: 14px/1.45 system-ui, sans-serif; z-index: 10;
+    }
+    #fatal.on { display: flex; }
+    #fatal .box { max-width: min(78ch, calc(100vw - 32px)); padding: 20px 24px; background: #26272b; border-radius: 8px; }
+    #fatal h1 { margin: 0 0 8px; font-size: 17px; color: #ff8a7a; }
+    #fatal pre { max-height: 40vh; overflow: auto; white-space: pre-wrap; font-size: 12px; color: #c9c9cc; }
+    #fatal button { font: inherit; padding: 6px 14px; border: 0; border-radius: 6px; background: #3b6fe0; color: #fff; cursor: pointer; }
  </style>
 </head>
 <body>
  <canvas id="filmcraft_canvas"></canvas>
  <div id="loading"><img src="favicon.png" alt=""><div id="status">Loading FilmCraft…</div></div>
-  <script type="module">
-    import init, { start } from "./filmcraft_web.js";
-    const t0 = performance.now();
+  <div id="fatal" role="alertdialog" aria-labelledby="fatal-title">
+    <div class="box">
+      <h1 id="fatal-title">FilmCraft stopped working</h1>
+      <div>Unsaved changes are kept in the browser every few seconds and come back when you reload.</div>
+      <pre id="fatal-msg"></pre>
+      <button id="fatal-reload" type="button">Reload</button>
+    </div>
+  </div>
+  <script>
+    // A Rust panic (or an out-of-memory abort) inside a frame stops the app for good: eframe logs
+    // "panicked at …" with console.error, then the wasm traps ("RuntimeError: unreachable") and
+    // the canvas freezes or goes blank. Show what happened instead of a dead page.
    window.filmcraftLoad = {};
+    let lastPanic = null;
+    const consoleError = console.error.bind(console);
+    console.error = (...a) => {
+      const m = a.map(String).join(" ");
+      if (/panicked at|memory allocation of/.test(m)) lastPanic = m;
+      consoleError(...a);
+    };
+    window.filmcraftFatal = (what) => {
+      if (window.filmcraftLoad.fatal) return;
+      const msg = lastPanic || String(what && (what.stack || what.message) || what);
+      window.filmcraftLoad.fatal = msg;
+      const el = document.getElementById("fatal");
+      document.getElementById("fatal-msg").textContent = msg.split("\n\nStack:")[0];
+      el.classList.add("on");
+    };
+    document.getElementById("fatal-reload").onclick = () => location.reload();
+    const isFatal = (e) => e instanceof WebAssembly.RuntimeError || /panicked at|unreachable|memory access out of bounds/.test(String(e && e.message || e));
+    // only after start-up: a failed start is shown in #loading below
+    addEventListener("error", (ev) => { if (window.filmcraftLoad.readyMs && isFatal(ev.error || ev.message)) window.filmcraftFatal(ev.error || ev.message); });
+    addEventListener("unhandledrejection", (ev) => { if (window.filmcraftLoad.readyMs && isFatal(ev.reason)) window.filmcraftFatal(ev.reason); });
+  </script>
+  <script type="module">
+    // `__FC_BUILD__` is replaced by `cargo xtask web` with a hash of the build: the glue and the
+    // wasm are cached as immutable, so their URLs must change with every build.
+    const build = "__FC_BUILD__";
+    const v = build.startsWith("__") ? "" : "?v=" + build;
+    const t0 = performance.now();
+    const params = new URLSearchParams(location.search);
    try {
-      await init();
+      const { default: init, start } = await import("./filmcraft_web.js" + v);
+      await init({ module_or_path: new URL("filmcraft_web_bg.wasm" + v, location.href) });
      window.filmcraftLoad.wasmMs = performance.now() - t0;
      await start("filmcraft_canvas");
      window.filmcraftLoad.readyMs = performance.now() - t0;
    } catch (e) {
-      const s = document.getElementById("status");
-      if (s) { s.className = "err"; s.textContent = "FilmCraft failed to start:\n" + (e && e.stack || e); }
+      const text = String(e && e.stack || e);
      window.filmcraftLoad.error = String(e);
+      // WebGPU was found but could not be started: try again on WebGL2 (once)
+      if (!params.has("webgl") && !params.has("cpu") && /wgpu|webgpu|requestDevice|requestAdapter|GPUDevice|surface/i.test(text)) {
+        params.set("webgl", "");
+        location.replace(location.pathname + "?" + params.toString().replace(/=(&|$)/g, "$1") + location.hash);
+      } else {
+        const s = document.getElementById("status");
+        if (s) { s.className = "err"; s.textContent = "FilmCraft failed to start:\n" + text; }
+      }
      throw e;
    }
  </script>
@@ -18,6 +18,7 @@ whisper = ["filmcraft-engine/whisper", "filmcraft-engine/speech-download"]
 [dependencies]
 filmcraft-engine = { workspace = true }
 filmcraft-ui-egui = { workspace = true }
+filmcraft-platform = { workspace = true }
 egui = { workspace = true }
 eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit", "wayland", "x11"] }
 serde_json = { workspace = true }
@@ -0,0 +1,171 @@
+//! The desktop app's command line (`filmcraft --help`).
+
+/// `filmcraft --help`.
+pub const USAGE: &str = "\
+Usage: filmcraft [options] [project.fcproj | media files...]
+
+Options:
+  --control <port>   start the localhost JSON-lines control server
+                     (also: FILMCRAFT_CONTROL_PORT)
+  --demo             open the demo project
+  --empty            start with an empty project
+  --recover          recover the newest unsaved changes without asking
+  --no-recover       start without asking about unsaved changes
+  --data-dir <dir>   folder for auto-save, crash recovery and logs
+                     (also: FILMCRAFT_DATA_DIR)
+  --version          print the version and exit
+  -h, --help         print this help and exit
+";
+
+/// What the command line asks for.
+#[derive(Debug, PartialEq)]
+pub enum Cli {
+    Run(Launch),
+    Help,
+    Version,
+}
+
+/// Options of a normal start.
+#[derive(Debug, PartialEq)]
+pub struct Launch {
+    pub control_port: Option<u16>,
+    /// A project and / or media files to open.
+    pub files: Vec<String>,
+    pub demo: bool,
+    /// `--demo` / `--empty` given: skip Settings ▸ General ▸ At Startup.
+    pub startup_flag: bool,
+    pub recover: Option<bool>,
+    pub data_dir: Option<std::path::PathBuf>,
+}
+
+/// Parse the arguments after the program name. `env_control_port` is the value of
+/// `FILMCRAFT_CONTROL_PORT`, used when `--control` is not given (an empty value counts as unset).
+///
+/// An option we don't know, or one without a usable value, is an error: opening a window for a
+/// mistyped flag helps nobody, and starting without the control server that was asked for leaves
+/// a script waiting for it. That holds for the whole line, so `--version --bogus` is an error
+/// too, and for a port from the environment exactly as for one from `--control`.
+pub fn parse(env_control_port: Option<String>, args: impl IntoIterator<Item = String>) -> Result<Cli, String> {
+    let mut l = Launch { control_port: None, files: Vec::new(), demo: true, startup_flag: false, recover: None, data_dir: None };
+    let (mut help, mut version) = (false, false);
+    let mut args = args.into_iter();
+    while let Some(a) = args.next() {
+        match a.as_str() {
+            "-h" | "--help" => help = true,
+            "--version" => version = true,
+            "--control" => {
+                let port = args.next().ok_or("--control needs a port number")?;
+                l.control_port = Some(port.parse().map_err(|_| format!("--control needs a port number, got `{port}`"))?);
+            }
+            "--demo" => (l.demo, l.startup_flag) = (true, true),
+            "--empty" => (l.demo, l.startup_flag) = (false, true),
+            "--recover" => l.recover = Some(true),
+            "--no-recover" => l.recover = Some(false),
+            "--data-dir" => l.data_dir = Some(args.next().map(std::path::PathBuf::from).ok_or("--data-dir needs a folder")?),
+            // everything after `--` is a file, whatever it looks like
+            "--" => l.files.extend(args.by_ref()),
+            // macOS adds a process serial number when it launches an app bundle
+            _ if a.starts_with("-psn_") => {}
+            _ if a.len() > 1 && a.starts_with('-') => return Err(format!("unknown option `{a}`")),
+            _ => l.files.push(a),
+        }
+    }
+    if help {
+        return Ok(Cli::Help);
+    }
+    if version {
+        return Ok(Cli::Version);
+    }
+    if l.control_port.is_none()
+        && let Some(port) = env_control_port.as_deref().map(str::trim).filter(|p| !p.is_empty())
+    {
+        l.control_port = Some(port.parse().map_err(|_| format!("FILMCRAFT_CONTROL_PORT needs a port number, got `{port}`"))?);
+    }
+    Ok(Cli::Run(l))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn parse_env(env: Option<&str>, args: &[&str]) -> Result<Cli, String> {
+        parse(env.map(str::to_string), args.iter().map(|a| a.to_string()))
+    }
+
+    fn parse_args(args: &[&str]) -> Result<Cli, String> {
+        parse_env(None, args)
+    }
+
+    fn launch(args: &[&str]) -> Launch {
+        match parse_args(args) {
+            Ok(Cli::Run(l)) => l,
+            other => panic!("{args:?} should start the app, got {other:?}"),
+        }
+    }
+
+    /// `filmcraft --help` used to open the app with "--help" as a media file to import.
+    #[test]
+    fn help_and_version_do_not_start_the_app() {
+        assert_eq!(parse_args(&["--help"]), Ok(Cli::Help));
+        assert_eq!(parse_args(&["-h"]), Ok(Cli::Help));
+        assert_eq!(parse_args(&["--empty", "--help"]), Ok(Cli::Help));
+        assert_eq!(parse_args(&["--version"]), Ok(Cli::Version));
+        assert_eq!(parse_args(&["--version", "--help"]), Ok(Cli::Help));
+        assert_eq!(parse_args(&["a.mp4", "--version"]), Ok(Cli::Version));
+        for flag in ["--control", "--demo", "--empty", "--recover", "--no-recover", "--data-dir", "--version", "--help"] {
+            assert!(USAGE.contains(flag), "usage lists {flag}");
+        }
+    }
+
+    #[test]
+    fn unknown_options_are_errors() {
+        assert_eq!(parse_args(&["--frobnicate"]), Err("unknown option `--frobnicate`".to_string()));
+        assert!(parse_args(&["a.mp4", "-x"]).is_err());
+        assert!(parse_args(&["--Help"]).is_err());
+        assert!(parse_args(&["--control"]).is_err(), "missing port");
+        assert!(parse_args(&["--control", "abc"]).unwrap_err().contains("abc"));
+        assert!(parse_args(&["--control", "70000"]).is_err(), "not a port");
+        assert!(parse_args(&["--data-dir"]).is_err(), "missing folder");
+        // the whole line is checked, whatever comes first
+        assert_eq!(parse_args(&["--version", "--bogus"]), Err("unknown option `--bogus`".to_string()));
+        assert_eq!(parse_args(&["--bogus", "--version"]), Err("unknown option `--bogus`".to_string()));
+        assert_eq!(parse_args(&["--help", "--bogus"]), Err("unknown option `--bogus`".to_string()));
+        assert!(parse_args(&["--help", "--control"]).is_err());
+    }
+
+    /// A bad `FILMCRAFT_CONTROL_PORT` used to start the app without the control server, silently.
+    #[test]
+    fn a_bad_port_in_the_environment_is_an_error_like_a_bad_control_flag() {
+        for bad in ["abc", "70000", "-1", "98 76", "9876x", "\u{fffd}"] {
+            let e = parse_env(Some(bad), &[]).unwrap_err();
+            assert!(e.contains("FILMCRAFT_CONTROL_PORT") && e.contains(bad), "{bad}: {e}");
+            assert!(parse_env(Some(bad), &["--empty", "a.mp4"]).is_err(), "{bad}");
+            // the flag wins, so the environment's value is not looked at; nor for --help / --version
+            assert_eq!(parse_env(Some(bad), &["--control", "9"]).map(|c| matches!(c, Cli::Run(l) if l.control_port == Some(9))), Ok(true), "{bad}");
+            assert_eq!(parse_env(Some(bad), &["--help"]), Ok(Cli::Help));
+            assert_eq!(parse_env(Some(bad), &["--version"]), Ok(Cli::Version));
+        }
+        // unset or empty: no control server
+        assert_eq!(launch(&[]).control_port, None);
+        assert_eq!(parse_env(Some(""), &[]), Ok(Cli::Run(launch(&[]))));
+        assert_eq!(parse_env(Some("  "), &[]), Ok(Cli::Run(launch(&[]))));
+        // a good one is the default
+        assert_eq!(parse_env(Some("1234"), &[]), Ok(Cli::Run(Launch { control_port: Some(1234), ..launch(&[]) })));
+        assert_eq!(parse_env(Some("1234"), &["--control", "9"]).map(|c| matches!(c, Cli::Run(l) if l.control_port == Some(9))), Ok(true));
+    }
+
+    #[test]
+    fn known_options_and_files_parse_as_before() {
+        let none = launch(&[]);
+        assert_eq!(none, Launch { control_port: None, files: vec![], demo: true, startup_flag: false, recover: None, data_dir: None });
+        let l = launch(&["--control", "9876", "--empty", "--no-recover", "--data-dir", "/tmp/fc", "cut.fcproj", "a.mp4"]);
+        assert_eq!(l.control_port, Some(9876));
+        assert_eq!((l.demo, l.startup_flag, l.recover), (false, true, Some(false)));
+        assert_eq!(l.data_dir, Some(std::path::PathBuf::from("/tmp/fc")));
+        assert_eq!(l.files, ["cut.fcproj", "a.mp4"]);
+        assert_eq!((launch(&["--demo"]).demo, launch(&["--demo"]).startup_flag, launch(&["--recover"]).recover), (true, true, Some(true)));
+        // `--` ends the options; a lone `-` and macOS' process serial number are not options
+        assert_eq!(launch(&["--", "--odd name.mov", "-h"]).files, ["--odd name.mov", "-h"]);
+        assert_eq!(launch(&["-", "-psn_0_12345"]).files, ["-"]);
+    }
+}
@@ -12,6 +12,7 @@ pub struct CpalOut {
    stream: Option<cpal::Stream>,
    played: Arc<AtomicU64>,
    rate: u32,
+    channels: u16,
    hw: AudioHardwarePrefs,
    /// Sequence sample rate for "Attempt to force hardware to document sample rate".
    document_rate: Option<u32>,
@@ -44,7 +45,14 @@ impl CpalOut {
        let host = cpal::default_host();
        let dev = host.default_output_device()?;
        let cfg = dev.default_output_config().ok()?;
-        Some(Self { stream: None, played: Arc::new(AtomicU64::new(0)), rate: cfg.sample_rate().0, hw: AudioHardwarePrefs::default(), document_rate: None })
+        Some(Self {
+            stream: None,
+            played: Arc::new(AtomicU64::new(0)),
+            rate: cfg.sample_rate().0,
+            channels: cfg.channels(),
+            hw: AudioHardwarePrefs::default(),
+            document_rate: None,
+        })
    }

    /// The stream configuration the settings ask for, falling back to the device default.
@@ -77,6 +85,7 @@ impl AudioOut for CpalOut {
            config.buffer_size = cpal::BufferSize::Fixed(self.hw.buffer_size);
        }
        self.rate = cfg.sample_rate().0;
+        self.channels = cfg.channels();
        self.played.store(0, Ordering::SeqCst);
        let played = self.played.clone();
        let err = |e| eprintln!("filmcraft: audio stream error: {e}");
@@ -103,6 +112,9 @@ impl AudioOut for CpalOut {
    fn sample_rate(&self) -> u32 {
        self.rate
    }
+    fn channels(&self) -> usize {
+        self.channels as usize
+    }
    fn played_frames(&self) -> Option<u64> {
        self.stream.as_ref().map(|_| self.played.load(Ordering::SeqCst))
    }
@@ -122,6 +134,7 @@ impl AudioOut for CpalOut {
            && let Ok(cfg) = self.config(&dev)
        {
            self.rate = cfg.sample_rate().0;
+            self.channels = cfg.channels();
        }
    }
 }
@@ -1,13 +1,27 @@
 //! Localhost JSON-lines control server (one request per line, one reply per line). Loopback only.
+//!
+//! The server only ever reads requests: a line that is not a JSON object with a string `method`
+//! (an HTTP request line from a browser's cross-origin `fetch`, a stray `nc`, binary junk) gets
+//! one error reply and the connection is closed, so nothing after it is executed. Lines are
+//! bounded ([`MAX_LINE`]) and so is the number of open connections ([`MAX_CONNECTIONS`]); junk
+//! never reaches the UI thread. See `docs/control-protocol.md`.

-use std::io::{BufRead, BufReader, Write};
+use std::io::{BufRead, BufReader, Read, Write};
 use std::net::{TcpListener, TcpStream};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::mpsc::{Receiver, Sender, channel};
 use std::time::Duration;

 use filmcraft_ui_egui::ControlRequest;
 use serde_json::{Value, json};

+/// Longest accepted request line (bytes, without the newline). Requests are small JSON objects;
+/// anything longer is refused and the connection closed.
+pub const MAX_LINE: usize = 4 * 1024 * 1024;
+/// Connections served at once; further ones get an error line and are closed.
+pub const MAX_CONNECTIONS: usize = 16;
+
 pub fn start(port: u16, ctx: egui::Context) -> Receiver<ControlRequest> {
    let (tx, rx) = channel::<ControlRequest>();
    let listener = match TcpListener::bind(("127.0.0.1", port)) {
@@ -18,44 +32,257 @@ pub fn start(port: u16, ctx: egui::Context) -> Receiver<ControlRequest> {
        }
    };
    eprintln!("filmcraft: control server listening on 127.0.0.1:{port}");
-    std::thread::spawn(move || {
-        for stream in listener.incoming().flatten() {
-            let tx = tx.clone();
-            let ctx = ctx.clone();
-            std::thread::spawn(move || serve(stream, tx, ctx));
-        }
-    });
+    std::thread::spawn(move || accept_loop(listener, tx, ctx));
    rx
 }

-fn serve(stream: TcpStream, tx: Sender<ControlRequest>, ctx: egui::Context) {
-    let Ok(read) = stream.try_clone() else { return };
-    let mut out = stream;
-    for line in BufReader::new(read).lines() {
-        let Ok(line) = line else { break };
-        if line.trim().is_empty() {
+fn accept_loop(listener: TcpListener, tx: Sender<ControlRequest>, ctx: egui::Context) {
+    let open = Arc::new(AtomicUsize::new(0));
+    for mut stream in listener.incoming().flatten() {
+        if open.fetch_add(1, Ordering::SeqCst) >= MAX_CONNECTIONS {
+            open.fetch_sub(1, Ordering::SeqCst);
+            let _ = writeln!(stream, "{}", json!({"ok": false, "error": "too many control connections"}));
            continue;
        }
-        let reply = match serde_json::from_str::<Value>(&line) {
-            Ok(msg) => {
-                let id = msg.get("id").cloned().unwrap_or(Value::Null);
-                let method = msg.get("method").and_then(Value::as_str).unwrap_or("").to_string();
-                let params = msg.get("params").cloned().unwrap_or(json!({}));
-                let (req, rrx) = ControlRequest::new(method, params);
-                if tx.send(req).is_err() {
-                    break;
-                }
-                ctx.request_repaint();
-                let mut r = rrx.recv_timeout(Duration::from_secs(60)).unwrap_or_else(|_| json!({"ok": false, "error": "timeout"}));
-                if let Some(o) = r.as_object_mut() {
-                    o.insert("id".into(), id);
-                }
-                r
-            }
-            Err(e) => json!({"ok": false, "error": format!("bad JSON: {e}")}),
-        };
-        if writeln!(out, "{reply}").is_err() {
-            break;
+        let tx = tx.clone();
+        let ctx = ctx.clone();
+        // The slot is given back when the guard drops: after `serve` returns, if it panics, or if
+        // the thread can't be started (the closure, and with it the guard, is dropped).
+        let slot = Slot(Arc::clone(&open));
+        let spawned = std::thread::Builder::new().name("control-conn".into()).spawn(move || {
+            let _slot = slot;
+            serve(stream, &tx, &ctx);
+        });
+        if let Err(e) = spawned {
+            eprintln!("filmcraft: control server could not start a connection thread: {e}");
        }
    }
 }
+
+/// One counted connection; decrements the open-connection count when dropped.
+struct Slot(Arc<AtomicUsize>);
+
+impl Drop for Slot {
+    fn drop(&mut self) {
+        self.0.fetch_sub(1, Ordering::SeqCst);
+    }
+}
+
+fn serve(stream: TcpStream, tx: &Sender<ControlRequest>, ctx: &egui::Context) {
+    let Ok(read) = stream.try_clone() else { return };
+    serve_lines(read, stream, |method, params| {
+        let (req, rrx) = ControlRequest::new(method, params);
+        tx.send(req).ok()?;
+        ctx.request_repaint();
+        Some(rrx.recv_timeout(Duration::from_secs(60)).unwrap_or_else(|_| json!({"ok": false, "error": "timeout"})))
+    });
+}
+
+/// One parsed line.
+enum Line {
+    Request {
+        id: Value,
+        method: String,
+        params: Value,
+    },
+    Blank,
+    /// Not a request: reply with this error and close the connection.
+    Reject(String),
+}
+
+fn parse_line(bytes: &[u8]) -> Line {
+    let Ok(text) = std::str::from_utf8(bytes) else {
+        return Line::Reject("not a control request (invalid UTF-8); closing the connection".into());
+    };
+    let text = text.trim();
+    if text.is_empty() {
+        return Line::Blank;
+    }
+    let msg = match serde_json::from_str::<Value>(text) {
+        Ok(v) => v,
+        Err(e) => return Line::Reject(format!("bad JSON ({e}); expected one JSON request object per line; closing the connection")),
+    };
+    let Some(obj) = msg.as_object() else {
+        return Line::Reject("not a control request (expected a JSON object); closing the connection".into());
+    };
+    let Some(method) = obj.get("method").and_then(Value::as_str) else {
+        return Line::Reject("not a control request (missing string `method`); closing the connection".into());
+    };
+    Line::Request { id: obj.get("id").cloned().unwrap_or(Value::Null), method: method.to_string(), params: obj.get("params").cloned().unwrap_or(json!({})) }
+}
+
+/// Read one `\n`-terminated line of at most `max` bytes into `buf` (newline stripped).
+/// `Ok(false)` at end of stream; `Err` when the line is too long or the read fails.
+fn read_bounded_line(reader: &mut impl BufRead, buf: &mut Vec<u8>, max: usize) -> Result<bool, String> {
+    buf.clear();
+    // `take` bounds the bytes buffered for one line: a peer can't make us allocate more than `max`.
+    let limit = u64::try_from(max).unwrap_or(u64::MAX).saturating_add(1);
+    let n = reader.take(limit).read_until(b'\n', buf).map_err(|e| e.to_string())?;
+    if n == 0 {
+        return Ok(false);
+    }
+    if buf.last() == Some(&b'\n') {
+        buf.pop();
+        if buf.last() == Some(&b'\r') {
+            buf.pop();
+        }
+        return Ok(true);
+    }
+    if buf.len() > max {
+        return Err(format!("request line longer than {max} bytes; closing the connection"));
+    }
+    // Last line without a newline, then end of stream.
+    Ok(true)
+}
+
+/// Serve requests from `read`, answering on `out`, until the peer closes, sends something that is
+/// not a request, or `handle` returns `None` (app gone). `handle` gets `(method, params)` and
+/// returns the reply object (the request's `id` is added here).
+fn serve_lines<R: Read, W: Write>(read: R, mut out: W, mut handle: impl FnMut(String, Value) -> Option<Value>) {
+    let mut reader = BufReader::new(read);
+    let mut buf = Vec::new();
+    loop {
+        let reject = match read_bounded_line(&mut reader, &mut buf, MAX_LINE) {
+            Ok(false) => return,
+            Err(e) => e,
+            Ok(true) => match parse_line(&buf) {
+                Line::Blank => continue,
+                Line::Reject(e) => e,
+                Line::Request { id, method, params } => {
+                    let Some(mut r) = handle(method, params) else { return };
+                    if let Some(o) = r.as_object_mut() {
+                        o.insert("id".into(), id);
+                    }
+                    if writeln!(out, "{r}").and_then(|()| out.flush()).is_err() {
+                        return;
+                    }
+                    continue;
+                }
+            },
+        };
+        let _ = writeln!(out, "{}", json!({"ok": false, "error": reject})).and_then(|()| out.flush());
+        return;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn run(input: &[u8]) -> (Vec<Value>, Vec<String>) {
+        let mut out = Vec::new();
+        let mut calls = Vec::new();
+        serve_lines(input, &mut out, |m, _p| {
+            calls.push(m);
+            Some(json!({"ok": true, "result": null}))
+        });
+        let replies = String::from_utf8(out).unwrap().lines().map(|l| serde_json::from_str::<Value>(l).unwrap()).collect();
+        (replies, calls)
+    }
+
+    #[test]
+    fn requests_are_answered_in_order_with_ids() {
+        let (r, calls) = run(b"{\"id\":1,\"method\":\"a\"}\n\n{\"id\":2,\"method\":\"b\",\"params\":{}}\r\n{\"method\":\"c\"}");
+        assert_eq!(calls, ["a", "b", "c"]);
+        assert_eq!(r.len(), 3);
+        assert_eq!(r[0]["id"], 1);
+        assert_eq!(r[1]["id"], 2);
+        assert_eq!(r[2]["id"], Value::Null);
+    }
+
+    #[test]
+    fn http_request_closes_before_the_body_runs() {
+        // A browser's cross-origin `fetch` POST (issue #119): the request line is rejected and the
+        // connection closed, so the JSON body is never executed.
+        let http = b"POST / HTTP/1.1\r\nHost: 127.0.0.1:9876\r\nOrigin: https://attacker.example\r\nContent-Type: text/plain\r\n\r\n\
+            {\"id\":7,\"method\":\"engine.execute\",\"params\":{\"command\":\"file.openDemoProject\",\"params\":{}}}\n";
+        let (r, calls) = run(http);
+        assert!(calls.is_empty(), "nothing may run: {calls:?}");
+        assert_eq!(r.len(), 1);
+        assert_eq!(r[0]["ok"], false);
+        assert!(r[0]["error"].as_str().unwrap().contains("closing the connection"));
+    }
+
+    #[test]
+    fn non_request_json_closes_the_connection() {
+        for junk in [
+            &b"[1,2]\n{\"method\":\"a\"}\n"[..],
+            b"{\"id\":1}\n{\"method\":\"a\"}\n",
+            b"{\"method\":5}\n{\"method\":\"a\"}\n",
+            b"\xff\xfe\n{\"method\":\"a\"}\n",
+        ] {
+            let (r, calls) = run(junk);
+            assert!(calls.is_empty(), "{calls:?}");
+            assert_eq!(r.len(), 1);
+            assert_eq!(r[0]["ok"], false);
+        }
+    }
+
+    #[test]
+    fn a_request_before_junk_still_runs() {
+        let (r, calls) = run(b"{\"method\":\"a\"}\nGET / HTTP/1.1\n{\"method\":\"b\"}\n");
+        assert_eq!(calls, ["a"]);
+        assert_eq!(r.len(), 2);
+        assert_eq!(r[1]["ok"], false);
+    }
+
+    #[test]
+    fn overlong_line_is_refused() {
+        // One byte over the limit, then a valid request: neither runs.
+        let mut input = vec![b'x'; MAX_LINE + 1];
+        input.extend_from_slice(b"\n{\"method\":\"a\"}\n");
+        let (r, calls) = run(&input);
+        assert!(calls.is_empty(), "{calls:?}");
+        assert_eq!(r.len(), 1);
+        assert!(r[0]["error"].as_str().unwrap().contains("longer than"));
+    }
+
+    #[test]
+    fn line_at_the_limit_is_accepted() {
+        let mut buf = Vec::new();
+        let line = vec![b'a'; 10];
+        let mut input = line.clone();
+        input.push(b'\n');
+        assert_eq!(read_bounded_line(&mut &input[..], &mut buf, 10), Ok(true));
+        assert_eq!(buf, line);
+        assert!(read_bounded_line(&mut &[b'a'; 11][..], &mut buf, 10).is_err());
+    }
+
+    #[test]
+    fn tcp_connection_is_closed_after_junk() {
+        // End to end over a real loopback socket (the transport the app uses).
+        let listener = TcpListener::bind(("127.0.0.1", 0)).unwrap();
+        let addr = listener.local_addr().unwrap();
+        let server = std::thread::spawn(move || {
+            let (s, _) = listener.accept().unwrap();
+            let read = s.try_clone().unwrap();
+            serve_lines(read, s, |_, _| Some(json!({"ok": true})));
+        });
+        let mut c = TcpStream::connect(addr).unwrap();
+        c.set_read_timeout(Some(Duration::from_secs(5))).unwrap();
+        c.write_all(b"{\"id\":7,\"method\":\"x\"}\nhello\n{\"method\":\"y\"}\n").unwrap();
+        let mut text = String::new();
+        c.read_to_string(&mut text).unwrap(); // returns at EOF: the server closed the connection
+        server.join().unwrap();
+        let lines: Vec<&str> = text.lines().collect();
+        assert_eq!(lines.len(), 2, "{text}");
+        assert!(lines[0].contains("\"id\":7"));
+        assert!(lines[1].contains("closing the connection"));
+    }
+
+    #[test]
+    fn extra_connections_are_refused() {
+        let listener = TcpListener::bind(("127.0.0.1", 0)).unwrap();
+        let addr = listener.local_addr().unwrap();
+        let (tx, _rx) = channel::<ControlRequest>();
+        std::thread::spawn(move || accept_loop(listener, tx, egui::Context::default()));
+        // Idle connections are accepted in order and held open.
+        let held: Vec<TcpStream> = (0..16).map(|_| TcpStream::connect(addr).unwrap()).collect();
+        let mut extra = TcpStream::connect(addr).unwrap();
+        extra.set_read_timeout(Some(Duration::from_secs(5))).unwrap();
+        let mut line = String::new();
+        BufReader::new(&mut extra).read_line(&mut line).unwrap();
+        assert!(line.contains("too many control connections"), "{line}");
+        drop(held);
+    }
+}
@@ -1,21 +1,26 @@
 //! FilmCraft desktop app.
 //!
 //! Usage: `filmcraft [--control <port>] [--demo|--empty] [--recover|--no-recover] [--data-dir <dir>]
-//! [project.fcproj | media files…]`
+//! [project.fcproj | media files…]`; `--help` prints the options, `--version` the version. An
+//! unknown option is an error (exit code 2), not a file to open.
 //!
 //! Without a project, `--demo` or `--empty`, Settings ▸ General ▸ At Startup decides: Show Home
 //! (the demo project), Open Most Recent, or an empty project.
 //!
 //! `--control <port>` (or `FILMCRAFT_CONTROL_PORT`) starts a localhost JSON-lines control server;
-//! see `filmcraft_ui_egui::control` for the methods.
+//! see `filmcraft_ui_egui::control` for the methods. A port that is not a number is an error from
+//! either source.
 //!
 //! Auto-save and the crash-recovery journal run in every session (data in `--data-dir`, else
 //! `FILMCRAFT_DATA_DIR`, else the per-user application data folder). If a previous session died
 //! with unsaved changes the app asks to recover them; `--recover` recovers the newest without
 //! asking, `--no-recover` starts without asking (the changes stay available via File ▸ Recover
 //! Unsaved Changes…).
+#![cfg_attr(all(target_os = "windows", not(debug_assertions)), windows_subsystem = "windows")]
+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]

 mod app_nap;
+mod args;
 mod audio;
 mod audio_in;
 mod control_server;
@@ -23,6 +28,7 @@ mod control_server;
 mod native_menu;
 mod window_raise;

+use args::{Cli, Launch};
 use chrono::TimeZone;
 use filmcraft_engine::Session;
 use filmcraft_engine::autosave::{AutosaveConfig, default_data_dir};
@@ -43,31 +49,47 @@ fn app_icon() -> egui::IconData {
    eframe::icon_data::from_png_bytes(png).unwrap_or_default()
 }

-fn main() -> eframe::Result {
-    app_nap::disable();
-    let mut control_port: Option<u16> = std::env::var("FILMCRAFT_CONTROL_PORT").ok().and_then(|p| p.parse().ok());
-    let mut files = Vec::new();
-    let mut demo = true;
-    // --demo / --empty given: skip Settings ▸ General ▸ At Startup
-    let mut startup_flag = false;
-    let mut recover: Option<bool> = None;
-    let mut data_dir = None;
-    let mut args = std::env::args().skip(1);
-    while let Some(a) = args.next() {
-        match a.as_str() {
-            "--control" => control_port = args.next().and_then(|p| p.parse().ok()),
-            "--demo" => (demo, startup_flag) = (true, true),
-            "--empty" => (demo, startup_flag) = (false, true),
-            "--recover" => recover = Some(true),
-            "--no-recover" => recover = Some(false),
-            "--data-dir" => data_dir = args.next().map(std::path::PathBuf::from),
-            "--version" => {
-                println!("filmcraft {}", env!("CARGO_PKG_VERSION"));
-                return Ok(());
-            }
-            _ => files.push(a),
-        }
+/// Print `text` (stdout, or stderr for an error). A Windows release build has no console
+/// (`windows_subsystem = "windows"`), so there it is also shown in a message box: otherwise `--help`
+/// would print nothing and a bad option would quit without a word.
+fn tell(text: &str, error: bool) {
+    if error {
+        eprint!("{text}");
+    } else {
+        print!("{text}");
    }
+    #[cfg(all(target_os = "windows", not(debug_assertions)))]
+    {
+        let level = if error { rfd::MessageLevel::Error } else { rfd::MessageLevel::Info };
+        let _ = rfd::MessageDialog::new().set_level(level).set_title("FilmCraft").set_description(text).show();
+    }
+}
+
+fn main() -> eframe::Result {
+    // lossy, so a value that is not Unicode is reported like any other bad port instead of ignored
+    let env_port = std::env::var_os("FILMCRAFT_CONTROL_PORT").map(|p| p.to_string_lossy().into_owned());
+    let Launch { control_port, files, demo, startup_flag, recover, data_dir } = match args::parse(env_port, std::env::args().skip(1)) {
+        Ok(Cli::Run(l)) => l,
+        Ok(Cli::Help) => {
+            tell(args::USAGE, false);
+            return Ok(());
+        }
+        Ok(Cli::Version) => {
+            tell(&format!("filmcraft {}\n", env!("CARGO_PKG_VERSION")), false);
+            return Ok(());
+        }
+        Err(e) => {
+            tell(&format!("filmcraft: {e}\n\n{}", args::USAGE), true);
+            std::process::exit(2);
+        }
+    };
+    app_nap::disable();
+    // Panics anywhere go to <data dir>/Logs/crash-<day>.log with a backtrace; the UI pass and
+    // frame workers catch them and keep running (see filmcraft_ui_egui::crash).
+    filmcraft_ui_egui::crash::install(data_dir.clone().or_else(default_data_dir).map(|d| d.join("Logs")));
+    // OS hardware video decoders (VideoToolbox on macOS) in front of our own; Settings ▸ Playback ▸
+    // Hardware decoding switches them off. Unsupported streams and failures use our decoders.
+    register_hardware_decoders();
    let options = eframe::NativeOptions {
        viewport: egui::ViewportBuilder::default()
            .with_title("FilmCraft")
@@ -85,7 +107,7 @@ fn main() -> eframe::Result {
        event_loop_builder: agent_event_loop(control_port.is_some()),
        ..Default::default()
    };
-    eframe::run_native(
+    let started = eframe::run_native(
        "FilmCraft",
        options,
        Box::new(move |cc| {
@@ -178,7 +200,16 @@ fn main() -> eframe::Result {
            }
            Ok(Box::new(app))
        }),
-    )
+    );
+    // The window could not be created (no usable GPU / graphics driver, no display): say so
+    // instead of exiting silently, and keep the reason in the crash log.
+    if let Err(e) = &started {
+        let msg = format!("FilmCraft could not start its window: {e}\n\nUpdating the graphics driver usually fixes this.");
+        eprintln!("filmcraft: {msg}");
+        filmcraft_ui_egui::crash::record(&msg);
+        let _ = rfd::MessageDialog::new().set_title("FilmCraft").set_description(&msg).set_level(rfd::MessageLevel::Error).show();
+    }
+    started
 }

 /// Open a file in its default application, or reveal it in the file manager (Edit Original,
@@ -208,6 +239,15 @@ fn open_path(path: &str, reveal: bool) -> Result<(), String> {
    cmd.spawn().map(|_| ()).map_err(|e| format!("can't open {path}: {e}"))
 }

+/// Put the OS hardware video decoders in front of our own. Registered in a statement of its own:
+/// a log macro does not evaluate its arguments while no logger takes its level, which left the
+/// hardware decoders out of every run.
+fn register_hardware_decoders() -> filmcraft_platform::Availability {
+    let hardware = filmcraft_platform::register();
+    log::info!("hardware decoding: {hardware:?}");
+    hardware
+}
+
 /// Local UTC offset at a unix time (auto-save file names and recovery times use local time).
 fn local_offset(unix: i64) -> i32 {
    chrono::Local.timestamp_opt(unix, 0).single().map(|d| d.offset().local_minus_utc()).unwrap_or(0)
@@ -226,3 +266,15 @@ fn agent_event_loop(agent: bool) -> Option<eframe::EventLoopBuilderHook> {
    let _ = agent;
    None
 }
+
+#[cfg(test)]
+mod tests {
+    /// Start-up registers the hardware decoders whether or not anything is logged (no logger is
+    /// installed here, as in a normal run).
+    #[test]
+    fn startup_registers_the_hardware_decoders_without_a_logger() {
+        assert!(!log::log_enabled!(log::Level::Info));
+        let hardware = super::register_hardware_decoders();
+        assert_eq!(filmcraft_platform::registered(), cfg!(any(target_os = "macos", target_os = "windows")), "{hardware:?}");
+    }
+}
@@ -25,10 +25,12 @@ pub type ShortcutUpdater = Box<dyn FnMut(&[Item])>;
 pub fn install(app: &FilmcraftApp, ctx: egui::Context) -> (Receiver<String>, ShortcutUpdater) {
    let items = menu_items(app);
    let mut native: Vec<(String, MenuItem)> = Vec::new();
+    let mut titles: Vec<(String, Submenu)> = Vec::new();
    let bar = Menu::new();
    let app_menu = Submenu::new("FilmCraft", true);
    // FilmCraft ▸ Settings ▸ <category> (Premiere's app-menu layout; General is Cmd+,)
-    let settings = Submenu::new("Settings", true);
+    let settings = Submenu::new(app.ui.language.tr("Settings"), true);
+    titles.push(("Settings".into(), settings.clone()));
    for it in items.iter().filter(|i| i.id.starts_with("app.settings.")) {
        let label = it.label.trim_end_matches('…').to_string();
        let mi = MenuItem::with_id(it.id.clone(), label, true, it.shortcut.as_deref().and_then(accel));
@@ -48,7 +50,8 @@ pub fn install(app: &FilmcraftApp, ctx: egui::Context) -> (Receiver<String>, Sho
    ]);
    let _ = bar.append(&app_menu);
    for top in MENUS {
-        let sub = Submenu::new(top, true);
+        let sub = Submenu::new(app.ui.language.tr(top), true);
+        titles.push((top.into(), sub.clone()));
        let mine: Vec<&Item> = items.iter().filter(|i| i.path.first().map(String::as_str) == Some(top) && !i.id.starts_with("app.settings.")).collect();
        // submenus by path prefix (e.g. Clip ▸ Video Options ▸ Time Interpolation), created where
        // their first item appears
@@ -62,7 +65,8 @@ pub fn install(app: &FilmcraftApp, ctx: egui::Context) -> (Receiver<String>, Sho
                parent = match subs.iter().find(|(k, _)| *k == key) {
                    Some((_, s)) => s.clone(),
                    None => {
-                        let s = Submenu::new(&it.path[depth], true);
+                        let s = Submenu::new(app.ui.language.tr(&it.path[depth]), true);
+                        titles.push((it.path[depth].clone(), s.clone()));
                        let _ = parent.append(&s);
                        subs.push((key, s.clone()));
                        s
@@ -88,8 +92,22 @@ pub fn install(app: &FilmcraftApp, ctx: egui::Context) -> (Receiver<String>, Sho
        }
    });
    let update: ShortcutUpdater = Box::new(move |items: &[Item]| {
+        let checked = |id: &str| items.iter().any(|it| it.id == id && it.checked == Some(true));
+        let language = if checked("app.language.japanese") {
+            filmcraft_ui_egui::i18n::Language::Ja
+        } else if checked("app.language.spanish") {
+            filmcraft_ui_egui::i18n::Language::Es
+        } else if checked("app.language.portuguese") {
+            filmcraft_ui_egui::i18n::Language::PtBr
+        } else {
+            filmcraft_ui_egui::i18n::Language::En
+        };
+        for (title, submenu) in &titles {
+            submenu.set_text(language.tr(title));
+        }
        for (id, mi) in &native {
            if let Some(it) = items.iter().find(|i| &i.id == id) {
+                mi.set_text(&it.label);
                let _ = mi.set_accelerator(it.shortcut.as_deref().and_then(accel));
            }
        }
@@ -0,0 +1,4 @@
+allow-unwrap-in-tests = true
+allow-expect-in-tests = true
+allow-panic-in-tests = true
+allow-indexing-slicing-in-tests = true
@@ -19,6 +19,10 @@ const ID_PCE: u32 = 5;
 const ID_FIL: u32 = 6;
 const ID_END: u32 = 7;

+/// `extension_type` of a fill element carrying SBR data (ISO/IEC 14496-3 §4.5.2.8.2, Table 4.121).
+const EXT_SBR_DATA: u32 = 13;
+const EXT_SBR_DATA_CRC: u32 = 14;
+
 /// One decoded `individual_channel_stream` before stereo processing and synthesis.
 struct Ics {
    info: IcsInfo,
@@ -45,6 +49,8 @@ pub struct Decoder {
    offsets: Vec<usize>,
    channels: Vec<ChannelState>,
    noise_state: u32,
+    /// A fill element carried SBR data (implicitly signalled HE-AAC).
+    sbr_seen: bool,
 }

 impl Decoder {
@@ -67,7 +73,7 @@ impl Decoder {
        if layout.is_empty() && asc.channel_config != 0 {
            return Err(Error::InvalidConfig("unsupported channel configuration"));
        }
-        let mut d = Decoder { asc, layout: Vec::new(), offsets: Vec::new(), channels: Vec::new(), noise_state: 0x2545_F491 };
+        let mut d = Decoder { asc, layout: Vec::new(), offsets: Vec::new(), channels: Vec::new(), noise_state: 0x2545_F491, sbr_seen: false };
        d.set_layout(layout);
        Ok(d)
    }
@@ -90,6 +96,12 @@ impl Decoder {
    pub fn sample_rate(&self) -> u32 {
        self.asc.sample_rate
    }
+    /// Whether the stream is HE-AAC: SBR signalled in the `AudioSpecificConfig` (explicit) or SBR
+    /// data seen in a fill element of a decoded access unit (implicit). Only the AAC-LC core is
+    /// decoded, at [`Self::sample_rate`]; the SBR high band is not reconstructed.
+    pub fn sbr(&self) -> bool {
+        self.asc.sbr || self.sbr_seen
+    }
    pub fn channels(&self) -> usize {
        self.channels.len()
    }
@@ -174,7 +186,11 @@ impl Decoder {
                        count += br.read_bits(8)? as usize;
                        count -= 1;
                    }
-                    br.skip(count * 8)?;
+                    if count > 0 {
+                        let ext = br.read_bits(4)?;
+                        self.sbr_seen |= matches!(ext, EXT_SBR_DATA | EXT_SBR_DATA_CRC);
+                        br.skip(count * 8 - 4)?;
+                    }
                }
                _ => break, // ID_END
            }
@@ -542,3 +558,27 @@ fn synth(state: &mut ChannelState, info: &IcsInfo, spec: &[f32]) -> Vec<f32> {
    state.prev_shape = cur;
    out
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Implicitly signalled HE-AAC (an AAC-LC config) is recognised from the SBR fill element.
+    #[test]
+    fn sbr_fill_element_marks_implicit_he_aac() {
+        // AAC-LC, 22.05 kHz, stereo
+        let mut dec = Decoder::new(&[0x13, 0x90]).unwrap();
+        assert!(!dec.sbr());
+        // ID_FIL, count 1, extension_type EXT_SBR_DATA (+ 4 bits of payload), ID_END
+        let _ = dec.decode(&[0b1100_0011, 0b1010_0001, 0b1100_0000]);
+        assert!(dec.sbr());
+        // other fill payloads (EXT_FILL) don't
+        let mut dec = Decoder::new(&[0x13, 0x90]).unwrap();
+        let _ = dec.decode(&[0b1100_0010, 0b0000_0001, 0b1100_0000]);
+        assert!(!dec.sbr());
+        // explicit signalling: AOT 5, core 22.05 kHz, stereo, extension 44.1 kHz, core AOT 2
+        let dec = Decoder::new(&[0x2B, 0x92, 0x08, 0x00]).unwrap();
+        assert!(dec.sbr());
+        assert_eq!(dec.sample_rate(), 22_050);
+    }
+}
@@ -31,6 +31,8 @@
 //! # Ok::<(), filmcraft_aac::Error>(())
 //! ```

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 mod config;
 mod decoder;
 mod encoder;
@@ -13,6 +13,8 @@
 //!
 //! E-AC-3 (bsid 11-16) is recognised and refused.

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 mod tables;

 use std::sync::OnceLock;
@@ -359,8 +361,7 @@ fn bit_allocation(exp: &[u8; 256], p: &AllocParams, g: &Globals, bap: &mut [u8;
    let bndend = tables::MASKTAB[end - 1] as usize + 1;
    let mut excite = [0i32; 50];
    let (mut fastleak, mut slowleak) = p.leak.unwrap_or((0, 0));
-    let begin;
-    if bndstrt == 0 {
+    let begin = if bndstrt == 0 {
        // the last band of the LFE channel (bndend 7) has no band above it
        let lfe_last = |bin: usize| !(bndend == 7 && bin == 6);
        let mut lowcomp = 0;
@@ -391,10 +392,10 @@ fn bit_allocation(exp: &[u8; 256], p: &AllocParams, g: &Globals, bap: &mut [u8;
            slowleak = slowleak.max(bndpsd[bin] - sgain);
            excite[bin] = (fastleak - lowcomp).max(slowleak);
        }
-        begin = 22;
+        22
    } else {
-        begin = bndstrt;
-    }
+        bndstrt
+    };
    for bin in begin..bndend {
        fastleak -= fdecay;
        fastleak = fastleak.max(bndpsd[bin] - p.fgain);
@@ -1030,7 +1031,7 @@ impl Decoder {
 /// Coded channel order (Table 5.8) → WAV / SMPTE order: fronts L R C, LFE, surrounds.
 fn wav_order(mut pcm: Vec<Vec<f32>>, acmod: usize, lfeon: bool) -> Vec<Vec<f32>> {
    let nf = NFCHANS[acmod];
-    let lfe = lfeon.then(|| pcm.pop().expect("lfe"));
+    let lfe = if lfeon { pcm.pop() } else { None };
    let mut fbw = pcm;
    // acmod 3, 5, 7 code L C R …: move C after R
    if acmod & 1 == 1 && acmod != 1 {
@@ -99,7 +99,7 @@ fn ffmpeg_encoded_streams_decode() {
            }
        }
        let o = Command::new(&ff).args(["-v", "error", "-i"]).arg(&f).args(["-f", "f32le", "-"]).output().unwrap();
-        let want: Vec<f32> = o.stdout.chunks_exact(4).map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect();
+        let want: Vec<f32> = o.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect();
        let ch = s.channels as usize;
        let n = want.len() / ch;
        assert_eq!(n, ours[0].len(), "{}: sample count", s.name);
@@ -0,0 +1,21 @@
+[package]
+name = "filmcraft-apv"
+description = "Clean-room Advanced Professional Video (APV, IETF RFC 9924) decoder and encoder"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[features]
+default = ["threads"]
+threads = ["dep:rayon"]
+
+[dependencies]
+filmcraft-bitstream.workspace = true
+rayon = { workspace = true, optional = true }
+thiserror.workspace = true
+
+[dev-dependencies]
+filmcraft-testkit.workspace = true
+
+[lints]
+workspace = true
@@ -0,0 +1,74 @@
+# filmcraft-apv
+
+Clean-room Advanced Professional Video (APV) decoder and encoder in pure Rust, implemented strictly
+from the public **IETF RFC 9924** specification (*Advanced Professional Video*, February 2026,
+ISSN 2070-1721).
+
+Layer L0: depends only on `filmcraft-bitstream`, `thiserror`, and (optional, feature `threads`,
+default on) `rayon`. Builds for `wasm32-unknown-unknown`; `unsafe_code = "forbid"`.
+
+## API
+
+```rust
+use filmcraft_apv::*;
+
+// Decode one APV Access Unit (or raw bitstream AU prefixed with a 32-bit au_size).
+let frame: Frame = decode_frame(&au)?;
+let f8 = decode_frame_with(&au, &DecodeOptions { bit_depth: Some(8), threads: true })?;
+decode_frame_into(&au, &DecodeOptions::default(), &mut frame_buf)?;
+let hdr: FrameHeader = probe(&au)?;
+
+// Split a multi-AU raw .apv bitstream (RFC 9924 Appendix A).
+let aus: Vec<&[u8]> = split_raw_bitstream(&raw_apv_bytes)?;
+
+// Encode progressive intra frames.
+let mut enc = Encoder::new(Profile::P422_10, 1920, 1080)?;
+let au: Vec<u8> = enc.encode(&frame)?;          // Access Unit starting with 'aPv1'
+let raw_au: Vec<u8> = enc.encode_raw_au(&frame)?; // Prefixed with 32-bit au_size (ISOBMFF apv1 / .apv)
+let apvc: Vec<u8> = enc.decoder_config_record();  // APVDecoderConfigurationRecord payload
+```
+
+## Specification Coverage (IETF RFC 9924)
+
+### Decoder
+- **Access Units & PBUs (§5.3.1–5.3.3, Appendix A)**: Accepts both unprefixed Access Units
+  (`'aPv1'` signature) and length-prefixed `raw_bitstream_access_unit()` packets. Parses primary
+  (`pbu_type == 1`), non-primary (`2`), preview (`25`), auxiliary alpha (`27`), AU info (`65`),
+  metadata (`66`), and filler (`67`) PBUs. PBUs or frame headers with non-zero `reserved_zero_*`
+  fields are ignored per §5.3.3 and §5.3.5.
+- **Profiles & Sampling (§9.3)**: All 7 standard profiles (`422-10` idc 33, `422-12` idc 44,
+  `444-10` idc 55, `444-12` idc 66, `4444-10` idc 77, `4444-12` idc 88, `400-10` idc 99) at
+  coded bit depths 10–16, with optional output depth rescaling (`8..=16`).
+- **Quantization Matrices & Tiles (§5.3.7–5.3.8, §5.3.12–5.3.14)**: Default flat (`16`) and
+  custom per-component 8×8 quantization matrices (`use_q_matrix`), optional `tile_size_in_fh`
+  verification, and independent per-tile, per-component byte-aligned entropy partitions. Tiles
+  decode in parallel via `rayon` when `threads` is enabled.
+- **Entropy Decoding (§5.3.15–5.3.16, §7.1)**: Adaptive Golomb-Rice / Exp-Golomb VLC decoding for
+  `abs_dc_coeff_diff`, `coeff_zero_run`, and `abs_ac_coeff_minus1` with state tracking (`PrevDC`,
+  `PrevDcDiff`, `Prev1stAcLevel`, `PrevLevel`, `PrevRun`) across the 8×8 blocks of each macroblock.
+- **Scaling & Inverse Transform (§6.3)**: Exact integer dequantization (`levelScale = [40, 45, 51,
+  57, 64, 71]`, `bdShift = BitDepth - 2`) and 2-D separable 8×8 integer inverse transform using the
+  RFC 9924 Figure 25 `transMatrix`. Note: in RFC 9924 §6.3.2.2, `transMatrix[m][n]` has row `m` as
+  the frequency index (row 0 is `[64; 8]`) and column `n` as the spatial sample index, so the 1-D
+  inverse transform evaluates `sum_j transMatrix[j][i] * x[j]`.
+- **Metadata (§8)**: Parses `metadata_mdcv` (`payloadType == 5`, Mastering Display Color Volume)
+  and `metadata_cll` (`payloadType == 6`, Content Light-Level Information).
+- **Robustness (§10)**: All size fields, tile coordinates, VLC codeword lengths, and coefficient
+  ranges (`-32768..=32767`) are checked before allocation or shift. Verified by `tests/fuzz.rs`
+  across thousands of mutated and random inputs.
+
+### Encoder
+- Progressive intra encoding for all 7 profiles (`422-10`, `422-12`, `444-10`, `444-12`,
+  `4444-10`, `4444-12`, `400-10`).
+- Supports fixed `qp` or binary-search frame-budget rate control over forward-transformed tiles.
+- Emits conforming tile grids (`tile_width_in_mbs >= 16`, `tile_height_in_mbs >= 8`,
+  `TileCols, TileRows <= 20`), optional custom quantization matrices, optional `MDCV`/`CLL`
+  metadata PBUs, and `APVDecoderConfigurationRecord` (`apvC`) metadata.
+
+## Accuracy (vs FFmpeg as an External Oracle)
+
+`tests/oracle.rs` encodes synthetic test patterns across all 7 profiles, odd dimensions, multiple
+tiles, custom asymmetric quantization matrices, and HDR metadata PBUs, then decodes the resulting
+`.apv` streams with `ffmpeg -v error -xerror -f apv` and compares against `filmcraft_apv::decode_frame`.
+Because APV specifies an exact integer inverse transform, **`filmcraft-apv` is 100% bit-exact
+(`max_diff = 0`) with FFmpeg's APV decoder across every profile and test case.**
@@ -0,0 +1,217 @@
+//! RFC 9924 §6.3 scaling and 8x8 integer inverse transform, plus the matching forward transform.
+
+use crate::tables::LEVEL_SCALE;
+
+/// 1D 8-point inverse transform using the RFC 9924 §6.3.2.3 even/odd butterfly decomposition,
+/// shifting each output by `(sum + round) >> shift`.
+#[inline(always)]
+fn idct_1d(x0: i32, x1: i32, x2: i32, x3: i32, x4: i32, x5: i32, x6: i32, x7: i32, round: i32, shift: u32) -> [i32; 8] {
+    if (x1 | x2 | x3 | x4 | x5 | x6 | x7) == 0 {
+        let v = (x0 * 64 + round) >> shift;
+        return [v; 8];
+    }
+    let e0 = 64 * (x0 + x4);
+    let e1 = 64 * (x0 - x4);
+    let e2 = 35 * x2 - 84 * x6;
+    let e3 = 84 * x2 + 35 * x6;
+
+    let even0 = e0 + e3;
+    let even1 = e1 + e2;
+    let even2 = e1 - e2;
+    let even3 = e0 - e3;
+
+    let odd0 = 89 * x1 + 75 * x3 + 50 * x5 + 18 * x7;
+    let odd1 = 75 * x1 - 18 * x3 - 89 * x5 - 50 * x7;
+    let odd2 = 50 * x1 - 89 * x3 + 18 * x5 + 75 * x7;
+    let odd3 = 18 * x1 - 50 * x3 + 75 * x5 - 89 * x7;
+
+    [
+        (even0 + odd0 + round) >> shift,
+        (even1 + odd1 + round) >> shift,
+        (even2 + odd2 + round) >> shift,
+        (even3 + odd3 + round) >> shift,
+        (even3 - odd3 + round) >> shift,
+        (even2 - odd2 + round) >> shift,
+        (even1 - odd1 + round) >> shift,
+        (even0 - odd0 + round) >> shift,
+    ]
+}
+
+/// Fast path when an 8x8 block has only a DC coefficient (`coeff[1..64]` are all zero).
+#[inline]
+pub fn scale_and_idct8x8_dc_only(dc_coeff: i16, q0: u8, qp: u8, bit_depth: u8, out: &mut [u16; 64]) {
+    let bd_shift_scale = (bit_depth as u32).saturating_sub(2);
+    let scale_round = if bd_shift_scale > 0 { 1i64 << (bd_shift_scale - 1) } else { 0 };
+    let level_scale = LEVEL_SCALE[(qp % 6) as usize] as i64;
+    let qp_shift = (qp / 6) as u32;
+
+    let scaled = ((dc_coeff as i64 * q0 as i64 * level_scale) << qp_shift) + scale_round;
+    let d0 = (scaled >> bd_shift_scale).clamp(-32768, 32767) as i32;
+    let g0 = (d0 * 64 + 64) >> 7;
+
+    let bd_shift = 20u32.saturating_sub(bit_depth as u32);
+    let round = 1i32 << (bd_shift - 1);
+    let mid = 1i32 << (bit_depth - 1);
+    let max_val = (1i32 << bit_depth) - 1;
+    let sample = (((g0 * 64 + round) >> bd_shift) + mid).clamp(0, max_val) as u16;
+    out.fill(sample);
+}
+
+/// Scale and inverse-transform one 8x8 block of transform coefficients (indexed by `y * 8 + x`)
+/// into reconstructed samples at `bit_depth` (`10..=16`), per RFC 9924 §6.3.
+#[inline]
+pub fn scale_and_idct8x8(coeff: &[i16; 64], q_matrix: &[u8; 64], qp: u8, bit_depth: u8, out: &mut [u16; 64]) {
+    let bd_shift_scale = (bit_depth as u32).saturating_sub(2);
+    let scale_round = if bd_shift_scale > 0 { 1i64 << (bd_shift_scale - 1) } else { 0 };
+    let level_scale = LEVEL_SCALE[(qp % 6) as usize] as i64;
+    let qp_shift = (qp / 6) as u32;
+
+    let mut d = [0i32; 64];
+    for idx in 0..64 {
+        let c = coeff[idx] as i64;
+        if c != 0 {
+            let qm = q_matrix[idx] as i64;
+            let scaled = ((c * qm * level_scale) << qp_shift) + scale_round;
+            d[idx] = (scaled >> bd_shift_scale).clamp(-32768, 32767) as i32;
+        }
+    }
+
+    // 1D vertical transform on each column x = 0..8, followed by (e + 64) >> 7
+    let mut g = [0i32; 64];
+    for x in 0..8 {
+        let col = idct_1d(d[x], d[8 + x], d[16 + x], d[24 + x], d[32 + x], d[40 + x], d[48 + x], d[56 + x], 64, 7);
+        for i in 0..8 {
+            g[i * 8 + x] = col[i];
+        }
+    }
+
+    // 1D horizontal transform on each row y = 0..8, followed by final bit-depth shift and offset
+    let bd_shift = 20u32.saturating_sub(bit_depth as u32);
+    let round = 1i32 << (bd_shift - 1);
+    let mid = 1i32 << (bit_depth - 1);
+    let max_val = (1i32 << bit_depth) - 1;
+
+    for y in 0..8 {
+        let r = &g[y * 8..y * 8 + 8];
+        let row = idct_1d(r[0], r[1], r[2], r[3], r[4], r[5], r[6], r[7], round, bd_shift);
+        for i in 0..8 {
+            out[y * 8 + i] = (row[i] + mid).clamp(0, max_val) as u16;
+        }
+    }
+}
+
+/// 1D 8-point forward butterfly transform matching `TRANS_MATRIX`.
+#[inline(always)]
+fn fdct_1d(x0: i32, x1: i32, x2: i32, x3: i32, x4: i32, x5: i32, x6: i32, x7: i32, round: i32, shift: u32) -> [i32; 8] {
+    let s0 = x0 + x7;
+    let d0 = x0 - x7;
+    let s1 = x1 + x6;
+    let d1 = x1 - x6;
+    let s2 = x2 + x5;
+    let d2 = x2 - x5;
+    let s3 = x3 + x4;
+    let d3 = x3 - x4;
+
+    let es0 = s0 + s3;
+    let ed0 = s0 - s3;
+    let es1 = s1 + s2;
+    let ed1 = s1 - s2;
+
+    [
+        (64 * (es0 + es1) + round) >> shift,
+        (89 * d0 + 75 * d1 + 50 * d2 + 18 * d3 + round) >> shift,
+        (84 * ed0 + 35 * ed1 + round) >> shift,
+        (75 * d0 - 18 * d1 - 89 * d2 - 50 * d3 + round) >> shift,
+        (64 * (es0 - es1) + round) >> shift,
+        (50 * d0 - 89 * d1 + 18 * d2 + 75 * d3 + round) >> shift,
+        (35 * ed0 - 84 * ed1 + round) >> shift,
+        (18 * d0 - 50 * d1 + 75 * d2 - 89 * d3 + round) >> shift,
+    ]
+}
+
+/// Forward 8x8 transform of level-shifted samples (`sample - (1 << (bit_depth - 1))`) into the
+/// scaled coefficient domain `d[y * 8 + x]` matching [`scale_and_idct8x8`].
+#[inline]
+pub fn fdct8x8(samples: &[u16; 64], bit_depth: u8) -> [i32; 64] {
+    let mid = 1i32 << (bit_depth - 1);
+    let shift1 = (bit_depth as u32).saturating_sub(5);
+    let add1 = if shift1 > 0 { 1i32 << (shift1 - 1) } else { 0 };
+
+    // Horizontal forward pass
+    let mut t = [0i32; 64];
+    for y in 0..8 {
+        let s = &samples[y * 8..y * 8 + 8];
+        let row = fdct_1d(
+            s[0] as i32 - mid,
+            s[1] as i32 - mid,
+            s[2] as i32 - mid,
+            s[3] as i32 - mid,
+            s[4] as i32 - mid,
+            s[5] as i32 - mid,
+            s[6] as i32 - mid,
+            s[7] as i32 - mid,
+            add1,
+            shift1,
+        );
+        t[y * 8..y * 8 + 8].copy_from_slice(&row);
+    }
+
+    // Vertical forward pass
+    let mut f = [0i32; 64];
+    for u in 0..8 {
+        let col = fdct_1d(t[u], t[8 + u], t[16 + u], t[24 + u], t[32 + u], t[40 + u], t[48 + u], t[56 + u], 128, 8);
+        for v in 0..8 {
+            f[v * 8 + u] = col[v];
+        }
+    }
+    f
+}
+
+/// Quantize forward-transformed coefficients `f` (in the `d` domain) at `qp` with `q_matrix`.
+#[inline]
+pub fn quantize8x8(f: &[i32; 64], q_matrix: &[u8; 64], qp: u8, bit_depth: u8) -> [i16; 64] {
+    let bd_shift_scale = (bit_depth as u32).saturating_sub(2);
+    let level_scale = LEVEL_SCALE[(qp % 6) as usize] as i64;
+    let qp_shift = (qp / 6) as u32;
+
+    let mut out = [0i16; 64];
+    for idx in 0..64 {
+        let val = f[idx] as i64;
+        if val == 0 {
+            continue;
+        }
+        let sign = if val < 0 { -1i64 } else { 1i64 };
+        let abs_val = val.unsigned_abs() as i64;
+        let qm = q_matrix[idx].max(1) as i64;
+        let den = (qm * level_scale) << qp_shift;
+        let num = abs_val << bd_shift_scale;
+        // Deadzone/rounding offset: 1/2 for DC, 3/8 for AC
+        let offset = if idx == 0 { den / 2 } else { (den * 3) / 8 };
+        let level = ((num + offset) / den).min(32767);
+        out[idx] = (level * sign) as i16;
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fdct_idct_roundtrip_10bit() {
+        let mut src = [0u16; 64];
+        for (i, s) in src.iter_mut().enumerate() {
+            *s = (64 + (i * 13) % 850) as u16;
+        }
+        let qm = [16u8; 64];
+        // At qp = 0 (very fine quantization), roundtrip is within 1 LSB
+        let f = fdct8x8(&src, 10);
+        let q = quantize8x8(&f, &qm, 0, 10);
+        let mut rec = [0u16; 64];
+        scale_and_idct8x8(&q, &qm, 0, 10, &mut rec);
+        for i in 0..64 {
+            let err = (src[i] as i32 - rec[i] as i32).abs();
+            assert!(err <= 1, "idx {i}: src={} rec={} err={err}", src[i], rec[i]);
+        }
+    }
+}
@@ -0,0 +1,484 @@
+//! RFC 9924 APV frame and tile decoder.
+
+use filmcraft_bitstream::BitReader;
+
+use crate::dct::{scale_and_idct8x8, scale_and_idct8x8_dc_only};
+use crate::header::{
+    FrameHeader, PBU_ALPHA_FRAME, PBU_METADATA, PBU_NON_PRIMARY_FRAME, PBU_PREVIEW_FRAME, PBU_PRIMARY_FRAME, parse_au_pbus, parse_frame_header,
+    parse_metadata_pbu, read_byte_alignment,
+};
+use crate::tables::ZIGZAG_8X8;
+use crate::{ChromaFormat, ContentLightLevel, Error, Frame, MasteringDisplay, Result};
+
+/// Options for [`decode_frame_with`] and [`decode_frame_into`].
+#[derive(Debug, Clone)]
+pub struct DecodeOptions {
+    /// Output sample bit depth (`8..=16`). `None` keeps the stream's coded bit depth (`10..=16`).
+    pub bit_depth: Option<u8>,
+    /// Decode tiles in parallel when the `threads` feature is enabled.
+    pub threads: bool,
+}
+
+impl Default for DecodeOptions {
+    fn default() -> Self {
+        Self { bit_depth: None, threads: true }
+    }
+}
+
+/// Parse RFC 9924 §7.1.4 variable-length codeword (`h(v)`).
+#[inline]
+pub(crate) fn read_vlc(r: &mut BitReader, k_param: u32) -> Result<u32> {
+    let mut symbol_value: u64 = 0;
+    let mut k = k_param;
+    let parse_exp_golomb = if r.read_bit().map_err(|_| Error::Truncated)? {
+        false
+    } else if !r.read_bit().map_err(|_| Error::Truncated)? {
+        symbol_value += 1u64 << k;
+        false
+    } else {
+        symbol_value += 2u64 << k;
+        true
+    };
+    if parse_exp_golomb {
+        loop {
+            if r.read_bit().map_err(|_| Error::Truncated)? {
+                break;
+            }
+            symbol_value += 1u64 << k;
+            k += 1;
+            if k > 28 {
+                return Err(Error::Invalid("VLC codeword exceeds maximum length"));
+            }
+        }
+    }
+    if k > 0 {
+        symbol_value += r.read_bits(k).map_err(|_| Error::Truncated)? as u64;
+    }
+    u32::try_from(symbol_value).map_err(|_| Error::Invalid("VLC symbol overflow"))
+}
+
+/// Probe the primary frame header of an Access Unit without decoding its tiles.
+pub fn probe(data: &[u8]) -> Result<FrameHeader> {
+    let pbus = parse_au_pbus(data)?;
+    for pbu in &pbus {
+        if matches!(pbu.pbu_type, PBU_PRIMARY_FRAME | PBU_NON_PRIMARY_FRAME | PBU_PREVIEW_FRAME)
+            && let Some(hdr) = parse_frame_header(pbu.payload)?
+        {
+            return Ok(hdr);
+        }
+    }
+    Err(Error::Invalid("no decodable frame PBU in access unit"))
+}
+
+/// Decode one APV Access Unit with default options.
+pub fn decode_frame(data: &[u8]) -> Result<Frame> {
+    decode_frame_with(data, &DecodeOptions::default())
+}
+
+/// Decode one APV Access Unit with custom [`DecodeOptions`].
+pub fn decode_frame_with(data: &[u8], opts: &DecodeOptions) -> Result<Frame> {
+    let mut out = Frame::new(2, 2, ChromaFormat::Yuv422, 10, false);
+    decode_frame_into(data, opts, &mut out)?;
+    Ok(out)
+}
+
+/// Decode one APV Access Unit into `out`, reusing its plane allocations when possible.
+pub fn decode_frame_into(data: &[u8], opts: &DecodeOptions, out: &mut Frame) -> Result<FrameHeader> {
+    if let Some(d) = opts.bit_depth
+        && !(8..=16).contains(&d)
+    {
+        return Err(Error::Invalid("requested output bit_depth must be in 8..=16"));
+    }
+
+    let pbus = parse_au_pbus(data)?;
+    let mut primary: Option<(u16, FrameHeader, &[u8])> = None;
+    let mut alpha_pbu: Option<(FrameHeader, &[u8])> = None;
+    let mut mdcv: Option<MasteringDisplay> = None;
+    let mut cll: Option<ContentLightLevel> = None;
+
+    for pbu in &pbus {
+        match pbu.pbu_type {
+            PBU_PRIMARY_FRAME => {
+                if primary.is_none()
+                    && let Some(hdr) = parse_frame_header(pbu.payload)?
+                {
+                    primary = Some((pbu.group_id, hdr, pbu.payload));
+                }
+            }
+            PBU_NON_PRIMARY_FRAME | PBU_PREVIEW_FRAME => {
+                if primary.is_none()
+                    && let Some(hdr) = parse_frame_header(pbu.payload)?
+                {
+                    primary = Some((pbu.group_id, hdr, pbu.payload));
+                }
+            }
+            PBU_ALPHA_FRAME => {
+                if alpha_pbu.is_none()
+                    && let Some(hdr) = parse_frame_header(pbu.payload)?
+                {
+                    alpha_pbu = Some((hdr, pbu.payload));
+                }
+            }
+            PBU_METADATA => {
+                let _ = parse_metadata_pbu(pbu.payload, &mut mdcv, &mut cll);
+            }
+            _ => {}
+        }
+    }
+
+    let (_group_id, hdr, payload) = primary.ok_or(Error::Invalid("no primary frame PBU in access unit"))?;
+    let out_depth = opts.bit_depth.unwrap_or(hdr.bit_depth);
+
+    decode_pbu_planes(&hdr, payload, out_depth, opts.threads, out)?;
+    out.mastering_display = mdcv;
+    out.content_light = cll;
+
+    // If the primary frame has no 4th component and an auxiliary alpha frame PBU (type 27) is present
+    // with matching dimensions, decode its luma plane as the alpha plane.
+    if out.alpha.is_none()
+        && let Some((ahdr, apayload)) = alpha_pbu
+        && ahdr.width == hdr.width
+        && ahdr.height == hdr.height
+    {
+        let mut aframe = Frame::new(ahdr.width, ahdr.height, ahdr.chroma, out_depth, false);
+        if decode_pbu_planes(&ahdr, apayload, out_depth, opts.threads, &mut aframe).is_ok() {
+            out.alpha = Some(aframe.y);
+        }
+    }
+
+    Ok(hdr)
+}
+
+#[derive(Clone)]
+struct DecodedTile {
+    x0: u32,
+    y0: u32,
+    w_luma: u32,
+    h_luma: u32,
+    /// Decoded pixels for each component `c` in `0..num_comps`, packed with stride `w_luma / sub_w`.
+    comps: [Vec<u16>; 4],
+}
+
+fn decode_pbu_planes(hdr: &FrameHeader, payload: &[u8], out_depth: u8, threads: bool, out: &mut Frame) -> Result<()> {
+    let num_tiles = hdr.num_tiles();
+    let mut pos = hdr.header_bytes;
+    let mut tile_slices: Vec<(usize, &[u8])> = Vec::with_capacity(num_tiles);
+
+    for tile_idx in 0..num_tiles {
+        let sz_bytes = payload.get(pos..pos + 4).ok_or(Error::Truncated)?;
+        let tile_size = u32::from_be_bytes([sz_bytes[0], sz_bytes[1], sz_bytes[2], sz_bytes[3]]) as usize;
+        if tile_size == 0 {
+            return Err(Error::Invalid("tile_size cannot be 0"));
+        }
+        if let Some(fh_sizes) = &hdr.tile_sizes_in_fh
+            && fh_sizes.get(tile_idx).copied() != Some(tile_size as u32)
+        {
+            return Err(Error::Invalid("tile_size does not match tile_size_in_fh"));
+        }
+        pos += 4;
+        let tile_end = pos.checked_add(tile_size).ok_or(Error::Truncated)?;
+        let tile_bytes = payload.get(pos..tile_end).ok_or(Error::Truncated)?;
+        pos = tile_end;
+        tile_slices.push((tile_idx, tile_bytes));
+    }
+
+    // Verify any trailing filler bytes in the frame PBU are 0xFF (RFC 9924 §5.3.4 & §5.3.11)
+    if payload.get(pos..).is_some_and(|rest| rest.iter().any(|&b| b != 0xFF)) {
+        return Err(Error::Invalid("non-0xFF filler byte at end of frame PBU"));
+    }
+
+    #[cfg(feature = "threads")]
+    let decoded_tiles: Result<Vec<DecodedTile>> = if threads && tile_slices.len() > 1 {
+        use rayon::prelude::*;
+        tile_slices.into_par_iter().map(|(idx, bytes)| decode_single_tile(hdr, idx, bytes, out_depth, false)).collect()
+    } else {
+        tile_slices.into_iter().map(|(idx, bytes)| decode_single_tile(hdr, idx, bytes, out_depth, threads)).collect()
+    };
+
+    #[cfg(not(feature = "threads"))]
+    let decoded_tiles: Result<Vec<DecodedTile>> = {
+        let _ = threads;
+        tile_slices.into_iter().map(|(idx, bytes)| decode_single_tile(hdr, idx, bytes, out_depth, false)).collect()
+    };
+
+    let mut decoded_tiles = decoded_tiles?;
+
+    // Prepare output frame metadata
+    let w = hdr.width as usize;
+    let h = hdr.height as usize;
+    let cw = hdr.chroma.chroma_width(hdr.width) as usize;
+    let ch = hdr.chroma.chroma_height(hdr.height) as usize;
+    let n_luma = w.checked_mul(h).ok_or(Error::Invalid("frame luma size overflow"))?;
+    let n_chroma = cw.checked_mul(ch).ok_or(Error::Invalid("frame chroma size overflow"))?;
+
+    out.width = hdr.width;
+    out.height = hdr.height;
+    out.chroma = hdr.chroma;
+    out.bit_depth = out_depth;
+    out.color = hdr.color;
+    out.profile_idc = hdr.profile_idc;
+    out.level_idc = hdr.level_idc;
+    out.band_idc = hdr.band_idc;
+
+    // Zero-copy fast path when a single tile covers the exact frame dimensions without macroblock padding.
+    if decoded_tiles.len() == 1 && decoded_tiles[0].w_luma == hdr.width && decoded_tiles[0].h_luma == hdr.height {
+        let [y, cb, cr, a] = std::mem::take(&mut decoded_tiles[0].comps);
+        out.y = y;
+        if hdr.chroma.num_comps() >= 3 {
+            out.cb = cb;
+            out.cr = cr;
+        } else {
+            out.cb.clear();
+            out.cr.clear();
+        }
+        out.alpha = if hdr.chroma == ChromaFormat::Yuv4444 { Some(a) } else { None };
+        return Ok(());
+    }
+
+    out.y.resize(n_luma, 0);
+    out.cb.resize(n_chroma, 0);
+    out.cr.resize(n_chroma, 0);
+    if hdr.chroma == ChromaFormat::Yuv4444 {
+        let a = out.alpha.get_or_insert_with(Vec::new);
+        a.resize(n_luma, 0);
+    } else {
+        out.alpha = None;
+    }
+
+    // Copy each tile's reconstructed samples into the cropped output planes (RFC 9924 §6)
+    let sub_w = hdr.chroma.sub_width_c() as usize;
+    let sub_h = hdr.chroma.sub_height_c() as usize;
+
+    for tile in &decoded_tiles {
+        copy_tile_comp(&tile.comps[0], tile.w_luma as usize, tile.h_luma as usize, tile.x0 as usize, tile.y0 as usize, &mut out.y, w, h);
+        if hdr.chroma.num_comps() >= 3 {
+            let tw_c = (tile.w_luma as usize) / sub_w;
+            let th_c = (tile.h_luma as usize) / sub_h;
+            let tx_c = (tile.x0 as usize) / sub_w;
+            let ty_c = (tile.y0 as usize) / sub_h;
+            copy_tile_comp(&tile.comps[1], tw_c, th_c, tx_c, ty_c, &mut out.cb, cw, ch);
+            copy_tile_comp(&tile.comps[2], tw_c, th_c, tx_c, ty_c, &mut out.cr, cw, ch);
+        }
+        if hdr.chroma == ChromaFormat::Yuv4444
+            && let Some(alpha) = out.alpha.as_mut()
+        {
+            copy_tile_comp(&tile.comps[3], tile.w_luma as usize, tile.h_luma as usize, tile.x0 as usize, tile.y0 as usize, alpha, w, h);
+        }
+    }
+
+    Ok(())
+}
+
+fn copy_tile_comp(src: &[u16], tw: usize, th: usize, tx: usize, ty: usize, dst: &mut [u16], fw: usize, fh: usize) {
+    if tx >= fw || ty >= fh {
+        return;
+    }
+    let copy_w = tw.min(fw - tx);
+    let copy_h = th.min(fh - ty);
+    for r in 0..copy_h {
+        let s_off = r * tw;
+        let d_off = (ty + r) * fw + tx;
+        dst[d_off..d_off + copy_w].copy_from_slice(&src[s_off..s_off + copy_w]);
+    }
+}
+
+fn decode_single_tile(hdr: &FrameHeader, tile_idx: usize, tile_bytes: &[u8], out_depth: u8, par_comps: bool) -> Result<DecodedTile> {
+    let num_comps = hdr.chroma.num_comps();
+    let min_hdr_size = 5 + 5 * num_comps;
+    if tile_bytes.len() < min_hdr_size {
+        return Err(Error::Truncated);
+    }
+
+    // tile_header(tileIdx) (RFC 9924 §5.3.13)
+    let tile_header_size = u16::from_be_bytes([tile_bytes[0], tile_bytes[1]]) as usize;
+    let tile_index = u16::from_be_bytes([tile_bytes[2], tile_bytes[3]]) as usize;
+    if tile_index != tile_idx {
+        return Err(Error::CorruptTile(tile_idx));
+    }
+    if tile_header_size < min_hdr_size || tile_header_size > tile_bytes.len() {
+        return Err(Error::CorruptTile(tile_idx));
+    }
+
+    let mut tile_data_size = [0usize; 4];
+    for c in 0..num_comps {
+        let off = 4 + c * 4;
+        let sz = u32::from_be_bytes([tile_bytes[off], tile_bytes[off + 1], tile_bytes[off + 2], tile_bytes[off + 3]]) as usize;
+        if sz == 0 {
+            return Err(Error::CorruptTile(tile_idx));
+        }
+        tile_data_size[c] = sz;
+    }
+
+    let max_tile_qp = (51 + hdr.qp_bd_offset()) as u8;
+    let mut tile_qp = [0u8; 4];
+    for c in 0..num_comps {
+        let qp = tile_bytes[4 + num_comps * 4 + c];
+        if qp > max_tile_qp {
+            return Err(Error::CorruptTile(tile_idx));
+        }
+        tile_qp[c] = qp;
+    }
+
+    let reserved_zero_8bits = tile_bytes[4 + num_comps * 5];
+    if reserved_zero_8bits != 0 {
+        return Err(Error::CorruptTile(tile_idx));
+    }
+
+    let tx = tile_idx % (hdr.tile_cols as usize);
+    let ty = tile_idx / (hdr.tile_cols as usize);
+    let x0 = hdr.col_starts[tx];
+    let x1 = hdr.col_starts[tx + 1];
+    let y0 = hdr.row_starts[ty];
+    let y1 = hdr.row_starts[ty + 1];
+    let w_luma = x1.saturating_sub(x0);
+    let h_luma = y1.saturating_sub(y0);
+
+    let mut comp_off = tile_header_size;
+    let mut comp_slices: Vec<(usize, &[u8])> = Vec::with_capacity(num_comps);
+    for c in 0..num_comps {
+        let comp_end = comp_off.checked_add(tile_data_size[c]).ok_or(Error::CorruptTile(tile_idx))?;
+        let comp_bytes = tile_bytes.get(comp_off..comp_end).ok_or(Error::CorruptTile(tile_idx))?;
+        comp_off = comp_end;
+        comp_slices.push((c, comp_bytes));
+    }
+
+    #[cfg(feature = "threads")]
+    let decoded_comps: Result<Vec<Vec<u16>>> = if par_comps && comp_slices.len() > 1 {
+        use rayon::prelude::*;
+        comp_slices.into_par_iter().map(|(c, comp_bytes)| decode_tile_comp(hdr, tile_idx, c, comp_bytes, tile_qp[c], w_luma, h_luma, out_depth)).collect()
+    } else {
+        comp_slices.into_iter().map(|(c, comp_bytes)| decode_tile_comp(hdr, tile_idx, c, comp_bytes, tile_qp[c], w_luma, h_luma, out_depth)).collect()
+    };
+
+    #[cfg(not(feature = "threads"))]
+    let decoded_comps: Result<Vec<Vec<u16>>> = {
+        let _ = par_comps;
+        comp_slices.into_iter().map(|(c, comp_bytes)| decode_tile_comp(hdr, tile_idx, c, comp_bytes, tile_qp[c], w_luma, h_luma, out_depth)).collect()
+    };
+
+    let mut comps: [Vec<u16>; 4] = Default::default();
+    for (c, buf) in decoded_comps?.into_iter().enumerate() {
+        comps[c] = buf;
+    }
+
+    Ok(DecodedTile { x0, y0, w_luma, h_luma, comps })
+}
+
+#[allow(clippy::too_many_arguments)]
+fn decode_tile_comp(hdr: &FrameHeader, tile_idx: usize, c: usize, comp_bytes: &[u8], qp: u8, w_luma: u32, h_luma: u32, out_depth: u8) -> Result<Vec<u16>> {
+    let num_mb_cols = w_luma / 16;
+    let num_mb_rows = h_luma / 16;
+    let sub_w = if c == 0 { 1 } else { hdr.chroma.sub_width_c() };
+    let sub_h = if c == 0 { 1 } else { hdr.chroma.sub_height_c() };
+    let tw_c = (w_luma / sub_w) as usize;
+    let th_c = (h_luma / sub_h) as usize;
+    let blk_w = (16 / sub_w) as usize;
+    let blk_h = (16 / sub_h) as usize;
+    let blocks_x = blk_w / 8;
+    let blocks_y = blk_h / 8;
+
+    let mut comp_buf = vec![0u16; tw_c * th_c];
+    let mut r = BitReader::new(comp_bytes);
+
+    let mut prev_dc: i32 = 0;
+    let mut prev_dc_diff: u32 = 20;
+    let mut prev_1st_ac_level: u32 = 0;
+
+    let q_mat = &hdr.q_matrix[c];
+    let coded_depth = hdr.bit_depth;
+
+    for mb_y in 0..(num_mb_rows as usize) {
+        for mb_x in 0..(num_mb_cols as usize) {
+            for by in 0..blocks_y {
+                for bx in 0..blocks_x {
+                    // abs_dc_coeff_diff (RFC 9924 §5.3.15 & §7.1.1)
+                    let k_dc = (prev_dc_diff >> 1).min(5);
+                    let abs_dc_diff = read_vlc(&mut r, k_dc).map_err(|_| Error::CorruptTile(tile_idx))?;
+                    let sign_dc = if abs_dc_diff > 0 { r.read_bit().map_err(|_| Error::CorruptTile(tile_idx))? } else { false };
+                    let diff = if sign_dc { -(abs_dc_diff as i64) } else { abs_dc_diff as i64 };
+                    let dc = prev_dc as i64 + diff;
+                    if !(-32768..=32767).contains(&dc) {
+                        return Err(Error::CorruptTile(tile_idx));
+                    }
+                    prev_dc = dc as i32;
+                    prev_dc_diff = abs_dc_diff;
+
+                    let mut coeff = [0i16; 64];
+                    coeff[0] = dc as i16;
+
+                    // ac_coeff_coding (RFC 9924 §5.3.16 & §7.1.2–7.1.3)
+                    let mut scan_pos = 1usize;
+                    let mut first_ac = true;
+                    let mut prev_level = prev_1st_ac_level;
+                    let mut prev_run = 0u32;
+
+                    while scan_pos < 64 {
+                        let k_run = (prev_run >> 2).min(2);
+                        let run = read_vlc(&mut r, k_run).map_err(|_| Error::CorruptTile(tile_idx))? as usize;
+                        scan_pos = scan_pos.checked_add(run).ok_or(Error::CorruptTile(tile_idx))?;
+                        if scan_pos > 64 {
+                            return Err(Error::CorruptTile(tile_idx));
+                        }
+                        prev_run = run as u32;
+                        if scan_pos < 64 {
+                            let k_lvl = (prev_level >> 2).min(4);
+                            let abs_ac_minus1 = read_vlc(&mut r, k_lvl).map_err(|_| Error::CorruptTile(tile_idx))?;
+                            let sign_ac = r.read_bit().map_err(|_| Error::CorruptTile(tile_idx))?;
+                            let abs_level = (abs_ac_minus1 as u64) + 1;
+                            let level_i64 = if sign_ac { -(abs_level as i64) } else { abs_level as i64 };
+                            if !(-32768..=32767).contains(&level_i64) {
+                                return Err(Error::CorruptTile(tile_idx));
+                            }
+                            coeff[ZIGZAG_8X8[scan_pos] as usize] = level_i64 as i16;
+                            scan_pos += 1;
+                            prev_level = abs_level as u32;
+                            if first_ac {
+                                first_ac = false;
+                                prev_1st_ac_level = prev_level;
+                            }
+                        }
+                    }
+
+                    let mut rec = [0u16; 64];
+                    if first_ac {
+                        scale_and_idct8x8_dc_only(coeff[0], q_mat[0], qp, coded_depth, &mut rec);
+                    } else {
+                        scale_and_idct8x8(&coeff, q_mat, qp, coded_depth, &mut rec);
+                    }
+                    if out_depth != coded_depth {
+                        rescale_block(&mut rec, coded_depth, out_depth);
+                    }
+
+                    let px0 = mb_x * blk_w + bx * 8;
+                    let py0 = mb_y * blk_h + by * 8;
+                    for ry in 0..8 {
+                        let dst_row = (py0 + ry) * tw_c + px0;
+                        comp_buf[dst_row..dst_row + 8].copy_from_slice(&rec[ry * 8..ry * 8 + 8]);
+                    }
+                }
+            }
+        }
+    }
+
+    read_byte_alignment(&mut r).map_err(|_| Error::CorruptTile(tile_idx))?;
+    Ok(comp_buf)
+}
+
+#[inline]
+fn rescale_block(block: &mut [u16; 64], from_depth: u8, to_depth: u8) {
+    if to_depth > from_depth {
+        let shift = (to_depth - from_depth) as u32;
+        let fill_shift = from_depth as u32;
+        for s in block.iter_mut() {
+            let v = *s as u32;
+            *s = ((v << shift) | (v >> (fill_shift - shift))) as u16;
+        }
+    } else if to_depth < from_depth {
+        let shift = (from_depth - to_depth) as u32;
+        let round = 1u32 << (shift - 1);
+        let max_v = (1u32 << to_depth) - 1;
+        for s in block.iter_mut() {
+            *s = (((*s as u32) + round) >> shift).min(max_v) as u16;
+        }
+    }
+}
@@ -0,0 +1,598 @@
+//! RFC 9924 APV intra frame encoder.
+
+use filmcraft_bitstream::BitWriter;
+
+use crate::dct::{fdct8x8, quantize8x8};
+use crate::header::{FrameHeader, MAX_DIMENSION, PBU_PRIMARY_FRAME, write_frame_header, write_metadata_pbu};
+use crate::tables::{DEFAULT_Q_MATRIX_VAL, ZIGZAG_8X8, select_level_and_band};
+use crate::{ChromaFormat, ColorInfo, ContentLightLevel, Error, Frame, MasteringDisplay, Profile, Result};
+
+/// Generate RFC 9924 §7.2.4 variable-length codeword (`h(v)`).
+#[inline]
+pub(crate) fn write_vlc(w: &mut BitWriter, symbol_val: u32, k_param: u32) {
+    const PREFIX_VLC: [[u32; 2]; 3] = [[1, 0], [0, 0], [0, 1]];
+    let mut symbol_value = symbol_val;
+    let val_prefix = ((symbol_val >> k_param) as usize).min(2);
+    let mut bit_count = 0usize;
+    let mut k = k_param;
+
+    while symbol_value >= (1u32 << k) {
+        symbol_value -= 1u32 << k;
+        if bit_count < 2 {
+            w.write_bits(PREFIX_VLC[val_prefix][bit_count], 1);
+        } else {
+            w.write_bits(0, 1);
+        }
+        if bit_count >= 2 {
+            k += 1;
+        }
+        bit_count += 1;
+    }
+    if bit_count < 2 {
+        w.write_bits(PREFIX_VLC[val_prefix][bit_count], 1);
+    } else {
+        w.write_bits(1, 1);
+    }
+    if k > 0 {
+        w.write_bits(symbol_value, k);
+    }
+}
+
+/// Exact bit length of a VLC codeword generated by [`write_vlc`].
+#[inline]
+pub(crate) fn vlc_bit_len(symbol_val: u32, k_param: u32) -> u32 {
+    if symbol_val < (1u32 << k_param) {
+        1 + k_param
+    } else if symbol_val < (2u32 << k_param) {
+        2 + k_param
+    } else {
+        let rem = (symbol_val >> k_param) - 1;
+        let zeros = 31 - rem.leading_zeros();
+        3 + k_param + 2 * zeros
+    }
+}
+
+/// APV encoder configuration.
+#[derive(Debug, Clone)]
+pub struct EncoderConfig {
+    pub profile: Profile,
+    pub width: u32,
+    pub height: u32,
+    pub chroma: ChromaFormat,
+    pub bit_depth: u8,
+    pub color: ColorInfo,
+    pub color_description_present: bool,
+    /// Fixed tile quantization parameter (`0..=51 + QpBdOffset`). When `None`, rate control
+    /// chooses a uniform QP per frame to fit [`Self::target_frame_bytes`].
+    pub qp: Option<u8>,
+    /// Target encoded frame size in bytes when `qp` is `None`.
+    pub target_frame_bytes: u32,
+    /// Tile width in 16x16 macroblocks (RFC 9924 §9.4.1 requires `>= 16`).
+    pub tile_width_in_mbs: u32,
+    /// Tile height in 16x16 macroblocks (RFC 9924 §9.4.1 requires `>= 8`).
+    pub tile_height_in_mbs: u32,
+    pub level_idc: u8,
+    pub band_idc: u8,
+    /// Optional custom per-component 8x8 quantization matrices (`y * 8 + x`).
+    pub q_matrix: Option<[[u8; 64]; 4]>,
+    /// Write `tile_size_in_fh` array in `frame_header()` (`tile_size_present_in_fh_flag = 1`).
+    pub write_tile_sizes_in_fh: bool,
+    pub mastering_display: Option<MasteringDisplay>,
+    pub content_light: Option<ContentLightLevel>,
+}
+
+impl EncoderConfig {
+    pub fn new(profile: Profile, width: u32, height: u32) -> Self {
+        let chroma = profile.default_chroma();
+        let bit_depth = profile.default_bit_depth();
+        let w_mbs = width.div_ceil(16).max(1);
+        let h_mbs = height.div_ceil(16).max(1);
+        // Choose conforming tile dimensions (>= 16x8 MBs, <= 20x20 tiles) with ~4-8 tiles on HD/4K.
+        let tile_width_in_mbs = w_mbs.div_ceil(4).max(16).max(w_mbs.div_ceil(20));
+        let tile_height_in_mbs = h_mbs.div_ceil(4).max(8).max(h_mbs.div_ceil(20));
+        let target_frame_bytes = profile.nominal_frame_bytes(width, height);
+        let kbps = ((target_frame_bytes as u64) * 8 * 30 / 1000).max(1000) as u32;
+        let (level_idc, band_idc) = select_level_and_band((width as u64) * (height as u64) * 30, kbps);
+        Self {
+            profile,
+            width,
+            height,
+            chroma,
+            bit_depth,
+            color: ColorInfo::BT709,
+            color_description_present: true,
+            qp: None,
+            target_frame_bytes,
+            tile_width_in_mbs,
+            tile_height_in_mbs,
+            level_idc,
+            band_idc,
+            q_matrix: None,
+            write_tile_sizes_in_fh: false,
+            mastering_display: None,
+            content_light: None,
+        }
+    }
+}
+
+/// APV intra encoder.
+pub struct Encoder {
+    cfg: EncoderConfig,
+    hdr: FrameHeader,
+}
+
+struct PreparedTileComp {
+    /// Forward-transformed 8x8 blocks in MB-then-subblock scan order.
+    blocks: Vec<[i32; 64]>,
+}
+
+struct PreparedTile {
+    tile_idx: usize,
+    comps: Vec<PreparedTileComp>,
+}
+
+impl Encoder {
+    pub fn new(profile: Profile, width: u32, height: u32) -> Result<Self> {
+        Self::with_config(EncoderConfig::new(profile, width, height))
+    }
+
+    pub fn with_config(cfg: EncoderConfig) -> Result<Self> {
+        if cfg.width == 0 || cfg.height == 0 || cfg.width > MAX_DIMENSION || cfg.height > MAX_DIMENSION {
+            return Err(Error::Input(format!("unsupported dimensions {}x{}", cfg.width, cfg.height)));
+        }
+        if cfg.chroma == ChromaFormat::Yuv422 && !cfg.width.is_multiple_of(2) {
+            return Err(Error::Input("4:2:2 requires even frame width".into()));
+        }
+        if !(10..=16).contains(&cfg.bit_depth) {
+            return Err(Error::Input(format!("unsupported coded bit depth {}", cfg.bit_depth)));
+        }
+        if !cfg.profile.supports(cfg.chroma, cfg.bit_depth) {
+            return Err(Error::Input(format!("profile {} does not support {:?} {}-bit", cfg.profile.name(), cfg.chroma, cfg.bit_depth)));
+        }
+        if cfg.tile_width_in_mbs == 0 || cfg.tile_height_in_mbs == 0 {
+            return Err(Error::Input("tile dimensions in MBs must be non-zero".into()));
+        }
+
+        let w_mbs = cfg.width.div_ceil(16);
+        let h_mbs = cfg.height.div_ceil(16);
+        let tile_cols = w_mbs.div_ceil(cfg.tile_width_in_mbs);
+        let tile_rows = h_mbs.div_ceil(cfg.tile_height_in_mbs);
+        if tile_cols > 20 || tile_rows > 20 {
+            return Err(Error::Input(format!("tile grid {tile_cols}x{tile_rows} exceeds RFC 9924 limit of 20x20")));
+        }
+
+        let mut col_starts = Vec::with_capacity(tile_cols as usize + 1);
+        let mut s = 0u32;
+        while s < w_mbs {
+            col_starts.push(s * 16);
+            s += cfg.tile_width_in_mbs;
+        }
+        col_starts.push(w_mbs * 16);
+
+        let mut row_starts = Vec::with_capacity(tile_rows as usize + 1);
+        let mut s = 0u32;
+        while s < h_mbs {
+            row_starts.push(s * 16);
+            s += cfg.tile_height_in_mbs;
+        }
+        row_starts.push(h_mbs * 16);
+
+        if let Some(qm) = &cfg.q_matrix {
+            for c in 0..cfg.chroma.num_comps() {
+                if qm[c].contains(&0) {
+                    return Err(Error::Input("q_matrix entries must be non-zero (1..=255)".into()));
+                }
+            }
+        }
+
+        let hdr = FrameHeader {
+            profile_idc: cfg.profile.idc(),
+            level_idc: cfg.level_idc,
+            band_idc: cfg.band_idc.min(3),
+            width: cfg.width,
+            height: cfg.height,
+            chroma: cfg.chroma,
+            bit_depth: cfg.bit_depth,
+            capture_time_distance: 0,
+            color_description_present: cfg.color_description_present,
+            color: cfg.color,
+            use_q_matrix: cfg.q_matrix.is_some(),
+            q_matrix: cfg.q_matrix.unwrap_or([[DEFAULT_Q_MATRIX_VAL; 64]; 4]),
+            tile_width_in_mbs: cfg.tile_width_in_mbs,
+            tile_height_in_mbs: cfg.tile_height_in_mbs,
+            tile_cols,
+            tile_rows,
+            col_starts,
+            row_starts,
+            tile_sizes_in_fh: None,
+            header_bytes: 0,
+        };
+
+        Ok(Self { cfg, hdr })
+    }
+
+    pub fn config(&self) -> &EncoderConfig {
+        &self.cfg
+    }
+
+    pub fn target_frame_bytes(&self) -> u32 {
+        self.cfg.target_frame_bytes
+    }
+
+    /// Encode one frame into an APV Access Unit (`b"aPv1"...`), suitable for MP4/MOV (`apv1`) or MKV (`V_APV`).
+    pub fn encode(&mut self, frame: &Frame) -> Result<Vec<u8>> {
+        if frame.width != self.cfg.width || frame.height != self.cfg.height {
+            return Err(Error::Input(format!("frame is {}x{}, encoder is {}x{}", frame.width, frame.height, self.cfg.width, self.cfg.height)));
+        }
+        if frame.chroma != self.cfg.chroma {
+            return Err(Error::Input(format!("frame chroma {:?} does not match encoder {:?}", frame.chroma, self.cfg.chroma)));
+        }
+        if !(8..=16).contains(&frame.bit_depth) {
+            return Err(Error::Input(format!("unsupported input bit depth {}", frame.bit_depth)));
+        }
+        let n_luma = (frame.width as usize) * (frame.height as usize);
+        let n_chroma = (frame.chroma_width() as usize) * (frame.chroma_height() as usize);
+        if frame.y.len() != n_luma || frame.cb.len() != n_chroma || frame.cr.len() != n_chroma {
+            return Err(Error::Input("plane buffer lengths do not match frame geometry".into()));
+        }
+        if self.cfg.chroma == ChromaFormat::Yuv4444 && frame.alpha.as_ref().is_none_or(|a| a.len() != n_luma) {
+            return Err(Error::Input("4:4:4:4 profile requires an alpha plane of width * height samples".into()));
+        }
+
+        let prepared = self.prepare_tiles(frame);
+        let max_qp = (51 + self.hdr.qp_bd_offset()) as u8;
+        let qp = match self.cfg.qp {
+            Some(q) => q.min(max_qp),
+            None => self.select_qp(&prepared, max_qp),
+        };
+
+        let encoded_tiles: Vec<Vec<u8>> = {
+            #[cfg(feature = "threads")]
+            {
+                use rayon::prelude::*;
+                prepared.par_iter().map(|t| self.encode_tile(t, qp)).collect()
+            }
+            #[cfg(not(feature = "threads"))]
+            {
+                prepared.iter().map(|t| self.encode_tile(t, qp)).collect()
+            }
+        };
+
+        let mut hdr = self.hdr.clone();
+        hdr.color = if !self.cfg.color_description_present {
+            ColorInfo::default()
+        } else if frame.color != ColorInfo::BT709 {
+            frame.color
+        } else {
+            self.cfg.color
+        };
+        if self.cfg.write_tile_sizes_in_fh {
+            hdr.tile_sizes_in_fh = Some(encoded_tiles.iter().map(|t| t.len() as u32).collect());
+        }
+        let fh_bytes = write_frame_header(&hdr);
+
+        let tiles_total_bytes: usize = encoded_tiles.iter().map(|t| 4 + t.len()).sum();
+        let pbu_size = 4 + fh_bytes.len() + tiles_total_bytes;
+
+        let mdcv = frame.mastering_display.as_ref().or(self.cfg.mastering_display.as_ref());
+        let cll = frame.content_light.as_ref().or(self.cfg.content_light.as_ref());
+        let meta_pbu = write_metadata_pbu(1, mdcv, cll);
+        let meta_total = meta_pbu.as_ref().map_or(0, |m| 4 + m.len());
+
+        let mut au = Vec::with_capacity(4 + 4 + pbu_size + meta_total);
+        au.extend_from_slice(b"aPv1");
+        // Primary frame PBU (pbu_type = 1, group_id = 1)
+        au.extend_from_slice(&(pbu_size as u32).to_be_bytes());
+        au.push(PBU_PRIMARY_FRAME);
+        au.extend_from_slice(&1u16.to_be_bytes());
+        au.push(0); // reserved_zero_8bits
+        au.extend_from_slice(&fh_bytes);
+        for t in &encoded_tiles {
+            au.extend_from_slice(&(t.len() as u32).to_be_bytes());
+            au.extend_from_slice(t);
+        }
+        if let Some(m) = meta_pbu {
+            au.extend_from_slice(&(m.len() as u32).to_be_bytes());
+            au.extend_from_slice(&m);
+        }
+        Ok(au)
+    }
+
+    /// Encode one frame as a `raw_bitstream_access_unit()` (prefixed by `au_size: u32 BE`, RFC 9924 Appendix A).
+    pub fn encode_raw_au(&mut self, frame: &Frame) -> Result<Vec<u8>> {
+        let au = self.encode(frame)?;
+        let mut raw = Vec::with_capacity(4 + au.len());
+        raw.extend_from_slice(&(au.len() as u32).to_be_bytes());
+        raw.extend_from_slice(&au);
+        Ok(raw)
+    }
+
+    /// Build the `APVDecoderConfigurationRecord` payload (for ISOBMFF `apvC` or Matroska CodecPrivate).
+    pub fn decoder_config_record(&self) -> Vec<u8> {
+        let mut v = Vec::with_capacity(24);
+        v.push(1); // configurationVersion = 1
+        v.push(1); // number_of_configuration_entry = 1
+        v.push(PBU_PRIMARY_FRAME); // pbu_type[0] = 1
+        v.push(1); // number_of_frame_info[0] = 1
+        let flags = if self.cfg.color_description_present { 0x02 } else { 0x00 } | 0x01; // capture_time_distance_ignored = 1
+        v.push(flags);
+        v.push(self.hdr.profile_idc);
+        v.push(self.hdr.level_idc);
+        v.push(self.hdr.band_idc);
+        v.extend_from_slice(&self.hdr.width.to_be_bytes());
+        v.extend_from_slice(&self.hdr.height.to_be_bytes());
+        v.push((self.hdr.chroma.idc() << 4) | (self.hdr.bit_depth.saturating_sub(8) & 0x0F));
+        v.push(0); // capture_time_distance = 0
+        if self.cfg.color_description_present {
+            v.push(self.cfg.color.primaries);
+            v.push(self.cfg.color.transfer);
+            v.push(self.cfg.color.matrix);
+            v.push(if self.cfg.color.full_range { 0x80 } else { 0x00 });
+        }
+        v
+    }
+
+    fn prepare_tiles(&self, frame: &Frame) -> Vec<PreparedTile> {
+        let num_tiles = self.hdr.num_tiles();
+        let prepare_one = |tile_idx: usize| -> PreparedTile {
+            let tx = tile_idx % (self.hdr.tile_cols as usize);
+            let ty = tile_idx / (self.hdr.tile_cols as usize);
+            let x0 = self.hdr.col_starts[tx];
+            let x1 = self.hdr.col_starts[tx + 1];
+            let y0 = self.hdr.row_starts[ty];
+            let y1 = self.hdr.row_starts[ty + 1];
+            let num_mb_cols = (x1 - x0) / 16;
+            let num_mb_rows = (y1 - y0) / 16;
+            let num_comps = self.hdr.chroma.num_comps();
+            let mut comps = Vec::with_capacity(num_comps);
+
+            for c in 0..num_comps {
+                let (plane, pw, ph, sub_w, sub_h) = match c {
+                    0 => (frame.y.as_slice(), frame.width as usize, frame.height as usize, 1u32, 1u32),
+                    1 => (
+                        frame.cb.as_slice(),
+                        frame.chroma_width() as usize,
+                        frame.chroma_height() as usize,
+                        self.hdr.chroma.sub_width_c(),
+                        self.hdr.chroma.sub_height_c(),
+                    ),
+                    2 => (
+                        frame.cr.as_slice(),
+                        frame.chroma_width() as usize,
+                        frame.chroma_height() as usize,
+                        self.hdr.chroma.sub_width_c(),
+                        self.hdr.chroma.sub_height_c(),
+                    ),
+                    _ => (frame.alpha.as_deref().unwrap_or(&[]), frame.width as usize, frame.height as usize, 1u32, 1u32),
+                };
+                let blk_w = (16 / sub_w) as usize;
+                let blk_h = (16 / sub_h) as usize;
+                let blocks_x = blk_w / 8;
+                let blocks_y = blk_h / 8;
+                let total_blocks = (num_mb_cols as usize) * (num_mb_rows as usize) * blocks_x * blocks_y;
+                let mut blocks = Vec::with_capacity(total_blocks);
+
+                let coded_depth = self.hdr.bit_depth;
+                let in_depth = frame.bit_depth;
+
+                for mb_y in 0..num_mb_rows {
+                    for mb_x in 0..num_mb_cols {
+                        let x_mb_c = ((x0 + mb_x * 16) / sub_w) as usize;
+                        let y_mb_c = ((y0 + mb_y * 16) / sub_h) as usize;
+                        for by in 0..blocks_y {
+                            for bx in 0..blocks_x {
+                                let bx0 = x_mb_c + bx * 8;
+                                let by0 = y_mb_c + by * 8;
+                                let mut samples = [0u16; 64];
+                                for ry in 0..8 {
+                                    let sy = (by0 + ry).min(ph.saturating_sub(1));
+                                    for rx in 0..8 {
+                                        let sx = (bx0 + rx).min(pw.saturating_sub(1));
+                                        let v = plane[sy * pw + sx];
+                                        samples[ry * 8 + rx] = scale_sample(v, in_depth, coded_depth);
+                                    }
+                                }
+                                blocks.push(fdct8x8(&samples, coded_depth));
+                            }
+                        }
+                    }
+                }
+                comps.push(PreparedTileComp { blocks });
+            }
+            PreparedTile { tile_idx, comps }
+        };
+
+        #[cfg(feature = "threads")]
+        {
+            use rayon::prelude::*;
+            (0..num_tiles).into_par_iter().map(prepare_one).collect()
+        }
+        #[cfg(not(feature = "threads"))]
+        {
+            (0..num_tiles).map(prepare_one).collect()
+        }
+    }
+
+    fn select_qp(&self, tiles: &[PreparedTile], max_qp: u8) -> u8 {
+        let target_bytes = (self.cfg.target_frame_bytes as usize).max(64);
+        let frame_bytes_at = |qp: u8| -> usize {
+            let tile_bytes = |t: &PreparedTile| -> usize {
+                let num_comps = t.comps.len();
+                let mut sz = 4 + (5 + 5 * num_comps);
+                for (c, comp) in t.comps.iter().enumerate() {
+                    let bits = self.estimate_comp_bits(comp, c, qp);
+                    sz += (bits.div_ceil(8) as usize).max(1);
+                }
+                sz
+            };
+            #[cfg(feature = "threads")]
+            let sum: usize = {
+                use rayon::prelude::*;
+                tiles.par_iter().map(tile_bytes).sum()
+            };
+            #[cfg(not(feature = "threads"))]
+            let sum: usize = tiles.iter().map(tile_bytes).sum();
+            24 + sum
+        };
+
+        let mut lo = 0u8;
+        let mut hi = max_qp;
+        if frame_bytes_at(0) <= target_bytes {
+            return 0;
+        }
+        while lo < hi {
+            let mid = lo + (hi - lo) / 2;
+            if frame_bytes_at(mid) <= target_bytes {
+                hi = mid;
+            } else {
+                lo = mid + 1;
+            }
+        }
+        lo
+    }
+
+    fn estimate_comp_bits(&self, comp: &PreparedTileComp, c: usize, qp: u8) -> u64 {
+        let qm = &self.hdr.q_matrix[c];
+        let depth = self.hdr.bit_depth;
+        let mut prev_dc: i32 = 0;
+        let mut prev_dc_diff: u32 = 20;
+        let mut prev_1st_ac_level: u32 = 0;
+        let mut bits: u64 = 0;
+
+        for f_blk in &comp.blocks {
+            let coeff = quantize8x8(f_blk, qm, qp, depth);
+            let dc = coeff[0] as i32;
+            let diff = dc - prev_dc;
+            let abs_dc_diff = diff.unsigned_abs();
+            let k_dc = (prev_dc_diff >> 1).min(5);
+            bits += vlc_bit_len(abs_dc_diff, k_dc) as u64;
+            if abs_dc_diff > 0 {
+                bits += 1;
+            }
+            prev_dc = dc;
+            prev_dc_diff = abs_dc_diff;
+
+            let mut scan_pos = 1usize;
+            let mut first_ac = true;
+            let mut prev_level = prev_1st_ac_level;
+            let mut prev_run = 0u32;
+
+            while scan_pos < 64 {
+                let mut run = 0u32;
+                while scan_pos + (run as usize) < 64 && coeff[ZIGZAG_8X8[scan_pos + (run as usize)] as usize] == 0 {
+                    run += 1;
+                }
+                let k_run = (prev_run >> 2).min(2);
+                bits += vlc_bit_len(run, k_run) as u64;
+                scan_pos += run as usize;
+                prev_run = run;
+                if scan_pos < 64 {
+                    let level = coeff[ZIGZAG_8X8[scan_pos] as usize];
+                    let abs_level = level.unsigned_abs() as u32;
+                    let k_lvl = (prev_level >> 2).min(4);
+                    bits += vlc_bit_len(abs_level - 1, k_lvl) as u64 + 1;
+                    scan_pos += 1;
+                    prev_level = abs_level;
+                    if first_ac {
+                        first_ac = false;
+                        prev_1st_ac_level = prev_level;
+                    }
+                }
+            }
+        }
+        bits
+    }
+
+    fn encode_tile(&self, tile: &PreparedTile, qp: u8) -> Vec<u8> {
+        let num_comps = tile.comps.len();
+        let mut comp_payloads: Vec<Vec<u8>> = Vec::with_capacity(num_comps);
+        let depth = self.hdr.bit_depth;
+
+        for (c, comp) in tile.comps.iter().enumerate() {
+            let qm = &self.hdr.q_matrix[c];
+            let mut w = BitWriter::new();
+            let mut prev_dc: i32 = 0;
+            let mut prev_dc_diff: u32 = 20;
+            let mut prev_1st_ac_level: u32 = 0;
+
+            for f_blk in &comp.blocks {
+                let coeff = quantize8x8(f_blk, qm, qp, depth);
+                let dc = coeff[0] as i32;
+                let diff = dc - prev_dc;
+                let abs_dc_diff = diff.unsigned_abs();
+                let k_dc = (prev_dc_diff >> 1).min(5);
+                write_vlc(&mut w, abs_dc_diff, k_dc);
+                if abs_dc_diff > 0 {
+                    w.write_bit(diff < 0);
+                }
+                prev_dc = dc;
+                prev_dc_diff = abs_dc_diff;
+
+                let mut scan_pos = 1usize;
+                let mut first_ac = true;
+                let mut prev_level = prev_1st_ac_level;
+                let mut prev_run = 0u32;
+
+                while scan_pos < 64 {
+                    let mut run = 0u32;
+                    while scan_pos + (run as usize) < 64 && coeff[ZIGZAG_8X8[scan_pos + (run as usize)] as usize] == 0 {
+                        run += 1;
+                    }
+                    let k_run = (prev_run >> 2).min(2);
+                    write_vlc(&mut w, run, k_run);
+                    scan_pos += run as usize;
+                    prev_run = run;
+                    if scan_pos < 64 {
+                        let level = coeff[ZIGZAG_8X8[scan_pos] as usize];
+                        let abs_level = level.unsigned_abs() as u32;
+                        let k_lvl = (prev_level >> 2).min(4);
+                        write_vlc(&mut w, abs_level - 1, k_lvl);
+                        w.write_bit(level < 0);
+                        scan_pos += 1;
+                        prev_level = abs_level;
+                        if first_ac {
+                            first_ac = false;
+                            prev_1st_ac_level = prev_level;
+                        }
+                    }
+                }
+            }
+            comp_payloads.push(w.finish());
+        }
+
+        // Write tile_header(tileIdx) (RFC 9924 §5.3.13)
+        let tile_header_size = (5 + 5 * num_comps) as u16;
+        let total_size = tile_header_size as usize + comp_payloads.iter().map(Vec::len).sum::<usize>();
+        let mut out = Vec::with_capacity(total_size);
+        out.extend_from_slice(&tile_header_size.to_be_bytes());
+        out.extend_from_slice(&(tile.tile_idx as u16).to_be_bytes());
+        for cp in &comp_payloads {
+            out.extend_from_slice(&(cp.len() as u32).to_be_bytes());
+        }
+        for _ in 0..num_comps {
+            out.push(qp);
+        }
+        out.push(0); // reserved_zero_8bits
+        for cp in comp_payloads {
+            out.extend_from_slice(&cp);
+        }
+        out
+    }
+}
+
+#[inline]
+fn scale_sample(v: u16, from_depth: u8, to_depth: u8) -> u16 {
+    let max_in = (1u32 << from_depth) - 1;
+    let v = (v as u32).min(max_in);
+    if to_depth == from_depth {
+        v as u16
+    } else if to_depth > from_depth {
+        let shift = (to_depth - from_depth) as u32;
+        ((v << shift) | (v >> ((from_depth as u32) - shift))) as u16
+    } else {
+        let shift = (from_depth - to_depth) as u32;
+        let round = 1u32 << (shift - 1);
+        let max_out = (1u32 << to_depth) - 1;
+        (((v + round) >> shift).min(max_out)) as u16
+    }
+}
@@ -0,0 +1,460 @@
+//! RFC 9924 §5.3 and §8 syntax structures: Access Unit, PBU, Frame Header, Tile Info, and Metadata.
+
+use filmcraft_bitstream::{BitReader, BitWriter};
+
+use crate::tables::DEFAULT_Q_MATRIX_VAL;
+use crate::{ChromaFormat, ColorInfo, ContentLightLevel, Error, MasteringDisplay, Result};
+
+/// Four-character signature `'aPv1'` (`0x61507631`) at the start of every APV Access Unit (RFC 9924 §5.3.1).
+pub const AU_SIGNATURE: [u8; 4] = *b"aPv1";
+
+/// Primitive Bitstream Unit (PBU) types (RFC 9924 §5.3.3 Table 3).
+pub const PBU_PRIMARY_FRAME: u8 = 1;
+pub const PBU_NON_PRIMARY_FRAME: u8 = 2;
+pub const PBU_PREVIEW_FRAME: u8 = 25;
+pub const PBU_DEPTH_FRAME: u8 = 26;
+pub const PBU_ALPHA_FRAME: u8 = 27;
+pub const PBU_AU_INFO: u8 = 65;
+pub const PBU_METADATA: u8 = 66;
+pub const PBU_FILLER: u8 = 67;
+
+/// Maximum supported frame dimension in luma samples (guards against hostile allocations).
+pub const MAX_DIMENSION: u32 = 16384;
+
+/// Maximum tiles per axis (RFC 9924 §9.4.1 specifies 20; we allow up to 64 for robustness).
+pub const MAX_TILE_DIM: u32 = 64;
+
+/// Parsed `frame_header()` and derived tile geometry (RFC 9924 §5.3.5–5.3.8).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FrameHeader {
+    pub profile_idc: u8,
+    pub level_idc: u8,
+    pub band_idc: u8,
+    pub width: u32,
+    pub height: u32,
+    pub chroma: ChromaFormat,
+    pub bit_depth: u8,
+    pub capture_time_distance: u8,
+    pub color_description_present: bool,
+    pub color: ColorInfo,
+    pub use_q_matrix: bool,
+    /// Per-component 8x8 quantization matrix in raster order (`y * 8 + x`).
+    pub q_matrix: [[u8; 64]; 4],
+    pub tile_width_in_mbs: u32,
+    pub tile_height_in_mbs: u32,
+    pub tile_cols: u32,
+    pub tile_rows: u32,
+    /// Tile column start positions in luma samples (`len == tile_cols + 1`).
+    pub col_starts: Vec<u32>,
+    /// Tile row start positions in luma samples (`len == tile_rows + 1`).
+    pub row_starts: Vec<u32>,
+    pub tile_sizes_in_fh: Option<Vec<u32>>,
+    /// Byte offset within the PBU payload where `frame_header()` ends (start of the tile loop).
+    pub header_bytes: usize,
+}
+
+impl FrameHeader {
+    pub fn frame_width_in_mbs(&self) -> u32 {
+        self.width.div_ceil(16)
+    }
+
+    pub fn frame_height_in_mbs(&self) -> u32 {
+        self.height.div_ceil(16)
+    }
+
+    pub fn num_tiles(&self) -> usize {
+        (self.tile_cols as usize) * (self.tile_rows as usize)
+    }
+
+    pub fn qp_bd_offset(&self) -> i32 {
+        (self.bit_depth.saturating_sub(8) as i32) * 6
+    }
+}
+
+/// A parsed PBU slice inside an Access Unit.
+#[derive(Debug, Clone)]
+pub struct PbuSlice<'a> {
+    pub pbu_type: u8,
+    pub group_id: u16,
+    /// Payload after the 4-byte `pbu_header()`.
+    pub payload: &'a [u8],
+}
+
+/// Unwrap an Access Unit byte slice: accepts either a direct `access_unit` starting with `'aPv1'`
+/// or a `raw_bitstream_access_unit` prefixed with a 32-bit big-endian `au_size` (RFC 9924 Appendix A).
+pub fn unwrap_au(data: &[u8]) -> Result<&[u8]> {
+    if data.len() < 4 {
+        return Err(Error::Truncated);
+    }
+    if data[..4] == AU_SIGNATURE {
+        return Ok(data);
+    }
+    if data.len() >= 8 && data[4..8] == AU_SIGNATURE {
+        let au_size = u32::from_be_bytes([data[0], data[1], data[2], data[3]]) as usize;
+        if au_size < 4 || au_size == 0xFFFF_FFFF {
+            return Err(Error::Invalid("invalid au_size in raw bitstream"));
+        }
+        let end = 4usize.checked_add(au_size).ok_or(Error::Truncated)?;
+        return data.get(4..end).ok_or(Error::Truncated);
+    }
+    Err(Error::Invalid("missing aPv1 access unit signature"))
+}
+
+/// Split a raw `.apv` bitstream (`raw_bitstream_access_unit()` sequence per RFC 9924 Appendix A)
+/// into individual Access Unit slices (each starting with `'aPv1'`).
+pub fn split_raw_bitstream(mut data: &[u8]) -> Result<Vec<&[u8]>> {
+    if data.is_empty() {
+        return Err(Error::Truncated);
+    }
+    // If the buffer starts directly with 'aPv1', treat the entire buffer as a single AU.
+    if data.len() >= 4 && data[..4] == AU_SIGNATURE {
+        return Ok(vec![data]);
+    }
+    let mut aus = Vec::new();
+    while !data.is_empty() {
+        if data.len() < 8 {
+            return Err(Error::Truncated);
+        }
+        let au_size = u32::from_be_bytes([data[0], data[1], data[2], data[3]]) as usize;
+        if au_size < 4 || au_size == 0xFFFF_FFFF {
+            return Err(Error::Invalid("invalid au_size in raw bitstream"));
+        }
+        let end = 4usize.checked_add(au_size).ok_or(Error::Truncated)?;
+        let au = data.get(4..end).ok_or(Error::Truncated)?;
+        if au[..4] != AU_SIGNATURE {
+            return Err(Error::Invalid("missing aPv1 signature in raw bitstream AU"));
+        }
+        aus.push(au);
+        data = &data[end..];
+    }
+    if aus.is_empty() {
+        return Err(Error::Truncated);
+    }
+    Ok(aus)
+}
+
+/// Parse the PBU list of a single Access Unit (RFC 9924 §5.3.1–5.3.3).
+/// PBUs with `reserved_zero_8bits > 0` are ignored as required by RFC 9924 §5.3.3.
+pub fn parse_au_pbus(data: &[u8]) -> Result<Vec<PbuSlice<'_>>> {
+    let au = unwrap_au(data)?;
+    if au.len() < 8 {
+        return Err(Error::Truncated);
+    }
+    let mut pos = 4usize;
+    let mut pbus = Vec::new();
+    while pos < au.len() {
+        let sz_bytes = au.get(pos..pos + 4).ok_or(Error::Truncated)?;
+        let pbu_size = u32::from_be_bytes([sz_bytes[0], sz_bytes[1], sz_bytes[2], sz_bytes[3]]) as usize;
+        if pbu_size == 0 || pbu_size == 0xFFFF_FFFF {
+            return Err(Error::Invalid("invalid pbu_size"));
+        }
+        if pbu_size < 4 {
+            return Err(Error::Truncated);
+        }
+        pos += 4;
+        let pbu_end = pos.checked_add(pbu_size).ok_or(Error::Truncated)?;
+        let pbu = au.get(pos..pbu_end).ok_or(Error::Truncated)?;
+        pos = pbu_end;
+
+        let pbu_type = pbu[0];
+        let group_id = u16::from_be_bytes([pbu[1], pbu[2]]);
+        let reserved_zero_8bits = pbu[3];
+        if reserved_zero_8bits > 0 {
+            // RFC 9924 §5.3.3: Decoders MUST ignore PBU with reserved_zero_8bits > 0.
+            continue;
+        }
+        if group_id == 0xFFFF || (group_id == 0 && pbu_type <= 64) {
+            return Err(Error::Invalid("invalid PBU group_id"));
+        }
+        pbus.push(PbuSlice { pbu_type, group_id, payload: &pbu[4..] });
+    }
+    Ok(pbus)
+}
+
+/// Read `byte_alignment()` and verify all alignment bits are zero (RFC 9924 §5.3.17).
+pub fn read_byte_alignment(r: &mut BitReader) -> Result<()> {
+    while !r.is_byte_aligned() {
+        let bit = r.read_bit().map_err(|_| Error::Truncated)?;
+        if bit {
+            return Err(Error::Invalid("non-zero alignment bit"));
+        }
+    }
+    Ok(())
+}
+
+/// Parse `frame_header()` from the payload of a frame PBU (after `pbu_header()`), per RFC 9924 §5.3.5–5.3.8.
+/// Returns `Ok(None)` if any `reserved_zero_*` field is non-zero (RFC 9924 §5.3.5 requires ignoring the PBU).
+pub fn parse_frame_header(payload: &[u8]) -> Result<Option<FrameHeader>> {
+    let mut r = BitReader::new(payload);
+
+    // frame_info() (RFC 9924 §5.3.6)
+    let profile_idc = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+    let level_idc = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+    let band_idc = r.read_bits(3).map_err(|_| Error::Truncated)? as u8;
+    let reserved_zero_5bits = r.read_bits(5).map_err(|_| Error::Truncated)? as u8;
+    let width = r.read_bits(24).map_err(|_| Error::Truncated)?;
+    let height = r.read_bits(24).map_err(|_| Error::Truncated)?;
+    let chroma_format_idc = r.read_bits(4).map_err(|_| Error::Truncated)? as u8;
+    let bit_depth_minus8 = r.read_bits(4).map_err(|_| Error::Truncated)? as u8;
+    let capture_time_distance = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+    let fi_reserved_8 = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+
+    // frame_header() (RFC 9924 §5.3.5)
+    let fh_reserved_8_a = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+    if reserved_zero_5bits > 0 || fi_reserved_8 > 0 || fh_reserved_8_a > 0 {
+        return Ok(None);
+    }
+
+    if width == 0 || height == 0 || width > MAX_DIMENSION || height > MAX_DIMENSION {
+        return Err(Error::Invalid("unsupported frame dimensions"));
+    }
+    let chroma = ChromaFormat::from_idc(chroma_format_idc).ok_or(Error::Invalid("invalid chroma_format_idc"))?;
+    if chroma == ChromaFormat::Yuv422 && !width.is_multiple_of(2) {
+        return Err(Error::Invalid("4:2:2 frame_width must be even"));
+    }
+    if !(2..=8).contains(&bit_depth_minus8) {
+        return Err(Error::Invalid("bit_depth_minus8 out of range 2..=8"));
+    }
+    let bit_depth = bit_depth_minus8 + 8;
+
+    let color_description_present = r.read_bit().map_err(|_| Error::Truncated)?;
+    let color = if color_description_present {
+        let primaries = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+        let transfer = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+        let matrix = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+        let full_range = r.read_bit().map_err(|_| Error::Truncated)?;
+        ColorInfo { primaries, transfer, matrix, full_range }
+    } else {
+        ColorInfo::default()
+    };
+
+    let use_q_matrix = r.read_bit().map_err(|_| Error::Truncated)?;
+    let mut q_matrix = [[DEFAULT_Q_MATRIX_VAL; 64]; 4];
+    if use_q_matrix {
+        for c in 0..chroma.num_comps() {
+            for y in 0..8 {
+                for x in 0..8 {
+                    let q = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+                    if q == 0 {
+                        return Err(Error::Invalid("q_matrix entry 0 is reserved"));
+                    }
+                    q_matrix[c][y * 8 + x] = q;
+                }
+            }
+        }
+    }
+
+    // tile_info() (RFC 9924 §5.3.8)
+    let tile_width_in_mbs = r.read_bits(20).map_err(|_| Error::Truncated)?;
+    let tile_height_in_mbs = r.read_bits(20).map_err(|_| Error::Truncated)?;
+    if tile_width_in_mbs == 0 || tile_height_in_mbs == 0 {
+        return Err(Error::Invalid("tile dimensions in MBs must be non-zero"));
+    }
+
+    let w_mbs = width.div_ceil(16);
+    let h_mbs = height.div_ceil(16);
+    let tile_cols = w_mbs.div_ceil(tile_width_in_mbs);
+    let tile_rows = h_mbs.div_ceil(tile_height_in_mbs);
+    if tile_cols == 0 || tile_rows == 0 || tile_cols > MAX_TILE_DIM || tile_rows > MAX_TILE_DIM {
+        return Err(Error::Invalid("too many tiles in frame"));
+    }
+
+    let mut col_starts = Vec::with_capacity(tile_cols as usize + 1);
+    let mut start_mb = 0u32;
+    while start_mb < w_mbs {
+        col_starts.push(start_mb * 16);
+        start_mb = start_mb.saturating_add(tile_width_in_mbs);
+    }
+    col_starts.push(w_mbs * 16);
+
+    let mut row_starts = Vec::with_capacity(tile_rows as usize + 1);
+    let mut start_mb = 0u32;
+    while start_mb < h_mbs {
+        row_starts.push(start_mb * 16);
+        start_mb = start_mb.saturating_add(tile_height_in_mbs);
+    }
+    row_starts.push(h_mbs * 16);
+
+    let num_tiles = (tile_cols as usize) * (tile_rows as usize);
+    let tile_size_present_in_fh = r.read_bit().map_err(|_| Error::Truncated)?;
+    let tile_sizes_in_fh = if tile_size_present_in_fh {
+        let mut sizes = Vec::with_capacity(num_tiles);
+        for _ in 0..num_tiles {
+            let sz = r.read_bits(32).map_err(|_| Error::Truncated)?;
+            if sz == 0 {
+                return Err(Error::Invalid("tile_size_in_fh cannot be 0"));
+            }
+            sizes.push(sz);
+        }
+        Some(sizes)
+    } else {
+        None
+    };
+
+    let fh_reserved_8_b = r.read_bits(8).map_err(|_| Error::Truncated)? as u8;
+    if fh_reserved_8_b > 0 {
+        return Ok(None);
+    }
+    read_byte_alignment(&mut r)?;
+
+    Ok(Some(FrameHeader {
+        profile_idc,
+        level_idc,
+        band_idc,
+        width,
+        height,
+        chroma,
+        bit_depth,
+        capture_time_distance,
+        color_description_present,
+        color,
+        use_q_matrix,
+        q_matrix,
+        tile_width_in_mbs,
+        tile_height_in_mbs,
+        tile_cols,
+        tile_rows,
+        col_starts,
+        row_starts,
+        tile_sizes_in_fh,
+        header_bytes: r.byte_pos(),
+    }))
+}
+
+/// Write `frame_header()` to a byte vector (RFC 9924 §5.3.5–5.3.8).
+pub fn write_frame_header(h: &FrameHeader) -> Vec<u8> {
+    let mut w = BitWriter::new();
+    // frame_info()
+    w.write_bits(h.profile_idc as u32, 8);
+    w.write_bits(h.level_idc as u32, 8);
+    w.write_bits((h.band_idc & 7) as u32, 3);
+    w.write_bits(0, 5); // reserved_zero_5bits
+    w.write_bits(h.width, 24);
+    w.write_bits(h.height, 24);
+    w.write_bits(h.chroma.idc() as u32, 4);
+    w.write_bits(h.bit_depth.saturating_sub(8) as u32, 4);
+    w.write_bits(h.capture_time_distance as u32, 8);
+    w.write_bits(0, 8); // reserved_zero_8bits
+
+    // frame_header()
+    w.write_bits(0, 8); // reserved_zero_8bits
+    w.write_bit(h.color_description_present);
+    if h.color_description_present {
+        w.write_bits(h.color.primaries as u32, 8);
+        w.write_bits(h.color.transfer as u32, 8);
+        w.write_bits(h.color.matrix as u32, 8);
+        w.write_bit(h.color.full_range);
+    }
+    w.write_bit(h.use_q_matrix);
+    if h.use_q_matrix {
+        for c in 0..h.chroma.num_comps() {
+            for y in 0..8 {
+                for x in 0..8 {
+                    w.write_bits(h.q_matrix[c][y * 8 + x].max(1) as u32, 8);
+                }
+            }
+        }
+    }
+    // tile_info()
+    w.write_bits(h.tile_width_in_mbs, 20);
+    w.write_bits(h.tile_height_in_mbs, 20);
+    if let Some(sizes) = &h.tile_sizes_in_fh {
+        w.write_bit(true);
+        for &sz in sizes {
+            w.write_bits(sz, 32);
+        }
+    } else {
+        w.write_bit(false);
+    }
+    w.write_bits(0, 8); // reserved_zero_8bits
+    w.finish()
+}
+
+/// Parse a `metadata()` PBU payload (after `pbu_header()`), extracting MDCV (`payloadType == 5`)
+/// and CLL (`payloadType == 6`) if present (RFC 9924 §5.3.10 & §8).
+pub fn parse_metadata_pbu(payload: &[u8], mdcv: &mut Option<MasteringDisplay>, cll: &mut Option<ContentLightLevel>) -> Result<()> {
+    if payload.len() < 4 {
+        return Err(Error::Truncated);
+    }
+    let metadata_size = u32::from_be_bytes([payload[0], payload[1], payload[2], payload[3]]) as usize;
+    let body = payload.get(4..4usize.checked_add(metadata_size).ok_or(Error::Truncated)?).ok_or(Error::Truncated)?;
+    let mut pos = 0usize;
+    while pos < body.len() {
+        let mut payload_type = 0u32;
+        while *body.get(pos).ok_or(Error::Truncated)? == 0xFF {
+            payload_type = payload_type.checked_add(255).ok_or(Error::Invalid("metadata payloadType overflow"))?;
+            pos += 1;
+        }
+        payload_type = payload_type.checked_add(*body.get(pos).ok_or(Error::Truncated)? as u32).ok_or(Error::Invalid("metadata payloadType overflow"))?;
+        pos += 1;
+
+        let mut payload_size = 0usize;
+        while *body.get(pos).ok_or(Error::Truncated)? == 0xFF {
+            payload_size = payload_size.checked_add(255).ok_or(Error::Invalid("metadata payloadSize overflow"))?;
+            pos += 1;
+        }
+        payload_size = payload_size.checked_add(*body.get(pos).ok_or(Error::Truncated)? as usize).ok_or(Error::Invalid("metadata payloadSize overflow"))?;
+        pos += 1;
+
+        let end = pos.checked_add(payload_size).ok_or(Error::Truncated)?;
+        let item = body.get(pos..end).ok_or(Error::Truncated)?;
+        pos = end;
+
+        match payload_type {
+            5 if item.len() >= 24 => {
+                let u16_at = |i: usize| u16::from_be_bytes([item[i], item[i + 1]]);
+                let u32_at = |i: usize| u32::from_be_bytes([item[i], item[i + 1], item[i + 2], item[i + 3]]);
+                *mdcv = Some(MasteringDisplay {
+                    primaries: [(u16_at(0), u16_at(2)), (u16_at(4), u16_at(6)), (u16_at(8), u16_at(10))],
+                    white_point: (u16_at(12), u16_at(14)),
+                    max_luminance: u32_at(16),
+                    min_luminance: u32_at(20),
+                });
+            }
+            6 if item.len() >= 4 => {
+                *cll = Some(ContentLightLevel { max_cll: u16::from_be_bytes([item[0], item[1]]), max_fall: u16::from_be_bytes([item[2], item[3]]) });
+            }
+            // Filler metadata (§8.2.1): must be 0xFF bytes
+            10 if item.iter().any(|&b| b != 0xFF) => {
+                return Err(Error::Invalid("non-0xFF byte in filler metadata"));
+            }
+            _ => {
+                // RFC 9924 §10: A decoder MUST NOT try to process metadata whose type is not recognized.
+            }
+        }
+    }
+    Ok(())
+}
+
+/// Build a `metadata()` PBU (including its 4-byte `pbu_header`) carrying MDCV and/or CLL metadata.
+pub fn write_metadata_pbu(group_id: u16, mdcv: Option<&MasteringDisplay>, cll: Option<&ContentLightLevel>) -> Option<Vec<u8>> {
+    if mdcv.is_none() && cll.is_none() {
+        return None;
+    }
+    let mut body = Vec::new();
+    if let Some(m) = mdcv {
+        body.push(5); // payloadType = 5 (MDCV)
+        body.push(24); // payloadSize = 24
+        for &(x, y) in &m.primaries {
+            body.extend_from_slice(&x.to_be_bytes());
+            body.extend_from_slice(&y.to_be_bytes());
+        }
+        body.extend_from_slice(&m.white_point.0.to_be_bytes());
+        body.extend_from_slice(&m.white_point.1.to_be_bytes());
+        body.extend_from_slice(&m.max_luminance.to_be_bytes());
+        body.extend_from_slice(&m.min_luminance.to_be_bytes());
+    }
+    if let Some(c) = cll {
+        body.push(6); // payloadType = 6 (CLL)
+        body.push(4); // payloadSize = 4
+        body.extend_from_slice(&c.max_cll.to_be_bytes());
+        body.extend_from_slice(&c.max_fall.to_be_bytes());
+    }
+    let mut pbu = Vec::with_capacity(8 + body.len());
+    pbu.push(PBU_METADATA);
+    pbu.extend_from_slice(&group_id.to_be_bytes());
+    pbu.push(0); // reserved_zero_8bits
+    pbu.extend_from_slice(&(body.len() as u32).to_be_bytes());
+    pbu.extend_from_slice(&body);
+    Some(pbu)
+}
@@ -0,0 +1,329 @@
+//! Clean-room Advanced Professional Video (APV) codec, implemented strictly from IETF RFC 9924
+//! (February 2026).
+//!
+//! - **Decoder** ([`decode_frame`], [`decode_frame_with`], [`decode_frame_into`], [`probe`]):
+//!   every profile in RFC 9924 §9 (`422-10`, `422-12`, `444-10`, `444-12`, `4444-10`, `4444-12`,
+//!   `400-10`) at 10–16 bits per sample, custom quantization matrices, multi-tile parallel decoding
+//!   (behind the `threads` feature), 4:4:4:4 and auxiliary alpha PBU (`pbu_type == 27`) support,
+//!   and HDR static metadata (`MDCV` and `CLL`, RFC 9924 §8).
+//! - **Encoder** ([`Encoder`]): progressive intra frame encoding across all 7 profiles with fixed-QP
+//!   or frame-budget rate control, plus `APVDecoderConfigurationRecord` (`apvC`) generation.
+//!
+//! See the crate README for specification edition, accuracy against external oracles, and design notes.
+
+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
+pub mod dct;
+mod decode;
+mod encode;
+pub mod header;
+pub mod tables;
+
+pub use decode::{DecodeOptions, decode_frame, decode_frame_into, decode_frame_with, probe};
+pub use encode::{Encoder, EncoderConfig};
+pub use header::{AU_SIGNATURE, FrameHeader, split_raw_bitstream, unwrap_au};
+
+/// APV codec errors.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum Error {
+    #[error("truncated APV bitstream")]
+    Truncated,
+    #[error("invalid APV bitstream: {0}")]
+    Invalid(&'static str),
+    #[error("corrupt APV tile {0}")]
+    CorruptTile(usize),
+    #[error("invalid APV encoder input: {0}")]
+    Input(String),
+}
+
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Chroma format (`chroma_format_idc` in RFC 9924 §4.1 Table 2).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ChromaFormat {
+    /// `chroma_format_idc == 0`: 4:0:0 monochrome (1 component).
+    Monochrome,
+    /// `chroma_format_idc == 2`: 4:2:2 YCbCr (3 components, `SubWidthC = 2, SubHeightC = 1`).
+    Yuv422,
+    /// `chroma_format_idc == 3`: 4:4:4 YCbCr (3 components, `SubWidthC = 1, SubHeightC = 1`).
+    Yuv444,
+    /// `chroma_format_idc == 4`: 4:4:4:4 YCbCrA (4 components, `SubWidthC = 1, SubHeightC = 1`).
+    Yuv4444,
+}
+
+impl ChromaFormat {
+    pub fn from_idc(idc: u8) -> Option<Self> {
+        match idc {
+            0 => Some(Self::Monochrome),
+            2 => Some(Self::Yuv422),
+            3 => Some(Self::Yuv444),
+            4 => Some(Self::Yuv4444),
+            _ => None,
+        }
+    }
+
+    pub fn idc(self) -> u8 {
+        match self {
+            Self::Monochrome => 0,
+            Self::Yuv422 => 2,
+            Self::Yuv444 => 3,
+            Self::Yuv4444 => 4,
+        }
+    }
+
+    pub fn num_comps(self) -> usize {
+        match self {
+            Self::Monochrome => 1,
+            Self::Yuv422 | Self::Yuv444 => 3,
+            Self::Yuv4444 => 4,
+        }
+    }
+
+    pub fn sub_width_c(self) -> u32 {
+        match self {
+            Self::Yuv422 => 2,
+            _ => 1,
+        }
+    }
+
+    pub fn sub_height_c(self) -> u32 {
+        1
+    }
+
+    pub fn chroma_width(self, width: u32) -> u32 {
+        match self {
+            Self::Monochrome => 0,
+            Self::Yuv422 => width.div_ceil(2),
+            Self::Yuv444 | Self::Yuv4444 => width,
+        }
+    }
+
+    pub fn chroma_height(self, height: u32) -> u32 {
+        match self {
+            Self::Monochrome => 0,
+            _ => height,
+        }
+    }
+
+    pub fn has_alpha(self) -> bool {
+        self == Self::Yuv4444
+    }
+}
+
+/// APV profiles defined in RFC 9924 §9.3.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub enum Profile {
+    /// `profile_idc == 33`: 422-10 profile (4:2:2, 10-bit).
+    #[default]
+    P422_10,
+    /// `profile_idc == 44`: 422-12 profile (4:2:2, 10–12-bit).
+    P422_12,
+    /// `profile_idc == 55`: 444-10 profile (4:2:2..4:4:4, 10-bit).
+    P444_10,
+    /// `profile_idc == 66`: 444-12 profile (4:2:2..4:4:4, 10–12-bit).
+    P444_12,
+    /// `profile_idc == 77`: 4444-10 profile (4:2:2..4:4:4:4, 10-bit).
+    P4444_10,
+    /// `profile_idc == 88`: 4444-12 profile (4:2:2..4:4:4:4, 10–12-bit).
+    P4444_12,
+    /// `profile_idc == 99`: 400-10 profile (4:0:0, 10-bit).
+    P400_10,
+}
+
+impl Profile {
+    pub const ALL: [Profile; 7] =
+        [Profile::P422_10, Profile::P422_12, Profile::P444_10, Profile::P444_12, Profile::P4444_10, Profile::P4444_12, Profile::P400_10];
+
+    pub fn idc(self) -> u8 {
+        match self {
+            Self::P422_10 => 33,
+            Self::P422_12 => 44,
+            Self::P444_10 => 55,
+            Self::P444_12 => 66,
+            Self::P4444_10 => 77,
+            Self::P4444_12 => 88,
+            Self::P400_10 => 99,
+        }
+    }
+
+    pub fn from_idc(idc: u8) -> Option<Self> {
+        Self::ALL.into_iter().find(|p| p.idc() == idc)
+    }
+
+    pub fn name(self) -> &'static str {
+        match self {
+            Self::P422_10 => "APV 422-10",
+            Self::P422_12 => "APV 422-12",
+            Self::P444_10 => "APV 444-10",
+            Self::P444_12 => "APV 444-12",
+            Self::P4444_10 => "APV 4444-10",
+            Self::P4444_12 => "APV 4444-12",
+            Self::P400_10 => "APV 400-10",
+        }
+    }
+
+    pub fn short_name(self) -> &'static str {
+        match self {
+            Self::P422_10 => "422-10",
+            Self::P422_12 => "422-12",
+            Self::P444_10 => "444-10",
+            Self::P444_12 => "444-12",
+            Self::P4444_10 => "4444-10",
+            Self::P4444_12 => "4444-12",
+            Self::P400_10 => "400-10",
+        }
+    }
+
+    pub fn default_chroma(self) -> ChromaFormat {
+        match self {
+            Self::P422_10 | Self::P422_12 => ChromaFormat::Yuv422,
+            Self::P444_10 | Self::P444_12 => ChromaFormat::Yuv444,
+            Self::P4444_10 | Self::P4444_12 => ChromaFormat::Yuv4444,
+            Self::P400_10 => ChromaFormat::Monochrome,
+        }
+    }
+
+    pub fn default_bit_depth(self) -> u8 {
+        match self {
+            Self::P422_12 | Self::P444_12 | Self::P4444_12 => 12,
+            _ => 10,
+        }
+    }
+
+    /// Check whether `(chroma, bit_depth)` conforms to this profile per RFC 9924 §9.3.
+    pub fn supports(self, chroma: ChromaFormat, bit_depth: u8) -> bool {
+        let c = chroma.idc();
+        let b = bit_depth.saturating_sub(8);
+        match self {
+            Self::P422_10 => c == 2 && b == 2,
+            Self::P422_12 => c == 2 && (2..=4).contains(&b),
+            Self::P444_10 => (2..=3).contains(&c) && b == 2,
+            Self::P444_12 => (2..=3).contains(&c) && (2..=4).contains(&b),
+            Self::P4444_10 => (2..=4).contains(&c) && b == 2,
+            Self::P4444_12 => (2..=4).contains(&c) && (2..=4).contains(&b),
+            Self::P400_10 => c == 0 && b == 2,
+        }
+    }
+
+    /// Nominal target bytes per frame for `(width, height)`.
+    pub fn nominal_frame_bytes(self, width: u32, height: u32) -> u32 {
+        let bpp = match self {
+            Self::P400_10 => 1.5,
+            Self::P422_10 => 3.0,
+            Self::P422_12 => 3.8,
+            Self::P444_10 => 4.2,
+            Self::P444_12 => 5.0,
+            Self::P4444_10 => 5.2,
+            Self::P4444_12 => 6.2,
+        };
+        let bytes = ((width as f64) * (height as f64) * bpp / 8.0).round() as u32;
+        bytes.max(512)
+    }
+
+    /// Nominal data rate in Mbit/s at 1920x1080 29.97 fps.
+    pub fn nominal_mbps_1080p30(self) -> f64 {
+        (self.nominal_frame_bytes(1920, 1080) as f64) * 8.0 * 29.97 / 1e6
+    }
+}
+
+/// Human-readable profile name from `profile_idc` (e.g. `"APV 422-10"`).
+pub fn profile_name(profile_idc: u8) -> String {
+    Profile::from_idc(profile_idc).map(|p| p.name().to_string()).unwrap_or_else(|| format!("APV (profile {profile_idc})"))
+}
+
+/// Colour description from `frame_header()` (ITU-T H.273 code points, RFC 9924 §5.3.5).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct ColorInfo {
+    pub primaries: u8,
+    pub transfer: u8,
+    pub matrix: u8,
+    pub full_range: bool,
+}
+
+impl Default for ColorInfo {
+    /// Inferred values when `color_description_present_flag == 0` (RFC 9924 §5.3.5: 2, 2, 2, 0).
+    fn default() -> Self {
+        Self { primaries: 2, transfer: 2, matrix: 2, full_range: false }
+    }
+}
+
+impl ColorInfo {
+    pub const BT709: Self = Self { primaries: 1, transfer: 1, matrix: 1, full_range: false };
+    pub const BT2020_PQ: Self = Self { primaries: 9, transfer: 16, matrix: 9, full_range: false };
+    pub const BT2020_HLG: Self = Self { primaries: 9, transfer: 18, matrix: 9, full_range: false };
+}
+
+/// Mastering Display Color Volume metadata (`payloadType == 5`, RFC 9924 §8.2.3).
+///
+/// Chromaticities are in 0.16 fixed-point (1/65536), order `[R, G, B]`;
+/// `max_luminance` is 24.8 fixed-point cd/m²; `min_luminance` is 18.14 fixed-point cd/m².
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct MasteringDisplay {
+    pub primaries: [(u16, u16); 3],
+    pub white_point: (u16, u16),
+    pub max_luminance: u32,
+    pub min_luminance: u32,
+}
+
+/// Content Light-Level Information metadata (`payloadType == 6`, RFC 9924 §8.2.4).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct ContentLightLevel {
+    pub max_cll: u16,
+    pub max_fall: u16,
+}
+
+/// A decoded (or to-be-encoded) APV frame: planar `u16` samples, rows packed without padding.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Frame {
+    pub width: u32,
+    pub height: u32,
+    pub chroma: ChromaFormat,
+    /// Significant bits per sample (`10..=16`, or `8..=16` when rescaled via [`DecodeOptions`]).
+    pub bit_depth: u8,
+    pub y: Vec<u16>,
+    pub cb: Vec<u16>,
+    pub cr: Vec<u16>,
+    pub alpha: Option<Vec<u16>>,
+    pub color: ColorInfo,
+    pub profile_idc: u8,
+    pub level_idc: u8,
+    pub band_idc: u8,
+    pub mastering_display: Option<MasteringDisplay>,
+    pub content_light: Option<ContentLightLevel>,
+}
+
+impl Frame {
+    /// Allocate a black video-range frame.
+    pub fn new(width: u32, height: u32, chroma: ChromaFormat, bit_depth: u8, with_alpha: bool) -> Self {
+        let n = (width as usize) * (height as usize);
+        let cw = chroma.chroma_width(width) as usize;
+        let ch = chroma.chroma_height(height) as usize;
+        let cn = cw * ch;
+        let shift = bit_depth.saturating_sub(8) as u32;
+        let has_alpha = with_alpha || chroma == ChromaFormat::Yuv4444;
+        Self {
+            width,
+            height,
+            chroma,
+            bit_depth,
+            y: vec![(16u32 << shift) as u16; n],
+            cb: vec![(128u32 << shift) as u16; cn],
+            cr: vec![(128u32 << shift) as u16; cn],
+            alpha: has_alpha.then(|| vec![((1u32 << bit_depth) - 1) as u16; n]),
+            color: ColorInfo::BT709,
+            profile_idc: Profile::P422_10.idc(),
+            level_idc: 90,
+            band_idc: 2,
+            mastering_display: None,
+            content_light: None,
+        }
+    }
+
+    pub fn chroma_width(&self) -> u32 {
+        self.chroma.chroma_width(self.width)
+    }
+
+    pub fn chroma_height(&self) -> u32 {
+        self.chroma.chroma_height(self.height)
+    }
+}
@@ -0,0 +1,59 @@
+//! RFC 9924 tables: zig-zag scan, 8x8 transform matrix, quantization level scales, and level limits.
+
+/// 8x8 zig-zag scan order (`ScanOrder[sPos] = yC * 8 + xC`), derived from RFC 9924 §4.4.1 Figure 5.
+pub const ZIGZAG_8X8: [u8; 64] = [
+    0, 1, 8, 16, 9, 2, 3, 10, 17, 24, 32, 25, 18, 11, 4, 5, 12, 19, 26, 33, 40, 48, 41, 34, 27, 20, 13, 6, 7, 14, 21, 28, 35, 42, 49, 56, 57, 50, 43, 36, 29,
+    22, 15, 23, 30, 37, 44, 51, 58, 59, 52, 45, 38, 31, 39, 46, 53, 60, 61, 54, 47, 55, 62, 63,
+];
+
+/// 8x8 transform matrix (`transMatrix` in RFC 9924 §6.3.2.3 Figure 25).
+pub const TRANS_MATRIX: [[i32; 8]; 8] = [
+    [64, 64, 64, 64, 64, 64, 64, 64],
+    [89, 75, 50, 18, -18, -50, -75, -89],
+    [84, 35, -35, -84, -84, -35, 35, 84],
+    [75, -18, -89, -50, 50, 89, 18, -75],
+    [64, -64, -64, 64, 64, -64, -64, 64],
+    [50, -89, 18, 75, -75, -18, 89, -50],
+    [35, -84, 84, -35, -35, 84, -84, 35],
+    [18, -50, 75, -89, 89, -75, 50, -18],
+];
+
+/// Quantization scaling list `levelScale[k]` for `k = qP % 6` (RFC 9924 §6.3.1).
+pub const LEVEL_SCALE: [i32; 6] = [40, 45, 51, 57, 64, 71];
+
+/// Default flat quantization matrix value when `use_q_matrix == 0` (RFC 9924 §5.3.7).
+pub const DEFAULT_Q_MATRIX_VAL: u8 = 16;
+
+/// General level limits (`level_idc`, max luma sample rate, and max coded data rate in Mbit/s per band)
+/// from RFC 9924 §9.4.2 Table 4.
+pub const LEVEL_LIMITS: [(u8, u64, [u32; 4]); 14] = [
+    (30, 3_041_280, [8, 11, 15, 23]),
+    (33, 6_082_560, [16, 21, 30, 45]),
+    (60, 15_667_200, [39, 54, 76, 114]),
+    (63, 31_334_400, [78, 108, 152, 227]),
+    (90, 66_846_720, [114, 159, 222, 333]),
+    (93, 133_693_440, [227, 317, 444, 666]),
+    (120, 265_420_800, [455, 637, 892, 1_338]),
+    (123, 530_841_600, [910, 1_274, 1_784, 2_675]),
+    (150, 1_061_683_200, [1_820, 2_548, 3_567, 5_350]),
+    (153, 2_123_366_400, [3_639, 5_095, 7_133, 10_699]),
+    (180, 4_777_574_400, [7_278, 10_189, 14_265, 21_397]),
+    (183, 8_493_465_600, [14_556, 20_378, 28_529, 42_793]),
+    (210, 16_986_931_200, [29_111, 40_756, 57_058, 85_586]),
+    (213, 33_973_862_400, [58_222, 81_511, 114_115, 171_172]),
+];
+
+/// Choose the lowest conforming `(level_idc, band_idc)` for a luma sample rate and bitrate (in kbps).
+pub fn select_level_and_band(luma_samples_per_sec: u64, kbps: u32) -> (u8, u8) {
+    let mbps = kbps.div_ceil(1000);
+    for &(level_idc, max_samples, bands) in &LEVEL_LIMITS {
+        if luma_samples_per_sec <= max_samples {
+            for (band_idc, &max_mbps) in bands.iter().enumerate() {
+                if mbps <= max_mbps {
+                    return (level_idc, band_idc as u8);
+                }
+            }
+        }
+    }
+    (213, 3)
+}
@@ -0,0 +1,136 @@
+//! Robustness: mutated, truncated, spliced, and random bitstreams must never panic (errors are fine).
+
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+use filmcraft_apv::*;
+
+struct Rng(u64);
+impl Rng {
+    fn next(&mut self) -> u64 {
+        self.0 ^= self.0 << 13;
+        self.0 ^= self.0 >> 7;
+        self.0 ^= self.0 << 17;
+        self.0
+    }
+    fn below(&mut self, n: usize) -> usize {
+        (self.next() % n.max(1) as u64) as usize
+    }
+}
+
+fn seeds() -> Vec<Vec<u8>> {
+    let mut v = Vec::new();
+    for (p, w, h) in
+        [(Profile::P422_10, 64u32, 48u32), (Profile::P422_12, 70, 38), (Profile::P444_10, 48, 32), (Profile::P4444_10, 64, 32), (Profile::P400_10, 32, 32)]
+    {
+        let chroma = p.default_chroma();
+        let depth = p.default_bit_depth();
+        let mut f = Frame::new(w, h, chroma, depth, chroma == ChromaFormat::Yuv4444);
+        for (i, s) in f.y.iter_mut().enumerate() {
+            *s = (64 + (i * 37) % 800) as u16;
+        }
+        if let Some(a) = f.alpha.as_mut() {
+            for (i, s) in a.iter_mut().enumerate() {
+                *s = ((i * 19) % 1024) as u16;
+            }
+        }
+        let mut cfg = EncoderConfig::new(p, w, h);
+        cfg.qp = Some(16);
+        let mut enc = Encoder::with_config(cfg).expect("seed encoder");
+        v.push(enc.encode(&f).expect("seed encode"));
+        v.push(enc.encode_raw_au(&f).expect("seed encode_raw_au"));
+    }
+    v
+}
+
+#[test]
+fn mutated_streams_never_panic() {
+    let seeds = seeds();
+    for s in &seeds {
+        decode_frame(s).expect("seed decodes");
+    }
+    let mut rng = Rng(0x9e3779b97f4a7c15);
+    let mut decoded_ok = 0usize;
+    let iters = 3000usize;
+
+    for i in 0..iters {
+        let mut d = seeds[i % seeds.len()].clone();
+        match rng.below(6) {
+            0 => {
+                // Bit flips
+                for _ in 0..1 + rng.below(8) {
+                    let p = rng.below(d.len());
+                    d[p] ^= 1 << rng.below(8);
+                }
+            }
+            1 => {
+                // Random byte overwrites
+                for _ in 0..1 + rng.below(4) {
+                    let p = rng.below(d.len());
+                    d[p] = rng.next() as u8;
+                }
+            }
+            2 => {
+                // Truncation
+                let n = rng.below(d.len());
+                d.truncate(n);
+            }
+            3 => {
+                // Corrupt header fields
+                if d.len() > 8 {
+                    let p = 4 + rng.below(24.min(d.len() - 4));
+                    d[p] = rng.next() as u8;
+                }
+            }
+            4 => {
+                // Corrupt tile payload region
+                let start = 24.min(d.len().saturating_sub(1));
+                let off = start + rng.below(d.len().saturating_sub(start).max(1));
+                for b in d.iter_mut().skip(off).take(1 + rng.below(48)) {
+                    *b = rng.next() as u8;
+                }
+            }
+            _ => {
+                // Splice random bytes
+                let p = rng.below(d.len());
+                let extra: Vec<u8> = (0..1 + rng.below(16)).map(|_| rng.next() as u8).collect();
+                d.splice(p..p, extra);
+            }
+        }
+
+        let res = catch_unwind(AssertUnwindSafe(|| {
+            for depth in [None, Some(8), Some(16)] {
+                let opts = DecodeOptions { bit_depth: depth, threads: i % 2 == 0 };
+                if let Ok(f) = decode_frame_with(&d, &opts) {
+                    decoded_ok += 1;
+                    assert_eq!(f.y.len(), (f.width as usize) * (f.height as usize));
+                }
+            }
+            let _ = probe(&d);
+            let _ = split_raw_bitstream(&d);
+        }));
+        assert!(res.is_ok(), "panic on mutated stream iteration {i}");
+    }
+    println!("{decoded_ok} of {} mutated decodes succeeded", iters * 3);
+}
+
+#[test]
+fn random_bytes_never_panic() {
+    let mut rng = Rng(123456789);
+    for i in 0..2000 {
+        let n = rng.below(400);
+        let mut d: Vec<u8> = (0..n).map(|_| rng.next() as u8).collect();
+        if d.len() >= 8 && rng.below(2) == 0 {
+            d[..4].copy_from_slice(b"aPv1");
+        } else if d.len() >= 12 && rng.below(2) == 0 {
+            let au_sz = (n - 4) as u32;
+            d[..4].copy_from_slice(&au_sz.to_be_bytes());
+            d[4..8].copy_from_slice(b"aPv1");
+        }
+        let res = catch_unwind(AssertUnwindSafe(|| {
+            let _ = decode_frame(&d);
+            let _ = probe(&d);
+            let _ = split_raw_bitstream(&d);
+        }));
+        assert!(res.is_ok(), "panic on random bytes iteration {i}");
+    }
+}
@@ -0,0 +1,230 @@
+//! Conformance, bit-exactness, and quality tests against ffmpeg's APV decoder (external oracle).
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use filmcraft_apv::{
+    ChromaFormat, ContentLightLevel, DecodeOptions, Encoder, EncoderConfig, Frame, MasteringDisplay, Profile, decode_frame, decode_frame_with, probe,
+};
+
+fn ffmpeg() -> Option<PathBuf> {
+    filmcraft_testkit::ffmpeg_or_skip("apv oracle")
+}
+
+fn fixture_dir() -> PathBuf {
+    filmcraft_testkit::fixtures_dir("apv")
+}
+
+fn native_pix_fmt(profile: Profile) -> &'static str {
+    match profile {
+        Profile::P422_10 => "yuv422p10le",
+        Profile::P422_12 => "yuv422p12le",
+        Profile::P444_10 => "yuv444p10le",
+        Profile::P444_12 => "yuv444p12le",
+        Profile::P4444_10 => "yuva444p10le",
+        Profile::P4444_12 => "yuva444p12le",
+        Profile::P400_10 => "gray10le",
+    }
+}
+
+/// Decode a raw `.apv` file with ffmpeg (`-v error -xerror`) to planar `u16` samples.
+fn ffmpeg_decode_raw(ff: &Path, apv_path: &Path, pix_fmt: &str) -> (Vec<u16>, String) {
+    let out = Command::new(ff)
+        .args(["-hide_banner", "-v", "error", "-xerror", "-f", "apv", "-i"])
+        .arg(apv_path)
+        .args(["-f", "rawvideo", "-pix_fmt", pix_fmt, "-"])
+        .output()
+        .expect("run ffmpeg");
+    let stderr = String::from_utf8_lossy(&out.stderr).into_owned();
+    assert!(out.status.success(), "ffmpeg failed on {:?}: {}", apv_path, stderr);
+    let samples = out.stdout.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]])).collect();
+    (samples, stderr)
+}
+
+fn synthetic_frame(profile: Profile, w: u32, h: u32) -> Frame {
+    let chroma = profile.default_chroma();
+    let depth = profile.default_bit_depth();
+    let mut f = Frame::new(w, h, chroma, depth, chroma == ChromaFormat::Yuv4444);
+    let max_v = (1u32 << depth) - 1;
+    let lo = 16u32 << (depth - 8);
+    let hi = 235u32 << (depth - 8);
+    let span = hi - lo;
+
+    for y in 0..h {
+        for x in 0..w {
+            // Mix smooth gradients, diagonal edges, and high-frequency patterns
+            let grad = (x * 7 + y * 13) % span;
+            let checker = if ((x / 3) ^ (y / 5)) & 1 == 0 { 40 << (depth - 10) } else { 0 };
+            f.y[(y * w + x) as usize] = (lo + (grad + checker) % span).min(max_v) as u16;
+        }
+    }
+    let cw = f.chroma_width();
+    let ch = f.chroma_height();
+    for y in 0..ch {
+        for x in 0..cw {
+            let u = lo + ((x * 11 + y * 5 + 100) % span);
+            let v = lo + ((x * 3 + y * 17 + 300) % span);
+            f.cb[(y * cw + x) as usize] = u.min(max_v) as u16;
+            f.cr[(y * cw + x) as usize] = v.min(max_v) as u16;
+        }
+    }
+    if let Some(a) = f.alpha.as_mut() {
+        for y in 0..h {
+            for x in 0..w {
+                let dx = x as i32 - (w as i32) / 2;
+                let dy = y as i32 - (h as i32) / 2;
+                a[(y * w + x) as usize] =
+                    if dx * dx + dy * dy < ((w.min(h) as i32) / 3).pow(2) { max_v as u16 } else { ((x * 19 + y * 23) % (max_v + 1)) as u16 };
+            }
+        }
+    }
+    f
+}
+
+fn flatten_frame(f: &Frame) -> Vec<u16> {
+    let mut v = Vec::new();
+    v.extend_from_slice(&f.y);
+    v.extend_from_slice(&f.cb);
+    v.extend_from_slice(&f.cr);
+    if let Some(a) = &f.alpha {
+        v.extend_from_slice(a);
+    }
+    v
+}
+
+fn psnr(a: &[u16], b: &[u16], peak: f64) -> f64 {
+    if a.is_empty() {
+        return 99.0;
+    }
+    let mse: f64 = a.iter().zip(b).map(|(&x, &y)| (x as f64 - y as f64).powi(2)).sum::<f64>() / a.len() as f64;
+    if mse == 0.0 { 99.0 } else { 10.0 * (peak * peak / mse).log10() }
+}
+
+#[test]
+fn all_profiles_bit_exact_with_ffmpeg() {
+    let Some(ff) = ffmpeg() else { return };
+    let dir = fixture_dir();
+
+    for profile in Profile::ALL {
+        let (w, h) = (320u32, 192u32);
+        let src = synthetic_frame(profile, w, h);
+        let mut cfg = EncoderConfig::new(profile, w, h);
+        cfg.qp = Some(12);
+        let mut enc = Encoder::with_config(cfg).expect("encoder init");
+
+        let raw_au = enc.encode_raw_au(&src).expect("encode_raw_au");
+        let apv_path = dir.join(format!("oracle_{}.apv", profile.short_name()));
+        std::fs::write(&apv_path, &raw_au).expect("write .apv");
+
+        let (ff_samples, stderr) = ffmpeg_decode_raw(&ff, &apv_path, native_pix_fmt(profile));
+        assert!(stderr.trim().is_empty(), "{profile:?}: ffmpeg stderr: {stderr}");
+
+        let ours = decode_frame(&raw_au).expect("our decode");
+        let our_samples = flatten_frame(&ours);
+        assert_eq!(our_samples.len(), ff_samples.len(), "{profile:?}: sample count mismatch");
+
+        let max_diff = our_samples.iter().zip(&ff_samples).map(|(&a, &b)| (a as i32 - b as i32).unsigned_abs()).max().unwrap_or(0);
+        assert_eq!(max_diff, 0, "{profile:?}: our decoder must be 100% bit-exact with ffmpeg (max_diff={max_diff})");
+
+        let peak = ((1u32 << profile.default_bit_depth()) - 1) as f64;
+        let y_psnr = psnr(&ours.y, &src.y, peak);
+        assert!(y_psnr > 45.0, "{profile:?}: expected high PSNR at qp=12, got {y_psnr:.2} dB");
+    }
+}
+
+#[test]
+fn odd_dimensions_and_multi_tile_bit_exact_with_ffmpeg() {
+    let Some(ff) = ffmpeg() else { return };
+    let dir = fixture_dir();
+
+    for (profile, w, h) in [
+        (Profile::P422_10, 640u32, 360u32),
+        (Profile::P422_10, 334, 202),
+        (Profile::P444_10, 333, 201),
+        (Profile::P4444_12, 512, 288),
+        (Profile::P400_10, 70, 38),
+    ] {
+        let mut src = synthetic_frame(profile, w, h);
+        src.mastering_display = Some(MasteringDisplay {
+            primaries: [(46400, 19136), (11141, 52232), (8585, 3015)],
+            white_point: (20493, 21561),
+            max_luminance: 1000 << 8,
+            min_luminance: 1,
+        });
+        src.content_light = Some(ContentLightLevel { max_cll: 1000, max_fall: 400 });
+
+        let mut enc = Encoder::new(profile, w, h).expect("encoder init");
+        let raw_au = enc.encode_raw_au(&src).expect("encode");
+        let apv_path = dir.join(format!("oracle_geom_{}_{w}x{h}.apv", profile.short_name()));
+        std::fs::write(&apv_path, &raw_au).expect("write .apv");
+
+        let (ff_samples, stderr) = ffmpeg_decode_raw(&ff, &apv_path, native_pix_fmt(profile));
+        assert!(stderr.trim().is_empty(), "{profile:?} {w}x{h}: {stderr}");
+
+        let hdr = probe(&raw_au).expect("probe");
+        assert_eq!((hdr.width, hdr.height), (w, h));
+
+        let ours = decode_frame(&raw_au).expect("decode");
+        assert_eq!(ours.mastering_display, src.mastering_display);
+        assert_eq!(ours.content_light, src.content_light);
+
+        let our_samples = flatten_frame(&ours);
+        assert_eq!(our_samples, ff_samples, "{profile:?} {w}x{h}: bit-exact match with ffmpeg failed");
+
+        // Also verify single-threaded decode produces identical output
+        let ours_st = decode_frame_with(&raw_au, &DecodeOptions { bit_depth: None, threads: false }).expect("decode single-threaded");
+        assert_eq!(ours, ours_st);
+    }
+}
+
+#[test]
+fn custom_q_matrix_and_fh_tile_sizes_bit_exact_with_ffmpeg() {
+    let Some(ff) = ffmpeg() else { return };
+    let dir = fixture_dir();
+
+    let profile = Profile::P444_12;
+    let (w, h) = (512u32, 256u32);
+    let src = synthetic_frame(profile, w, h);
+
+    let mut q_matrix = [[16u8; 64]; 4];
+    for (c, qm) in q_matrix.iter_mut().enumerate() {
+        for y in 0..8 {
+            for x in 0..8 {
+                // Intentionally asymmetric (x != y weight) to verify exact (x, y) matrix orientation
+                qm[y * 8 + x] = (10 + c * 3 + y * 5 + x * 2) as u8;
+            }
+        }
+    }
+
+    let mut cfg = EncoderConfig::new(profile, w, h);
+    cfg.qp = Some(18);
+    cfg.q_matrix = Some(q_matrix);
+    cfg.write_tile_sizes_in_fh = true;
+    cfg.tile_width_in_mbs = 16;
+    cfg.tile_height_in_mbs = 8;
+
+    let mut enc = Encoder::with_config(cfg).expect("encoder init");
+    let raw_au = enc.encode_raw_au(&src).expect("encode");
+    let apv_path = dir.join("oracle_custom_qmat_444-12.apv");
+    std::fs::write(&apv_path, &raw_au).expect("write .apv");
+
+    let (ff_samples, stderr) = ffmpeg_decode_raw(&ff, &apv_path, native_pix_fmt(profile));
+    assert!(stderr.trim().is_empty(), "ffmpeg stderr: {stderr}");
+
+    let hdr = probe(&raw_au).expect("probe");
+    assert!(hdr.use_q_matrix);
+    assert!(hdr.tile_sizes_in_fh.is_some());
+    assert_eq!(hdr.num_tiles(), 4);
+
+    let ours = decode_frame(&raw_au).expect("decode");
+    let our_samples = flatten_frame(&ours);
+    assert_eq!(our_samples, ff_samples, "asymmetric q_matrix decode must be bit-exact with ffmpeg");
+
+    // Verify 8-bit and 16-bit rescaled output
+    let d8 = decode_frame_with(&raw_au, &DecodeOptions { bit_depth: Some(8), threads: true }).expect("decode 8-bit");
+    assert_eq!(d8.bit_depth, 8);
+    assert!(d8.y.iter().all(|&s| s <= 255));
+
+    let d16 = decode_frame_with(&raw_au, &DecodeOptions { bit_depth: Some(16), threads: true }).expect("decode 16-bit");
+    assert_eq!(d16.bit_depth, 16);
+}
@@ -123,7 +123,7 @@ pub fn matrix(from: Layout, to: Layout, mixdown: Mixdown) -> Vec<Vec<f32>> {
    let (ni, no) = (from.channels(), to.channels());
    let mut m = vec![vec![0.0f32; ni]; no];
    match (from, to) {
-        (a, b) if a == b => {
+        (Layout::Mono, Layout::Mono) | (Layout::Stereo, Layout::Stereo) | (Layout::Surround51, Layout::Surround51) => {
            for (i, row) in m.iter_mut().enumerate() {
                row[i] = 1.0;
            }
@@ -159,7 +159,6 @@ pub fn matrix(from: Layout, to: Layout, mixdown: Mixdown) -> Vec<Vec<f32>> {
                m[1][LFE] = K;
            }
        }
-        _ => unreachable!("all layout pairs are covered"),
    }
    m
 }
@@ -7,6 +7,7 @@
 //!   engine and UI can build controls generically.
 //! * [`biquad`] — RBJ-cookbook biquads (TDF-II) with analytic magnitude response.
 //! * [`sync`] — offset between two recordings of one event (GCC-PHAT, sample-accurate).
+//! * [`resample`] — streaming, block-invariant rate conversion for playback on a device at another rate.
 //! * [`channels`] — channel layouts, ITU-R BS.775 up/downmix, 5.1 mixdown types, the 5.1 panner.
 //!
 //! Conventions: audio is **planar f32** (`&mut [&mut [f32]]`, one slice per channel, all the same
@@ -16,6 +17,8 @@
 //! denormals never appear (no FTZ/DAZ CPU flags needed, which keeps the crate `unsafe`-free and
 //! portable to wasm).

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 pub mod biquad;
 pub mod channels;
 pub mod design;
@@ -25,6 +28,7 @@ pub mod fft;
 pub mod loudness;
 pub mod oversample;
 pub mod remix;
+pub mod resample;
 mod smooth;
 pub mod sync;

@@ -169,12 +173,11 @@ impl ParamValues {
    pub(crate) fn get(&self, id: &str) -> Option<f32> {
        self.index_of(id).map(|i| self.values[i])
    }
-    /// Value of a parameter that is known to exist (panics otherwise — programming error).
+    /// Value of a parameter that is known to exist (0 otherwise — a programming error caught by
+    /// debug builds).
    pub(crate) fn v(&self, id: &str) -> f32 {
-        match self.get(id) {
-            Some(v) => v,
-            None => panic!("unknown parameter {id}"),
-        }
+        debug_assert!(self.get(id).is_some(), "unknown parameter {id}");
+        self.get(id).unwrap_or(0.0)
    }
    pub(crate) fn on(&self, id: &str) -> bool {
        self.v(id) >= 0.5
@@ -0,0 +1,170 @@
+//! Streaming sample-rate conversion for playback, when the output device runs at another rate
+//! than the sequence (a 44.1 kHz device playing a 48 kHz sequence).
+//!
+//! Every output sample's source position comes from its absolute output frame, as an exact
+//! rational (`frame × from / to`), and is linearly interpolated, so the output is identical however
+//! the stream is cut into blocks: no phase jump at block boundaries. Source frames are pulled in
+//! contiguous, non-overlapping spans, so whatever produces them (the mixer, with its effect state)
+//! sees one continuous stream. Output lags the source by one source sample (≈21 µs at 48 kHz),
+//! which is what lets each block interpolate without reading ahead.
+
+/// Converts a planar stream from `from` Hz to `to` Hz, block by block.
+#[derive(Debug, Clone)]
+pub struct StreamResampler {
+    from: u32,
+    to: u32,
+    /// Source frames `[held_start, held_start + held[c].len())` kept from the last pull.
+    held_start: i64,
+    held: Vec<Vec<f32>>,
+    /// The output frame the next block is expected to start at (contiguous playback).
+    next_out: Option<i64>,
+}
+
+impl StreamResampler {
+    /// Rates of zero are treated as 1 Hz rather than dividing by zero.
+    pub fn new(from: u32, to: u32) -> Self {
+        Self { from: from.max(1), to: to.max(1), held_start: 0, held: Vec::new(), next_out: None }
+    }
+
+    pub fn rates(&self) -> (u32, u32) {
+        (self.from, self.to)
+    }
+
+    /// The source frame whose sample lands at (or just before) output frame `out`.
+    fn source_index(&self, out: i64) -> (i64, f32) {
+        let p = out as i128 * self.from as i128;
+        let to = self.to as i128;
+        (p.div_euclid(to) as i64, (p.rem_euclid(to) as f64 / to as f64) as f32)
+    }
+
+    /// Output frames `[out, out + n)`, planar. `pull(start, frames)` returns source frames
+    /// `[start, start + frames)`, planar (missing samples read as silence). A block that does not
+    /// continue the previous one (a seek) starts the stream afresh.
+    pub fn process(&mut self, out: i64, n: usize, mut pull: impl FnMut(i64, usize) -> Vec<Vec<f32>>) -> Vec<Vec<f32>> {
+        if n == 0 {
+            return vec![Vec::new(); self.held.len().max(1)];
+        }
+        let (first, _) = self.source_index(out);
+        let (last, _) = self.source_index(out.saturating_add(n as i64 - 1));
+        // interpolation reads source frames first - 1 ..= last
+        if self.next_out != Some(out) || self.held.is_empty() {
+            self.held_start = first - 1;
+            self.held.clear();
+        }
+        let held_end = self.held_start + self.held.first().map_or(0, Vec::len) as i64;
+        if last + 1 > held_end {
+            let want = (last + 1 - held_end) as usize;
+            let got = pull(held_end, want);
+            if self.held.is_empty() {
+                self.held = vec![Vec::new(); got.len().max(1)];
+            }
+            for (c, h) in self.held.iter_mut().enumerate() {
+                let src = got.get(c).map(Vec::as_slice).unwrap_or_default();
+                h.extend((0..want).map(|i| src.get(i).copied().unwrap_or(0.0)));
+            }
+        }
+        let mut dst = vec![vec![0.0f32; n]; self.held.len()];
+        for (i, frame) in (out..).take(n).enumerate() {
+            let (s, frac) = self.source_index(frame);
+            // held starts at first - 1, so the earlier frame is always held
+            let k = usize::try_from(s - self.held_start).unwrap_or(0);
+            for (d, h) in dst.iter_mut().zip(&self.held) {
+                let a = k.checked_sub(1).and_then(|j| h.get(j)).copied().unwrap_or(0.0);
+                let b = h.get(k).copied().unwrap_or(0.0);
+                if let Some(x) = d.get_mut(i) {
+                    *x = a + (b - a) * frac;
+                }
+            }
+        }
+        // keep what the next block can still read: from its first frame - 1 on
+        let (next_first, _) = self.source_index(out.saturating_add(n as i64));
+        let drop = (next_first - 1 - self.held_start).clamp(0, self.held.first().map_or(0, Vec::len) as i64) as usize;
+        for h in &mut self.held {
+            h.drain(..drop);
+        }
+        self.held_start += drop as i64;
+        self.next_out = Some(out.saturating_add(n as i64));
+        dst
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A sine at `hz`, sampled at `rate`, from absolute frame `start`; logs every pull.
+    fn sine(hz: f64, rate: u32, pulls: &mut Vec<(i64, usize)>) -> impl FnMut(i64, usize) -> Vec<Vec<f32>> + '_ {
+        move |start, frames| {
+            pulls.push((start, frames));
+            let ch: Vec<f32> = (0..frames).map(|i| (2.0 * std::f64::consts::PI * hz * (start + i as i64) as f64 / rate as f64).sin() as f32).collect();
+            vec![ch.clone(), ch]
+        }
+    }
+
+    fn convert(from: u32, to: u32, blocks: &[usize], total: usize) -> (Vec<f32>, Vec<(i64, usize)>) {
+        let mut r = StreamResampler::new(from, to);
+        let mut pulls = Vec::new();
+        let mut out = Vec::new();
+        let mut pos = 0i64;
+        let mut k = 0;
+        while (pos as usize) < total {
+            let n = blocks[k % blocks.len()].min(total - pos as usize);
+            let b = r.process(pos, n, sine(1000.0, from, &mut pulls));
+            assert_eq!(b.len(), 2);
+            assert!(b.iter().all(|c| c.len() == n));
+            out.extend_from_slice(&b[0]);
+            pos += n as i64;
+            k += 1;
+        }
+        (out, pulls)
+    }
+
+    #[test]
+    fn output_is_the_same_however_the_stream_is_cut() {
+        for (from, to) in [(48_000, 44_100), (44_100, 48_000), (48_000, 96_000), (96_000, 48_000)] {
+            let (whole, _) = convert(from, to, &[20_000], 20_000);
+            for blocks in [&[512][..], &[333], &[1, 7, 512, 64]] {
+                let (cut, _) = convert(from, to, blocks, 20_000);
+                assert_eq!(cut, whole, "{from}→{to} in blocks {blocks:?}");
+            }
+        }
+    }
+
+    #[test]
+    fn a_tone_converts_to_the_same_tone() {
+        // 1 kHz at 48 kHz played on a 44.1 kHz device: within linear interpolation's error of the
+        // ideal tone, one source sample late
+        let (from, to) = (48_000u32, 44_100u32);
+        let (out, _) = convert(from, to, &[512], 20_000);
+        for (o, x) in out.iter().enumerate().skip(2) {
+            let t = o as f64 / to as f64 - 1.0 / from as f64;
+            let want = (2.0 * std::f64::consts::PI * 1000.0 * t).sin() as f32;
+            assert!((x - want).abs() < 3e-3, "frame {o}: {x} vs {want}");
+        }
+    }
+
+    #[test]
+    fn the_source_is_pulled_as_one_continuous_stream() {
+        for (from, to) in [(48_000, 44_100), (44_100, 48_000)] {
+            let (_, pulls) = convert(from, to, &[512, 333], 20_000);
+            for w in pulls.windows(2) {
+                assert_eq!(w[0].0 + w[0].1 as i64, w[1].0, "{from}→{to}: {:?} then {:?}", w[0], w[1]);
+            }
+        }
+    }
+
+    #[test]
+    fn a_seek_starts_afresh_and_hostile_input_stays_finite() {
+        let mut r = StreamResampler::new(48_000, 44_100);
+        let mut pulls = Vec::new();
+        let _ = r.process(0, 512, sine(1000.0, 48_000, &mut pulls));
+        let _ = r.process(1_000_000, 512, sine(1000.0, 48_000, &mut pulls));
+        assert_eq!(pulls.last().map(|p| p.0), Some(1_000_000 * 48_000 / 44_100 - 1));
+        // a mixer returning too few channels and samples, and zero rates
+        let mut r = StreamResampler::new(0, 0);
+        let b = r.process(5, 64, |_, _| vec![vec![1.0; 3]]);
+        assert_eq!(b.len(), 1);
+        assert!(b[0].iter().all(|x| x.is_finite()));
+        assert!(r.process(0, 0, |_, _| Vec::new()).iter().all(Vec::is_empty));
+    }
+}
@@ -10,6 +10,9 @@ use tokio::sync::Mutex;

 use crate::AutomationError;

+/// How often a blocking export's app job is polled.
+const JOB_POLL: Duration = Duration::from_millis(250);
+
 type Conn = (BufReader<tokio::net::tcp::OwnedReadHalf>, tokio::net::tcp::OwnedWriteHalf);

 pub struct BridgeClient {
@@ -29,6 +32,40 @@ impl BridgeClient {
        Ok(Self { addr, conn: Mutex::new(None), next_id: AtomicU64::new(1) })
    }

+    /// Run engine command `id` in the app. A blocking export (`file.exportMedia` with
+    /// `wait: true`, see [`crate::long_job::LONG_COMMANDS`]) is started as an app job and polled
+    /// here until it finishes, so the app keeps repainting (its status bar shows the progress) and
+    /// answering other requests, and no request waits on the control server's 60 s reply limit
+    /// (#91, #92). The reply is the same as a blocking export's: `{job, path, result}`, or the
+    /// export's error.
+    pub async fn execute(&self, id: &str, mut params: Value) -> Result<Value, AutomationError> {
+        if !crate::long_job::is_long(id, &params) {
+            return self.call("engine.execute", json!({"command": id, "params": params})).await;
+        }
+        if let Some(p) = params.as_object_mut() {
+            p.insert("wait".into(), json!(false));
+        }
+        let mut start = self.call("engine.execute", json!({"command": id, "params": params})).await?;
+        let Some(job) = start.get("job").and_then(Value::as_u64) else { return Ok(start) };
+        let result = loop {
+            tokio::time::sleep(JOB_POLL).await;
+            let jobs = self.call("engine.execute", json!({"command": "jobs.list", "params": {}})).await?;
+            let Some(j) = jobs.as_array().and_then(|a| a.iter().find(|j| j["id"].as_u64() == Some(job))).cloned() else {
+                break Value::Null;
+            };
+            if j["finished"].as_bool() == Some(true) {
+                break j["result"].clone();
+            }
+        };
+        if let Some(e) = result.get("error").and_then(Value::as_str) {
+            return Err(AutomationError::App(format!("export failed: {e}")));
+        }
+        if let Some(o) = start.as_object_mut() {
+            o.insert("result".into(), result);
+        }
+        Ok(start)
+    }
+
    /// Call a control method; returns `result` or the app's error.
    pub async fn call(&self, method: &str, params: Value) -> Result<Value, AutomationError> {
        let mut guard = self.conn.lock().await;
@@ -42,7 +79,9 @@ impl BridgeClient {
                *guard = Some((BufReader::new(r), w));
            }
            let id = self.next_id.fetch_add(1, Ordering::Relaxed);
-            let conn = guard.as_mut().expect("connected");
+            let Some(conn) = guard.as_mut() else {
+                return Err(AutomationError::Bridge(format!("not connected to {}", self.addr)));
+            };
            let line = format!("{}\n", json!({"id": id, "method": method, "params": params}));
            let res: Result<Value, AutomationError> = async {
                conn.1.write_all(line.as_bytes()).await.map_err(|e| AutomationError::Bridge(e.to_string()))?;
@@ -72,3 +111,77 @@ impl BridgeClient {
        Err(AutomationError::Bridge("unreachable".into()))
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+    use tokio::net::TcpListener;
+
+    /// A stand-in for the app's control server: the export starts job 7, which `jobs.list` reports
+    /// running twice and then finished with `result`. Every request is recorded.
+    async fn fake_app(result: Value) -> (String, Arc<Mutex<Vec<Value>>>) {
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap().to_string();
+        let seen = Arc::new(Mutex::new(Vec::new()));
+        let log = seen.clone();
+        tokio::spawn(async move {
+            let (s, _) = listener.accept().await.unwrap();
+            let (r, mut w) = s.into_split();
+            let mut lines = BufReader::new(r).lines();
+            let mut polls = 0;
+            while let Ok(Some(line)) = lines.next_line().await {
+                let req: Value = serde_json::from_str(&line).unwrap();
+                log.lock().await.push(req.clone());
+                let reply = match req["params"]["command"].as_str() {
+                    Some("file.exportMedia") => json!({"job": 7, "path": "/tmp/out.mov"}),
+                    Some("jobs.list") => {
+                        polls += 1;
+                        let finished = polls >= 3;
+                        json!([{"id": 7, "finished": finished, "result": if finished { result.clone() } else { Value::Null }}])
+                    }
+                    _ => json!(null),
+                };
+                let line = format!("{}\n", json!({"id": req["id"], "ok": true, "result": reply}));
+                w.write_all(line.as_bytes()).await.unwrap();
+            }
+        });
+        (addr, seen)
+    }
+
+    /// A blocking bridge export runs as an app job (#91, #92): the app never sees `wait: true` (it
+    /// would encode on its UI thread and the reply would time out after 60 s), and the caller still
+    /// gets the finished result.
+    #[tokio::test]
+    async fn a_blocking_export_is_polled_as_a_job() {
+        let (addr, seen) = fake_app(json!({"frames": 642})).await;
+        let b = BridgeClient::new(addr).unwrap();
+        let r = b.execute("file.exportMedia", json!({"path": "/tmp/out.mov", "wait": true})).await.unwrap();
+        assert_eq!(r, json!({"job": 7, "path": "/tmp/out.mov", "result": {"frames": 642}}));
+        let seen = seen.lock().await;
+        assert_eq!(seen[0]["params"]["params"]["wait"], json!(false));
+        assert!(seen.iter().all(|q| q["params"]["params"]["wait"] != json!(true)));
+        assert_eq!(seen.iter().filter(|q| q["params"]["command"] == "file.exportMedia").count(), 1, "started once");
+        assert_eq!(seen.iter().filter(|q| q["params"]["command"] == "jobs.list").count(), 3);
+    }
+
+    #[tokio::test]
+    async fn a_failed_blocking_export_is_an_error() {
+        let (addr, _) = fake_app(json!({"error": "encode: disk full"})).await;
+        let b = BridgeClient::new(addr).unwrap();
+        let e = b.execute("file.exportMedia", json!({"path": "/tmp/out.mov", "wait": true})).await.unwrap_err();
+        assert!(e.to_string().contains("export failed: encode: disk full"), "{e}");
+    }
+
+    /// Everything else is forwarded unchanged.
+    #[tokio::test]
+    async fn other_commands_are_forwarded() {
+        let (addr, seen) = fake_app(Value::Null).await;
+        let b = BridgeClient::new(addr).unwrap();
+        b.execute("file.exportMedia", json!({"path": "/tmp/out.mov"})).await.unwrap();
+        b.execute("sequence.inspect", json!({})).await.unwrap();
+        let seen = seen.lock().await;
+        assert_eq!(seen.len(), 2);
+        assert_eq!(seen[1]["params"]["command"], "sequence.inspect");
+    }
+}
@@ -8,7 +8,10 @@
 //!   (`filmcraft --control <port>`), so agents can also inspect, screenshot, click, drag, scroll
 //!   and type in the live UI — every menu, panel, timeline gesture and keystroke.

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 pub mod bridge;
+pub mod long_job;
 pub mod server;

 pub use bridge::BridgeClient;
@@ -0,0 +1,183 @@
+//! Long exports over MCP (docs/agents.md § Long exports): `file.exportMedia` with `wait: true`
+//! runs as a background engine job; the server reports its progress as MCP
+//! `notifications/progress` (when the request carried a `progressToken`) and stops it on
+//! `notifications/cancelled`, deleting the partial output. The session lock is only held for
+//! short polls, so other requests are answered while the export runs.
+
+use std::path::Path;
+use std::time::{Duration, SystemTime};
+
+use rmcp::RoleServer;
+use rmcp::model::{CallToolResult, ContentBlock as Content, ProgressNotificationParam, ProgressToken};
+use rmcp::service::{Peer, RequestContext};
+use serde_json::{Value, json};
+
+use crate::server::FilmcraftMcp;
+
+/// Engine commands that block until a render is written when called with `wait: true`.
+pub const LONG_COMMANDS: &[&str] = &["file.exportMedia"];
+
+/// How often the job is polled (and at most how often progress is reported).
+const POLL: Duration = Duration::from_millis(100);
+
+/// Whether `command_run {id, params}` is a long call this module runs.
+pub fn is_long(id: &str, params: &Value) -> bool {
+    LONG_COMMANDS.contains(&id) && params.get("wait").and_then(Value::as_bool) == Some(true)
+}
+
+/// Sends `notifications/progress` for one request; progress only ever increases.
+struct Reporter {
+    peer: Peer<RoleServer>,
+    token: Option<ProgressToken>,
+    last: f64,
+}
+
+impl Reporter {
+    async fn report(&mut self, done: f64, total: f64, message: &str) {
+        let Some(token) = self.token.clone() else { return };
+        if total <= 0.0 || done <= self.last {
+            return;
+        }
+        self.last = done;
+        let mut p = ProgressNotificationParam::new(token, done).with_total(total);
+        if !message.is_empty() {
+            p = p.with_message(message);
+        }
+        let _ = self.peer.notify_progress(p).await;
+    }
+}
+
+impl FilmcraftMcp {
+    /// Run `id` (a [`LONG_COMMANDS`] entry, `wait: true`) as a job, reporting progress and
+    /// honouring cancellation.
+    pub(crate) async fn run_long(&self, id: &str, mut params: Value, context: &RequestContext<RoleServer>) -> CallToolResult {
+        let started = SystemTime::now();
+        if let Some(p) = params.as_object_mut() {
+            p.insert("wait".into(), json!(false));
+        }
+        let start = match self.run(id, params).await {
+            Ok(v) => v,
+            Err(e) => return CallToolResult::error(vec![Content::text(e.to_string())]),
+        };
+        let Some(job) = start.get("job").and_then(Value::as_u64) else {
+            return CallToolResult::error(vec![Content::text(format!("{id} started no job: {start}"))]);
+        };
+        let path = start.get("path").and_then(Value::as_str).unwrap_or_default().to_string();
+        let mut rep = Reporter { peer: context.peer.clone(), token: context.meta.get_progress_token(), last: 0.0 };
+        loop {
+            let state = self.job_state(job).await;
+            let finished = state.as_ref().is_none_or(|j| j["finished"].as_bool() == Some(true));
+            if let Some(j) = &state {
+                let (done, total) = (j["done"].as_f64().unwrap_or(0.0), j["total"].as_f64().unwrap_or(0.0));
+                rep.report(done, total, j["status"].as_str().unwrap_or_default()).await;
+            }
+            if finished {
+                let result = state.map(|j| j["result"].clone()).unwrap_or(Value::Null);
+                if let Some(e) = result.get("error").and_then(Value::as_str) {
+                    return CallToolResult::error(vec![Content::text(format!("export failed: {e}"))]);
+                }
+                let mut out = start;
+                if let Some(o) = out.as_object_mut() {
+                    o.insert("result".into(), result);
+                }
+                return CallToolResult::success(vec![Content::text(serde_json::to_string_pretty(&out).unwrap_or_default())]);
+            }
+            tokio::select! {
+                _ = context.ct.cancelled() => break,
+                _ = tokio::time::sleep(POLL) => {}
+            }
+        }
+        // Cancelled: stop the encode at the next batch, wait for the worker, delete the partial file.
+        let _ = self.run("jobs.cancel", json!({"job": job})).await;
+        for _ in 0..600 {
+            if self.job_state(job).await.is_none_or(|j| j["finished"].as_bool() == Some(true)) {
+                break;
+            }
+            tokio::time::sleep(POLL).await;
+        }
+        remove_partial(&path, started);
+        CallToolResult::error(vec![Content::text("cancelled")])
+    }
+
+    /// The job's `jobs.list` entry.
+    async fn job_state(&self, job: u64) -> Option<Value> {
+        let jobs = self.run("jobs.list", json!({})).await.ok()?;
+        jobs.as_array()?.iter().find(|j| j["id"].as_u64() == Some(job)).cloned()
+    }
+}
+
+/// Delete what an interrupted export wrote, and nothing else: the output file itself, the numbered
+/// stills of an image sequence (`<stem><digits>.<same extension>`) and the caption sidecar
+/// (`<stem>.srt` / `<stem>.vtt`), each only if it was written since `since`. Other files that
+/// merely share the name's stem (`<stem>.aep`, `<stem>2.psd`, …) are never touched, even when they
+/// were saved during the export.
+pub fn remove_partial(path: &str, since: SystemTime) {
+    let p = Path::new(path);
+    let (Some(dir), Some(stem), Some(file)) = (p.parent(), p.file_stem().and_then(|s| s.to_str()), p.file_name().and_then(|s| s.to_str())) else {
+        return;
+    };
+    let ext = p.extension().and_then(|s| s.to_str()).unwrap_or_default();
+    let dir = if dir.as_os_str().is_empty() { Path::new(".") } else { dir };
+    let Ok(entries) = std::fs::read_dir(dir) else { return };
+    // file times are coarser than the clock
+    let since = since.checked_sub(Duration::from_secs(1)).unwrap_or(since);
+    for e in entries.flatten() {
+        let name = e.file_name();
+        let Some(name) = name.to_str() else { continue };
+        if is_export_output(name, file, stem, ext) && e.metadata().is_ok_and(|m| m.is_file() && m.modified().is_ok_and(|t| t >= since)) {
+            let _ = std::fs::remove_file(e.path());
+        }
+    }
+}
+
+/// Whether `name` is a file an export to `file` (`stem` + `.ext`) writes.
+fn is_export_output(name: &str, file: &str, stem: &str, ext: &str) -> bool {
+    if name == file {
+        return true;
+    }
+    let Some(rest) = name.strip_prefix(stem) else { return false };
+    if let Some(sidecar) = rest.strip_prefix('.') {
+        return sidecar.eq_ignore_ascii_case("srt") || sidecar.eq_ignore_ascii_case("vtt");
+    }
+    // image sequence: one or more digits, then the output's own extension
+    let digits = rest.len() - rest.trim_start_matches(|c: char| c.is_ascii_digit()).len();
+    digits > 0 && !ext.is_empty() && rest.get(digits..).is_some_and(|r| r.strip_prefix('.').is_some_and(|x| x == ext))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn only_the_exports_own_files_are_removed() {
+        let dir = std::env::temp_dir().join(format!("fc-remove-partial-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let started = SystemTime::now();
+        let ours = ["trailer.png", "trailer000.png", "trailer123.png", "trailer.srt", "trailer.vtt"];
+        // same stem, written during the export, but not the export's
+        let theirs = ["trailer.aep", "trailer2.psd", "trailer.docx", "trailer000.jpg", "trailers.png", "trailer.png.bak", "other.png"];
+        for f in ours.iter().chain(theirs.iter()) {
+            std::fs::write(dir.join(f), b"x").unwrap();
+        }
+        remove_partial(&dir.join("trailer.png").to_string_lossy(), started);
+        for f in ours {
+            assert!(!dir.join(f).exists(), "{f} should be removed");
+        }
+        for f in theirs {
+            assert!(dir.join(f).exists(), "{f} must not be removed");
+        }
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn files_older_than_the_export_are_kept() {
+        let dir = std::env::temp_dir().join(format!("fc-remove-partial-old-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(dir.join("clip.mp4"), b"x").unwrap();
+        remove_partial(&dir.join("clip.mp4").to_string_lossy(), SystemTime::now() + Duration::from_secs(60));
+        assert!(dir.join("clip.mp4").exists());
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}
@@ -1,6 +1,6 @@
 //! The MCP server. Tool names are snake_case.

-use std::sync::{Arc, Mutex};
+use std::sync::{Arc, Mutex, PoisonError};

 use base64::Engine as _;
 use filmcraft_engine::Session;
@@ -19,6 +19,19 @@ pub enum Backend {
    Bridge(Arc<BridgeClient>),
 }

+/// A panic payload as text.
+fn panic_message(p: Box<dyn std::any::Any + Send>) -> String {
+    p.downcast_ref::<&str>().map(|s| s.to_string()).or_else(|| p.downcast_ref::<String>().cloned()).unwrap_or_else(|| "panic".into())
+}
+
+/// A failed blocking task: a panic is reported as an internal error and the session stays usable.
+fn join_error(e: tokio::task::JoinError) -> AutomationError {
+    match e.try_into_panic() {
+        Ok(p) => AutomationError::Other(format!("internal error: {}", panic_message(p))),
+        Err(e) => AutomationError::Other(e.to_string()),
+    }
+}
+
 #[derive(Clone)]
 pub struct FilmcraftMcp {
    backend: Arc<Backend>,
@@ -44,6 +57,24 @@ pub struct RunParams {
    pub params: Option<Value>,
 }

+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct BatchStep {
+    /// Command id.
+    pub id: String,
+    /// Parameters object.
+    #[serde(default)]
+    pub params: Option<Value>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct BatchParams {
+    /// Commands to run in order.
+    pub steps: Vec<BatchStep>,
+    /// Stop at the first failing step (default true).
+    #[serde(default)]
+    pub stop_on_error: Option<bool>,
+}
+
 #[derive(Debug, Default, Deserialize, JsonSchema)]
 pub struct RenderParams {
    /// Timeline time in seconds (default: the playhead).
@@ -148,9 +179,60 @@ impl FilmcraftMcp {
    }

    pub async fn serve_stdio(self) -> Result<(), AutomationError> {
-        let running = self.serve(rmcp::transport::stdio()).await.map_err(|e| AutomationError::Other(format!("MCP init: {e}")))?;
-        running.waiting().await.map_err(|e| AutomationError::Other(e.to_string()))?;
-        Ok(())
+        self.serve_io(tokio::io::stdin(), tokio::io::stdout()).await
+    }
+
+    /// Serve MCP over any line stream. A line that isn't JSON gets a JSON-RPC parse error
+    /// (`-32700`, id null) instead of being dropped silently; the rest go to the rmcp service. One
+    /// writer task owns `output`, so replies never interleave.
+    pub async fn serve_io(
+        self,
+        input: impl tokio::io::AsyncRead + Unpin + Send + 'static,
+        output: impl tokio::io::AsyncWrite + Unpin + Send + 'static,
+    ) -> Result<(), AutomationError> {
+        use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+        let (mut to_service, service_in) = tokio::io::duplex(1 << 20);
+        let (service_out, from_service) = tokio::io::duplex(1 << 20);
+        let (err_tx, mut err_rx) = tokio::sync::mpsc::unbounded_channel::<String>();
+        let reader = tokio::spawn(async move {
+            let mut lines = BufReader::new(input).lines();
+            while let Ok(Some(line)) = lines.next_line().await {
+                if line.trim().is_empty() {
+                    continue;
+                }
+                match serde_json::from_str::<Value>(&line) {
+                    Ok(_) => {
+                        if to_service.write_all(format!("{line}\n").as_bytes()).await.is_err() {
+                            break;
+                        }
+                    }
+                    Err(e) => {
+                        let reply = json!({"jsonrpc": "2.0", "id": null, "error": {"code": -32700, "message": format!("parse error: {e}")}});
+                        let _ = err_tx.send(reply.to_string());
+                    }
+                }
+            }
+            // EOF: closing the pipe ends the service
+            let _ = to_service.shutdown().await;
+        });
+        let writer = tokio::spawn(async move {
+            let mut output = output;
+            let mut replies = BufReader::new(from_service).lines();
+            loop {
+                let line = tokio::select! {
+                    l = replies.next_line() => match l { Ok(Some(l)) => l, _ => break },
+                    Some(e) = err_rx.recv() => e,
+                };
+                if output.write_all(format!("{line}\n").as_bytes()).await.is_err() || output.flush().await.is_err() {
+                    break;
+                }
+            }
+        });
+        let running = self.serve((service_in, service_out)).await.map_err(|e| AutomationError::Other(format!("MCP init: {e}")))?;
+        let r = running.waiting().await.map_err(|e| AutomationError::Other(e.to_string()));
+        reader.abort();
+        let _ = writer.await;
+        r.map(|_| ())
    }

    /// Run an engine command on whichever backend.
@@ -160,16 +242,24 @@ impl FilmcraftMcp {
                let s = s.clone();
                let id = id.to_string();
                tokio::task::spawn_blocking(move || {
-                    let mut g = s.lock().map_err(|_| AutomationError::Other("session lock poisoned".into()))?;
+                    // A command that panicked earlier poisoned the lock; the session is still usable.
+                    let mut g = s.lock().unwrap_or_else(PoisonError::into_inner);
                    g.execute(&id, params).map_err(AutomationError::from)
                })
                .await
-                .map_err(|e| AutomationError::Other(e.to_string()))?
+                .map_err(join_error)?
            }
-            Backend::Bridge(b) => b.call("engine.execute", json!({"command": id, "params": params})).await,
+            Backend::Bridge(b) => b.execute(id, params).await,
        }
    }

+    /// The project tree plus the active sequence (null when there is none).
+    async fn document(&self) -> Result<Value, AutomationError> {
+        let project = self.run("project.inspect", json!({})).await?;
+        let sequence = self.run("sequence.inspect", json!({})).await.ok();
+        Ok(json!({"project": project, "sequence": sequence}))
+    }
+
    fn bridge_client(&self) -> Option<Arc<BridgeClient>> {
        match &*self.backend {
            Backend::Bridge(b) => Some(b.clone()),
@@ -190,7 +280,9 @@ impl FilmcraftMcp {
 #[tool_router]
 impl FilmcraftMcp {
    #[tool(
-        description = "List every command (id, label, menu path, shortcut, parameter doc, enabled now). Menus, shortcuts, panels and timeline gestures all map to these ids."
+        title = "List commands",
+        description = "List every command (id, label, menu path, shortcut, parameter doc, enabled now). Menus, shortcuts, panels and timeline gestures all map to these ids.",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
    )]
    async fn command_list(&self, Parameters(p): Parameters<ListParams>) -> Result<CallToolResult, McpError> {
        let r = self.run("command.list", json!({})).await.map(|v| {
@@ -213,76 +305,167 @@ impl FilmcraftMcp {
    }

    #[tool(
-        description = "Run a command by id with JSON params, e.g. {\"id\":\"timeline.razor\",\"params\":{\"seconds\":3.5}} or {\"id\":\"effects.apply\",\"params\":{\"effect\":\"Gaussian Blur\"}}. Undoable edits land in History."
+        title = "Run a command",
+        description = "Run a command by id with JSON params, e.g. {\"id\":\"timeline.razor\",\"params\":{\"seconds\":3.5}} or {\"id\":\"effects.apply\",\"params\":{\"effect\":\"Gaussian Blur\"}}. Undoable edits land in History.",
+        annotations(read_only_hint = false, destructive_hint = true, idempotent_hint = false, open_world_hint = false)
    )]
    async fn command_run(&self, Parameters(p): Parameters<RunParams>) -> Result<CallToolResult, McpError> {
        wrap(self.run(&p.id, p.params.unwrap_or(json!({}))).await)
    }

-    #[tool(description = "Project tree (bins and items with ids, types, durations), active sequence, source clip.")]
+    #[tool(
+        title = "Run several commands",
+        description = "Run several commands in order: {steps: [{id, params?}], stop_on_error?: true}. Returns {completed, failed, results: [{ok, result | error}]}; each edit is its own undo step.",
+        annotations(read_only_hint = false, destructive_hint = true, idempotent_hint = false, open_world_hint = false)
+    )]
+    async fn command_batch(&self, Parameters(p): Parameters<BatchParams>) -> Result<CallToolResult, McpError> {
+        let stop = p.stop_on_error.unwrap_or(true);
+        let (mut completed, mut failed, mut results) = (0u32, 0u32, Vec::new());
+        for st in p.steps {
+            match self.run(&st.id, st.params.unwrap_or(json!({}))).await {
+                Ok(v) => {
+                    completed += 1;
+                    results.push(json!({"ok": true, "result": v}));
+                }
+                Err(e) => {
+                    failed += 1;
+                    results.push(json!({"ok": false, "error": e.to_string()}));
+                    if stop {
+                        break;
+                    }
+                }
+            }
+        }
+        let v = json!({"completed": completed, "failed": failed, "results": results});
+        Ok(if failed > 0 { CallToolResult::error(vec![Content::text(v.to_string())]) } else { ok_json(&v) })
+    }
+
+    #[tool(
+        title = "Inspect the document",
+        description = "The project as JSON: the tree (as project_inspect) plus the active sequence (as sequence_inspect; null when there is none).",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
+    )]
+    async fn doc_inspect(&self) -> Result<CallToolResult, McpError> {
+        wrap(self.document().await)
+    }
+
+    #[tool(
+        title = "Render a preview",
+        description = "The active sequence's frame at `seconds` (default: the playhead) as PNG, same as render_frame (bridge mode: Program monitor screenshot).",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
+    )]
+    async fn render_preview(&self, p: Parameters<RenderParams>) -> Result<CallToolResult, McpError> {
+        self.render_frame(p).await
+    }
+
+    #[tool(
+        title = "Inspect the project tree",
+        description = "Project tree (bins and items with ids, types, durations), active sequence, source clip.",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
+    )]
    async fn project_inspect(&self) -> Result<CallToolResult, McpError> {
        wrap(self.run("project.inspect", json!({})).await)
    }

    #[tool(
-        description = "The active sequence as JSON: settings, tracks, clips (ids, start/duration in ticks and frames, effects), transitions, markers, in/out, playhead, selection. 254016000000 ticks = 1 second."
+        title = "Inspect the active sequence",
+        description = "The active sequence as JSON: settings, tracks, clips (ids, start/duration in ticks and frames, effects), transitions, markers, in/out, playhead, selection. 254016000000 ticks = 1 second.",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
    )]
    async fn sequence_inspect(&self) -> Result<CallToolResult, McpError> {
        wrap(self.run("sequence.inspect", json!({})).await)
    }

-    #[tool(description = "Import media files by absolute path (MP4/MOV, WAV/MP3/FLAC/AIFF/Ogg, PNG/JPEG/…).")]
+    #[tool(
+        title = "Import media",
+        description = "Import media files by absolute path (MP4/MOV, WAV/MP3/FLAC/AIFF/Ogg, PNG/JPEG/…).",
+        annotations(read_only_hint = false, destructive_hint = false, idempotent_hint = false, open_world_hint = false)
+    )]
    async fn media_import(&self, Parameters(p): Parameters<TypeParams>) -> Result<CallToolResult, McpError> {
        let paths: Vec<&str> = p.text.split('\n').map(str::trim).filter(|s| !s.is_empty()).collect();
        wrap(self.run("file.import", json!({"paths": paths})).await)
    }

-    #[tool(description = "Render the active sequence's frame (at `seconds` or the playhead) and return it as PNG.")]
+    #[tool(
+        title = "Render a frame",
+        description = "Render the active sequence's frame (at `seconds` or the playhead) and return it as PNG.",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
+    )]
    async fn render_frame(&self, Parameters(p): Parameters<RenderParams>) -> Result<CallToolResult, McpError> {
        let max = p.max_side.unwrap_or(960);
        match &*self.backend {
            Backend::Headless(s) => {
                let s = s.clone();
                let r = tokio::task::spawn_blocking(move || -> Result<Vec<u8>, AutomationError> {
-                    let mut g = s.lock().map_err(|_| AutomationError::Other("lock".into()))?;
-                    if let Some(sec) = p.seconds {
-                        g.set_playhead(filmcraft_time::Tick::from_seconds_f64(sec));
-                    }
+                    let g = s.lock().unwrap_or_else(PoisonError::into_inner);
+                    // read-only: render at `seconds` without moving the playhead (#114)
+                    let t = p.seconds.map_or_else(|| g.playhead(), filmcraft_time::Tick::from_seconds_f64);
                    let (w, h) =
                        g.active_sequence().map(|q| (q.settings.width, q.settings.height)).ok_or_else(|| AutomationError::Other("no sequence".into()))?;
                    let scale = (max as f32 / w.max(h) as f32).min(1.0);
-                    let img = g.render_program(scale).ok_or_else(|| AutomationError::Other("no sequence".into()))?;
+                    let img = g.render_program_at(scale, t).ok_or_else(|| AutomationError::Other("no sequence".into()))?;
                    png_rgba(img.w as u32, img.h as u32, img.over_black_rgba8(), max)
                })
                .await
-                .map_err(|e| McpError::internal_error(e.to_string(), None))?;
+                .unwrap_or_else(|e| Err(join_error(e)));
                Ok(match r {
                    Ok(png) => png_result(&png, "rendered frame"),
                    Err(e) => fail(e),
                })
            }
            Backend::Bridge(b) => {
-                if let Some(sec) = p.seconds
-                    && let Err(e) = b.call("engine.execute", json!({"command": "playhead.set", "params": {"seconds": sec}})).await
-                {
+                let Some(sec) = p.seconds else {
+                    return self.screenshot(&b.clone(), Some("Program".into()), max).await;
+                };
+                // The Program monitor shows the playhead's frame, so the live playhead has to move
+                // for the screenshot; put it (and the selection, which may follow it) back after,
+                // so the tool stays read-only (#114).
+                let before = match self.run("sequence.inspect", json!({})).await {
+                    Ok(v) => v,
+                    Err(e) => return Ok(fail(e)),
+                };
+                if let Err(e) = self.run("playhead.set", json!({"seconds": sec})).await {
                    return Ok(fail(e));
                }
-                self.screenshot(&b.clone(), Some("Program".into()), max).await
+                let shot = self.screenshot(&b.clone(), Some("Program".into()), max).await;
+                if let Some(t) = before.get("playhead").and_then(Value::as_i64) {
+                    let _ = self.run("playhead.set", json!({"time": t})).await;
+                }
+                // only when it changed: selecting also leaves trim mode
+                let now = self.run("sequence.inspect", json!({})).await.ok();
+                if let Some(sel) = before.get("selection").filter(|v| v.is_array())
+                    && now.as_ref().and_then(|n| n.get("selection")) != Some(sel)
+                {
+                    let _ = self.run("timeline.select", json!({"clips": sel})).await;
+                }
+                shot
            }
        }
    }

-    #[tool(description = "Live app: UI state (tool, workspace, panels, timeline zoom, playback, selection, fps).")]
+    #[tool(
+        title = "Live app: UI state",
+        description = "Live app: UI state (tool, workspace, panels, timeline zoom, playback, selection, fps).",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
+    )]
    async fn ui_inspect(&self) -> Result<CallToolResult, McpError> {
        self.ui("ui.inspect", json!({})).await
    }

-    #[tool(description = "Live app: every on-screen interactive element with id, label and rect (points). Use ids with ui_click/ui_drag.")]
+    #[tool(
+        title = "Live app: on-screen elements",
+        description = "Live app: every on-screen interactive element with id, label and rect (points). Use ids with ui_click/ui_drag.",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
+    )]
    async fn ui_elements(&self, Parameters(p): Parameters<ElementsParams>) -> Result<CallToolResult, McpError> {
        self.ui("ui.elements", json!({"prefix": p.prefix.unwrap_or_default()})).await
    }

-    #[tool(description = "Live app: click an element by id or at x,y (points). Supports right/middle button, double-click (count=2) and modifiers.")]
+    #[tool(
+        title = "Live app: click",
+        description = "Live app: click an element by id or at x,y (points). Supports right/middle button, double-click (count=2) and modifiers.",
+        annotations(read_only_hint = false, destructive_hint = true, idempotent_hint = false, open_world_hint = false)
+    )]
    async fn ui_click(&self, Parameters(p): Parameters<ClickParams>) -> Result<CallToolResult, McpError> {
        let mut v = json!({"button": p.button, "count": p.count, "modifiers": p.modifiers});
        if let Some(id) = p.id {
@@ -295,23 +478,37 @@ impl FilmcraftMcp {
    }

    #[tool(
-        description = "Live app: press-drag-release from one point/element to another (move clips, trim edges, scrub, resize panels, drop project items onto tracks)."
+        title = "Live app: drag",
+        description = "Live app: press-drag-release from one point/element to another (move clips, trim edges, scrub, resize panels, drop project items onto tracks).",
+        annotations(read_only_hint = false, destructive_hint = true, idempotent_hint = false, open_world_hint = false)
    )]
    async fn ui_drag(&self, Parameters(p): Parameters<DragParams>) -> Result<CallToolResult, McpError> {
        self.ui("ui.drag", json!({"from": p.from, "to": p.to, "steps": p.steps, "modifiers": p.modifiers})).await
    }

-    #[tool(description = "Live app: press a key or shortcut (e.g. `Space`, `L`, `Cmd+K`, `Shift+Delete`, `Cmd+Z`).")]
+    #[tool(
+        title = "Live app: press a key",
+        description = "Live app: press a key or shortcut (e.g. `Space`, `L`, `Cmd+K`, `Shift+Delete`, `Cmd+Z`).",
+        annotations(read_only_hint = false, destructive_hint = true, idempotent_hint = false, open_world_hint = false)
+    )]
    async fn ui_key(&self, Parameters(p): Parameters<KeyParams>) -> Result<CallToolResult, McpError> {
        self.ui("ui.key", json!({"key": p.key})).await
    }

-    #[tool(description = "Live app: type text into the focused field.")]
+    #[tool(
+        title = "Live app: type text",
+        description = "Live app: type text into the focused field.",
+        annotations(read_only_hint = false, destructive_hint = true, idempotent_hint = false, open_world_hint = false)
+    )]
    async fn ui_type(&self, Parameters(p): Parameters<TypeParams>) -> Result<CallToolResult, McpError> {
        self.ui("ui.type", json!({"text": p.text})).await
    }

-    #[tool(description = "Live app: screenshot of the window or one panel (PNG).")]
+    #[tool(
+        title = "Live app: screenshot",
+        description = "Live app: screenshot of the window or one panel (PNG).",
+        annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
+    )]
    async fn ui_screenshot(&self, Parameters(p): Parameters<ShotParams>) -> Result<CallToolResult, McpError> {
        match self.bridge_client() {
            Some(b) => self.screenshot(&b, p.panel, p.max_side.unwrap_or(1600)).await,
@@ -320,7 +517,9 @@ impl FilmcraftMcp {
    }

    #[tool(
-        description = "Live app: call any control-channel method directly (ui.set, ui.scroll, ui.timeline.hit, ui.timeline.locate, ui.playback, ui.panel.show, ui.menu.list, …)."
+        title = "Live app: control-channel call",
+        description = "Live app: call any control-channel method directly (ui.set, ui.scroll, ui.timeline.hit, ui.timeline.locate, ui.playback, ui.panel.show, ui.menu.list, …).",
+        annotations(read_only_hint = false, destructive_hint = true, idempotent_hint = false, open_world_hint = false)
    )]
    async fn ui_control(&self, Parameters(p): Parameters<ControlParams>) -> Result<CallToolResult, McpError> {
        self.ui(&p.method, p.params.unwrap_or(json!({}))).await
@@ -350,12 +549,104 @@ impl FilmcraftMcp {
    }
 }

-#[tool_handler(
-    router = self.tool_router,
-    name = "filmcraft",
-    instructions = "FilmCraft video editor (Premiere Pro-class). Every edit is an engine command: `command_list` to discover ids/params, `command_run` to execute (undoable). `project_inspect`/`sequence_inspect` return ids you can pass to commands; `render_frame` shows the result. In bridge mode the `ui_*` tools drive the live app: `ui_elements` lists clickable ids, `ui_click`/`ui_drag`/`ui_key` operate it, `ui_screenshot` shows it. Time is in ticks: 254016000000 per second (commands also accept `seconds`, `frame` or `timecode`)."
-)]
-impl ServerHandler for FilmcraftMcp {}
+impl FilmcraftMcp {
+    /// The first argument `tool` doesn't take, as a message naming the ones it does.
+    fn unknown_arg(&self, tool: &str, args: Option<&rmcp::model::JsonObject>) -> Option<String> {
+        let def = self.tool_router.get(tool)?;
+        let props = def.input_schema.get("properties").and_then(Value::as_object).cloned().unwrap_or_default();
+        let bad = args?.keys().find(|k| !props.contains_key(*k))?;
+        let accepted: Vec<&str> = props.keys().map(String::as_str).collect();
+        let accepted = if accepted.is_empty() { "no arguments".to_string() } else { accepted.join(", ") };
+        Some(format!("unknown argument \"{bad}\" for {tool}; expected: {accepted}"))
+    }
+}
+
+const INSTRUCTIONS: &str = "FilmCraft video editor (Premiere Pro-class). Every edit is an engine command: `command_list` to discover ids/params, `command_run` to execute (undoable; `command_batch` runs several). `doc_inspect` (or `project_inspect`/`sequence_inspect`) returns ids you can pass to commands; `render_preview` shows the result. In bridge mode the `ui_*` tools drive the live app: `ui_elements` lists clickable ids, `ui_click`/`ui_drag`/`ui_key` operate it, `ui_screenshot` shows it. Time is in ticks: 254016000000 per second (commands also accept `seconds`, `frame` or `timecode`).";
+
+/// Resources: the project (as `doc_inspect`) and the command catalog (as `command_list`).
+const DOCUMENT_URI: &str = "filmcraft://document";
+const COMMANDS_URI: &str = "filmcraft://commands";
+
+/// MCP 2026-07-28 clients (current Claude Code) require `ttlMs` and `cacheScope` on list and read
+/// results; rmcp fills `resultType` and leaves the cache hints to the server, as the generated
+/// `tools/list` does. The resource list never changes; the document does, so reads aren't cached.
+fn cache_hints(context: &rmcp::service::RequestContext<rmcp::RoleServer>, ttl_ms: u64) -> Option<(u64, rmcp::model::CacheScope)> {
+    context.protocol_version().is_some_and(|v| v >= rmcp::model::ProtocolVersion::V_2026_07_28).then_some((ttl_ms, rmcp::model::CacheScope::Private))
+}
+
+#[tool_handler(router = self.tool_router)]
+impl ServerHandler for FilmcraftMcp {
+    fn get_info(&self) -> rmcp::model::ServerConfig {
+        rmcp::model::ServerConfig::new(rmcp::model::ServerCapabilities::builder().enable_tools().enable_resources().build())
+            .with_server_info(rmcp::model::Implementation::new("filmcraft", env!("CARGO_PKG_VERSION")))
+            .with_instructions(INSTRUCTIONS.to_string())
+    }
+
+    /// Strict arguments and long exports in front of the tool router.
+    async fn call_tool(
+        &self,
+        request: rmcp::model::CallToolRequestParams,
+        context: rmcp::service::RequestContext<rmcp::RoleServer>,
+    ) -> Result<rmcp::model::CallToolResponse, McpError> {
+        if let Some(m) = self.unknown_arg(&request.name, request.arguments.as_ref()) {
+            return Err(McpError::invalid_params(m, None));
+        }
+        // A blocking export reports progress and can be cancelled (docs/agents.md § Long exports).
+        // Bridge mode too: the app runs it as a job, so it stays responsive (#91, #92).
+        if request.name == "command_run"
+            && let Some(a) = &request.arguments
+            && let Some(id) = a.get("id").and_then(Value::as_str)
+        {
+            let params = a.get("params").cloned().filter(Value::is_object).unwrap_or_else(|| json!({}));
+            if crate::long_job::is_long(id, &params) {
+                return Ok(self.run_long(id, params, &context).await.into());
+            }
+        }
+        let tcc = rmcp::handler::server::tool::ToolCallContext::new(self, request, context);
+        self.tool_router.call(tcc).await
+    }
+
+    async fn list_resources(
+        &self,
+        _request: Option<rmcp::model::PaginatedRequestParams>,
+        context: rmcp::service::RequestContext<rmcp::RoleServer>,
+    ) -> Result<rmcp::model::ListResourcesResult, McpError> {
+        use rmcp::model::Resource;
+        let mut r = rmcp::model::ListResourcesResult::with_all_items(vec![
+            Resource::new(DOCUMENT_URI, "document")
+                .with_title("Project")
+                .with_description("The project tree and the active sequence (same as doc_inspect).")
+                .with_mime_type("application/json"),
+            Resource::new(COMMANDS_URI, "commands")
+                .with_title("Command catalog")
+                .with_description("Every command with id, label, menu path, shortcut, params and enabled state (same as command_list).")
+                .with_mime_type("application/json"),
+        ]);
+        if let Some((ttl, scope)) = cache_hints(&context, 600_000) {
+            r = r.with_ttl_ms(ttl).with_cache_scope(scope);
+        }
+        Ok(r)
+    }
+
+    async fn read_resource(
+        &self,
+        request: rmcp::model::ReadResourceRequestParams,
+        context: rmcp::service::RequestContext<rmcp::RoleServer>,
+    ) -> Result<rmcp::model::ReadResourceResponse, McpError> {
+        let v = match request.uri.as_str() {
+            DOCUMENT_URI => self.document().await,
+            COMMANDS_URI => self.run("command.list", json!({})).await,
+            other => return Err(McpError::resource_not_found(format!("resource not found: {other}"), None)),
+        }
+        .map_err(|e| McpError::internal_error(e.to_string(), None))?;
+        let text = serde_json::to_string_pretty(&v).map_err(|e| McpError::internal_error(e.to_string(), None))?;
+        let mut r = rmcp::model::ReadResourceResult::new(vec![rmcp::model::ResourceContents::text(text, request.uri).with_mime_type("application/json")]);
+        if let Some((ttl, scope)) = cache_hints(&context, 0) {
+            r = r.with_ttl_ms(ttl).with_cache_scope(scope);
+        }
+        Ok(r.into())
+    }
+}

 #[cfg(test)]
 mod tests {
@@ -371,4 +662,286 @@ mod tests {
        let r = m.render_frame(Parameters(RenderParams { seconds: Some(1.0), max_side: Some(320) })).await.unwrap();
        assert_ne!(r.is_error, Some(true));
    }
+
+    /// `render_frame` / `render_preview` are annotated read-only (#114): rendering at `seconds`
+    /// leaves the playhead, and the selection that follows it, where they were, and still renders
+    /// the frame at `seconds`.
+    #[tokio::test]
+    async fn rendering_at_a_time_does_not_move_the_playhead() {
+        let m = FilmcraftMcp::headless(demo());
+        m.run("sequence.selectionFollowsPlayhead", json!({"on": true})).await.unwrap();
+        m.run("playhead.set", json!({"seconds": 1.0})).await.unwrap();
+        let before = m.run("sequence.inspect", json!({})).await.unwrap();
+        let png = |r: CallToolResult| serde_json::to_string(&r.content).unwrap();
+        let at_playhead = png(m.render_frame(Parameters(RenderParams { seconds: None, max_side: Some(64) })).await.unwrap());
+        for seconds in [5.0, 8.0] {
+            let r = m.render_frame(Parameters(RenderParams { seconds: Some(seconds), max_side: Some(64) })).await.unwrap();
+            assert_ne!(png(r), at_playhead, "renders the frame at {seconds} s");
+            m.render_preview(Parameters(RenderParams { seconds: Some(seconds), max_side: Some(64) })).await.unwrap();
+        }
+        let after = m.run("sequence.inspect", json!({})).await.unwrap();
+        assert_eq!(after["playhead"], before["playhead"]);
+        assert_eq!(after["selection"], before["selection"]);
+    }
+
+    /// One request/response exchange over `serve_io`, as an MCP client sees it.
+    struct Client {
+        tx: tokio::io::DuplexStream,
+        rx: tokio::io::Lines<tokio::io::BufReader<tokio::io::DuplexStream>>,
+    }
+
+    impl Client {
+        fn start(s: Session) -> Self {
+            use tokio::io::AsyncBufReadExt;
+            let (tx, server_in) = tokio::io::duplex(1 << 22);
+            let (server_out, rx) = tokio::io::duplex(1 << 22);
+            tokio::spawn(FilmcraftMcp::headless(s).serve_io(server_in, server_out));
+            Self { tx, rx: tokio::io::BufReader::new(rx).lines() }
+        }
+        async fn send(&mut self, line: &str) {
+            use tokio::io::AsyncWriteExt;
+            self.tx.write_all(format!("{line}\n").as_bytes()).await.unwrap();
+        }
+        async fn next(&mut self) -> Value {
+            serde_json::from_str(&self.rx.next_line().await.unwrap().unwrap()).unwrap()
+        }
+        async fn ask(&mut self, msg: Value) -> Value {
+            self.send(&msg.to_string()).await;
+            self.next().await
+        }
+        async fn init(&mut self) -> Value {
+            let r = self.ask(json!({"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}})).await;
+            self.send(&json!({"jsonrpc":"2.0","method":"notifications/initialized"}).to_string()).await;
+            r
+        }
+        async fn call(&mut self, id: u64, name: &str, arguments: Value) -> Value {
+            self.ask(json!({"jsonrpc":"2.0","id":id,"method":"tools/call","params":{"name":name,"arguments":arguments}})).await
+        }
+    }
+
+    fn demo() -> Session {
+        let mut s = Session::default();
+        s.execute("file.openDemoProject", json!({})).unwrap();
+        s
+    }
+
+    /// Every listed tool has a title and the four hints, and the core tools are listed.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn tools_are_titled_and_annotated() {
+        let mut c = Client::start(demo());
+        let init = c.init().await;
+        assert_eq!(init["result"]["serverInfo"]["name"], "filmcraft");
+        let tools = c.ask(json!({"jsonrpc":"2.0","id":1,"method":"tools/list"})).await["result"]["tools"].as_array().cloned().unwrap();
+        for t in &tools {
+            assert!(t["title"].is_string(), "{} has no title", t["name"]);
+            for h in ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"] {
+                assert!(t["annotations"][h].is_boolean(), "{} lacks {h}", t["name"]);
+            }
+        }
+        let names: Vec<&str> = tools.iter().filter_map(|t| t["name"].as_str()).collect();
+        for want in ["command_list", "command_run", "command_batch", "doc_inspect", "render_preview", "project_inspect", "render_frame", "ui_click"] {
+            assert!(names.contains(&want), "{want} not listed");
+        }
+        let ro = |n: &str| tools.iter().find(|t| t["name"] == n).map(|t| t["annotations"]["readOnlyHint"].clone());
+        assert_eq!((ro("command_list"), ro("command_run")), (Some(json!(true)), Some(json!(false))));
+    }
+
+    /// Strict arguments, malformed JSON, batch, doc_inspect and render_preview over the raw line
+    /// protocol.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn strict_arguments_and_parse_errors() {
+        let mut c = Client::start(demo());
+        c.init().await;
+        let r = c.call(1, "command_list", json!({"filter": "razor", "enabled_only": true})).await;
+        assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("timeline.razor"), "{r}");
+        // an unknown argument names itself and the accepted ones
+        let r = c.call(2, "command_list", json!({"filtr": "x"})).await;
+        assert_eq!(r["error"]["code"], -32602, "{r}");
+        let m = r["error"]["message"].as_str().unwrap();
+        assert!(m.contains("\"filtr\"") && m.contains("filter") && m.contains("enabled_only"), "{m}");
+        let r = c.call(3, "doc_inspect", json!({"verbose": true})).await;
+        assert_eq!(r["error"]["code"], -32602, "{r}");
+        // command params stay free-form
+        let r = c.call(4, "command_run", json!({"id": "playhead.set", "params": {"seconds": 0.5}})).await;
+        assert_eq!(r["result"]["isError"], false, "{r}");
+        // malformed JSON: a parse error, and the server keeps serving
+        c.send("{\"jsonrpc\": \"2.0\", \"id\": 5, BROKEN").await;
+        let r = c.next().await;
+        assert_eq!((r["error"]["code"].as_i64(), r["id"].is_null()), (Some(-32700), true), "{r}");
+        let r = c.ask(json!({"jsonrpc":"2.0","id":6,"method":"ping"})).await;
+        assert!(r["result"].is_object(), "{r}");
+        // batch: stops at the first failure and reports both
+        let r =
+            c.call(7, "command_batch", json!({"steps": [{"id": "playhead.set", "params": {"seconds": 0.5}}, {"id": "no.such"}, {"id": "playhead.set"}]})).await;
+        assert_eq!(r["result"]["isError"], true, "{r}");
+        let v: Value = serde_json::from_str(r["result"]["content"][0]["text"].as_str().unwrap()).unwrap();
+        assert_eq!((v["completed"].as_u64(), v["failed"].as_u64(), v["results"].as_array().map(Vec::len)), (Some(1), Some(1), Some(2)), "{v}");
+        let r = c.call(8, "doc_inspect", json!({})).await;
+        let v: Value = serde_json::from_str(r["result"]["content"][0]["text"].as_str().unwrap()).unwrap();
+        assert!(v["project"].is_object() && v["sequence"].is_object(), "{v}");
+        let r = c.call(9, "render_preview", json!({"max_side": 64})).await;
+        assert_eq!(r["result"]["content"][0]["type"], "image", "{r}");
+    }
+
+    /// `filmcraft://document` and `filmcraft://commands` are listed and readable as JSON.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn resources_document_and_commands() {
+        let mut c = Client::start(demo());
+        let init = c.init().await;
+        assert!(init["result"]["capabilities"]["resources"].is_object(), "{init}");
+        assert!(init["result"]["instructions"].as_str().unwrap().contains("doc_inspect"), "{init}");
+        let r = c.ask(json!({"jsonrpc":"2.0","id":1,"method":"resources/list"})).await;
+        let uris: Vec<&str> = r["result"]["resources"].as_array().unwrap().iter().filter_map(|x| x["uri"].as_str()).collect();
+        assert_eq!(uris, [DOCUMENT_URI, COMMANDS_URI], "{r}");
+        let r = c.ask(json!({"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":DOCUMENT_URI}})).await;
+        assert_eq!(r["result"]["contents"][0]["mimeType"], "application/json", "{r}");
+        let v: Value = serde_json::from_str(r["result"]["contents"][0]["text"].as_str().unwrap()).unwrap();
+        assert!(v["project"].is_object() && v["sequence"].is_object(), "{v}");
+        let r = c.ask(json!({"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":COMMANDS_URI}})).await;
+        assert!(r["result"]["contents"][0]["text"].as_str().unwrap().contains("timeline.razor"), "{r}");
+        let r = c.ask(json!({"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"filmcraft://nope"}})).await;
+        assert!(r["error"]["code"].is_i64(), "{r}");
+    }
+
+    /// MCP 2026-07-28 clients (current Claude Code) negotiate per request and reject list and read
+    /// results without `resultType`, `ttlMs` and `cacheScope`; sessions that negotiated an older
+    /// revision through `initialize` get the old shape.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn modern_clients_get_result_type_and_cache_hints() {
+        let mut c = Client::start(Session::default());
+        let meta = json!({
+            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+            "io.modelcontextprotocol/clientInfo": {"name": "t", "version": "1"},
+            "io.modelcontextprotocol/clientCapabilities": {},
+        });
+        let r = c.ask(json!({"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":meta}})).await;
+        assert!(r["result"]["supportedVersions"].as_array().unwrap().contains(&json!("2026-07-28")), "{r}");
+        for (id, method, params) in [
+            (2, "tools/list", json!({"_meta": meta})),
+            (3, "resources/list", json!({"_meta": meta})),
+            (4, "resources/read", json!({"_meta": meta, "uri": DOCUMENT_URI})),
+        ] {
+            let r = c.ask(json!({"jsonrpc":"2.0","id":id,"method":method,"params":params})).await;
+            assert_eq!(r["result"]["resultType"], "complete", "{method}: {r}");
+            assert!(r["result"]["ttlMs"].is_u64(), "{method}: {r}");
+            assert!(matches!(r["result"]["cacheScope"].as_str(), Some("public" | "private")), "{method}: {r}");
+        }
+        let mut c = Client::start(Session::default());
+        c.init().await;
+        for (id, method, params) in [(2, "tools/list", json!({})), (3, "resources/list", json!({})), (4, "resources/read", json!({"uri": DOCUMENT_URI}))] {
+            let r = c.ask(json!({"jsonrpc":"2.0","id":id,"method":method,"params":params})).await;
+            assert!(r["result"].is_object() && r["result"].get("resultType").is_none() && r["result"].get("ttlMs").is_none(), "{method}: {r}");
+        }
+    }
+
+    /// docs/agents.md § Long exports: a blocking export reports `notifications/progress` for its
+    /// token (none without one), answers `ping` meanwhile, and `notifications/cancelled` stops
+    /// it, deletes the partial file and sends no response.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn export_progress_and_cancel() {
+        let dir = std::env::temp_dir().join(format!("filmcraft-mcp-progress-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        let mut c = Client::start(demo());
+        c.init().await;
+        let export = |id: u64, name: &str, token: Option<Value>, seconds: f64| {
+            let path = dir.join(name).to_string_lossy().to_string();
+            let params = json!({"path": path, "format": "h264", "width": 640, "height": 360, "audio": false, "range": "custom", "startSeconds": 0, "endSeconds": seconds, "wait": true});
+            let mut call =
+                json!({"jsonrpc":"2.0","id":id,"method":"tools/call","params":{"name":"command_run","arguments":{"id":"file.exportMedia","params":params}}});
+            if let Some(t) = token {
+                call["params"]["_meta"] = json!({"progressToken": t});
+            }
+            call.to_string()
+        };
+        // no token: no notifications, the same response as before
+        c.send(&export(1, "quiet.mp4", None, 0.5)).await;
+        let m = c.next().await;
+        assert_eq!((m["id"].as_u64(), &m["result"]["isError"]), (Some(1), &json!(false)), "{m}");
+        // progress, strictly increasing, with a total; ping answered while the export runs. The
+        // job is polled every 100 ms, so a fast machine finishes a short export within one poll:
+        // a longer one is tried until the export outlasts a few polls.
+        let (mut notes, mut pong) = (0, false);
+        for (attempt, seconds) in [1.0, 4.0, 16.0].into_iter().enumerate() {
+            let (id, ping, name) = (20 + attempt as u64, 30 + attempt as u64, format!("a{attempt}.mp4"));
+            c.send(&export(id, &name, Some(json!("tok")), seconds)).await;
+            let (mut last, mut pinged) = (-1.0, false);
+            (notes, pong) = (0, false);
+            let done = loop {
+                let m = c.next().await;
+                if m["method"] == "notifications/progress" {
+                    assert_eq!(m["params"]["progressToken"], "tok", "{m}");
+                    let p = m["params"]["progress"].as_f64().unwrap();
+                    assert!(p > last && m["params"]["total"].as_f64().unwrap() >= p, "{m}");
+                    last = p;
+                    notes += 1;
+                    if !pinged {
+                        pinged = true;
+                        c.send(&json!({"jsonrpc": "2.0", "id": ping, "method": "ping"}).to_string()).await;
+                    }
+                } else if m["id"] == ping {
+                    pong = true;
+                } else if m["id"] == id {
+                    break m;
+                }
+            };
+            assert_eq!(done["result"]["isError"], false, "{done}");
+            assert!(notes >= 1, "a finished export reports its progress at least once");
+            assert!(dir.join(&name).exists());
+            if notes >= 2 && pong {
+                break;
+            }
+            // the ping's answer is still on its way: read it so it cannot be taken for a later reply
+            while pinged && !pong {
+                pong = c.next().await["id"] == ping;
+            }
+            pong = false;
+        }
+        assert!(notes >= 2 && pong, "{notes} notifications, ping answered during the export: {pong}");
+        // cancel after the first notification: no response, no partial file
+        c.send(&export(4, "b.mp4", Some(json!(7)), 20.0)).await;
+        loop {
+            let m = c.next().await;
+            assert_ne!(m["id"], 4, "finished before the cancel: {m}");
+            if m["method"] == "notifications/progress" {
+                break;
+            }
+        }
+        c.send(r#"{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":4}}"#).await;
+        let t0 = std::time::Instant::now();
+        while dir.join("b.mp4").exists() || t0.elapsed() < std::time::Duration::from_millis(500) {
+            assert!(t0.elapsed().as_secs() < 30, "partial file still there");
+            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        }
+        c.send(r#"{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"command_run","arguments":{"id":"jobs.list"}}}"#).await;
+        let m = loop {
+            let m = c.next().await;
+            assert_ne!(m["id"], 4, "no response for a cancelled request: {m}");
+            if m["id"] == 5 {
+                break m;
+            }
+        };
+        let jobs: Value = serde_json::from_str(m["result"]["content"][0]["text"].as_str().unwrap()).unwrap();
+        let last = jobs.as_array().and_then(|a| a.last()).cloned().unwrap_or_default();
+        assert_eq!(last["result"]["error"], "cancelled", "{jobs}");
+        assert!(!dir.join("b.mp4").exists());
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// A command that panicked used to poison the session lock, and every later call failed with
+    /// "session lock poisoned" until the server was restarted.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_poisoned_session_lock_keeps_serving() {
+        let m = FilmcraftMcp::headless(demo());
+        let Backend::Headless(s) = &*m.backend else { panic!("headless backend") };
+        let s = s.clone();
+        let _ = std::thread::spawn(move || {
+            let _g = s.lock().unwrap();
+            panic!("a command panicked");
+        })
+        .join();
+        let v = m.run("sequence.inspect", json!({})).await.unwrap();
+        assert!(v.is_object(), "{v}");
+        let r = m.render_frame(Parameters(RenderParams { seconds: Some(0.5), max_side: Some(64) })).await.unwrap();
+        assert_ne!(r.is_error, Some(true));
+    }
 }
@@ -58,7 +58,8 @@ and `b10-23-film_grain-50` are **bit-exact** in the default run. The ignored
 with scaled inter-layer prediction), `24-monochrome` (8 and 10-bit) and
 `16-intra_only-intrabc-extreme-dv` (1080p intra block copy), `23-film_grain-50` (8 and 10-bit).

-`tests/oracle_inter.rs` encodes SVT-AV1 GOPs (hierarchical references, compound prediction,
+`tests/oracle_inter.rs` also checks draft mode: every unflagged frame stays bit-exact with
+libdav1d and only flagged frames differ, with 1 and 4 threads. `tests/oracle_inter.rs` encodes SVT-AV1 GOPs (hierarchical references, compound prediction,
 OBMC / warped motion, motion-field projection, all loop filters; presets 3–8, 8- and 10-bit, odd
 sizes), plus super-resolution (denominator 12) and film-grain streams, and compares every frame
 with libdav1d: **bit-exact** on all 6 fixtures.
@@ -91,6 +92,36 @@ noisy; single-threaded figures use thread CPU time and are comparable.
 | `perf_1080p_gop_hq` (crf 18) | 19.5 fps | 19.4 fps | 2.4 fps | 3.6 fps |
 | `perf_1080p_gop_tiles` (4x2 tiles) | 44.4 fps | 44.7 fps | 2.7 fps | 16.3 fps |

+### M4.10 (2026-10-03)
+
+CPU cycles per frame counted by the kernel (`/usr/bin/time -l`, all threads summed; mean of two
+interleaved base / after rounds at load average 190-320) with
+`AV1_THREADS=n cargo run --release -p filmcraft-av1 --example av1dec -- in.ivf` on the
+`cargo xtask bench` decode clips (SVT-AV1 preset 10, CRF 35, keyint 48, testsrc2 + grain),
+bit-exact with libdav1d:
+
+| stream | threads | Mcycles / frame before | after | after, draft mode |
+|---|---|---|---|---|
+| 1080p (120 frames) | 1 | 60.5 | **48.3** (−20 %) | 46.2 |
+| 1080p | 14 | 63.6 | **51.9** (−18 %) | 50.3 |
+| 2160p (72 frames) | 1 | 212.5 | **172.4** (−19 %) | 167.9 |
+| 2160p | 14 | 220.0 | **177.1** (−20 %) | 171.1 |
+
+What changed: the sub-pixel filter passes run over fixed block widths (taps outer, columns
+inner); frame and tile-region planes come from a bounded pool of recycled buffers (zeroed on
+reuse) instead of a fresh `calloc` and `munmap` per frame (allocation, page faults and zeroing
+were ~10 % of the time); the palette mode-info arrays (40 bytes per 4x4 unit) are only
+allocated when screen content tools are allowed; CDF adaptation is branch-free (a branch-free
+symbol search was tried and was slower: most symbols have 2-4 values). Single-threaded 4K now
+splits into coefficient parsing ~20 %, inter prediction ~18 %, other block-level parsing
+~12 %, deblocking ~11 % (still one edge at a time), inverse transforms ~12 %, CDEF ~5 %.
+
+Draft mode (`Decoder::set_draft(true)`, `AV1_DRAFT=1`; reduced-resolution playback only): shown
+frames whose `refresh_frame_flags` is 0 — no reference slot keeps them, so neither their samples,
+motion vectors nor CDFs reach another frame — skip deblocking, CDEF and loop restoration
+(super-resolution still runs, it sets the output size) and are flagged `Picture::draft`. In
+SVT-AV1's hierarchical GOPs that is the top layer, half of the frames.
+
 ## API

 ```rust
@@ -0,0 +1,54 @@
+//! Decode an IVF AV1 file: `cargo run --release -p filmcraft-av1 --example av1dec -- in.ivf [out.yuv]`.
+//! Writes raw planar 16-bit little-endian output. `AV1_THREADS=n` sets the thread count,
+//! `AV1_LOOPS=k` decodes the file k times (benchmarking), `AV1_STATS=1` prints stage statistics.
+
+use std::io::Write;
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() < 2 {
+        eprintln!("usage: av1dec in.ivf [out.yuv]");
+        std::process::exit(2);
+    }
+    let data = std::fs::read(&args[1]).expect("read input");
+    let mut out = args.get(2).map(|p| std::io::BufWriter::new(std::fs::File::create(p).expect("create output")));
+    let threads = std::env::var("AV1_THREADS").ok().and_then(|s| s.parse().ok()).unwrap_or(0usize);
+    let loops = std::env::var("AV1_LOOPS").ok().and_then(|s| s.parse().ok()).unwrap_or(1usize);
+    let hl = u16::from_le_bytes([data[6], data[7]]) as usize;
+    let t0 = std::time::Instant::now();
+    let mut n = 0;
+    let mut dec = if threads > 0 { filmcraft_av1::Decoder::with_threads(threads) } else { filmcraft_av1::Decoder::new() };
+    // AV1_DRAFT=1: draft mode (non-reference frames skip the in-loop filters).
+    dec.set_draft(std::env::var_os("AV1_DRAFT").is_some());
+    let mut write = |pics: Vec<filmcraft_av1::Picture>| {
+        for pic in pics {
+            n += 1;
+            if let Some(o) = out.as_mut() {
+                for pl in &pic.planes {
+                    let bytes: Vec<u8> = pl.iter().flat_map(|s| s.to_le_bytes()).collect();
+                    o.write_all(&bytes).unwrap();
+                }
+            }
+        }
+    };
+    for _ in 0..loops {
+        let mut p = hl;
+        let mut i = 0i64;
+        while p + 12 <= data.len() {
+            let sz = u32::from_le_bytes(data[p..p + 4].try_into().unwrap()) as usize;
+            p += 12;
+            let Some(tu) = data.get(p..p + sz) else { break };
+            p += sz;
+            match dec.decode_pts(tu, i) {
+                Ok(pics) => write(pics),
+                Err(e) => eprintln!("temporal unit {i}: {e}"),
+            }
+            i += 1;
+        }
+        write(dec.flush());
+    }
+    eprintln!("{n} pictures in {:.3}s", t0.elapsed().as_secs_f64());
+    if std::env::var_os("AV1_STATS").is_some() {
+        eprintln!("{:#?}", dec.stats());
+    }
+}
@@ -237,12 +237,16 @@ fn filter_rows<const W: usize>(buf: &[i32; PAD_STRIDE * PAD_STRIDE], taps: &[(is
    }
    for i in 0..h {
        let ci = ((i + 2) * PAD_STRIDE + 2) as isize;
-        let x: [i16; W] = b16[ci as usize..ci as usize + W].try_into().expect("centre row");
+        let Some(&x) = b16.get(ci as usize..).and_then(|r| r.first_chunk::<W>()) else {
+            return;
+        };
        let (mut sum, mut max, mut min) = ([0i16; W], x, x);
        for &(off, weight, thr, adj) in taps {
            let (weight, thr) = (weight as i16, thr as i16);
            let start = (ci + off) as usize;
-            let p: &[i16; W] = b16[start..start + W].try_into().expect("tap row");
+            let Some(p) = b16.get(start..).and_then(|r| r.first_chunk::<W>()) else {
+                return;
+            };
            for j in 0..W {
                // constrain(): .max / .min instead of clamp (whose bound check panics), and
                // the sign applied branch-free, so the loop vectorises.
@@ -72,10 +72,12 @@ impl<T: Clone> Slot<T> {

    fn wait(&self) -> Result<T> {
        let mut g = self.value.lock().unwrap_or_else(|e| e.into_inner());
-        while g.is_none() {
+        loop {
+            if let Some(v) = g.as_ref() {
+                return v.clone();
+            }
            g = self.cv.wait(g).unwrap_or_else(|e| e.into_inner());
        }
-        g.as_ref().expect("slot value").clone()
    }
 }

@@ -95,6 +97,8 @@ struct FrameJob {
    picture: Option<Arc<Slot<Arc<Picture>>>>,
    pts: i64,
    apply_film_grain: bool,
+    /// Draft mode: the frame refreshes no reference slot, so its in-loop filters are skipped.
+    draft: bool,
 }

 /// A shown picture in output order.
@@ -193,6 +197,7 @@ pub struct Decoder {
    seen_frame_header: bool,
    /// Apply film grain synthesis to output frames (default true).
    pub apply_film_grain: bool,
+    draft: bool,
    stats: Arc<Mutex<DecodeStats>>,
    threads: usize,
    pool: Pool,
@@ -255,6 +260,7 @@ impl Decoder {
            pending: None,
            seen_frame_header: false,
            apply_film_grain: true,
+            draft: false,
            stats,
            threads,
            pool,
@@ -268,6 +274,14 @@ impl Decoder {
    }

    /// Frame / tile counts and per-stage busy time of the frames finished so far.
+    /// Draft mode for reduced-resolution playback (off by default): shown frames that refresh
+    /// no reference slot (nothing can predict from them, read their motion vectors or CDFs)
+    /// skip deblocking, CDEF and loop restoration and come out flagged [`Picture::draft`];
+    /// every other picture is unchanged.
+    pub fn set_draft(&mut self, on: bool) {
+        self.draft = on;
+    }
+
    pub fn stats(&self) -> DecodeStats {
        self.stats.lock().map(|s| *s).unwrap_or_default()
    }
@@ -296,7 +310,7 @@ impl Decoder {
            if !o.is_ready() && self.out.len() <= max_queue {
                break;
            }
-            let o = self.out.pop_front().expect("front");
+            let Some(o) = self.out.pop_front() else { break };
            pics.push(o.take()?);
        }
        parsed?;
@@ -346,7 +360,9 @@ impl Decoder {
                match last {
                    Some((lt, lsid)) if lt == t => {
                        if sid >= lsid {
-                            *sel.last_mut().expect("picture") = o;
+                            if let Some(l) = sel.last_mut() {
+                                *l = o;
+                            }
                            last = Some((t, sid));
                        }
                    }
@@ -503,6 +519,7 @@ impl Decoder {
            return Err(Error::Invalid("primary reference frame missing"));
        }
        let picture = fh.show_frame.then(Slot::new);
+        let draft = self.draft && fh.show_frame && fh.refresh_frame_flags == 0;
        self.pending = Some(Box::new(FrameJob {
            seq,
            fh,
@@ -513,6 +530,7 @@ impl Decoder {
            picture,
            pts: self.pts,
            apply_film_grain: self.apply_film_grain,
+            draft,
        }));
        Ok(None)
    }
@@ -598,7 +616,7 @@ impl Decoder {
                    self.in_flight.push_back(slot);
                    // Bound the frames in flight (memory): wait for the oldest.
                    while self.in_flight.len() > self.max_in_flight {
-                        let s = self.in_flight.pop_front().expect("in flight");
+                        let Some(s) = self.in_flight.pop_front() else { break };
                        let _ = s.wait();
                    }
                    self.in_flight.retain(|s| !s.is_set());
@@ -692,7 +710,8 @@ fn decode_frame(job: &FrameJob, pool: &Pool, stats: &mut DecodeStats) -> Result<
    {
        cdfs = s;
    }
-    crate::postfilter::apply(&mut fs, stats, pool);
+    crate::postfilter::apply(&mut fs, stats, pool, job.draft);
+    stats.draft_frames += job.draft as u64;
    let t = Timer::start();
    stats.frames += 1;
    if fh.seg.enabled && !fh.seg.update_map {
@@ -714,8 +733,11 @@ fn decode_frame(job: &FrameJob, pool: &Pool, stats: &mut DecodeStats) -> Result<
        saved_ref_frames: mf_refs,
        saved_mvs: mf_mvs,
    });
-    let pic =
-        fh.show_frame.then(|| output_picture(seq, &rf, fh.upscaled_width as usize, fh.frame_height as usize, &fh.film_grain, job.apply_film_grain, job.pts));
+    let pic = fh.show_frame.then(|| {
+        let mut p = output_picture(seq, &rf, fh.upscaled_width as usize, fh.frame_height as usize, &fh.film_grain, job.apply_film_grain, job.pts);
+        p.draft = job.draft;
+        p
+    });
    stats.add(Stage::Output, t.secs());
    Ok((rf, pic))
 }
@@ -800,6 +822,7 @@ fn output_picture(seq: &SequenceHeader, rf: &RefFrame, w: usize, h: usize, grain
        matrix_coefficients: rf.color.2,
        full_range: rf.color.3,
        pts,
+        draft: false,
    };
    if apply_film_grain && seq.film_grain_params_present && grain.apply_grain {
        crate::grain::apply(&mut pic, grain, seq);
@@ -4,8 +4,32 @@
 //! or [`MiInfo`] may hold a region of the frame (origin `ox`, `oy`), addressed with frame
 //! coordinates throughout.

+/// Recycled plane allocations: every frame allocates (and every evicted reference frees)
+/// megabytes of planes, and fresh large allocations cost page faults and kernel calls. Buffers
+/// are zeroed again on reuse, so contents never leak between frames.
+static PLANE_POOL: std::sync::Mutex<Vec<Vec<u16>>> = std::sync::Mutex::new(Vec::new());
+const POOL_MIN_LEN: usize = 1 << 16;
+/// Samples kept at most (96 M samples = 192 MB, a few 4K frames).
+const POOL_MAX_SAMPLES: usize = 96 << 20;
+
+/// A zeroed buffer of `len` samples (recycled memory for large ones).
+fn zeroed(len: usize) -> Vec<u16> {
+    if len >= POOL_MIN_LEN {
+        let found = {
+            let mut pool = PLANE_POOL.lock().unwrap_or_else(|e| e.into_inner());
+            pool.iter().position(|v| v.capacity() >= len && v.capacity() <= 2 * len).map(|i| pool.swap_remove(i))
+        };
+        if let Some(mut v) = found {
+            v.clear();
+            v.resize(len, 0);
+            return v;
+        }
+    }
+    vec![0; len]
+}
+
 /// One plane of samples (u16 at every bit depth), or a rectangular region of one.
-#[derive(Clone, Default)]
+#[derive(Default)]
 pub struct Plane {
    pub data: Vec<u16>,
    pub stride: usize,
@@ -16,13 +40,34 @@ pub struct Plane {
    pub oy: usize,
 }

+impl Clone for Plane {
+    fn clone(&self) -> Plane {
+        let mut data = zeroed(self.data.len());
+        data.copy_from_slice(&self.data);
+        Plane { data, stride: self.stride, rows: self.rows, ox: self.ox, oy: self.oy }
+    }
+}
+
+impl Drop for Plane {
+    fn drop(&mut self) {
+        if self.data.capacity() >= POOL_MIN_LEN {
+            let v = std::mem::take(&mut self.data);
+            let mut pool = PLANE_POOL.lock().unwrap_or_else(|e| e.into_inner());
+            let kept: usize = pool.iter().map(|b| b.capacity()).sum();
+            if kept + v.capacity() <= POOL_MAX_SAMPLES {
+                pool.push(v);
+            }
+        }
+    }
+}
+
 impl Plane {
    pub fn new(width: usize, height: usize) -> Plane {
-        Plane { data: vec![0; width * height], stride: width, rows: height, ox: 0, oy: 0 }
+        Plane { data: zeroed(width * height), stride: width, rows: height, ox: 0, oy: 0 }
    }
    /// A `width` x `height` region with its top-left sample at frame position (ox, oy).
    pub fn region(ox: usize, oy: usize, width: usize, height: usize) -> Plane {
-        Plane { data: vec![0; width * height], stride: width, rows: height, ox, oy }
+        Plane { data: zeroed(width * height), stride: width, rows: height, ox, oy }
    }
    #[inline(always)]
    pub fn at(&self, x: usize, y: usize) -> u16 {
@@ -173,13 +218,16 @@ pub struct MiInfo {
 }

 impl MiInfo {
-    pub fn new(cols: usize, rows: usize) -> MiInfo {
-        MiInfo::region(cols, rows, 0, 0, cols, rows)
+    /// `palette`: whether palette mode can occur (allow_screen_content_tools); without it the
+    /// palette arrays (40 bytes per unit) stay empty.
+    pub fn new(cols: usize, rows: usize, palette: bool) -> MiInfo {
+        MiInfo::region(cols, rows, 0, 0, cols, rows, palette)
    }

    /// Storage for the w x h mode info units at (ox, oy) of a cols x rows frame.
-    pub fn region(cols: usize, rows: usize, ox: usize, oy: usize, w: usize, h: usize) -> MiInfo {
+    pub fn region(cols: usize, rows: usize, ox: usize, oy: usize, w: usize, h: usize, palette: bool) -> MiInfo {
        let n = w * h;
+        let np = if palette { n } else { 0 };
        MiInfo {
            cols,
            rows,
@@ -198,8 +246,8 @@ impl MiInfo {
            inter_tx_size: vec![0; n],
            mi_size: vec![0; n],
            segment_id: vec![0; n],
-            palette_size: [vec![0; n], vec![0; n]],
-            palette_colors: [vec![[0; 8]; n], vec![[0; 8]; n]],
+            palette_size: [vec![0; np], vec![0; np]],
+            palette_colors: [vec![[0; 8]; np], vec![[0; 8]; np]],
            delta_lf: vec![[0; 4]; n],
            comp_group_idx: vec![0; n],
            compound_idx: vec![0; n],
@@ -228,7 +276,7 @@ impl MiInfo {
            )*};
        }
        copy!(y_mode uv_mode ref_frame mv is_inter skip_mode skip tx_size inter_tx_size mi_size segment_id delta_lf comp_group_idx compound_idx interp_filter motion_mode tx_type written);
-        for k in 0..2 {
+        for k in (0..2).filter(|&k| !self.palette_size[k].is_empty()) {
            for y in 0..h {
                let d = dst.idx(self.oy + y, self.ox);
                dst.palette_size[k][d..d + w].copy_from_slice(&self.palette_size[k][y * w..(y + 1) * w]);
@@ -180,7 +180,11 @@ impl TileDecoder<'_, '_> {
    }

    fn ref_plane(&self, ref_idx: i32, plane: usize) -> &Plane {
-        if ref_idx < 0 { &self.t.cur.planes[plane] } else { &self.fs.refs[ref_idx as usize].as_ref().expect("reference frame").buf.planes[plane] }
+        // A missing reference (rejected earlier for valid streams) predicts from the current frame.
+        match usize::try_from(ref_idx).ok().and_then(|i| self.fs.refs.get(i)).and_then(|r| r.as_ref()) {
+            Some(r) => &r.buf.planes[plane],
+            None => &self.t.cur.planes[plane],
+        }
    }

    /// Block inter prediction process (7.11.3.4) into `pred` (stride PRED_STRIDE); `tmp` holds
@@ -665,6 +669,49 @@ impl TileDecoder<'_, '_> {

 const IDENTITY_TAPS: [i16; 8] = [0, 0, 0, 128, 0, 0, 0, 0];

+/// Horizontal pass of one row for a block `W` wide: taps outer, columns inner, fixed width so
+/// the row stays in registers.
+#[inline(always)]
+fn hpass<const W: usize>(src: &[u16], hf: &[i16; 8], out: &mut [i32], half: i32, sh: u32) {
+    let mut acc = [half; W];
+    for t in 0..8 {
+        let f = hf[t] as i32;
+        let Some(p) = src.get(t..).and_then(|s| s.first_chunk::<W>()) else {
+            return;
+        };
+        for j in 0..W {
+            acc[j] += f * p[j] as i32;
+        }
+    }
+    let Some(o) = out.first_chunk_mut::<W>() else {
+        return;
+    };
+    for j in 0..W {
+        o[j] = acc[j] >> sh;
+    }
+}
+
+/// Vertical pass of one output row from 8 intermediate rows (`rows`, stride `W`).
+#[inline(always)]
+fn vpass<const W: usize>(rows: &[i32], vf: &[i16; 8], out: &mut [i32], half: i32, sh: u32) {
+    let mut acc = [half; W];
+    for t in 0..8 {
+        let f = vf[t] as i32;
+        let Some(p) = rows.get(t * W..).and_then(|s| s.first_chunk::<W>()) else {
+            return;
+        };
+        for j in 0..W {
+            acc[j] += f * p[j];
+        }
+    }
+    let Some(o) = out.first_chunk_mut::<W>() else {
+        return;
+    };
+    for j in 0..W {
+        o[j] = acc[j] >> sh;
+    }
+}
+
 /// Block inter prediction without reference scaling: every column / row uses the same filter
 /// phase, so the filters run over whole rows (bit-identical to the per-sample process).
 #[allow(clippy::too_many_arguments)]
@@ -711,17 +758,27 @@ fn mc_unscaled(
                *o = (v as i32) << (7 - r0);
            }
        } else {
-            let acc = &mut acc[..w];
-            acc.fill(0);
-            for t in 0..8 {
-                let f = hf[t] as i32;
-                for (a, &v) in acc.iter_mut().zip(&src[t..t + w]) {
-                    *a += f * v as i32;
+            match w {
+                2 => hpass::<2>(src, hf, out, half0, r0),
+                4 => hpass::<4>(src, hf, out, half0, r0),
+                8 => hpass::<8>(src, hf, out, half0, r0),
+                16 => hpass::<16>(src, hf, out, half0, r0),
+                32 => hpass::<32>(src, hf, out, half0, r0),
+                64 => hpass::<64>(src, hf, out, half0, r0),
+                _ => {
+                    let acc = &mut acc[..w];
+                    acc.fill(0);
+                    for t in 0..8 {
+                        let f = hf[t] as i32;
+                        for (a, &v) in acc.iter_mut().zip(&src[t..t + w]) {
+                            *a += f * v as i32;
+                        }
+                    }
+                    for (o, &a) in out.iter_mut().zip(acc.iter()) {
+                        *o = (a + half0) >> r0;
+                    }
                }
            }
-            for (o, &a) in out.iter_mut().zip(acc.iter()) {
-                *o = (a + half0) >> r0;
-            }
        }
    }
    for r in 0..h {
@@ -731,17 +788,28 @@ fn mc_unscaled(
                *o = (128 * v + half1) >> r1;
            }
        } else {
-            let acc = &mut acc[..w];
-            acc.fill(0);
-            for t in 0..8 {
-                let f = vf[t] as i32;
-                for (a, &v) in acc.iter_mut().zip(&tmp[(r + t) * w..(r + t + 1) * w]) {
-                    *a += f * v;
+            let rows = &tmp[r * w..(r + 8) * w];
+            match w {
+                2 => vpass::<2>(rows, vf, out, half1, r1),
+                4 => vpass::<4>(rows, vf, out, half1, r1),
+                8 => vpass::<8>(rows, vf, out, half1, r1),
+                16 => vpass::<16>(rows, vf, out, half1, r1),
+                32 => vpass::<32>(rows, vf, out, half1, r1),
+                64 => vpass::<64>(rows, vf, out, half1, r1),
+                _ => {
+                    let acc = &mut acc[..w];
+                    acc.fill(0);
+                    for t in 0..8 {
+                        let f = vf[t] as i32;
+                        for (a, &v) in acc.iter_mut().zip(&tmp[(r + t) * w..(r + t + 1) * w]) {
+                            *a += f * v;
+                        }
+                    }
+                    for (o, &a) in out.iter_mut().zip(acc.iter()) {
+                        *o = (a + half1) >> r1;
+                    }
                }
            }
-            for (o, &a) in out.iter_mut().zip(acc.iter()) {
-                *o = (a + half1) >> r1;
-            }
        }
    }
 }
@@ -5,6 +5,7 @@

 // Items used only by stages still being written (inter prediction, post filters).
 #![allow(dead_code)]
+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]

 mod bits;
 mod cdef;
@@ -62,6 +63,9 @@ pub struct Picture {
    pub full_range: bool,
    /// Timestamp of the temporal unit that showed the picture ([`Decoder::decode_pts`]).
    pub pts: i64,
+    /// Decoded in draft mode without deblocking / CDEF / loop restoration
+    /// ([`Decoder::set_draft`]): approximate, for reduced-resolution playback only.
+    pub draft: bool,
 }

 impl Picture {
@@ -6,14 +6,15 @@ use crate::state::FrameState;
 use crate::stats::{DecodeStats, Stage, Timer};

 /// The post-filters run on the frame worker; `_pool` is for row-parallel filtering (not yet used).
-pub(crate) fn apply(fs: &mut FrameState, stats: &mut DecodeStats, _pool: &crate::par::Pool) {
+/// `draft`: only super-resolution (which sets the output size) runs.
+pub(crate) fn apply(fs: &mut FrameState, stats: &mut DecodeStats, _pool: &crate::par::Pool, draft: bool) {
    let mut t = Timer::start();
    let lvl = fs.fh.lf.level;
-    if lvl[0] != 0 || lvl[1] != 0 {
+    if (lvl[0] != 0 || lvl[1] != 0) && !draft {
        loop_filter(fs);
    }
    stats.add(Stage::LoopFilter, t.lap());
-    let cdef = crate::cdef::apply(fs);
+    let cdef = if draft { None } else { crate::cdef::apply(fs) };
    stats.add(Stage::Cdef, t.lap());
    let (up_cur, up_cdef) = if fs.fh.use_superres {
        let c = crate::restoration::upscale(fs, &fs.cur);
@@ -23,7 +24,11 @@ pub(crate) fn apply(fs: &mut FrameState, stats: &mut DecodeStats, _pool: &crate:
        (std::mem::take(&mut fs.cur), cdef)
    };
    stats.add(Stage::Superres, t.lap());
-    fs.cur = if fs.fh.lr.uses_lr { crate::restoration::loop_restoration(fs, &up_cur, up_cdef.as_ref().unwrap_or(&up_cur)) } else { up_cdef.unwrap_or(up_cur) };
+    fs.cur = if fs.fh.lr.uses_lr && !draft {
+        crate::restoration::loop_restoration(fs, &up_cur, up_cdef.as_ref().unwrap_or(&up_cur))
+    } else {
+        up_cdef.unwrap_or(up_cur)
+    };
    stats.add(Stage::Restoration, t.lap());
 }

@@ -215,7 +215,7 @@ impl FrameState {
                prev_segment_ids: vec![0; mi_cols * mi_rows],
            },
            cur,
-            mi: MiInfo::new(mi_cols, mi_rows),
+            mi: MiInfo::new(mi_cols, mi_rows, fh.allow_screen_content_tools),
            cdef: vec![-1; cdef_cols * cdef_rows],
            lf_tx_size: std::array::from_fn(|_| Grid8::new(0, 0, mi_cols + 32, mi_rows + 32)),
            lr,
@@ -260,7 +260,7 @@ impl FrameState {
        let x1 = if c1 >= mi_cols { usize::MAX } else { c1 * 4 };
        let y1 = if r1 >= mi_rows { usize::MAX } else { r1 * 4 };
        let cur = self.cur.region_like(c0 * 4, r0 * 4, x1, y1);
-        let mi = MiInfo::region(mi_cols, mi_rows, c0, r0, c1 - c0, r1 - r0);
+        let mi = MiInfo::region(mi_cols, mi_rows, c0, r0, c1 - c0, r1 - r0, !self.mi.palette_size[0].is_empty());
        let lf = std::array::from_fn(|p| {
            let (sx, sy) = if p == 0 { (0, 0) } else { (self.ssx, self.ssy) };
            let full = &self.lf_tx_size[p];
@@ -43,6 +43,8 @@ impl Stage {
 pub struct DecodeStats {
    /// Frames decoded (excluding show_existing_frame repeats).
    pub frames: u64,
+    /// Frames decoded in draft mode without in-loop filters.
+    pub draft_frames: u64,
    /// Tiles decoded.
    pub tiles: u64,
    /// Busy seconds per [`Stage`] (index with `stage as usize`).
@@ -60,6 +62,7 @@ impl DecodeStats {

    pub(crate) fn merge(&mut self, o: &DecodeStats) {
        self.frames += o.frames;
+        self.draft_frames += o.draft_frames;
        self.tiles += o.tiles;
        for (a, b) in self.stage_secs.iter_mut().zip(o.stage_secs.iter()) {
            *a += b;
@@ -127,17 +127,12 @@ impl<'a> SymbolDecoder<'a> {
 pub(crate) fn update_cdf(cdf: &mut [u16], n: usize, symbol: usize) {
    let count = cdf[n];
    let rate = 3 + (count > 15) as u32 + (count > 31) as u32 + (31 - (n as u32).leading_zeros()).min(2);
-    let mut tmp = 0u32;
-    for i in 0..n - 1 {
-        if i == symbol {
-            tmp = 1 << 15;
-        }
-        let c = cdf[i] as u32;
-        if tmp < c {
-            cdf[i] = (c - ((c - tmp) >> rate)) as u16;
-        } else {
-            cdf[i] = (c + ((tmp - c) >> rate)) as u16;
-        }
+    // Entries below `symbol` move towards 0, the others towards 1 << 15 (the specification's
+    // comparison with tmp, resolved per entry: c >= 0 and c <= 1 << 15), without branching on
+    // the decoded symbol.
+    for (i, e) in cdf[..n - 1].iter_mut().enumerate() {
+        let c = *e as u32;
+        *e = if i < symbol { c - (c >> rate) } else { c + (((1 << 15) - c) >> rate) } as u16;
    }
    cdf[n] += (count < 32) as u16;
 }
@@ -474,10 +474,12 @@ impl<'a, 'f> TileDecoder<'a, 'f> {
            mi.tx_size[span.clone()].fill(b.tx_size as u8);
            mi.mi_size[span.clone()].fill(b.mi_size as u8);
            mi.segment_id[span.clone()].fill(b.segment_id as u8);
-            mi.palette_size[0][span.clone()].fill(b.palette_size_y as u8);
-            mi.palette_size[1][span.clone()].fill(b.palette_size_uv as u8);
-            mi.palette_colors[0][span.clone()].fill(b.palette_colors_y);
-            mi.palette_colors[1][span.clone()].fill(b.palette_colors_u);
+            if !mi.palette_size[0].is_empty() {
+                mi.palette_size[0][span.clone()].fill(b.palette_size_y as u8);
+                mi.palette_size[1][span.clone()].fill(b.palette_size_uv as u8);
+                mi.palette_colors[0][span.clone()].fill(b.palette_colors_y);
+                mi.palette_colors[1][span.clone()].fill(b.palette_colors_u);
+            }
            mi.delta_lf[span.clone()].fill(dlf);
            mi.motion_mode[span].fill(b.motion_mode);
        }
@@ -76,7 +76,7 @@ pub fn reference(ff: &Path, path: &Path, pix_fmt: &str) -> Vec<u16> {
        .expect("run ffmpeg");
    assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
    if pix_fmt.ends_with("le") {
-        out.stdout.chunks_exact(2).map(|c| u16::from_le_bytes([c[0], c[1]])).collect()
+        out.stdout.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]])).collect()
    } else {
        out.stdout.iter().map(|&b| b as u16).collect()
    }
@@ -89,7 +89,13 @@ pub fn decode_all(path: &Path) -> Result<Vec<Picture>, String> {

 /// Decode every frame of an IVF file with a decoder using `threads` threads.
 pub fn decode_all_threads(path: &Path, threads: usize) -> Result<Vec<Picture>, String> {
+    decode_all_opts(path, threads, false)
+}
+
+/// [`decode_all_threads`] with draft mode on or off.
+pub fn decode_all_opts(path: &Path, threads: usize, draft: bool) -> Result<Vec<Picture>, String> {
    let mut dec = Decoder::with_threads(threads);
+    dec.set_draft(draft);
    let mut pics = Vec::new();
    for (i, f) in ivf_frames(path).iter().enumerate() {
        let p = dec.decode_pts(f, i as i64).map_err(|e| format!("frame {i}: {e}"))?;
@@ -174,6 +180,7 @@ pub fn check_file(ff: &Path, name: &str, path: &Path) {
        assert!(a == b, "{name}: frame {i} differs with {threads} threads");
    }
    assert!(!pics.is_empty(), "{name}: no frames");
+    assert!(pics.iter().all(|p| !p.draft), "{name}: picture flagged draft without draft mode");
    let raw = reference(ff, path, pix_fmt_for(&pics[0]));
    let per = picture_samples(&pics[0]);
    assert_eq!(raw.len(), per * pics.len(), "{name}: frame count/size ({} pictures)", pics.len());
@@ -40,6 +40,34 @@ fn inter_gops() {
    }
 }

+/// Draft mode: frames that refresh no reference slot skip the in-loop filters and are flagged;
+/// every other picture stays bit-exact, with 1 and several threads.
+#[test]
+fn draft_mode_changes_only_flagged_non_reference_frames() {
+    let Some(ff) = ffmpeg() else { return };
+    let s = &specs()[0];
+    let path = make(&ff, s);
+    let first = decode_all_threads(&path, 1).expect("decode");
+    let raw = reference(&ff, &path, pix_fmt_for(&first[0]));
+    let per = picture_samples(&first[0]);
+    for threads in [1, 4] {
+        let pics = decode_all_opts(&path, threads, true).expect("decode");
+        assert_eq!(pics.len(), first.len(), "threads {threads}");
+        let (mut draft, mut changed) = (0, 0);
+        for (i, p) in pics.iter().enumerate() {
+            let (_, count) = compare(p, &raw[i * per..(i + 1) * per]);
+            if p.draft {
+                draft += 1;
+                changed += (count > 0) as usize;
+            } else {
+                assert_eq!(count, 0, "threads {threads}: unflagged frame {i} differs");
+            }
+        }
+        assert!(draft > 0, "threads {threads}: no non-reference frames");
+        assert!(changed > 0, "threads {threads}: draft frames identical to the filtered ones");
+    }
+}
+
 /// Several tiles (decoded in parallel into private buffers, then merged).
 fn specs_tiles() -> Vec<Spec> {
    let p = |preset: &'static str, params: &'static str| -> Vec<&'static str> { vec!["-preset", preset, "-crf", "32", "-svtav1-params", params] };
@@ -5,6 +5,8 @@
 //! - [`unescape_rbsp`] / [`escape_rbsp`]: remove/insert H.264/HEVC emulation-prevention bytes.
 //! - [`annexb_nals`] / [`length_prefixed_nals`]: split Annex-B byte streams and AVCC/HVCC samples into NAL units.

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 use std::fmt;

 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -15,6 +15,8 @@
 //! - **Burn-in:** [`burn`] lays a caption out with the track style and draws it with the
 //!   `filmcraft-text` engine (Inter SemiBold, shaped and kerned).

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 pub mod burn;
 pub mod cea608;
 pub mod mcc;
@@ -212,7 +214,7 @@ pub fn parse(bytes: &[u8], format: Format) -> Result<Document> {
        Format::Scc => scc::parse(&text),
        Format::Mcc => mcc::parse(&text),
        Format::Ttml | Format::Dfxp => ttml::parse(&text),
-        Format::Stl => unreachable!("handled above"),
+        Format::Stl => stl::parse(bytes),
    }
 }

@@ -253,7 +255,7 @@ pub fn decode_text(bytes: &[u8]) -> String {
    } else if bytes.starts_with(&[0xff, 0xfe]) || bytes.starts_with(&[0xfe, 0xff]) {
        let le = bytes[0] == 0xff;
        let units: Vec<u16> =
-            bytes[2..].chunks_exact(2).map(|c| if le { u16::from_le_bytes([c[0], c[1]]) } else { u16::from_be_bytes([c[0], c[1]]) }).collect();
+            bytes[2..].as_chunks::<2>().0.iter().map(|c| if le { u16::from_le_bytes([c[0], c[1]]) } else { u16::from_be_bytes([c[0], c[1]]) }).collect();
        String::from_utf16_lossy(&units)
    } else {
        match std::str::from_utf8(bytes) {
@@ -411,10 +411,10 @@ impl Dec708 {
    }
    fn put(&mut self, c: char) {
        let w = self.w();
-        if w.rows.is_empty() {
-            w.rows.push(String::new());
+        match w.rows.last_mut() {
+            Some(row) => row.push(c),
+            None => w.rows.push(c.to_string()),
        }
-        w.rows.last_mut().expect("row").push(c);
    }
    fn bitmap(&mut self, m: u8, f: impl Fn(&mut Win)) {
        for (i, w) in self.win.iter_mut().enumerate() {
@@ -251,7 +251,9 @@ pub fn parse(bytes: &[u8]) -> Result<Document> {
    if !sniff(bytes) {
        return Err(Error::NotFormat("EBU STL"));
    }
-    let rate = rate_of(&bytes[3..11]).expect("sniffed");
+    let Some(rate) = bytes.get(3..11).and_then(rate_of) else {
+        return Err(Error::NotFormat("EBU STL"));
+    };
    let gsi = &bytes[..GSI];
    // start of programme (HHMMSSFF, ASCII)
    let tcp = ascii_field(&gsi[256..264]);
@@ -277,7 +279,7 @@ pub fn parse(bytes: &[u8]) -> Result<Document> {
            }
        }
    };
-    for blk in bytes[GSI..].chunks_exact(TTI) {
+    for blk in bytes[GSI..].as_chunks::<TTI>().0 {
        let sn = u16::from_le_bytes([blk[1], blk[2]]);
        let ebn = blk[3];
        let cf = blk[15];
@@ -103,7 +103,7 @@ fn inline(text: &str) -> String {
            rest = &after[end + 1..];
            continue;
        }
-        let ch = rest.chars().next().expect("non-empty");
+        let Some(ch) = rest.chars().next() else { break };
        if ch == '\n' {
            out.push_str("<br/>");
        } else {
@@ -184,28 +184,45 @@ struct Timing {
    tick_rate: i64,
 }

+fn positive_integer(s: &str) -> Option<i64> {
+    let s = s.trim();
+    if s.is_empty() || !s.bytes().all(|b| b.is_ascii_digit()) {
+        return None;
+    }
+    s.parse::<i64>().ok().filter(|v| *v > 0)
+}
+
 fn parse_ratio(s: &str) -> Option<(i64, i64)> {
-    let mut it = s.split_whitespace().map(|x| x.parse::<i64>().ok());
+    let mut it = s.split_whitespace().map(positive_integer);
    let a = it.next()??;
-    let b = it.next().flatten().unwrap_or(1);
-    (a > 0 && b > 0).then_some((a, b))
+    let b = it.next()??;
+    it.next().is_none().then_some((a, b))
 }

 fn attr<'a>(n: roxmltree::Node<'a, '_>, local: &str) -> Option<&'a str> {
    n.attributes().find(|a| a.name() == local).map(|a| a.value())
 }

-fn timing(root: roxmltree::Node) -> Timing {
-    let base = attr(root, "frameRate").and_then(|v| v.trim().parse::<i64>().ok()).filter(|v| *v > 0).unwrap_or(30);
-    let (mn, md) = attr(root, "frameRateMultiplier").and_then(parse_ratio).unwrap_or((1, 1));
-    let rate = FrameRate::new(base * mn, md);
-    let sub = attr(root, "subFrameRate").and_then(|v| v.trim().parse::<i64>().ok()).filter(|v| *v > 0).unwrap_or(1);
-    let tick_rate = attr(root, "tickRate").and_then(|v| v.trim().parse::<i64>().ok()).filter(|v| *v > 0).unwrap_or(if attr(root, "frameRate").is_some() {
-        base * sub
-    } else {
-        1
-    });
-    Timing { rate, base, sub_frame_rate: sub, tick_rate }
+fn timing(root: roxmltree::Node) -> Result<Timing> {
+    let invalid =
+        |name: &str| Error::Syntax { line: root.document().text_pos_at(root.range().start).row as usize, msg: format!("invalid TTML timing parameter {name}") };
+    let integer = |name: &str, default| match attr(root, name) {
+        Some(v) => positive_integer(v).ok_or_else(|| invalid(name)),
+        None => Ok(default),
+    };
+    let base = integer("frameRate", 30)?;
+    let (mn, md) = match attr(root, "frameRateMultiplier") {
+        Some(v) => parse_ratio(v).ok_or_else(|| invalid("frameRateMultiplier"))?,
+        None => (1, 1),
+    };
+    let rate = FrameRate::new(base.checked_mul(mn).ok_or_else(|| invalid("frameRateMultiplier"))?, md);
+    let sub = integer("subFrameRate", 1)?;
+    let tick_rate = match attr(root, "tickRate") {
+        Some(v) => positive_integer(v).ok_or_else(|| invalid("tickRate"))?,
+        None if attr(root, "frameRate").is_some() => base.checked_mul(sub).ok_or_else(|| invalid("subFrameRate"))?,
+        None => 1,
+    };
+    Ok(Timing { rate, base, sub_frame_rate: sub, tick_rate })
 }

 /// Seconds as an exact decimal string → ticks.
@@ -383,7 +400,7 @@ pub fn parse(text: &str) -> Result<Document> {
    if root.tag_name().name() != "tt" {
        return Err(Error::NotFormat("TTML"));
    }
-    let tm = timing(root);
+    let tm = timing(root)?;
    let mut styles = std::collections::HashMap::new();
    for s in root.descendants().filter(|n| n.is_element() && n.tag_name().name() == "style") {
        if let Some(id) = s.attributes().find(|a| a.name() == "id").map(|a| a.value()) {
@@ -478,6 +495,44 @@ mod tests {
        Timing { rate, base: rate.timecode_base(), sub_frame_rate: 1, tick_rate: 1 }
    }

+    #[test]
+    fn invalid_timing_parameters_return_an_error() {
+        for params in [
+            r#"ttp:frameRate="0""#,
+            r#"ttp:frameRate="-25""#,
+            r#"ttp:frameRate="""#,
+            r#"ttp:subFrameRate="0""#,
+            r#"ttp:tickRate="-1""#,
+            r#"ttp:frameRateMultiplier="1 0""#,
+            r#"ttp:frameRateMultiplier="1""#,
+            r#"ttp:frameRateMultiplier="1 2 3""#,
+        ] {
+            let xml = format!(
+                r#"<tt xmlns="http://www.w3.org/ns/ttml" xmlns:ttp="http://www.w3.org/ns/ttml#parameter" {params}><body><div><p begin="1s" end="2s">Hello</p></div></body></tt>"#
+            );
+            assert!(crate::parse(xml.as_bytes(), crate::Format::Ttml).is_err(), "{params}");
+        }
+    }
+
+    #[test]
+    fn missing_timing_parameters_keep_defaults() {
+        for (params, begin, end) in [
+            ("", "1s", "2s"),
+            (r#"ttp:frameRate="25""#, "25f", "50f"),
+            (r#"ttp:frameRate="30" ttp:subFrameRate="2""#, "60t", "120t"),
+            (r#"ttp:frameRate="30" ttp:subFrameRate="2" ttp:tickRate="10""#, "10t", "20t"),
+            (r#"ttp:frameRate="25" ttp:frameRateMultiplier="2 1""#, "50f", "100f"),
+        ] {
+            let xml = format!(
+                r#"<tt xmlns="http://www.w3.org/ns/ttml" xmlns:ttp="http://www.w3.org/ns/ttml#parameter" {params}><body><div><p begin="{begin}" end="{end}">Hello</p></div></body></tt>"#
+            );
+            let doc = crate::parse(xml.as_bytes(), crate::Format::Ttml).unwrap();
+            assert_eq!(doc.cues.len(), 1, "{params}");
+            assert_eq!(doc.cues[0].start, Tick(TICKS_PER_SECOND), "{params}");
+            assert_eq!(doc.cues[0].end, Tick(2 * TICKS_PER_SECOND), "{params}");
+        }
+    }
+
    #[test]
    fn time_expressions() {
        let t = tm(FrameRate::FPS_25);
@@ -15,6 +15,8 @@
 //!
 //! Layer L0: no dependencies beyond `std`, no `unsafe`, builds for `wasm32-unknown-unknown`.

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 mod read;
 mod write;

@@ -143,7 +143,7 @@ impl<'a> CompoundFile<'a> {
        // Mini FAT and mini stream.
        if first_minifat <= MAXREGSECT {
            let mf = cf.read_chain(first_minifat, None)?;
-            cf.minifat = mf.chunks_exact(4).map(|c| u32::from_le_bytes([c[0], c[1], c[2], c[3]])).collect();
+            cf.minifat = mf.as_chunks::<4>().0.iter().map(|c| u32::from_le_bytes([c[0], c[1], c[2], c[3]])).collect();
        }
        let root = &cf.entries[0];
        if root.start <= MAXREGSECT && root.size > 0 {
@@ -28,6 +28,7 @@ filmcraft-vp9 = { workspace = true }
 filmcraft-prores = { workspace = true }
 filmcraft-dnx = { workspace = true }
 filmcraft-av1 = { workspace = true }
+filmcraft-apv = { workspace = true }
 filmcraft-aac = { workspace = true }
 filmcraft-opus = { workspace = true }
 thiserror = { workspace = true }
@@ -36,7 +37,7 @@ log = { workspace = true }
 web-time = "1"
 image = { version = "0.25", default-features = false, features = ["jpeg"] }
 # Bootstrap audio decoding (MPL-2.0, used unmodified); replaced by own decoders over time.
-symphonia = { version = "0.5.5", default-features = false, features = ["aac", "mp1", "mp2", "mp3", "flac", "alac", "pcm", "wav", "ogg", "vorbis", "isomp4"] }
+symphonia = { version = "0.5.5", default-features = false, features = ["aac", "mp1", "mp2", "mp3", "flac", "alac", "pcm", "wav", "aiff", "ogg", "vorbis", "isomp4"] }

 [dev-dependencies]
 filmcraft-testkit = { workspace = true }
@@ -0,0 +1,177 @@
+//! Standalone APV raw bitstream source (RFC 9924 Appendix A: `.apv` elementary streams).
+//!
+//! Each access unit in a raw bitstream is prefixed by a 4-byte big-endian `au_size` followed by
+//! the `'aPv1'` signature (unprefixed single-AU streams starting directly with `'aPv1'` are also
+//! accepted). Every frame is intra-coded, so random access is direct.
+
+use std::sync::Arc;
+
+use filmcraft_color::{ColorInfo, Matrix, Range, Transfer};
+use filmcraft_frame::{AudioBuffer, VideoFrame};
+use filmcraft_media::{FrameRequest, MediaError, MediaInfo, MediaKind, MediaSource, SharedSource, VideoStreamInfo};
+use filmcraft_time::{FrameRate, Tick};
+
+use crate::CodecError;
+use crate::gop::{GopCache, VideoSamples};
+use crate::video::{ApvDecoder, VideoDecoder, primaries_from_code};
+
+/// Sniff a raw APV bitstream: either a `raw_bitstream_access_unit()` (`[au_size: u32]['aPv1']`) or
+/// an unprefixed `access_unit()` starting with `'aPv1'`.
+pub fn sniff(head: &[u8]) -> bool {
+    (head.len() >= 8 && &head[4..8] == b"aPv1" && u32::from_be_bytes([head[0], head[1], head[2], head[3]]) >= 8) || head.starts_with(b"aPv1")
+}
+
+pub struct ApvSource {
+    info: MediaInfo,
+    bytes: crate::Src,
+    samples: Vec<(u64, u32)>,
+    rate: FrameRate,
+    video: GopCache,
+}
+
+pub(crate) fn apv_pixfmt_label(chroma: filmcraft_apv::ChromaFormat, bit_depth: u8) -> String {
+    let sub = match chroma {
+        filmcraft_apv::ChromaFormat::Monochrome => "Monochrome",
+        filmcraft_apv::ChromaFormat::Yuv422 => "YUV 4:2:2",
+        filmcraft_apv::ChromaFormat::Yuv444 => "YUV 4:4:4",
+        filmcraft_apv::ChromaFormat::Yuv4444 => "YUVA 4:4:4:4",
+    };
+    format!("{sub} {bit_depth}-bit")
+}
+
+impl ApvSource {
+    pub fn open(name: &str, bytes: Arc<[u8]>) -> crate::Result<Self> {
+        Self::open_reader(name, Arc::new(filmcraft_media::reader::MemReader(bytes)))
+    }
+
+    pub fn open_reader(name: &str, reader: filmcraft_media::SharedReader) -> crate::Result<Self> {
+        let len = reader.len();
+        let mut samples = Vec::new();
+        let mut pos = 0u64;
+        let mut hdr = [0u8; 8];
+        while pos + 8 <= len {
+            if reader.read_at(pos, &mut hdr).is_err() {
+                break;
+            }
+            if &hdr[4..8] == b"aPv1" {
+                let sz = u32::from_be_bytes([hdr[0], hdr[1], hdr[2], hdr[3]]);
+                if sz < 8 || pos + 4 + sz as u64 > len {
+                    break;
+                }
+                samples.push((pos + 4, sz));
+                pos += 4 + sz as u64;
+            } else if pos == 0 && &hdr[0..4] == b"aPv1" && len <= u32::MAX as u64 {
+                samples.push((0, len as u32));
+                break;
+            } else {
+                break;
+            }
+        }
+        let Some(&(off0, sz0)) = samples.first() else {
+            return Err(CodecError::Container("APV: no valid access units".into()));
+        };
+        let first = filmcraft_media::reader::read_range(&*reader, off0, sz0 as usize).map_err(|e| CodecError::Container(e.to_string()))?;
+        let fh = filmcraft_apv::probe(&first).map_err(|e| CodecError::Decode(e.to_string()))?;
+        let mut color = ColorInfo { matrix: filmcraft_frame::default_matrix(fh.width, fh.height), ..ColorInfo::REC709 };
+        let mut explicit_color = None;
+        if fh.color_description_present {
+            if let Some(m) = Matrix::from_code(fh.color.matrix) {
+                color.matrix = m;
+            }
+            if let Some(t) = Transfer::from_code(fh.color.transfer) {
+                color.transfer = t;
+            }
+            if let Some(p) = primaries_from_code(fh.color.primaries) {
+                color.primaries = p;
+            }
+            if fh.color.full_range {
+                color.range = Range::Full;
+            }
+            explicit_color = Some(color);
+        }
+        let rate = FrameRate::FPS_24;
+        let duration = Tick::from_rational(samples.len() as i64 * rate.den, 1, rate.num);
+        let total_bits: u64 = samples.iter().map(|s| s.1 as u64 * 8).sum();
+        let secs = duration.seconds();
+        let bitrate = (secs > 0.0).then(|| (total_bits as f64 / secs) as u64);
+        let codec = match filmcraft_apv::Profile::from_idc(fh.profile_idc) {
+            Some(p) => p.name().into(),
+            None => "APV".into(),
+        };
+        let info = MediaInfo {
+            name: name.to_string(),
+            kind: MediaKind::Movie,
+            duration,
+            video: Some(VideoStreamInfo {
+                width: fh.width,
+                height: fh.height,
+                frame_rate: rate,
+                par: (1, 1),
+                codec,
+                pixel_format: apv_pixfmt_label(fh.chroma, fh.bit_depth),
+                color,
+                has_alpha: fh.chroma == filmcraft_apv::ChromaFormat::Yuv4444,
+                bitrate,
+                hdr: None,
+            }),
+            audio: None,
+            container: "APV".into(),
+            start_timecode: None,
+            file_size: Some(len),
+        };
+        Ok(Self { info, bytes: crate::Src(reader), samples, rate, video: GopCache::new(explicit_color) })
+    }
+}
+
+struct ApvVideo<'a>(&'a ApvSource);
+
+impl VideoSamples for ApvVideo<'_> {
+    fn count(&self) -> usize {
+        self.0.samples.len()
+    }
+    fn pts(&self, i: usize) -> i64 {
+        i as i64
+    }
+    fn sync_before(&self, i: usize) -> usize {
+        i
+    }
+    fn sample_at(&self, t: i64) -> Option<usize> {
+        (!self.0.samples.is_empty()).then(|| t.clamp(0, self.0.samples.len() as i64 - 1) as usize)
+    }
+    fn read(&self, i: usize) -> crate::Result<Vec<u8>> {
+        let (off, sz) = self.0.samples.get(i).copied().ok_or_else(|| CodecError::Container("sample index out of range".into()))?;
+        filmcraft_media::reader::read_range(&*self.0.bytes.0, off, sz as usize).map_err(|e| CodecError::Container(e.to_string()))
+    }
+    fn make_decoder(&self) -> crate::Result<Box<dyn VideoDecoder>> {
+        Ok(Box::new(ApvDecoder))
+    }
+}
+
+impl MediaSource for ApvSource {
+    fn info(&self) -> &MediaInfo {
+        &self.info
+    }
+
+    fn video_frame(&self, req: FrameRequest) -> Result<Arc<VideoFrame>, MediaError> {
+        let frame_idx = self.rate.frame_at(req.time.max(Tick::ZERO));
+        Ok(self.video.frame(&ApvVideo(self), frame_idx)?)
+    }
+
+    fn audio(&self, _start: i64, _frames: usize, _sample_rate: u32) -> Result<AudioBuffer, MediaError> {
+        Err(MediaError::NoStream("audio"))
+    }
+}
+
+pub fn opener(name: &str, bytes: Arc<[u8]>) -> Option<Result<SharedSource, MediaError>> {
+    if !sniff(&bytes) {
+        return None;
+    }
+    Some(ApvSource::open(name, bytes).map(|s| Arc::new(s) as SharedSource).map_err(Into::into))
+}
+
+pub fn reader_opener(name: &str, head: &[u8], reader: &filmcraft_media::SharedReader) -> Option<Result<SharedSource, MediaError>> {
+    if !sniff(head) {
+        return None;
+    }
+    Some(ApvSource::open_reader(name, reader.clone()).map(|s| Arc::new(s) as SharedSource).map_err(Into::into))
+}
@@ -15,8 +15,8 @@ use symphonia::core::probe::Hint;
 use crate::{CodecError, Result};

 enum Inner {
-    /// Our own AAC-LC decoder.
-    Aac { dec: Box<filmcraft_aac::Decoder>, asc: Vec<u8> },
+    /// Our own AAC-LC decoder. `up` interpolates HE-AAC's core to the output rate (see [`Upsample2x`]).
+    Aac { dec: Box<filmcraft_aac::Decoder>, asc: Vec<u8>, up: Option<Box<Upsample2x>> },
    /// AAC whose configuration arrives with the first frame (ADTS / LATM).
    AacPending,
    /// Our own Opus decoder (always 48 kHz output; pre-skip is left to container timestamps).
@@ -82,11 +82,13 @@ impl PacketDecoder {
        let dec = symphonia::default::get_codecs().make(&p, &DecoderOptions::default()).map_err(|e| CodecError::Unsupported(e.to_string()))?;
        Ok(Self { inner: Inner::Symphonia(dec), channels: 0 })
    }
-    /// AAC: our decoder for AAC-LC; symphonia for other object types (HE-AAC…).
+    /// AAC: our decoder for AAC-LC and the AAC-LC core of HE-AAC (v1/v2); symphonia for other
+    /// object types. `sample_rate` is the stream's output rate: when it is twice the core rate
+    /// (HE-AAC, see [`aac_output_rate`]) the decoded core is upsampled to it.
    pub fn aac(asc: &[u8], sample_rate: u32) -> Result<Self> {
-        let lc = asc.first().map(|b| b >> 3) == Some(2);
-        if lc && let Ok(dec) = filmcraft_aac::Decoder::new(asc) {
-            return Ok(Self { inner: Inner::Aac { dec: Box::new(dec), asc: asc.to_vec() }, channels: 0 });
+        if let Ok(dec) = filmcraft_aac::Decoder::new(asc) {
+            let up = (dec.sample_rate().checked_mul(2) == Some(sample_rate)).then(|| Box::new(Upsample2x::new(dec.channels())));
+            return Ok(Self { inner: Inner::Aac { dec: Box::new(dec), asc: asc.to_vec(), up }, channels: 0 });
        }
        Self::new(CODEC_TYPE_AAC, sample_rate, Some(asc.to_vec()))
    }
@@ -119,7 +121,7 @@ impl PacketDecoder {
            return Ok(());
        }
        let dec = filmcraft_aac::Decoder::new(asc).map_err(|e| CodecError::Unsupported(format!("AAC: {e}")))?;
-        self.inner = Inner::Aac { dec: Box::new(dec), asc: asc.to_vec() };
+        self.inner = Inner::Aac { dec: Box::new(dec), asc: asc.to_vec(), up: None };
        Ok(())
    }
    /// AC-3 (ATSC A/52).
@@ -133,7 +135,7 @@ impl PacketDecoder {
    pub fn for_isobmff(c: &filmcraft_isobmff::CodecConfig, rate: u32) -> Result<Self> {
        use filmcraft_isobmff::CodecConfig as C;
        match c {
-            C::Aac(a) => Self::aac(&a.asc, if a.sample_rate > 0 { a.sample_rate } else { rate }),
+            C::Aac(a) => Self::aac(&a.asc, if rate > 0 { rate } else { a.sample_rate }),
            C::Mp3 => Self::new(CODEC_TYPE_MP3, rate, None),
            C::Ac3 { .. } => Self::ac3(),
            C::Alac { cookie } => Self::new(CODEC_TYPE_ALAC, rate, Some(cookie.clone())),
@@ -145,8 +147,11 @@ impl PacketDecoder {
    /// Decode one packet into planar channels.
    pub fn decode(&mut self, data: &[u8], ts: u64) -> Result<Vec<Vec<f32>>> {
        let dec = match &mut self.inner {
-            Inner::Aac { dec, .. } => {
-                let out = dec.decode(data).map_err(|e| CodecError::Decode(e.to_string()))?;
+            Inner::Aac { dec, up, .. } => {
+                let mut out = dec.decode(data).map_err(|e| CodecError::Decode(e.to_string()))?;
+                if let Some(up) = up {
+                    out = up.process(out);
+                }
                self.channels = out.len();
                return Ok(out);
            }
@@ -202,10 +207,13 @@ impl PacketDecoder {
    }
    pub fn reset(&mut self) {
        match &mut self.inner {
-            Inner::Aac { dec, asc } => {
+            Inner::Aac { dec, asc, up } => {
                if let Ok(d) = filmcraft_aac::Decoder::new(asc) {
                    **dec = d;
                }
+                if let Some(up) = up {
+                    up.reset();
+                }
            }
            Inner::Opus { dec, .. } => dec.reset(),
            Inner::Symphonia(d) => d.reset(),
@@ -215,6 +223,94 @@ impl PacketDecoder {
    }
 }

+/// The output rate of an AAC stream: twice the core rate for HE-AAC (ISO/IEC 14496-3 §1.6.5).
+/// Explicit signalling names the rate in the `AudioSpecificConfig`; with implicit signalling (an
+/// AAC-LC config at 24 kHz or less) SBR is only visible as fill-element data in the access units,
+/// so the first ones are decoded to look for it. `None` if `asc` is not one our decoder reads.
+pub fn aac_output_rate<'a>(asc: &[u8], first_units: impl IntoIterator<Item = &'a [u8]>) -> Option<u32> {
+    let mut dec = filmcraft_aac::Decoder::new(asc).ok()?;
+    let core = dec.sample_rate();
+    if let Some(ext) = dec.config().extension_sample_rate {
+        return Some(ext);
+    }
+    if core <= 24_000 {
+        for au in first_units {
+            let _ = dec.decode(au);
+            if dec.sbr() {
+                return Some(core * 2);
+            }
+        }
+    }
+    Some(core)
+}
+
+/// Taps on each side of the interpolation point in [`Upsample2x`].
+const UPSAMPLE_HALF: usize = 12;
+
+/// 2× upsampler for HE-AAC. Our decoder reconstructs the AAC-LC core at half the output rate and
+/// not yet the SBR high band, so the core is interpolated to the output rate: timing and pitch are
+/// right and the band above the core's Nyquist stays empty. Even outputs are the input samples,
+/// odd ones a Blackman-windowed sinc half-band interpolation over 2 × [`UPSAMPLE_HALF`] inputs.
+/// The look-ahead delays the output by `UPSAMPLE_HALF` input samples (0.5 ms at 24 kHz); the
+/// state carries across packets, so a seek primed with the preceding packet gives the same
+/// samples as continuous decoding.
+#[derive(Clone)]
+pub struct Upsample2x {
+    taps: [f32; 2 * UPSAMPLE_HALF],
+    /// The last `2 × UPSAMPLE_HALF` input samples per channel.
+    hist: Vec<Vec<f32>>,
+}
+
+impl Upsample2x {
+    pub fn new(channels: usize) -> Self {
+        let m = UPSAMPLE_HALF as f64;
+        let mut taps = [0f32; 2 * UPSAMPLE_HALF];
+        let mut sum = 0.0;
+        for (k, t) in taps.iter_mut().enumerate() {
+            // distance from the interpolation point (halfway between two inputs)
+            let x = k as f64 - m + 0.5;
+            let sinc = (std::f64::consts::PI * x).sin() / (std::f64::consts::PI * x);
+            let w = 0.42 + 0.5 * (std::f64::consts::PI * x / m).cos() + 0.08 * (2.0 * std::f64::consts::PI * x / m).cos();
+            *t = (sinc * w) as f32;
+            sum += sinc * w;
+        }
+        for t in &mut taps {
+            *t = (*t as f64 / sum) as f32;
+        }
+        Self { taps, hist: vec![vec![0.0; 2 * UPSAMPLE_HALF]; channels] }
+    }
+
+    pub fn reset(&mut self) {
+        for h in &mut self.hist {
+            h.fill(0.0);
+        }
+    }
+
+    pub fn process(&mut self, input: Vec<Vec<f32>>) -> Vec<Vec<f32>> {
+        if self.hist.len() < input.len() {
+            self.hist.resize(input.len(), vec![0.0; 2 * UPSAMPLE_HALF]);
+        }
+        let m = UPSAMPLE_HALF;
+        input
+            .into_iter()
+            .zip(&mut self.hist)
+            .map(|(x, hist)| {
+                let mut buf = std::mem::take(hist);
+                buf.extend_from_slice(&x);
+                let mut out = Vec::with_capacity(x.len() * 2);
+                // output pair i is centred on buf[i + m]: the sample itself, then the point halfway
+                // to the next one from buf[i + 1 ..= i + 2m]
+                for w in buf.windows(2 * m + 1).take(x.len()) {
+                    out.push(w[m]);
+                    out.push(w[1..].iter().zip(&self.taps).map(|(a, b)| a * b).sum());
+                }
+                *hist = buf.split_off(buf.len() - 2 * m);
+                out
+            })
+            .collect()
+    }
+}
+
 /// Whether AC-3 audio decodes (our ATSC A/52 decoder).
 pub const AC3_DECODER: bool = true;

@@ -603,3 +699,43 @@ pub fn opener(name: &str, bytes: Arc<[u8]>) -> Option<std::result::Result<Shared
    }
    Some(AudioFileSource::decode(name, bytes).map(|s| Arc::new(s) as SharedSource).map_err(Into::into))
 }
+
+#[cfg(test)]
+mod he_aac_tests {
+    use super::*;
+
+    /// AAC-LC config, 22.05 kHz stereo.
+    const LC_22K: [u8; 2] = [0x13, 0x90];
+    /// An access unit holding only a fill element with SBR data (ID_FIL, EXT_SBR_DATA, ID_END).
+    const SBR_FILL: [u8; 3] = [0b1100_0011, 0b1010_0001, 0b1100_0000];
+
+    #[test]
+    fn output_rate_doubles_for_he_aac() {
+        // explicit: the extension rate from the config
+        assert_eq!(aac_output_rate(&[0x2B, 0x92, 0x08, 0x00], []), Some(44_100));
+        // implicit: SBR data in the first access units of a ≤ 24 kHz AAC-LC stream
+        assert_eq!(aac_output_rate(&LC_22K, [&SBR_FILL[..]]), Some(44_100));
+        assert_eq!(aac_output_rate(&LC_22K, []), Some(22_050));
+        // AAC-LC at 44.1 kHz stays as it is, even with SBR-looking fill data
+        assert_eq!(aac_output_rate(&[0x12, 0x10], [&SBR_FILL[..]]), Some(44_100));
+    }
+
+    #[test]
+    fn upsampler_interpolates_continuously_across_packets() {
+        let f = 1000.0 / 22_050.0;
+        let x: Vec<f32> = (0..4096).map(|i| (2.0 * std::f32::consts::PI * f * i as f32).sin()).collect();
+        let mut up = Upsample2x::new(1);
+        let mut y = Vec::new();
+        for chunk in x.chunks(1024) {
+            y.extend(up.process(vec![chunk.to_vec()]).remove(0));
+        }
+        assert_eq!(y.len(), 8192);
+        // output 2k + 1 is input k − UPSAMPLE_HALF + ½ (the look-ahead delay), within 0.1 %
+        let d = UPSAMPLE_HALF as f32;
+        for k in 100..4000 {
+            let want = (2.0 * std::f32::consts::PI * f * (k as f32 - d + 0.5)).sin();
+            assert!((y[2 * k + 1] - want).abs() < 1e-3, "{k}: {} vs {want}", y[2 * k + 1]);
+            assert_eq!(y[2 * k], x[k - UPSAMPLE_HALF]);
+        }
+    }
+}
@@ -5,8 +5,11 @@
 //! for the next frames therefore hit the cache or continue the running decoder without re-seeking.

 use std::collections::BTreeMap;
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::sync::{Arc, Mutex};
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex, MutexGuard, PoisonError, TryLockError, Weak};
+use std::time::Duration;
+
+use web_time::Instant;

 use filmcraft_color::ColorInfo;
 use filmcraft_frame::VideoFrame;
@@ -33,6 +36,9 @@ pub struct GopStats {
    pub skipped: u64,
    /// Frames decoded in draft mode (reduced-resolution playback, [`VideoDecoder::set_draft`]).
    pub draft: u64,
+    /// Pictures decoders output (hardware and software; [`crate::hw::hw_stats`] counts the
+    /// hardware ones).
+    pub frames: u64,
 }

 impl GopStats {
@@ -56,10 +62,16 @@ static EVICTED: AtomicU64 = AtomicU64::new(0);
 static DECODE_NS: AtomicU64 = AtomicU64::new(0);
 static SKIPPED: AtomicU64 = AtomicU64::new(0);
 static DRAFT: AtomicU64 = AtomicU64::new(0);
+static FRAMES: AtomicU64 = AtomicU64::new(0);
+
+/// Count pictures a decoder call output.
+fn count_frames<T>(out: &[T]) {
+    FRAMES.fetch_add(out.len() as u64, Ordering::Relaxed);
+}

 /// Run a decoder call, adding its wall time to the process-wide counter.
 fn timed<R>(f: impl FnOnce() -> R) -> R {
-    let t0 = web_time::Instant::now();
+    let t0 = Instant::now();
    let r = f();
    DECODE_NS.fetch_add(t0.elapsed().as_nanos() as u64, Ordering::Relaxed);
    r
@@ -76,6 +88,7 @@ pub fn gop_stats() -> GopStats {
        decode_ns: DECODE_NS.load(Ordering::Relaxed),
        skipped: SKIPPED.load(Ordering::Relaxed),
        draft: DRAFT.load(Ordering::Relaxed),
+        frames: FRAMES.load(Ordering::Relaxed),
    }
 }

@@ -91,6 +104,7 @@ impl std::ops::Sub for GopStats {
            decode_ns: self.decode_ns - o.decode_ns,
            skipped: self.skipped - o.skipped,
            draft: self.draft - o.draft,
+            frames: self.frames - o.frames,
        }
    }
 }
@@ -124,9 +138,35 @@ struct State {
    /// The cached frames that were decoded in draft mode: served to draft requests only.
    drafts: std::collections::BTreeSet<i64>,
    bytes: usize,
+    /// When a frame was last asked of this cache.
+    last_used: Instant,
 }

 impl State {
+    /// Give up the decoder (and the spare intra decoders): the next request that has to decode
+    /// makes a new one and restarts at a sync sample. Returned so they are dropped off the lock.
+    fn release_decoder(&mut self, pool: &Pool) -> Vec<Box<dyn VideoDecoder>> {
+        let mut out = std::mem::take(&mut self.spare);
+        if let Some(d) = self.decoder.take() {
+            pool.decoders.fetch_sub(1, Ordering::Relaxed);
+            out.push(d);
+        }
+        self.next = usize::MAX;
+        out
+    }
+
+    /// Evict frames, earliest first, while `more` says so.
+    fn release_frames(&mut self, pool: &Pool, more: impl Fn() -> bool) {
+        while more() {
+            let Some((pts, f)) = self.frames.pop_first() else { break };
+            self.drafts.remove(&pts);
+            self.bytes = self.bytes.saturating_sub(f.byte_size());
+            pool.bytes.fetch_sub(f.byte_size(), Ordering::Relaxed);
+            EVICTED.fetch_add(1, Ordering::Relaxed);
+            filmcraft_frame::pool::recycle(f);
+        }
+    }
+
    /// The cached frame at `pts`, unless it is a draft frame and the request wants the exact one.
    fn cached(&self, pts: i64, draft_ok: bool) -> Option<&Arc<VideoFrame>> {
        self.frames.get(&pts).filter(|_| draft_ok || !self.drafts.contains(&pts))
@@ -167,11 +207,144 @@ impl Drop for DecodingGuard {
    }
 }

+/// A decoder keeps its reference and in-flight pictures (hundreds of MB for a frame-threaded
+/// 4K decoder), so only this many caches keep theirs once idle: a timeline's other clips make a
+/// new one when the playhead reaches them, which costs what a seek costs.
+const MAX_LIVE_DECODERS: usize = 4;
+
+/// A cache asked for a frame this recently is in use (a layer of the frame being composited,
+/// the next clip being prefetched): it keeps its decoder whatever the count.
+const IDLE: Duration = Duration::from_secs(3);
+
+/// Decoded frames all caches may hold together before idle ones give theirs up. Each cache also
+/// has its own budget, which alone let every clip on a timeline keep hundreds of MB of frames
+/// nobody was looking at.
+pub const FRAME_BUDGET: usize = 1 << 30;
+
+/// What the caches of a process share: the cap on live decoders and the frame budget.
+struct Pool {
+    caches: Mutex<Vec<Weak<Shared>>>,
+    /// Caches that hold a decoder.
+    decoders: AtomicUsize,
+    max_decoders: usize,
+    idle: Duration,
+    /// Bytes of the frames the caches hold.
+    bytes: AtomicUsize,
+    budget: usize,
+}
+
+/// The part of a [`GopCache`] its pool reaches.
+struct Shared {
+    state: Mutex<State>,
+    pool: Arc<Pool>,
+}
+
+impl Drop for Shared {
+    fn drop(&mut self) {
+        let st = self.state.get_mut().unwrap_or_else(PoisonError::into_inner);
+        drop(st.release_decoder(&self.pool));
+        self.pool.bytes.fetch_sub(st.bytes, Ordering::Relaxed);
+    }
+}
+
+/// A cache's state unless another thread is using it (it is then decoding: not idle).
+fn try_state(c: &Shared) -> Option<MutexGuard<'_, State>> {
+    match c.state.try_lock() {
+        Ok(g) => Some(g),
+        Err(TryLockError::Poisoned(e)) => Some(e.into_inner()),
+        Err(TryLockError::WouldBlock) => None,
+    }
+}
+
+impl Pool {
+    fn new(max_decoders: usize, idle: Duration, budget: usize) -> Self {
+        Self { caches: Mutex::new(Vec::new()), decoders: AtomicUsize::new(0), max_decoders, idle, bytes: AtomicUsize::new(0), budget }
+    }
+
+    /// The pool of every cache in the process.
+    fn global() -> Arc<Pool> {
+        static POOL: std::sync::OnceLock<Arc<Pool>> = std::sync::OnceLock::new();
+        POOL.get_or_init(|| Arc::new(Pool::new(MAX_LIVE_DECODERS, IDLE, FRAME_BUDGET))).clone()
+    }
+
+    fn register(&self, c: &Arc<Shared>) {
+        let mut g = self.caches.lock().unwrap_or_else(PoisonError::into_inner);
+        g.retain(|w| w.strong_count() > 0);
+        g.push(Arc::downgrade(c));
+    }
+
+    /// The idle caches other than `me` that `keep` selects, least recently used first. Other
+    /// caches are only ever try-locked, so two caches trimming each other cannot deadlock.
+    fn idle_others(&self, me: &Shared, keep: impl Fn(&State) -> bool) -> Vec<Arc<Shared>> {
+        let all: Vec<Arc<Shared>> = self.caches.lock().unwrap_or_else(PoisonError::into_inner).iter().filter_map(Weak::upgrade).collect();
+        let mut idle: Vec<(Instant, Arc<Shared>)> = all
+            .into_iter()
+            .filter(|c| !std::ptr::eq(Arc::as_ptr(c), me))
+            .filter_map(|c| {
+                let used = try_state(&c).filter(|st| keep(st) && st.last_used.elapsed() >= self.idle).map(|st| st.last_used)?;
+                Some((used, c))
+            })
+            .collect();
+        idle.sort_by_key(|(used, _)| *used);
+        idle.into_iter().map(|(_, c)| c).collect()
+    }
+
+    /// Take the decoders of idle caches, least recently used first, down to the cap. The caller
+    /// drops them with no cache lock held: dropping a decoder can block (a hardware session waits
+    /// for its frames in flight).
+    #[must_use = "drop the released decoders with no cache lock held"]
+    fn trim_decoders(&self, me: &Shared) -> Vec<Box<dyn VideoDecoder>> {
+        let mut released = Vec::new();
+        if self.decoders.load(Ordering::Relaxed) <= self.max_decoders {
+            return released;
+        }
+        for c in self.idle_others(me, |st| st.decoder.is_some()) {
+            if self.decoders.load(Ordering::Relaxed) <= self.max_decoders {
+                break;
+            }
+            if let Some(mut st) = try_state(&c) {
+                released.extend(st.release_decoder(self));
+            }
+        }
+        released
+    }
+
+    /// Evict the frames of idle caches, least recently used first, down to the budget. Caches in
+    /// use keep theirs (each within its own budget): a frame evicted before it is shown costs a
+    /// re-decode from the keyframe.
+    fn trim_frames(&self, me: &Shared) {
+        let over = || self.bytes.load(Ordering::Relaxed) > self.budget;
+        if !over() {
+            return;
+        }
+        for c in self.idle_others(me, |st| !st.frames.is_empty()) {
+            if !over() {
+                break;
+            }
+            if let Some(mut st) = try_state(&c) {
+                st.release_frames(self, over);
+            }
+        }
+    }
+}
+
+/// Caches that hold a decoder right now, process-wide (`perf.stats`).
+pub fn live_decoders() -> usize {
+    Pool::global().decoders.load(Ordering::Relaxed)
+}
+
+/// Bytes of decoded frames the caches hold right now, process-wide (`perf.stats`).
+pub fn cached_bytes() -> usize {
+    Pool::global().bytes.load(Ordering::Relaxed)
+}
+
 /// Decoder + decoded-frame cache for one video track.
 pub struct GopCache {
-    state: Mutex<State>,
+    shared: Arc<Shared>,
    /// Colour signalled by the container, which wins over the bitstream's.
    explicit_color: Option<ColorInfo>,
+    /// Clockwise quarter turns from the container's display matrix, applied to every frame.
+    rotation: u8,
    budget: usize,
 }

@@ -187,7 +360,13 @@ const CONTINUE_THROUGH: usize = 48;

 impl GopCache {
    pub fn new(explicit_color: Option<ColorInfo>) -> Self {
-        Self {
+        // unit tests count decoder restarts: each of their caches gets a pool of its own
+        let pool = if cfg!(test) { Arc::new(Pool::new(MAX_LIVE_DECODERS, IDLE, FRAME_BUDGET)) } else { Pool::global() };
+        Self::in_pool(explicit_color, pool)
+    }
+
+    fn in_pool(explicit_color: Option<ColorInfo>, pool: Arc<Pool>) -> Self {
+        let shared = Arc::new(Shared {
            state: Mutex::new(State {
                decoder: None,
                intra: false,
@@ -198,23 +377,34 @@ impl GopCache {
                frames: BTreeMap::new(),
                drafts: Default::default(),
                bytes: 0,
+                last_used: Instant::now(),
            }),
-            explicit_color,
-            budget: 384 << 20,
-        }
+            pool: pool.clone(),
+        });
+        pool.register(&shared);
+        Self { shared, explicit_color, rotation: 0, budget: 384 << 20 }
    }

-    /// Colour signalled by the container wins over the bitstream's (YUV frames only).
-    fn apply_color(&self, f: &mut VideoFrame) {
+    /// Turn every decoded frame clockwise by `quarter_turns` × 90° (the container's display
+    /// rotation, e.g. portrait phone video stored landscape).
+    pub fn with_rotation(mut self, quarter_turns: u8) -> Self {
+        self.rotation = quarter_turns % 4;
+        self
+    }
+
+    /// Colour signalled by the container wins over the bitstream's (YUV frames only); the
+    /// container's display rotation is applied.
+    fn finish(&self, mut f: VideoFrame) -> VideoFrame {
        if let Some(c) = self.explicit_color
            && !matches!(f.data, filmcraft_frame::PixelData::Rgba8(_) | filmcraft_frame::PixelData::RgbaF32(_))
        {
            f.color = c;
        }
+        if self.rotation != 0 { f.rotated(self.rotation) } else { f }
    }

-    fn store(&self, st: &mut State, pts: i64, mut f: VideoFrame, draft: bool) {
-        self.apply_color(&mut f);
+    fn store(&self, st: &mut State, pts: i64, f: VideoFrame, draft: bool) {
+        let f = self.finish(f);
        if draft {
            st.drafts.insert(pts);
            DRAFT.fetch_add(1, Ordering::Relaxed);
@@ -222,25 +412,36 @@ impl GopCache {
            st.drafts.remove(&pts);
        }
        let budget = self.budget.max(MIN_FRAMES * f.byte_size());
+        let before = st.bytes;
        st.bytes += f.byte_size();
        if let Some(old) = st.frames.insert(pts, Arc::new(f)) {
            st.bytes -= old.byte_size();
+            filmcraft_frame::pool::recycle(old);
        }
        // evict frames far from the most recent (keep a window around the working position)
        while st.bytes > budget && st.frames.len() > 2 {
-            let first = *st.frames.keys().next().expect("non-empty");
-            let last = *st.frames.keys().next_back().expect("non-empty");
+            let (Some(&first), Some(&last)) = (st.frames.keys().next(), st.frames.keys().next_back()) else { break };
            let victim = if pts - first > last - pts { first } else { last };
            if let Some(v) = st.frames.remove(&victim) {
                st.drafts.remove(&victim);
                st.bytes -= v.byte_size();
                EVICTED.fetch_add(1, Ordering::Relaxed);
+                // its planes serve the next decoded pictures instead of going back to the allocator
+                filmcraft_frame::pool::recycle(v);
            }
        }
+        let pool = &self.shared.pool;
+        if st.bytes >= before {
+            pool.bytes.fetch_add(st.bytes - before, Ordering::Relaxed);
+        } else {
+            pool.bytes.fetch_sub(before - st.bytes, Ordering::Relaxed);
+        }
+        pool.trim_frames(&self.shared);
    }

    /// Store decoder output (in presentation order) and advance `out_max`.
    fn store_output(&self, st: &mut State, out: Vec<crate::video::DecodedFrame>) {
+        count_frames(&out);
        for d in out {
            st.out_max = st.out_max.max(d.pts);
            self.store(st, d.pts, d.frame, d.draft);
@@ -274,8 +475,13 @@ impl GopCache {
            return self.private_frame(s, i, want_pts, n);
        }
        let draft = filmcraft_media::cancel::draft();
-        let mut st = self.state.lock().unwrap_or_else(|e| e.into_inner());
+        // Idle caches' decoders released below. Declared before the lock guard, so it is dropped
+        // after the guard on every return path: dropping a decoder can block (a hardware session
+        // waits for its frames in flight) and must not hold this cache's lock.
+        let mut released: Vec<Box<dyn VideoDecoder>> = Vec::new();
+        let mut st = self.shared.state.lock().unwrap_or_else(|e| e.into_inner());
        let _decoding = DecodingGuard::enter(me);
+        st.last_used = Instant::now();
        if let Some(f) = st.cached(want_pts, draft) {
            HITS.fetch_add(1, Ordering::Relaxed);
            return Ok(f.clone());
@@ -286,7 +492,9 @@ impl GopCache {
            st.intra = d.intra_only();
            st.decoder = Some(d);
            st.next = usize::MAX;
+            self.shared.pool.decoders.fetch_add(1, Ordering::Relaxed);
        }
+        released.extend(self.shared.pool.trim_decoders(&self.shared));
        // Nothing cached: the work ahead (possibly a seek and a GOP of decoding) is only worth it
        // while someone still wants the frame.
        if filmcraft_media::cancel::cancelled() {
@@ -311,7 +519,7 @@ impl GopCache {
            // every sample): step back to a sample the decoder can start from.
            while key > 0 {
                let data = s.read(key)?;
-                if st.decoder.as_ref().expect("decoder").is_random_access(&data) != Some(false) {
+                if st.decoder.as_ref().and_then(|d| d.is_random_access(&data)) != Some(false) {
                    break;
                }
                key = s.sync_before(key - 1);
@@ -325,7 +533,10 @@ impl GopCache {
        }
        let limit = (i.max(st.next) + 64).min(n);
        let late = late_before.unwrap_or(i64::MIN).min(want_pts);
-        st.decoder.as_mut().expect("decoder").set_draft(draft);
+        let Some(decoder) = st.decoder.as_mut() else {
+            return Err(CodecError::Decode("no video decoder".into()));
+        };
+        decoder.set_draft(draft);
        while st.next < limit {
            if filmcraft_media::cancel::cancelled() {
                // The decoder state stays consistent (`next`, `out_max`): a later request continues.
@@ -333,12 +544,15 @@ impl GopCache {
            }
            let k = st.next;
            let data = s.read(k)?;
-            if k != i && s.pts(k) < late && st.decoder.as_ref().expect("decoder").is_disposable(&data) {
+            if k != i && s.pts(k) < late && st.decoder.as_ref().is_some_and(|d| d.is_disposable(&data)) {
                st.next += 1;
                SKIPPED.fetch_add(1, Ordering::Relaxed);
                continue;
            }
-            let out = timed(|| st.decoder.as_mut().expect("decoder").decode(&data, s.pts(k)))?;
+            let Some(decoder) = st.decoder.as_mut() else {
+                return Err(CodecError::Decode("no video decoder".into()));
+            };
+            let out = timed(|| decoder.decode(&data, s.pts(k)))?;
            st.next += 1;
            DECODED.fetch_add(1, Ordering::Relaxed);
            self.store_output(&mut st, out);
@@ -347,7 +561,7 @@ impl GopCache {
            }
        }
        if st.cached(want_pts, draft).is_none() {
-            let out = timed(|| st.decoder.as_mut().expect("decoder").flush());
+            let out = st.decoder.as_mut().map(|d| timed(|| d.flush())).unwrap_or_default();
            self.store_output(&mut st, out);
            st.next = usize::MAX;
        }
@@ -361,14 +575,13 @@ impl GopCache {
        let mut d = s.make_decoder()?;
        let mut next = usize::MAX;
        let out = Self::decode_to(s, d.as_mut(), &mut next, i, want_pts, n)?;
-        let mut f = out
+        let f = out
            .into_iter()
            .filter(|p| p.pts <= want_pts)
            .max_by_key(|p| p.pts)
            .map(|p| p.frame)
            .ok_or_else(|| CodecError::Decode("frame not produced".into()))?;
-        self.apply_color(&mut f);
-        Ok(Arc::new(f))
+        Ok(Arc::new(self.finish(f)))
    }

    /// Decode with `d` (positioned at `next`) until the picture with `want_pts` (sample `i`) comes out.
@@ -403,6 +616,7 @@ impl GopCache {
            let k = *next;
            let data = s.read(k)?;
            let pics = timed(|| d.decode(&data, s.pts(k)))?;
+            count_frames(&pics);
            *next += 1;
            found |= pics.iter().any(|p| p.pts == want_pts);
            out.extend(pics);
@@ -411,7 +625,9 @@ impl GopCache {
            }
        }
        if !found {
-            out.extend(timed(|| d.flush()));
+            let pics = timed(|| d.flush());
+            count_frames(&pics);
+            out.extend(pics);
            *next = usize::MAX;
        }
        Ok(out)
@@ -431,11 +647,13 @@ impl GopCache {
            DECODED.fetch_add(1, Ordering::Relaxed);
            timed(|| dec.decode(&data, want_pts))
        });
-        let mut st = self.state.lock().unwrap_or_else(|e| e.into_inner());
+        let mut st = self.shared.state.lock().unwrap_or_else(|e| e.into_inner());
        if st.spare.len() < 16 {
            st.spare.push(dec);
        }
-        for d in res? {
+        let res = res?;
+        count_frames(&res);
+        for d in res {
            self.store(&mut st, d.pts, d.frame, d.draft);
        }
        st.at_or_before(want_pts, true).ok_or_else(|| CodecError::Decode("frame not produced".into()))
@@ -447,7 +665,6 @@ mod tests {
    use super::*;
    use crate::video::DecodedFrame;
    use std::collections::VecDeque;
-    use std::sync::atomic::AtomicUsize;

    /// `n` samples, a sync sample every `gop`, pts = 1000 · index (no reordering).
    struct Samples {
@@ -683,4 +900,165 @@ mod tests {
        assert_eq!(index_of(&c.frame(&s, 7_000).expect("frame")), 7);
        assert_eq!(s.resets.load(Ordering::Relaxed), 1);
    }
+
+    #[test]
+    fn idle_caches_give_up_their_decoders_beyond_the_cap() {
+        let pool = Arc::new(Pool::new(2, Duration::ZERO, FRAME_BUDGET));
+        let live = || pool.decoders.load(Ordering::Relaxed);
+        let s: Vec<Samples> = (0..5).map(|_| samples(300, 250, 3, false)).collect();
+        let c: Vec<GopCache> = (0..5).map(|_| GopCache::in_pool(None, pool.clone())).collect();
+        // a clip after another, as when clips are dropped on a timeline
+        for k in 0..5 {
+            assert_eq!(index_of(&c[k].frame(&s[k], 10_000).expect("frame")), 10);
+            assert!(live() <= 2, "{} live decoders after clip {k}", live());
+        }
+        assert_eq!(live(), 2);
+        // the most recently used keep theirs and carry on without a seek
+        assert_eq!(index_of(&c[4].frame(&s[4], 20_000).expect("frame")), 20);
+        assert_eq!(s[4].resets.load(Ordering::Relaxed), 1);
+        // a cache that lost its decoder still serves what it cached…
+        let decodes = s[0].decodes.load(Ordering::Relaxed);
+        assert_eq!(index_of(&c[0].frame(&s[0], 10_000).expect("cached")), 10);
+        assert_eq!(s[0].decodes.load(Ordering::Relaxed), decodes);
+        // …and decodes again with a new decoder, from the sync sample
+        assert_eq!(index_of(&c[0].frame(&s[0], 20_000).expect("frame")), 20);
+        assert_eq!(s[0].resets.load(Ordering::Relaxed), 2);
+        assert_eq!(live(), 2);
+        // a dropped cache no longer counts
+        drop(c);
+        assert_eq!(live(), 0);
+    }
+
+    #[test]
+    fn caches_in_use_keep_their_decoders_whatever_the_cap() {
+        // every layer of one composited frame was asked moments ago: none is idle
+        let pool = Arc::new(Pool::new(2, Duration::from_secs(3600), FRAME_BUDGET));
+        let s: Vec<Samples> = (0..5).map(|_| samples(300, 250, 3, false)).collect();
+        let c: Vec<GopCache> = (0..5).map(|_| GopCache::in_pool(None, pool.clone())).collect();
+        for t in [10_000, 11_000, 12_000] {
+            for k in 0..5 {
+                assert_eq!(index_of(&c[k].frame(&s[k], t).expect("frame")) as i64, t / 1000);
+            }
+        }
+        assert_eq!(pool.decoders.load(Ordering::Relaxed), 5);
+        assert!(s.iter().all(|s| s.resets.load(Ordering::Relaxed) == 1), "no decoder restarted");
+    }
+
+    #[test]
+    fn intra_caches_give_up_their_spare_decoders_too() {
+        let pool = Arc::new(Pool::new(1, Duration::ZERO, FRAME_BUDGET));
+        let (a, b) = (samples(50, 1, 0, true), samples(50, 1, 0, true));
+        let (ca, cb) = (GopCache::in_pool(None, pool.clone()), GopCache::in_pool(None, pool.clone()));
+        assert_eq!(index_of(&ca.frame(&a, 3_000).expect("frame")), 3);
+        assert_eq!(index_of(&cb.frame(&b, 4_000).expect("frame")), 4);
+        let st = ca.shared.state.lock().unwrap();
+        assert!(st.decoder.is_none() && st.spare.is_empty());
+        drop(st);
+        assert_eq!(pool.decoders.load(Ordering::Relaxed), 1);
+        assert_eq!(index_of(&ca.frame(&a, 5_000).expect("frame")), 5);
+    }
+
+    #[test]
+    fn idle_caches_give_up_their_frames_beyond_the_shared_budget() {
+        // 1×1 RGBA pictures: 4 bytes each, a shared budget of ten of them
+        let pool = Arc::new(Pool::new(usize::MAX, Duration::ZERO, 40));
+        let held = || pool.bytes.load(Ordering::Relaxed);
+        let (a, b) = (samples(300, 250, 0, false), samples(300, 250, 0, false));
+        let (ca, cb) = (GopCache::in_pool(None, pool.clone()), GopCache::in_pool(None, pool.clone()));
+        // the only cache keeps what its own budget allows
+        assert_eq!(index_of(&ca.frame(&a, 10_000).expect("frame")), 10);
+        assert_eq!(held(), 44);
+        // a second clip takes the room from the idle first one, earliest frames first
+        assert_eq!(index_of(&cb.frame(&b, 5_000).expect("frame")), 5);
+        assert_eq!(held(), 40);
+        let decodes = b.decodes.load(Ordering::Relaxed);
+        assert!((0..=5).all(|i| index_of(&cb.frame(&b, i * 1000).expect("cached")) as i64 == i));
+        assert_eq!(b.decodes.load(Ordering::Relaxed), decodes, "the clip in use lost nothing");
+        let st = ca.shared.state.lock().unwrap();
+        assert_eq!((st.frames.len(), st.bytes), (4, 16));
+        assert_eq!(st.frames.keys().next(), Some(&7_000));
+        drop(st);
+        // an evicted frame decodes again
+        assert_eq!(index_of(&ca.frame(&a, 2_000).expect("frame")), 2);
+        assert!(held() <= 40 + 4 * 3, "{} bytes held", held());
+        drop((ca, cb));
+        assert_eq!(held(), 0);
+    }
+
+    #[test]
+    fn caches_in_use_keep_their_frames_whatever_the_shared_budget() {
+        let pool = Arc::new(Pool::new(usize::MAX, Duration::from_secs(3600), 40));
+        let (a, b) = (samples(300, 250, 0, false), samples(300, 250, 0, false));
+        let (ca, cb) = (GopCache::in_pool(None, pool.clone()), GopCache::in_pool(None, pool.clone()));
+        assert_eq!(index_of(&ca.frame(&a, 10_000).expect("frame")), 10);
+        assert_eq!(index_of(&cb.frame(&b, 10_000).expect("frame")), 10);
+        assert_eq!(pool.bytes.load(Ordering::Relaxed), 88);
+        let decodes = a.decodes.load(Ordering::Relaxed);
+        assert_eq!(index_of(&ca.frame(&a, 0).expect("cached")), 0);
+        assert_eq!(a.decodes.load(Ordering::Relaxed), decodes);
+    }
+
+    /// Pictures big enough for the plane pool (its own size, so that parallel tests cannot take
+    /// the buffers), no reordering, one long GOP.
+    struct Big(usize);
+    const BIG: (u32, u32) = (200, 101);
+
+    impl VideoDecoder for Big {
+        fn decode(&mut self, _sample: &[u8], pts: i64) -> crate::Result<Vec<DecodedFrame>> {
+            let mut px = filmcraft_frame::pool::take_u8((BIG.0 * BIG.1 * 4) as usize);
+            px.resize((BIG.0 * BIG.1 * 4) as usize, (pts / 1000) as u8);
+            Ok(vec![DecodedFrame { pts, frame: VideoFrame::rgba8(BIG.0, BIG.1, px), draft: false }])
+        }
+        fn flush(&mut self) -> Vec<DecodedFrame> {
+            Vec::new()
+        }
+        fn reset(&mut self) {}
+        fn name(&self) -> &str {
+            "big"
+        }
+    }
+
+    impl VideoSamples for Big {
+        fn count(&self) -> usize {
+            self.0
+        }
+        fn pts(&self, i: usize) -> i64 {
+            i as i64 * 1000
+        }
+        fn sync_before(&self, _i: usize) -> usize {
+            0
+        }
+        fn sample_at(&self, t: i64) -> Option<usize> {
+            let i = (t / 1000) as usize;
+            (i < self.0).then_some(i)
+        }
+        fn read(&self, i: usize) -> crate::Result<Vec<u8>> {
+            Ok(vec![i as u8])
+        }
+        fn make_decoder(&self) -> crate::Result<Box<dyn VideoDecoder>> {
+            Ok(Box::new(Big(self.0)))
+        }
+    }
+
+    #[test]
+    fn evicted_frames_are_decoded_into_again() {
+        let s = Big(200);
+        // room for MIN_FRAMES pictures only
+        let mut c = GopCache::new(None);
+        c.budget = 0;
+        let reused = || filmcraft_frame::pool::stats().reused;
+        let before = reused();
+        // the cache holds MIN_FRAMES pictures: none is evicted yet, every plane is new
+        for i in 0..MIN_FRAMES as i64 {
+            assert_eq!(c.frame(&s, i * 1000).expect("frame").width, BIG.0);
+        }
+        assert_eq!(reused(), before);
+        // from here on each picture evicts one, whose buffer the next picture is decoded into
+        let more = 40;
+        for i in MIN_FRAMES as i64..MIN_FRAMES as i64 + more {
+            let f = c.frame(&s, i * 1000).expect("frame");
+            assert!(matches!(&f.data, filmcraft_frame::PixelData::Rgba8(d) if d.iter().all(|&b| b == i as u8)), "frame {i} has its own pixels");
+        }
+        assert!(reused() - before >= more as u64 - 2, "{} of {more} planes recycled", reused() - before);
+    }
 }
@@ -0,0 +1,429 @@
+//! Support for hardware (OS) video decoders registered by `filmcraft-platform`: the
+//! Settings ▸ Playback ▸ Hardware decoding switch, the hardware counters `perf.stats` reports, and
+//! what such a decoder needs from an `avcC` / `hvcC` sample entry to behave exactly like our
+//! software decoder for the same stream (parameter sets, cropping, colour, pixel aspect, reorder
+//! depth, random-access and disposable samples).
+//!
+//! The software decoders stay the reference: a hardware factory declines streams it cannot
+//! decode, and a hardware decoder that fails mid-stream switches to
+//! [`crate::software_video_decoder`], so registering one never makes a file undecodable.
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+
+use filmcraft_isobmff::{CodecConfig, SampleEntry};
+
+pub use crate::hw_frame::{FrameCodec, FrameStreamInfo, PictureParams};
+use crate::video::{avcc_length_size, h264_disposable, hevc_disposable, hvcc_length_size_and_tid, sar_par, vui_color};
+use crate::{CodecError, Result};
+
+static ENABLED: AtomicBool = AtomicBool::new(true);
+
+/// Settings ▸ Playback ▸ Hardware decoding: `Auto` (true, the default) lets registered hardware
+/// decoders take streams they support; `Off` (false) makes every new decoder a software one.
+/// Decoders already created keep running: a source picks the change up when it is reopened.
+pub fn set_hardware_decoding(on: bool) {
+    ENABLED.store(on, Ordering::Relaxed);
+}
+
+/// Whether hardware decoders may be used for new decoders ([`set_hardware_decoding`]).
+pub fn hardware_decoding() -> bool {
+    ENABLED.load(Ordering::Relaxed)
+}
+
+static BACKEND: std::sync::Mutex<Option<&'static str>> = std::sync::Mutex::new(None);
+
+/// Record the OS decoder backend `filmcraft_platform::register` put in front of our decoders
+/// ("VideoToolbox", "Media Foundation"), for `perf.stats`.
+pub fn set_hw_backend(name: &'static str) {
+    *BACKEND.lock().unwrap_or_else(std::sync::PoisonError::into_inner) = Some(name);
+}
+
+/// The registered hardware decoder backend, if any ([`set_hw_backend`]).
+pub fn hw_backend() -> Option<&'static str> {
+    *BACKEND.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+/// Process-wide hardware decoding counters (they only grow; subtract two snapshots to measure an
+/// interval). Frames decoded in software are `GopStats::frames - frames`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct HwStats {
+    /// Pictures output by hardware decoders.
+    pub frames: u64,
+    /// Hardware decoders created (one per decoder instance; a seek reuses it).
+    pub sessions: u64,
+    /// Streams a hardware factory handed to the software decoder (unsupported profile, size,
+    /// chroma format or bit depth, no hardware, or the switch is Off).
+    pub declined: u64,
+    /// Hardware decoders that failed mid-stream and continued in software.
+    pub fallbacks: u64,
+}
+
+static FRAMES: AtomicU64 = AtomicU64::new(0);
+static SESSIONS: AtomicU64 = AtomicU64::new(0);
+static DECLINED: AtomicU64 = AtomicU64::new(0);
+static FALLBACKS: AtomicU64 = AtomicU64::new(0);
+
+/// The counters so far.
+pub fn hw_stats() -> HwStats {
+    HwStats {
+        frames: FRAMES.load(Ordering::Relaxed),
+        sessions: SESSIONS.load(Ordering::Relaxed),
+        declined: DECLINED.load(Ordering::Relaxed),
+        fallbacks: FALLBACKS.load(Ordering::Relaxed),
+    }
+}
+
+/// A hardware decoder output `n` pictures.
+pub fn note_hw_frames(n: usize) {
+    FRAMES.fetch_add(n as u64, Ordering::Relaxed);
+}
+
+/// A hardware decoder was created.
+pub fn note_hw_session() {
+    SESSIONS.fetch_add(1, Ordering::Relaxed);
+}
+
+/// A hardware factory declined a stream it is responsible for.
+pub fn note_hw_declined() {
+    DECLINED.fetch_add(1, Ordering::Relaxed);
+}
+
+/// A hardware decoder switched to software mid-stream.
+pub fn note_hw_fallback() {
+    FALLBACKS.fetch_add(1, Ordering::Relaxed);
+}
+
+/// The two codecs whose `avcC` / `hvcC` streams hardware decoders take.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum NalCodec {
+    H264,
+    Hevc,
+}
+
+/// What a decoder needs to know about a length-prefixed H.264 / HEVC stream, from its sample
+/// entry's configuration record and active sequence parameter set (parsed with the software
+/// decoders' own parsers, so both decoders derive the same values).
+#[derive(Clone, Debug)]
+pub struct NalStreamInfo {
+    pub codec: NalCodec,
+    /// NAL unit length-prefix size of the samples (1, 2 or 4).
+    pub length_size: usize,
+    /// HEVC: highest TemporalId (numTemporalLayers - 1), when signalled.
+    pub highest_tid: Option<u8>,
+    /// The parameter-set NAL units of the record (header included, emulation prevention kept),
+    /// in record order: H.264 SPS then PPS; HEVC VPS, SPS, PPS. SEI arrays are left out.
+    pub parameter_sets: Vec<Vec<u8>>,
+    /// Coded (decoded) picture size in luma samples.
+    pub coded: (u32, u32),
+    /// Output (cropped) rectangle in luma samples: x, y, width, height.
+    pub crop: (u32, u32, u32, u32),
+    /// 0 monochrome, 1 4:2:0, 2 4:2:2, 3 4:4:4.
+    pub chroma_format_idc: u32,
+    pub bit_depth_luma: u32,
+    pub bit_depth_chroma: u32,
+    /// Field (PAFF / MBAFF) coding (H.264 `frame_mbs_only_flag` 0).
+    pub interlaced: bool,
+    /// H.264 `profile_idc` / HEVC `general_profile_idc`.
+    pub profile_idc: u8,
+    /// Colour of every output picture, as the software decoder reports it.
+    pub color: filmcraft_color::ColorInfo,
+    /// Pixel aspect ratio, as the software decoder reports it.
+    pub par: (u32, u32),
+    /// Pictures that may precede a picture in decoding order and follow it in output order
+    /// (H.264 `max_num_reorder_frames`, HEVC `sps_max_num_reorder_pics`).
+    pub reorder: usize,
+}
+
+/// Any stream a hardware decoder can take: what [`crate::hw`]'s hybrid decoder needs to know about
+/// it to find restart points and in-band parameter changes.
+#[derive(Clone, Debug)]
+pub enum StreamInfo {
+    Nal(NalStreamInfo),
+    Frame(FrameStreamInfo),
+}
+
+impl From<NalStreamInfo> for StreamInfo {
+    fn from(i: NalStreamInfo) -> Self {
+        Self::Nal(i)
+    }
+}
+
+impl From<FrameStreamInfo> for StreamInfo {
+    fn from(i: FrameStreamInfo) -> Self {
+        Self::Frame(i)
+    }
+}
+
+impl StreamInfo {
+    /// Whether decoding can restart at `sample` with no earlier state (IDR / IRAP, a key frame).
+    pub fn is_irap(&self, sample: &[u8]) -> bool {
+        match self {
+            Self::Nal(i) => i.is_irap(sample),
+            Self::Frame(i) => i.is_random_access(sample),
+        }
+    }
+
+    /// An HEVC CRA restarts nothing by itself (its RASL pictures need the previous restart point).
+    pub fn keeps_previous_restart(&self, sample: &[u8]) -> bool {
+        match self {
+            Self::Nal(i) => i.codec == NalCodec::Hevc && i.nal_types(sample).contains(&21),
+            Self::Frame(_) => false,
+        }
+    }
+
+    /// Whether `sample` carries parameters different from the ones the hardware decoder was set up
+    /// with (parameter sets, a sequence header, a key frame of another format).
+    pub fn parameters_changed(&self, sample: &[u8]) -> bool {
+        match self {
+            Self::Nal(i) => {
+                i.nals(sample).into_iter().any(|n| n.first().is_some_and(|&h| i.is_parameter_set(i.nal_type(h))) && !i.parameter_sets.iter().any(|p| p == n))
+            }
+            Self::Frame(i) => i.parameters_changed(sample),
+        }
+    }
+
+    /// As the software decoder's [`crate::VideoDecoder::is_random_access`].
+    pub fn is_random_access(&self, sample: &[u8]) -> Option<bool> {
+        match self {
+            Self::Nal(i) => i.is_random_access(sample),
+            Self::Frame(i) => Some(i.is_random_access(sample)),
+        }
+    }
+
+    /// As the software decoder's [`crate::VideoDecoder::is_disposable`].
+    pub fn is_disposable(&self, sample: &[u8]) -> bool {
+        match self {
+            Self::Nal(i) => i.is_disposable(sample),
+            Self::Frame(_) => false,
+        }
+    }
+}
+
+/// Length-prefixed parameter-set entries (`u16` length + bytes) starting at `pos`.
+fn read_sets(rec: &[u8], pos: &mut usize, count: usize, out: &mut Vec<Vec<u8>>) -> Result<()> {
+    for _ in 0..count {
+        let len = rec
+            .get(*pos..*pos + 2)
+            .map(|b| u16::from_be_bytes([b[0], b[1]]) as usize)
+            .ok_or_else(|| CodecError::Decode("configuration record truncated".into()))?;
+        *pos += 2;
+        let nal = rec.get(*pos..*pos + len).ok_or_else(|| CodecError::Decode("configuration record truncated".into()))?;
+        *pos += len;
+        if !nal.is_empty() {
+            out.push(nal.to_vec());
+        }
+    }
+    Ok(())
+}
+
+impl NalStreamInfo {
+    /// The stream info of an `avcC` / `hvcC` sample entry (`None` for other codecs).
+    pub fn from_entry(e: &SampleEntry) -> Option<Result<Self>> {
+        match &e.codec {
+            CodecConfig::Avc(a) => Some(Self::from_avcc(&a.to_bytes())),
+            CodecConfig::Hevc(c) => Some(Self::from_hvcc(&c.to_bytes())),
+            _ => None,
+        }
+    }
+
+    /// From an `avcC` (AVCDecoderConfigurationRecord) payload.
+    pub fn from_avcc(avcc: &[u8]) -> Result<Self> {
+        if avcc.len() < 7 || avcc[0] != 1 {
+            return Err(CodecError::Decode("bad avcC record".into()));
+        }
+        let mut sets = Vec::new();
+        let mut pos = 6;
+        read_sets(avcc, &mut pos, (avcc[5] & 0x1f) as usize, &mut sets)?;
+        let nsps = sets.len();
+        let npps = *avcc.get(pos).ok_or_else(|| CodecError::Decode("avcC truncated".into()))? as usize;
+        pos += 1;
+        read_sets(avcc, &mut pos, npps, &mut sets)?;
+        let sps_nal = sets.iter().take(nsps).find(|n| n.first().is_some_and(|h| h & 0x1f == 7)).ok_or_else(|| CodecError::Decode("avcC has no SPS".into()))?;
+        if sets.len() == nsps {
+            return Err(CodecError::Decode("avcC has no PPS".into()));
+        }
+        let sps = filmcraft_h264::params::Sps::parse(&filmcraft_bitstream::unescape_rbsp(sps_nal.get(1..).unwrap_or_default()))
+            .map_err(|e| CodecError::Decode(e.to_string()))?;
+        let crop = sps.crop_rect();
+        let vui = sps.vui.clone().unwrap_or_default();
+        Ok(Self {
+            codec: NalCodec::H264,
+            length_size: avcc_length_size(avcc),
+            highest_tid: None,
+            parameter_sets: sets,
+            coded: (sps.width(), sps.height()),
+            crop,
+            chroma_format_idc: sps.chroma_format_idc,
+            bit_depth_luma: sps.bit_depth_luma,
+            bit_depth_chroma: sps.bit_depth_chroma,
+            interlaced: !sps.frame_mbs_only,
+            profile_idc: sps.profile_idc,
+            color: vui_color(crop.2, crop.3, vui.matrix_coefficients, vui.transfer_characteristics, vui.full_range),
+            par: sar_par(vui.sar),
+            // as the software decoder's DPB (`max_reorder`)
+            reorder: sps.max_num_reorder_frames().min(sps.max_dpb_frames()),
+        })
+    }
+
+    /// From an `hvcC` (HEVCDecoderConfigurationRecord) payload.
+    pub fn from_hvcc(hvcc: &[u8]) -> Result<Self> {
+        if hvcc.len() < 23 || hvcc[0] != 1 {
+            return Err(CodecError::Decode("bad hvcC record".into()));
+        }
+        let (length_size, highest_tid) = hvcc_length_size_and_tid(hvcc);
+        let mut sets = Vec::new();
+        let mut pos = 23;
+        for _ in 0..hvcc[22] {
+            let hdr = hvcc.get(pos..pos + 3).ok_or_else(|| CodecError::Decode("hvcC truncated".into()))?;
+            let (kind, n) = (hdr[0] & 0x3f, u16::from_be_bytes([hdr[1], hdr[2]]) as usize);
+            pos += 3;
+            let mut arr = Vec::new();
+            read_sets(hvcc, &mut pos, n, &mut arr)?;
+            if (32..=34).contains(&kind) {
+                sets.extend(arr);
+            }
+        }
+        let nal_type = |n: &[u8]| n.first().map(|h| (h >> 1) & 0x3f);
+        let sps_nal = sets.iter().find(|n| nal_type(n) == Some(33)).ok_or_else(|| CodecError::Decode("hvcC has no SPS".into()))?;
+        if !sets.iter().any(|n| nal_type(n) == Some(32)) || !sets.iter().any(|n| nal_type(n) == Some(34)) {
+            return Err(CodecError::Decode("hvcC lacks a VPS or PPS".into()));
+        }
+        let sps = filmcraft_hevc::params::Sps::parse(&filmcraft_bitstream::unescape_rbsp(sps_nal.get(2..).unwrap_or_default()))
+            .map_err(|e| CodecError::Decode(e.to_string()))?;
+        let crop = sps.crop_rect();
+        let vui = sps.vui.clone().unwrap_or_default();
+        Ok(Self {
+            codec: NalCodec::Hevc,
+            length_size,
+            highest_tid,
+            parameter_sets: sets,
+            coded: (sps.width, sps.height),
+            crop,
+            chroma_format_idc: sps.chroma_format_idc,
+            bit_depth_luma: sps.bit_depth_luma,
+            bit_depth_chroma: sps.bit_depth_chroma,
+            interlaced: false,
+            profile_idc: sps.ptl.profile_idc,
+            color: vui_color(crop.2, crop.3, vui.matrix_coefficients, vui.transfer_characteristics, vui.full_range),
+            par: sar_par(vui.sar),
+            reorder: sps.max_num_reorder as usize,
+        })
+    }
+
+    /// NAL unit types of a sample (stops at the first malformed length prefix).
+    pub fn nal_types(&self, sample: &[u8]) -> Vec<u8> {
+        self.nals(sample).into_iter().filter_map(|n| n.first().map(|&h| self.nal_type(h))).collect()
+    }
+
+    /// The NAL units of a length-prefixed sample (stops at the first malformed length prefix).
+    pub fn nals<'a>(&self, sample: &'a [u8]) -> Vec<&'a [u8]> {
+        let ls = self.length_size;
+        let mut out = Vec::new();
+        let mut pos = 0usize;
+        while let Some(pre) = sample.get(pos..pos.saturating_add(ls)) {
+            if !(1..=4).contains(&ls) {
+                break;
+            }
+            let len = pre.iter().fold(0usize, |a, &b| (a << 8) | b as usize);
+            pos += ls;
+            let Some(n) = sample.get(pos..pos.saturating_add(len)) else { break };
+            pos += len;
+            out.push(n);
+        }
+        out
+    }
+
+    /// The NAL unit type in a NAL header byte.
+    pub fn nal_type(&self, header: u8) -> u8 {
+        match self.codec {
+            NalCodec::H264 => header & 0x1f,
+            NalCodec::Hevc => (header >> 1) & 0x3f,
+        }
+    }
+
+    /// Whether `t` is a parameter-set NAL unit type (H.264 SPS / PPS / SPS extension, HEVC VPS /
+    /// SPS / PPS).
+    pub fn is_parameter_set(&self, t: u8) -> bool {
+        match self.codec {
+            NalCodec::H264 => matches!(t, 7 | 8 | 13 | 15),
+            NalCodec::Hevc => (32..=34).contains(&t),
+        }
+    }
+
+    /// Whether decoding can restart at `sample` with no earlier state: an IDR access unit (H.264)
+    /// or an IRAP one (HEVC IDR / CRA / BLA).
+    pub fn is_irap(&self, sample: &[u8]) -> bool {
+        self.nal_types(sample).iter().any(|&t| match self.codec {
+            NalCodec::H264 => t == 5,
+            NalCodec::Hevc => (16..=23).contains(&t),
+        })
+    }
+
+    /// As the software decoder's [`crate::VideoDecoder::is_random_access`] for this stream
+    /// (length-prefixed samples: unknown, the container's sync flags are trusted).
+    pub fn is_random_access(&self, _sample: &[u8]) -> Option<bool> {
+        None
+    }
+
+    /// As the software decoder's [`crate::VideoDecoder::is_disposable`] for this stream.
+    pub fn is_disposable(&self, sample: &[u8]) -> bool {
+        match self.codec {
+            NalCodec::H264 => h264_disposable(sample, self.length_size),
+            NalCodec::Hevc => hevc_disposable(sample, self.length_size, self.highest_tid),
+        }
+    }
+
+    /// Output picture size (cropped).
+    pub fn size(&self) -> (u32, u32) {
+        (self.crop.2, self.crop.3)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn switch_defaults_to_auto() {
+        // other tests in this process may flip it; only check the round trip
+        let was = hardware_decoding();
+        set_hardware_decoding(false);
+        assert!(!hardware_decoding());
+        set_hardware_decoding(true);
+        assert!(hardware_decoding());
+        set_hardware_decoding(was);
+    }
+
+    #[test]
+    fn hostile_records_are_errors() {
+        for rec in [&[][..], &[1, 2, 3], &[1, 0x64, 0, 0x1f, 0xff, 0xe1, 0, 9, 0x67], &[0; 30]] {
+            assert!(NalStreamInfo::from_avcc(rec).is_err());
+            assert!(NalStreamInfo::from_hvcc(rec).is_err());
+        }
+    }
+
+    #[test]
+    fn nal_splitting_is_bounded() {
+        let info = NalStreamInfo {
+            codec: NalCodec::Hevc,
+            length_size: 4,
+            highest_tid: None,
+            parameter_sets: Vec::new(),
+            coded: (16, 16),
+            crop: (0, 0, 16, 16),
+            chroma_format_idc: 1,
+            bit_depth_luma: 8,
+            bit_depth_chroma: 8,
+            interlaced: false,
+            profile_idc: 1,
+            color: filmcraft_color::ColorInfo::REC709,
+            par: (1, 1),
+            reorder: 0,
+        };
+        // CRA (21) then a length that runs past the end
+        let s = [0, 0, 0, 2, 21 << 1, 1, 0xff, 0xff, 0xff, 0xff, 1];
+        assert_eq!(info.nal_types(&s), vec![21]);
+        assert!(info.is_irap(&s));
+        assert!(!info.is_irap(&[0, 0, 0, 2, 1 << 1, 1]));
+    }
+}
@@ -0,0 +1,256 @@
+//! What a hardware decoder needs to know about a VP9 or AV1 stream so that it behaves exactly like
+//! our software decoder for it (the frame-coded counterpart of [`crate::hw::NalStreamInfo`]):
+//! codec profile, bit depth and chroma format from the container's `vpcC` / `av1C`, the picture
+//! size and colour as the software decoder reports them (read from the bitstream the same way),
+//! random-access samples, and in-band changes of the stream's parameters.
+
+use filmcraft_color::{ColorInfo, Primaries, Transfer};
+use filmcraft_isobmff::{CodecConfig, SampleEntry};
+
+use crate::video::primaries_from_code;
+use crate::{CodecError, Result};
+
+/// The two frame-coded codecs hardware decoders take besides H.264 / HEVC.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum FrameCodec {
+    Vp9,
+    Av1,
+}
+
+/// Picture parameters read from a random-access sample.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct PictureParams {
+    /// Picture size in luma samples (the decoded size).
+    pub size: (u32, u32),
+    pub bit_depth: u32,
+    /// `subsampling_x`, `subsampling_y`.
+    pub subsampling: (u8, u8),
+    /// Colour of every output picture, as the software decoder reports it.
+    pub color: ColorInfo,
+}
+
+/// A VP9 or AV1 stream, from its sample entry.
+#[derive(Clone, Debug)]
+pub struct FrameStreamInfo {
+    pub codec: FrameCodec,
+    /// VP9 `profile` (0..=3) / AV1 `seq_profile` (0..=2).
+    pub profile: u8,
+    pub bit_depth: u32,
+    pub subsampling: (u8, u8),
+    pub mono: bool,
+    /// Picture size: the sample entry's, checked against the bitstream's.
+    pub size: (u32, u32),
+    /// AV1: the `av1C` configuration OBUs (the sequence header the decoder is primed with).
+    pub config_obus: Vec<u8>,
+    /// AV1: the sequence header's payload; VP9: none.
+    sequence_header: Option<Vec<u8>>,
+    /// Colour of the stream when it is known before the first picture (AV1: from the sequence
+    /// header).
+    pub color: Option<ColorInfo>,
+    /// VP9: transfer and primaries from the container (not in the bitstream).
+    transfer: Option<Transfer>,
+    primaries: Option<Primaries>,
+}
+
+/// The OBUs of a low-overhead AV1 sample: `(type, payload)`, stopping at the first malformed one.
+fn obus(data: &[u8]) -> Vec<(u8, &[u8])> {
+    let mut out = Vec::new();
+    let mut pos = 0usize;
+    while let Some(&h) = data.get(pos) {
+        let (obu_type, ext, has_size) = ((h >> 3) & 0xf, h & 4 != 0, h & 2 != 0);
+        let mut p = pos + 1 + usize::from(ext);
+        let size = if has_size {
+            let (mut v, mut shift, mut n) = (0usize, 0u32, 0usize);
+            loop {
+                let Some(&b) = data.get(p + n) else { return out };
+                v |= usize::from(b & 0x7f).checked_shl(shift).unwrap_or(0);
+                n += 1;
+                if b & 0x80 == 0 || n >= 8 {
+                    break;
+                }
+                shift += 7;
+            }
+            p += n;
+            v
+        } else {
+            data.len().saturating_sub(p)
+        };
+        let Some(payload) = data.get(p..p.saturating_add(size)) else { return out };
+        out.push((obu_type, payload));
+        pos = p + size;
+    }
+    out
+}
+
+/// VP9 colour as our decoder reports it: `color_space` and range from the bitstream, transfer and
+/// primaries from the container when it says. (Shared with `Vp9Decoder`.)
+pub(crate) fn vp9_color(width: u32, height: u32, color_space: u8, full_range: bool, transfer: Option<Transfer>, primaries: Option<Primaries>) -> ColorInfo {
+    use filmcraft_color::{Matrix, Range};
+    let mut color = ColorInfo { matrix: filmcraft_frame::default_matrix(width, height), ..ColorInfo::REC709 };
+    // color_space (7.2.2): 1 BT.601, 2 BT.709, 3 SMPTE-170, 4 SMPTE-240, 5 BT.2020, 7 sRGB.
+    match color_space {
+        1 | 3 => color.matrix = Matrix::Bt601,
+        2 | 4 => color.matrix = Matrix::Bt709,
+        5 => {
+            color.matrix = Matrix::Bt2020Ncl;
+            color.primaries = Primaries::Bt2020;
+        }
+        _ => {}
+    }
+    if let Some(t) = transfer {
+        color.transfer = t;
+    }
+    if let Some(p) = primaries {
+        color.primaries = p;
+    }
+    if full_range {
+        color.range = Range::Full;
+    }
+    color
+}
+
+/// AV1 colour as our decoder reports it. (Shared with `Av1Decoder`.)
+pub(crate) fn av1_color(width: u32, height: u32, matrix_coefficients: u8, transfer: u8, primaries: u8, full_range: bool) -> ColorInfo {
+    let mut color = ColorInfo::REC709;
+    color.matrix = filmcraft_color::Matrix::from_code(matrix_coefficients).unwrap_or_else(|| filmcraft_frame::default_matrix(width, height));
+    if let Some(t) = Transfer::from_code(transfer) {
+        color.transfer = t;
+    }
+    color.primaries = match primaries {
+        9 => Primaries::Bt2020,
+        12 => Primaries::P3D65,
+        5 => Primaries::Bt601_625,
+        6 => Primaries::Bt601_525,
+        _ => Primaries::Bt709,
+    };
+    if full_range {
+        color.range = filmcraft_color::Range::Full;
+    }
+    color
+}
+
+impl FrameStreamInfo {
+    /// The stream info of a `vpcC` / `av1C` sample entry (`None` for other codecs).
+    pub fn from_entry(e: &SampleEntry) -> Option<Result<Self>> {
+        let size = e.video.as_ref().map_or((0, 0), |v| (u32::from(v.width), u32::from(v.height)));
+        match &e.codec {
+            CodecConfig::Vp9(c) => {
+                // vpcC chroma_subsampling: 0 / 1 4:2:0, 2 4:2:2, 3 4:4:4
+                let subsampling = match c.chroma_subsampling {
+                    0 | 1 => (1, 1),
+                    2 => (1, 0),
+                    _ => (0, 0),
+                };
+                Some(Ok(Self {
+                    codec: FrameCodec::Vp9,
+                    profile: c.profile,
+                    bit_depth: u32::from(c.bit_depth),
+                    subsampling,
+                    mono: false,
+                    size,
+                    config_obus: Vec::new(),
+                    sequence_header: None,
+                    color: None,
+                    transfer: Transfer::from_code(c.transfer_characteristics),
+                    primaries: primaries_from_code(c.colour_primaries),
+                }))
+            }
+            CodecConfig::Av1(c) => Some(Self::from_av1(c, size)),
+            _ => None,
+        }
+    }
+
+    fn from_av1(c: &filmcraft_isobmff::Av1Config, entry_size: (u32, u32)) -> Result<Self> {
+        let seq =
+            obus(&c.config_obus).into_iter().find(|(t, _)| *t == 1).map(|(_, p)| p).ok_or_else(|| CodecError::Decode("av1C has no sequence header".into()))?;
+        let h = filmcraft_av1::SequenceHeader::parse(seq).map_err(|e| CodecError::Decode(e.to_string()))?;
+        let size = (h.max_frame_width, h.max_frame_height);
+        if entry_size != (0, 0) && entry_size != size {
+            // the sample entry and the sequence header disagree: leave the stream to our decoder
+            return Err(CodecError::Decode(format!("sample entry says {}x{}, the sequence header {}x{}", entry_size.0, entry_size.1, size.0, size.1)));
+        }
+        let cc = &h.color;
+        Ok(Self {
+            codec: FrameCodec::Av1,
+            profile: h.profile,
+            bit_depth: u32::from(cc.bit_depth),
+            subsampling: (cc.subsampling_x, cc.subsampling_y),
+            mono: cc.mono_chrome,
+            size,
+            config_obus: c.config_obus.clone(),
+            sequence_header: Some(seq.to_vec()),
+            color: Some(av1_color(size.0, size.1, cc.matrix_coefficients, cc.transfer_characteristics, cc.color_primaries, cc.color_range)),
+            transfer: None,
+            primaries: None,
+        })
+    }
+
+    /// Whether `sample` has a sequence header OBU of its own (AV1).
+    pub fn carries_sequence_header(&self, sample: &[u8]) -> bool {
+        self.codec == FrameCodec::Av1 && obus(sample).iter().any(|(t, _)| *t == 1)
+    }
+
+    /// A description made by hand (tests of what a backend declines).
+    #[doc(hidden)]
+    pub fn for_tests(codec: FrameCodec, profile: u8, bit_depth: u32, subsampling: (u8, u8), size: (u32, u32)) -> Self {
+        Self {
+            codec,
+            profile,
+            bit_depth,
+            subsampling,
+            mono: false,
+            size,
+            config_obus: Vec::new(),
+            sequence_header: None,
+            color: None,
+            transfer: None,
+            primaries: None,
+        }
+    }
+
+    /// Whether decoding can start at `sample` (a VP9 key frame / an AV1 temporal unit whose first
+    /// frame is a shown key frame): the software decoders' own test.
+    pub fn is_random_access(&self, sample: &[u8]) -> bool {
+        match self.codec {
+            FrameCodec::Vp9 => filmcraft_vp9::is_keyframe(sample),
+            FrameCodec::Av1 => filmcraft_av1::is_key_frame_unit(sample),
+        }
+    }
+
+    /// The picture parameters a random-access `sample` declares (a VP9 key frame header; an AV1
+    /// sample carrying a sequence header), or `None`.
+    pub fn picture_params(&self, sample: &[u8]) -> Option<PictureParams> {
+        match self.codec {
+            FrameCodec::Vp9 => {
+                let k = filmcraft_vp9::keyframe_info(sample)?;
+                let color = vp9_color(k.width, k.height, k.color.color_space, k.color.full_range, self.transfer, self.primaries);
+                Some(PictureParams {
+                    size: (k.width, k.height),
+                    bit_depth: k.bit_depth,
+                    subsampling: (u8::from(k.subsampling_x), u8::from(k.subsampling_y)),
+                    color,
+                })
+            }
+            FrameCodec::Av1 => {
+                let seq = obus(sample).into_iter().find(|(t, _)| *t == 1).map(|(_, p)| p)?;
+                let h = filmcraft_av1::SequenceHeader::parse(seq).ok()?;
+                let cc = &h.color;
+                let size = (h.max_frame_width, h.max_frame_height);
+                let color = av1_color(size.0, size.1, cc.matrix_coefficients, cc.transfer_characteristics, cc.color_primaries, cc.color_range);
+                Some(PictureParams { size, bit_depth: u32::from(cc.bit_depth), subsampling: (cc.subsampling_x, cc.subsampling_y), color })
+            }
+        }
+    }
+
+    /// Whether `sample` declares parameters the hardware session was not set up for: an AV1
+    /// sequence header that differs from `av1C`'s, a VP9 key frame of another size, bit depth or
+    /// chroma format. The decoder then hands the stream to our software decoder.
+    pub fn parameters_changed(&self, sample: &[u8]) -> bool {
+        match self.codec {
+            FrameCodec::Av1 => obus(sample).into_iter().any(|(t, p)| t == 1 && self.sequence_header.as_deref() != Some(p)),
+            FrameCodec::Vp9 => {
+                self.picture_params(sample).is_some_and(|p| p.size != self.size || p.bit_depth != self.bit_depth || p.subsampling != self.subsampling)
+            }
+        }
+    }
+}
@@ -16,8 +16,13 @@
 //! - [`AudioFileSource`]: standalone compressed audio files (MP3, FLAC, AIFF, …).
 //! - [`openers`]: the openers to register with the engine's media pool.

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
+pub mod apv;
 pub mod audio;
 pub mod gop;
+pub mod hw;
+mod hw_frame;
 pub mod mkv;
 pub mod mp4;
 pub mod mpeg;
@@ -27,8 +32,9 @@ pub mod video;

 use std::sync::{Arc, RwLock};

+pub use apv::ApvSource;
 pub use audio::AudioFileSource;
-pub use gop::{GopStats, gop_stats};
+pub use gop::{FRAME_BUDGET, GopStats, cached_bytes, gop_stats, live_decoders};
 pub use mkv::MkvSource;
 pub use mp4::Mp4Source;
 pub use mpeg::MpegSource;
@@ -61,20 +67,22 @@ impl From<CodecError> for filmcraft_media::MediaError {
    }
 }

+/// Our own (pure-Rust) decoders, in the order they are tried.
+const BUILTIN_FACTORIES: [VideoDecoderFactory; 9] = [
+    video::h264_factory,
+    video::hevc_factory,
+    video::vp9_factory,
+    video::av1_factory,
+    video::apv_factory,
+    video::prores_factory,
+    video::dnx_factory,
+    video::mjpeg_factory,
+    video::mpeg2_factory,
+];
+
 fn factories() -> &'static RwLock<Vec<VideoDecoderFactory>> {
    static F: std::sync::OnceLock<RwLock<Vec<VideoDecoderFactory>>> = std::sync::OnceLock::new();
-    F.get_or_init(|| {
-        RwLock::new(vec![
-            video::h264_factory,
-            video::hevc_factory,
-            video::vp9_factory,
-            video::av1_factory,
-            video::prores_factory,
-            video::dnx_factory,
-            video::mjpeg_factory,
-            video::mpeg2_factory,
-        ])
-    })
+    F.get_or_init(|| RwLock::new(BUILTIN_FACTORIES.to_vec()))
 }

 /// Register a video decoder factory (tried before previously registered ones).
@@ -85,6 +93,11 @@ pub fn register_video_decoder(f: VideoDecoderFactory) {
    }
 }

+/// Whether `f` is among the registered video decoder factories (startup diagnostics, tests).
+pub fn video_decoder_registered(f: VideoDecoderFactory) -> bool {
+    factories().read().unwrap_or_else(|e| e.into_inner()).iter().any(|x| std::ptr::fn_addr_eq(*x, f))
+}
+
 /// Create a decoder for a sample entry.
 pub fn make_video_decoder(entry: &filmcraft_isobmff::SampleEntry) -> Result<Box<dyn VideoDecoder>> {
    let g = factories().read().unwrap_or_else(|e| e.into_inner());
@@ -96,15 +109,26 @@ pub fn make_video_decoder(entry: &filmcraft_isobmff::SampleEntry) -> Result<Box<
    Err(CodecError::Unsupported(format!("no decoder for {} video", entry.codec.name())))
 }

+/// Create one of our own (software) decoders for a sample entry, skipping registered factories:
+/// what a hardware decoder falls back to when it fails mid-stream.
+pub fn software_video_decoder(entry: &filmcraft_isobmff::SampleEntry) -> Result<Box<dyn VideoDecoder>> {
+    for f in BUILTIN_FACTORIES {
+        if let Some(r) = f(entry) {
+            return r;
+        }
+    }
+    Err(CodecError::Unsupported(format!("no decoder for {} video", entry.codec.name())))
+}
+
 /// Openers for the engine's media pool (MP4/MOV, Matroska/WebM, MXF, Ogg Opus/Vorbis, MPEG TS/PS and
-/// MPEG-1/2 video elementary streams, standalone audio).
+/// MPEG-1/2 video elementary streams, APV raw bitstreams, standalone audio).
 pub fn openers() -> Vec<filmcraft_media::Opener> {
-    vec![mp4::opener, mkv::opener, mxf::opener, ogg::opener, mpeg::opener, audio::opener]
+    vec![mp4::opener, mkv::opener, mxf::opener, ogg::opener, mpeg::opener, apv::opener, audio::opener]
 }

 fn reader_registry() -> &'static RwLock<Vec<filmcraft_media::ReaderOpener>> {
    static R: std::sync::OnceLock<RwLock<Vec<filmcraft_media::ReaderOpener>>> = std::sync::OnceLock::new();
-    R.get_or_init(|| RwLock::new(vec![mp4::reader_opener, mkv::reader_opener, mxf::reader_opener, ogg::reader_opener, mpeg::reader_opener]))
+    R.get_or_init(|| RwLock::new(vec![mp4::reader_opener, mkv::reader_opener, mxf::reader_opener, ogg::reader_opener, mpeg::reader_opener, apv::reader_opener]))
 }

 /// Openers that read containers through a [`filmcraft_media::ByteReader`] (index now, samples on
@@ -149,5 +173,7 @@ pub fn open_bytes(name: &str, bytes: Arc<[u8]>) -> std::result::Result<filmcraft
    filmcraft_media::open_bytes(name, bytes, &openers())
 }

+#[cfg(test)]
+mod rounded_pts_tests;
 #[cfg(test)]
 mod tests;
@@ -100,9 +100,12 @@ fn to_tick(t: &filmcraft_matroska::Track, pts: i64) -> Tick {
    Tick::from_rational(pts * n, 1, d)
 }

+/// A time as the track timestamp to look a frame up by: rounded to the nearest tick, as muxers
+/// round frame times to `TimestampScale` (usually 1 ms). Flooring skipped every frame whose
+/// timestamp was rounded up (every third frame at 30 fps).
 fn from_tick(t: &filmcraft_matroska::Track, time: Tick) -> i64 {
    let (n, d) = tb(t);
-    time.to_rational_floor(n, d)
+    time.to_rational_round(n, d)
 }

 /// VP9 configuration from the Matroska `CodecPrivate` feature list (ID / length / value triples:
@@ -142,6 +145,7 @@ fn sample_entry(c: &Codec, private: &[u8], v: Option<&filmcraft_matroska::VideoI
    Some(match c {
        Codec::Vp9 { private } => SampleEntry::video(FourCc(*b"vp09"), CodecConfig::Vp9(vp9_config(private, v)), w, h),
        Codec::Av1 { av1c } => SampleEntry::video(FourCc(*b"av01"), CodecConfig::Av1(filmcraft_isobmff::Av1Config::parse(av1c).unwrap_or_default()), w, h),
+        Codec::Apv { apvc } => SampleEntry::apv(filmcraft_isobmff::ApvConfig::parse(apvc).unwrap_or_default(), w, h),
        Codec::Avc { avcc } => SampleEntry::avc(AvcConfig::parse(avcc).ok()?, w, h),
        Codec::Hevc { hvcc } => SampleEntry::hevc(HevcConfig::parse(hvcc).ok()?, w, h),
        Codec::ProRes { fourcc } => SampleEntry::prores(FourCc(fourcc.unwrap_or(*b"apcn")), w, h),
@@ -154,6 +158,20 @@ fn sample_entry(c: &Codec, private: &[u8], v: Option<&filmcraft_matroska::VideoI
    })
 }

+/// HDR static metadata from the Matroska `Colour` element.
+fn hdr_metadata(c: &filmcraft_matroska::Colour) -> Option<filmcraft_color::HdrMetadata> {
+    if c.mastering.is_none() && c.max_cll.is_none() && c.max_fall.is_none() {
+        return None;
+    }
+    let nz = |v: f64| (v > 0.0).then_some(v as f32);
+    Some(filmcraft_color::HdrMetadata {
+        mastering_max_nits: c.mastering.as_ref().and_then(|m| nz(m.luminance_max)),
+        mastering_min_nits: c.mastering.as_ref().map(|m| m.luminance_min as f32),
+        max_cll: c.max_cll.and_then(|v| nz(v as f64)),
+        max_fall: c.max_fall.and_then(|v| nz(v as f64)),
+    })
+}
+
 fn color_of(v: &filmcraft_matroska::VideoInfo, w: u32, h: u32) -> (ColorInfo, bool) {
    let mut c = ColorInfo { matrix: filmcraft_frame::default_matrix(w, h), transfer: Transfer::Bt709, primaries: Primaries::Bt709, range: Range::Limited };
    let Some(col) = &v.colour else { return (c, false) };
@@ -189,6 +207,10 @@ fn codec_label(c: &Codec) -> String {
        Codec::Vp8 => "VP8".into(),
        Codec::Vp9 { .. } => "VP9".into(),
        Codec::Av1 { .. } => "AV1".into(),
+        Codec::Apv { apvc } => match filmcraft_isobmff::ApvConfig::parse(apvc).ok().and_then(|a| filmcraft_apv::Profile::from_idc(a.profile_idc)) {
+            Some(p) => p.name().into(),
+            None => "APV".into(),
+        },
        Codec::ProRes { .. } => "Apple ProRes".into(),
        Codec::Mjpeg => "Motion JPEG".into(),
        Codec::Aac { .. } => "AAC".into(),
@@ -220,6 +242,8 @@ impl MkvSource {
        }
        let mut explicit_color = None;
        let mut ventry = None;
+        // display rotation from the track's Projection (portrait phone video is stored landscape)
+        let rotation = vtrack.and_then(|i| file.tracks[i].video.as_ref()).and_then(|v| v.display_rotation()).unwrap_or(0);
        let video = vtrack.map(|i| {
            let t = &file.tracks[i];
            let v = t.video.clone().unwrap_or_default();
@@ -241,16 +265,18 @@ impl MkvSource {
            ventry = sample_entry(&t.codec, &t.codec_private, t.video.as_ref(), w as u16, h as u16);
            let secs = file.duration_ns().unwrap_or(0) as f64 / 1e9;
            let bitrate = (secs > 0.0).then(|| (t.samples.iter().map(|s| s.size as u64).sum::<u64>() as f64 * 8.0 / secs) as u64);
+            let ((w, h), par) = if rotation % 2 == 1 { ((h, w), (v.pixel_aspect().1, v.pixel_aspect().0)) } else { ((w, h), v.pixel_aspect()) };
            VideoStreamInfo {
                width: w,
                height: h,
                frame_rate: rate,
-                par: v.pixel_aspect(),
+                par,
                codec: codec_label(&t.codec),
                pixel_format: String::new(),
                color,
                has_alpha: v.alpha_mode != 0,
                bitrate,
+                hdr: v.colour.as_ref().and_then(hdr_metadata),
            }
        });
        let audio = atrack.map(|i| {
@@ -317,7 +343,7 @@ impl MkvSource {
            vtrack,
            atrack,
            ventry,
-            video: GopCache::new(explicit_color),
+            video: GopCache::new(explicit_color).with_rotation(rotation),
            audio: Mutex::new(AudioState { decoder: None, packets: HashMap::new(), order: Vec::new(), last_decoded: None }),
            audio_starts,
            audio_preroll,
@@ -351,9 +377,9 @@ impl MkvSource {
        if let Some(p) = st.packets.get(&i) {
            return Ok(p.clone());
        }
-        let ti = self.atrack.expect("audio");
+        let ti = self.atrack.ok_or_else(|| CodecError::Unsupported("no audio track".into()))?;
        let track = &self.file.tracks[ti];
-        let ainfo = self.info.audio.as_ref().expect("audio info");
+        let ainfo = self.info.audio.as_ref().ok_or_else(|| CodecError::Unsupported("no audio track".into()))?;
        let data = self.read(ti, i)?;
        let decoded = match &track.codec {
            Codec::Pcm { float, big_endian, bits } => {
@@ -374,7 +400,7 @@ impl MkvSource {
                // Non-sequential access: reset and prime with the preceding packets (codec pre-roll:
                // one packet, or `SeekPreRoll` worth for Opus).
                if st.last_decoded.is_none_or(|l| l + 1 != i) {
-                    let d = st.decoder.as_mut().expect("decoder");
+                    let d = st.decoder.as_mut().ok_or_else(|| CodecError::Decode("no audio decoder".into()))?;
                    d.reset();
                    let from = if self.audio_preroll > 0 {
                        self.audio_starts.partition_point(|&x| x <= self.audio_starts[i] - self.audio_preroll).saturating_sub(1)
@@ -387,7 +413,7 @@ impl MkvSource {
                        }
                    }
                }
-                let r = st.decoder.as_mut().expect("decoder").decode(&data, self.audio_starts[i].max(0) as u64);
+                let r = st.decoder.as_mut().ok_or_else(|| CodecError::Decode("no audio decoder".into()))?.decode(&data, self.audio_starts[i].max(0) as u64);
                st.last_decoded = Some(i);
                r.unwrap_or_default()
            }
@@ -18,6 +18,9 @@ use crate::gop::{GopCache, VideoSamples};
 use crate::video::VideoDecoder;
 use crate::{CodecError, make_video_decoder};

+/// Most bytes read from one AAC access unit when probing for HE-AAC at open (8 channels × 6144 bits).
+const MAX_AAC_PROBE_UNIT: usize = 8 * 6144 / 8;
+
 struct AudioState {
    decoder: Option<PacketDecoder>,
    /// Decoded packets by sample index.
@@ -46,9 +49,23 @@ pub fn sniff(b: &[u8]) -> bool {
    b.len() >= 12 && matches!(&b[4..8], b"ftyp" | b"moov" | b"mdat" | b"wide" | b"free" | b"skip")
 }

+/// HDR static metadata from the sample entry's `mdcv` / `clli` boxes (0 = unknown).
+fn hdr_metadata(md: Option<&filmcraft_isobmff::MasteringDisplay>, cll: Option<(u16, u16)>) -> Option<filmcraft_color::HdrMetadata> {
+    if md.is_none() && cll.is_none() {
+        return None;
+    }
+    let nz = |v: f32| (v > 0.0).then_some(v);
+    Some(filmcraft_color::HdrMetadata {
+        mastering_max_nits: md.and_then(|m| nz(m.max_nits() as f32)),
+        mastering_min_nits: md.map(|m| m.min_luminance as f32 / 10_000.0),
+        max_cll: cll.and_then(|c| nz(c.0 as f32)),
+        max_fall: cll.and_then(|c| nz(c.1 as f32)),
+    })
+}
+
 fn color_from(entry: &filmcraft_isobmff::SampleEntry, w: u32, h: u32) -> ColorInfo {
    let mut c = ColorInfo { matrix: filmcraft_frame::default_matrix(w, h), transfer: Transfer::Bt709, primaries: Primaries::Bt709, range: Range::Limited };
-    // VP9 carries its colour description in vpcC (used when there is no colr box).
+    // VP9 and APV carry their colour description in vpcC / apvC (used when there is no colr box).
    let vpc = match &entry.codec {
        CodecConfig::Vp9(v) => Some(filmcraft_isobmff::ColorInfo::Nclx {
            primaries: v.colour_primaries as u16,
@@ -56,6 +73,12 @@ fn color_from(entry: &filmcraft_isobmff::SampleEntry, w: u32, h: u32) -> ColorIn
            matrix: v.matrix_coefficients as u16,
            full_range: v.full_range,
        }),
+        CodecConfig::Apv(a) if a.color_description_present => Some(filmcraft_isobmff::ColorInfo::Nclx {
+            primaries: a.color_primaries as u16,
+            transfer: a.transfer_characteristics as u16,
+            matrix: a.matrix_coefficients as u16,
+            full_range: a.full_range,
+        }),
        _ => None,
    };
    if let Some(col) = entry.video.as_ref().and_then(|v| v.color.as_ref()).or(vpc.as_ref()) {
@@ -93,13 +116,18 @@ impl Mp4Source {
    pub fn open_reader(name: &str, reader: filmcraft_media::SharedReader) -> crate::Result<Self> {
        let bytes = crate::Src(reader);
        let file = filmcraft_isobmff::open(&bytes).map_err(|e| CodecError::Container(e.to_string()))?;
-        let vtrack = file.tracks.iter().position(|t| t.kind == TrackKind::Video && !t.samples.is_empty());
-        let atrack = file.tracks.iter().position(|t| t.kind == TrackKind::Audio && !t.samples.is_empty());
+        // A track needs samples, a sample description and a timescale to be playable (damaged
+        // files can lack them: indexing `entries[0]` or dividing by the timescale used to panic).
+        let playable = |t: &&filmcraft_isobmff::Track, kind| t.kind == kind && !t.samples.is_empty() && !t.entries.is_empty() && t.timescale > 0;
+        let vtrack = file.tracks.iter().position(|t| playable(&t, TrackKind::Video));
+        let atrack = file.tracks.iter().position(|t| playable(&t, TrackKind::Audio));
        if vtrack.is_none() && atrack.is_none() {
            return Err(CodecError::Unsupported("no playable tracks".into()));
        }
        let mut color = ColorInfo::REC709;
        let mut explicit_color = None;
+        // display rotation from the track matrix (portrait phone video is stored landscape)
+        let rotation = vtrack.and_then(|i| file.tracks[i].display_rotation()).unwrap_or(0);
        let video = vtrack.map(|i| {
            let t = &file.tracks[i];
            let entry = &t.entries[0];
@@ -110,6 +138,8 @@ impl Mp4Source {
            durs.sort_unstable();
            let d = durs.get(durs.len() / 2).copied().unwrap_or(1).max(1);
            let rate = FrameRate::from_f64(t.timescale as f64 / d as f64);
+            // A rate that rounds to zero (one sample per huge duration) can't be divided by.
+            let rate = if rate.num > 0 && rate.den > 0 { rate } else { FrameRate::default() };
            color = color_from(entry, w, h);
            if entry
                .video
@@ -127,9 +157,15 @@ impl Mp4Source {
                codec: codec_label(&entry.codec),
                pixel_format: pixfmt_label(&entry.codec),
                color,
-                has_alpha: matches!(&entry.codec, CodecConfig::ProRes { fourcc } if fourcc.0 == *b"ap4h" || fourcc.0 == *b"ap4x"),
+                // ProRes 4444 alpha comes from its first frame header (`open_reader`)
+                has_alpha: matches!(&entry.codec, CodecConfig::Apv(a) if a.chroma_format_idc == 4),
                bitrate,
+                hdr: entry.video.as_ref().and_then(|v| hdr_metadata(v.mastering_display.as_ref(), v.content_light)),
            };
+            if rotation % 2 == 1 {
+                (info.width, info.height) = (info.height, info.width);
+                info.par = (info.par.1, info.par.0);
+            }
            if matches!(entry.codec, CodecConfig::Dnx { .. }) {
                // the sample entry doesn't say which VC-3 compression ID it is: read the first frame header
                let s0 = &t.samples[0];
@@ -144,6 +180,19 @@ impl Mp4Source {
                    info.has_alpha = h.alpha;
                }
            }
+            if matches!(entry.codec, CodecConfig::ProRes { .. }) {
+                // a 4444 fourcc doesn't mean the frames carry alpha (alpha_channel_type does): read the first frame header
+                let s0 = &t.samples[0];
+                if let Some(h) = filmcraft_media::reader::read_range(&*bytes.0, s0.offset, s0.size as usize).ok().and_then(|d| filmcraft_prores::probe(&d).ok())
+                {
+                    info.has_alpha = h.alpha != filmcraft_prores::AlphaType::None;
+                    let sub = match h.chroma {
+                        filmcraft_prores::ChromaFormat::Yuv422 => "4:2:2 10-bit",
+                        filmcraft_prores::ChromaFormat::Yuv444 => "4:4:4 12-bit",
+                    };
+                    info.pixel_format = format!("{} {sub}", if info.has_alpha { "YUVA" } else { "YUV" });
+                }
+            }
            info
        });
        let audio = atrack.map(|i| {
@@ -152,7 +201,21 @@ impl Mp4Source {
            let ap = entry.audio.clone().unwrap_or_default();
            let (rate, ch, bits) = match &entry.codec {
                CodecConfig::Aac(a) => (
-                    if a.sample_rate > 0 { a.sample_rate } else { ap.sample_rate as u32 },
+                    {
+                        // HE-AAC plays at twice the core rate the AudioSpecificConfig starts with
+                        // an AAC access unit is at most 6144 bits per channel: a hostile `stsz` can't make us read more
+                        let units = t
+                            .samples
+                            .iter()
+                            .take(8)
+                            .filter_map(|x| filmcraft_media::reader::read_range(&*bytes.0, x.offset, (x.size as usize).min(MAX_AAC_PROBE_UNIT)).ok());
+                        let units: Vec<Vec<u8>> = units.collect();
+                        match crate::audio::aac_output_rate(&a.asc, units.iter().map(Vec::as_slice)) {
+                            Some(r) => r,
+                            None if a.sample_rate > 0 => a.sample_rate,
+                            None => ap.sample_rate as u32,
+                        }
+                    },
                    if a.channel_config > 0 { a.channel_config as u32 } else { ap.channels },
                    None,
                ),
@@ -162,17 +225,7 @@ impl Mp4Source {
            };
            AudioStreamInfo { sample_rate: rate.max(1), channels: ch.max(1), codec: codec_label(&entry.codec), bits_per_sample: bits }
        });
-        let duration = {
-            let v = vtrack.map(|i| {
-                let t = &file.tracks[i];
-                Tick::from_rational(t.duration as i64, 1, t.timescale as i64)
-            });
-            let a = atrack.map(|i| {
-                let t = &file.tracks[i];
-                Tick::from_rational(t.duration as i64, 1, t.timescale as i64)
-            });
-            v.or(a).unwrap_or_default()
-        };
+        let duration = vtrack.or(atrack).and_then(|i| file.tracks.get(i)).map(|t| presentation_duration(&file, t)).unwrap_or_default();
        let start_timecode = file.tracks.iter().find_map(|t| match t.codec() {
            Some(CodecConfig::Timecode(tc)) => tc.start_frame.map(|f| f as i64),
            _ => None,
@@ -220,7 +273,7 @@ impl Mp4Source {
            file,
            vtrack,
            atrack,
-            video: GopCache::new(explicit_color),
+            video: GopCache::new(explicit_color).with_rotation(rotation),
            audio: Mutex::new(AudioState { decoder: None, packets: HashMap::new(), order: Vec::new(), last_decoded: None }),
            audio_starts,
            audio_offset,
@@ -235,17 +288,19 @@ impl Mp4Source {
    fn video_at(&self, t: Tick) -> crate::Result<Arc<VideoFrame>> {
        let ti = self.vtrack.ok_or_else(|| CodecError::Unsupported("no video".into()))?;
        let ts = self.file.tracks[ti].timescale as i64;
-        let late = filmcraft_media::cancel::catch_up().map(|m| (t - m).to_rational_floor(1, ts));
-        self.video.frame_late(&Mp4Video { src: self, track: ti }, t.to_rational_floor(1, ts), late)
+        // Nearest, not floor: with a coarse timescale (1000) sample times are rounded, and a
+        // floored lookup lands one unit short of every frame whose time was rounded up.
+        let late = filmcraft_media::cancel::catch_up().map(|m| (t - m).to_rational_round(1, ts));
+        self.video.frame_late(&Mp4Video { src: self, track: ti }, t.to_rational_round(1, ts), late)
    }

    fn audio_packet(&self, st: &mut AudioState, i: usize) -> crate::Result<Arc<Vec<Vec<f32>>>> {
        if let Some(p) = st.packets.get(&i) {
            return Ok(p.clone());
        }
-        let ti = self.atrack.expect("audio");
+        let ti = self.atrack.ok_or_else(|| CodecError::Unsupported("no audio track".into()))?;
        let track = &self.file.tracks[ti];
-        let entry = &track.entries[0];
+        let entry = track.entries.first().ok_or_else(|| CodecError::Container("audio track without a sample description".into()))?;
        let data = self.read(ti, i)?;
        let decoded = match &entry.codec {
            CodecConfig::Pcm(p) => decode_pcm(&data, p),
@@ -256,7 +311,7 @@ impl Mp4Source {
                // Non-sequential access: reset and prime with the preceding packets (codec pre-roll:
                // one packet, or `OPUS_PRE_ROLL` worth for Opus).
                if st.last_decoded.is_none_or(|l| l + 1 != i) {
-                    let d = st.decoder.as_mut().expect("decoder");
+                    let d = st.decoder.as_mut().ok_or_else(|| CodecError::Decode("no audio decoder".into()))?;
                    d.reset();
                    let from = if self.audio_preroll > 0 {
                        self.audio_starts.partition_point(|&x| x <= self.audio_starts[i] - self.audio_preroll).saturating_sub(1)
@@ -269,7 +324,7 @@ impl Mp4Source {
                        }
                    }
                }
-                let r = st.decoder.as_mut().expect("decoder").decode(&data, self.audio_starts[i].max(0) as u64);
+                let r = st.decoder.as_mut().ok_or_else(|| CodecError::Decode("no audio decoder".into()))?.decode(&data, self.audio_starts[i].max(0) as u64);
                st.last_decoded = Some(i);
                match r {
                    Ok(v) => v,
@@ -333,7 +388,10 @@ impl MediaSource for Mp4Source {
        let ch = ainfo.channels.max(1) as usize;
        // Map the requested window to source samples (edit list offset applied: presentation = pts + edit_offset).
        let ratio = src_rate as f64 / sample_rate as f64;
-        let s0 = (start as f64 * ratio).floor() as i64 - self.audio_offset * src_rate as i64 / track.timescale.max(1) as i64;
+        let p0 = (start as f64 * ratio).floor() as i64;
+        // (in i128: a hostile edit list can make the offset large enough to overflow i64)
+        let offset = i128::from(self.audio_offset) * i128::from(src_rate) / i128::from(track.timescale.max(1));
+        let s0 = i64::try_from(i128::from(p0) - offset).unwrap_or(if offset > 0 { i64::MIN } else { i64::MAX });
        let need = (frames as f64 * ratio).ceil() as i64 + 2;
        // Samples-per-unit: the track timescale is usually the sample rate for audio.
        let unit = src_rate as f64 / track.timescale.max(1) as f64;
@@ -343,14 +401,14 @@ impl MediaSource for Mp4Source {
        let mut i = first;
        while i < track.samples.len() {
            let pk_start = (self.audio_starts[i] as f64 * unit) as i64;
-            if pk_start >= s0 + need {
+            if pk_start >= s0.saturating_add(need) {
                break;
            }
            let pk = self.audio_packet(&mut st, i)?;
            for (c, dst) in src.iter_mut().enumerate() {
                let Some(chan) = pk.get(c.min(pk.len().saturating_sub(1))) else { continue };
                for (k, v) in chan.iter().enumerate() {
-                    let pos = pk_start + k as i64 - s0;
+                    let pos = pk_start.saturating_add(k as i64).saturating_sub(s0);
                    if pos >= 0 && (pos as usize) < dst.len() {
                        dst[pos as usize] = *v;
                    }
@@ -367,8 +425,9 @@ impl MediaSource for Mp4Source {
            }
            return Ok(out);
        }
-        // resample the local window
-        let frac = s0 as f64 - start as f64 * ratio;
+        // Resample the local window. Its first sample is presentation sample `p0`; the edit list
+        // offset is already in `s0` and must not shift the read position a second time.
+        let frac = p0 as f64 - start as f64 * ratio;
        let mut out = AudioBuffer::silence(sample_rate, ch, frames);
        for k in 0..frames {
            let pos = k as f64 * ratio - frac;
@@ -401,6 +460,10 @@ fn codec_label(c: &CodecConfig) -> String {
        CodecConfig::Hevc(_) => "HEVC".into(),
        CodecConfig::Vp9(c) => format!("VP9 (Profile {})", c.profile),
        CodecConfig::Av1(c) => format!("AV1 ({} Profile)", ["Main", "High", "Professional"].get(c.seq_profile as usize).unwrap_or(&"Main")),
+        CodecConfig::Apv(a) => match filmcraft_apv::Profile::from_idc(a.profile_idc) {
+            Some(p) => p.name().into(),
+            None => "APV".into(),
+        },
        CodecConfig::ProRes { fourcc } => match &fourcc.0 {
            b"apco" => "Apple ProRes 422 Proxy".into(),
            b"apcs" => "Apple ProRes 422 LT".into(),
@@ -425,14 +488,37 @@ fn codec_label(c: &CodecConfig) -> String {
    }
 }

+/// "YUV 4:2:2 10-bit" from an H.264 / HEVC `chroma_format_idc` and bit depth.
+fn yuv_label(chroma_format_idc: u32, bits: u32) -> String {
+    let sub = match chroma_format_idc {
+        0 => "4:0:0",
+        1 => "4:2:0",
+        2 => "4:2:2",
+        _ => "4:4:4",
+    };
+    format!("YUV {sub} {bits}-bit")
+}
+
+/// `chroma_format_idc` and luma bit depth of an H.264 track: from the `avcC` High-profile extension
+/// (ISO/IEC 14496-15 §5.3.3), else from its first SPS. The profile alone can't say (High 4:2:2 is
+/// 8 or 10-bit, High 10 can be 8-bit).
+fn avc_format(a: &filmcraft_isobmff::AvcConfig) -> Option<(u32, u32)> {
+    // reserved bits set: '111111' chroma_format, '11111' bit_depth_luma_minus8 (else not an extension)
+    if !matches!(a.profile, 66 | 77 | 88)
+        && let &[chroma, depth, ..] = a.ext.as_slice()
+        && chroma & 0xFC == 0xFC
+        && depth & 0xF8 == 0xF8
+    {
+        return Some(((chroma & 3) as u32, (depth & 7) as u32 + 8));
+    }
+    let sps = filmcraft_h264::params::Sps::parse(&filmcraft_bitstream::unescape_rbsp(a.sps.first()?.get(1..)?)).ok()?;
+    Some((sps.chroma_format_idc, sps.bit_depth_luma))
+}
+
 fn pixfmt_label(c: &CodecConfig) -> String {
    match c {
-        CodecConfig::Avc(a) => match a.profile {
-            110 => "YUV 4:2:0 10-bit".into(),
-            122 => "YUV 4:2:2".into(),
-            244 => "YUV 4:4:4".into(),
-            _ => "YUV 4:2:0 8-bit".into(),
-        },
+        CodecConfig::Avc(a) => avc_format(a).map(|(chroma, bits)| yuv_label(chroma, bits)).unwrap_or_default(),
+        CodecConfig::Hevc(h) => yuv_label(h.chroma_format_idc as u32, h.bit_depth_luma as u32),
        CodecConfig::Vp9(c) => {
            let sub = match c.chroma_subsampling {
                2 => "4:2:2",
@@ -441,7 +527,12 @@ fn pixfmt_label(c: &CodecConfig) -> String {
            };
            format!("YUV {sub} {}-bit", c.bit_depth.max(8))
        }
-        CodecConfig::ProRes { fourcc } if fourcc.0[2] == b'4' => "YUVA 4:4:4 12-bit".into(),
+        CodecConfig::Apv(a) => {
+            let chroma = filmcraft_apv::ChromaFormat::from_idc(a.chroma_format_idc).unwrap_or(filmcraft_apv::ChromaFormat::Yuv422);
+            crate::apv::apv_pixfmt_label(chroma, a.bit_depth_minus8.saturating_add(8))
+        }
+        // 4444 until the first frame header says whether it codes alpha (`open_reader`)
+        CodecConfig::ProRes { fourcc } if fourcc.0[2] == b'4' => "YUV 4:4:4 12-bit".into(),
        CodecConfig::ProRes { .. } => "YUV 4:2:2 10-bit".into(),
        CodecConfig::Jpeg { .. } => "YUV 4:2:x 8-bit".into(),
        _ => String::new(),
@@ -455,6 +546,25 @@ pub fn opener(name: &str, bytes: Arc<[u8]>) -> Option<Result<SharedSource, Media
    Some(Mp4Source::open(name, bytes).map(|s| Arc::new(s) as SharedSource).map_err(Into::into))
 }

+/// How long a track plays. With an edit list that is the sum of its edits (ISO/IEC 14496-12
+/// §8.6.6, movie timescale), as `tkhd` records it. The media duration (`mdhd`) runs on the decode
+/// timeline: it is longer than the presentation by the B-frame delay an edit skips (`media_time`, one
+/// extra frame on every ffmpeg / x264 MP4 with B-frames) and shorter by a leading empty edit (the last
+/// frame of a delayed video track was never shown). Fragmented files, and edit lists that add up to
+/// nothing or to more than a [`Tick`] holds, keep the media duration.
+fn presentation_duration(file: &Mp4File, t: &filmcraft_isobmff::Track) -> Tick {
+    let media = Tick::from_rational(t.duration as i64, 1, t.timescale as i64);
+    if file.fragmented || t.edits.is_empty() || file.timescale == 0 {
+        return media;
+    }
+    let edits = t.edits.iter().fold(0u128, |a, e| a.saturating_add(e.segment_duration as u128));
+    let ticks = edits.saturating_mul(filmcraft_time::TICKS_PER_SECOND as u128) / file.timescale as u128;
+    match i64::try_from(ticks) {
+        Ok(t) if t > 0 => Tick(t),
+        _ => media,
+    }
+}
+
 /// [`filmcraft_media::ReaderOpener`] for MP4/MOV.
 pub fn reader_opener(name: &str, head: &[u8], reader: &filmcraft_media::SharedReader) -> Option<Result<SharedSource, MediaError>> {
    if !sniff(head) {
@@ -462,3 +572,296 @@ pub fn reader_opener(name: &str, head: &[u8], reader: &filmcraft_media::SharedRe
    }
    Some(Mp4Source::open_reader(name, reader.clone()).map(|s| Arc::new(s) as SharedSource).map_err(Into::into))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use filmcraft_isobmff::{Brand, FourCc, Mp4Writer, SampleEntry, TrackConfig, WriteSample, WriterOptions};
+    use filmcraft_media::FrameRequest;
+
+    /// A one-frame 64×32 ProRes MOV (bright left half, dark right half) whose `tkhd` matrix is
+    /// replaced by `matrix` — built here, no media files.
+    fn rotated_mov(matrix: [i32; 9]) -> Arc<[u8]> {
+        let (w, h) = (64u32, 32u32);
+        let mut fr = filmcraft_prores::Frame::new(w, h, filmcraft_prores::ChromaFormat::Yuv422, 10, false);
+        for (i, y) in fr.y.iter_mut().enumerate() {
+            *y = if (i as u32 % w) < w / 2 { 800 } else { 100 };
+        }
+        let data = filmcraft_prores::Encoder::new(filmcraft_prores::Profile::Hq, w, h).encode(&fr).expect("encode");
+        let mut mux = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mov)).expect("writer");
+        let t = mux.add_track(TrackConfig::new(SampleEntry::prores(FourCc(*b"apch"), w as u16, h as u16), 25)).expect("track");
+        mux.write_sample(t, WriteSample { data: &data, duration: 1, composition_offset: 0, is_sync: true }).expect("sample");
+        let mut b = mux.finish().expect("finish").into_inner();
+        // tkhd (ISO/IEC 14496-12 §8.3.2): version/flags, then 20 (v0) or 32 (v1) bytes of
+        // times/id/duration, 8 reserved, layer, alternate_group, volume, reserved, matrix
+        let k = b.windows(4).position(|x| x == b"tkhd").expect("tkhd") + 4;
+        let m = k + 4 + if b[k] == 1 { 32 } else { 20 } + 16;
+        for (j, v) in matrix.iter().enumerate() {
+            b[m + j * 4..m + j * 4 + 4].copy_from_slice(&v.to_be_bytes());
+        }
+        b.into()
+    }
+
+    /// A four-frame 25 fps ProRes MOV (64×32) whose video track carries `edits`.
+    fn mov_with_edits(edits: Vec<filmcraft_isobmff::Edit>) -> Arc<[u8]> {
+        let fr = filmcraft_prores::Frame::new(64, 32, filmcraft_prores::ChromaFormat::Yuv422, 10, false);
+        let data = filmcraft_prores::Encoder::new(filmcraft_prores::Profile::Hq, 64, 32).encode(&fr).expect("encode");
+        let mut mux = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mov)).expect("writer");
+        let mut cfg = TrackConfig::new(SampleEntry::prores(FourCc(*b"apch"), 64, 32), 25);
+        cfg.edits = edits;
+        let t = mux.add_track(cfg).expect("track");
+        for _ in 0..4 {
+            mux.write_sample(t, WriteSample { data: &data, duration: 1, composition_offset: 0, is_sync: true }).expect("sample");
+        }
+        mux.finish().expect("finish").into_inner().into()
+    }
+
+    /// A clip lasts as long as its edit list presents it, not as long as its media (`mdhd`) runs.
+    /// Every ffmpeg / x264 MP4 with B-frames skips its reorder delay with an edit and imported one
+    /// frame too long; a video track delayed by an empty edit lost its last frame.
+    #[test]
+    fn duration_follows_the_edit_list() {
+        use filmcraft_isobmff::Edit;
+        let frames = |s: &Mp4Source| s.info().duration.to_rational_floor(1, 25);
+        // no edit list: the media duration
+        assert_eq!(frames(&Mp4Source::open("plain.mov", mov_with_edits(Vec::new())).expect("open")), 4);
+        // skip the first frame (B-frame delay style): three frames play (movie timescale 1000 ms)
+        let skip = vec![Edit { segment_duration: 120, media_time: 1, media_rate: 0x10000 }];
+        assert_eq!(frames(&Mp4Source::open("skip.mov", mov_with_edits(skip)).expect("open")), 3);
+        // a one-frame empty edit, then all four frames: five frames, and the last one is there
+        let delayed =
+            vec![Edit { segment_duration: 40, media_time: -1, media_rate: 0x10000 }, Edit { segment_duration: 160, media_time: 0, media_rate: 0x10000 }];
+        let s = Mp4Source::open("delayed.mov", mov_with_edits(delayed)).expect("open");
+        assert_eq!(frames(&s), 5);
+        assert!(s.video_frame(FrameRequest::full(Tick::from_rational(4, 1, 25))).is_ok());
+        // hostile segment durations fall back to the media duration instead of wrapping
+        let huge = vec![Edit { segment_duration: u64::MAX, media_time: 0, media_rate: 0x10000 }];
+        assert_eq!(frames(&Mp4Source::open("huge.mov", mov_with_edits(huge)).expect("open")), 4);
+        let zero = vec![Edit { segment_duration: 0, media_time: 0, media_rate: 0x10000 }];
+        assert_eq!(frames(&Mp4Source::open("zero.mov", mov_with_edits(zero)).expect("open")), 4);
+    }
+
+    /// Overwrite the big-endian u32 `skip` bytes after the first `fourcc` box type.
+    fn patch_u32(b: &mut [u8], fourcc: &[u8; 4], skip: usize, v: u32) {
+        let k = b.windows(4).position(|x| x == fourcc).expect("box") + 4 + skip;
+        b[k..k + 4].copy_from_slice(&v.to_be_bytes());
+    }
+
+    /// Damaged MOVs found by mutation fuzzing panicked on import: a track with timescale 0
+    /// ("attempt to divide by zero" in the duration) and one whose sample description list is
+    /// empty ("index out of bounds" on `entries[0]`). Both must open as an error, or as media
+    /// that answers requests without panicking.
+    #[test]
+    fn damaged_track_headers_never_panic() {
+        let identity = [0x10000, 0, 0, 0, 0x10000, 0, 0, 0, 0x4000_0000];
+        // mdhd v0: version/flags, creation, modification, then timescale
+        let mut zero_timescale = rotated_mov(identity).to_vec();
+        patch_u32(&mut zero_timescale, b"mdhd", 12, 0);
+        // stsd: version/flags, then entry_count
+        let mut no_entries = rotated_mov(identity).to_vec();
+        patch_u32(&mut no_entries, b"stsd", 4, 0);
+        for (name, b) in [("ts0.mov", zero_timescale), ("stsd0.mov", no_entries)] {
+            if let Ok(s) = Mp4Source::open(name, b.into()) {
+                let _ = s.video_frame(FrameRequest::full(Tick::ZERO));
+                let _ = s.audio(0, 1024, 48_000);
+            }
+        }
+    }
+
+    /// Mean luma of the top and bottom halves of the decoded frame, and its size.
+    fn halves(src: &Mp4Source) -> (u32, u32, u8, u8) {
+        let f = src.video_frame(FrameRequest::full(Tick::ZERO)).expect("frame");
+        let l = f.luma8();
+        let half = l.len() / 2;
+        let mean = |s: &[u8]| (s.iter().map(|&v| v as u32).sum::<u32>() / s.len() as u32) as u8;
+        (f.width, f.height, mean(&l[..half]), mean(&l[half..]))
+    }
+
+    #[test]
+    fn display_matrix_rotates_frames_and_reported_size() {
+        const ONE: i32 = 0x10000;
+        const W: i32 = 0x4000_0000;
+        // identity: landscape 64x32, top and bottom alike
+        let s = Mp4Source::open("id.mov", rotated_mov([ONE, 0, 0, 0, ONE, 0, 0, 0, W])).expect("open");
+        let v = s.info().video.as_ref().expect("video");
+        assert_eq!((v.width, v.height), (64, 32));
+        let (w, h, top, bottom) = halves(&s);
+        assert_eq!((w, h), (64, 32));
+        assert!(top.abs_diff(bottom) < 4);
+
+        // 90° clockwise (what an iPhone writes for portrait): the left half ends up on top
+        let s = Mp4Source::open("cw.mov", rotated_mov([0, ONE, 0, -ONE, 0, 0, 32 * ONE, 0, W])).expect("open");
+        let v = s.info().video.as_ref().expect("video");
+        assert_eq!((v.width, v.height), (32, 64));
+        let (w, h, top, bottom) = halves(&s);
+        assert_eq!((w, h), (32, 64));
+        assert!(top > bottom + 100, "top {top} bottom {bottom}");
+
+        // 270° clockwise: the left half ends up at the bottom
+        let s = Mp4Source::open("ccw.mov", rotated_mov([0, -ONE, 0, ONE, 0, 0, 0, 64 * ONE, W])).expect("open");
+        let (w, h, top, bottom) = halves(&s);
+        assert_eq!((w, h), (32, 64));
+        assert!(bottom > top + 100, "top {top} bottom {bottom}");
+
+        // 180°: still landscape
+        let s = Mp4Source::open("180.mov", rotated_mov([-ONE, 0, 0, 0, -ONE, 0, 64 * ONE, 32 * ONE, W])).expect("open");
+        assert_eq!(s.info().video.as_ref().map(|v| (v.width, v.height)), Some((64, 32)));
+    }
+
+    #[test]
+    fn mirrored_or_scaled_matrices_are_not_mistaken_for_rotations() {
+        const ONE: i32 = 0x10000;
+        const W: i32 = 0x4000_0000;
+        // horizontal mirror: not a pure rotation, so the frame is left as stored
+        let s = Mp4Source::open("mirror.mov", rotated_mov([-ONE, 0, 0, 0, ONE, 0, 64 * ONE, 0, W])).expect("open");
+        let (w, h, top, bottom) = halves(&s);
+        assert_eq!((w, h), (64, 32));
+        assert!(top.abs_diff(bottom) < 4);
+        // a 2× scaled identity is still upright (only the signs decide the rotation)
+        let s = Mp4Source::open("scaled.mov", rotated_mov([2 * ONE, 0, 0, 0, 2 * ONE, 0, 0, 0, W])).expect("open");
+        assert_eq!(s.info().video.as_ref().map(|v| (v.width, v.height)), Some((64, 32)));
+        // a scaled quarter turn is still a quarter turn
+        let s = Mp4Source::open("cw2.mov", rotated_mov([0, 2 * ONE, 0, -2 * ONE, 0, 0, 64 * ONE, 0, W])).expect("open");
+        assert_eq!(s.info().video.as_ref().map(|v| (v.width, v.height)), Some((32, 64)));
+    }
+
+    #[test]
+    fn hevc_pixel_format_comes_from_hvcc() {
+        for (chroma, bits, want) in [(1, 8, "YUV 4:2:0 8-bit"), (1, 10, "YUV 4:2:0 10-bit"), (2, 8, "YUV 4:2:2 8-bit"), (2, 10, "YUV 4:2:2 10-bit")] {
+            let c = filmcraft_isobmff::HevcConfig { general_profile_idc: 1, chroma_format_idc: chroma, bit_depth_luma: bits, ..Default::default() };
+            assert_eq!(pixfmt_label(&CodecConfig::Hevc(c)), want);
+        }
+    }
+
+    /// A High-profile SPS NAL unit (ITU-T H.264 §7.3.2.1.1) with the given chroma format and bit depth, 16×16.
+    fn high_sps(profile: u8, chroma: u32, bits: u32) -> Vec<u8> {
+        let mut w = filmcraft_bitstream::BitWriter::new();
+        w.write_bits(0x67, 8);
+        w.write_bits(profile as u32, 8);
+        w.write_bits(0, 8); // constraint flags
+        w.write_bits(30, 8); // level
+        w.write_ue(0); // seq_parameter_set_id
+        w.write_ue(chroma);
+        if chroma == 3 {
+            w.write_bit(false); // separate_colour_plane_flag
+        }
+        w.write_ue(bits - 8); // luma
+        w.write_ue(bits - 8); // chroma
+        w.write_bits(0, 2); // no transform bypass, no scaling matrices
+        w.write_ue(0); // log2_max_frame_num_minus4
+        w.write_ue(2); // pic_order_cnt_type
+        w.write_ue(1); // max_num_ref_frames
+        w.write_bit(false); // gaps_in_frame_num_allowed
+        w.write_ue(0); // pic_width_in_mbs_minus1
+        w.write_ue(0); // pic_height_in_map_units_minus1
+        w.write_bits(0b110, 3); // frame_mbs_only, direct_8x8_inference, no cropping
+        w.write_bit(false); // no VUI
+        w.rbsp_trailing();
+        w.finish()
+    }
+
+    #[test]
+    fn avc_pixel_format_comes_from_avcc_not_the_profile() {
+        let avc =
+            |profile: u8, sps: Vec<u8>, ext: Vec<u8>| CodecConfig::Avc(filmcraft_isobmff::AvcConfig { profile, sps: vec![sps], ext, ..Default::default() });
+        // High 4:2:2 at 10 and 8 bits, from the avcC extension (chroma_format 2, bit_depth_luma_minus8)
+        assert_eq!(pixfmt_label(&avc(122, high_sps(122, 2, 10), vec![0xFE, 0xFA, 0xFA, 0])), "YUV 4:2:2 10-bit");
+        assert_eq!(pixfmt_label(&avc(122, high_sps(122, 2, 8), vec![0xFE, 0xF8, 0xF8, 0])), "YUV 4:2:2 8-bit");
+        // no extension (or not a valid one): the SPS says
+        assert_eq!(pixfmt_label(&avc(122, high_sps(122, 2, 10), Vec::new())), "YUV 4:2:2 10-bit");
+        assert_eq!(pixfmt_label(&avc(110, high_sps(110, 1, 10), vec![0, 0, 0, 0])), "YUV 4:2:0 10-bit");
+        assert_eq!(pixfmt_label(&avc(244, high_sps(244, 3, 10), Vec::new())), "YUV 4:4:4 10-bit");
+        // an unreadable SPS and no extension: unknown, not a guess
+        assert_eq!(pixfmt_label(&avc(122, vec![0x67, 122], Vec::new())), "");
+    }
+
+    /// A one-frame 32×16 ProRes MOV with the given profile, chroma format and fourcc.
+    fn prores_mov(profile: filmcraft_prores::Profile, fourcc: &[u8; 4], chroma: filmcraft_prores::ChromaFormat, alpha: bool) -> Arc<[u8]> {
+        let (w, h) = (32u32, 16u32);
+        let fr = filmcraft_prores::Frame::new(w, h, chroma, if chroma == filmcraft_prores::ChromaFormat::Yuv444 { 12 } else { 10 }, alpha);
+        let data = filmcraft_prores::Encoder::new(profile, w, h).encode(&fr).expect("encode");
+        let mut mux = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mov)).expect("writer");
+        let t = mux.add_track(TrackConfig::new(SampleEntry::prores(FourCc(*fourcc), w as u16, h as u16), 25)).expect("track");
+        mux.write_sample(t, WriteSample { data: &data, duration: 1, composition_offset: 0, is_sync: true }).expect("sample");
+        mux.finish().expect("finish").into_inner().into()
+    }
+
+    /// `ap4h` / `ap4x` don't imply alpha: the frame header's alpha_channel_type does.
+    #[test]
+    fn prores_alpha_comes_from_the_frame_header() {
+        use filmcraft_prores::{ChromaFormat, Profile};
+        for (profile, fourcc, chroma, alpha, want) in [
+            (Profile::P4444, b"ap4h", ChromaFormat::Yuv444, false, "YUV 4:4:4 12-bit"),
+            (Profile::P4444, b"ap4h", ChromaFormat::Yuv444, true, "YUVA 4:4:4 12-bit"),
+            (Profile::P4444Xq, b"ap4x", ChromaFormat::Yuv444, false, "YUV 4:4:4 12-bit"),
+            (Profile::Hq, b"apch", ChromaFormat::Yuv422, false, "YUV 4:2:2 10-bit"),
+        ] {
+            let s = Mp4Source::open("p.mov", prores_mov(profile, fourcc, chroma, alpha)).expect("open");
+            let v = s.info().video.as_ref().expect("video");
+            assert_eq!((v.pixel_format.as_str(), v.has_alpha), (want, alpha), "{}", String::from_utf8_lossy(fourcc));
+        }
+    }
+}
+
+#[cfg(test)]
+mod he_aac_tests {
+    use filmcraft_isobmff::{Brand, Mp4Writer, SampleEntry, TrackConfig, WriteSample, WriterOptions};
+    use filmcraft_media::MediaSource;
+
+    /// #108: an HE-AAC MP4 (explicit SBR signalling, core 22.05 kHz, output 44.1 kHz, timescale
+    /// 44.1 kHz) built here from our AAC-LC encoder: the stream has no SBR data, which only the
+    /// high band would need. It was reported at the 22.05 kHz core rate, so sequences made from
+    /// such a clip were created at 22.05 kHz.
+    #[test]
+    fn he_aac_plays_at_the_output_rate() {
+        let core = 22_050u32;
+        let n = core as usize * 2;
+        let tone: Vec<f32> = (0..n).map(|i| 0.25 * (2.0 * std::f32::consts::PI * 1000.0 * i as f32 / core as f32).sin()).collect();
+        let mut enc = filmcraft_aac::Encoder::new(filmcraft_aac::EncoderConfig::cbr(core, 2, 64_000)).unwrap();
+        let mut aus = enc.encode(&[&tone, &tone]);
+        aus.extend(enc.flush());
+        // AOT 5, core 22.05 kHz, stereo, extension 44.1 kHz, core AOT 2
+        let asc = vec![0x2B, 0x92, 0x08, 0x00];
+        let mut mux = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4)).unwrap();
+        let t = mux.add_track(TrackConfig::new(SampleEntry::aac(asc, 2, 44_100), 44_100)).unwrap();
+        for au in &aus {
+            mux.write_sample(t, WriteSample { data: au, duration: 2048, composition_offset: 0, is_sync: true }).unwrap();
+        }
+        let b = mux.finish().unwrap().into_inner();
+        let src = super::Mp4Source::open("he.mp4", b.into()).unwrap();
+        assert_eq!(src.info().audio.as_ref().unwrap().sample_rate, 44_100);
+        // one second from 0.5 s at 44.1 kHz: the 1 kHz tone at its level (not silence, not shifted)
+        let buf = src.audio(22_050, 44_100, 44_100).unwrap();
+        let x = &buf.channels[0];
+        let peak = x.iter().fold(0f32, |m, v| m.max(v.abs()));
+        assert!((0.2..0.3).contains(&peak), "peak {peak}");
+        let crossings = x.windows(2).filter(|w| w[0] < 0.0 && w[1] >= 0.0).count();
+        assert!((995..=1005).contains(&crossings), "{crossings} Hz");
+    }
+
+    /// A hostile edit list (#66): an AAC track whose edit puts it absurdly far off, read at another
+    /// rate, scaled the offset to the source rate in i64 and overflowed. It reads as silence now.
+    #[test]
+    fn hostile_audio_edit_offset_never_overflows() {
+        use filmcraft_isobmff::Edit;
+        let rate = 32_000u32;
+        let tone: Vec<f32> = (0..rate as usize / 2).map(|i| 0.25 * (i as f32 * 0.05).sin()).collect();
+        let mut enc = filmcraft_aac::Encoder::new(filmcraft_aac::EncoderConfig::cbr(rate, 1, 64_000)).unwrap();
+        let mut aus = enc.encode(&[&tone]);
+        aus.extend(enc.flush());
+        // AOT 2 (AAC-LC), 32 kHz (index 5), mono
+        let asc = vec![0x12, 0x88];
+        for media_time in [i64::MAX, i64::MAX / 3, i64::MIN / 3] {
+            let mut mux = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4)).unwrap();
+            let mut cfg = TrackConfig::new(SampleEntry::aac(asc.clone(), 1, rate), rate);
+            cfg.edits = vec![Edit { segment_duration: 500, media_time, media_rate: 0x10000 }];
+            let t = mux.add_track(cfg).unwrap();
+            for au in &aus {
+                mux.write_sample(t, WriteSample { data: au, duration: 1024, composition_offset: 0, is_sync: true }).unwrap();
+            }
+            let src = super::Mp4Source::open("hostile.mp4", mux.finish().unwrap().into_inner().into()).unwrap();
+            let buf = src.audio(0, 4800, 48_000).unwrap();
+            assert!(buf.channels.iter().flatten().all(|v| v.is_finite() && v.abs() <= 1.0), "media_time {media_time}");
+        }
+    }
+}
@@ -123,6 +123,19 @@ fn audio_supported(c: &Codec) -> bool {
    matches!(c, Codec::MpegAudio | Codec::AacAdts | Codec::AacLatm | Codec::LpcmBluray | Codec::LpcmDvd | Codec::Ac3)
 }

+/// The coded rate unless the timestamps say otherwise (3:2 pulldown, field-rate coding). Never
+/// zero: damaged timestamps spread over a huge span give a rate that rounds to 0 fps, which the
+/// duration computation divided by.
+fn stream_rate(coded: Option<FrameRate>, from_pts: Option<f64>) -> FrameRate {
+    let rate = match (coded, from_pts) {
+        (Some(r), Some(p)) if (r.as_f64() - p).abs() / p > 0.01 => FrameRate::from_f64(p),
+        (Some(r), _) => r,
+        (None, Some(p)) => FrameRate::from_f64(p),
+        (None, None) => FrameRate::FPS_25,
+    };
+    if rate.num > 0 && rate.den > 0 { rate } else { FrameRate::FPS_25 }
+}
+
 /// Display-order keys of samples (decode order): the PTS when every unit has one, else (MPEG
 /// video) GOP start + temporal_reference, else the decode order.
 fn display_keys(units: &[&Unit], mpeg: bool) -> Vec<i64> {
@@ -242,8 +255,9 @@ impl MpegSource {
                    src.file = Some(file);
                    src.video = Some(track);
                    src.describe_video(rate_from_pts)?;
-                    let file = src.file.take().expect("file");
-                    src.setup_audio(file, astream, origin);
+                    if let Some(file) = src.file.take() {
+                        src.setup_audio(file, astream, origin);
+                    }
                }
                None => {
                    src.unsupported_video = Some(format!("{} video in {} (FilmCraft has no decoder for it)", st.codec.name(), file.format.name()));
@@ -257,6 +271,7 @@ impl MpegSource {
                        color: filmcraft_color::ColorInfo::REC709,
                        has_alpha: false,
                        bitrate: None,
+                        hdr: None,
                    });
                    src.setup_audio(file, astream, None);
                }
@@ -368,14 +383,14 @@ impl MpegSource {
        if let Some((data, aus)) = &self.es {
            return Ok(data[aus[u].clone()].to_vec());
        }
-        let file = self.file.as_ref().expect("file");
+        let file = self.file.as_ref().ok_or_else(|| CodecError::Container("no stream file".into()))?;
        file.read_unit(&self.bytes, v.stream, u).map_err(|e| CodecError::Container(e.to_string()))
    }

    /// Fill in the video stream info from the first picture.
    fn describe_video(&mut self, rate_from_pts: Option<f64>) -> crate::Result<()> {
        let mut seq_header = None;
-        let v = self.video.as_ref().expect("video");
+        let v = self.video.as_ref().ok_or_else(|| CodecError::Unsupported("no video stream".into()))?;
        let first = self.read_unit(v, 0)?;
        let n = v.order.len();
        let (width, height, par, codec, pixel_format, mut color);
@@ -431,12 +446,7 @@ impl MpegSource {
            }
        }
        // the coded rate unless the timestamps say otherwise (3:2 pulldown, field-rate coding)
-        let rate = match (rate, rate_from_pts) {
-            (Some(r), Some(p)) if (r.as_f64() - p).abs() / p > 0.01 => FrameRate::from_f64(p),
-            (Some(r), _) => r,
-            (None, Some(p)) => FrameRate::from_f64(p),
-            (None, None) => FrameRate::FPS_25,
-        };
+        let rate = stream_rate(rate, rate_from_pts);
        let duration = rate.tick_of(n as i64);
        let total_bytes: u64 = match (&self.es, &self.file) {
            (Some((_, aus)), _) => v.units.iter().map(|&u| aus[u].len() as u64).sum(),
@@ -444,8 +454,10 @@ impl MpegSource {
            _ => 0,
        };
        let secs = duration.seconds();
-        if let Some(h) = seq_header {
-            self.video.as_mut().expect("video").header = h;
+        if let Some(h) = seq_header
+            && let Some(v) = self.video.as_mut()
+        {
+            v.header = h;
        }
        self.info.duration = duration;
        self.info.video = Some(VideoStreamInfo {
@@ -458,6 +470,7 @@ impl MpegSource {
            color,
            has_alpha: false,
            bitrate: (secs > 0.0).then(|| (total_bytes as f64 * 8.0 / secs) as u64),
+            hdr: None,
        });
        Ok(())
    }
@@ -523,7 +536,7 @@ impl MpegSource {
                    return self.audio_unsupported(&codec_name, "DVD LPCM: no format header".into());
                }
            },
-            _ => unreachable!("audio_supported"),
+            _ => return self.audio_unsupported(&codec_name, format!("{codec_name} audio")),
        };
        if codec_is_ac3_unsupported(codec) {
            return self.audio_unsupported(&codec_name, format!("{codec_name} audio (FilmCraft has no AC-3 decoder yet)"));
@@ -606,12 +619,12 @@ impl MpegSource {
        if let Some(p) = st.cache.get(&i) {
            return Ok(p.clone());
        }
-        let file = self.file.as_ref().expect("file");
+        let file = self.file.as_ref().ok_or_else(|| CodecError::Container("no stream file".into()))?;
        let read = |k: usize| file.read_unit(&self.bytes, a.stream, k).map_err(|e| CodecError::Container(e.to_string()));
        if st.dec.is_none() {
            st.dec = Some(AudioDecoder::new(a.codec, a.rate, a.channels, a.latm.clone())?);
        }
-        let dec = st.dec.as_mut().expect("decoder");
+        let dec = st.dec.as_mut().ok_or_else(|| CodecError::Decode("no audio decoder".into()))?;
        if st.last.is_none_or(|l| l + 1 != i) {
            dec.reset();
            if i > 0
@@ -838,6 +851,21 @@ pub fn reader_opener(name: &str, head: &[u8], reader: &filmcraft_media::SharedRe
 mod tests {
    use super::*;

+    /// A mutated transport stream whose PTS span gave ~0 fps panicked on open with "attempt to
+    /// divide by zero" (`FrameRate::tick_of`).
+    #[test]
+    fn damaged_timestamps_never_give_a_zero_rate() {
+        for (coded, p) in
+            [(None, Some(1e-9)), (Some(FrameRate::FPS_25), Some(1e-9)), (Some(FrameRate::new(0, 0)), None), (None, Some(0.0)), (None, Some(f64::NAN))]
+        {
+            let r = stream_rate(coded, p);
+            assert!(r.num > 0 && r.den > 0, "{coded:?} {p:?} -> {r:?}");
+            let _ = r.tick_of(1000);
+        }
+        assert_eq!(stream_rate(Some(FrameRate::FPS_25), Some(25.0)), FrameRate::FPS_25);
+        assert_eq!(stream_rate(None, Some(50.0)), FrameRate::from_f64(50.0));
+    }
+
    #[test]
    fn presentation_drops_leading_pictures_and_orders_by_key() {
        // decode order I(2) B(0) B(1) P(5) B(3) B(4): the leading B pictures are not presented
@@ -320,6 +320,7 @@ impl MxfSource {
                color,
                has_alpha: p.alpha_depth > 0,
                bitrate: (secs > 0.0).then(|| (bytes_total as f64 * 8.0 / (t.samples.len().max(1) as f64 / rate.as_f64().max(1e-9))) as u64),
+                hdr: None,
            });
        }
        // Audio: all PCM sound tracks of the first track's rate, channels in track order
@@ -332,7 +333,7 @@ impl MxfSource {
            let mut channels = 0;
            for &ai in &atracks {
                let t = &file.tracks[ai];
-                let si = t.sound.as_ref().expect("sound info");
+                let Some(si) = t.sound.as_ref() else { continue };
                if si.sample_rate != rate {
                    continue;
                }
@@ -423,7 +424,7 @@ impl VideoSamples for MxfVideo<'_> {
            return Err(CodecError::Unsupported(why.clone()));
        }
        let t = &self.src.file.tracks[self.track];
-        let v = self.src.info.video.as_ref().expect("video info");
+        let v = self.src.info.video.as_ref().ok_or_else(|| CodecError::Unsupported("no video track".into()))?;
        let (w, h) = (v.width.min(u16::MAX as u32) as u16, v.height.min(u16::MAX as u32) as u16);
        match t.codec {
            Codec::Avc { .. } => Ok(Box::new(crate::video::H264Decoder::annexb())),
@@ -133,7 +133,7 @@ impl OggSource {
        }
        // Non-sequential access: reset and decode the pre-roll (RFC 7845 §4.6; see OPUS_PRE_ROLL).
        if st.last_decoded.is_none_or(|l| l + 1 != i) {
-            let d = st.decoder.as_mut().expect("decoder");
+            let d = st.decoder.as_mut().ok_or_else(|| CodecError::Decode("no audio decoder".into()))?;
            d.reset();
            let from = timing.starts.partition_point(|&x| x <= timing.starts[i] - OPUS_PRE_ROLL as i64).saturating_sub(1);
            for j in from..i {
@@ -143,7 +143,7 @@ impl OggSource {
            }
        }
        let data = read(i)?;
-        let r = st.decoder.as_mut().expect("decoder").decode(&data, 0);
+        let r = st.decoder.as_mut().ok_or_else(|| CodecError::Decode("no audio decoder".into()))?.decode(&data, 0);
        st.last_decoded = Some(i);
        let p = Arc::new(r.unwrap_or_default());
        st.packets.insert(i, p.clone());
@@ -0,0 +1,136 @@
+//! Frame lookup against timestamps rounded to the container's timebase (issue #73).
+//!
+//! WebM stores timestamps in 1 ms units, so at 30 fps frame 2 (66.67 ms) is stored as 67. Flooring
+//! the requested time to 66 picked frame 1 instead: every third frame was skipped and the one
+//! before it shown twice. MP4 has the same problem when a muxer picks a 1 ms track timescale.
+//!
+//! The streams are synthetic Motion-JPEG: each picture shows its index as a row of black and
+//! white blocks, so a decoded frame says which sample it came from.
+
+use std::io::Cursor;
+use std::sync::Arc;
+
+use filmcraft_frame::{PixelData, VideoFrame};
+use filmcraft_isobmff::{Brand, Mp4Writer, SampleEntry, TrackConfig, WriteSample, WriterOptions};
+use filmcraft_matroska::{MkvWriter, MuxOptions, TrackKind, TrackSpec};
+use filmcraft_media::{FrameRequest, MediaSource};
+use filmcraft_time::{FrameRate, TICKS_PER_SECOND, Tick};
+
+/// Bits of the frame index drawn per picture, one `BLOCK`-pixel square each.
+const BITS: u32 = 8;
+const BLOCK: u32 = 16;
+const SECONDS: i64 = 3;
+
+/// The rates that don't divide 1 ms evenly (affected), and 25 fps (never was).
+const RATES: [FrameRate; 7] =
+    [FrameRate::FPS_30, FrameRate::FPS_29_97, FrameRate::FPS_60, FrameRate::FPS_59_94, FrameRate::FPS_24, FrameRate::FPS_23_976, FrameRate::FPS_25];
+
+/// How the muxer quantised the exact frame times to milliseconds.
+#[derive(Clone, Copy, Debug)]
+enum Stamp {
+    /// To the nearest millisecond, halves up (mkvmerge, ffmpeg).
+    Nearest,
+    /// Truncated.
+    Floor,
+}
+
+fn picture(index: usize) -> Vec<u8> {
+    let img = image::GrayImage::from_fn(BITS * BLOCK, BLOCK, |x, _| image::Luma([if (index >> (x / BLOCK)) & 1 == 1 { 255 } else { 0 }]));
+    let mut out = Vec::new();
+    image::codecs::jpeg::JpegEncoder::new_with_quality(&mut out, 90).encode_image(&img).unwrap();
+    out
+}
+
+fn index_of(f: &VideoFrame) -> usize {
+    let PixelData::Rgba8(px) = &f.data else { panic!("MJPEG decodes to RGBA8") };
+    (0..BITS).filter(|b| px[((BLOCK / 2 * f.width + b * BLOCK + BLOCK / 2) * 4) as usize] > 127).map(|b| 1 << b).sum()
+}
+
+fn frame_count(rate: FrameRate) -> usize {
+    rate.frame_at(Tick(SECONDS * TICKS_PER_SECOND)) as usize
+}
+
+/// Frame `k`'s start in milliseconds, as the muxer stores it.
+fn stamp_ms(rate: FrameRate, k: usize, stamp: Stamp) -> i64 {
+    let (num, den) = (rate.num as i128, rate.den as i128);
+    let exact2 = 2 * k as i128 * 1000 * den; // twice the time in ms, times num
+    (match stamp {
+        Stamp::Nearest => (exact2 + num) / (2 * num),
+        Stamp::Floor => exact2 / (2 * num),
+    }) as i64
+}
+
+fn webm(rate: FrameRate, stamp: Stamp) -> Arc<[u8]> {
+    let mut spec = TrackSpec::new(TrackKind::Video, "V_MJPEG");
+    spec.video_size = Some((BITS * BLOCK, BLOCK));
+    spec.default_duration_ns = Some((1_000_000_000 * rate.den / rate.num) as u64);
+    let opts = MuxOptions { doc_type: "webm".into(), ..MuxOptions::default() };
+    assert_eq!(opts.timestamp_scale, 1_000_000, "1 ms timestamps");
+    let mut w = MkvWriter::new(Cursor::new(Vec::new()), vec![spec], opts).unwrap();
+    for k in 0..frame_count(rate) {
+        w.write_frame(0, stamp_ms(rate, k, stamp) * 1_000_000, true, &picture(k), None).unwrap();
+    }
+    w.finish().unwrap().into_inner().into()
+}
+
+fn mp4_1ms(rate: FrameRate, stamp: Stamp) -> Arc<[u8]> {
+    let mut w = Mp4Writer::new(Cursor::new(Vec::new()), WriterOptions::new(Brand::Mov)).unwrap();
+    let t = w.add_track(TrackConfig::new(SampleEntry::jpeg((BITS * BLOCK) as u16, BLOCK as u16), 1000)).unwrap();
+    let n = frame_count(rate);
+    for k in 0..n {
+        let duration = (stamp_ms(rate, k + 1, stamp) - stamp_ms(rate, k, stamp)) as u32;
+        w.write_sample(t, WriteSample { data: &picture(k), duration, composition_offset: 0, is_sync: true }).unwrap();
+    }
+    w.finish().unwrap().into_inner().into()
+}
+
+/// Plays the stream back at its own rate (every frame's start), and asks for every frame's
+/// midpoint too. Returns what went wrong: frames never shown, frames shown twice, wrong midpoints.
+fn problems(src: &dyn MediaSource, rate: FrameRate) -> Vec<String> {
+    let n = frame_count(rate);
+    let at = |t: Tick| index_of(&src.video_frame(FrameRequest::full(t)).unwrap());
+    let mut shown = vec![0usize; n];
+    for k in 0..n {
+        shown[at(rate.tick_of(k as i64)).min(n - 1)] += 1;
+    }
+    let mut out = Vec::new();
+    let dropped: Vec<usize> = (0..n).filter(|&k| shown[k] == 0).collect();
+    let repeated: Vec<usize> = (0..n).filter(|&k| shown[k] > 1).collect();
+    if !dropped.is_empty() || !repeated.is_empty() {
+        out.push(format!(
+            "{} of {n} frames never shown {:?}…, {} shown twice {:?}…",
+            dropped.len(),
+            &dropped[..dropped.len().min(4)],
+            repeated.len(),
+            &repeated[..repeated.len().min(4)]
+        ));
+    }
+    let mid: Vec<(usize, usize)> = (0..n).map(|k| (k, at(rate.tick_of(k as i64) + Tick(rate.frame_duration().0 / 2)))).filter(|(k, got)| k != got).collect();
+    if !mid.is_empty() {
+        out.push(format!("{} mid-frame requests wrong, e.g. (wanted, got) {:?}", mid.len(), &mid[..mid.len().min(4)]));
+    }
+    out
+}
+
+fn check(container: &str, open: fn(FrameRate, Stamp) -> Arc<[u8]>) {
+    let mut failures = Vec::new();
+    for rate in RATES {
+        for stamp in [Stamp::Nearest, Stamp::Floor] {
+            let src = crate::open_bytes(&format!("synthetic.{container}"), open(rate, stamp)).unwrap();
+            for p in problems(src.as_ref(), rate) {
+                failures.push(format!("{rate}, {stamp:?} ms stamps: {p}"));
+            }
+        }
+    }
+    assert!(failures.is_empty(), "{container}:\n{}", failures.join("\n"));
+}
+
+#[test]
+fn webm_with_1ms_timestamps_shows_every_frame_once() {
+    check("webm", webm);
+}
+
+#[test]
+fn mp4_with_a_1ms_timescale_shows_every_frame_once() {
+    check("mov", mp4_1ms);
+}
@@ -88,6 +88,33 @@ fn mp3_file_decodes() {
    assert!(a.peaks()[0] > 0.1);
 }

+#[test]
+fn aiff_file_decodes() {
+    // 0.1 s of 48 kHz 16-bit stereo PCM: left a ramp, right silent (AIFF, big-endian samples)
+    let frames = 4800u32;
+    let mut b = b"FORM".to_vec();
+    b.extend((4 + 26 + 16 + frames * 4).to_be_bytes());
+    b.extend(b"AIFFCOMM");
+    b.extend(18u32.to_be_bytes());
+    b.extend(2u16.to_be_bytes());
+    b.extend(frames.to_be_bytes());
+    b.extend(16u16.to_be_bytes());
+    b.extend([0x40, 0x0E, 0xBB, 0x80, 0, 0, 0, 0, 0, 0]); // 48000 as an 80-bit extended float
+    b.extend(b"SSND");
+    b.extend((8 + frames * 4).to_be_bytes());
+    b.extend([0; 8]);
+    for i in 0..frames {
+        b.extend(((i as i16) * 4).to_be_bytes());
+        b.extend(0i16.to_be_bytes());
+    }
+    let src = crate::open_bytes("tone.aif", b.into()).unwrap();
+    assert!((src.info().duration.seconds() - 0.1).abs() < 1e-3, "{}", src.info().duration.seconds());
+    let a = src.audio(0, 4800, 48_000).unwrap();
+    assert_eq!(a.channels.len(), 2);
+    assert!((a.channels[0][1000] - 4000.0 / 32768.0).abs() < 1e-4, "{}", a.channels[0][1000]);
+    assert_eq!(a.channels[1][1000], 0.0);
+}
+
 #[test]
 fn seek_backwards_and_forwards_mjpeg() {
    let Some(b) = fixture("counter_mjpeg.mov", &["-f", "lavfi", "-i", "testsrc2=s=160x120:r=25:d=3", "-c:v", "mjpeg"]) else { return };
@@ -445,7 +472,7 @@ fn opus_reference(name: &str) -> Option<Vec<f32>> {
    if !st.success() {
        return None;
    }
-    Some(std::fs::read(out).ok()?.chunks_exact(4).map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]])).collect())
+    Some(std::fs::read(out).ok()?.as_chunks::<4>().0.iter().map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]])).collect())
 }

 fn snr_db(reference: &[f32], test: &[f32]) -> f64 {
@@ -551,3 +578,40 @@ fn opus_mp4_stereo() {
        "MPEG-4",
    );
 }
+
+#[test]
+fn apv_mp4_and_raw_bitstream_decode() {
+    use filmcraft_isobmff::{ApvConfig, Brand, Mp4Writer, SampleEntry, TrackConfig, WriteSample, WriterOptions};
+
+    let (w, h) = (64u32, 32u32);
+    let mut fr = filmcraft_apv::Frame::new(w, h, filmcraft_apv::ChromaFormat::Yuv422, 10, false);
+    for (i, y) in fr.y.iter_mut().enumerate() {
+        *y = if (i as u32 % w) < w / 2 { 850 } else { 150 };
+    }
+    let mut enc = filmcraft_apv::Encoder::new(filmcraft_apv::Profile::P422_10, w, h).expect("encoder");
+    let au = enc.encode_raw_au(&fr).expect("encode_raw_au");
+    let apvc = ApvConfig::parse(&enc.decoder_config_record()).expect("parse apvC");
+
+    // 1. Raw .apv elementary stream
+    let raw_src = crate::open_bytes("clip.apv", au.clone().into()).expect("open raw .apv");
+    let raw_v = raw_src.info().video.as_ref().expect("video info");
+    assert_eq!((raw_v.width, raw_v.height), (w, h));
+    assert_eq!(raw_v.codec, "APV 422-10");
+    assert_eq!(raw_v.pixel_format, "YUV 4:2:2 10-bit");
+    let decoded_raw = raw_src.video_frame(FrameRequest::full(Tick::ZERO)).expect("decode raw frame");
+    assert_eq!((decoded_raw.width, decoded_raw.height), (w, h));
+
+    // 2. MP4 with apv1 + apvC
+    let mut mux = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4)).expect("writer");
+    let vt = mux.add_track(TrackConfig::new(SampleEntry::apv(apvc, w as u16, h as u16), 24)).expect("track");
+    mux.write_sample(vt, WriteSample { data: &au, duration: 1, composition_offset: 0, is_sync: true }).expect("sample");
+    let mp4_bytes: Arc<[u8]> = mux.finish().expect("finish").into_inner().into();
+
+    let mp4_src = crate::open_bytes("clip.mp4", mp4_bytes).expect("open mp4");
+    let mp4_v = mp4_src.info().video.as_ref().expect("mp4 video info");
+    assert_eq!((mp4_v.width, mp4_v.height), (w, h));
+    assert_eq!(mp4_v.codec, "APV 422-10");
+    assert_eq!(mp4_v.pixel_format, "YUV 4:2:2 10-bit");
+    let decoded_mp4 = mp4_src.video_frame(FrameRequest::full(Tick::ZERO)).expect("decode mp4 frame");
+    assert_eq!(decoded_mp4.to_rgba8(), decoded_raw.to_rgba8());
+}
@@ -128,6 +128,42 @@ pub(crate) fn tight_plane<T: Copy>(src: Vec<T>, stride: usize, w: usize, h: usiz
    out
 }

+/// Colour of an H.264 / HEVC picture from its VUI code points (ITU-T H.273), as the decoders
+/// report it: BT.709 by default with the matrix guessed from the size, the signalled matrix and
+/// transfer when known, and full range when flagged. Shared by the software and hardware
+/// decoders so the two are interchangeable.
+pub fn vui_color(width: u32, height: u32, matrix: u8, transfer: u8, full_range: bool) -> filmcraft_color::ColorInfo {
+    let mut color = filmcraft_color::ColorInfo { matrix: filmcraft_frame::default_matrix(width, height), ..filmcraft_color::ColorInfo::REC709 };
+    if let Some(m) = filmcraft_color::Matrix::from_code(matrix) {
+        color.matrix = m;
+    }
+    if let Some(t) = filmcraft_color::Transfer::from_code(transfer) {
+        color.transfer = t;
+    }
+    if full_range {
+        color.range = filmcraft_color::Range::Full;
+    }
+    color
+}
+
+/// Pixel aspect ratio from a VUI sample aspect ratio ((0, 0) = unspecified = square).
+pub fn sar_par(sar: (u16, u16)) -> (u32, u32) {
+    if sar.0 > 0 && sar.1 > 0 { (sar.0 as u32, sar.1 as u32) } else { (1, 1) }
+}
+
+/// NAL length-prefix size of an `avcC` record (byte 4: lengthSizeMinusOne).
+pub fn avcc_length_size(avcc: &[u8]) -> usize {
+    avcc.get(4).map_or(4, |b| (b & 3) as usize + 1)
+}
+
+/// NAL length-prefix size and highest TemporalId of an `hvcC` record.
+pub fn hvcc_length_size_and_tid(hvcc: &[u8]) -> (usize, Option<u8>) {
+    // hvcC byte 21: constantFrameRate(2) numTemporalLayers(3) temporalIdNested(1) lengthSizeMinusOne(2)
+    let length_size = hvcc.get(21).map_or(4, |b| (b & 3) as usize + 1);
+    let highest_tid = hvcc.get(21).map(|b| (b >> 3) & 7).filter(|&n| n > 0).map(|n| n - 1);
+    (length_size, highest_tid)
+}
+
 /// A factory returns `None` when it does not handle the entry.
 pub type VideoDecoderFactory = fn(&SampleEntry) -> Option<Result<Box<dyn VideoDecoder>>>;

@@ -168,12 +204,14 @@ pub struct H264Decoder {

 impl H264Decoder {
    pub fn new(avcc: Vec<u8>) -> Result<Self> {
+        recycle_h264_planes();
        let dec = filmcraft_h264::Decoder::from_avcc(&avcc).map_err(|e| CodecError::Decode(e.to_string()))?;
-        let length_size = avcc.get(4).map_or(4, |b| (b & 3) as usize + 1);
+        let length_size = avcc_length_size(&avcc);
        Ok(Self { avcc, dec, length_size, draft: false })
    }
    /// A decoder for Annex B byte-stream samples (start codes, in-band parameter sets: MXF, TS).
    pub fn annexb() -> Self {
+        recycle_h264_planes();
        Self { avcc: Vec::new(), dec: filmcraft_h264::Decoder::new(), length_size: 0, draft: false }
    }
    fn convert(p: filmcraft_h264::Picture) -> DecodedFrame {
@@ -184,17 +222,8 @@ impl H264Decoder {
        let y = tight_plane(p.y, p.y_stride, w, h);
        let u = tight_plane(p.u, p.uv_stride, cw, ch);
        let v = tight_plane(p.v, p.uv_stride, cw, ch);
-        let mut color = filmcraft_color::ColorInfo { matrix: filmcraft_frame::default_matrix(p.width, p.height), ..filmcraft_color::ColorInfo::REC709 };
-        if let Some(m) = filmcraft_color::Matrix::from_code(p.color.matrix) {
-            color.matrix = m;
-        }
-        if let Some(t) = filmcraft_color::Transfer::from_code(p.color.transfer) {
-            color.transfer = t;
-        }
-        if p.color.full_range {
-            color.range = filmcraft_color::Range::Full;
-        }
-        let par = if p.sar.0 > 0 && p.sar.1 > 0 { (p.sar.0 as u32, p.sar.1 as u32) } else { (1, 1) };
+        let color = vui_color(p.width, p.height, p.color.matrix, p.color.transfer, p.color.full_range);
+        let par = sar_par(p.sar);
        let frame = VideoFrame {
            width: p.width,
            height: p.height,
@@ -242,6 +271,12 @@ impl VideoDecoder for H264Decoder {
    }
 }

+/// The H.264 decoder's output planes come from the frames the caches evicted
+/// (`filmcraft_frame::pool`) instead of the allocator.
+fn recycle_h264_planes() {
+    filmcraft_h264::set_plane_allocator(filmcraft_frame::pool::take_u8);
+}
+
 /// Worker threads each H.264 decoder uses (frame threading; 1 on wasm).
 pub fn h264_threads() -> usize {
    filmcraft_h264::default_threads()
@@ -265,9 +300,7 @@ pub struct HevcDecoder {
 impl HevcDecoder {
    pub fn new(hvcc: Vec<u8>) -> Result<Self> {
        let dec = filmcraft_hevc::Decoder::from_hvcc(&hvcc).map_err(|e| CodecError::Decode(e.to_string()))?;
-        // hvcC byte 21: constantFrameRate(2) numTemporalLayers(3) temporalIdNested(1) lengthSizeMinusOne(2)
-        let length_size = hvcc.get(21).map_or(4, |b| (b & 3) as usize + 1);
-        let highest_tid = hvcc.get(21).map(|b| (b >> 3) & 7).filter(|&n| n > 0).map(|n| n - 1);
+        let (length_size, highest_tid) = hvcc_length_size_and_tid(&hvcc);
        Ok(Self { hvcc, dec, length_size, highest_tid })
    }
    /// A decoder for Annex B byte-stream samples (start codes, in-band parameter sets: TS).
@@ -299,19 +332,10 @@ impl HevcDecoder {
                alpha: None,
            },
        };
-        let mut color = filmcraft_color::ColorInfo { matrix: filmcraft_frame::default_matrix(p.width, p.height), ..filmcraft_color::ColorInfo::REC709 };
-        if let Some(m) = filmcraft_color::Matrix::from_code(p.color.matrix) {
-            color.matrix = m;
-        }
-        if let Some(t) = filmcraft_color::Transfer::from_code(p.color.transfer) {
-            color.transfer = t;
-        }
-        if p.color.full_range {
-            color.range = filmcraft_color::Range::Full;
-        }
-        let par = if p.sar.0 > 0 && p.sar.1 > 0 { (p.sar.0 as u32, p.sar.1 as u32) } else { (1, 1) };
+        let color = vui_color(p.width, p.height, p.color.matrix, p.color.transfer, p.color.full_range);
+        let par = sar_par(p.sar);
        let frame = VideoFrame { width: p.width, height: p.height, data, color, par, pts: filmcraft_time::Tick::ZERO };
-        DecodedFrame { pts: p.pts, frame, draft: false }
+        DecodedFrame { pts: p.pts, frame, draft: p.draft }
    }
 }

@@ -336,6 +360,9 @@ impl VideoDecoder for HevcDecoder {
    fn is_disposable(&self, sample: &[u8]) -> bool {
        hevc_disposable(sample, self.length_size, self.highest_tid)
    }
+    fn set_draft(&mut self, on: bool) {
+        self.dec.set_draft(on);
+    }
    fn is_random_access(&self, sample: &[u8]) -> Option<bool> {
        // Annex B samples carry their parameter sets: an IDR / CRA / BLA access unit is a
        // starting point.
@@ -383,34 +410,17 @@ impl Vp9Decoder {
        }
    }

-    fn convert(&self, p: filmcraft_vp9::Picture) -> DecodedFrame {
-        use filmcraft_color::{Matrix, Primaries, Range};
+    /// `None` for a picture whose planes mix sample types (never produced by the decoder).
+    fn convert(&self, p: filmcraft_vp9::Picture) -> Option<DecodedFrame> {
+        use filmcraft_color::Range;
        use filmcraft_frame::{Chroma, PixelData};
        use filmcraft_vp9::Plane;
        use std::sync::Arc;
        let (w, h) = (p.width as usize, p.height as usize);
        let (cw, ch) = (p.chroma_width as usize, p.chroma_height as usize);
-        let mut color = filmcraft_color::ColorInfo { matrix: filmcraft_frame::default_matrix(p.width, p.height), ..filmcraft_color::ColorInfo::REC709 };
-        // color_space (7.2.2): 1 BT.601, 2 BT.709, 3 SMPTE-170, 4 SMPTE-240, 5 BT.2020, 7 sRGB.
-        match p.color.color_space {
-            1 | 3 => color.matrix = Matrix::Bt601,
-            2 | 4 => color.matrix = Matrix::Bt709,
-            5 => {
-                color.matrix = Matrix::Bt2020Ncl;
-                color.primaries = Primaries::Bt2020;
-            }
-            _ => {}
-        }
-        if let Some(t) = self.transfer {
-            color.transfer = t;
-        }
-        if let Some(pr) = self.primaries {
-            color.primaries = pr;
-        }
-        if p.color.full_range {
-            color.range = Range::Full;
-        }
-        let pts = p.pts;
+        // (shared with the hardware decoders: `hw_frame::vp9_color`)
+        let color = crate::hw_frame::vp9_color(p.width, p.height, p.color.color_space, p.color.full_range, self.transfer, self.primaries);
+        let (pts, draft) = (p.pts, p.draft);
        if p.color.color_space == 7 {
            // RGB (profiles 1 / 3, 4:4:4): the planes carry G, B, R.
            let shift = p.bit_depth - 8;
@@ -420,7 +430,7 @@ impl Vp9Decoder {
            }
            let mut frame = VideoFrame::rgba8(p.width, p.height, rgba);
            frame.color = filmcraft_color::ColorInfo { range: Range::Full, transfer: filmcraft_color::Transfer::Srgb, ..color };
-            return DecodedFrame { pts, frame, draft: false };
+            return Some(DecodedFrame { pts, frame, draft });
        }
        // 4:4:0 has no frame format of its own: chroma rows are repeated to 4:4:4.
        let (chroma, rows_440) = match (p.subsampling_x, p.subsampling_y) {
@@ -452,22 +462,22 @@ impl Vp9Decoder {
                bits: p.bit_depth,
                alpha: None,
            },
-            _ => unreachable!("VP9 planes share one sample type"),
+            _ => return None,
        };
        // render_size (the intended display size) is not applied: the container's display
        // dimensions / pixel aspect describe the presentation.
        let par = (1, 1);
-        DecodedFrame { pts, frame: VideoFrame { width: p.width, height: p.height, data, color, par, pts: filmcraft_time::Tick::ZERO }, draft: false }
+        Some(DecodedFrame { pts, frame: VideoFrame { width: p.width, height: p.height, data, color, par, pts: filmcraft_time::Tick::ZERO }, draft })
    }
 }

 impl VideoDecoder for Vp9Decoder {
    fn decode(&mut self, sample: &[u8], pts: i64) -> Result<Vec<DecodedFrame>> {
        let pics = self.dec.decode(sample, pts).map_err(|e| CodecError::Decode(e.to_string()))?;
-        Ok(pics.into_iter().map(|p| self.convert(p)).collect())
+        Ok(pics.into_iter().filter_map(|p| self.convert(p)).collect())
    }
    fn flush(&mut self) -> Vec<DecodedFrame> {
-        self.dec.flush().into_iter().map(|p| self.convert(p)).collect()
+        self.dec.flush().into_iter().filter_map(|p| self.convert(p)).collect()
    }
    fn reset(&mut self) {
        self.dec.reset();
@@ -475,6 +485,9 @@ impl VideoDecoder for Vp9Decoder {
    fn name(&self) -> &str {
        "FilmCraft VP9"
    }
+    fn set_draft(&mut self, on: bool) {
+        self.dec.set_draft(on);
+    }
    fn is_random_access(&self, sample: &[u8]) -> Option<bool> {
        Some(filmcraft_vp9::is_keyframe(sample))
    }
@@ -502,27 +515,11 @@ impl Av1Decoder {

    fn convert(p: filmcraft_av1::Picture, pts: i64) -> DecodedFrame {
        use std::sync::Arc;
+        let draft = p.draft;
        let w = p.width as usize;
        let h = p.height as usize;
-        let mut color = filmcraft_color::ColorInfo::REC709;
-        if let Some(m) = filmcraft_color::Matrix::from_code(p.matrix_coefficients) {
-            color.matrix = m;
-        } else {
-            color.matrix = filmcraft_frame::default_matrix(p.width, p.height);
-        }
-        if let Some(t) = filmcraft_color::Transfer::from_code(p.transfer_characteristics) {
-            color.transfer = t;
-        }
-        color.primaries = match p.color_primaries {
-            9 => filmcraft_color::Primaries::Bt2020,
-            12 => filmcraft_color::Primaries::P3D65,
-            5 => filmcraft_color::Primaries::Bt601_625,
-            6 => filmcraft_color::Primaries::Bt601_525,
-            _ => filmcraft_color::Primaries::Bt709,
-        };
-        if p.full_range {
-            color.range = filmcraft_color::Range::Full;
-        }
+        // (shared with the hardware decoders: `hw_frame::av1_color`)
+        let color = crate::hw_frame::av1_color(p.width, p.height, p.matrix_coefficients, p.transfer_characteristics, p.color_primaries, p.full_range);
        let chroma = match (p.subsampling_x, p.subsampling_y) {
            (1, 1) => filmcraft_frame::Chroma::C420,
            (1, 0) => filmcraft_frame::Chroma::C422,
@@ -541,7 +538,7 @@ impl Av1Decoder {
        } else {
            filmcraft_frame::PixelData::Yuv16 { planes: [Arc::new(y), Arc::new(u), Arc::new(v)], chroma, bits: p.bit_depth as u32, alpha: None }
        };
-        DecodedFrame { pts, frame: VideoFrame { width: p.width, height: p.height, data, color, par: (1, 1), pts: filmcraft_time::Tick::ZERO }, draft: false }
+        DecodedFrame { pts, frame: VideoFrame { width: p.width, height: p.height, data, color, par: (1, 1), pts: filmcraft_time::Tick::ZERO }, draft }
    }
 }

@@ -580,6 +577,9 @@ impl VideoDecoder for Av1Decoder {
    fn name(&self) -> &str {
        "FilmCraft AV1"
    }
+    fn set_draft(&mut self, on: bool) {
+        self.dec.set_draft(on);
+    }
    fn is_random_access(&self, sample: &[u8]) -> Option<bool> {
        Some(filmcraft_av1::is_key_frame_unit(sample))
    }
@@ -641,6 +641,72 @@ pub fn prores_factory(e: &SampleEntry) -> Option<Result<Box<dyn VideoDecoder>>>
    matches!(e.codec, CodecConfig::ProRes { .. }).then(|| Ok(Box::new(ProResDecoder) as Box<dyn VideoDecoder>))
 }

+/// Our APV (Advanced Professional Video, RFC 9924) decoder (every frame is intra; tiles decode in
+/// parallel).
+pub struct ApvDecoder;
+
+/// Convert a decoded APV frame to a [`VideoFrame`].
+pub fn apv_to_video_frame(f: filmcraft_apv::Frame) -> VideoFrame {
+    use std::sync::Arc;
+    let chroma = match f.chroma {
+        filmcraft_apv::ChromaFormat::Yuv422 => filmcraft_frame::Chroma::C422,
+        filmcraft_apv::ChromaFormat::Monochrome | filmcraft_apv::ChromaFormat::Yuv444 | filmcraft_apv::ChromaFormat::Yuv4444 => filmcraft_frame::Chroma::C444,
+    };
+    let mut color = filmcraft_color::ColorInfo { matrix: filmcraft_frame::default_matrix(f.width, f.height), ..filmcraft_color::ColorInfo::REC709 };
+    if let Some(m) = filmcraft_color::Matrix::from_code(f.color.matrix) {
+        color.matrix = m;
+    }
+    if let Some(t) = filmcraft_color::Transfer::from_code(f.color.transfer) {
+        color.transfer = t;
+    }
+    if let Some(p) = primaries_from_code(f.color.primaries) {
+        color.primaries = p;
+    }
+    if f.color.full_range {
+        color.range = filmcraft_color::Range::Full;
+    }
+    let neutral = 1u16 << f.bit_depth.saturating_sub(1);
+    let (cb, cr) = if f.chroma == filmcraft_apv::ChromaFormat::Monochrome {
+        let u = vec![neutral; (f.width as usize) * (f.height as usize)];
+        (u.clone(), u)
+    } else {
+        (f.cb, f.cr)
+    };
+    let data = if f.bit_depth == 8 {
+        let to8 = |p: Vec<u16>| Arc::new(p.into_iter().map(|v| v as u8).collect::<Vec<u8>>());
+        filmcraft_frame::PixelData::Yuv8 { planes: [to8(f.y), to8(cb), to8(cr)], chroma, alpha: f.alpha.map(to8) }
+    } else {
+        filmcraft_frame::PixelData::Yuv16 {
+            planes: [Arc::new(f.y), Arc::new(cb), Arc::new(cr)],
+            chroma,
+            bits: f.bit_depth as u32,
+            alpha: f.alpha.map(Arc::new),
+        }
+    };
+    VideoFrame { width: f.width, height: f.height, data, color, par: (1, 1), pts: filmcraft_time::Tick::ZERO }
+}
+
+impl VideoDecoder for ApvDecoder {
+    fn decode(&mut self, sample: &[u8], pts: i64) -> Result<Vec<DecodedFrame>> {
+        let f = filmcraft_apv::decode_frame(sample).map_err(|e| CodecError::Decode(e.to_string()))?;
+        Ok(vec![DecodedFrame { pts, frame: apv_to_video_frame(f), draft: false }])
+    }
+    fn flush(&mut self) -> Vec<DecodedFrame> {
+        Vec::new()
+    }
+    fn reset(&mut self) {}
+    fn name(&self) -> &str {
+        "FilmCraft APV"
+    }
+    fn intra_only(&self) -> bool {
+        true
+    }
+}
+
+pub fn apv_factory(e: &SampleEntry) -> Option<Result<Box<dyn VideoDecoder>>> {
+    matches!(e.codec, CodecConfig::Apv(_)).then(|| Ok(Box::new(ApvDecoder) as Box<dyn VideoDecoder>))
+}
+
 /// Our DNxHD / DNxHR (VC-3) decoder (every frame is intra; macroblock rows decode in parallel).
 pub struct DnxDecoder;

@@ -48,7 +48,7 @@ pub fn ffmpeg_audio_f32(ff: &Path, file: &Path, extra: &[&str]) -> Vec<f32> {
    let mut args = vec!["-i", file.to_str().unwrap()];
    args.extend_from_slice(extra);
    args.extend_from_slice(&["-map", "0:a:0", "-f", "f32le", "-"]);
-    ffmpeg_out(ff, &args).chunks_exact(4).map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect()
+    ffmpeg_out(ff, &args).as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect()
 }

 /// Our frame's three planes widened to u16 (and their sizes).
@@ -63,7 +63,7 @@ pub fn planes(f: &VideoFrame) -> Vec<Vec<u16>> {
 /// Split one raw frame of `ffmpeg_frames` into planes (`bps` bytes per sample, chroma `cw`×`ch`).
 pub fn raw_planes(raw: &[u8], w: usize, h: usize, cw: usize, ch: usize, bps: usize) -> Vec<Vec<u16>> {
    let get = |b: &[u8]| -> Vec<u16> {
-        if bps == 1 { b.iter().map(|&v| v as u16).collect() } else { b.chunks_exact(2).map(|c| u16::from_le_bytes([c[0], c[1]])).collect() }
+        if bps == 1 { b.iter().map(|&v| v as u16).collect() } else { b.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]])).collect() }
    };
    let y = w * h * bps;
    let c = cw * ch * bps;
@@ -0,0 +1,119 @@
+//! Draft decoding of VP9, HEVC and AV1 through the media stack (as `h264_draft.rs` for H.264):
+//! off by default, approximate frames only reach draft requests, and decoding for an export after
+//! draft playback (same source, same GOP cache) still matches ffmpeg bit for bit.
+
+mod common;
+
+use common::*;
+use filmcraft_media::FrameRequest;
+use filmcraft_media::cancel::with_draft;
+
+/// Play `name` without and with draft decoding, then "export" it: every non-draft request must
+/// be bit-exact with ffmpeg, and draft playback must have produced some approximate frames.
+fn check(name: &str, args: &[&str], w: usize, h: usize) {
+    let ff = filmcraft_testkit::require_ffmpeg!();
+    let Some(file) = fixture(&ff, name, args) else { return };
+    let raw = ffmpeg_frames(&ff, &file, "yuv420p");
+    let fsize = w * h * 3 / 2;
+    let n = raw.len() / fsize;
+    assert!(n >= 16, "{name}: {n} frames");
+    let reference = |i: usize| raw_planes(&raw[i * fsize..(i + 1) * fsize], w, h, w / 2, h / 2, 1);
+
+    // Default: nothing is a draft, every frame exact.
+    let src = filmcraft_codecs::open_bytes(name, bytes(&file)).expect("open");
+    let rate = src.info().frame_rate();
+    let g0 = filmcraft_codecs::gop_stats();
+    for i in 0..n {
+        let f = src.video_frame(FrameRequest { time: rate.tick_of(i as i64), scale: 0.5 }).expect("frame");
+        assert_eq!(max_diff(&planes(&f), &reference(i)), 0, "{name}: frame {i} without draft mode");
+    }
+    assert_eq!(filmcraft_codecs::gop_stats().draft, g0.draft, "{name}: draft decoding is off by default");
+
+    // Draft playback at 1/2 resolution on a fresh source: non-reference frames are drafts.
+    let src = filmcraft_codecs::open_bytes(name, bytes(&file)).expect("open");
+    let g1 = filmcraft_codecs::gop_stats();
+    let mut approximate = 0;
+    for i in 0..n {
+        let f = with_draft(true, || src.video_frame(FrameRequest { time: rate.tick_of(i as i64), scale: 0.5 })).expect("frame");
+        approximate += (max_diff(&planes(&f), &reference(i)) > 0) as usize;
+    }
+    let drafts = filmcraft_codecs::gop_stats().draft - g1.draft;
+    assert!(drafts > 0 && approximate > 0 && approximate as u64 <= drafts, "{name}: {drafts} draft frames, {approximate} differ");
+
+    // Then an export from the same source (no draft hint): every frame is exact again.
+    for i in 0..n {
+        let f = src.video_frame(FrameRequest::full(rate.tick_of(i as i64))).expect("frame");
+        assert_eq!(max_diff(&planes(&f), &reference(i)), 0, "{name}: export frame {i} after draft playback");
+    }
+}
+
+/// One test (the GOP cache statistics are process-wide, so the codecs run one after another).
+#[test]
+fn draft_playback_never_reaches_exports() {
+    vp9();
+    hevc();
+    av1();
+}
+
+fn vp9() {
+    // Two temporal layers: every other frame refreshes no reference slot. (25 fps: WebM stores
+    // millisecond timestamps.)
+    check(
+        "draft_vp9.webm",
+        &[
+            "-f",
+            "lavfi",
+            "-i",
+            "testsrc2=s=320x240:r=25:d=1,noise=alls=10:allf=t",
+            "-c:v",
+            "libvpx-vp9",
+            "-deadline",
+            "realtime",
+            "-speed",
+            "8",
+            "-b:v",
+            "600k",
+            "-ts-parameters",
+            "ts_number_layers=2:ts_target_bitrate=300,600:ts_rate_decimator=2,1:ts_periodicity=2:ts_layer_id=0,1:ts_layering_mode=2",
+            "-pix_fmt",
+            "yuv420p",
+        ],
+        320,
+        240,
+    );
+}
+
+fn hevc() {
+    // B-pyramid: non-reference B pictures (sub-layer non-reference NAL types).
+    check(
+        "draft_hevc.mp4",
+        &[
+            "-f",
+            "lavfi",
+            "-i",
+            "testsrc2=s=320x240:r=25:d=1,noise=alls=10:allf=t",
+            "-c:v",
+            "libx265",
+            "-preset",
+            "fast",
+            "-x265-params",
+            "bframes=4:b-pyramid=1:keyint=24:log-level=error",
+            "-pix_fmt",
+            "yuv420p",
+            "-tag:v",
+            "hvc1",
+        ],
+        320,
+        240,
+    );
+}
+
+fn av1() {
+    // SVT-AV1 hierarchical GOP: the top layer refreshes no reference slot.
+    check(
+        "draft_av1.mp4",
+        &["-f", "lavfi", "-i", "testsrc2=s=320x240:r=25:d=1,noise=alls=10:allf=t", "-c:v", "libsvtav1", "-preset", "8", "-crf", "35", "-pix_fmt", "yuv420p"],
+        320,
+        240,
+    );
+}
@@ -13,19 +13,33 @@ use filmcraft_media::sequence::{FrameLoader, ImageSequenceSource, Numbered, sequ
 use filmcraft_media::{FrameRequest, MediaKind, MediaSource};
 use filmcraft_time::FrameRate;

+/// Twelve numbered stills written by ffmpeg, shared by every test that uses `ext` (#125).
+///
+/// ffmpeg writes into a private temporary directory, which is renamed into place only when all
+/// twelve frames are there, so a test never reads a sequence another test is still writing (a
+/// half-written PNG decodes as missing, and the sequence then holds the previous frame). A test that
+/// loses the race keeps the winner's copy. The `.complete` marker tells a finished cache from a
+/// directory left by an older, non-atomic generator (hence the `_v2` name).
 fn make_sequence(ff: &Path, ext: &str, codec_args: &[&str]) -> Option<std::path::PathBuf> {
-    let d = dir().join(format!("seq_{ext}"));
-    let first = d.join(format!("img_0001.{ext}"));
-    if first.exists() && d.join(format!("img_0012.{ext}")).exists() {
+    let d = dir().join(format!("seq_{ext}_v2"));
+    let complete = |d: &Path| d.join(".complete").exists();
+    if complete(&d) {
        return Some(d);
    }
-    let _ = std::fs::create_dir_all(&d);
-    let pattern = d.join(format!("img_%04d.{ext}"));
+    let tmp = filmcraft_testkit::fixtures::temp_path(&d);
+    std::fs::create_dir_all(&tmp).ok()?;
+    let pattern = tmp.join(format!("img_%04d.{ext}"));
    let mut args = vec!["-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=size=96x64:rate=25", "-frames:v", "12"];
    args.extend_from_slice(codec_args);
    args.extend_from_slice(&["-f", "image2"]);
-    let st = std::process::Command::new(ff).args(&args).arg(&pattern).status().ok()?;
-    st.success().then_some(d)
+    let made = std::process::Command::new(ff).args(&args).arg(&pattern).status().is_ok_and(|st| st.success())
+        && (1..=12).all(|n| tmp.join(format!("img_{n:04}.{ext}")).exists())
+        && std::fs::write(tmp.join(".complete"), b"").is_ok();
+    if made && std::fs::rename(&tmp, &d).is_ok() {
+        return Some(d);
+    }
+    let _ = std::fs::remove_dir_all(&tmp);
+    complete(&d).then_some(d)
 }

 fn loader() -> FrameLoader {
@@ -104,9 +118,9 @@ fn webp_sequence_lossless() {
 fn missing_frames_hold_the_previous_frame() {
    let ff = filmcraft_testkit::require_ffmpeg!();
    let Some(d) = make_sequence(&ff, "png", &[]) else { return };
-    // a copy without frames 5 and 6
-    let gap = dir().join("seq_png_gap");
-    let _ = std::fs::create_dir_all(&gap);
+    // a private copy without frames 5 and 6
+    let gap = filmcraft_testkit::fixtures::temp_path(&dir().join("seq_png_gap"));
+    std::fs::create_dir_all(&gap).unwrap();
    for n in (1..=12).filter(|n| *n != 5 && *n != 6) {
        let name = format!("img_{n:04}.png");
        std::fs::copy(d.join(&name), gap.join(&name)).unwrap();
@@ -119,6 +133,7 @@ fn missing_frames_hold_the_previous_frame() {
    assert_eq!(at(4), at(3));
    assert_eq!(at(5), at(3));
    assert_ne!(at(6), at(3));
+    let _ = std::fs::remove_dir_all(&gap);
 }

 #[test]
@@ -0,0 +1,55 @@
+//! MP4 audio against ffmpeg: ffmpeg writes an AAC track (with the edit list that skips the encoder
+//! priming), and reads at another sample rate must land on the same source samples as the native
+//! decode, however the requests are cut.
+
+mod common;
+
+use common::*;
+
+/// A source whose rate differs from the sequence's is resampled per request. An AAC track in MP4
+/// carries an edit list that skips the encoder priming (ffmpeg: 1024 samples), and every request
+/// must still land on the same source samples: reading at 44.1 kHz in video-frame-sized pieces (as
+/// an export does) equals the 48 kHz decode interpolated at the same times.
+#[test]
+fn aac_mp4_resampled_reads_follow_the_edit_list() {
+    let ff = filmcraft_testkit::require_ffmpeg!();
+    let Some(f) = fixture(&ff, "tone_aac_48k.mp4", &["-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000:d=3", "-c:a", "aac", "-b:a", "128k"]) else {
+        panic!("could not write the AAC fixture")
+    };
+    let src = filmcraft_codecs::open_bytes("tone_aac_48k.mp4", bytes(&f)).unwrap();
+    let native = src.audio(0, 2 * 48_000, 48_000).unwrap().channels[0].clone();
+    let ratio = 48_000.0 / 44_100.0;
+    // 30 fps at 44.1 kHz, starting mid-file and off the 48 kHz grid
+    let (mut start, piece) = (22_051i64, 1470usize);
+    let (mut worst, mut peak) = (0f32, 0f32);
+    for _ in 0..20 {
+        let got = src.audio(start, piece, 44_100).unwrap();
+        for (k, &v) in got.channels[0].iter().enumerate() {
+            let pos = (start + k as i64) as f64 * ratio;
+            let i0 = pos.floor() as usize;
+            let want = native[i0] + (native[i0 + 1] - native[i0]) * (pos - i0 as f64) as f32;
+            worst = worst.max((v - want).abs());
+            peak = peak.max(v.abs());
+        }
+        start += piece as i64;
+    }
+    let level = native.iter().fold(0f32, |m, v| m.max(v.abs()));
+    assert!(peak <= level * 1.01, "resampled peak {peak} above the source's {level}");
+    assert!(worst < 1e-4, "resampled read differs from the source by {worst}");
+}
+
+/// ffmpeg's MP4 muxer skips the B-frame reorder delay with an edit list, so the media (`mdhd`) runs
+/// one frame past what plays. The clip must be as long as ffmpeg decodes it: 60 frames, not 61.
+#[test]
+fn bframe_mp4_duration_is_the_decoded_frame_count() {
+    let ff = filmcraft_testkit::require_ffmpeg!();
+    let args = ["-f", "lavfi", "-i", "testsrc2=size=160x96:rate=30:duration=2", "-c:v", "libx264", "-bf", "2", "-pix_fmt", "yuv420p"];
+    let Some(f) = fixture(&ff, "bframes_x264.mp4", &args) else {
+        eprintln!("SKIPPED: ffmpeg without libx264");
+        return;
+    };
+    let n = ffmpeg_frames(&ff, &f, "yuv420p").len() / (160 * 96 * 3 / 2);
+    assert_eq!(n, 60);
+    let src = filmcraft_codecs::open_bytes("bframes_x264.mp4", bytes(&f)).unwrap();
+    assert_eq!(src.info().duration, filmcraft_time::FrameRate::FPS_30.tick_of(n as i64));
+}
@@ -92,7 +92,7 @@ fn decode_both(ff: &Path, file: &Path, decoder: &[&str]) -> (OggSource, Vec<f32>
    let ch = a.channels as usize;
    let mut args: Vec<&str> = decoder.to_vec();
    args.extend_from_slice(&["-i", file.to_str().unwrap(), "-map", "0:a:0", "-f", "f32le", "-"]);
-    let want: Vec<f32> = ffmpeg_out(ff, &args).chunks_exact(4).map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect();
+    let want: Vec<f32> = ffmpeg_out(ff, &args).as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]])).collect();
    let n = want.len() / ch;
    let frames = src.info().duration.to_units_floor(a.sample_rate as i64) as usize;
    assert_eq!(frames, n, "{}: our length = ffmpeg's ({} samples)", file.display(), n);
@@ -0,0 +1,63 @@
+//! Decoded pictures are written into recycled plane buffers (`filmcraft_frame::pool`). A recycled
+//! buffer still holds an old picture, so the decoder must overwrite every byte: here the pool is
+//! primed with buffers full of 0xAA before decoding, and every frame must still match ffmpeg bit
+//! for bit. (Its own process: the pool is global.)
+
+mod common;
+
+use std::sync::Arc;
+
+use common::*;
+use filmcraft_frame::{Chroma, PixelData, VideoFrame};
+use filmcraft_media::FrameRequest;
+
+#[test]
+fn dirty_recycled_planes_decode_bit_exact() {
+    let ff = filmcraft_testkit::require_ffmpeg!();
+    // 640×480: luma and chroma planes are both large enough to be pooled
+    let Some(file) = fixture(
+        &ff,
+        "pool_h264.mp4",
+        &[
+            "-f",
+            "lavfi",
+            "-i",
+            "testsrc2=s=640x480:r=24:d=1,noise=alls=10:allf=t",
+            "-c:v",
+            "libx264",
+            "-preset",
+            "fast",
+            "-x264-params",
+            "bframes=2:keyint=12",
+            "-pix_fmt",
+            "yuv420p",
+        ],
+    ) else {
+        return;
+    };
+    let (w, h) = (640usize, 480usize);
+    let raw = ffmpeg_frames(&ff, &file, "yuv420p");
+    let fsize = w * h * 3 / 2;
+    let n = raw.len() / fsize;
+    assert!(n >= 20, "{n} frames");
+    let reference = |i: usize| raw_planes(&raw[i * fsize..(i + 1) * fsize], w, h, w / 2, h / 2, 1);
+
+    // prime the pool with dirty buffers of exactly the plane sizes the decoder asks for
+    for _ in 0..8 {
+        let dirty = |len: usize| Arc::new(vec![0xAAu8; len]);
+        let f = VideoFrame {
+            data: PixelData::Yuv8 { planes: [dirty(w * h), dirty(w * h / 4), dirty(w * h / 4)], chroma: Chroma::C420, alpha: None },
+            ..VideoFrame::rgba8(w as u32, h as u32, vec![0; w * h * 4])
+        };
+        filmcraft_frame::pool::recycle(Arc::new(f));
+    }
+    let reused_before = filmcraft_frame::pool::stats().reused;
+
+    let src = filmcraft_codecs::open_bytes("pool_h264.mp4", bytes(&file)).expect("open");
+    let rate = src.info().frame_rate();
+    for i in 0..n {
+        let f = src.video_frame(FrameRequest::full(rate.tick_of(i as i64))).expect("frame");
+        assert_eq!(max_diff(&planes(&f), &reference(i)), 0, "frame {i} decoded into a recycled buffer");
+    }
+    assert!(filmcraft_frame::pool::stats().reused > reused_before, "the decoder took the dirty pooled buffers");
+}
@@ -41,7 +41,8 @@ for limited- and full-range files.

 The encoders are the exact inverses given in the same documents. DJI **D-Log M** is not
 implemented: DJI has not published its formula (only conversion LUTs), and we do not derive curves
-from third-party LUTs.
+from third-party LUTs. (Checked again in October 2026: DJI's published white papers cover D-Log /
+D-Gamut only; D-Log M remains unsupported, so D-Log M footage should be interpreted with a LUT.)

 Gamut primaries (all D65 white, x/y):

@@ -84,6 +85,27 @@ HLG, and for log media the curve's own peak capped at 4000 cd/m² (so the knee s
 grey). Target peak: 203 cd/m² = SDR white. HDR reference white then lands at ≈ 0.79 linear (≈ 90 %
 on the sRGB curve).

+## Grading signal (`grade`)
+
+Lumetri's controls work on a 0…1 signal. `GradeSpace` picks it from the working space:
+
+| Working space | Signal of working-linear `c` (1.0 = 203 cd/m² in HDR) | 1.0 means |
+|---|---|---|
+| Rec. 709 | sRGB curve, clamped back to 0…1 | SDR white |
+| Rec. 2100 PQ | `PQ⁻¹(c·203/10000) / PQ⁻¹(W/10000)` (SMPTE ST 2084) | HDR White `W` cd/m² |
+| Rec. 2100 HLG | `F = c·203/W`, `Y = BT.2020 luma(F)`, `E = F·Y^((1−γ)/γ)`, signal = HLG OETF(E), γ = 1.2 + 0.42·log10(W/1000) (BT.2100 inverse OOTF, note 5f) | display peak `W` |
+
+`W` is Lumetri's HDR White (Basic Correction) or HDR Range (Curves), default 1000 cd/m². HDR
+values above `W` are signals above 1 and are kept (PQ to 10 000 cd/m², HLG to signal 1.5). Checked
+values: PQ 100 / 203 / 1000 cd/m² = 0.508 / 0.581 / 0.752 of the plain PQ signal (BT.2408); HLG on
+a 1000 cd/m² display: 203 cd/m² = 0.75, 26 cd/m² (18 % grey) ≈ 0.38 (BT.2408).
+
+## HDR static metadata
+
+`HdrMetadata` (mastering display max / min luminance, MaxCLL, MaxFALL; 0 = unknown) gives the
+tone-mapping source peak of PQ media: MaxCLL when known (the brightest pixel of the content),
+else the mastering peak, clamped to 203…10 000 cd/m²; without metadata 1000 cd/m² is assumed.
+
 ## Gamut mapping

 * **Input** (camera gamuts wider than the working gamut): per-channel distance compression towards
@@ -0,0 +1,176 @@
+//! The grading signal colour correctors (Lumetri) work on.
+//!
+//! Grading controls (whites / blacks, highlights / shadows, contrast, curves, wheels, keys) are
+//! defined on a perceptual signal from 0 (black) to 1 (white), not on linear light. In an SDR
+//! working space that signal is the sRGB-encoded display value, and 1 is SDR white.
+//!
+//! In an HDR working space (Rec. 2100 PQ or HLG) the signal follows the working space's own
+//! transfer function and is **normalised to HDR White** (cd/m², Lumetri ▸ Basic Correction ▸ HDR
+//! White; the curves have their own HDR Range): signal 1 is HDR White, so the sliders and curves
+//! span 0 … HDR White nits the way they span black … white in SDR, and highlights above HDR
+//! White (speculars) are values above 1 that pass through instead of clipping:
+//!
+//! - **PQ** (SMPTE ST 2084): `signal = PQ⁻¹(nits / 10000) / PQ⁻¹(white / 10000)`.
+//! - **HLG** (ITU-R BT.2100): the inverse OOTF of a display with peak `white` (system gamma
+//!   γ = 1.2 + 0.42·log10(white / 1000), BT.2100 note 5f), then the HLG OETF; so 203 cd/m²
+//!   (BT.2408 HDR reference white) is signal 0.75 with HDR White = 1000 cd/m².
+//!
+//! Working units are linear light with 1.0 = 203 cd/m² ([`crate::REFERENCE_WHITE_NITS`]) in HDR
+//! working spaces, as in [`crate::transform`].
+
+use crate::spaces::{Gamut, WorkingSpace};
+use crate::{REFERENCE_WHITE_NITS, hlg_inverse_oetf, hlg_oetf, linear_to_srgb, pq_eotf, pq_inverse_eotf, srgb_to_linear};
+
+/// Default HDR White / curve HDR Range (cd/m²): the nominal HLG display peak and the usual PQ
+/// mastering peak.
+pub const DEFAULT_HDR_WHITE_NITS: f32 = 1000.0;
+
+/// The signal a grading operation works on.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum GradeSpace {
+    /// sRGB-encoded display values, clamped to 0…1 on the way back (the classic SDR behaviour).
+    Sdr,
+    /// PQ signal normalised to `white` cd/m².
+    Pq { white: f32, norm: f32 },
+    /// HLG signal of a display with peak `white` cd/m² (`gamma` = its system gamma).
+    Hlg { white: f32, gamma: f32 },
+}
+
+impl GradeSpace {
+    /// The grading space of a working space, with HDR White `white_nits` (ignored for SDR).
+    pub fn new(working: WorkingSpace, white_nits: f32) -> Self {
+        let white = white_nits.clamp(100.0, 10_000.0);
+        match working {
+            WorkingSpace::Rec709 => GradeSpace::Sdr,
+            WorkingSpace::Rec2100Pq => GradeSpace::Pq { white, norm: pq_inverse_eotf(white / 10_000.0) },
+            WorkingSpace::Rec2100Hlg => GradeSpace::Hlg { white, gamma: 1.2 + 0.42 * (white / 1000.0).log10() },
+        }
+    }
+
+    pub fn is_hdr(&self) -> bool {
+        !matches!(self, GradeSpace::Sdr)
+    }
+
+    /// HDR White in cd/m² (None for SDR).
+    pub fn white_nits(&self) -> Option<f32> {
+        match *self {
+            GradeSpace::Sdr => None,
+            GradeSpace::Pq { white, .. } | GradeSpace::Hlg { white, .. } => Some(white),
+        }
+    }
+
+    /// Working linear → grading signal (1 = white; HDR values above HDR White are > 1).
+    #[inline]
+    pub fn encode(&self, c: [f32; 3]) -> [f32; 3] {
+        match *self {
+            GradeSpace::Sdr => c.map(|v| linear_to_srgb(v.max(0.0))),
+            GradeSpace::Pq { norm, .. } => c.map(|v| pq_inverse_eotf((v.max(0.0) * REFERENCE_WHITE_NITS as f32 / 10_000.0).min(1.0)) / norm),
+            GradeSpace::Hlg { white, gamma } => {
+                // display light normalised to the peak, inverse OOTF (scene light), OETF
+                let fd = c.map(|v| v.max(0.0) * REFERENCE_WHITE_NITS as f32 / white);
+                let l = luma2020();
+                let yd = l[0] * fd[0] + l[1] * fd[1] + l[2] * fd[2];
+                if yd <= 0.0 {
+                    return [0.0; 3];
+                }
+                let k = yd.powf((1.0 - gamma) / gamma);
+                fd.map(|v| hlg_oetf(v * k))
+            }
+        }
+    }
+
+    /// Grading signal → working linear. SDR clamps to 0…1 (white); HDR keeps values above HDR
+    /// White up to 10 000 cd/m² (PQ) or the HLG signal's range.
+    #[inline]
+    pub fn decode(&self, v: [f32; 3]) -> [f32; 3] {
+        match *self {
+            GradeSpace::Sdr => v.map(|q| srgb_to_linear(q.clamp(0.0, 1.0))),
+            GradeSpace::Pq { norm, .. } => v.map(|q| pq_eotf((q * norm).clamp(0.0, 1.0)) * 10_000.0 / REFERENCE_WHITE_NITS as f32),
+            GradeSpace::Hlg { white, gamma } => {
+                // graded highlights may go past signal 1.0 (the display peak); keep them up to
+                // 1.5 (≈ 28× the peak) instead of clipping
+                let es = v.map(|q| hlg_inverse_oetf(q.clamp(0.0, 1.5)));
+                let l = luma2020();
+                let ys = l[0] * es[0] + l[1] * es[1] + l[2] * es[2];
+                if ys <= 0.0 {
+                    return [0.0; 3];
+                }
+                let k = ys.powf(gamma - 1.0);
+                es.map(|e| e * k * white / REFERENCE_WHITE_NITS as f32)
+            }
+        }
+    }
+
+    /// The signal of a grey of `nits` cd/m² (HDR) — what a nit-scaled slider position means.
+    pub fn signal_of_nits(&self, nits: f32) -> f32 {
+        let w = nits / REFERENCE_WHITE_NITS as f32;
+        self.encode([w; 3])[1]
+    }
+
+    /// The cd/m² of a grey of signal `s` (HDR).
+    pub fn nits_of_signal(&self, s: f32) -> f32 {
+        self.decode([s; 3])[1] * REFERENCE_WHITE_NITS as f32
+    }
+}
+
+fn luma2020() -> [f32; 3] {
+    let l = Gamut::Bt2020.luma();
+    [l[0] as f32, l[1] as f32, l[2] as f32]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn grey(nits: f32) -> [f32; 3] {
+        [nits / REFERENCE_WHITE_NITS as f32; 3]
+    }
+
+    #[test]
+    fn sdr_is_the_srgb_signal() {
+        let g = GradeSpace::new(WorkingSpace::Rec709, 1000.0);
+        assert!(!g.is_hdr());
+        let e = g.encode([0.18, 0.5, 1.0]);
+        assert!((e[0] - linear_to_srgb(0.18)).abs() < 1e-6 && (e[2] - 1.0).abs() < 1e-6);
+        // values above white clip on the way back (SDR)
+        assert_eq!(g.decode([1.4, 1.4, 1.4]), [1.0; 3]);
+    }
+
+    #[test]
+    fn pq_known_nit_values() {
+        // HDR White 10 000: the plain PQ signal; 203 cd/m² ≈ 58 % (BT.2408), 1000 cd/m² ≈ 75.2 %
+        let g = GradeSpace::new(WorkingSpace::Rec2100Pq, 10_000.0);
+        assert!((g.signal_of_nits(203.0) - 0.5807).abs() < 1e-3);
+        assert!((g.signal_of_nits(1000.0) - 0.7518).abs() < 1e-3);
+        assert!((g.signal_of_nits(100.0) - 0.5081).abs() < 1e-3);
+        // HDR White 1000: 1000 cd/m² is signal 1, reference white 0.772
+        let g = GradeSpace::new(WorkingSpace::Rec2100Pq, 1000.0);
+        assert!((g.signal_of_nits(1000.0) - 1.0).abs() < 1e-4);
+        assert!((g.signal_of_nits(203.0) - 0.5807 / 0.7518).abs() < 1e-3);
+        // above HDR White: > 1, not clipped, round trip to 4000 cd/m²
+        let s = g.signal_of_nits(4000.0);
+        assert!(s > 1.1);
+        assert!((g.nits_of_signal(s) - 4000.0).abs() < 4.0);
+        for n in [0.05f32, 1.0, 26.0, 100.0, 203.0, 600.0, 1000.0, 2500.0, 10_000.0] {
+            let back = g.decode(g.encode(grey(n)))[0] * REFERENCE_WHITE_NITS as f32;
+            assert!((back - n).abs() <= n * 2e-3 + 1e-3, "{n} → {back}");
+        }
+    }
+
+    #[test]
+    fn hlg_known_nit_values() {
+        // a 1000 cd/m² HLG display: reference white 203 cd/m² = 75 % (BT.2408), the peak = 100 %
+        let g = GradeSpace::new(WorkingSpace::Rec2100Hlg, 1000.0);
+        assert!((g.signal_of_nits(203.0) - 0.75).abs() < 2e-3, "{}", g.signal_of_nits(203.0));
+        assert!((g.signal_of_nits(1000.0) - 1.0).abs() < 1e-3);
+        // 18 % grey card (≈ 26 cd/m² on that display, BT.2408 table) ≈ 38 %
+        assert!((g.signal_of_nits(26.0) - 0.38).abs() < 0.01, "{}", g.signal_of_nits(26.0));
+        // colour round trip (the inverse OOTF depends on luminance)
+        let c = [2.0f32, 0.5, 0.25];
+        let back = g.decode(g.encode(c));
+        assert!(c.iter().zip(back).all(|(a, b)| (a - b).abs() < 1e-3 * a.max(1.0)), "{back:?}");
+        // a brighter display has a higher system gamma (BT.2100: 1.2 + 0.42 log10(Lw / 1000))
+        let GradeSpace::Hlg { gamma, .. } = GradeSpace::new(WorkingSpace::Rec2100Hlg, 2000.0) else { panic!() };
+        assert!((gamma - 1.2 - 0.42 * 2f32.log10()).abs() < 1e-5);
+    }
+}
@@ -5,14 +5,18 @@
 //! The compositor works in **linear-light, premultiplied RGBA f32** in the sequence working space
 //! (Rec.709 primaries by default). Decoded frames carry [`ColorInfo`] so conversions are explicit.

+#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))]
+
 use serde::{Deserialize, Serialize};
 use std::sync::OnceLock;

+pub mod grade;
 pub mod log;
 pub mod lut;
 pub mod spaces;
 pub mod transform;

+pub use grade::GradeSpace;
 pub use log::LogCurve;
 pub use lut::{Lut, Lut1d, Lut3d, LutFormat};
 pub use spaces::{ColorPipeline, ColorSpace, Curve, Gamut, WorkingSpace};
@@ -101,6 +105,33 @@ pub struct ColorInfo {
    pub range: Range,
 }

+/// HDR static metadata of a stream: SMPTE ST 2086 mastering display luminance and the CTA-861.3
+/// content light levels (MaxCLL / MaxFALL), in cd/m². Read from `mdcv` / `clli` (MP4 / MOV) and
+/// Matroska `MasteringMetadata` / `MaxCLL` / `MaxFALL`.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HdrMetadata {
+    pub mastering_max_nits: Option<f32>,
+    pub mastering_min_nits: Option<f32>,
+    pub max_cll: Option<f32>,
+    pub max_fall: Option<f32>,
+}
+
+impl HdrMetadata {
+    /// The content's peak for tone mapping: MaxCLL when signalled (the brightest pixel actually
+    /// in the content), else the mastering display's peak; `None` when neither is (0 means
+    /// unknown in both). Never below HDR reference white.
+    pub fn peak_nits(&self) -> Option<f32> {
+        let known = |v: Option<f32>| v.filter(|n| *n > 0.0);
+        let p = match (known(self.max_cll), known(self.mastering_max_nits)) {
+            (Some(c), Some(m)) => c.min(m),
+            (Some(c), None) => c,
+            (None, m) => m?,
+        };
+        Some(p.clamp(transform::REFERENCE_WHITE_NITS as f32, 10_000.0))
+    }
+}
+
 impl ColorInfo {
    pub const SRGB_FULL: ColorInfo = ColorInfo { matrix: Matrix::Bt709, transfer: Transfer::Srgb, primaries: Primaries::Bt709, range: Range::Full };
    pub const REC709: ColorInfo = ColorInfo { matrix: Matrix::Bt709, transfer: Transfer::Bt709, primaries: Primaries::Bt709, range: Range::Limited };
@@ -38,7 +38,7 @@ let f = decode_frame_with(&sample, &DecodeOptions { threads: false, ..Default::d
 let hdr: FrameHeader = probe(&sample)?;                  // cid, raster, depth, chroma…
 let name = cid_name(hdr.cid);                            // "DNxHR HQX", "DNxHD 1080i 8-bit (CID 1242)"

-let mut enc = Encoder::new(Profile::Hq, 1920, 1080);     // or Encoder::with_config(EncoderConfig { .. })
+let mut enc = Encoder::new(Profile::Hq, 1920, 1080)?;    // or Encoder::with_config(EncoderConfig { .. })
 let sample: Vec<u8> = enc.encode(&frame)?;               // exactly enc.frame_size() bytes (CBR)
 ```

@@ -19,8 +19,7 @@ pub(crate) fn idct8x8(block: &mut [f32; 64]) {
    let mut nz = [false; 8];
    let mut dc_only = true;
    // Horizontal pass: t[r][x] = Σ_u F[r][u] · B[u][x]
-    for r in 0..8 {
-        let c: &[f32; 8] = block[r * 8..r * 8 + 8].try_into().unwrap();
+    for (r, c) in block.as_chunks::<8>().0.iter().enumerate() {
        if c[1..].iter().all(|&v| v == 0.0) {
            if c[0] != 0.0 {
                t[r] = [c[0] * BASIS[0][0]; 8];
@@ -61,8 +61,9 @@ struct Prepared {
 }

 impl Encoder {
-    pub fn new(profile: Profile, width: u32, height: u32) -> Encoder {
-        Encoder::with_config(EncoderConfig::new(profile, width, height)).expect("valid default configuration")
+    /// An encoder with the default configuration; fails on rasters the profile can't code.
+    pub fn new(profile: Profile, width: u32, height: u32) -> Result<Encoder> {
+        Encoder::with_config(EncoderConfig::new(profile, width, height))
    }

    pub fn with_config(cfg: EncoderConfig) -> Result<Encoder> {
@@ -79,7 +80,7 @@ impl Encoder {
        if !ok_depth {
            return Err(Error::Input(format!("{} does not support {}-bit", cfg.profile.name(), cfg.bit_depth)));
        }
-        let info = cid_info(cfg.profile.cid()).expect("RI CID");
+        let info = cid_info(cfg.profile.cid()).ok_or_else(|| Error::Input(format!("no compression table for {}", cfg.profile.name())))?;
        let frame_size = cfg.profile.frame_size(cfg.width, cfg.height);
        let header_size = header::header_size_for(cfg.height);
        Ok(Encoder { cfg, info, frame_size, header_size, last_q: 8 })
@@ -127,7 +127,7 @@ fn probe_weights() {
            let px: Vec<f64> = if depth == 8 {
                out.stdout.iter().map(|&b| b as f64).collect()
            } else {
-                out.stdout.chunks_exact(2).map(|c| u16::from_le_bytes([c[0], c[1]]) as f64).collect()
+                out.stdout.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]]) as f64).collect()
            };
            let (off, stride) = if blk == 0 { (0, w as usize) } else { ((w * h) as usize, w as usize / 2) };
            let mid = (1 << (depth - 1)) as f64;
@@ -224,7 +224,7 @@ fn probe_reconstruction() {
            let px: Vec<f64> = if depth == 8 {
                out.stdout.iter().map(|&b| b as f64).collect()
            } else {
-                out.stdout.chunks_exact(2).map(|c| u16::from_le_bytes([c[0], c[1]]) as f64).collect()
+                out.stdout.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]]) as f64).collect()
            };
            let mid = (1 << (depth - 1)) as f64;
            let mut sum = 0f64;