MattJackson
ed43ced710
Architecture: - One stream per format, bidirectional PES (read/write on same type) - IsoStream merged into DiscStream (one type, any SectorReader) - Disc::copy() for disc→ISO raw sector dump - IOStream trait deleted, all byte-level Read/Write removed - ContentReader/OpenDisc/open_title/open_input/open_output deleted - CountingStream wrapper for progress tracking Error codes: - All io::Error English strings replaced with Error enum variants - From<Error> for io::Error conversion - Unused variants removed, new stream/mux variants added Deleted: mkvout.rs, pesout.rs, isowriter.rs, mkv-muxer-plan.md Updated: all docs, README stream table, CHANGELOG 238 tests, 0 clippy warnings.
130 lines
4.7 KiB
Markdown
130 lines
4.7 KiB
Markdown
# Disc to Rip: End-to-End Flow
|
|
|
|
How libfreemkv goes from a disc in the drive to decrypted content ready for backup.
|
|
This is the starting point for understanding the library.
|
|
|
|
## The Pipeline
|
|
|
|
```
|
|
Insert disc
|
|
│
|
|
▼
|
|
1. Open drive (drive/mod.rs)
|
|
│ INQUIRY → identify drive
|
|
│ Match bundled profile → chipset, unlock parameters
|
|
│
|
|
▼
|
|
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
|
|
│ Read Volume ID + read_data_key
|
|
│ (fails gracefully if drive doesn't support AACS for this disc)
|
|
│
|
|
▼
|
|
4. Read UDF filesystem (udf.rs)
|
|
│ Sector 256: AVDP → find Volume Descriptor Sequence
|
|
│ VDS: Partition Descriptor (physical start) + Logical Volume (metadata start)
|
|
│ Metadata partition → File Set Descriptor → Root directory
|
|
│ Walk directory tree: BDMV/, AACS/, CERTIFICATE/
|
|
│ → docs/udf.md
|
|
│
|
|
▼
|
|
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 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) — 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) — 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 (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. 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)
|
|
│
|
|
▼
|
|
PES frames → output stream (MKV, M2TS, network, etc.)
|
|
```
|
|
|
|
## API Summary
|
|
|
|
```rust
|
|
// Open + init drive
|
|
let mut drive = Drive::open(Path::new("/dev/sg4"))?;
|
|
drive.wait_ready()?;
|
|
drive.init()?;
|
|
drive.probe_disc()?;
|
|
|
|
// Scan disc (UDF + playlists + AACS — all automatic)
|
|
let disc = Disc::scan(&mut drive, &ScanOptions::default())?;
|
|
|
|
// 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()?;
|
|
```
|
|
|
|
## Module Reference
|
|
|
|
| Module | Doc | Purpose |
|
|
|--------|-----|---------|
|
|
| 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 |
|
|
| 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 |
|