v0.13.1: scsi::reset() bounded by wallclock timeout

Production incident: autorip's poll loop called scsi::reset() on a
wedged BU40N USB drive. The Linux SG_SCSI_RESET ioctl blocked
indefinitely (kernel SCSI subsystem waiting for a bus-wedged device to
ack a reset that will never come). Caller's poll loop hung for 60+
seconds before manual intervention.

scsi::reset() now spawns a detached worker for the platform-specific
reset and bounds the caller's wait via mpsc::recv_timeout. Default
30 s (DEFAULT_RESET_TIMEOUT_SECS); reset_with_timeout(device, dur)
exposes the bound for callers that want a different value. Returns
DeviceResetFailed on timeout. Worker thread keeps running until the
kernel eventually unblocks — leaks one OS thread per hard wedge, but
the daemon stays responsive instead of hanging forever.

Follow-up flagged for 0.13.2: USB-attached drives wedge at the USB
Mass Storage layer below SCSI; SG_SCSI_RESET doesn't help. A
scsi::usb_reset(path) using USBDEVFS_RESET is the proper escalation.

.github/workflows/ci.yml

@@ -6,16 +6,33 @@ on:
   pull_request:
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+        with:
+          components: clippy, rustfmt
+      - run: cargo fmt --check
+      - run: cargo clippy -- -D warnings
+
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
       - run: cargo test
 
   check-macos:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
+      - run: cargo check
+
+  check-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
       - run: cargo check

.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Verify Cargo.toml version matches tag
         run: |
           CARGO_VER="v$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')"
@@ -26,16 +26,16 @@ jobs:
     needs: verify
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
       - run: cargo test
 
   publish:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@1.86.0
       - name: Publish to crates.io
         run: cargo publish
         env:
@@ -45,7 +45,7 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:

.github/workflows/update-readme.yml

@@ -11,9 +11,10 @@ jobs:
   update:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           ref: main
+          token: ${{ secrets.ORG_DISPATCH_TOKEN }}
 
       - name: Update version in README
         run: |

CHANGELOG.md

@@ -1,5 +1,592 @@
 # Changelog
 
