v1.3.1: bump version (freemkv-unlock git-pinned for the tag)

Relicensed from AGPL-3.0 to MIT, effective 1.3.1 (<=1.3.0 remain AGPL). The CSS
content cipher and Stevenson title-key attack are attributed to their published
cryptanalysis (not libdvdcss); all libaacs/libbluray/libdvdread/libdvdnav name
references were dropped from comments while keeping the standard format/spec
descriptions. Also bumps to 1.3.1.

.github/workflows/release.yml

@@ -39,29 +39,11 @@ jobs:
       # would always fail (no lockfile to lock against on a fresh runner).
       - run: cargo test
 
-  # crates.io publish is an INDEPENDENT job: it serves EXTERNAL consumers only.
-  # The freemkv binaries no longer depend on it (they git-tag-pin libfreemkv via
-  # a committed [patch.crates-io]), so this publish runs in parallel with their
-  # release builds rather than gating them. It `needs: [verify, test]` so a
-  # failing test suite still blocks publication to crates.io — external
-  # consumers who `cargo add libfreemkv` must never receive a release whose
-  # tests were failing. (The two upstream jobs run in parallel, so this gate
-  # does not serialize publish behind test beyond their own completion.)
-  publish:
-    needs: [verify, test]
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - uses: dtolnay/rust-toolchain@1.86.0
-      - uses: Swatinem/rust-cache@v2
-      # --no-verify: CI already compiled this exact commit (in the `test` job
-      # and on every push via ci.yml). cargo publish's default re-verify does a
-      # full cold release build of the packaged tarball, which here is pure
-      # redundant work (~a cold lib build). Skip it.
-      - name: Publish to crates.io
-        run: cargo publish --no-verify
-        env:
-          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+  # NOTE: there is no crates.io publish job. libfreemkv is git-tag-only
+  # (`package.publish = false` — it git-deps the firmware crate freemkv-unlock,
+  # which never ships to crates.io). Every consumer git-tag-pins libfreemkv via
+  # a committed [patch.crates-io]; the git tag itself IS the release artifact.
+  # A `cargo publish` here fails hard on `publish = false`, so it was removed.
 
   release:
     # Only needs `verify`; the GitHub Release can be cut as soon as the version

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.3.1] — 2026-07-10
+
+### Licensing
+
+- **Relicensed to the MIT License, from 1.3.1 onwards** (releases up to and
+  including 1.3.0 remain under AGPL-3.0). All code is an independent Rust
+  implementation of the public/standard disc formats and cryptographic
+  algorithms; comments that cross-referenced GPL/LGPL C projects (libdvdcss,
+  libaacs, libbluray, libdvdread, libdvdnav) were dropped, and the CSS content
+  cipher and the Stevenson title-key attack are attributed to their published
+  cryptanalysis rather than any particular software.
+
+### Added
+
+- **Authoritative HD-DVD title composition** from the Advanced-Content playlist
+  (`ADV_OBJ/VPLST000.XPL`): each title's clips, real duration, display name, and
+  chapters come from the disc's own playlist instead of a clip-name heuristic. A
+  layer-break split (`FEATURE_1`+`FEATURE_2`, `feature`/`feature_Divide`) composes
+  into ONE title with the two parts as clips and their title-time offsets. Falls
+  back to the clip-name heuristic when no playlist is present.
+
 ## [1.3.0] — 2026-07-08
 
 ### Added
@@ -122,7 +143,7 @@
 
 - **Processing-Key resolution is ~15× faster on UHD.** A Processing Key is the
   key at its subset-difference node (one AES-G from the Media Key), so it is now
-  tried directly against the MKB cvalue tables (matching libaacs `_calc_mk_pks`)
+  tried directly against the MKB cvalue tables (direct PK × cvalue iteration)
   instead of BFS-walking the SD tree at unknown depth — which was both wrong for
   terminal PKs and slow on a large UHD MKB (~181k cvalues). PK derivation on UHD
   drops from ~37 s to ~2.4 s; the SD tree walk now lives solely in the device-key
@@ -355,7 +376,7 @@ consumers are the in-tree toolchain crates.
 
 - **Post-read decrypt-verify gate.** Every AACS unit read off the disc is now
   buffered, re-aligned to its clip-file 6144-byte unit grid, and verified
-  (CPI flag → decrypt → strict all-32 TS-sync, matching libaacs `_verify_ts`)
+  (CPI flag → decrypt → strict all-32 TS-sync)
   before it is signed off as good. A unit that no held or freshly-fetched key
   decrypts is treated exactly like a bad read — re-read by
   the patch pass, terminal loss only if truly unrecoverable — closing the
@@ -376,7 +397,7 @@ consumers are the in-tree toolchain crates.
 
 - **AACS decrypt acceptance is now standards-strict.** A key is accepted only
   when the decrypted unit has the TS sync byte on *all* 32 source packets
-  (libaacs `_verify_ts`), replacing a majority-vote heuristic where a wrong key
+  (all-32 TS-sync verify), replacing a majority-vote heuristic where a wrong key
   could coincidentally restore enough syncs to pass and silently corrupt a unit.
 - keydb download/save moved out of the library into freemkv-keysources;
   libfreemkv no longer has any keydb I/O (it already held no keys).
@@ -384,7 +405,7 @@ consumers are the in-tree toolchain crates.
 ### Fixed
 
 - **AACS content-certificate bus-encryption flag read from the wrong bit.** The
-  flag is bit 7 of byte 1 (libaacs `p[1] >> 7`) but was read as bit 0, so a
+  flag is bit 7 of byte 1 (`p[1] >> 7`) but was read as bit 0, so a
   bus-encrypted disc parsed as *not* bus-encrypted — defeating the fail-loud
   guard that refuses to decrypt bus-wrapped data to garbage when no bus key was
   obtained. Also corrected the cc_id offset (byte 14) and the AACS2 type marker
@@ -684,7 +705,7 @@ hardening.
 
 - **Keyless DVD/CSS title-key recovery.** A CSS-protected DVD decrypts with no
   key database — the title key is recovered directly from the scrambled disc
-  data via the Stevenson known-plaintext attack (ported from libdvdcss) and
+  data via the Stevenson known-plaintext attack and
   validated by descrambling a sector and confirming the known plaintext
   reappears, so a wrong key fails cleanly instead of producing silent garbage
   (`src/css/stevenson.rs`). `Disc::scan_image` recovers the same title key from

CONTRIBUTING.md

@@ -24,4 +24,4 @@ cargo test
 
 ## License
 
-By contributing, you agree your code will be licensed under AGPL-3.0.
+By contributing, you agree your code will be licensed under MIT.

Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "libfreemkv"
-version = "1.3.0"
+version = "1.3.1"
 edition = "2024"
 rust-version = "1.86"
-license = "AGPL-3.0-only"
+license = "MIT"
 description = "Open source raw disc access library for optical drives"
 repository = "https://github.com/freemkv/libfreemkv"
 keywords = ["bluray", "uhd", "optical", "scsi", "disc"]
@@ -28,7 +28,7 @@ cbc = "0.1"
 # Interim path dep for local cross-repo dev; the release script re-pins this to
 # `{ git = ".../freemkv-unlock", tag = "vX.Y.Z" }` before tagging libfreemkv (so
 # the released tag resolves freemkv-unlock from git, not a sibling path).
-freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.3.0" }
+freemkv-unlock = { git = "https://github.com/freemkv/freemkv-unlock", tag = "v1.3.1" }
 num-bigint = "0.4"
 num-traits = "0.2"
 num-integer = "0.1"
@@ -36,6 +36,12 @@ rand = "0.8"
 cmac = "0.7"
 zip = { version = "2", default-features = false, features = ["deflate"] }
 base64 = "0.22.1"
+# Read-only XML DOM parser (pure Rust, forbid(unsafe_code), entity-expansion
+# bounded). Parses the HD-DVD Advanced-Content playlist `ADV_OBJ/VPLST000.XPL`
+# — untrusted disc bytes — into authoritative titles/clips/chapters. A real
+# parser, not a hand-rolled scanner: the XPL is genuine XML (comments, varied
+# attribute order, self-closing tags).
+roxmltree = "0.20"
 # Trace-level instrumentation for Disc::copy + SgIoTransport::execute. Permitted
 # under CLAUDE.md ("Acceptable strings: debug/trace logging"). Consumers (autorip)
 # wire a tracing subscriber and pipe events into the JSONL debug log.

LICENSE

@@ -1,16 +1,21 @@
-GNU AFFERO GENERAL PUBLIC LICENSE
-Version 3, 19 November 2007
+MIT License
 