+## 0.13.1 (2026-04-24)
+
+### `scsi::reset()` now has a hard wallclock timeout
+
+Production incident on a wedged BU40N USB drive: autorip's poll loop
+called `scsi::reset()` and the call hung for 60+ seconds before the
+operator manually intervened. Root cause: the Linux `SG_SCSI_RESET`
+ioctl can block indefinitely when the kernel SCSI subsystem is waiting
+on a bus-wedged device that will never ack — there's no kernel-side
+timeout on this ioctl. Without an outer wallclock bound the caller's
+thread is stuck in the kernel until the device unwedges (which, for a
+permanently-dead USB target, may be never).
+
+`scsi::reset()` is now a wrapper that runs the platform-specific reset
+on a detached worker thread and bounds the caller's wait via
+`mpsc::recv_timeout(DEFAULT_RESET_TIMEOUT_SECS)` (30 s). Returns
+`DeviceResetFailed` on timeout. The worker thread keeps running until
+the kernel eventually unblocks (we can't cancel a Linux ioctl from
+userspace) — this leaks one OS thread per hard wedge, an acceptable
+cost for a daemon that recovers vs. one that hangs.
+
+- New `pub const DEFAULT_RESET_TIMEOUT_SECS: u64 = 30;`
+- New `pub fn reset_with_timeout(device, Duration) -> Result<()>` for
+  callers that want a different bound.
+- Existing `pub fn reset(device) -> Result<()>` keeps the same
+  signature; behaviour change is the timeout, not the API.
+
+### Follow-up flagged
+
+`SG_SCSI_RESET` only resets at the SCSI layer. For USB-attached drives
+(the BU40N case), the wedge is often in the USB Mass Storage layer
+*below* SCSI — `SG_SCSI_RESET` doesn't help. The proper escalation is
+`USBDEVFS_RESET` (the `usbreset.c` ioctl), which re-enumerates the
+device at the USB layer. Tracked for 0.13.2: a `scsi::usb_reset(path)`
+that resolves sg → USB device and issues `USBDEVFS_RESET`. That would
+have recovered tonight's BU40N without operator intervention.
+
+## 0.13.0 (2026-04-24)
+
+### Zero English in library — typed variants for every error path
+
+Audit pass against the `project docs` rule (no English text in library code).
+Found nine call sites that violated the contract by stuffing English into
+`io::Error::new(kind, "…")` or by abusing `Error::DeviceNotFound { path }`
+as a free-form description field. Each is now a typed variant with
+structured fields; the CLI / autorip translates to localized text.
+
+New `Error` variants and codes:
+
+- `ScsiInterfaceUnavailable { path }` — `E1004` (macOS
+  `SCSITaskDeviceInterface` couldn't be obtained)
+- `DeviceLocked { path, kr }` — `E1005` (replaces an English
+  "exclusive access denied. Try: diskutil unmountDisk" message)
+- `IoKitPluginFailed { path, kr }` — `E1006`
+- `UnsupportedPlatform { target }` — `E2003` (built on an OS without an
+  SCSI backend)
+- `PlatformNotImplemented { platform }` — `E2004` (replaces the
+  `product_revision: "Renesas not yet implemented"` string-stuffing in
+  `drive::mod`)
+- `MapfileInvalid { kind }` — `E6011` (ddrescue mapfile parse, with a
+  stable `&'static str` kind: `"status_char"` or `"hex"`)
+- `DiscUrlNotDirect` — `E9009` (replaces the full English sentence
+  `"Use Drive::open() + Disc::scan() + DiscStream::new() for disc sources"`
+  that `mux::input(disc://…)` returned to callers)
+
+Migrated call sites:
+
+- `mux/resolve.rs` — disc URL → `DiscUrlNotDirect`; the four
+  `format!("m2ts://…")` / `format!("mkv://…")` IO error wraps now
+  propagate the inner `io::Error` unchanged (the URL-prefix wrap added
+  no semantic information).
+- `mux/iso.rs` — same `format!("iso://…")` wrap dropped.
+- `sector.rs` — image-too-large now uses the existing `IsoTooLarge`
+  variant instead of `format!("…image too large, max ~8 TB")`.
+- `disc/mapfile.rs` — bad-status-char and bad-hex parser errors now use
+  `MapfileInvalid { kind }`.
+- `scsi/mod.rs` — unsupported-platform path uses `UnsupportedPlatform`.
+- `scsi/macos.rs` — IOKit plugin failure → `IoKitPluginFailed`,
+  `SCSITaskDeviceInterface` missing → `ScsiInterfaceUnavailable`,
+  exclusive-access denied → `DeviceLocked` with the IOReturn code as a
+  structured `kr` field. The `find_scsi_service` four-stage failure path
+  is now a single `DeviceNotFound { path }` (none of the prior
+  per-stage English descriptions were user-actionable individually).
+- `drive/mod.rs` — Renesas platform → `PlatformNotImplemented`.
+
+### Stripped English from `labels` module
+
+`labels::apply()` previously pushed `"Commentary"`, `"Descriptive Audio"`,
+`"Score"`, `"IME"`, and `" (Secondary)"` directly into
+`AudioStream.label`. Those English strings then leaked into MKV titles
+and into autorip's UI. The data was already structured upstream
+(`LabelPurpose` enum on `StreamLabel`); the lib was downcasting it for
+the caller's convenience.
+
+- `AudioStream` gains `purpose: LabelPurpose` (re-exported from
+  `crate::disc` next to the struct, alongside `LabelQualifier`).
+- `SubtitleStream` gains `qualifier: LabelQualifier`.
+- `apply()` writes structured fields, never English. `label` keeps
+  codec-formatting only (`"Dolby TrueHD 5.1"`).
+- `generate_audio_label` drops the `" (Secondary)"` suffix; `secondary`
+  is already a `bool` field, callers render it.
+- `generate_video_label` drops the `"Secondary Video"` fallback.
+  `"Dolby Vision EL"` kept (brand identifier, not translatable).
+
+### API hygiene
+
+- **mux module visibility tightened**. `pub mod ebml`, `m2ts`, `mkv`,
+  `network`, `null`, `ps`, `stdio`, `ts`, `tsmux` are now `pub(crate)`.
+  Their *types* are still re-exported from `lib.rs` — the modules
+  themselves were leaking low-level EBML primitives, TS muxer
+  internals, and network/stdio implementations that no external caller
+  used. `mux::codec`, `mux::disc`, `mux::iso`, `mux::resolve`, and
+  `mux::meta` stay public (genuine APIs).
+- **Stream trait rustdoc**. The keystone PES `Stream` trait (in
+  `pes.rs`) had per-method docs but no trait-level doc. Now explains
+  read-vs-write split, error contracts, the role of `info()` /
+  `codec_private()` / `headers_ready()`.
+- **lib.rs re-export sections**. Eight grouped sections with a
+  paragraph each (Drive lifecycle, Errors, Decryption, Disc structure,
+  Streams, Lower-level surfaces) so `cargo doc` tells callers when to
+  reach for what.
+- **Dropped `ScanOptions::with_keydb()`**. The `_with_X` constructor
+  pattern was banned by `project docs` (one method per action). Use the
+  struct literal: `ScanOptions { keydb_path: Some(p.into()) }`. Five
+  external call sites (autorip ×3, freemkv CLI ×3) and three test
+  fixtures migrated.
+- **`pid_index` allocation documented**. The `TsDemuxer::new` flat
+  lookup table was flagged by audit as "unbounded for adversarial
+  PIDs"; on closer reading it's bounded by `u16::MAX × 2 bytes ≈ 128 KB`.
+  Doc comment now states the bound explicitly so future contributors
+  don't re-flag it.
+
+### Dead-code sweep
+
+Pre-PES-rewrite leftovers that were `pub` but unreachable:
+
+- Deleted `mux/lookahead.rs` entirely (orphan file — never had a `mod`
+  declaration; only used by its own tests).
+- Deleted `mux/tsreader.rs` (`TsDemuxReader` struct + four methods,
+  used nowhere).
+- Deleted `mux::ebml::write_int`, `read_vint`, `SEEK_HEAD`, `SEEK`,
+  `SEEK_ID`, `SEEK_POSITION` (unused).
+- Deleted `mux::ts::scan_first_pts`, `scan_last_pts`, `scan_duration`,
+  `SCAN_HEAD_SIZE`, `SCAN_TAIL_SIZE`, `take_remainder`, `set_remainder`
+  (unused since the v0.10 PES rewrite).
+- Deleted `MkvMuxer::codec_private_slots` /
+  `codec_private_filled` fields and `fill_codec_private` method —
+  deferred-codecPrivate path was never exercised once codec_privates
+  flowed through `DiscTitle`.
+
+`cargo clippy --all-targets -- -D warnings` is clean.
+
+### Tests
+
+- New `error::tests` module — code distinctness, Display has no English
+  words, `io::ErrorKind` mapping for every new variant.
+- 233 lib tests (was 230), all green.
+
+### Breaking changes
+
+Source-compatible for callers who use `Error` opaquely (handle
+`Result<T, Error>` and `error.code()` only). The following are breaking:
+
+- `ScanOptions::with_keydb()` removed — use struct literal.
+- `mux::ebml`, `mux::mkv`, `mux::ts`, etc. modules no longer accessible
+  externally — use the re-exported types from the crate root instead.
+- `AudioStream` and `SubtitleStream` gained required fields (`purpose`,
+  `qualifier`). Construction-by-struct-literal must include them.
+- `Error::UnsupportedDrive { product_revision: "Renesas not yet
+  implemented" }` no longer produced — match `PlatformNotImplemented`.
+
+### Magic-number policy
+
+Per the v0.13 audit directive: new code in this release uses named
+documented constants (e.g. `POLL_INTERVAL_SECS` in autorip, the wedge
+signature literals in `ripper.rs`, the `BD_TS_PID_SPACE` floor in
+`ts.rs`'s table allocation). A comprehensive retrofit of pre-existing
+magic numbers across the older codebase is queued as follow-up work for
+0.13.1+ — too large to absorb into this release without scope creep.
+
+## 0.12.0 (2026-04-24)
+
+### Rust 2024 edition migration
+- Bumped `edition = "2024"`. Required code changes:
+  - FFI declarations in `src/scsi/macos.rs` wrapped in `unsafe extern "C" { … }` per the 2024 FFI safety rules.
+  - `unsafe_op_in_unsafe_fn` lint: `vtable_fn()` body now has an explicit `unsafe { … }` block rather than relying on implicit unsafe of the containing `unsafe fn`.
+  - Match-ergonomics: removed redundant `ref`/`ref mut` bindings in `mux/meta.rs`, `mux/mkvstream.rs`, `mux/network.rs`, `mux/stdio.rs` — 2024 tightens "cannot explicitly borrow within an implicitly-borrowing pattern."
+- No behavior change. MSRV stays at 1.86.
+
+### Minor / version sync
+- Part of the 0.12.0 ecosystem release. The autorip-side fixes (progress regressions, UI redesign, regression-guard tests) drove the minor bump.
+
+## 0.11.22 (2026-04-24)
+
+### Version sync — no functional changes
+Part of the 0.11.22 ecosystem release. autorip 0.11.22 ships full multi-pass UI (bad-range viz, live mapfile stats, Recovery settings); the library API is unchanged from 0.11.21.
+
+## 0.11.21 (2026-04-24)
+
+### Multi-pass rip architecture — disc → ISO → patch → ISO
+
+New primitives for two-stage rip: fast forward pass with zero-fill on failures, then targeted retries of bad ranges. Keeps the library API stream-based; the multi-pass model lives entirely in caller-orchestrated function composition.
+
+- **New `Disc::copy(reader, path, &CopyOptions)`** replaces the positional-arg version. Always produces a ddrescue-format mapfile at `path + ".mapfile"` as a side-effect. With `skip_on_error=true` + `skip_forward=true`, does ddrescue-style fast sweep: 64 KB block reads, exponential skip-forward (256 KB → cap at 1% of disc) on failure, zero-fill bad blocks, record ranges in the mapfile. With defaults (both false), matches pre-0.11.21 behavior — uses drive-level recovery, aborts on bad sector. Mapfile is produced either way.
+- **New `Disc::patch(reader, path, &PatchOptions)`** — idempotent retry pass. Reads the mapfile, re-reads every non-`+` range with full drive recovery enabled, writes successful bytes back into the ISO at exact offsets, updates mapfile. Call N times for N retry attempts.
+- **New `disc::mapfile` module** — ddrescue-compatible plain-text format. Crash-safe (flushes on every `record()`), greppable, human-editable, tool-interoperable. Status chars match ddrescue: `?` non-tried · `*` non-trimmed · `/` non-scraped · `-` unreadable · `+` finished.
+- **Re-exports:** `FileSectorReader` from the crate root for ISO readers.
+
+### Breaking changes
+- `Disc::copy`'s signature changes from positional args (`decrypt, resume, batch, on_progress`) to `CopyOptions`. Previous callers must migrate. `freemkv` CLI updated in lockstep.
+
+### Version sync
+- Part of the 0.11.21 ecosystem release (libfreemkv + freemkv + bdemu + autorip all on 0.11.21).
+
+## 0.11.18 (2026-04-24)
+
+### DiscStream halt flag — Stop works during dense bad-sector regions
+
+`DiscStream::fill_extents` loops internally when the demuxer hasn't accumulated enough data to emit a PES frame — during a dense bad-sector run, that loop can spend many minutes shrinking batch sizes and zero-filling sectors without ever returning to the outer read() call. Without an internal halt check, the caller's Stop request goes unserviced until the demuxer eventually emits a frame, which may be very far away.
+
+- **`DiscStream::set_halt(Arc<AtomicBool>)`** — share a halt flag with the stream. Typically wired to `Drive::halt_flag()` so Stop propagates across both the drive's recovery phases and the stream's sector processing.
+- **`fill_extents()` checks the halt flag** at the top of every retry iteration (before each attempt at every size level). Raising the flag aborts within one read round-trip — at most the current SCSI command's timeout.
+- Returns `Err(Error::Halted)` (E6010) so the outer rip pipeline terminates cleanly.
+
+No behavior change for callers that don't call `set_halt`. Unblocks the architectural fix for the "Stop doesn't stop" bug observed on a damaged UHD disc where the stream was stuck in a 12+ hour bad-sector grind.
+
+## 0.11.17 (2026-04-23)
+
+### Adaptive batch sizer in DiscStream — no more per-sector descent
+
+Rip recovery rewritten. The old binary-search-per-bad-sector model paid the full descent (batch → half → quarter → … → single) for every bad sector in a region. On a damaged disc with 600 consecutive bad sectors this took 12+ hours. The new algorithm pays the descent once, remembers the working size, and ramps back up only after a sustained clean streak.
+
+- **`BatchSizeChanged { new_size, reason }` event** — fires on shrink (read failed) and probe-up (clean streak threshold hit). Consumers use this to distinguish a "recovering" rip from a normal one.
+- **Removed `BinarySearch` and `SectorRecovered` emissions from DiscStream** — no longer produced by the rip path. `SectorRecovered` still fires from `Drive::read`'s multi-phase recovery (unused by rips today, but kept for scan/other callers).
+- **Removed `read_with_binary_search` and the 3×5s light-recovery loop** — no retry loops, no sleeps. One 5s attempt per read. On size-1 failure, skip (zero-fill) or error.
+- **Probe-up threshold: 100 MiB (51,200 sectors) of clean reading at current size** before doubling toward preferred. Ramp 1 → preferred on good reading takes ~100 seconds for a typical BD — trivial vs. rip duration, conservative enough that a single lucky sector in a marginal zone can't trigger a premature probe.
+- **Bad-region math**: ~600 consecutive bad sectors now complete in ~50 min (600 × 5s) instead of ~12h. The descent is O(log preferred) one time, not per sector.
+
+### macOS
+
+- Fix new clippy lint (`manual_c_str_literals`) in `scsi/macos.rs`.
+
+## 0.11.16 (2026-04-21)
+
+### API cleanup — one method per action
+- **SectorReader::read_sectors(lba, count, buf, recovery)** — single method with `recovery: bool`. Removes `read_sectors_recover()`.
+- **parser_for_codec(codec, codec_data)** — single constructor. Removes `parser_for_codec_with_data()`.
+- **DvdSubParser::new(codec_data)** — single constructor. Removes `with_codec_data()`.
+- **MkvMuxer::new(writer, tracks, title, duration, chapters)** — single constructor. Removes `new_with_chapters()`.
+
+## 0.11.15 (2026-04-21)
+
+### Lint cleanup
+- Fix all `cargo fmt` and `cargo clippy -D warnings` across codebase.
+- Remove unused imports, dead code, collapsible if-statements, div_ceil reimplementation.
+
+## 0.11.14 (2026-04-21)
+
+### Audit fixes: read recovery, verify, SCSI
+- **Fix: trailing sectors at extent boundaries** — extents with sector_count not divisible by 3 no longer drop 1-2 trailing sectors. decrypt_sectors() safely skips partial AACS units.
+- **Fix: verify_title stop support** — progress callback now returns bool. Return false to stop verification early instead of running to completion.
+- **Fix: O_CLOEXEC on all SCSI fd opens** — prevents fd leak to child processes.
+- **Fix: SCSI sense descriptor format** — correctly detect response code 0x72/0x73 (descriptor format) and extract sense key from byte 1 instead of byte 2.
+- **Fix: DecryptFailed on missing unit key** — decrypt_sectors() returns Err(DecryptFailed) instead of silently using a zero key.
+
+## 0.11.13 (2026-04-21)
+
+### Fix: all rip reads use fast timeout
+- Initial batch read changed from full Drive::read() recovery to fast 5s timeout. Binary search starts immediately on failure instead of after 10 minutes of retries.
+- Max 15 seconds per bad sector (3 x 5s attempts). Max 23 seconds per batch with 1 bad sector.
+
+## 0.11.12 (2026-04-21)
+
+### Drive halt + sector events + light recovery
+- **Drive.halt()** — AtomicBool flag checked between retry phases. Max 30s to stop.
+- **Drive.on_event()** — callback for ReadError, Retry, SpeedChange, SectorRecovered events.
+- **Error::Halted (E6010)** — distinct from DiscRead, indicates intentional stop.
+- **Binary search light recovery** — single sectors get 3 attempts x 5s (15s max) instead of full 10-min Drive::read() recovery. Marginal disc zones complete in minutes not hours.
+- **DiscStream.on_event()** — BinarySearch, SectorRecovered, SectorSkipped events.
+
+## 0.11.11 (2026-04-20)
+
+### Binary search error recovery
+- **fill_extents binary search** — when a batch read fails, binary search to isolate the failing sector(s). Good sectors read in sub-batches at full speed. Only truly bad sectors get individual recovery. 60-sector batch with 1 bad sector: ~5 seconds instead of 10+ minutes.
+
+## 0.11.10 (2026-04-20)
+
+### Skip errors + clean verify API
+- **DiscStream.skip_errors** — when true, zero-fills unreadable sectors and continues instead of aborting. Caller sets based on user preference.
+- **read_sectors_recover(recovery: bool)** — single API for recovery vs fast reads. Replaces separate read_sectors_fast method.
+
+## 0.11.9 (2026-04-20)
+
+### Fast verify reads
+- **read_sectors_fast()** — single-attempt 5s timeout SCSI read for verify. No recovery loop. Bad sectors detected in seconds instead of 10+ minutes.
+- **SectorReader trait** — added read_sectors_fast() with default fallback to read_sectors().
+
+## 0.11.8 (2026-04-20)
+
+### Disc verify
+- **verify::verify_title()** — sector-by-sector health check. Classifies sectors as Good/Slow/Recovered/Bad. Progress callback, chapter mapping, sector ranges.
+
+## 0.11.7 (2026-04-19)
+
+### TrueHD parser rewrite
+- **12-bit length mask** — access unit length is lower 12 bits of first 2 bytes, not full 16. Upper 4 bits are parity nibble. Wrong mask caused misaligned frame splits.
+- **AC-3 frame skipping** — BD-TS TrueHD PES contains interleaved AC-3 frames (same PID). Parser now detects AC-3 sync word (0x0B77) and skips those frames.
+- **Cross-PES buffering** — access units that span PES packet boundaries are correctly reassembled.
+- **Per-unit timestamps** — each access unit gets incrementing PTS (1/1200th second apart) instead of all units in one PES sharing the same timestamp.
+- **Major sync detection** — keyframe flag set when access unit contains MLP major sync (0xF8726FBA).
+- Result: zero TrueHD decode errors on UHD and BD (was ~19 per 30 seconds).
+
+## 0.11.6 (2026-04-18)
+
+### TrueHD fix (incomplete)
+- Initial attempt at TrueHD header stripping — wrong approach, superseded by 0.11.7.
+
+## 0.11.5 (2026-04-18)
+
+### MKV container fixes — Jellyfin/player compatibility
+- **Timestamp normalization** — MKV and M2TS output starts at 0.000s instead of raw disc PTS offset. Fixes playback failures in Jellyfin and other players.
+- **DefaultDuration** — correct frame rate written to MKV track header. Fixes wrong avg_frame_rate (was 293/12, now 24000/1001).
+- **HDR Colour metadata** — MatrixCoefficients, TransferCharacteristics, Primaries, Range written to MKV video track. Enables HDR tone mapping in players.
+- **DisplayWidth/DisplayHeight** — aspect ratio fields in MKV video track.
+- **Chapters (Blu-ray)** — accept mark_type 0 as chapter entry (was filtering to type 1 only, which no disc uses).
+- **Chapters (DVD)** — extract chapter timestamps from PGC program map + cell durations.
+- **Default disposition** — only first video and first audio track marked default. Fixes wrong auto-selection in players.
+
+## 0.11.3 (2026-04-18)
+
+### Unified versioning
+- All freemkv repos now share the same version number. No functional changes from 0.10.10.
+
+## 0.10.10 (2026-04-18)
+
+### Dual-layer disc fix
+- **UDF extent allocation** — use actual UDF allocation descriptors (`file_extents()`) instead of assuming m2ts files are contiguous from `file_start_lba`. Dual-layer UHD discs split large files across many extents (~1 GB each). The old single-extent assumption truncated rips at ~37% on affected discs.
+- **Read error propagation** — `fill_extents()` returns `io::Result<bool>` so SCSI read errors propagate to the caller instead of being silently treated as EOF.
+
+## 0.10.9 (2026-04-17)
+
+### Fast disc identification
+- **Disc::identify()** — reads UDF filesystem only (name, format, layers, encrypted). ~3s on USB vs 18s for full scan. No AACS handshake or playlist parsing.
+- **KEYDB path fix** — added `~/.config/freemkv/keydb.cfg` to search paths. Fixes silent rip hang when KEYDB exists but isn't found by `resolve_keydb()`.
+
+## 0.10.8 (2026-04-17)
+
+### Buffered UDF reads
+- **BufferedSectorReader** — prefetches batch sectors on single-sector reads. USB drives have ~500ms per SCSI command; this eliminates scan hangs.
+- **Metadata partition pre-read** — loads entire UDF metadata partition into memory after initial parse.
+- Scan time reduced from 10+ minutes to ~18 seconds on USB.
+
+## 0.10.7 (2026-04-17)
+
+### DiscStream::new()
+- Replaced open_drive(), open_iso(), from_reader() with single new() constructor
+- Stream accepts ContentFormat and sets up demuxer internally
+- Removed disc:// case from input() — callers use primitives directly
+
+## 0.10.6 (2026-04-16)
+
+### Docker compatibility
+- **Drive discovery** — removed sysfs check that blocked detection inside Docker containers. Device nodes are sufficient; INQUIRY command validates the device is an optical drive.
+
+## 0.10.5 (2026-04-16)
+
+### Audio parser buffering
+- **AC3** — buffer across PES boundaries with frame size from fscod/frmsizecod table. Eliminates all AC3 decode errors on BD and UHD.
+- **DTS** — buffer with core sync detection + frame size from header. DTS-HD extension frames handled correctly.
+- **TrueHD** — buffer with unit length field parsing. Incomplete units held for next PES.
+- All audio parsers now emit complete frames only. When PES boundaries align (normal case), buffering is a no-op.
+
+## 0.10.4 (2026-04-16)
+
+### CSS decryption — full key hierarchy
+- **Bus auth → disc key → title key** — complete CSS key chain. Bus authentication with CSSCryptKey challenge-response, disc key decryption using 31 player keys via READ DVD STRUCTURE, title key extraction via REPORT KEY format 0x04.
+- **CSS descramble cipher** — correct LFSR keystream generation with TAB5 for LFSR1 output and TAB4 for LFSR0 output. Per-sector key derivation from title key XOR sector seed.
+- **Stevenson plaintext attack** — expanded pattern set (padding, video, audio, nav pack headers), scans up to 50K scrambled sectors for ISO key recovery.
+- **Disc::copy() CSS decrypt** — sector-level decryption during disc→ISO copy produces clean ISOs with zero scramble flags.
+
+### MPEG-2 PS demuxer fixes
+- **DVD PS path routes through codec parsers** — was bypassing parser.parse(), producing raw PES frames without codec_private extraction or keyframe detection.
+- **MPEG-2 sequence header extraction** — calculates exact header size including quantizer matrices (intra/non-intra flags), captures sequence extension from subsequent PES packets.
+- **TsDemuxer dynamic PID table** — Vec instead of fixed [i16; 8192] for DVD PIDs that may exceed 8192.
+
+## 0.10.3 (2026-04-16)
+
+### DVD CSS authentication
+- **CSS drive authentication** — full SCSI REPORT KEY / SEND KEY handshake with 6-round substitution-permutation cipher (CSSCryptKey). Brute-forces variant from 32 possibilities. Drive serves scrambled sectors after auth completes.
+- **CSS auth runs before scan** — chicken-and-egg fix: auth must happen before reading VOB sectors for title key cracking, not after.
+- **Remove debug output** — strip temporary eprintln from drive reads and CSS auth.
+
+## 0.10.2 (2026-04-15)
+
+### Fixes
+- **Disc::copy() batch overflow** — hardcoded 64-sector batch exceeded BU40N's 60-sector hardware limit, causing every read to fail and trigger 5×30s recovery sleep. Now accepts detected batch size from caller, defaults to 60.
+- **IFO PGC parsing** — playback time read from offset 0x04 (correct) instead of 0x02 (nr_programs). Cell BCD time at cell+4 not cell+0. DVD durations now correct.
+- **Demuxer flush at EOF** — TS and PS demuxers flushed when source reaches EOF, preventing loss of last PES frame. Applied to DiscStream and M2tsStream.
+- **DiscStream demuxer selection** — demuxer set by caller based on content_format (TS for Blu-ray, PS for DVD) instead of unconditionally creating TsDemuxer in from_reader()
+- **StdioStream FMKV header** — writes/reads metadata header for roundtrip compatibility through stdio pipes
+
+## 0.10.1 (2026-04-15)
+
+### Architecture: streams are PES, disc.copy() for sector dumps
+- **One stream per format, bidirectional PES** — MkvStream, M2tsStream, NetworkStream, StdioStream, NullStream each handle read and write
+- **IsoStream merged into DiscStream** — one type for physical drives and ISO files, different SectorReader
+- **Disc::copy()** — raw sector dump for disc→ISO, not a stream operation
+- **IOStream deleted** — no more byte-level Read/Write on streams
+- **ContentReader/OpenDisc deleted** — replaced by DiscStream + PES pipeline
+- **CountingStream** — wrapper for progress tracking, no state in streams
+
+### Error codes only — zero English in library
+- All `io::Error::new(kind, "english")` replaced with `Error` enum variants
+- New error variants: StreamReadOnly, StreamWriteOnly, StreamUrlInvalid, MkvInvalid, NoStreams, etc.
+- `From<Error> for io::Error` — clean conversion at system boundaries
+- Removed unused error variants: WriteError, ProfileNotFound, NotUnlocked, NotCalibrated, ScsiTimeout, etc.
+
+### Deleted dead code
+- `mkvout.rs`, `pesout.rs`, `isowriter.rs` — merged into parent stream types
+- `lookahead.rs` usage in MkvStream — replaced by PES direct write
+- ContentReader, OpenDisc, open_title() — replaced by PES pipeline
+- `open_input()`, `open_output()` — replaced by `input()`, `output()`
+
+## 0.10.0 (2026-04-15)
+
+### PES pipeline
+- **Unified Stream trait** — `read()` returns PES frames, `write()` accepts them. One trait for all streams.
+- **All streams produce/consume PES frames** — DiscStream, IsoStream, MkvStream, M2tsStream, NetworkStream, StdioStream, NullStream
+- **DVD PS demux** — MPEG-2 Program Stream demuxer produces PES frames
+- **MKV input stream** — MKV demux produces PES frames
+- **Network/stdio PES** — PES serialization over TCP and pipes
+- **FileSectorReader** — ISO files implement SectorReader for unified disc/ISO handling
+
+### PES pipeline audit (20 fixes)
+- PES serialize: track/length validation, OOM cap (256 MB), stuffing compliance
+- TsDemuxer: AF length validation, find_start_code verified
+- PTS: marker bit validation, ns→90kHz saturating_mul, round-to-nearest
+- AC3/DTS: debug_assert promoted to runtime check
+- MKV: block_vint 3-4 byte support, track bounds check
+- FMKV: JSON 10 MB cap, PAT section_len underflow guard
+
+### codec_privates refactor
+- **codec_privates on DiscTitle** — no separate parameter passing, no `_with_X` method variants
+- **Streams-not-files** — MkvStream and M2tsStream take `impl Read`, not `File`/`Seek`
+- **M2TS roundtrip fix** — TsMuxer Annex B conversion + codec_private in FMKV header
+- **MKV remux fix** — MkvStream returns codec_privates from EBML header
+- **Network codec_private fix** — FMKV header carries base64 codec_privates
+
+### Cleanup
+- Remove Seek/File dependencies from stream interfaces
+- Remove eprintln from library code
+- Fix all clippy warnings
+- 342 tests pass
+
+## 0.9.0 (2026-04-14)
+
+### Drive recovery + decrypt architecture
+- **Drive::read()** — single read method with built-in error recovery (min speed → reset → retry)
+- **Decrypt in streams** — streams handle their own decryption via `decrypt_sectors()`. Pipeline just moves bytes.
+- **keys() on IOStream** — streams report their own decrypt keys
+- **InputOptions** — `--raw` wired through to streams, skips decrypt only
+- **decrypt_sectors returns Result** — fail instead of silent corruption
+- **Handshake fix** — no longer returns fake success on failure
+- **Drive::read_capacity()** — for raw sector dump (disc→ISO)
+- **Reset on open** — SgIoTransport resets device on every open
+- **Simplified DiscStream** — removed on_error/on_success/Recovery enum
+
+### Platform
+- **Rust 1.86 MSRV** pinned in Cargo.toml and CI
+- **macOS build fix** — MacScsiTransport marked Send
+- **is_multiple_of** — replaced nightly API with stable equivalent
+
+### API changes
+- **Drive object** — typed DriveSession API
+- **Typed StreamUrl** — URL parsing returns enum, not strings
+- **DriveStatus API** — reset(), wait_ready with fallback
+- **Granular SCSI queries** — individual methods on DriveSession for capture
+- **Profile module public** — for external tools (bdemu)
+- **Tray lock/unlock** — exposed on Drive
+
+## 0.8.0 (2026-04-11)
+
+### DVD support
+- **Full DVD pipeline** — VIDEO_TS detection, IFO parsing, CSS decryption, MPEG-2 PS demuxing
+- **CSS cipher** — Stevenson 1999 table-driven implementation, no keys needed
+- **IFO parser** — title sets, PGC chains, cell addresses, audio/subtitle attributes, palette
+- **MPEG-2 PS demuxer** — pack headers, PES extraction, private stream 1 sub-streams
+- **MPEG-2 video parser** — sequence headers, I-frame detection, codec_private
+
+### 100% codec coverage
+- **E-AC-3 (Dolby Digital Plus)** — bsid detection, frame size calculation
+- **DTS-HD MA/HR** — extension substream detection and inclusion
+- **LPCM** — BD header skip, raw PCM extraction
+- **DVD subtitles (VobSub)** — passthrough with IFO palette extraction (YCbCr→RGB)
+- **Dolby Vision** — verified RPU NAL type 62 preserved in HEVC passthrough
+
+### MKV improvements
+- **Chapters** — MPLS PlayList marks → MKV Chapters element
+- **Track flags** — FlagDefault, FlagForced, Language correctly set
+- **HEVC codec_private** — profile compatibility and constraint flags from SPS
+- **VC-1 codec_private** — resolution parsed from sequence header
+
+### Architecture
+- **SectorReader trait** — decouples disc scanning from SCSI
+- **Disc::scan_image()** — scan ISO images or any SectorReader
+- **resolve_encryption()** — single function handles AACS 1.0/2.0/CSS/none
+- **Module refactors** — disc/ (4 files), aacs/ (5 files), drive/ (3 files)
+- **Module visibility** — internal modules pub(crate), explicit AACS re-exports
+
+### Streams
+- **StdioStream** — stdin/stdout pipe
+- **IsoStream** — read/write Blu-ray ISO images with UDF 2.50 filesystem
+- **Strict URLs** — all URLs require scheme:// prefix, bare paths rejected
+- **total_bytes()** — IOStream reports content size for progress display
+
+### Platform
+- **Windows SPTI** — SCSI Pass-Through Interface backend
+- **Windows builds** — CI + release workflow for x86_64-pc-windows-msvc
+- **macOS drive discovery** — separate from Linux (drive/macos.rs)
+- **Stable download URLs** — /latest/download/ with version-free filenames
+
+### Audit fixes (4 rounds, 14→0 critical)
+- UDF bounds checking on all disc-sourced offsets
+- SCSI: Linux residual underflow, macOS task_status type, Windows buffer zeroing
+- AACS: EC mod_inv safe, key reduced mod n, host cert fallback
+- DiscStream: persistent read state (was recreating ContentReader per call)
+- ISO writer: UDF tag checksums, multi-extent >4GB, reserve AVDP placement
+- CSS crack: labeled loop break, polynomial match
+- 0 clippy warnings
+
+### Testing
+- **327 tests** (was 64 at start)
+- CSS/AACS cross-validation against independent AES implementation
+- End-to-end MKV mux test with H.264 codec headers
+
+## 0.7.2 (2026-04-11)
+
+### Windows support
+
+- **SPTI backend** (`scsi/windows.rs`) — SCSI_PASS_THROUGH_DIRECT via DeviceIoControl
+- **Windows drive discovery** (`drive/windows.rs`) — scans CdRom0-15 + drive letters
+- **Platform file separation** — `drive/unix.rs` and `drive/windows.rs`, no inline cfg branches
+- **CI** — `cargo check` on windows-latest, actions/checkout@v5
+
+### Test suite
+
+- **177 tests** (was 64) — MPLS, CLPI, H.264, HEVC, AC3, VC1, DTS, TrueHd, PGS, EBML, UDF, disc scanning, streams
+- **FEATURES.md** created
+
+### Improvements
+
+- **Stable download URLs** — `/latest/download/freemkv-x86_64-unknown-linux-musl.tar.gz` works forever
+
+## 0.7.1 (2026-04-11)
+
+### SectorReader trait
+
+- **`SectorReader` trait** — decouples disc scanning from SCSI. UDF, MPLS, CLPI, labels, and AACS resolution now work with any sector source.
+- **`Disc::scan_image()`** — scan ISO images or any SectorReader. Full title/stream/label/AACS pipeline, no drive required.
+- **`resolve_encryption()`** — single function handles AACS 1.0, 2.0, or none. Uses whatever path works (KEYDB VUK, handshake, media key, device key).
+
+### Stream types
+
+- **7 stream types** — Disc, ISO, MKV, M2TS, Network, Stdio, Null
+- **`IsoStream`** — read/write Blu-ray ISO images. Uses `Disc::scan_image()` for full UDF parsing (not heuristic scanning).
+- **`StdioStream`** — stdin/stdout pipe, format-agnostic
+- **Strict URL format** — all URLs require `scheme://path`. Bare paths rejected with clear error messages.
+- **Validation** — empty paths, missing ports, read-only/write-only direction errors
+
+### IOStream trait
+
+- `IOStream` trait for all stream types (Read + Write + info + finish)
+- `open_input()` / `open_output()` resolve URL strings to stream instances
+
+## 0.7.0 (2026-04-11)
+
+### Stream I/O architecture
+
+- **5 stream types** — Disc, MKV, M2TS, Network, Null
+- **`IOStream` trait** — common interface for all streams
+- **URL resolver** — `open_input()` / `open_output()` with scheme://path format
+- **FMKV metadata header** — JSON metadata embedded in M2TS and network streams
+- **Bidirectional MKV** — MkvStream reads and writes Matroska containers
+- **Network streaming** — TCP with metadata header, TCP_NODELAY
+- **BD-TS demuxer** — PAT/PMT scanning, PTS duration detection
+- **EBML reader** — parse existing MKV files for read-side MkvStream
+
 ## 0.6.0 (2026-04-10)
 
 ### API improvements

Cargo.toml

@@ -1,7 +1,8 @@
 [package]
 name = "libfreemkv"
-version = "0.6.0"
-edition = "2021"
+version = "0.13.1"
+edition = "2024"
+rust-version = "1.86"
 license = "AGPL-3.0-only"
 description = "Open source raw disc access library for optical drives"
 repository = "https://github.com/freemkv/libfreemkv"
@@ -30,3 +31,7 @@ libc = "0.2"
 [target.'cfg(target_os = "macos")'.dependencies]
 libc = "0.2"
 
+[[bench]]
+name = "sgio_read"
+harness = false
+

FEATURES.md

@@ -0,0 +1,34 @@
+# libfreemkv — Feature List
+
+## v0.10.10 (current)
+
+### Done
+- [x] Drive access: open, identify, unlock, firmware upload, speed calibration, eject
+- [x] 206 bundled drive profiles (MediaTek MT1959 A + B variants)
+- [x] SCSI transport: Linux SG_IO, macOS IOKit, Windows SPTI
+- [x] UDF 2.50 filesystem parser (metadata partitions, Blu-ray profile)
+- [x] MPLS playlist parser (play items, STN table, secondary streams)
+- [x] CLPI clip info parser (EP map, sector extents)
+- [x] AACS 1.0 decryption (4 VUK paths: KEYDB, media key, processing key, device key)
+- [x] AACS 2.0 SCSI handshake (P-256/SHA-256 ECDH, bus decryption, read data key)
+- [x] DVD IFO parser (VMG, VTS, PGC chains, cell addresses)
+- [x] DVD CSS decryption (bus auth, disc key via player keys, title key, sector descramble)
+- [x] CSS Stevenson plaintext attack for ISO key recovery
+- [x] MPEG-2 PS demuxer (DVD Program Stream with PES extraction)
+- [x] MPEG-2 video codec parser (sequence header, quantizer matrices, keyframe detection)
+- [x] KEYDB.cfg download, verify, save (raw TCP, zero HTTP deps)
+- [x] Content reading with adaptive batch sizing, error recovery, 12+ MB/s
+- [x] Stream labels: 5 BD-J format parsers (Paramount, Criterion, Pixelogic, CTRM, Deluxe)
+- [x] MKV muxer: 14 codec parsers (H.264, HEVC, MPEG-2, AC-3, DTS, TrueHD, PGS, DVD Sub, VC-1, LPCM, +4 more)
+- [x] SectorReader trait: decouples disc scanning from SCSI
+- [x] 7 stream types: Disc, ISO, MKV, M2TS, Network, Stdio, Null
+- [x] PES pipeline with unified Stream trait (any source → any dest)
+- [x] FMKV metadata header for M2TS and network streams
+- [x] Numeric error codes only (no English text in library)
+- [x] Event system for progress callbacks
+
+### Planned
+- [ ] Windows testing on real hardware
+- [ ] Pioneer Renesas platform support (48 drives, need GET_CONFIG 010C)
+- [ ] TranscodeStream (ffmpeg integration)
+- [ ] ISO write with BD-compliant UDF structure

README.md

@@ -4,7 +4,7 @@
 
 # libfreemkv
 
-Rust library for 4K UHD / Blu-ray optical drives. Drive access, disc scanning, stream labels, AACS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.
+Rust library for 4K UHD / Blu-ray / DVD optical drives. Drive access, disc scanning, stream labels, AACS decryption, CSS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.
 
 **12+ MB/s** sustained read speeds on BD. Full init: unlock, firmware upload, speed calibration — all from pure Rust.
 
@@ -18,33 +18,62 @@ Part of the [freemkv](https://github.com/freemkv) project.
 
 ```toml
 [dependencies]
-libfreemkv = "0.6"
+libfreemkv = "0.11"
 ```
 
 ## Quick Start
 
 ```rust
-use libfreemkv::{DriveSession, Disc, ScanOptions};
+use libfreemkv::{Drive, Disc, ScanOptions};
 use std::path::Path;
 
 // Open drive — profiles are bundled, auto-identified
-let mut session = DriveSession::open(Path::new("/dev/sr0"))?;
-session.wait_ready()?;            // wait for disc
-session.init()?;                   // unlock + firmware upload
-session.probe_disc()?;             // probe disc surface for optimal speeds
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
+drive.wait_ready()?;              // wait for disc
+drive.init()?;                     // unlock + firmware upload
+drive.probe_disc()?;               // probe disc surface for optimal speeds
 
 // Scan disc — UDF, playlists, streams, AACS (all automatic)
-let disc = Disc::scan(&mut session, &ScanOptions::default())?;
+let disc = Disc::scan(&mut drive, &ScanOptions::default())?;
 
 for title in &disc.titles {
     println!("{} — {} streams", title.duration_display(), title.streams.len());
 }
 
-// Read content (decrypted transparently if AACS keys available)
-let mut reader = disc.open_title(&mut session, 0)?;
-while let Some(unit) = reader.read_unit()? {
-    // 6144 bytes of content per aligned unit
+// Stream pipeline — read PES frames from any source, write to any output
+let opts = libfreemkv::InputOptions::default();
+let mut input = libfreemkv::input("iso://Disc.iso", &opts)?;
+let title = input.info().clone();
+let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
+while let Ok(Some(frame)) = input.read() {
+    output.write(&frame)?;
 }
+output.finish()?;
+```
+
+### Multi-pass recovery rip
+
+For damaged discs, the library offers a two-stage rip model: fast sweep with zero-fill and a ddrescue-format mapfile, then targeted retry of bad ranges. See [`docs/rip-recovery.md`](docs/rip-recovery.md) for the full architecture.
+
+```rust
+use libfreemkv::disc::{CopyOptions, PatchOptions};
+
+// Pass 1: disc → ISO. Fast 64 KB reads, skip-forward on failure,
+// zero-fill bad blocks, write a sidecar .mapfile.
+let mut result = disc.copy(
+    &mut drive,
+    Path::new("disc.iso"),
+    &CopyOptions { skip_on_error: true, skip_forward: true, ..Default::default() },
+)?;
+
+// Pass 2..N: retry bad ranges with full drive recovery.
+// Idempotent — call as many times as you want.
+while result.bytes_unreadable + result.bytes_pending > 0 {
+    let pr = disc.patch(&mut drive, Path::new("disc.iso"), &PatchOptions::default())?;
+    if pr.bytes_recovered_this_pass == 0 { break; }
+}
+
+// Then mux from the ISO via the normal stream pipeline (no drive involvement).
 ```
 
 ## What It Does
@@ -56,24 +85,51 @@ while let Some(unit) = reader.read_unit()? {
 - **AACS decryption** — transparent key resolution and content decrypt (1.0 + 2.0 bus decryption)
 - **KEYDB updates** — download, verify, save from any HTTP URL (zero deps, raw TCP)
 - **Content reading** — adaptive batch reads with automatic decryption and error recovery
+- **Stream I/O** — unified stream pipeline for reading and writing any format
+
+### Streams
+
+| Stream | Input | Output | Transport |
+|--------|-------|--------|-----------|
+| DiscStream | Yes | -- | Optical drive via SCSI |
+| IsoStream | Yes | Yes | Blu-ray ISO image file |
+| MkvStream | Yes | Yes | Matroska container |
+| M2tsStream | Yes | Yes | BD transport stream with FMKV metadata header |
+| NetworkStream | Yes (listen) | Yes (connect) | TCP with FMKV metadata header |
+| StdioStream | Yes (stdin) | Yes (stdout) | Raw byte pipe |
+| NullStream | -- | Yes | Discard sink (byte counter for benchmarks) |
+
+Streams implement `IOStream` (byte-level) and `pes::Stream` (frame-level). `input()` / `output()` resolve URL strings to PES stream instances. `open_input()` / `open_output()` resolve to byte-level IOStream instances. All URLs use the `scheme://path` format — bare paths are rejected.
 
 AACS decryption requires a KEYDB.cfg file. If available at `~/.config/aacs/KEYDB.cfg` or passed via `ScanOptions`, the library handles everything — handshake, key derivation, and per-sector decryption — without the application needing to know anything about encryption.
 
 ## Architecture
 
 ```text
-DriveSession           — open any drive, identify, init (optional), read sectors
-  ├── ScsiTransport    — SG_IO (Linux), IOKit (macOS)
+Drive                  — open, identify, init, unlock, read (with recovery)
+  ├── ScsiTransport    — SG_IO (Linux), IOKit (macOS), SPTI (Windows)
   ├── DriveProfile     — per-drive unlock parameters (bundled)
   └── PlatformDriver   — MediaTek (supported), Renesas (planned)
 
-Disc                   — scan titles, streams, AACS state
+Disc                   — scan titles, streams, AACS/CSS state
   ├── UDF reader       — Blu-ray UDF 2.50 with metadata partitions
   ├── MPLS parser      — playlists → titles + clips + streams
   ├── CLPI parser      — clip info → EP map → sector extents
+  ├── IFO parser       — DVD title sets, PGC chains, cell addresses
   ├── Labels           — 5 BD-J format parsers (detect + parse)
   ├── AACS             — key resolution + content decryption
+  ├── CSS              — DVD CSS cipher (table-driven, no keys needed)
   └── KEYDB            — download + verify + save
+
+Streams                — unified PES pipeline
+  ├── pes::Stream      — read()/write() PES frames
+  ├── DiscStream       — sectors → decrypt → TS demux → PES
+  ├── IsoStream        — ISO file → decrypt → TS demux → PES
+  ├── MkvStream        — MKV mux/demux
+  ├── M2tsStream       — BD transport stream
+  ├── NetworkStream    — TCP with FMKV metadata header
+  ├── StdioStream      — stdin/stdout pipe
+  └── NullStream       — discard sink
 ```
 
 See [docs/](docs/) for detailed technical documentation on each module.
@@ -99,11 +155,11 @@ All errors are structured with numeric codes. No user-facing English text — ap
 |----------|--------|---------|
 | Linux | Supported | SG_IO ioctl |
 | macOS | Supported | IOKit SCSITask |
-| Windows | Planned | SPTI |
+| Windows | Supported | SPTI |
 
 ## Contributing
 
-Run `freemkv drive-info --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to contribute your drive's profile.
+Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/freemkv/freemkv) to contribute your drive's profile.
 
 ## License
 

benches/sgio_read.rs

@@ -0,0 +1,88 @@
+// Mimics ISO dump exactly — read + write + progress
+use libfreemkv::Drive;
+use std::io::Write;
+use std::path::Path;
+use std::time::Instant;
+
+fn main() {
+    let device = std::env::args()
+        .skip(1)
+        .find(|a| !a.starts_with('-'))
+        .unwrap_or_else(|| {
+            let drives = libfreemkv::find_drives();
+            if drives.is_empty() {
+                eprintln!("No drives found");
+                std::process::exit(1);
+            }
+            drives[0].device_path().to_string()
+        });
+
+    let mut drive = Drive::open(Path::new(&device)).unwrap_or_else(|e| {
+        eprintln!("Cannot open {}: {}", device, e);
+        std::process::exit(1);
+    });
+    eprintln!("wait_ready...");
+    let _ = drive.wait_ready();
+    eprintln!("read_capacity...");
+    let cap = drive.read_capacity().unwrap();
+    eprintln!("capacity: {} sectors", cap);
+
+    let batch = libfreemkv::disc::detect_max_batch_sectors(drive.device_path());
+    let mut buf = vec![0u8; batch as usize * 2048];
+
+    // Open /dev/null writer like ISO dump does
+    let file = std::fs::File::create("/dev/null").unwrap();
+    let mut writer = std::io::BufWriter::with_capacity(4 * 1024 * 1024, file);
+
+    eprintln!(
+        "Reading 1000 batches ({:.1} MB) with write + progress...",
+        1000.0 * batch as f64 * 2048.0 / 1_048_576.0
+    );
+
+    let start = Instant::now();
+    let mut ok = 0u32;
+    let mut fail = 0u32;
+    let mut bytes: u64 = 0;
+
+    // Recovery flag: true matches pre-0.11.13 bench behavior — full SCSI
+    // ECC retry loop on errors (slower, what the rip path used before the
+    // adaptive batch sizer landed). Flip to `false` for the fast-fail path
+    // that current rips use; benches are configurable via this constant.
+    const READ_WITH_RECOVERY: bool = true;
+
+    for i in 0..1000u32 {
+        let lba = i * batch as u32;
+        match drive.read(lba, batch, &mut buf, READ_WITH_RECOVERY) {
+            Ok(_) => {
+                writer.write_all(&buf).unwrap();
+                ok += 1;
+            }
+            Err(e) => {
+                fail += 1;
+                if fail <= 5 {
+                    eprintln!("  FAIL LBA {}: {}", lba, e);
+                }
+                buf.fill(0);
+                writer.write_all(&buf).unwrap();
+            }
+        }
+        bytes += buf.len() as u64;
+
+        if i % 50 == 0 && i > 0 {
+            let elapsed = start.elapsed().as_secs_f64();
+            let mb = bytes as f64 / 1_048_576.0;
+            eprint!("\r  {:.1} MB | {:.1} MB/s    ", mb, mb / elapsed);
+        }
+    }
+
+    let elapsed = start.elapsed().as_secs_f64();
+    let mb = ok as f64 * batch as f64 * 2048.0 / 1_048_576.0;
+    eprintln!(
+        "\n{} ok, {} fail, {:.1} MB in {:.1}s = {:.1} MB/s",
+        ok,
+        fail,
+        mb,
+        elapsed,
+        mb / elapsed
+    );
+}

docs/README.md

@@ -11,11 +11,12 @@ Technical documentation for [libfreemkv](https://github.com/freemkv/libfreemkv),
 | Document | What it covers |
 |----------|---------------|
 | [Architecture](architecture.md) | Module map, design principles, error codes, platform support |
-| [Drive Access](drive-access.md) | DriveSession, SCSI transport, profiles, unlock, why raw mode is needed |
+| [Drive Access](drive-access.md) | Drive, SCSI transport, profiles, unlock, why raw mode is needed |
 | [AACS Encryption](aacs.md) | Key resolution (4 paths), content decryption, bus encryption, SCSI handshake |
 | [UDF Filesystem](udf.md) | UDF 2.50 with metadata partitions, pointer chain, how files are read from disc |
 | [MPLS Playlists](mpls.md) | Playlist format, play items, STN stream table, coding types |
 | [CLPI Clip Info](clpi.md) | EP map (coarse + fine entries), timestamp-to-sector mapping, extent calculation |
+| [API Design](api-design.md) | Stream API design, PES pipeline, input/output resolution |
 
 ## Reading Order
 

docs/aacs.md

@@ -189,12 +189,14 @@ In practice, AACS 2.0 UHD discs work through the backward-compatible AACS 1.0 ha
 AACS decryption is transparent to the application. The `Disc::scan()` method handles everything automatically:
 
 ```rust
-use libfreemkv::{DriveSession, Disc};
+use libfreemkv::{Drive, Disc};
 use libfreemkv::disc::ScanOptions;
 use std::path::Path;
 
-let mut session = DriveSession::open(Path::new("/dev/sr0")).unwrap();
-let disc = Disc::scan(&mut session, &ScanOptions::default()).unwrap();
+let mut drive = Drive::open(Path::new("/dev/sg4")).unwrap();
+drive.wait_ready().unwrap();
+drive.init().unwrap();
+let disc = Disc::scan(&mut drive, &ScanOptions::default()).unwrap();
 
 // Check encryption state
 if disc.encrypted {

docs/api-design.md

@@ -12,82 +12,110 @@
 
 ```rust
 // Open drive — explicit steps, app prints between them
-let mut session = DriveSession::open(path)?;
-session.wait_ready()?;
-session.init()?;
-session.probe_disc()?;
+let mut drive = Drive::open(path)?;
+drive.wait_ready()?;
+drive.init()?;
+drive.probe_disc()?;
 
 // Scan disc
-let disc = Disc::scan(&mut session, &ScanOptions::default())?;
+let disc = Disc::scan(&mut drive, &ScanOptions::default())?;
 
 // Browse
-disc.titles      // Vec<Title>
+disc.titles      // Vec<DiscTitle>
 disc.format      // BD / UHD / DVD
 disc.capacity_gb()
-
-// Rip with events
-disc.rip(&mut session, 0, output, |event| {
-    match event.kind {
-        EventKind::BytesRead { bytes, total } => ...,
-        EventKind::ReadError { sector, error } => ...,
-        EventKind::Retry { attempt } => ...,
-        EventKind::SpeedChange { speed_kbs } => ...,
-        EventKind::Complete { bytes, errors } => ...,
-    }
-})?;
-
-// Rip without events
-disc.rip(&mut session, 0, output, event::ignore)?;
 ```
 
-## Stream Chains
+## PES Pipeline (primary API)
 
-Each stream wraps the next. Builder pattern, no `.build()`.
+The PES pipeline is the main way to move content. All streams produce/consume
+PES frames. The pipeline just reads frames and writes frames.
 
-### Raw m2ts
 ```rust
-disc.rip(&mut session, 0, File::create("movie.m2ts")?, event::ignore)?;
+// URL-based — any source to any destination
+let opts = InputOptions::default();
+let mut input = libfreemkv::input("disc:///dev/sg4", &opts)?;
+let title = input.info().clone();
+let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
+
+while let Ok(Some(frame)) = input.read() {
+    output.write(&frame)?;
+}
+output.finish()?;
 ```
 
-### MKV
+The `pes::Stream` trait:
+
 ```rust
-let output = MkvStream::new(File::create("movie.mkv")?)
-    .title(&disc.titles[0])
-    .max_buffer(10 * 1024 * 1024);
-
-disc.rip(&mut session, 0, output, |e| { ... })?;
+pub trait Stream {
+    fn read(&mut self) -> io::Result<Option<PesFrame>>;
+    fn write(&mut self, frame: &PesFrame) -> io::Result<()>;
+    fn finish(&mut self) -> io::Result<()>;
+    fn info(&self) -> &DiscTitle;
+    fn codec_private(&self, track: usize) -> Option<Vec<u8>>;
+    fn headers_ready(&self) -> bool;
+}
 ```
 
-### MKV with progress (CLI)
+## IOStream (byte-level API)
+
+For raw byte copies (disc→ISO, resume, benchmarks). Lower level than PES.
+
 ```rust
-let output = ProgressStream::new(
-    MkvStream::new(File::create("movie.mkv")?)
-        .title(&disc.titles[0])
-        .max_buffer(10 * 1024 * 1024),
-    total_bytes,
-    |pct, speed| eprint!("\r  {}%  {:.1} MB/s", pct, speed),
-);
-
-disc.rip(&mut session, 0, output, |e| { ... })?;
+let opts = InputOptions::default();
+let mut input = open_input("iso://Disc.iso", &opts)?;
+let mut output = open_output("mkv://Movie.mkv", input.info())?;
+io::copy(&mut *input, &mut *output)?;
+output.finish()?;
 ```
 
-### Future: transcode
+## Streams
+
+All streams implement `IOStream` (byte-level) and/or `pes::Stream` (frame-level).
+URL-based resolvers open any stream by string.
+
+| Stream | Input | Output | URL | Transport |
+|--------|-------|--------|-----|-----------|
+| DiscStream | Yes | -- | `disc://` `disc:///dev/sg4` | Optical drive via SCSI |
+| IsoStream | Yes | Yes | `iso://path.iso` | Blu-ray ISO image |
+| MkvStream | Yes | Yes | `mkv://path` | Matroska container |
+| M2tsStream | Yes | Yes | `m2ts://path` | BD-TS with FMKV metadata header |
+| NetworkStream | Yes (listen) | Yes (connect) | `network://host:port` | TCP with FMKV metadata header |
+| StdioStream | Yes (stdin) | Yes (stdout) | `stdio://` | Raw byte pipe |
+| NullStream | -- | Yes | `null://` | Discard sink (byte counter) |
+
+All URLs require a `scheme://path` format. Bare paths are rejected.
+
 ```rust
-let output = ProgressStream::new(
-    TranscodeStream::new(
-        MkvStream::new(File::create("movie.mkv")?)
-            .title(&disc.titles[0])
-            .max_buffer(50 * 1024 * 1024),
-    )
-        .codec(H265)
-        .quality(22),
-    total_bytes,
-    |pct, speed| eprint!("\r  {}%  {:.1} MB/s", pct, speed),
-);
+// PES pipeline (frame-level)
+let input = libfreemkv::input("disc:///dev/sg4", &opts)?;    // DiscStream
+let input = libfreemkv::input("iso://Dune.iso", &opts)?;     // IsoStream
+let output = libfreemkv::output("mkv://Dune.mkv", &title)?;  // MkvOutputStream
+let output = libfreemkv::output("m2ts://Dune.m2ts", &title)?; // M2tsOutputStream
+let output = libfreemkv::output("network://10.0.0.1:9000", &title)?; // NetworkOutputStream
+let output = libfreemkv::output("null://", &title)?;          // NullOutputStream
 
-disc.rip(&mut session, 0, output, |e| { ... })?;
+// IOStream (byte-level)
+let input = open_input("disc://", &opts)?;                    // DiscStream
+let input = open_input("iso://Dune.iso", &opts)?;             // IsoStream
+let output = open_output("iso://Copy.iso", &meta)?;           // IsoStream (write)
+let output = open_output("mkv://Dune.mkv", &meta)?;           // MkvStream
+let output = open_output("m2ts://Dune.m2ts", &meta)?;         // M2tsStream
+let output = open_output("null://", &meta)?;                  // NullStream
 ```
 
+### FMKV Metadata Header
+
+M2tsStream and NetworkStream embed a JSON metadata header before the BD-TS data:
+
+```
+[8B magic "FMKV\0\0\0\0"][4B JSON length][JSON metadata][padding to 192B boundary][BD-TS data...]
+```
+
+The header carries title name, duration, codec_privates, and full stream layout
+(PIDs, codecs, languages, labels). This allows the receiving end to set up
+demuxing and track metadata without scanning the TS.
+
 ## Events
 
 Lib fires events during operations. App provides a callback. No display, no text.
@@ -107,68 +135,8 @@ pub enum EventKind {
 }
 ```
 
-Events report what happened. App decides what to do. GUI shows a dialog. CLI prints a line. Server logs to file.
-
-## Error Codes
-
-Lib errors are codes, not messages. Like HTTP status codes.
-
-```rust
-pub enum Error {
-    // Drive
-    DriveNotFound,
-    DriveOpenFailed,
-    DriveNotReady,
-    
-    // Unlock
-    UnlockFailed,
-    NoProfile,
-    
-    // AACS
-    AacsNoKeys,
-    AacsCertVerifyFailed,
-    AacsAgidAllocFailed,
-    AacsHandshakeFailed,
-    AacsVidMacFailed,
-    
-    // Disc
-    DiscReadError { sector: u64 },
-    MplsParseError,
-    ClpiParseError,
-    UdfFileNotFound { path: String },
-    
-    // Mux
-    LookaheadOverflow,
-    MuxWriteError,
-    
-    // SCSI
-    ScsiError { sense: u8 },
-}
-```
-
-App maps codes to localized strings. Lib never contains display text.
-
-## Streams the Lib Provides
-
-| Stream | Purpose |
-|--------|---------|
-| MkvStream | BD-TS → MKV (demux + mux) |
-
-CLI provides:
-| Stream | Purpose |
-|--------|---------|
-| ProgressStream | Byte counting + progress callback |
-| Future: TranscodeStream | Re-encode video |
-
-Any `impl Write` works as a stream. Third-party apps create their own.
-
-## MkvStream Internals
-
-LookaheadBuffer (default 5MB, configurable):
-1. Phase 1: buffer incoming data, scan for codec setup (SPS/PPS)
-2. Found it? Write MKV header, flush buffer, switch to streaming
-3. Buffer full? Error — app handles it
-4. Phase 2: parse TS → frames → MKV clusters, direct to output
+Events report what happened. App decides what to do. GUI shows a dialog. CLI
+prints a line. Server logs to file.
 
 ## File Layout
 
@@ -177,27 +145,59 @@ libfreemkv/src/
 ├── lib.rs              Public exports
 ├── error.rs            Error codes (no English)
 ├── event.rs            Event types for callbacks
-├── drive.rs            DriveSession (open, init, read)
-├── disc.rs             Disc (scan, rip, titles)
-├── scsi/               SCSI transport (Linux, macOS)
+├── drive/              Drive (open, init, read with recovery)
+│   ├── mod.rs          Drive struct, init, read, reset, eject
+│   ├── capture.rs      Drive profile capture for contribution
+│   ├── linux.rs        Linux drive discovery
+│   ├── macos.rs        macOS drive discovery
+│   └── windows.rs      Windows drive discovery
+├── disc/               Disc (scan, titles, AACS setup)
+├── scsi/               SCSI transport (Linux SG_IO, macOS IOKit, Windows SPTI)
 ├── platform/           Drive unlock (MT1959 A/B)
-├── aacs/               AACS decryption
-├── udf.rs              UDF filesystem parser
-├── mpls.rs             Playlist parser
-├── clpi.rs             Clip info parser
+├── aacs/               AACS decryption (handshake, keys, keydb, decrypt)
+├── css/                DVD CSS cipher
+├── decrypt.rs          Unified decrypt dispatcher (AACS/CSS/None)
+├── pes.rs              PES frame types, Stream trait
+├── sector.rs           SectorReader trait
+├── udf.rs              UDF 2.50 filesystem parser
+├── mpls.rs             MPLS playlist parser
+├── clpi.rs             CLPI clip info parser
+├── ifo.rs              DVD IFO parser
+├── labels/             BD-J label extraction (5 format parsers)
+├── keydb.rs            KEYDB download, parse, save
+├── identity.rs         DriveId from INQUIRY
+├── profile.rs          Bundled drive profiles
+├── speed.rs            DriveSpeed enum
 ├── mux/
-│   ├── stream.rs       MkvStream (builder pattern, impl Write)
-│   ├── lookahead.rs    LookaheadBuffer (generic, reusable)
-│   ├── ts.rs           BD-TS demuxer
-│   ├── ebml.rs         EBML primitives
-│   ├── mkv.rs          MKV muxer
-│   └── codec/          Frame parsers (H.264, HEVC, VC-1, AC3, DTS, TrueHD, PGS)
+│   ├── mod.rs          IOStream trait, public exports
+│   ├── resolve.rs      URL parser + open_input/open_output + input/output
+│   ├── meta.rs         FMKV header format
+│   ├── disc.rs         DiscStream (optical drive → PES)
+│   ├── iso.rs          IsoStream (ISO image read/write)
+│   ├── isowriter.rs    ISO image writer (UDF, AVDP, multi-extent)
+│   ├── mkvstream.rs    MkvStream (bidirectional Matroska, IOStream)
+│   ├── mkvout.rs       MkvOutputStream (PES → MKV)
+│   ├── m2ts.rs         M2tsStream (BD-TS, IOStream)
+│   ├── pesout.rs       PES output streams (M2ts, Network, Stdio, Null)
+│   ├── network.rs      NetworkStream (TCP + FMKV header)
+│   ├── stdio.rs        StdioStream (stdin/stdout pipe)
+│   ├── null.rs         NullStream (discard + byte counter)
+│   ├── lookahead.rs    LookaheadBuffer (codec header scanning)
+│   ├── ts.rs           BD-TS demuxer + PAT/PMT scanner
+│   ├── tsreader.rs     TS reader utilities
+│   ├── tsmux.rs        TS muxer (PES → BD-TS packets)
+│   ├── ps.rs           MPEG-2 PS demuxer (DVD)
+│   ├── ebml.rs         EBML read/write primitives
+│   ├── mkv.rs          MKV muxer (tracks, clusters, cues)
+│   └── codec/          Frame parsers (H.264, HEVC, MPEG-2, VC-1, AC3, EAC3, DTS, TrueHD, LPCM, PGS)
 └── ...
 
 freemkv/src/
-├── main.rs             CLI entry, command routing
-├── rip.rs              Rip command (streams + progress)
-├── remux.rs            Remux command (m2ts → MKV, no drive)
-├── info.rs             Drive info display
-└── disc_info.rs        Disc info display
+├── main.rs             CLI dispatcher (URL routing)
+├── pipe.rs             PES pipeline — source → dest copy
+├── disc_info.rs        Disc/file info display
+├── info.rs             Drive info + profile submission
+├── strings.rs          i18n string table
+├── output.rs           Verbosity-filtered output
+└── build.rs            Bundled locale code generation
 ```

docs/architecture.md

@@ -13,9 +13,9 @@ AACS keys are derived internally, and all SCSI communication is handled in-proce
 
 1. **CLI is dumb.** All drive communication, disc parsing, AACS decryption, and
    format handling live in the library. CLI binaries are thin wrappers that call
-   `DriveSession::open()` and `Disc::scan()`.
+   `Drive::open()` and `Disc::scan()`.
 
-2. **No external files.** 206 drive profiles are compiled into the binary via
+2. **No external files.** Bundled drive profiles are compiled into the binary via
    `include_str!`. No configuration directory, no runtime file lookups for drive
    support.
 
@@ -23,12 +23,16 @@ AACS keys are derived internally, and all SCSI communication is handled in-proce
    available. Callers read cleartext sectors without knowing whether the disc
    was encrypted.
 
-4. **Structured errors, no English.** Every error has a numeric code (E1000-E7000).
+4. **Structured errors, no English.** Every error has a numeric code (E1000-E8000).
    The library never formats user-facing messages -- applications do that.
 
 5. **Library-agnostic.** No concept of "supported" vs "unsupported" drives at a
    policy level. If a profile exists, the library uses it.
 
+6. **Streams are dumb pipes.** Streams read/write PES frames. They don't know
+   about encryption, transport format, or source type. Decrypt is a stream-internal
+   concern; the pipeline just moves frames.
+
 ---
 
 ## Module Map
@@ -37,26 +41,39 @@ AACS keys are derived internally, and all SCSI communication is handled in-proce
 libfreemkv (lib.rs)
 │
 ├── Drive Access
-│   ├── drive         DriveSession — open, identify, unlock, read
-│   ├── scsi          ScsiTransport trait + SG_IO implementation
+│   ├── drive         Drive — open, identify, init, unlock, read (with recovery)
+│   ├── scsi          ScsiTransport trait + platform backends (sg async, IOKit, SPTI)
 │   ├── platform/     Platform trait — per-chipset command handlers
-│   │   └── mt1959    MediaTek MT1959 driver (LG, ASUS, hp)
+│   │   └── mt1959    MediaTek MT1959 driver (LG, ASUS, HP)
 │   ├── profile       DriveProfile loading, matching, bundled JSON
 │   ├── identity      DriveId from INQUIRY + GET_CONFIG 010C
-│   └── speed         DriveSpeed enum, SET CD SPEED CDB builder
+│   ├── speed         DriveSpeed enum, SET CD SPEED CDB builder
+│   └── event         Event system for drive status callbacks
 │
 ├── Disc Scanning
 │   ├── disc          Disc::scan() — titles, streams, extents, AACS setup
 │   ├── udf           UDF 2.50 filesystem reader (metadata partitions)
 │   ├── mpls          MPLS playlist parser — clips, streams, STN table
 │   ├── clpi          CLPI clip info parser — EP map, sector extents
-│   └── jar           BD-J JAR label extraction (audio/subtitle names)
+│   ├── ifo           DVD IFO parser — title sets, PGC chains, cell addresses
+│   └── labels/       BD-J label extraction (5 formats: Paramount, Criterion, Pixelogic, CTRM, Deluxe)
 │
 ├── Encryption
-│   ├── aacs          KEYDB parsing, VUK lookup, MKB processing, unit decryption
-│   └── aacs_handshake  ECDH bus authentication, Volume ID, Read Data Key
+│   ├── aacs/         AACS handshake, KEYDB, VUK lookup, MKB, unit decryption
+│   ├── css           DVD CSS cipher — table-driven, no external keys needed
+│   └── decrypt       decrypt_sectors() — unified AACS/CSS/None dispatcher
 │
-└── error             Error enum with numeric codes E1000-E7000
+├── Streaming
+│   ├── mux/          Stream implementations (Disc, ISO, MKV, M2TS, Network, Stdio, Null)
+│   ├── pes           PES frame types, Stream trait (read/write frames)
+│   └── sector        SectorReader trait — abstracts disc vs ISO vs file
+│
+├── Support
+│   ├── keydb         KEYDB.cfg download, parse, verify, save
+│   ├── error         Error enum with numeric codes E1000-E8000
+│   └── profile       Bundled drive profiles
+│
+└── lib.rs            Public API re-exports
 ```
 
 ---
@@ -64,27 +81,28 @@ libfreemkv (lib.rs)
 ## Drive Access Flow
 
 ```
-DriveSession::open("/dev/sr0")
+Drive::open(Path::new("/dev/sg4"))
   │
-  ├─ scsi::open()           Open /dev/sr0 via SG_IO
+  ├─ scsi::open()           Open /dev/sg4 (async write/poll/read)
   ├─ DriveId::from_drive()  INQUIRY + GET_CONFIG 010C
-  ├─ profile::find_by_drive_id()  Match against 206 bundled profiles
+  ├─ profile::find_by_drive_id()  Match against bundled profiles
   ├─ Platform::new()        Instantiate chipset driver (Mt1959)
-  └─ Platform::unlock()     Activate raw disc access mode
+  └─ Drive ready for init/unlock/read
 ```
 
-After open, the session provides:
-- `read_sectors(lba, count, buf)` -- raw sector reads (through platform driver)
-- `read_disc(lba, count, buf)` -- standard READ(10) for filesystem data
-- `scsi_execute(cdb, dir, buf, timeout)` -- arbitrary SCSI commands
-- `status()`, `calibrate()`, `read_config()`, `read_register()`
+After open:
+- `init()` -- unlock + firmware upload + speed calibration
+- `probe_disc()` -- probe disc surface for optimal speeds
+- `read(lba, count, buf)` -- single read method with built-in error recovery
+- `wait_ready()` -- wait for disc insertion
+- `eject()` -- eject tray
 
 ---
 
 ## Disc Scanning Flow
 
 ```
-Disc::scan(&mut session, &ScanOptions)
+Disc::scan(&mut drive, &ScanOptions)
   │
   ├─ READ CAPACITY          Get disc size in sectors
   ├─ udf::read_filesystem() Parse UDF 2.50 (AVDP → VDS → metadata → FSD → root)
@@ -92,14 +110,24 @@ Disc::scan(&mut session, &ScanOptions)
   │   ├─ mpls::parse()      Extract play items, STN streams
   │   └─ For each clip:
   │       └─ clpi::parse()  EP map → sector extents for the clip's time range
+  ├─ labels::detect()       Parse BD-J JARs for stream labels
   ├─ Detect AACS            Check for /AACS directory on disc
   └─ Disc::setup_aacs()     Handshake + KEYDB → VUK → unit keys (if encrypted)
 ```
 
+For DVD:
+```
+Disc::scan_dvd(&mut drive, &ScanOptions)
+  │
+  ├─ ifo::parse()           Parse VIDEO_TS.IFO — title sets, PGC chains
+  ├─ CSS detection          Check disc structure flag
+  └─ CSS key cracking       Table-driven, no KEYDB needed
+```
+
 The result is a `Disc` with:
-- `titles: Vec<Title>` -- sorted by duration, each with streams and sector extents
-- `aacs: Option<AacsState>` -- decryption keys if available
-- `encrypted: bool` -- whether the disc uses AACS
+- `titles: Vec<DiscTitle>` -- sorted by duration, each with streams, sector extents, codec_privates
+- `decrypt_keys()` -- DecryptKeys for content decryption
+- `encrypted: bool` -- whether the disc uses AACS/CSS
 
 ---
 
@@ -114,13 +142,14 @@ Four key resolution paths, tried in order:
 | 3 | Processing Keys + MKB → Media Key → VUK | Medium |
 | 4 | Device Keys + MKB subset-difference tree → VUK | Slow |
 
-The AACS handshake (`aacs_handshake`) performs ECDH key agreement over the
+The AACS handshake (`aacs/handshake`) performs ECDH key agreement over the
 AACS 1.0 160-bit elliptic curve to obtain:
 - **Volume ID** -- needed for VUK derivation (paths 2-4)
 - **Read Data Key** -- needed for AACS 2.0 (UHD) bus decryption
 
 Content decryption uses AES-128-CBC on 6144-byte aligned units. The
-`ContentReader` handles this transparently.
+`ContentReader` handles this transparently. Streams that read sectors
+(DiscStream, IsoStream) decrypt internally — the pipeline sees clean bytes.
 
 ---
 
@@ -138,6 +167,7 @@ is baked into the library.
 | E5xxx | I/O errors | `IoError` (wraps `std::io::Error`) |
 | E6xxx | Disc format errors | `DiscError` (UDF, MPLS, CLPI parse failures) |
 | E7xxx | AACS errors | `AacsError` (key resolution, handshake, decryption) |
+| E8xxx | KEYDB errors | `KeydbError` (download, parse, save) |
 
 ---
 
@@ -145,9 +175,9 @@ is baked into the library.
 
 | Platform | Transport | Status |
 |----------|-----------|--------|
-| Linux | SG_IO ioctl on `/dev/sr*` | Implemented |
-| macOS | IOKit SCSI passthrough | Planned |
-| Windows | SPTI (`IOCTL_SCSI_PASS_THROUGH_DIRECT`) | Planned |
+| Linux | async sg write/poll/read on `/dev/sg*` | Supported |
+| macOS | IOKit SCSITask | Supported |
+| Windows | SPTI (`IOCTL_SCSI_PASS_THROUGH_DIRECT`) | Supported |
 
 The `ScsiTransport` trait abstracts the platform. Adding a new platform requires
 implementing `execute()` for that OS and wiring it into `scsi::open()`.
@@ -158,11 +188,11 @@ implementing `execute()` for that OS and wiring it into `scsi::open()`.
 
 | Chipset | Drives | Status |
 |---------|--------|--------|
-| MediaTek MT1959 | LG, ASUS, hp | Implemented (206 profiles) |
+| MediaTek MT1959 | LG, ASUS, HP | Supported (bundled profiles) |
 | Renesas RS8xxx/RS9xxx | Pioneer, some HL-DT-ST | Planned |
 
 The `Platform` trait abstracts chipset-specific commands. Each chipset implements
-10 handlers (unlock, config, register, calibrate, keepalive, status, probe,
+handlers (unlock, config, register, calibrate, keepalive, status, probe,
 read_sectors, timing). All handlers are accessed via SCSI READ BUFFER with
 chipset-specific mode and buffer ID bytes.
 
@@ -174,7 +204,5 @@ chipset-specific mode and buffer ID bytes.
 cargo build --release
 ```
 
-Linux builds produce a static library and two binaries (`freemkv-info`,
-`freemkv-test`). The `libc` dependency is Linux-only. On non-Linux platforms,
-the library compiles but `scsi::open()` returns a platform-not-supported error
-until the IOKit/SPTI backends are implemented.
+Produces a Rust library crate. The `libc` dependency is unix-only (gated).
+All three platforms build and pass CI.

docs/disc-to-rip.md

@@ -9,12 +9,18 @@ This is the starting point for understanding the library.
 Insert disc
     │
     ▼
-1. Open drive (drive.rs)
+1. Open drive (drive/mod.rs)
     │  INQUIRY → identify drive
     │  Match bundled profile → chipset, unlock parameters
     │
     ▼
-2. AACS handshake (aacs_handshake.rs) — optional, separate transport
+2. Init drive (drive/mod.rs → platform/mt1959)
+    │  Firmware upload (if needed, 10s recovery wait)
+    │  Unlock → vendor-specific command activates raw read mode
+    │  Speed calibration → probe_disc()
+    │
+    ▼
+3. AACS handshake (aacs/handshake.rs) — optional
     │  Allocate AGID
     │  Exchange certificates + nonces (ECDH)
     │  Derive bus key
@@ -22,11 +28,6 @@ Insert disc
     │  (fails gracefully if drive doesn't support AACS for this disc)
     │
     ▼
-3. Unlock drive (drive.rs → platform/mt1959.rs)
-    │  Vendor-specific command activates raw read mode
-    │  Required — drive firmware blocks all reads without it
-    │
-    ▼
 4. Read UDF filesystem (udf.rs)
     │  Sector 256: AVDP → find Volume Descriptor Sequence
     │  VDS: Partition Descriptor (physical start) + Logical Volume (metadata start)
@@ -35,80 +36,94 @@ Insert disc
     │  → docs/udf.md
     │
     ▼
-5. Read AACS files from disc (aacs.rs)
+5. Read AACS files from disc (aacs/mod.rs)
     │  AACS/Unit_Key_RO.inf → SHA1 = disc hash
     │  AACS/Content000.cer → AACS version (1.0 or 2.0), bus encryption flag
     │  MKB via SCSI → for key derivation fallback
     │
     ▼
-6. Resolve AACS keys (aacs.rs → resolve_keys)
-    │  Path 1: disc hash → KEYDB.cfg → VUK (fast, 99% of discs)
-    │  Path 2: KEYDB media key + Volume ID → VUK
-    │  Path 3: MKB + processing keys → media key → VUK
-    │  Path 4: MKB + device keys → subset-difference tree → VUK
-    │  VUK → decrypt unit keys from Unit_Key_RO.inf
+6. Resolve encryption keys (decrypt.rs → resolve_encryption)
+    │  BD AACS:
+    │    Path 1: disc hash → KEYDB.cfg → VUK (fast, 99% of discs)
+    │    Path 2: KEYDB media key + Volume ID → VUK
+    │    Path 3: MKB + processing keys → media key → VUK
+    │    Path 4: MKB + device keys → subset-difference tree → VUK
+    │    VUK → decrypt unit keys from Unit_Key_RO.inf
+    │  DVD CSS:
+    │    Table-driven cipher — no KEYDB needed
     │  → docs/aacs.md
     │
     ▼
-7. Parse playlists (mpls.rs)
+7. Parse playlists (mpls.rs) — BD/UHD only
     │  BDMV/PLAYLIST/*.mpls → titles with play items
     │  Each play item: clip ID, in/out timestamps
     │  STN table: video, audio, subtitle streams with codec + language
     │  → docs/mpls.md
     │
     ▼
-8. Parse clip info (clpi.rs)
+8. Parse clip info (clpi.rs) — BD/UHD only
     │  BDMV/CLIPINF/*.clpi → EP map (timestamp → sector mapping)
     │  Coarse + fine entries → full PTS and SPN
     │  SPN → byte offset → sector extents for reading
     │  → docs/clpi.md
     │
     ▼
-9. Parse BD-J labels (jar.rs) — optional
+9. Parse BD-J labels (labels/) — optional
     │  BDMV/JAR/*.jar → Java class constant pool strings
+    │  5 format parsers: Paramount, Criterion, Pixelogic, CTRM, Deluxe
     │  Audio track labels: "English Descriptive Audio", "French 5.1", etc.
     │
     ▼
-10. Read + decrypt content (disc.rs → ContentReader)
-     │  For each aligned unit (6144 bytes = 3 sectors):
-     │    Read 3 sectors from disc
-     │    If AACS 2.0: bus decrypt (read_data_key, per-sector AES-CBC)
-     │    If encrypted: unit decrypt (per-unit key derivation + AES-CBC)
-     │    Output decrypted content
+10. Stream content (mux/disc.rs → DiscStream)
+     │  Read sectors → decrypt → TS demux → PES frames
+     │  Or: read sectors → decrypt → raw bytes (for ISO output)
+     │  Drive::read() handles error recovery (min speed → reset → retry)
      │
      ▼
-  Decrypted m2ts stream → ready for muxing/backup
+  PES frames → output stream (MKV, M2TS, network, etc.)
 ```
 
 ## API Summary
 
 ```rust
-// Steps 1 + 3 (open + unlock)
-let mut session = DriveSession::open(Path::new("/dev/sr0"))?;
+// Open + init drive
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
+drive.wait_ready()?;
+drive.init()?;
+drive.probe_disc()?;
 
-// Steps 2 + 4-9 (AACS + scan)
-let disc = Disc::scan(&mut session, &ScanOptions::with_keydb("keydb.cfg"))?;
+// Scan disc (UDF + playlists + AACS — all automatic)
+let disc = Disc::scan(&mut drive, &ScanOptions::default())?;
 
-// Step 10 (read + decrypt)
-let mut reader = disc.open_title(&mut session, 0)?;
-while let Some(unit) = reader.read_unit()? {
-    output.write_all(&unit)?;
+// Stream pipeline — PES frames from any source to any output
+let opts = InputOptions::default();
+let mut input = libfreemkv::input("disc:///dev/sg4", &opts)?;
+let title = input.info().clone();
+let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
+while let Ok(Some(frame)) = input.read() {
+    output.write(&frame)?;
 }
+output.finish()?;
 ```
 
-Three lines. Everything else is internal.
-
 ## Module Reference
 
 | Module | Doc | Purpose |
 |--------|-----|---------|
-| drive.rs | [drive-access.md](drive-access.md) | Open, identify, unlock, read |
-| scsi.rs | [drive-access.md](drive-access.md) | Platform SCSI transport |
+| drive/ | [drive-access.md](drive-access.md) | Open, identify, init, unlock, read (with recovery) |
+| scsi/ | [drive-access.md](drive-access.md) | Platform SCSI transport (Linux, macOS, Windows) |
 | udf.rs | [udf.md](udf.md) | UDF 2.50 filesystem |
 | mpls.rs | [mpls.md](mpls.md) | MPLS playlists + STN streams |
 | clpi.rs | [clpi.md](clpi.md) | CLPI clip info + EP map |
-| aacs.rs | [aacs.md](aacs.md) | Key resolution + content decrypt |
-| aacs_handshake.rs | [aacs.md](aacs.md) | SCSI bus authentication |
-| disc.rs | -- | High-level scan + read API |
-| jar.rs | -- | BD-J audio track labels |
-| error.rs | -- | Error codes (E1xxx-E7xxx) |
+| ifo.rs | -- | DVD IFO parser |
+| aacs/ | [aacs.md](aacs.md) | Key resolution + content decrypt + bus handshake |
+| css/ | -- | DVD CSS cipher |
+| decrypt.rs | -- | Unified decrypt dispatcher (AACS/CSS/None) |
+| disc/ | -- | High-level scan + read API |
+| labels/ | -- | BD-J stream labels (5 format parsers) |
+| mux/ | -- | Stream implementations (7 stream types) |
+| pes.rs | -- | PES frame types + Stream trait |
+| sector.rs | -- | SectorReader trait |
+| keydb.rs | -- | KEYDB download, parse, save |
+| error.rs | -- | Error codes (E1xxx-E8xxx) |
+| event.rs | -- | Drive event system |

docs/drive-access.md

@@ -5,51 +5,61 @@ optical drives.
 
 ---
 
-## DriveSession
+## Drive
 
-`DriveSession` is the primary API. It owns the SCSI transport, the matched
+`Drive` is the primary API. It owns the SCSI transport, the matched
 drive profile, and the chipset-specific platform driver.
 
 ### Opening a Drive
 
 ```rust
-// Full open: identify → match profile → unlock
-let mut session = DriveSession::open(Path::new("/dev/sr0"))?;
-
-// No-unlock open: identify → match profile only
-let mut session = DriveSession::open_no_unlock(Path::new("/dev/sr0"))?;
-
-// Explicit profile (skip auto-detection)
-let mut session = DriveSession::open_with_profile(Path::new("/dev/sr0"), profile)?;
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
 ```
 
-**`open()`** performs the full sequence: open device, send INQUIRY, match
-profile, instantiate platform driver, and unlock. Unlock failures are silently
-ignored (unencrypted discs do not need it). After `open()`, both raw sector
-reads and standard READ(10) work immediately.
+`open()` performs: open device → send INQUIRY → match profile → instantiate
+platform driver. The drive is ready for `wait_ready()` and `init()`.
 
-**`open_no_unlock()`** skips the unlock step. This is required when AACS bus
-authentication must happen before unlock. The handshake uses standard SCSI
-commands that work without raw mode. After authentication completes, the caller
-can invoke `session.unlock()` manually.
-
-**`open_with_profile()`** bypasses profile auto-detection. Useful for testing
-or when a custom profile is loaded from an external source.
-
-### Session Operations
+### Drive Operations
 
 | Method | Description |
 |--------|-------------|
-| `unlock()` | Activate raw disc access mode via platform driver |
-| `is_unlocked()` | Check if raw mode is active |
-| `calibrate()` | Build speed lookup table for the current disc |
-| `read_sectors(lba, count, buf)` | Raw sector read (requires unlock + calibrate) |
-| `read_disc(lba, count, buf)` | Standard READ(10) with 5s timeout |
-| `status()` | Query drive status and feature flags |
-| `read_config()` | Read drive configuration block (1888 bytes) |
-| `read_register(index)` | Read 16-byte hardware register |
-| `probe(sub_cmd, addr, len)` | Generic READ BUFFER with caller parameters |
-| `scsi_execute(cdb, dir, buf, timeout)` | Send an arbitrary SCSI CDB |
+| `wait_ready()` | Wait for disc insertion (30s timeout, TUR polling) |
+| `init()` | Firmware upload + unlock + speed calibration |
+| `probe_disc()` | Probe disc surface for optimal speeds |
+| `read(lba, count, buf)` | Read sectors with built-in error recovery |
+| `reset()` | Close/reopen device, TUR, escalate if needed |
+| `lock_tray()` | Prevent tray ejection during rip |
+| `unlock_tray()` | Allow tray ejection (also runs on Drop) |
+| `eject()` | Eject disc tray |
+| `drive_status()` | Query physical state (disc present, tray open, etc.) |
+| `has_profile()` | Whether a bundled profile matched |
+| `close()` | Consume Drive, cleanup (also runs via Drop) |
+
+### init() Sequence
+
+`init()` orchestrates the full drive unlock:
+
+1. Platform driver `run_init()` — sends vendor-specific SCSI commands
+2. If firmware upload needed: upload, wait 10s for drive reset, retry
+3. Speed calibration after unlock
+4. Max 3 attempts before giving up
+
+### read() with Recovery
+
+`Drive::read(lba, count, buf, recovery)` is the single read method. The
+`recovery` parameter controls whether to attempt multi-phase recovery on
+failure or return immediately (used by DiscStream's binary search for
+single-sector probes).
+
+On error with `recovery = true`:
+
+1. **Phase 1 — gentle retry (5 attempts):** set min speed, sleep 30s, retry.
+   Each retry has a hard wall-clock timeout via async SG_IO.
+2. **Phase 2 — fresh start:** close transport, reset device, reopen, reinit.
+3. **Phase 3 — gentle retry on fresh connection (5 attempts).**
+4. If all fail: return `Err(DiscRead)`. DiscStream handles it (binary search,
+   skip, zero-fill).
+5. Stay at min speed for 500 MB after any recovery (recovery window).
 
 ---
 
@@ -58,7 +68,7 @@ or when a custom profile is loaded from an external source.
 ### Trait
 
 ```rust
-pub trait ScsiTransport {
+pub trait ScsiTransport: Send {
     fn execute(
         &mut self,
         cdb: &[u8],
@@ -72,17 +82,22 @@ pub trait ScsiTransport {
 All drive communication goes through this trait. The library never opens file
 descriptors or calls ioctls outside of a `ScsiTransport` implementation.
 
-### Linux: SG_IO
+### Platform Backends
 
-The `SgIoTransport` implementation:
+| Platform | Implementation | Device |
+|----------|---------------|--------|
+| Linux | `SgIoTransport` — async `write`/`poll`/`read` on `/dev/sg*` | `/dev/sg*` |
+| macOS | `MacScsiTransport` — IOKit SCSITask | IOKit service |
+| Windows | `WindowsScsiTransport` — SPTI | `\\.\CdRomN` |
 
-1. Opens the device path with `O_RDWR | O_NONBLOCK`.
-2. Constructs an `sg_io_hdr` struct with the CDB, data buffer, and timeout.
-3. Calls `ioctl(fd, SG_IO, &hdr)`.
-4. Returns `ScsiResult` with status, bytes transferred, and sense data.
+The Linux backend uses the sg driver's asynchronous interface: `write()` submits
+the command, `poll()` waits with an enforceable wall-clock timeout, `read()`
+retrieves the result. If `poll()` times out, the fd is abandoned (closed in a
+background thread) and a fresh fd opened — the kernel's USB error recovery
+cannot block us. Opens with `O_RDWR | O_NONBLOCK`.
 
-On non-zero SCSI status, the transport parses sense key, ASC, and ASCQ from the
-sense buffer and returns `Error::ScsiError`.
+On non-zero SCSI status, the transport parses sense key from the sense buffer
+and returns `Error::ScsiError`.
 
 ### CDB Builders
 
@@ -119,8 +134,8 @@ date for drives where Feature 010C is unavailable.
 
 ## Drive Profiles
 
-Profiles are JSON objects compiled into the binary (`profiles.json`,
-206 entries). Each profile contains:
+Profiles are JSON objects compiled into the binary (`profiles.json`).
+Each profile contains:
 
 | Field | Purpose |
 |-------|---------|
@@ -148,7 +163,7 @@ let profiles = profile::load_all(Path::new("/path/to/profiles.json"))?;
 
 ### MediaTek MT1959
 
-Covers all LG, ASUS, and hp optical drives. Two sub-variants share identical
+Covers all LG, ASUS, and HP optical drives. Two sub-variants share identical
 logic with different SCSI parameters:
 
 | Variant | READ BUFFER mode | Buffer ID |
@@ -156,7 +171,7 @@ logic with different SCSI parameters:
 | MT1959-A | 0x01 | 0x44 |
 | MT1959-B | 0x02 | 0x77 |
 
-The Platform trait maps to 10 command handlers:
+The Platform trait maps to command handlers:
 
 | Handler | Function | Description |
 |---------|----------|-------------|
@@ -183,64 +198,32 @@ Optical drive firmware restricts what applications can read from disc. Without
 unlock:
 
 - **READ(10) works for unencrypted filesystem data.** UDF structures, MPLS
-  playlists, and CLPI clip info are readable without unlock. The `read_disc()`
-  method uses standard READ(10) and works on any drive.
+  playlists, and CLPI clip info are readable without unlock. Standard READ(10)
+  works on any drive.
 
 - **READ(10) fails for encrypted content sectors.** The drive firmware returns
   SCSI errors (sense key 0x05, illegal request) when an application attempts to
   read sectors containing encrypted m2ts content without prior AACS
   authentication via the bus key.
 
-- **The kernel sr driver blocks block-device reads.** On Linux, the kernel's
-  SCSI CD-ROM driver (`sr`) refuses to expose encrypted disc content through
-  `/dev/sr0` as a block device. Even if you open the block device directly,
-  reads to encrypted regions fail.
-
 - **Raw mode bypasses firmware restrictions.** After unlock, the drive accepts
   READ(10) with the raw read flag (CDB byte 1 = 0x08) for all sectors,
-  regardless of encryption status. This is how raw sector ripping works.
+  regardless of encryption status.
 
-### open() vs open_no_unlock()
+### AACS Before Unlock
 
 AACS bus authentication uses standard MMC REPORT KEY / SEND KEY commands.
-These must execute before unlock because:
-
-1. The AACS handshake establishes a bus key via ECDH.
-2. The bus key encrypts the Volume ID and Read Data Key responses.
-3. The Volume ID is needed to derive the Volume Unique Key (VUK).
-4. The VUK is needed to decrypt unit keys from `Unit_Key_RO.inf`.
-
-If `open()` unlocks first, some drives reject the subsequent AACS commands.
-The correct sequence for encrypted discs is:
-
-```rust
-// 1. Open without unlock
-let mut session = DriveSession::open_no_unlock(device)?;
-
-// 2. AACS handshake (uses standard SCSI, no unlock needed)
-let auth = aacs_handshake::aacs_authenticate(&mut session, &key, &cert)?;
-let vid = aacs_handshake::read_volume_id(&mut session, &mut auth)?;
-
-// 3. Now unlock for raw reads
-session.unlock()?;
-session.calibrate()?;
-
-// 4. Read and decrypt content
-session.read_sectors(lba, count, &mut buf)?;
-```
-
-In practice, `Disc::scan()` handles this internally. The default `open()` call
-unlocks immediately and is correct for most use cases -- the scan re-opens a
-second session with `open_no_unlock()` for the AACS handshake when needed.
+On some drives these must execute before unlock. The `Disc::scan()` handles
+this internally — it manages the handshake/unlock ordering automatically.
 
 ---
 
 ## Speed Control
 
-After `calibrate()`, the platform driver maintains a 64-entry speed lookup table
-built by probing the disc surface. On each `read_sectors()` call, the driver:
+After `probe_disc()`, the platform driver maintains a speed lookup table
+built by probing the disc surface. On each `read()` call, the driver:
 
-1. Looks up the optimal speed for the target LBA in the table.
+1. Looks up the optimal speed for the target LBA.
 2. Issues SET CD SPEED (0xBB) if the speed differs from current.
 3. Performs the READ(10).
 

docs/mkv-muxer-plan.md

@@ -1,240 +0,0 @@
-# MKV Native Muxer — Architecture
-
-## Goal
-
-Replace raw m2ts output with in-pipeline MKV muxing.
-Disc → TS demux → MKV mux → .mkv file. One pass, no temp files.
-
-## Data Flow
-
-```
-ContentReader::read_batch()        returns &[u8] of raw BD transport stream
-        ↓
-TsDemuxer::feed(batch)             parses 192-byte BD-TS packets, extracts PES
-        ↓
-PES reassembly per PID             builds complete PES packets with PTS/DTS
-        ↓
-ElementaryStreamParser per track   finds frame boundaries, extracts codec headers
-        ↓
-MkvMuxer::write_frame(track, pts, data)   writes EBML clusters + blocks
-        ↓
-.mkv file on disk
-```
-
-## Current Integration Point
-
-```rust
-// rip.rs line ~287
-match reader.read_batch() {
-    Ok(Some(batch)) => {
-        writer.write_all(batch)?;  // ← replace with muxer.feed(batch)
-    }
-}
-```
-
-Becomes:
-```rust
-match reader.read_batch() {
-    Ok(Some(batch)) => {
-        muxer.feed(batch)?;
-    }
-}
-```
-
-## Components
-
-### 1. BD Transport Stream Demuxer (`ts.rs`)
-
-BD uses 192-byte packets (not standard 188):
-```
-[0-3]   TP_extra_header: 2-bit copy_permission + 30-bit arrival_time_stamp
-[4]     Sync byte: 0x47
-[5]     TEI + PUSI + priority + PID[12:8]
-[6]     PID[7:0]
-[7]     Scrambling + adaptation + continuity_counter
-[8..]   Adaptation field (if present) + payload
-```
-
-API:
-```rust
-pub struct TsDemuxer {
-    pes_assemblers: HashMap<u16, PesAssembler>,  // PID → assembler
-}
-
-impl TsDemuxer {
-    pub fn new(pids: &[u16]) -> Self;
-    pub fn feed(&mut self, data: &[u8]) -> Vec<PesPacket>;
-}
-
-pub struct PesPacket {
-    pub pid: u16,
-    pub pts: Option<i64>,   // 90kHz ticks
-    pub dts: Option<i64>,   // 90kHz ticks
-    pub data: Vec<u8>,      // elementary stream data
-}
-```
-
-### 2. Elementary Stream Parsers (`codec/`)
-
-Each codec parser finds frame boundaries and extracts initialization data.
-
-**H.264 (`codec/h264.rs`):**
-- Parse NAL units (start code 00 00 01 or 00 00 00 01)
-- Extract SPS + PPS for codecPrivate
-- Frame boundary = Access Unit Delimiter (NAL type 9) or SPS
-
-**HEVC (`codec/hevc.rs`):**
-- Parse NAL units
-- Extract VPS + SPS + PPS for codecPrivate
-- Frame boundary = VCL NAL with first_slice_segment_in_pic_flag
-
-**AC3/EAC3 (`codec/ac3.rs`):**
-- Syncword 0x0B77
-- Parse frame size from header
-- No codecPrivate needed (or minimal)
-
-**DTS (`codec/dts.rs`):**
-- Syncword 0x7FFE8001
-- Parse frame size
-- No codecPrivate needed
-
-**TrueHD (`codec/truehd.rs`):**
-- Major sync: 0xF8726FBA
-- Access unit = major sync + minor syncs
-- AC3 core embedded in first substream
-
-**LPCM (`codec/lpcm.rs`):**
-- Fixed frame sizes based on sample rate + channels
-- Header describes format
-
-**PGS (`codec/pgs.rs`):**
-- Segment types: PCS, WDS, PDS, ODS, END
-- Each segment is a complete unit
-- No codecPrivate needed
-
-### 3. MKV/EBML Muxer (`mkv.rs`)
-
-Matroska uses EBML (Extensible Binary Meta Language).
-
-**EBML primitives:**
-- Variable-length element ID (1-4 bytes)
-- Variable-length size (1-8 bytes)
-- Data: uint, int, float, string, UTF-8, binary, date
-
-**MKV structure:**
-```
-EBML Header
-Segment
-├── SeekHead (index of top-level elements)
-├── Info (title, duration, muxing app)
-├── Tracks (one entry per stream)
-│   ├── TrackEntry (video)
-│   │   ├── CodecID: "V_MPEG4/ISO/AVC" or "V_MPEGH/ISO/HEVC"
-│   │   ├── CodecPrivate: SPS+PPS (H.264) or VPS+SPS+PPS (HEVC)
-│   │   └── Video: PixelWidth, PixelHeight, DisplayWidth, DisplayHeight
-│   ├── TrackEntry (audio)
-│   │   ├── CodecID: "A_AC3" or "A_TRUEHD" or "A_DTS"
-│   │   └── Audio: SamplingFrequency, Channels, BitDepth
-│   └── TrackEntry (subtitle)
-│       └── CodecID: "S_HDMV/PGS"
-├── Chapters (optional, from MPLS chapter marks)
-├── Cluster (every ~5 seconds)
-│   ├── Timestamp (cluster base time)
-│   ├── SimpleBlock (track, relative_ts, data)
-│   ├── SimpleBlock ...
-│   └── ...
-├── Cluster ...
-├── Cues (seek index, written at end)
-└── Tags (metadata)
-```
-
-**API:**
-```rust
-pub struct MkvMuxer<W: Write + Seek> {
-    writer: W,
-    tracks: Vec<MkvTrack>,
-    cluster_start: Option<i64>,
-    cue_points: Vec<CuePoint>,
-}
-
-impl<W: Write + Seek> MkvMuxer<W> {
-    pub fn new(writer: W, tracks: &[MkvTrack]) -> Result<Self>;
-    pub fn write_frame(&mut self, track_idx: usize, pts_ns: i64, keyframe: bool, data: &[u8]) -> Result<()>;
-    pub fn finish(self) -> Result<()>;  // writes Cues + fixes SeekHead
-}
-```
-
-### 4. Pipeline Glue (`mux.rs`)
-
-Ties everything together:
-
-```rust
-pub struct MuxPipeline<W: Write + Seek> {
-    demuxer: TsDemuxer,
-    parsers: HashMap<u16, Box<dyn CodecParser>>,
-    muxer: MkvMuxer<W>,
-    pid_to_track: HashMap<u16, usize>,
-}
-
-impl<W: Write + Seek> MuxPipeline<W> {
-    pub fn new(writer: W, streams: &[Stream]) -> Result<Self>;
-    pub fn feed(&mut self, ts_data: &[u8]) -> Result<()>;
-    pub fn finish(self) -> Result<()>;
-}
-```
-
-## File Layout
-
-```
-libfreemkv/src/
-├── mux/
-│   ├── mod.rs          MuxPipeline (glue)
-│   ├── ts.rs           BD-TS demuxer (192-byte packets)
-│   ├── ebml.rs         EBML primitives (write variable-length ints)
-│   ├── mkv.rs          MKV muxer (Segment, Tracks, Clusters)
-│   └── codec/
-│       ├── mod.rs      CodecParser trait
-│       ├── h264.rs     H.264 NAL parser
-│       ├── hevc.rs     HEVC NAL parser
-│       ├── ac3.rs      AC3/EAC3 frame parser
-│       ├── dts.rs      DTS frame parser
-│       ├── truehd.rs   TrueHD/Atmos parser
-│       ├── lpcm.rs     LPCM frame parser
-│       └── pgs.rs      PGS subtitle parser
-```
-
-## MKV Codec IDs
-
-| Our Codec | MKV CodecID | codecPrivate |
-|-----------|------------|--------------|
-| H264 | V_MPEG4/ISO/AVC | AVCDecoderConfigurationRecord (SPS+PPS) |
-| Hevc | V_MPEGH/ISO/HEVC | HEVCDecoderConfigurationRecord (VPS+SPS+PPS) |
-| Vc1 | V_MS/VFW/FOURCC | BITMAPINFOHEADER |
-| Mpeg2 | V_MPEG2 | sequence_header |
-| Ac3 | A_AC3 | none |
-| Ac3Plus | A_EAC3 | none |
-| TrueHd | A_TRUEHD | none |
-| DtsHdMa | A_DTS | none (core + extension) |
-| Dts | A_DTS | none |
-| Lpcm | A_PCM/INT/BIG | none |
-| Pgs | S_HDMV/PGS | none |
-
-## Timestamps
-
-BD uses 90kHz PTS/DTS. MKV uses nanoseconds.
-Conversion: `ns = pts * 1_000_000_000 / 90_000` = `pts * 100_000 / 9`
-
-MKV TimestampScale default = 1,000,000 (1ms precision).
-For BD content, 1ms is sufficient.
-
-## Build Order
-
-1. `ebml.rs` — EBML write primitives (smallest, no dependencies)
-2. `ts.rs` — BD-TS demuxer (parse 192-byte packets, PES assembly)
-3. `codec/ac3.rs` — simplest codec parser (fixed syncword)
-4. `mkv.rs` — MKV muxer (header, tracks, clusters, blocks)
-5. `mux.rs` — pipeline glue
-6. Test with AC3-only stream (simplest case)
-7. `codec/h264.rs` — video parser (NAL units, SPS/PPS)
-8. Full BD rip test (video + audio + subs)
-9. Remaining codecs (HEVC, DTS, TrueHD, PGS, LPCM, VC-1)

docs/rip-recovery.md

@@ -0,0 +1,127 @@
+# Rip recovery — multi-pass architecture
+
+`libfreemkv` supports a two-stage rip model for damaged or protection-bearing
+discs: a fast forward sweep that tolerates read failures, followed by targeted
+retry passes against a persistent bad-range map. The stream pipeline
+(`DiscStream` + `input`/`output`) operates against the resulting ISO image, so
+the mux stage never touches the drive.
+
+Three primitives compose the flow:
+
+| Primitive                 | What it does                                                          |
+|---------------------------|-----------------------------------------------------------------------|
+| `Disc::copy`              | disc → ISO. Writes a sidecar `.mapfile`. Opt-in skip-forward on failure. |
+| `Disc::patch`             | Re-reads bad ranges from the drive. Idempotent; call N times.         |
+| `DiscStream` (ISO source) | Reads sectors from the ISO, feeds decrypt → demux → codec → mux.      |
+
+The caller orchestrates. Autorip's `rip_disc` loops `copy` then N × `patch` per
+the `MAX_RETRIES` config, then hands the ISO off to the existing mux pipeline.
+
+## Data model
+
+### Mapfile
+
+Format: [ddrescue](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)-compatible
+plain text, greppable, tool-interoperable. Flushed to disk on every `record()`
+so a crashed rip loses at most one block.
+
+```
+# Rescue Logfile. Created by libfreemkv v0.11.22
+# Current pos / status / pass / pass_time
+0x000000000  ?  1  0
+#      pos        size  status
+0x000000000  0x12a35d000    +
+0x12a35d000  0x000003000    -
+0x12a360000  0x009c4a000    +
+0x12d00a000  0x000064000    *
+```
+
+Status characters match ddrescue:
+
+| Char | Meaning                                            |
+|------|----------------------------------------------------|
+| `?`  | Not yet attempted                                  |
+| `*`  | Fast-pass failed; needs edge-trim                  |
+| `/`  | Trimmed; interior needs sector scrape              |
+| `-`  | Unreadable this session                            |
+| `+`  | Finished (good)                                    |
+
+Position and size are hex byte offsets into the ISO.
+
+### `CopyOptions` and `PatchOptions`
+
+Defaults preserve pre-`0.11.21` behavior — full drive recovery on every read,
+abort on the first unreadable sector. Opt in to the recovery-friendly path:
+
+```rust
+CopyOptions {
+    skip_on_error: true,   // zero-fill bad blocks, continue
+    skip_forward: true,    // exponential skip-forward after a failure
+    resume: true,          // pick up from an existing ISO + mapfile
+    decrypt: false,        // keep the ISO a raw disc image
+    ..Default::default()
+}
+```
+
+## Algorithm
+
+### Pass 1 — fast sweep
+
+1. Read 64 KB (32 sectors, one BD ECC block) at the current LBA.
+2. On success: mark the range `+`, advance by one block.
+3. On failure (with `skip_on_error`): zero-fill the block in the ISO, mark
+   it `*`, advance.
+4. If `skip_forward` is set: after a failure, jump ahead by an exponentially
+   growing amount (256 KB initial, doubling on consecutive failures, capped at
+   1% of disc). The skipped bytes are also marked `*` — `patch` will visit
+   them later.
+5. Reset the skip size to 256 KB on the first success after a failure.
+
+Pass 1 completes when every byte has terminal status (`+`, `-`, or the caller
+bails via the halt flag).
+
+### Pass 2+ — patch
+
+`Disc::patch` reads the mapfile and iterates every non-`+` range. For each:
+
+1. Issue a drive read with full recovery enabled (SCSI-level retries,
+   ECC recovery, the lot).
+2. On success: write the good bytes into the ISO at the exact byte offset,
+   mark `+`.
+3. On failure: mark `-`.
+4. Update the mapfile after every block — crash-safe resume.
+
+Idempotent. Call `patch` N times for N retry attempts; typically the caller
+stops early if a pass recovers zero bytes (structure-protected sectors will
+never yield).
+
+## Design choices
+
+**No `MODE SELECT` to disable drive retries.** Research showed neither ddrescue
+nor MakeMKV does this. Drive firmware has access to raw analog signal, laser
+power control, and drive-specific ECC tuning that userspace can't replicate —
+disabling it throws away recovery headroom on marginal sectors. We fail fast
+via short SG_IO timeouts instead, and we avoid per-sector probing on first
+contact by using large blocks + skip-forward.
+
+**ISO intermediate, even for single-pass.** Pass 1 always writes an ISO. The
+mux stage reads the ISO via `IsoSectorReader`. For single-pass (no retries),
+this adds ~2-3 min (local disk mux) but gains resumability across crashes,
+re-muxability without re-ripping, and a persistent forensic artifact. Callers
+who need pure speed can bypass and use `DiscStream::new(Box::new(drive), …)`
+directly — the lib doesn't forbid it.
+
+**Mapfile in ddrescue format.** Plain text so users can `less` it, `diff` it,
+or feed it to ddrescue's own tooling. Crash-safe (flush-per-record). Entries
+coalesce on adjacent same-status ranges so files stay small.
+
+**Patches target `-`, `*`, `/`, and `?` alike.** The status state machine is
+ddrescue's but `patch` collapses the distinction — it just tries every
+non-finished range with full recovery. Future work can specialize (trim vs.
+scrape vs. retry with direction reversal) if there's measured benefit.
+
+## References
+
+- [ddrescue manual, Algorithm chapter](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)
+- [ddrescue optical media notes](https://www.electric-spoon.com/doc/gddrescue/html/Optical-media.html)
+- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/mod.rs`](../src/disc/mod.rs) (`Disc::copy`, `Disc::patch`)

docs/udf.md

@@ -120,6 +120,14 @@ Each directory read involves two sector reads: one for the ICB, then one or more
 
 `read_file()` reads a file by navigating the directory tree, reading the file's ICB to get its data extent, then reading the data sector by sector from the **physical partition** (partition_start + LBA, not metadata_start).
 
+## Buffered Sector Reads
+
+USB optical drives have ~500ms round-trip latency per SCSI command. Since `read_filesystem()` and `read_file()` issue one SCSI READ per sector, a full disc scan can require hundreds of commands -- taking 10+ minutes on USB.
+
+`Disc::scan()` wraps the drive in a `BufferedSectorReader` before reading. On a single-sector read, the buffer prefetches a batch of sectors (sized from the kernel's `max_hw_sectors_kb` for the device) and caches them. Subsequent reads to nearby LBAs return from cache with zero SCSI overhead. After parsing the UDF directory structure, the entire metadata partition is pre-read into the cache, so all ICB lookups during title scanning and encryption resolution are instant.
+
+The buffer is transparent -- `read_filesystem()`, `read_file()`, and all downstream code still call `read_sectors(lba, 1, buf)` as before. The batching happens inside the `SectorReader` implementation.
+
 ### UDF Filename Encoding
 
 UDF filenames use a compression ID as the first byte:

examples/iso_dump.rs

@@ -0,0 +1,83 @@
+// Minimal ISO dumper — find exact stall point
+use libfreemkv::Drive;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+use std::time::Instant;
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() < 3 {
+        eprintln!("Usage: iso_dump <device> <output>");
+        std::process::exit(1);
+    }
+
+    let mut drive = Drive::open(Path::new(&args[1])).unwrap();
+    drive.wait_ready().unwrap();
+    let _ = drive.init();
+    let _ = drive.probe_disc();
+
+    // AACS handshake — required to read past the protected area
+    eprint!("Scanning disc... ");
+    let _ = libfreemkv::Disc::scan(&mut drive, &libfreemkv::ScanOptions::default());
+    eprintln!("OK");
+
+    let cap = drive.read_capacity().unwrap();
+    let batch = libfreemkv::disc::detect_max_batch_sectors(drive.device_path());
+
+    eprintln!("Device: {} | {} sectors | batch {}", args[1], cap, batch);
+
+    let file = std::fs::File::create(&args[2]).unwrap();
+    let mut w = BufWriter::with_capacity(4 * 1024 * 1024, file);
+    let mut buf = vec![0u8; batch as usize * 2048];
+    let mut lba: u32 = 0;
+    let start = Instant::now();
+    let mut last = Instant::now();
+    let mut bytes: u64 = 0;
+    let mut last_bytes: u64 = 0;
+
+    while lba < cap {
+        let count = ((cap - lba) as u16).min(batch);
+        let n = count as usize * 2048;
+
+        // Tiny yield between reads — test if pacing prevents firmware throttle
+        std::thread::yield_now();
+        let t0 = Instant::now();
+        let ok = drive.read(lba, count, &mut buf[..n], true).is_ok();
+        let read_ms = t0.elapsed().as_millis();
+
+        // Flag slow reads
+        if read_ms > 2000 {
+            eprintln!("\n  SLOW READ: LBA {} took {}ms (ok={})", lba, read_ms, ok);
+        }
+
+        if !ok {
+            buf[..n].fill(0);
+        }
+        w.write_all(&buf[..n]).unwrap();
+        lba += count as u32;
+        bytes += n as u64;
+
+        if last.elapsed().as_millis() >= 1000 {
+            let delta = bytes - last_bytes;
+            let speed = delta as f64 / last.elapsed().as_secs_f64() / 1_048_576.0;
+            let avg = bytes as f64 / start.elapsed().as_secs_f64() / 1_048_576.0;
+            let pct = bytes as f64 / (cap as f64 * 2048.0) * 100.0;
+            eprint!(
+                "\r  {:.1}% LBA {} | {:.0} MB/s (avg {:.0}) | {:.1} GB    ",
+                pct,
+                lba,
+                speed,
+                avg,
+                bytes as f64 / 1e9
+            );
+            last_bytes = bytes;
+            last = Instant::now();
+        }
+    }
+    w.flush().unwrap();
+    eprintln!(
+        "\nDone: {:.1} GB in {:.0}s",
+        bytes as f64 / 1e9,
+        start.elapsed().as_secs_f64()
+    );
+}

rustfmt.toml

@@ -0,0 +1 @@
+max_width = 100

src/aacs/decrypt.rs

@@ -0,0 +1,299 @@
+//! AACS content decryption — AES primitives, unit decryption, bus encryption.
+
+use aes::Aes128;
+use aes::cipher::{BlockDecrypt, BlockEncrypt, KeyInit, generic_array::GenericArray};
+
+// ── AACS constants ──────────────────────────────────────────────────────────
+
+/// Fixed IV used by AACS for all AES-CBC operations.
+pub(crate) const AACS_IV: [u8; 16] = [
+    0x0B, 0xA0, 0xF8, 0xDD, 0xFE, 0xA6, 0x1F, 0xB3, 0xD8, 0xDF, 0x9F, 0x56, 0x6A, 0x05, 0x0F, 0x78,
+];
+
+/// Size of an AACS aligned unit (3 × 2048-byte sectors).
+pub const ALIGNED_UNIT_LEN: usize = 6144;
+
+/// Size of one sector.
+const SECTOR_LEN: usize = 2048;
+
+/// Transport stream packet spacing in Blu-ray m2ts (192 bytes = 4 TP_extra + 188 TS).
+const TS_PACKET_LEN: usize = 192;
+
+/// TS sync byte.
+const TS_SYNC: u8 = 0x47;
+
+// ── AES primitives ──────────────────────────────────────────────────────────
+
+/// AES-128-ECB encrypt a single 16-byte block.
+pub(crate) fn aes_ecb_encrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let mut block = GenericArray::clone_from_slice(data);
+    cipher.encrypt_block(&mut block);
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&block);
+    out
+}
+
+/// AES-128-ECB decrypt a single 16-byte block.
+pub(crate) fn aes_ecb_decrypt(key: &[u8; 16], data: &[u8; 16]) -> [u8; 16] {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let mut block = GenericArray::clone_from_slice(data);
+    cipher.decrypt_block(&mut block);
+    let mut out = [0u8; 16];
+    out.copy_from_slice(&block);
+    out
+}
+
+/// AES-128-CBC decrypt in-place with the fixed AACS IV.
+/// AES-128-CBC decrypt in-place with the fixed AACS IV.
+pub(crate) fn aes_cbc_decrypt(key: &[u8; 16], data: &mut [u8]) {
+    let cipher = Aes128::new(GenericArray::from_slice(key));
+    let num_blocks = data.len() / 16;
+    // Process blocks in reverse to avoid clobbering ciphertext needed for XOR
+    for i in (0..num_blocks).rev() {
+        let offset = i * 16;
+        let prev = if i == 0 {
+            AACS_IV
+        } else {
+            let mut p = [0u8; 16];
+            p.copy_from_slice(&data[(i - 1) * 16..i * 16]);
+            p
+        };
+        let mut block = GenericArray::clone_from_slice(&data[offset..offset + 16]);
+        cipher.decrypt_block(&mut block);
+        for j in 0..16 {
+            data[offset + j] = block[j] ^ prev[j];
+        }
+    }
+}
+
+// ── Content decryption ──────────────────────────────────────────────────────
+
+/// Check if a 6144-byte aligned unit is encrypted (copy_permission_indicator bits).
+pub fn is_unit_encrypted(unit: &[u8]) -> bool {
+    unit.len() >= ALIGNED_UNIT_LEN && (unit[0] & 0xC0) != 0
+}
+
+/// Verify decrypted unit by checking TS sync bytes at expected offsets.
+fn verify_ts(unit: &[u8]) -> bool {
+    // In a 6144-byte unit, TS packets start at byte 0 with 4-byte TP_extra_header
+    // then 188-byte TS packet, repeating every 192 bytes.
+    // Sync byte 0x47 should appear at offset 4, 196, 388, ...
+    let mut count = 0;
+    let mut offset = 4;
+    while offset < unit.len() {
+        if unit[offset] == TS_SYNC {
+            count += 1;
+        }
+        offset += TS_PACKET_LEN;
+    }
+    // Expect at least most packets to have sync bytes
+    let total = (unit.len() - 4) / TS_PACKET_LEN + 1;
+    count > total / 2
+}
+
+/// Decrypt one AACS aligned unit (6144 bytes) in-place.
+/// Returns true if decryption succeeded (verified by TS sync bytes).
+///
+/// Algorithm:
+/// 1. AES-128-ECB encrypt first 16 bytes with unit_key → derived
+/// 2. XOR derived with original 16 bytes → unit_decrypt_key
+/// 3. AES-128-CBC decrypt bytes 16..6143 with unit_decrypt_key and AACS IV
+/// 4. Clear encryption flag bits
+pub fn decrypt_unit(unit: &mut [u8], unit_key: &[u8; 16]) -> bool {
+    if unit.len() < ALIGNED_UNIT_LEN {
+        return false;
+    }
+    if !is_unit_encrypted(unit) {
+        return true; // not encrypted
+    }
+
+    // Save original first 16 bytes (they're plaintext TP_extra_header)
+    let mut header = [0u8; 16];
+    header.copy_from_slice(&unit[..16]);
+
+    // Step 1: Encrypt header with unit key to derive per-unit key
+    let derived = aes_ecb_encrypt(unit_key, &header);
+
+    // Step 2: XOR to get the actual decryption key
+    let mut decrypt_key = [0u8; 16];
+    for i in 0..16 {
+        decrypt_key[i] = derived[i] ^ header[i];
+    }
+
+    // Step 3: Decrypt bytes 16..6143 with AES-CBC
+    aes_cbc_decrypt(&decrypt_key, &mut unit[16..ALIGNED_UNIT_LEN]);
+
+    // Step 4: Clear encryption flag
+    unit[0] &= !0xC0;
+
+    // Verify
+    verify_ts(unit)
+}
+
+/// Decrypt one aligned unit trying multiple unit keys. Returns the key index that worked.
+pub fn decrypt_unit_try_keys(unit: &mut [u8], unit_keys: &[[u8; 16]]) -> Option<usize> {
+    if !is_unit_encrypted(unit) {
+        return Some(0);
+    }
+
+    // Save original for retry
+    let original = unit[..ALIGNED_UNIT_LEN].to_vec();
+
+    for (i, key) in unit_keys.iter().enumerate() {
+        unit[..ALIGNED_UNIT_LEN].copy_from_slice(&original);
+        if decrypt_unit(unit, key) {
+            return Some(i);
+        }
+    }
+
+    // Restore original on failure
+    unit[..ALIGNED_UNIT_LEN].copy_from_slice(&original);
+    None
+}
+
+/// Remove bus encryption from an aligned unit (AACS 2.0 / UHD).
+/// Bus encryption uses read_data_key, decrypting bytes 16..2047 of each 2048-byte sector.
+pub fn decrypt_bus(unit: &mut [u8], read_data_key: &[u8; 16]) {
+    for sector_start in (0..ALIGNED_UNIT_LEN).step_by(SECTOR_LEN) {
+        if sector_start + SECTOR_LEN > unit.len() {
+            break;
+        }
+        // First 16 bytes of each sector are plaintext
+        aes_cbc_decrypt(
+            read_data_key,
+            &mut unit[sector_start + 16..sector_start + SECTOR_LEN],
+        );
+    }
+}
+
+/// Full decrypt of an aligned unit: bus decrypt (if needed) then AACS decrypt.
+pub fn decrypt_unit_full(
+    unit: &mut [u8],
+    unit_key: &[u8; 16],
+    read_data_key: Option<&[u8; 16]>,
+) -> bool {
+    if !is_unit_encrypted(unit) {
+        return true;
+    }
+    if let Some(rdk) = read_data_key {
+        decrypt_bus(unit, rdk);
+    }
+    decrypt_unit(unit, unit_key)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_aes_ecb_roundtrip() {
+        let key = [
+            0x15u8, 0x66, 0x5F, 0x98, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A,
+            0x0B, 0x0C,
+        ];
+        let plain = [0x41u8; 16];
+        let enc = aes_ecb_encrypt(&key, &plain);
+        let dec = aes_ecb_decrypt(&key, &enc);
+        assert_eq!(dec, plain);
+    }
+
+    #[test]
+    fn test_decrypt_unit_unencrypted() {
+        // Unit with 0xC0 bits clear should pass through unchanged
+        let mut unit = vec![0u8; ALIGNED_UNIT_LEN];
+        unit[0] = 0x00; // not encrypted
+        let key = [0u8; 16];
+        assert!(decrypt_unit(&mut unit, &key));
+    }
+
+    #[test]
+    fn test_aes_cbc_roundtrip() {
+        let key = [
+            0x11u8, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
+            0xFF, 0x00,
+        ];
+        let original = vec![0x42u8; 128]; // 8 blocks
+        let mut data = original.clone();
+
+        // Encrypt with CBC manually (forward direction)
+        fn aes_cbc_encrypt(key: &[u8; 16], data: &mut [u8]) {
+            let cipher = Aes128::new(GenericArray::from_slice(key));
+            let mut prev = super::AACS_IV;
+            let num_blocks = data.len() / 16;
+            for i in 0..num_blocks {
+                let offset = i * 16;
+                for j in 0..16 {
+                    data[offset + j] ^= prev[j];
+                }
+                let mut block = GenericArray::clone_from_slice(&data[offset..offset + 16]);
+                cipher.encrypt_block(&mut block);
+                data[offset..offset + 16].copy_from_slice(&block);
+                prev.copy_from_slice(&data[offset..offset + 16]);
+            }
+        }
+
+        aes_cbc_encrypt(&key, &mut data);
+        assert_ne!(data, original); // should be different after encrypt
+
+        super::aes_cbc_decrypt(&key, &mut data);
+        assert_eq!(data, original); // should match after roundtrip
+    }
+
+    #[test]
+    fn test_decrypt_unit_synthetic() {
+        // Build a fake 6144-byte aligned unit with known TS sync pattern,
+        // encrypt it with the AACS algorithm, then decrypt and verify.
+        let unit_key = [0xAAu8; 16];
+
+        // Build plaintext unit with TS sync bytes every 192 bytes starting at offset 4
+        let mut plain = vec![0u8; ALIGNED_UNIT_LEN];
+        let mut offset = 4;
+        while offset < ALIGNED_UNIT_LEN {
+            plain[offset] = TS_SYNC;
+            offset += TS_PACKET_LEN;
+        }
+        // Set encryption flag
+        plain[0] |= 0xC0;
+
+        // Now encrypt bytes 16..6143 using the AACS algorithm (reverse of decrypt)
+        let header: [u8; 16] = plain[..16].try_into().unwrap();
+        let derived = aes_ecb_encrypt(&unit_key, &header);
+        let mut encrypt_key = [0u8; 16];
+        for i in 0..16 {
+            encrypt_key[i] = derived[i] ^ header[i];
+        }
+
+        // CBC encrypt bytes 16..6143
+        let cipher = Aes128::new(GenericArray::from_slice(&encrypt_key));
+        let mut prev = AACS_IV;
+        let num_blocks = (ALIGNED_UNIT_LEN - 16) / 16;
+        for i in 0..num_blocks {
+            let off = 16 + i * 16;
+            for j in 0..16 {
+                plain[off + j] ^= prev[j];
+            }
+            let mut block = GenericArray::clone_from_slice(&plain[off..off + 16]);
+            cipher.encrypt_block(&mut block);
+            plain[off..off + 16].copy_from_slice(&block);
+            prev.copy_from_slice(&plain[off..off + 16]);
+        }
+
+        // Now plain contains encrypted data. Decrypt it.
+        let mut unit = plain;
+        assert!(is_unit_encrypted(&unit));
+        assert!(decrypt_unit(&mut unit, &unit_key));
+        assert!(!is_unit_encrypted(&unit)); // flag should be cleared
+
+        // Verify TS sync bytes
+        let mut count = 0;
+        let mut off = 4;
+        while off < ALIGNED_UNIT_LEN {
+            if unit[off] == TS_SYNC {
+                count += 1;
+            }
+            off += TS_PACKET_LEN;
+        }
+        assert_eq!(count, (ALIGNED_UNIT_LEN - 4) / TS_PACKET_LEN + 1);
+    }
+}