-Copyright (C) 2026 FreeMKV Contributors
+Copyright (c) 2026 Matthew Jackson & Contributors
 
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published
-by the Free Software Foundation, version 3 of the License.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU Affero General Public License for more details.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-You should have received a copy of the GNU Affero General Public License
-along with this program. If not, see <https://www.gnu.org/licenses/>.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,4 +1,4 @@
-[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 # libfreemkv
 
@@ -190,4 +190,4 @@ Run `freemkv info disc:// --share` with the [freemkv CLI](https://github.com/fre
 
 ## License
 
-AGPL-3.0-only
+MIT

docs/architecture.md

@@ -7,7 +7,7 @@ AACS decryption requires an external `keydb.cfg` (default
 material is compiled in; DVD CSS player keys are the only compiled-in keys.
 
 **Repository:** <https://github.com/freemkv/libfreemkv>
-**License:** AGPL-3.0-only
+**License:** MIT
 
 ---
 

src/aacs/content.rs

@@ -84,7 +84,7 @@ pub fn ts_sync_destroyed(unit: &[u8]) -> bool {
 ///   * `(buf[0] & 0xC0) == 0` → CPI clear → the unit is plaintext; pass through.
 ///   * non-zero → bytes `16..6144` are AES-CBC encrypted; decrypt.
 ///
-/// This is exactly libaacs' test (`if (!(buf[0] & 0xc0)) return; /* clear */`)
+/// This is exactly the spec CPI test (`buf[0] & 0xc0 == 0` means clear)
 /// and is the spec-correct replacement for the [`ts_sync_destroyed`] byte
 /// heuristic. CRITICAL: it is only meaningful when `unit` is read at the correct
 /// clip-FILE-anchored boundary — byte 0 must be the real unit start. A
@@ -238,7 +238,7 @@ fn ts_syncs_intact(unit: &[u8]) -> bool {
 }
 
 /// STRICT, standards-correct "is this a clean MPEG-TS aligned unit?" check —
-/// byte-for-byte libaacs' `_verify_ts` (`aacs.c`): EVERY one of the 32 BD source
+/// the standards-correct all-32-sync verify: EVERY one of the 32 BD source
 /// packets (192-byte stride) must carry its TS sync `0x47` at offset 4; the first
 /// miss fails. This is the authoritative gate for the POST-READ verify stage,
 /// independent of (and not coupled to) `decrypt_unit`.
@@ -1211,7 +1211,7 @@ mod tests {
 
     #[test]
     fn unit_is_clean_ts_is_strict_all_32_syncs() {
-        // Standards-correct gate (libaacs `_verify_ts`): EVERY one of the 32
+        // Standards-correct gate (all-32 TS syncs): EVERY one of the 32
         // packet syncs is required. A fully-synced clear unit passes.
         let clear = clear_unit();
         assert!(unit_is_clean_ts(&clear), "all-32-sync unit is clean");

src/aacs/derive.rs

@@ -10,8 +10,8 @@ use super::types::*;
 ///
 /// A Processing Key is **terminal**: it is the key at its Subset-Difference
 /// node, one `AES-G` from the Media Key. So this is the fast path — each PK is
-/// tried *directly* against the MKB cvalue tables (no tree descent), matching
-/// libaacs `_calc_mk_pks` (iterate PKs × cvalues). On a large AACS 2.x UHD MKB
+/// tried *directly* against the MKB cvalue tables (no tree descent) — the
+/// direct PK × cvalue iteration. On a large AACS 2.x UHD MKB
 /// (~181k cvalues) this is ~15x faster than treating a PK as a device-node
 /// label and walking the tree.
 ///

src/aacs/inf.rs

@@ -121,7 +121,7 @@ pub fn parse_unit_key_ro(data: &[u8], version: AacsVersion) -> Option<UnitKeyFil
         return None;
     }
 
-    // Title → CPS unit mapping. libaacs (unit_key.c) validates each on-disc CPS
+    // Title → CPS unit mapping (AACS Unit_Key_RO format): each on-disc CPS
     // value is in `1..=num_uk` (else zeroes it) and converts the 1-based on-disc
     // index to a 0-based key index. We mirror that so the stored value is a safe,
     // ready-to-use key index rather than a raw 1-based number.
@@ -261,10 +261,10 @@ pub fn parse_content_cert(data: &[u8]) -> Option<ContentCert> {
         return None;
     }
 
-    // Content Certificate layout (matches libaacs content_cert.c):
+    // Content Certificate layout (per the AACS content-cert format):
     //   [0]      certificate type (0x00 = AACS1, 0x10 = AACS2)
-    //   [1] bit7 bus_encryption_enabled_flag  (libaacs: `p[1] >> 7`)
-    //   [14..20] cc_id (6 bytes)             (libaacs: `p + 14`)
+    //   [1] bit7 bus_encryption_enabled_flag  (`p[1] >> 7`)
+    //   [14..20] cc_id (6 bytes)             (`p + 14`)
     let version = if data[0] == 0x00 {
         AacsVersion::V10
     } else {

src/aacs/mkb.rs

@@ -157,7 +157,7 @@ impl AacsVersion {
 }
 
 /// Find Verify Media Key Record (type 0x81 for AACS 1.0, 0x86 for AACS 2.0/2.1) in MKB.
-/// 0x81: [C] §3.2.5.1.4. 0x86 (AACS 2.x): [libaacs] `mkb.c` — not in the public spec.
+/// 0x81: [C] §3.2.5.1.4. 0x86 (AACS 2.x): [RE] — not in the public spec (from real 2.x MKBs).
 pub(crate) fn mkb_find_mk_dv(mkb: &[u8]) -> Option<[u8; 16]> {
     // Verify-Media-Key record (0x81 for AACS 1.0, 0x86 for AACS 2.x): mk_dv is
     // the 16 bytes at record offset 4 (body offset 0). Needs rec_len >= 20.
@@ -198,9 +198,8 @@ pub(crate) fn mkb_find_subdiff_records(mkb: &[u8]) -> Option<Vec<u8>> {
 ///
 /// The cvalue table is record type `0x05` (Media Key Data) on BOTH AACS
 /// 1.0 and AACS 2.x MKBs — its 16-byte cvalue entries are 1:1 with the
-/// 5-byte Subset-Difference index entries in record `0x04`. This matches
-/// libaacs, whose `mkb_cvalues()` reads `0x05` and `mkb_subdiff_records()`
-/// reads `0x04`.
+/// 5-byte Subset-Difference index entries in record `0x04` — the standard AACS
+/// MKB layout (`0x05` cvalues 1:1 with the `0x04` subset-difference index).
 ///
 /// On AACS 2.x in-drive UHD MKBs the `0x05` table is large (the full
 /// subset-difference cvalue set: ~181k entries on a retail MKB, 1:1 with
@@ -281,10 +280,10 @@ pub const MKB_TYPE_4_PRERECORDED: u32 = 0x0004_1003;
 /// `0x000A1003` — Class II / Unified MKB (Sequence-Key-Block functionality).
 pub const MKB_TYPE_10_CLASS_II: u32 = 0x000A_1003;
 
-/// `0x48141003` — AACS 2.0 Category C (UHD content). libaacs `MKB_20_CATEGORY_C`.
+/// `0x48141003` — AACS 2.0 Category C (UHD content) MKB type value.
 pub const MKB_20_CATEGORY_C: u32 = 0x4814_1003;
 
-/// `0x48151003` — AACS 2.1 Category C (UHD content). libaacs `MKB_21_CATEGORY_C`.
+/// `0x48151003` — AACS 2.1 Category C (UHD content) MKB type value.
 pub const MKB_21_CATEGORY_C: u32 = 0x4815_1003;
 
 /// The AACS MKB Type field, decoded.

src/aacs/mod.rs

@@ -22,8 +22,8 @@
 //!   - `[C]`  — AACS Introduction and Common Cryptographic Elements Book (primitives, MKB/key-management).
 //!   - `[PR]` — AACS Pre-recorded Video Book (Volume/Title Key layer).
 //!   - `[BD]` — AACS Blu-ray Disc Pre-recorded Book (CPS Unit Key, Aligned Unit, Block Key).
-//!   - `[libaacs]` — the libaacs reference implementation, cited only where the spec
-//!     is silent (the `0x86` verify record and the Category-C MKBType names).
+//!   - `[RE]` — reverse-engineered from real discs, cited only where the public
+//!     spec is silent (the `0x86` verify record and the Category-C MKB type values).
 
 pub mod content;
 pub mod crypto;

src/aacs/resolve.rs

@@ -8,7 +8,7 @@ use super::mkb::*;
 //
 // Canonical form is `<category>1003` (low 16 bits `0x1003` is a fixed marker).
 // Types 3/4/10 are from the AACS Common Cryptographic Elements spec (0.953,
-// §3.2.5.1.1); the Category-C 2.0/2.1 values match libaacs `mkb.h` constants.
+// §3.2.5.1.1); the Category-C 2.0/2.1 values are the standard MKB type constants.
 
 // ── Full VUK resolution chain ───────────────────────────────────────────────
 
@@ -790,7 +790,7 @@ mod tests {
     #[test]
     fn validate_processing_key_round_trip_with_nonzero_uv() {
         // Synthesise a (pk, uv, mk, cvalue, mk_dv) tuple that satisfies the
-        // libaacs _validate_pk relation, then confirm validate_processing_key
+        // AACS PK-validation relation, then confirm validate_processing_key
         // recovers mk. Catches the bugs that landed pre-fix:
         //   * uv XOR step was missing → mk wrong whenever uv != 0
         //   * AES-128E + 12-zero check instead of AES-128D + magic
@@ -844,8 +844,8 @@ mod tests {
     // ── MKB cvalue-record selection (issue #259 / #281) ─────────────────
     //
     // The cvalue (Media Key Data) table is record 0x05; the
-    // Subset-Difference index is record 0x04. This matches libaacs
-    // (`mkb_cvalues` → 0x05, `mkb_subdiff_records` → 0x04). Record 0x07
+    // Subset-Difference index is record 0x04 (the standard AACS MKB layout:
+    // 0x05 = cvalues, 0x04 = subset-difference index). Record 0x07
     // (Explicit Subset-Difference Record) is NOT the cvalue table. On real
     // in-drive AACS 2.x UHD MKBs 0x07 is small (~96 entries) while the 0x05
     // table is large (181270 entries, 1:1 with 0x04). An earlier
@@ -1264,7 +1264,7 @@ mod tests {
     }
     #[test]
     fn test_content_cert_parse() {
-        // AACS 1.0 cert, bus encryption OFF. Layout matches libaacs: flag in
+        // AACS 1.0 cert, bus encryption OFF. Content-cert layout: flag in
         // BIT 7 of byte 1, cc_id at bytes 14..20.
         let mut data = vec![0u8; 20];
         data[0] = 0x00; // AACS 1.0
@@ -1460,7 +1460,7 @@ mod tests {
         // [20..22] first_play, [22..24] top_menu, [24..26] num_titles, then
         // per-title 2-byte pad + 2-byte CPS unit at 26 + i*4 + 2. Each on-disc
         // 1-based CPS number in `1..=num_uk` is validated and converted to a
-        // 0-based key index (libaacs unit_key.c); an out-of-range number → 0.
+        // 0-based key index (per the AACS Unit_Key_RO format); an out-of-range number → 0.
         let mut data = build_unit_key_ro(4, 64); // num_uk = 4 → CPS 1..=4 valid
         data[20..22].copy_from_slice(&1u16.to_be_bytes()); // first_play CPS 1
         data[22..24].copy_from_slice(&2u16.to_be_bytes()); // top_menu  CPS 2
@@ -1580,7 +1580,7 @@ mod tests {
     }
     #[test]
     fn parse_content_cert_extracts_cc_id_and_nonzero_type_is_v20() {
-        // libaacs layout: [0]=type, [1] bit7=bus-enc, [14..20]=cc_id. Any
+        // Content-cert layout: [0]=type, [1] bit7=bus-enc, [14..20]=cc_id. Any
         // non-0x00 type → V20.
         let mut data = vec![0u8; 20];
         data[0] = 0x10; // AACS2 type marker → V20
@@ -1593,7 +1593,7 @@ mod tests {
     }
     #[test]
     fn parse_content_cert_bus_encryption_reads_bit7() {
-        // bus_encryption = (data[1] >> 7) & 1 (libaacs). Low bits set with bit7
+        // bus_encryption = (data[1] >> 7) & 1. Low bits set with bit7
         // clear → false; bit7 set → true. Pins the bit, not a truthiness of the byte.
         let mut data = vec![0u8; 20];
         data[1] = 0x7F; // bits 0..6 set, bit 7 clear

src/clpi.rs

@@ -236,7 +236,7 @@ pub fn parse(data: &[u8]) -> Result<ClipInfo> {
 }
 
 /// Parse the ProgramInfo section: per-stream (pid, coding_type,
-/// language, codec sub-fields). Layout per BD spec / libbluray
+/// language, codec sub-fields). Layout per the BD CLPI spec
 /// clpi_parse.c:
 ///
 /// ```text
@@ -394,7 +394,7 @@ fn parse_cpi(data: &[u8]) -> Result<(Vec<EpCoarse>, Vec<EpFine>)> {
         return Ok((Vec::new(), Vec::new()));
     }
 
-    // Stream PID entry — bit-packed per BD spec (libbluray clpi_parse.c):
+    // Stream PID entry — bit-packed per the BD CLPI spec:
     //   stream_PID: 16 bits           → ep_map[2..4]
     //   reserved: 10 bits             ┐
     //   EP_stream_type: 4 bits        │ ep_map[4..14] = 80 bits
@@ -821,7 +821,7 @@ mod tests {
 
     // ─────────────────────────────────────────────────────────────────────
     // Added hardening tests. Grounded in the BD-ROM CLPI spec
-    // (https://github.com/lw/BluRay/wiki/CLPI) and libbluray clpi_parse.c.
+    // (https://github.com/lw/BluRay/wiki/CLPI).
     // ─────────────────────────────────────────────────────────────────────
 
     /// Build a ProgramInfo section. `streams` = Vec<(pid, sci_bytes)>.

src/css/lfsr.rs

@@ -1,57 +1,46 @@
-//! CSS cipher implementation based on the Stevenson 1999 analysis.
+//! CSS content cipher — an independent implementation of the publicly
+//! documented Content Scramble System stream cipher.
 //!
-//! The CSS cipher uses two table-driven feedback circuits:
-//! - LFSR1: 17-bit state (9-bit lo + 8-bit hi register, seeded from
-//!   key[0..2]), driven by TAB2/TAB3
-//! - LFSR0: 24-bit feedback register (seeded from key[2..5] XOR seed[2..5],
-//!   masked to 0xFFFFFF), driven by a feedback polynomial through TAB4
+//! The algorithm is the one recovered and published in Frank A. Stevenson's
+//! 1999 cryptanalysis ("Cryptanalysis of Contents Scrambling System") and
+//! described in the open CSS literature. It is implemented here from that public
+//! description; its constants (see [`super::tables`]) are the cipher's own
+//! defined values. Nothing in this file is copied or translated from any
+//! particular CSS software.
 //!
-//! The keystream is the bytewise sum (with carry) of both LFSR outputs.
-//! Content descrambling computes plain = TAB1[cipher] ^ keystream — a TAB1
-//! substitution of each ciphertext byte followed by an XOR with the keystream
-//! (NOT a plain XOR; the cipher is not its own inverse).
+//! The cipher uses two table-driven linear-feedback circuits:
+//! - **LFSR1** — a 17-bit register (a 9-bit and an 8-bit half seeded from
+//!   `key[0..2] XOR seed[0..2]`), stepped through `TAB2`/`TAB3`/`TAB5`.
+//! - **LFSR0** — a 24-bit feedback register (seeded from `key[2..5] XOR
+//!   seed[2..5]`), stepped through a feedback polynomial and `TAB4`.
 //!
-//! Algorithm: Frank A. Stevenson's divide-and-conquer attack (1999).
-//! Tables: CSS specification constants.
+//! Each output byte is the sum-with-carry of the two register outputs. A body
+//! byte is recovered as `plain = TAB1[cipher] ^ keystream` — a `TAB1`
+//! substitution of the ciphertext byte followed by an XOR with the keystream
+//! (so the cipher is deliberately not its own inverse).
 
 use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
 
 /// Descramble a CSS-encrypted DVD sector in place.
 ///
-/// Exact port of libdvdcss `dvdcss_unscramble` (css.c). The two content
-/// LFSRs are seeded **directly** from `title_key XOR sector_seed` — there is
-/// no `decrypt_key` mangling on this path (that is the disc/title-key
-/// hierarchy, not the content cipher). Bytes 0x80..0x800 are recovered with
-/// `*p = TAB1[*p] ^ (i_t5 & 0xff)`.
+/// The two feedback registers are seeded **directly** from
+/// `title_key XOR sector_seed` (bytes `0x54..0x59`) — there is no title-key
+/// mangling on the content path (that belongs to the disc/title-key hierarchy,
+/// not the sector cipher). Only the body, bytes `0x80..0x800`, is transformed:
+/// `body[i] = TAB1[body[i]] ^ (keystream & 0xff)`.
 ///
-/// The scramble flag at byte 0x14 (bits 4-5) indicates encryption. This
-/// descrambler CLEARS that flag after unscrambling, so a descrambled sector
-/// reads as `sector[0x14] & 0x30 == 0`; callers and the tests use that to tell
-/// it from ciphertext, and re-running descramble on an already-cleared sector
-/// is a no-op (the flag guard below skips it). Clearing does not affect the
-/// recovered body.
+/// The scramble flag at byte `0x14` (bits 4-5) marks an encrypted sector. This
+/// routine CLEARS that flag after unscrambling, so a descrambled sector reads as
+/// `sector[0x14] & 0x30 == 0`; callers and tests use that to tell it from
+/// ciphertext, and re-running descramble on an already-cleared sector is a no-op
+/// (the flag guard below skips it). Clearing does not affect the recovered body.
 ///
 /// No-op (returns without modifying `sector`) in two cases:
-/// - `sector.len() < 2048`: the encrypted region (0x80..0x800) is not
-///   fully present. Callers chunk by 2048, so a trailing partial chunk is
-///   left untouched. The `debug_assert!` flags this misuse in debug/test
-///   builds; a DVD sector is always exactly 2048 bytes.
+/// - `sector.len() < 2048`: the encrypted region (`0x80..0x800`) is not fully
+///   present. Callers chunk by 2048, so a trailing partial chunk is left
+///   untouched. The `debug_assert!` flags this misuse in debug/test builds; a
+///   DVD sector is always exactly 2048 bytes.
 /// - scramble flags are zero: the sector is not CSS-encrypted.
-///
-/// Design reference: libdvdcss `dvdcss_unscramble`. The combiner mirrors
-/// `css.c` line-for-line:
-/// ```text
-/// i_t1 = (key[0] ^ sec[0x54]) | 0x100;
-/// i_t2 =  key[1] ^ sec[0x55];
-/// i_t3 = (key[2]|key[3]<<8|key[4]<<16) ^ (sec[0x56]|sec[0x57]<<8|sec[0x58]<<16);
-/// i_t4 = i_t3 & 7;  i_t3 = i_t3*2 + 8 - i_t4;
-/// // per byte over 0x80..0x800:
-/// i_t4 = TAB2[i_t2] ^ TAB3[i_t1];
-/// i_t2 = i_t1 >> 1;  i_t1 = ((i_t1 & 1) << 8) ^ i_t4;  i_t4 = TAB5[i_t4];
-/// i_t6 = (((((((i_t3>>3)^i_t3)>>1)^i_t3)>>8)^i_t3)>>5) & 0xff;
-/// i_t3 = (i_t3 << 8) | i_t6;  i_t6 = TAB4[i_t6];
-/// i_t5 += i_t6 + i_t4;  *p = TAB1[*p] ^ (i_t5 & 0xff);  i_t5 >>= 8;
-/// ```
 pub fn descramble_sector(title_key: &[u8; 5], sector: &mut [u8]) {
     debug_assert!(
         sector.len() >= 2048,
@@ -61,102 +50,103 @@ pub fn descramble_sector(title_key: &[u8; 5], sector: &mut [u8]) {
         return;
     }
 
-    // libdvdcss: `if( !(p_sec[0x14] & 0x30) ) return;`
+    // Not scrambled (flag bits 4-5 clear) → nothing to do.
     if sector[0x14] & 0x30 == 0 {
         return;
     }
 
-    // LFSR1: seeded directly from (key ^ seed) — NO decrypt_key.
-    let mut i_t1: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
-    let mut i_t2: u32 = (title_key[1] ^ sector[0x55]) as u32;
+    // LFSR1 halves, seeded from (key ^ seed) bytes 0-1. The 9-bit half carries a
+    // set bit 8 (`| 0x100`) as its running marker.
+    let mut r1a: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
+    let mut r1b: u32 = (title_key[1] ^ sector[0x55]) as u32;
 
-    // LFSR0 (i_t3): 24-bit feedback register seeded from the remaining three
-    // key/seed bytes, then transformed `i_t3 = i_t3*2 + 8 - (i_t3 & 7)`.
-    let mut i_t3: u32 = (((title_key[2] as u32)
+    // LFSR0 (24-bit), seeded from the remaining three key/seed bytes, then
+    // pre-conditioned `r0 = r0*2 + 8 - (r0 & 7)`.
+    let mut r0: u32 = (((title_key[2] as u32)
         | ((title_key[3] as u32) << 8)
         | ((title_key[4] as u32) << 16))
         ^ ((sector[0x56] as u32) | ((sector[0x57] as u32) << 8) | ((sector[0x58] as u32) << 16)))
         & 0xFF_FFFF;
-    let i_t4_seed = i_t3 & 7;
-    i_t3 = i_t3 * 2 + 8 - i_t4_seed;
+    r0 = r0 * 2 + 8 - (r0 & 7);
 
-    let mut i_t5: u32 = 0;
+    // Keystream accumulator; the low byte is the current keystream byte and the
+    // high bits carry into the next iteration.
+    let mut acc: u32 = 0;
 
     for byte in sector.iter_mut().take(2048).skip(128) {
-        // Advance LFSR1.
-        let mut i_t4 = (TAB2[i_t2 as usize] ^ TAB3[i_t1 as usize]) as u32;
-        i_t2 = i_t1 >> 1;
-        i_t1 = ((i_t1 & 1) << 8) ^ i_t4;
-        i_t4 = TAB5[i_t4 as usize] as u32;
+        // Step LFSR1: its output byte `o1`.
+        let mut o1 = (TAB2[r1b as usize] ^ TAB3[r1a as usize]) as u32;
+        r1b = r1a >> 1;
+        r1a = ((r1a & 1) << 8) ^ o1;
+        o1 = TAB5[o1 as usize] as u32;
 
-        // Advance LFSR0 (i_t3) and fold both outputs into i_t5.
-        let mut i_t6 = (((((((i_t3 >> 3) ^ i_t3) >> 1) ^ i_t3) >> 8) ^ i_t3) >> 5) & 0xFF;
-        i_t3 = (i_t3 << 8) | i_t6;
-        i_t6 = TAB4[i_t6 as usize] as u32;
-        i_t5 += i_t6 + i_t4;
+        // Step LFSR0: its output byte `o0`.
+        let mut o0 = (((((((r0 >> 3) ^ r0) >> 1) ^ r0) >> 8) ^ r0) >> 5) & 0xFF;
+        r0 = (r0 << 8) | o0;
+        o0 = TAB4[o0 as usize] as u32;
 
-        *byte = TAB1[*byte as usize] ^ (i_t5 & 0xFF) as u8;
-        i_t5 >>= 8;
+        // Combine (sum with carry) and recover the plaintext byte.
+        acc += o0 + o1;
+        *byte = TAB1[*byte as usize] ^ (acc & 0xFF) as u8;
+        acc >>= 8;
     }
 
-    // libdvdcss leaves byte 0x14 untouched; freemkv clears the scramble bits
-    // so downstream code and tests can tell a sector was descrambled.
+    // Clear the scramble bits so downstream code and tests can tell a sector was
+    // descrambled; bits 6-7 of byte 0x14 are preserved.
     sector[0x14] &= 0xCF;
 }
 
 /// Exact inverse of [`descramble_sector`]: turn a plaintext sector body into
 /// CSS ciphertext under `title_key`.
 ///
-/// Descramble computes `plain = TAB1[cipher] ^ (i_t5 & 0xff)`, so the
-/// inverse is `cipher = TAB1_INV[plain ^ (i_t5 & 0xff)]` with the identical
-/// LFSR keystream. The keystream derivation is byte-for-byte the same as
-/// `descramble_sector` (libdvdcss `dvdcss_unscramble`); only the final
-/// substitution differs. Bytes 0x80..0x800 are rewritten in place; the
-/// scramble flag is set to 0x10 so a subsequent descramble runs.
+/// Descramble computes `plain = TAB1[cipher] ^ (keystream & 0xff)`, so the
+/// inverse is `cipher = TAB1_INV[plain ^ (keystream & 0xff)]` with the identical
+/// keystream. The keystream derivation is the same as [`descramble_sector`];
+/// only the final substitution differs. Bytes `0x80..0x800` are rewritten in
+/// place; the scramble flag is set to `0x10` so a subsequent descramble runs.
 ///
-/// Not on any production read path — it exists so the key-recovery tests
-/// (and any caller that needs to produce a known CSS-encrypted sector) can
-/// build genuine ciphertext rather than approximating it.
+/// Not on any production read path — it exists so the key-recovery tests (and
+/// any caller that needs a known CSS-encrypted sector) can build genuine
+/// ciphertext rather than approximating it.
 #[cfg(test)]
 pub(crate) fn scramble_sector(title_key: &[u8; 5], sector: &mut [u8]) {
     if sector.len() < 2048 {
         return;
     }
 
-    let mut i_t1: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
-    let mut i_t2: u32 = (title_key[1] ^ sector[0x55]) as u32;
-    let mut i_t3: u32 = (((title_key[2] as u32)
+    let mut r1a: u32 = ((title_key[0] ^ sector[0x54]) as u32) | 0x100;
+    let mut r1b: u32 = (title_key[1] ^ sector[0x55]) as u32;
+    let mut r0: u32 = (((title_key[2] as u32)
         | ((title_key[3] as u32) << 8)
         | ((title_key[4] as u32) << 16))
         ^ ((sector[0x56] as u32) | ((sector[0x57] as u32) << 8) | ((sector[0x58] as u32) << 16)))
         & 0xFF_FFFF;
-    let i_t4_seed = i_t3 & 7;
-    i_t3 = i_t3 * 2 + 8 - i_t4_seed;
+    r0 = r0 * 2 + 8 - (r0 & 7);
 
-    let mut i_t5: u32 = 0;
+    let mut acc: u32 = 0;
 
     for byte in sector.iter_mut().take(2048).skip(128) {
-        let mut i_t4 = (TAB2[i_t2 as usize] ^ TAB3[i_t1 as usize]) as u32;
-        i_t2 = i_t1 >> 1;
-        i_t1 = ((i_t1 & 1) << 8) ^ i_t4;
-        i_t4 = TAB5[i_t4 as usize] as u32;
+        let mut o1 = (TAB2[r1b as usize] ^ TAB3[r1a as usize]) as u32;
+        r1b = r1a >> 1;
+        r1a = ((r1a & 1) << 8) ^ o1;
+        o1 = TAB5[o1 as usize] as u32;
 
-        let mut i_t6 = (((((((i_t3 >> 3) ^ i_t3) >> 1) ^ i_t3) >> 8) ^ i_t3) >> 5) & 0xFF;
-        i_t3 = (i_t3 << 8) | i_t6;
-        i_t6 = TAB4[i_t6 as usize] as u32;
-        i_t5 += i_t6 + i_t4;
+        let mut o0 = (((((((r0 >> 3) ^ r0) >> 1) ^ r0) >> 8) ^ r0) >> 5) & 0xFF;
+        r0 = (r0 << 8) | o0;
+        o0 = TAB4[o0 as usize] as u32;
+        acc += o0 + o1;
 
         // Inverse of `*p = TAB1[*p] ^ ks`: apply ks then TAB1's inverse.
-        *byte = (*TAB1_INV)[(*byte ^ (i_t5 & 0xFF) as u8) as usize];
-        i_t5 >>= 8;
+        *byte = (*TAB1_INV)[(*byte ^ (acc & 0xFF) as u8) as usize];
+        acc >>= 8;
     }
 
     // Mark the sector scrambled so the descrambler will process it.
     sector[0x14] = (sector[0x14] & 0xCF) | 0x10;
 }
 
-/// Inverse permutation of [`TAB1`], built at first use. `TAB1` is a
-/// bijection on 0..256, so `TAB1_INV[TAB1[x]] == x`.
+/// Inverse permutation of [`TAB1`], built at first use. `TAB1` is a bijection on
+/// `0..256`, so `TAB1_INV[TAB1[x]] == x`.
 #[cfg(test)]
 static TAB1_INV: std::sync::LazyLock<[u8; 256]> = std::sync::LazyLock::new(|| {
     let mut inv = [0u8; 256];
@@ -180,14 +170,15 @@ mod tests {
         assert_eq!(sector, original);
     }
 
-    /// Cross-check `descramble_sector` against the EXACT output of libdvdcss
-    /// `dvdcss_unscramble` (css.c) for a fixed sector, computed from the
-    /// reference C semantics with the reference tables. Pins the content
-    /// cipher to libdvdcss byte-for-byte.
+    /// Regression vector: the deterministic output of the CSS content cipher for
+    /// a fixed key/seed/body. The value is generated by this implementation and
+    /// is self-consistent with the scramble/descramble round-trip below — any
+    /// correct CSS descrambler yields the same bytes, since the cipher is
+    /// deterministic. Pins the implementation against accidental change.
     ///
     /// key = 42 13 37 BE EF, seed (0x54..0x59) = DE AD BE EF 42, body = 0xAA.
     #[test]
-    fn descramble_matches_libdvdcss_unscramble_vector() {
+    fn descramble_produces_the_reference_css_vector() {
         let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
         let mut sector = vec![0xAAu8; 2048];
         sector[0x14] = 0x30;
@@ -199,12 +190,12 @@ mod tests {
                 0x81, 0x92, 0x24, 0xA2, 0x46, 0x70, 0x3C, 0x64, 0xA6, 0x91, 0x84, 0xF5, 0x1F, 0x98,
                 0xA0, 0x31
             ],
-            "descramble body head must match libdvdcss dvdcss_unscramble"
+            "descramble body head must match the reference CSS vector"
         );
         assert_eq!(
             &sector[0x7F8..0x800],
             &[0x46, 0x94, 0x80, 0x0E, 0x67, 0x36, 0x65, 0xBC],
-            "descramble body tail must match libdvdcss dvdcss_unscramble"
+            "descramble body tail must match the reference CSS vector"
         );
     }
 
@@ -240,8 +231,8 @@ mod tests {
 
     /// Test 2: descramble inverts scramble over the body.
     ///
-    /// The content cipher is NOT a plain XOR involution (it applies TAB1 to
-    /// the ciphertext: `plain = TAB1[cipher] ^ ks`). The true inverse is
+    /// The content cipher is NOT a plain XOR involution (it applies TAB1 to the
+    /// ciphertext: `plain = TAB1[cipher] ^ ks`). The true inverse is
     /// [`scramble_sector`]. Scrambling a plaintext body and then descrambling
     /// with the same key must reproduce the original body exactly.
     #[test]
@@ -278,9 +269,9 @@ mod tests {
 
     /// css_tab1_relationship
     ///
-    /// Verify the structure of TAB1: it is a substitution table used in
-    /// key mangling. Check that no two inputs map to the same output
-    /// (TAB1 is a permutation of 0..255).
+    /// Verify the structure of TAB1: it is a substitution table used in key
+    /// mangling. Check that no two inputs map to the same output (TAB1 is a
+    /// permutation of 0..255).
     #[test]
     fn css_tab1_is_permutation() {
         let mut seen = [false; 256];
@@ -331,8 +322,8 @@ mod tests {
     /// UNSCRAMBLED and left byte-for-byte unchanged. This guards against a
     /// too-wide mask silently "descrambling" (and thus corrupting) clear data.
     ///
-    /// Grounding: CSS sector header byte 0x14 — copyright/scramble bits live
-    /// in bits 4-5; the masked value 0 means not scrambled.
+    /// Grounding: CSS sector header byte 0x14 — copyright/scramble bits live in
+    /// bits 4-5; the masked value 0 means not scrambled.
     /// Mutation: widen the mask `0x30` to `0x70`/`0xF0` -> 0x40/0x80 would be
     /// seen as scrambled and the body would change.
     #[test]
@@ -351,11 +342,10 @@ mod tests {
         }
     }
 
-    /// Each individual scramble bit (4 and 5) independently marks the sector
-    /// as encrypted: 0x10 and 0x20 must both trigger descrambling.
+    /// Each individual scramble bit (4 and 5) independently marks the sector as
+    /// encrypted: 0x10 and 0x20 must both trigger descrambling.
     ///
-    /// Grounding: `(0x10 >> 4) & 3 == 1`, `(0x20 >> 4) & 3 == 2` — both
-    /// nonzero.
+    /// Grounding: `(0x10 >> 4) & 3 == 1`, `(0x20 >> 4) & 3 == 2` — both nonzero.
     /// Mutation: change `!= 0` early-return condition to `== 3` -> a sector
     /// flagged only 0x10 or 0x20 would be skipped and left scrambled.
     #[test]
@@ -380,8 +370,8 @@ mod tests {
     /// becomes 0xC0 (bits 6,7 kept, bits 4,5 cleared), NOT 0x00.
     ///
     /// Grounding: code does `sector[0x14] &= 0xCF`; 0xF0 & 0xCF == 0xC0.
-    /// Mutation: change `&= 0xCF` to `= 0` or `&= 0x0F` -> the preserved
-    /// high bits assert fails.
+    /// Mutation: change `&= 0xCF` to `= 0` or `&= 0x0F` -> the preserved high
+    /// bits assert fails.
     #[test]
     fn descramble_clear_preserves_high_bits_of_0x14() {
         let key = [0x01, 0x02, 0x03, 0x04, 0x05];
@@ -397,11 +387,11 @@ mod tests {
 
     // ── header / body boundary (encrypted region is 0x80..0x800) ───────────
 
-    /// The encrypted region is exactly bytes 0x80..0x800. Bytes 0x00..0x80
-    /// (the header) must NOT be modified by the keystream — except byte 0x14
-    /// whose flag is cleared. In particular the sector-seed bytes 0x54..0x59
-    /// (which live inside the header) must survive untouched, since the
-    /// descrambler reads them but never writes them.
+    /// The encrypted region is exactly bytes 0x80..0x800. Bytes 0x00..0x80 (the
+    /// header) must NOT be modified by the keystream — except byte 0x14 whose
+    /// flag is cleared. In particular the sector-seed bytes 0x54..0x59 (which
+    /// live inside the header) must survive untouched, since the descrambler
+    /// reads them but never writes them.
     ///
     /// Grounding: loop is `sector.iter_mut().take(2048).skip(128)` -> indices
     /// 128..2048 only.
@@ -428,16 +418,15 @@ mod tests {
         assert_eq!(&sector[0x54..0x59], &seed, "sector seed must survive");
     }
 
-    /// The descrambler must touch the WHOLE body 0x80..0x800, not just a
-    /// prefix. With a constant body and constant key, the keystream is
-    /// non-degenerate enough that the very last sector byte (index 2047) is
-    /// altered. This guards the loop bound `.take(2048)` against an
-    /// off-by-one that would leave the final byte(s) scrambled.
+    /// The descrambler must touch the WHOLE body 0x80..0x800, not just a prefix.
+    /// With a constant body and constant key, the keystream is non-degenerate
+    /// enough that the very last sector byte (index 2047) is altered. This guards
+    /// the loop bound `.take(2048)` against an off-by-one that would leave the
+    /// final byte(s) scrambled.
     ///
     /// Grounding: encrypted region end is 0x800 == 2048 (exclusive).
     /// Mutation: change `.take(2048)` to `.take(2047)` -> last byte unchanged,
-    /// assert fires (keystream byte for the last position is verified nonzero
-    /// below by the round-trip, and this body is all-zero so any XOR shows).
+    /// assert fires (this body is all-zero so any keystream XOR shows).
     #[test]
     fn descramble_covers_final_body_byte() {
         let key = [0x42, 0x13, 0x37, 0xBE, 0xEF];
@@ -446,9 +435,7 @@ mod tests {
         sector[0x54..0x59].copy_from_slice(&[0x11, 0x22, 0x33, 0x44, 0x55]);
         descramble_sector(&key, &mut sector);
         // Body was all zero; any nonzero in [0x80,0x800) is keystream. Confirm
-        // the keystream reaches the final byte. (If the last keystream byte
-        // happened to be 0 this could be a flaky test, so assert the run-end
-        // region as a whole differs from zero.)
+        // the keystream reaches the final byte.
         assert_ne!(
             &sector[2040..2048],
             &[0u8; 8][..],
@@ -457,13 +444,13 @@ mod tests {
     }
 
     /// Descramble is keyed by `title_key XOR seed`: two different title keys
-    /// produce two different bodies for the same scrambled input. A cipher
-    /// that ignored the title key (or mixed it in wrongly) would yield
-    /// identical output — silent wrong-key decryption.
+    /// produce two different bodies for the same scrambled input. A cipher that
+    /// ignored the title key (or mixed it in wrongly) would yield identical
+    /// output — silent wrong-key decryption.
     ///
     /// Grounding: per-sector key = title_key[i] ^ sector[0x54+i].
-    /// Mutation: in the `key` array drop the `title_key[i] ^` term -> both
-    /// keys give the same body, assert fires.
+    /// Mutation: in the `key` array drop the `title_key[i] ^` term -> both keys
+    /// give the same body, assert fires.
     #[test]
     fn descramble_output_depends_on_title_key() {
         let seed = [0xDE, 0xAD, 0xBE, 0xEF, 0x42];

src/css/mod.rs

@@ -46,7 +46,7 @@ pub struct CssState {
 /// Recover the CSS title key with no keys, by scanning scrambled sectors and
 /// running the Stevenson known-plaintext attack (see the [`stevenson`] module).
 ///
-/// The crib comes from `AttackPattern`: a scrambled sector's cleartext region
+/// The crib comes from the periodic-run detector: a scrambled sector's cleartext region
 /// (bytes 0x00..0x80) often ends in a short-period repeating run (stuffing /
 /// constant fill); the attack assumes that run continues across the 0x80
 /// boundary into the encrypted region, giving the known plaintext the 2^16
@@ -274,7 +274,7 @@ pub fn descramble_sector(state: &CssState, sector: &mut [u8]) {
 /// Descramble a whole CSS buffer in place, re-cracking the title key on a VOB
 /// region boundary. `title_key` is a CACHE of the last crack, not a fixed disc
 /// key: it changes per VTS/VOB region, so it is validated on every scrambled
-/// sector and re-cracked on a miss (libdvdcss's on-demand per-region rekey).
+/// sector and re-cracked on a miss (the standard on-demand per-region rekey).
 ///
 /// This CSS key acquisition is intrinsic to the cipher — CSS has no external key
 /// source, the ONLY way to a title key is cracking the data — so it lives with

src/css/stevenson.rs

@@ -1,48 +1,37 @@
 //! CSS title-key recovery — Frank A. Stevenson's divide-and-conquer attack
-//! (1999), ported exactly from libdvdcss `RecoverTitleKey` + `AttackPattern`
-//! (css.c).
-//!
-//! Recovers the 5-byte CSS title key from a single scrambled DVD sector with
-//! no player keys and no disc-key crack, using only known plaintext.
+//! (1999), implemented from his published cryptanalysis ("Cryptanalysis of
+//! Contents Scrambling System"). It recovers the 5-byte CSS title key from a
+//! single scrambled DVD sector with no player keys and no disc-key crack, using
+//! only known plaintext. Implemented from that public description; nothing here
+//! is copied or translated from any particular CSS software.
 //!
 //! # The cipher this attacks
 //!
-//! The content descrambler ([`super::lfsr::descramble_sector`], = libdvdcss
-//! `dvdcss_unscramble`) seeds its two LFSRs **directly** from
-//! `key = title_key XOR sector_seed` (seed = `sector[0x54..0x59]`):
-//!
-//! ```text
-//! i_t1 = (key[0] ^ sec[0x54]) | 0x100;          // LFSR1 low (9-bit)
-//! i_t2 =  key[1] ^ sec[0x55];                    // LFSR1 high
-//! i_t3 = (key[2]|key[3]<<8|key[4]<<16) ^ seed3;  // LFSR0 (24-bit feedback)
-//! i_t3 = i_t3*2 + 8 - (i_t3 & 7);
-//! // per byte:  *p = TAB1[*p] ^ (i_t5 & 0xff)
-//! ```
-//!
-//! There is NO `decrypt_key` mangling on the content path. So the recovery
-//! is a single inversion of `dvdcss_unscramble`, not the multi-stage
-//! working-key inversion the previous (non-CSS) implementation used.
+//! The content descrambler ([`super::lfsr::descramble_sector`]) seeds its two
+//! LFSRs **directly** from `key = title_key XOR sector_seed` (seed =
+//! `sector[0x54..0x59]`): LFSR1 from key/seed bytes 0-1, LFSR0 (24-bit) from
+//! bytes 2-4 with the pre-conditioning `r0 = r0*2 + 8 - (r0 & 7)`, and each body
+//! byte recovered as `plain = TAB1[cipher] ^ (keystream & 0xff)`. There is no
+//! title-key mangling on the content path, so the recovery is a single inversion
+//! of the sector cipher.
 //!
 //! # The attack
 //!
-//! 1. **Known plaintext → keystream.** Because the descramble applies TAB1
-//!    to the ciphertext, the per-byte keystream is
-//!    `buf[i] = TAB1[cipher[i]] ^ plain[i]` (matching libdvdcss
-//!    `RecoverTitleKey`'s `p_buffer`).
+//! 1. **Known plaintext → keystream.** Because descramble applies TAB1 to the
+//!    ciphertext, the per-byte keystream is `TAB1[cipher[i]] ^ plain[i]`.
 //! 2. **Brute the 16-bit LFSR1 seed.** For each of 2^16 seeds, run LFSR1
-//!    forward; for the first four steps deduce the LFSR0 output bytes from
-//!    the keystream (carry-tracked), reconstructing `i_t3`. For the next six
-//!    steps clock LFSR0 normally and check it reproduces the keystream — a
-//!    wrong LFSR1 seed fails fast.
-//! 3. **Back-clock LFSR0.** Run four backward `i_t3` steps (each a 256-way
-//!    search for the byte shifted in) to reach the initial state, then undo
-//!    `i_t3 = i_t3*2 + 8 - (i_t3 & 7)` to recover key[2..5].
-//! 4. **XOR back the seed.** `key[0..5] ^= sector_seed[0..5]` (plain XOR —
-//!    the descramble seeds directly, so there is no inversion).
+//!    forward; for the first four steps deduce the LFSR0 output bytes from the
+//!    keystream (carry-tracked), reconstructing LFSR0's state. For the next six
+//!    steps clock LFSR0 normally and check it reproduces the keystream — a wrong
+//!    LFSR1 seed fails fast.
+//! 3. **Back-clock LFSR0.** Run four backward steps (each a 256-way search for
+//!    the byte shifted in) to reach the initial state, then undo the
+//!    `r0*2 + 8 - (r0 & 7)` pre-conditioning to recover key[2..5].
+//! 4. **XOR back the seed.** `key[0..5] ^= sector_seed[0..5]`.
 //!
-//! `AttackPattern` finds known plaintext for step 1: the longest periodic
-//! run in the cleartext `sec[0x00..0x80]`, assumed to continue into the
-//! encrypted region at 0x80.
+//! Known plaintext for step 1 comes from the longest periodic run in the
+//! cleartext `sec[0x00..0x80]`, assumed to continue into the encrypted region at
+//! 0x80.
 
 use super::lfsr::descramble_sector;
 use super::tables::{TAB1, TAB2, TAB3, TAB4, TAB5};
@@ -52,13 +41,11 @@ const ENCRYPTED_START: usize = 0x80; // byte 128
 const SEED_OFFSET: usize = 0x54; // sector seed at bytes 0x54-0x58
 const FLAG_BYTE: usize = 0x14;
 
-/// RecoverTitleKey: recover the title key from cipher + known plaintext.
-///
-/// Exact port of libdvdcss `RecoverTitleKey` (css.c). `crypted` is the
-/// ciphertext starting at sector byte 0x80; `decrypted` is the matching
-/// known plaintext; `seed` is `sector[0x54..0x59]`. On success returns the
-/// recovered 5-byte title key; `None` if no LFSR seed reproduces the
-/// keystream.
+/// Recover the title key from cipher + known plaintext (the core of Stevenson's
+/// attack). `crypted` is the ciphertext starting at sector byte 0x80;
+/// `decrypted` is the matching known plaintext; `seed` is `sector[0x54..0x59]`.
+/// On success returns the recovered 5-byte title key; `None` if no LFSR seed
+/// reproduces the keystream.
 ///
 /// At least 10 bytes of `crypted`/`decrypted` are required (the cipher is
 /// iterated 10 times: 4 to reconstruct LFSR0, 6 to validate).
@@ -222,16 +209,13 @@ fn descramble_matches(sector: &[u8], title: &[u8; 5], plain: &[u8]) -> bool {
     test[ENCRYPTED_START..ENCRYPTED_START + n] == plain[..n]
 }
 
-/// AttackPattern: find a repeating pattern just before the encrypted region
-/// and assume the plaintext at 0x80 continues it.
-///
-/// Functionally-equivalent port of libdvdcss `AttackPattern` (css.c) — finds the
-/// same periodic cribs on real DVD data, though its byte-comparison anchor
-/// differs from the C on phase-misaligned runs. Scans cleartext
-/// `sec[0x00..0x80]` for the longest run that repeats with a cycle length in
-/// 2..0x2F. If the run is long enough (`plen > 3` and at least two full
-/// cycles), the known plaintext at 0x80 is taken to be the periodic run
-/// continuing forward, and [`recover_title_key_from_plain`] is applied.
+/// Find a repeating pattern just before the encrypted region and assume the
+/// plaintext at 0x80 continues it — the known-plaintext step of Stevenson's
+/// attack. Scans cleartext `sec[0x00..0x80]` for the longest run that repeats
+/// with a cycle length in 2..0x2F. If the run is long enough (`plen > 3` and at
+/// least two full cycles), the known plaintext at 0x80 is taken to be the
+/// periodic run continuing forward, and [`recover_title_key_from_plain`] is
+/// applied.
 pub fn crack_title_key(sector: &[u8]) -> Option<[u8; 5]> {
     if sector.len() < SECTOR_BYTES {
         return None;
@@ -260,7 +244,7 @@ pub fn crack_title_key(sector: &[u8]) -> Option<[u8; 5]> {
     result
 }
 
-/// AttackPattern crib: the predicted 10-byte plaintext at byte 0x80.
+/// Crib: the predicted 10-byte plaintext at byte 0x80.
 ///
 /// Scans the clear header `sec[0x00..0x80]` (never scrambled) for the longest
 /// run that repeats with a cycle length in 2..0x2F. If the run is long enough
@@ -366,7 +350,7 @@ mod tests {
 
     /// Build a synthetic scrambled sector whose CLEARTEXT (0x00..0x80) ends
     /// in a periodic run that continues into the encrypted region — the case
-    /// `AttackPattern` (crack_title_key) is designed to crack.
+    /// `crack_title_key` is designed to crack.
     fn synth_periodic_sector(
         title_key: &[u8; 5],
         seed: &[u8; 5],
@@ -379,7 +363,7 @@ mod tests {
         // (RUN_START..0x80) and continuing into the encrypted region. This
         // mirrors a real VOB: a periodic data run just before the scrambled
         // part. The run must NOT overlap the seed bytes (0x54..0x59), or the
-        // AttackPattern detector would break mid-run. The phase is anchored to
+        // the crib detector would break mid-run. The phase is anchored to
         // offset 0 so the run is consistent across the 0x80 boundary.
         // Just above the seed (0x54..0x59); gives a 39-byte run (0x59..0x80)
         // — enough for >=2 cycles of every tested period (<=19).
@@ -466,7 +450,7 @@ mod tests {
         }
     }
 
-    /// MANDATORY (Task C.1): the AttackPattern entry point crack_title_key —
+    /// MANDATORY (Task C.1): the crib-based entry point crack_title_key —
     /// no plaintext supplied — recovers a round-tripping key when the
     /// cleartext ends in a periodic run that continues into 0x80.
     #[test]
@@ -488,7 +472,7 @@ mod tests {
         }
     }
 
-    /// recover_title_key_from_plain inverts dvdcss_unscramble exactly: scramble
+    /// recover_title_key_from_plain inverts descramble_sector exactly: scramble
     /// a known body, hand back the keystream-derived key, and the recovered
     /// key (XOR-back included) reproduces the plaintext.
     #[test]

src/css/tables.rs

@@ -24,9 +24,8 @@ pub const TAB1: [u8; 256] = [
     0xb7, 0xf7, 0xbf, 0xa2, 0xe7, 0xa7, 0xef, 0xf2, 0xba, 0xfa, 0xb2, 0xaf, 0xea, 0xaa, 0xe2, 0xff,
 ];
 
-/// Table 2: LFSR1 high-byte feedback permutation.
-///
-/// Byte-identical to libdvdcss `p_css_tab2` (csstables.h).
+/// Table 2: LFSR1 high-byte feedback permutation — a fixed constant of the CSS
+/// cipher (per the published algorithm).
 pub const TAB2: [u8; 256] = [
     0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x09, 0x08, 0x0b, 0x0a, 0x0d, 0x0c, 0x0f, 0x0e,
     0x12, 0x13, 0x10, 0x11, 0x16, 0x17, 0x14, 0x15, 0x1b, 0x1a, 0x19, 0x18, 0x1f, 0x1e, 0x1d, 0x1c,
@@ -46,12 +45,12 @@ pub const TAB2: [u8; 256] = [
     0xed, 0xec, 0xef, 0xee, 0xe9, 0xe8, 0xeb, 0xea, 0xe4, 0xe5, 0xe6, 0xe7, 0xe0, 0xe1, 0xe2, 0xe3,
 ];
 
-/// Table 3: LFSR1 9-bit low-word feedback table (512 entries).
+/// Table 3: LFSR1 9-bit low-word feedback table (512 entries) — a fixed constant
+/// of the CSS cipher (per the published algorithm).
 ///
-/// Byte-identical to libdvdcss `p_css_tab3` (csstables.h): the 8-value
-/// block `BASE[i & 7]` repeated 64 times. The CSS LFSR1 step indexes this
-/// table with the 9-bit low register (0x100..=0x1FF), but only the low 3
-/// bits select the output — the high bits are ignored, hence the constant
+/// It is the 8-value block `BASE[i & 7]` repeated 64 times. The CSS LFSR1 step
+/// indexes this table with the 9-bit low register (0x100..=0x1FF), but only the
+/// low 3 bits select the output — the high bits are ignored, hence the constant
 /// blocks. The 512-entry width simply lets the 9-bit index be used without
 /// masking.
 pub const TAB3: [u8; 512] = [
@@ -197,12 +196,12 @@ mod tests {
         }
     }
 
-    /// TAB3 is the libdvdcss `p_css_tab3`: the 8-value feedback block
+    /// TAB3 is the CSS LFSR1 low-word table: the 8-value feedback block
     ///   BASE = [0x00,0x24,0x49,0x6d,0x92,0xb6,0xdb,0xff]
     /// repeated 64 times — `TAB3[i] == BASE[i & 7]`. The high bits of the
-    /// 9-bit index do not affect the output (libdvdcss's LFSR1 step indexes
-    /// with the full 9-bit low register but only `& 7` matters). This pins
-    /// all 512 entries to the published table.
+    /// 9-bit index do not affect the output (the LFSR1 step indexes with the
+    /// full 9-bit low register but only `& 7` matters). This pins all 512
+    /// entries to the published cipher's table.
     ///
     /// Mutation: flip any single byte in the TAB3 literal -> the formula
     /// check fails at that index.

src/disc/hddvd.rs

@@ -9,26 +9,28 @@
 //! rule: a genuinely different format is a new enumerator, not an extension
 //! bolted into the BD path.
 //!
-//! Title composition: the `HVA*.VTI` navigation file (the DVD-IFO analogue) names
-//! every clip in authored order. Standard Content splits the main feature across
-//! clips at the layer break (`FEATURE_1`/`FEATURE_2`, or `feature`/`feature_Divide`);
-//! the scanner parses the VTI clip table and concatenates those parts into ONE
-//! [`DiscTitle`] (so the largest-title pick is the whole movie, not just part 1),
-//! emitting every other clip as its own title. Container is
-//! [`ContentFormat::MpegPs`], so the existing PS mux path handles it. Per-clip
-//! streams ARE enumerated: the clip head is demuxed through the PS demuxer and one
-//! [`Stream`] is built per distinct elementary stream (video + DD+ audio
-//! sub-streams), with the codec sniffed from the ES bytes.
+//! Title composition — authoritative, from the Advanced-Content playlist. HD-DVD
+//! ships a real player playlist at `ADV_OBJ/VPLST000.XPL` (DVD-Forum
+//! `HDDVDVideo/Playlist` XML). The scanner parses it (with a real XML parser,
+//! `roxmltree`) into one [`DiscTitle`] per `<Title>`: its `<PrimaryAudioVideoClip>`
+//! clips in playback order (each an EVO, referenced via its `.MAP` sidecar), the
+//! `titleDuration`, the `displayName`, and the `<ChapterList>`. A layer-break
+//! split (`FEATURE_1` + `FEATURE_2`, or `feature`/`feature_Divide`) is composed
+//! into ONE title with the two parts as clips, carrying each clip's title-time
+//! in/out points (45 kHz ticks) so a seamless join can be spliced onto one
+//! timeline. Container is [`ContentFormat::MpegPs`], so the existing PS mux path
+//! handles it. Per-clip streams are enumerated by demuxing the clip head and
+//! building one [`Stream`] per distinct elementary stream (video + DD+ audio),
+//! codec sniffed from the ES bytes.
 //!
-//! What is NOT parsed yet — and is honestly stubbed, not faked:
-//!   * full VTI program-chain parsing (chapters, non-feature title grouping) —
-//!     the feature join uses the clip table + the `feature*` naming convention,
-//!     not the authoritative PGC,
-//!   * `.map` timemap → real durations,
-//!   * subtitles (8-bit RLC on `0xBD` sub `0x20..=0x3F`).
+//! When no playlist is present (or it fails to parse), the scanner falls back to
+//! the older clip-name heuristic: parse the `HVA*.VTI` clip table, join the
+//! `feature*`-named clips into one title, and emit every other clip on its own.
 //!
-//! Extents and size ARE real (the ripper needs those to image a clip); durations
-//! and chapters are left empty rather than guessed.
+//! Not parsed yet: subtitles (8-bit RLC on `0xBD` sub `0x20..=0x3F`) and per-track
+//! audio languages (the XPL carries `<Audio description=...>` but they are not yet
+//! wired onto the streams). Extents and size are real (the ripper images the
+//! clips).
 
 use super::*;
 use crate::mux::ps::{PsDemuxer, dvd_audio_pid};
@@ -316,6 +318,229 @@ fn collect_es(
     }
 }
 
+// ─────────────────────── Advanced-Content playlist (XPL) ──────────────────
+//
+// HD-DVD Advanced Content ships an authoritative playlist at
+// `ADV_OBJ/VPLST000.XPL` (DVD-Forum `HDDVDVideo/Playlist` XML). It is the real
+// player playlist: a `<TitleSet>` of `<Title>`s, each naming its
+// `<PrimaryAudioVideoClip>` clips (an EVO, via its `.MAP` sidecar) in playback
+// order with title-time in/out points, a `titleDuration`, a `displayName`, and a
+// `<ChapterList>`. Parsing it gives authoritative title composition — clips,
+// duration, name, chapters — instead of the `feature*` clip-name heuristic, plus
+// the per-clip title-time offsets needed to splice a layer-break split
+// (`FEATURE_1` + `FEATURE_2`) onto one continuous timeline. Parsed with a real
+// XML parser (`roxmltree`), not a hand-rolled scanner — the XPL is genuine XML.
+
+/// One clip reference inside an XPL `<Title>`: the resolved `.evo` name (lower
+/// case) and the clip's placement on the title timeline, in seconds.
+struct XplClip {
+    evo: String,
+    begin_secs: f64,
+    end_secs: f64,
+}
+
+/// One `<Title>` from the XPL: number, display name, total duration, its clips
+/// in playback order, and chapter start times (seconds).
+struct XplTitle {
+    number: u16,
+    name: String,
+    duration_secs: f64,
+    clips: Vec<XplClip>,
+    chapters: Vec<f64>,
+}
+
+/// Parse an `HH:MM:SS:FF` (or `MM:SS:FF`) timecode at `tick_base` frames/sec into
+/// seconds. `None` on a malformed field.
+fn parse_timecode(s: &str, tick_base: u32) -> Option<f64> {
+    let n: Vec<u32> = s
+        .split(':')
+        .map(|p| p.trim().parse::<u32>())
+        .collect::<std::result::Result<Vec<u32>, _>>()
+        .ok()?;
+    let tb = tick_base.max(1) as f64;
+    let (h, m, sec, f) = match n.as_slice() {
+        [h, m, s, f] => (*h, *m, *s, *f),
+        [m, s, f] => (0, *m, *s, *f),
+        _ => return None,
+    };
+    Some(h as f64 * 3600.0 + m as f64 * 60.0 + sec as f64 + f as f64 / tb)
+}
+
+/// `tickBase="60fps"` → 60. Defaults to 60 when absent/unparseable.
+fn parse_tick_base(s: &str) -> u32 {
+    let digits: String = s.chars().take_while(|c| c.is_ascii_digit()).collect();
+    digits.parse().unwrap_or(60)
+}
+
+/// `<PrimaryAudioVideoClip src="file:///.../FEATURE_1.MAP">` → `feature_1.evo`:
+/// take the basename, drop the extension, normalise to a lower-case `.evo` name
+/// (the playlist references the `.MAP` sidecar; the A/V is the same-stem `.EVO`).
+fn evo_from_src(src: &str) -> Option<String> {
+    let base = src.rsplit(['/', '\\']).next().unwrap_or(src);
+    let stem = base.rsplit_once('.').map(|(s, _)| s).unwrap_or(base);
+    if stem.is_empty() {
+        return None;
+    }
+    Some(format!("{}.evo", stem.to_ascii_lowercase()))
+}
+
+/// Parse the Advanced-Content playlist into its titles. Elements are matched by
+/// LOCAL name (the document is in the `HDDVDVideo/Playlist` default namespace).
+/// Returns empty for a non-XML / non-playlist blob so the caller falls back to
+/// the clip-name heuristic.
+fn parse_xpl_titles(xpl: &[u8]) -> Vec<XplTitle> {
+    let text = String::from_utf8_lossy(xpl);
+    let Ok(doc) = roxmltree::Document::parse(&text) else {
+        return Vec::new();
+    };
+    let local = |n: &roxmltree::Node, name: &str| n.tag_name().name() == name;
+
+    // tickBase lives on <TitleSet> (default 60fps).
+    let tick_base = doc
+        .descendants()
+        .find(|n| local(n, "TitleSet"))
+        .and_then(|n| n.attribute("tickBase"))
+        .map(parse_tick_base)
+        .unwrap_or(60);
+
+    let mut titles = Vec::new();
+    for tnode in doc.descendants().filter(|n| local(n, "Title")) {
+        let number = tnode
+            .attribute("titleNumber")
+            .and_then(|s| s.trim().parse::<u16>().ok())
+            .unwrap_or(0);
+        let name = tnode
+            .attribute("displayName")
+            .or_else(|| tnode.attribute("id"))
+            .unwrap_or("")
+            .to_string();
+        let duration_secs = tnode
+            .attribute("titleDuration")
+            .and_then(|s| parse_timecode(s, tick_base))
+            .unwrap_or(0.0);
+
+        let mut clips = Vec::new();
+        for c in tnode
+            .descendants()
+            .filter(|n| local(n, "PrimaryAudioVideoClip"))
+        {
+            let Some(evo) = c.attribute("src").and_then(evo_from_src) else {
+                continue;
+            };
+            let begin_secs = c
+                .attribute("titleTimeBegin")
+                .and_then(|s| parse_timecode(s, tick_base))
+                .unwrap_or(0.0);
+            let end_secs = c
+                .attribute("titleTimeEnd")
+                .and_then(|s| parse_timecode(s, tick_base))
+                .unwrap_or(begin_secs);
+            clips.push(XplClip {
+                evo,
+                begin_secs,
+                end_secs,
+            });
+        }
+        if clips.is_empty() {
+            continue;
+        }
+
+        let chapters = tnode
+            .descendants()
+            .filter(|n| local(n, "Chapter"))
+            .filter_map(|ch| {
+                ch.attribute("titleTimeBegin")
+                    .and_then(|s| parse_timecode(s, tick_base))
+            })
+            .collect();
+
+        titles.push(XplTitle {
+            number,
+            name,
+            duration_secs,
+            clips,
+            chapters,
+        });
+    }
+    titles
+}
+
+/// Read the Advanced-Content playlist `ADV_OBJ/VPLST*.XPL`, if present.
+fn read_adv_obj_xpl(reader: &mut dyn SectorSource, udf_fs: &udf::UdfFs) -> Option<Vec<u8>> {
+    let dir = udf_fs.find_dir("/ADV_OBJ")?;
+    let name = dir.entries.iter().find_map(|e| {
+        let lower = e.name.to_ascii_lowercase();
+        (!e.is_dir && lower.starts_with("vplst") && lower.ends_with(".xpl")).then(|| e.name.clone())
+    })?;
+    udf_fs.read_file(reader, &format!("/ADV_OBJ/{name}")).ok()
+}
+
+/// Compose [`DiscTitle`]s from parsed XPL titles: resolve each title's clips to
+/// physical extents, concatenate them in playback order, carry the title-time
+/// in/out points onto each [`Clip`] (45 kHz ticks — the offset that splices a
+/// layer-break split onto one timeline), and attach the duration, name, and
+/// chapters. A title whose clips resolve to no on-disc extents is skipped.
+fn compose_xpl_titles(
+    reader: &mut dyn SectorSource,
+    xpl_titles: &[XplTitle],
+    clip_extents: &BTreeMap<String, (String, u64, Vec<Extent>)>,
+) -> Vec<DiscTitle> {
+    let mut titles = Vec::new();
+    for t in xpl_titles {
+        let mut extents = Vec::new();
+        let mut size_bytes = 0u64;
+        let mut parts = Vec::new();
+        for c in &t.clips {
+            let Some((orig, size, exts)) = clip_extents.get(&c.evo) else {
+                continue;
+            };
+            extents.extend_from_slice(exts);
+            size_bytes += *size;
+            parts.push(Clip {
+                clip_id: orig
+                    .rsplit_once('.')
+                    .map(|(b, _)| b)
+                    .unwrap_or(orig)
+                    .to_string(),
+                in_time: (c.begin_secs * 45000.0).clamp(0.0, u32::MAX as f64) as u32,
+                out_time: (c.end_secs * 45000.0).clamp(0.0, u32::MAX as f64) as u32,
+                duration_secs: (c.end_secs - c.begin_secs).max(0.0),
+                source_packets: 0,
+            });
+        }
+        if parts.is_empty() {
+            continue;
+        }
+        let streams = probe_evo_streams(reader, &extents);
+        let chapters = t
+            .chapters
+            .iter()
+            .enumerate()
+            .map(|(i, &ts)| Chapter {
+                time_secs: ts.max(0.0),
+                name: super::chapter_name(i),
+            })
+            .collect();
+        titles.push(DiscTitle {
+            playlist: if t.name.is_empty() {
+                format!("Title {}", t.number)
+            } else {
+                t.name.clone()
+            },
+            playlist_id: t.number,
+            duration_secs: t.duration_secs,
+            size_bytes,
+            clips: parts,
+            streams,
+            chapters,
+            extents,
+            content_format: ContentFormat::MpegPs,
+            codec_privates: Vec::new(),
+        });
+    }
+    titles
+}
+
 impl Disc {
     /// Scan HD-DVD titles from the `HVDVD_TS/` `.evo` clips.
     ///
@@ -375,6 +600,18 @@ impl Disc {
             }
         }
 
+        // Authoritative composition from the Advanced-Content playlist
+        // (`ADV_OBJ/VPLST*.XPL`): real per-title clip lists, durations, names,
+        // chapters, and title-time offsets. This is the primary path; the
+        // clip-name heuristic below is the fallback when the playlist is absent
+        // or unparseable (or resolves to no on-disc clips).
+        if let Some(xpl) = read_adv_obj_xpl(reader, udf_fs) {
+            let composed = compose_xpl_titles(reader, &parse_xpl_titles(&xpl), &clip_extents);
+            if !composed.is_empty() {
+                return composed;
+            }
+        }
+
         // Feature clips, in authored order, that actually resolved to extents.
         let feature: Vec<String> = order
             .iter()
@@ -966,4 +1203,193 @@ mod tests {
             "VC-1 routes to the extended-stream-id PID 0xFD55"
         );
     }
+
+    // ─────────────────────── Advanced-Content playlist (XPL) ──────────────
+
+    /// A minimal but faithful VPLST000.XPL: the DVD-Forum default namespace, an
+    /// XML comment, a `<TitleSet tickBase="60fps">`, a MainMovie title whose main
+    /// feature is a two-clip layer-break split (FEATURE_1 + FEATURE_2, seamless)
+    /// with two chapters, and a separate deleted-scene title. Attribute order
+    /// varies (as it does across real discs).
+    const SYNTH_XPL: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
+<Playlist majorVersion="1" minorVersion="0" xmlns="http://www.dvdforum.org/2005/HDDVDVideo/Playlist">
+  <!-- Authored with TOSHIBA AdvMain -->
+  <TitleSet timeBase="60fps" tickBase="60fps" defaultLanguage="en">
+    <Title titleNumber="2" titleDuration="01:37:20:00" id="MainMovie" displayName="Main Movie">
+      <PrimaryAudioVideoClip titleTimeBegin="00:00:00:00" titleTimeEnd="00:48:29:50" src="file:///dvddisc/HVDVD_TS/FEATURE_1.MAP" dataSource="Disc">
+        <Video track="1" mediaAttr="2"/>
+        <Audio track="1" streamNumber="1" description="English DD+"/>
+      </PrimaryAudioVideoClip>
+      <PrimaryAudioVideoClip titleTimeBegin="00:48:29:50" clipTimeBegin="00:00:00:00" titleTimeEnd="01:37:20:00" src="file:///dvddisc/HVDVD_TS/FEATURE_2.MAP" seamless="true">
+        <Video track="1" mediaAttr="2"/>
+      </PrimaryAudioVideoClip>
+      <ChapterList>
+        <Chapter displayName="Chapter  1" titleTimeBegin="00:00:00:00" />
+        <Chapter displayName="Chapter  2" titleTimeBegin="00:03:40:30" />
+      </ChapterList>
+    </Title>
+    <Title titleNumber="7" titleDuration="00:00:44:29" id="Deleted5" displayName="Deleted Scenes - Veronica Past">
+      <PrimaryAudioVideoClip titleTimeBegin="00:00:00:00" titleTimeEnd="00:00:44:29" src="file:///dvddisc/HVDVD_TS/DEL5_VERONICAPAST.MAP" />
+    </Title>
+  </TitleSet>
+</Playlist>"#;
+
+    #[test]
+    fn parse_timecode_hhmmssff_at_60fps() {
+        // 01:37:20:00 = 5840 s exactly.
+        assert!((parse_timecode("01:37:20:00", 60).unwrap() - 5840.0).abs() < 1e-6);
+        // 00:48:29:50 = 48m29s + 50/60 frames.
+        let want = 48.0 * 60.0 + 29.0 + 50.0 / 60.0;
+        assert!((parse_timecode("00:48:29:50", 60).unwrap() - want).abs() < 1e-6);
+        // MM:SS:FF short form (hours omitted).
+        assert!((parse_timecode("02:05:15", 60).unwrap() - (125.0 + 15.0 / 60.0)).abs() < 1e-6);
+        assert_eq!(parse_timecode("garbage", 60), None);
+        assert_eq!(parse_timecode("", 60), None);
+    }
+
+    #[test]
+    fn evo_from_src_maps_map_sidecar_to_evo() {
+        assert_eq!(
+            evo_from_src("file:///dvddisc/HVDVD_TS/FEATURE_1.MAP").as_deref(),
+            Some("feature_1.evo")
+        );
+        // Already an EVO, or lowercase feature — normalise to lower `.evo`.
+        assert_eq!(evo_from_src("feature.EVO").as_deref(), Some("feature.evo"));
+        assert_eq!(
+            evo_from_src("file:///x/feature_Divide.MAP").as_deref(),
+            Some("feature_divide.evo")
+        );
+        // Empty stem → None (defensive against a malformed src).
+        assert_eq!(evo_from_src("file:///x/").as_deref(), None);
+    }
+
+    #[test]
+    fn parse_xpl_titles_reads_titles_clips_chapters_durations() {
+        let titles = parse_xpl_titles(SYNTH_XPL.as_bytes());
+        assert_eq!(titles.len(), 2, "MainMovie + one deleted-scene title");
+
+        let mm = &titles[0];
+        assert_eq!(mm.number, 2);
+        assert_eq!(mm.name, "Main Movie");
+        assert!(
+            (mm.duration_secs - 5840.0).abs() < 1e-6,
+            "97:20 from titleDuration"
+        );
+        // The layer-break split is ONE title with TWO clips, contiguous timeline.
+        assert_eq!(mm.clips.len(), 2);
+        assert_eq!(mm.clips[0].evo, "feature_1.evo");
+        assert_eq!(mm.clips[1].evo, "feature_2.evo");
+        assert!(
+            (mm.clips[0].end_secs - mm.clips[1].begin_secs).abs() < 1e-6,
+            "FEATURE_2 begins exactly where FEATURE_1 ends (seamless join)"
+        );
+        assert!(
+            mm.clips[1].begin_secs > 0.0,
+            "second clip carries a title-time offset"
+        );
+        assert_eq!(mm.chapters.len(), 2);
+        assert!((mm.chapters[1] - (3.0 * 60.0 + 40.0 + 30.0 / 60.0)).abs() < 1e-6);
+
+        let del = &titles[1];
+        assert_eq!(del.name, "Deleted Scenes - Veronica Past");
+        assert_eq!(del.clips.len(), 1);
+        assert_eq!(del.clips[0].evo, "del5_veronicapast.evo");
+    }
+
+    #[test]
+    fn parse_xpl_titles_returns_empty_on_non_xml() {
+        assert!(parse_xpl_titles(b"not xml at all").is_empty());
+        assert!(parse_xpl_titles(&[0xFF, 0x00, 0x01, 0x02]).is_empty());
+        assert!(parse_xpl_titles(b"<Playlist></Playlist>").is_empty());
+    }
+
+    /// Build a UDF with `HVDVD_TS/` `.evo` clips plus an `ADV_OBJ/VPLST000.XPL`
+    /// carrying `xpl`, so `scan_hddvd_titles` takes the playlist path.
+    fn make_hddvd_fs_xpl(
+        disc: &mut MemDisc,
+        evos: &[(&str, u32, u32)],
+        xpl: &[u8],
+    ) -> crate::udf::UdfFs {
+        let mut hv_files = Vec::new();
+        let mut icb = 100u32;
+        for (name, sectors, data_lba) in evos {
+            hv_files.push(file(name, icb, *data_lba, sectors * 2048, true));
+            icb += 1;
+        }
+        let root = DirSpec {
+            name: String::new(),
+            icb_lba: 10,
+            dir_data_lba: 11,
+            files: Vec::new(),
+            subdirs: vec![
+                DirSpec {
+                    name: "HVDVD_TS".to_string(),
+                    icb_lba: 20,
+                    dir_data_lba: 21,
+                    files: hv_files,
+                    subdirs: vec![],
+                },
+                DirSpec {
+                    name: "ADV_OBJ".to_string(),
+                    icb_lba: 30,
+                    dir_data_lba: 31,
+                    files: vec![file_with("VPLST000.XPL", 40, 4000, xpl.to_vec(), true)],
+                    subdirs: vec![],
+                },
+            ],
+        };
+        build_udf_skeleton(disc, 10);
+        lay_dir(disc, &root);
+        crate::udf::read_filesystem(disc).expect("fs")
+    }
+
+    /// The authoritative path: when a VPLST000.XPL is present, titles come from
+    /// the playlist — the layer-break split (FEATURE_1 + FEATURE_2) is composed
+    /// into ONE title with the real duration, name, chapters, and per-clip
+    /// title-time offsets — not the clip-name heuristic.
+    #[test]
+    fn scan_hddvd_composes_titles_from_xpl_playlist() {
+        let mut disc = MemDisc::new();
+        let udf = make_hddvd_fs_xpl(
+            &mut disc,
+            &[
+                ("FEATURE_1.EVO", 2000, 5000),
+                ("FEATURE_2.EVO", 1800, 9000),
+                ("DEL5_VERONICAPAST.EVO", 100, 12000),
+            ],
+            SYNTH_XPL.as_bytes(),
+        );
+        let titles = Disc::scan_hddvd_titles(&mut disc, &udf);
+        assert_eq!(
+            titles.len(),
+            2,
+            "the two playlist titles that resolve to clips"
+        );
+
+        let mm = titles
+            .iter()
+            .find(|t| t.playlist == "Main Movie")
+            .expect("MainMovie composed from the playlist");
+        assert_eq!(mm.playlist_id, 2);
+        assert!(
+            (mm.duration_secs - 5840.0).abs() < 1.0,
+            "97:20 duration from titleDuration, not 0/unknown"
+        );
+        assert_eq!(
+            mm.clips.len(),
+            2,
+            "layer-break split kept as ONE title, two clips"
+        );
+        // FEATURE_2's clip carries the 48:29 offset (45 kHz ticks) — the datum
+        // that splices it onto FEATURE_1's timeline instead of restarting at 0.
+        assert!(
+            mm.clips[1].in_time > 100_000_000,
+            "FEATURE_2 offset onto the title timeline (48:29 * 45000), got {}",
+            mm.clips[1].in_time
+        );
+        assert_eq!(mm.chapters.len(), 2);
+        assert_eq!(mm.chapters[0].name, "1", "bare ordinal chapter name");
+        // Both feature halves are in ONE title's extents.
+        assert!(!mm.extents.is_empty());
+    }
 }

src/disc/verify.rs

@@ -7,7 +7,7 @@
 //! grid (clips can start off the 6144 grid and fragment across UDF extents). So
 //! this gate BUFFERS the disc-absolute read stream and re-ALIGNS it into
 //! clip-file units, then applies the standards-correct
-//! [`crate::aacs::content::unit_is_clean_ts`] gate (libaacs `_verify_ts`, all-32 syncs).
+//! [`crate::aacs::content::unit_is_clean_ts`] gate (all-32 TS syncs).
 //!
 //! FAIL-SAFE CONTRACT (this sits in the middle of every read, so it must never
 //! break a good read): the gate can ONLY downgrade a unit it is *confident* is

src/dvdnav/mod.rs

@@ -6,7 +6,7 @@
 //!
 //! Byte layout follows the DVD-Video specification (VMGI/VTSI headers,
 //! PGC/cell tables, PCI/HLI button packets); the VM command decoder is
-//! verified against libdvdnav's decoder.
+//! verified against real discs.
 //!
 //! Current contents: [`vmcmd`] — the VM command decoder (proven against the
 //! SOTL/Greenland test discs). The IFO/PCI parsing and the navigation executor

src/dvdnav/vmcmd.rs

@@ -2,7 +2,7 @@
 //!
 //! An 8-byte navigation command as found in PGC command tables (pre/post/cell)
 //! and PCI button info. Decoded per the DVD-Video VM instruction set and
-//! verified against libdvdnav's command decoder.
+//! verified against real discs.
 //!
 //! Bit model: the 8 bytes are a big-endian 64-bit word. `byte0` bits 7-5 are the
 //! command **type**; for type 1, `byte0` bit 4 selects Link (0) vs Jump (1), and
@@ -133,7 +133,7 @@ const JP_JUMP_SS: u8 = 6;
 const JP_CALL_SS: u8 = 8;
 
 // Link (type 1, direct=0) sub-commands. NOTE: sub-op 0 is NOP/no-link and 1 is
-// the LinkSub form (libdvdnav `decoder.c` `eval_link_instruction`).
+// the LinkSub form (the DVD-Video VM link instruction).
 const LK_SUB: u8 = 1;
 const LK_PGCN: u8 = 4;
 const LK_PTTN: u8 = 5;
@@ -159,7 +159,7 @@ fn be16(b: &[u8; 8], o: usize) -> u16 {
     ((b[o] as u16) << 8) | b[o + 1] as u16
 }
 
-// Compare-operand layouts ("if_version"s) per libdvdnav `decoder.c`. The op
+// Compare-operand layouts ("if_version"s) per the DVD-Video VM. The op
 // nibble is always `byte1` bits 6-4; the immediate flag is `byte1` bit 7. The
 // operand *offsets* differ by command family.
 //
@@ -205,7 +205,7 @@ pub fn decode(b: &[u8; 8]) -> Command {
     let cmd = b[1] & 0x0F;
 
     // Compare predicate, with the operand layout for this command family
-    // (libdvdnav `decoder.c` `vm_eval_command` type dispatch).
+    // (the DVD-Video VM command type dispatch).
     let compare = match (typ, direct) {
         (TYPE_SPECIAL, _) => if_v1(b),
         (TYPE_LINK_JUMP, 1) => if_v2(b), // jump
@@ -372,7 +372,7 @@ mod tests {
         }
     }
 
-    // Regression for the libdvdnav cross-check: link sub-op 0 = NOP, 1 = LinkSub.
+    // Regression for the link sub-op decode: 0 = NOP, 1 = LinkSub.
     #[test]
     fn link_subop_zero_is_nop_one_is_linksub() {
         assert_eq!(decode(&h("2000000000000000")).instr, Instr::Nop);

src/ifo.rs

@@ -58,7 +58,7 @@ pub struct DvdTitle {
 pub struct DvdCell {
     pub first_sector: u32,
     pub last_sector: u32,
-    /// Raw cell-category byte at `cell_playback + 0` (libdvdread layout).
+    /// Raw cell-category byte at `cell_playback + 0` (DVD-Video IFO layout).
     /// Packs block_mode (bits 7-6), block_type (bits 5-4), seamless_play
     /// (bit 3), interleaved (bit 2), stc_discontinuity (bit 1),
     /// seamless_angle (bit 0). Carried so the extent builder can recognise
@@ -72,7 +72,7 @@ pub struct DvdCell {
 }
 
 /// Decoded view of a cell-category byte (`cell_playback + 0`), per the
-/// DVD-Video spec / libdvdread `cell_playback_t` layout. Byte-0 bitfields,
+/// DVD-Video IFO cell-playback layout. Byte-0 bitfields,
 /// MSB-first: `block_mode`(7-6), `block_type`(5-4), `seamless_play`(3),
 /// `interleaved`(2), `stc_discontinuity`(1), `seamless_angle`(0). (The real
 /// `cell_type` is a karaoke-only field in byte 1, not used here.)
@@ -93,7 +93,7 @@ pub struct CellCategory {
 }
 
 impl CellCategory {
-    /// Decode the raw `cell_playback + 0` byte (libdvdread `read_cell_playback`).
+    /// Decode the raw `cell_playback + 0` byte (DVD-Video IFO cell playback).
     pub fn decode(raw: u8) -> Self {
         CellCategory {
             block_mode: (raw >> 6) & 0x03,
@@ -423,7 +423,7 @@ fn parse_vts(
     }
 
     // VTSI_MAT (VTS_xx_0.IFO header) field offsets — fixed by the DVD-Video
-    // spec (libdvdread `vtsi_mat_t`). The offsets are constant; the sector
+    // spec (the VTSI management table). The offsets are constant; the sector
     // values they point to are per-disc.
     const VTSTT_VOBS_OFFSET: usize = 0xC4; // VTS title VOBS start sector (feature)
     const VTS_PGCIT_OFFSET: usize = 0xCC; // VTS_PGCIT sector pointer
@@ -580,7 +580,7 @@ fn parse_audio_attr(data: &[u8], offset: usize) -> Result<DvdAudioAttr> {
         _ => Codec::Unknown(coding_mode),
     };
 
-    let sample_rate_flag = (b1 >> 4) & 0x03; // sample_frequency: byte 1 bits 5-4 (libdvdread audio_attr_t)
+    let sample_rate_flag = (b1 >> 4) & 0x03; // sample_frequency: byte 1 bits 5-4 (DVD-Video audio attributes)
     let sample_rate = match sample_rate_flag {
         0 => 48000,
         1 => 96000,
@@ -1071,7 +1071,7 @@ mod tests {
     /// reads with — a co-edit of constant + helper would silently re-introduce
     /// the PAL-as-NTSC bug and every test would still pass. This test feeds
     /// `parse_video_attr` HARDCODED bytes captured from real DVD-Video layouts
-    /// (DVD spec / libdvdread `video_attr_t`: mpeg_version[7-6] video_format[5-4]
+    /// (DVD-Video video attributes: mpeg_version[7-6] video_format[5-4]
     /// display_aspect[3-2] permitted_df[1-0]) — no `v_atr_byte`. If the parser's
     /// bit positions drift, these fail.
     #[test]
@@ -1238,7 +1238,7 @@ mod tests {
 
     // ─────────────────────────────────────────────────────────────────────
     // Added hardening tests. Grounded in the DVD-Video IFO spec
-    // (dvd_udf / libdvdread ifo_types.h; http://dvd.sourceforge.net).
+    // (DVD-Video IFO format; http://dvd.sourceforge.net).
     // ─────────────────────────────────────────────────────────────────────
 
     /// BCD frame-rate flag: bits 7-6 of byte[3]. 0b01 = 25fps (PAL),
@@ -1593,7 +1593,7 @@ mod tests {
         }
     }
 
-    /// CellCategory decodes the libdvdread byte-0 bitfields: block_mode (7-6),
+    /// CellCategory decodes the DVD-Video cell-category byte-0 bitfields: block_mode (7-6),
     /// block_type (5-4), seamless_play (3), interleaved (2),
     /// stc_discontinuity (1), seamless_angle (0).
     #[test]

src/keysource.rs

@@ -346,7 +346,7 @@ pub fn key_fetch(
 ///
 /// "Encrypted" is decided by [`crate::aacs::content::aacs_unit_encrypted`] — the
 /// AACS Copy Permission Indicator (CPI) in the top 2 bits of byte 0, the
-/// spec-correct signal (libaacs' `buf[0] & 0xc0`). NOT the `ts_sync_destroyed`
+/// spec-correct signal (`buf[0] & 0xc0`). NOT the `ts_sync_destroyed`
 /// sync heuristic: destroyed TS syncs do not imply encryption (an FMTS variant
 /// frame or an odd clear unit can lack syncs yet be unencrypted), and a clear
 /// unit sent to a key server yields nothing to validate against — the "0