pq/libfreemkv
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up for public release: docs, zero warnings, no hardcoded paths

Browse Source 
Documentation:
- docs/aacs.md — AACS encryption (1.0 + 2.0), key resolution, decrypt
- docs/udf.md — UDF 2.50 filesystem with metadata partitions
- docs/mpls.md — MPLS playlist format, STN stream table
- docs/clpi.md — CLPI clip info, EP map, sector extents
- docs/architecture.md — library module map, design principles
- docs/drive-access.md — drive sessions, SCSI transport, unlock

Code cleanup:
- Zero compiler warnings
- Removed all debug eprintln from library code
- No hardcoded private paths — KEYDB tests use KEYDB_PATH env var
- KEYDB search locations as named constants
- drive.rs: extracted create_platform(), deduplicated open methods
- lib.rs: updated doc examples to show Disc::scan() API
- Fixed UDF file reads (partition_start, not metadata_start)
- Exported KeySource from disc module
This commit is contained in:
MattJackson
2026-04-07 12:12:24 -07:00
parent 721308cb8e
commit 272215c551
14 changed files with 1481 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/lib.rs
+41 -42
View File
@@ -1,72 +1,70 @@
//! libfreemkv — Open source optical drive library for 4K UHD / Blu-ray / DVD.
//!
//! Drive access, disc format parsing, and raw sector reading in one library.
//! 206 bundled drive profiles. No external files, no configuration.
//! Handles drive access, disc structure parsing, AACS decryption, and raw
//! sector reading. 206 bundled drive profiles. No external files needed.
//!
//! # Drive Access
//! # Quick Start
//!
//! ```no_run
//! use libfreemkv::DriveSession;
//! use libfreemkv::{DriveSession, Disc, ScanOptions};
//! use std::path::Path;
//!
//! // Open drive — profiles are bundled, auto-identify
//! let mut session = DriveSession::open(Path::new("/dev/sr0")).unwrap();
//! let disc = Disc::scan(&mut session, &ScanOptions::default()).unwrap();
//!
//! // Drive identity
//! println!("{} {}", session.drive_id.vendor_id.trim(), session.drive_id.product_id.trim());
//! for title in &disc.titles {
//! println!("{} — {} streams", title.duration_display(), title.streams.len());
//! }
//!
//! // Unlock and read raw sectors
//! session.unlock().unwrap();
//! session.calibrate().unwrap();
//! let mut buf = vec![0u8; 2048];
//! session.read_sectors(0, 1, &mut buf).unwrap();
//! ```
//!
//! # Disc Scanning
//!
//! ```no_run
//! # use libfreemkv::{DriveSession, Disc, Title, Stream, StreamKind};
//! # use std::path::Path;
//! # let mut session = DriveSession::open(Path::new("/dev/sr0")).unwrap();
//! // Scan disc structure — UDF filesystem, MPLS playlists, CLPI clip info
//! // (API in progress — Disc::scan() coming soon)
//!
//! // Each title has typed streams:
//! // stream.codec → Codec::Hevc / Codec::TrueHd / Codec::Ac3 / Codec::Pgs
//! // stream.pid → 0x1100
//! // stream.language → "eng"
//! // stream.hdr → HdrFormat::Hdr10 / HdrFormat::DolbyVision
//! // Read content (decrypted automatically if AACS keys available)
//! let mut reader = disc.open_title(&mut session, 0).unwrap();
//! while let Some(unit) = reader.read_unit().unwrap() {
//! // 6144 bytes of decrypted content per unit
//! }
//! ```
//!
//! # Architecture
//!
//! ```text
//! DriveSession — open, identify, unlock, read sectors
//! ├── ScsiTransport — SG_IO (Linux), IOKit (macOS planned)
//! ├── DriveProfile — per-drive unlock parameters (206 bundled)
//! ├── DriveId — INQUIRY + GET_CONFIG 010C identification
//! DriveSession — open, identify, unlock, read sectors
//! ├── ScsiTransport — SG_IO (Linux), IOKit (macOS planned)
//! ├── DriveProfile — per-drive unlock parameters (206 bundled)
//! ├── DriveId — INQUIRY + GET_CONFIG identification
//! └── Platform
//! └── Mt1959 — MediaTek unlock/read (Renesas planned)
//! └── Mt1959 — MediaTek unlock/read (Renesas planned)
//!
//! Disc — scan titles, streams, sector ranges
//! ├── UDF reader — Blu-ray UDF 2.50 with metadata partitions
//! ├── MPLS parser — playlists → titles + clips + STN streams
//! └── CLPI parser — clip info → EP map → sector extents
//! Disc — scan titles, streams, AACS state
//! ├── UDF reader — Blu-ray UDF 2.50 with metadata partitions
//! ├── MPLS parser — playlists → titles + clips + STN streams
//! ├── CLPI parser — clip info → EP map → sector extents
//! ├── JAR parser — BD-J audio track labels
//! └── AACS — encryption: key resolution + content decrypt
//! ├── aacs — KEYDB, VUK, MKB, unit decrypt
//! └── handshake — SCSI auth, ECDH, bus key
//! ```
//!
//! # AACS Encryption
//!
//! Disc scanning automatically detects and handles AACS encryption.
//! If a KEYDB.cfg is available (via `ScanOptions` or standard paths),
//! the library resolves keys and decrypts content transparently.
//!
//! Supports AACS 1.0 (Blu-ray) and AACS 2.0 (UHD, with fallback).
//!
//! # Error Codes
//!
//! All errors are structured with numeric codes (E1000-E6000).
//! No user-facing English text — applications format their own messages.
//! All errors are structured with numeric codes. No user-facing English
//! text — applications format their own messages.
//!
//! | Range | Category |
//! |-------|----------|
//! | E1xxx | Device errors (not found, permission) |
//! | E2xxx | Profile errors (unsupported drive, parse) |
//! | E3xxx | Unlock errors (failed, signature mismatch) |
//! | E2xxx | Profile errors (unsupported drive) |
//! | E3xxx | Unlock errors (failed, signature) |
//! | E4xxx | SCSI errors (command failed, timeout) |
//! | E5xxx | I/O errors |
//! | E6xxx | Disc format errors |
//! | E7xxx | AACS errors |
pub mod error;
pub mod scsi;
@@ -90,4 +88,5 @@ pub use profile::{DriveProfile, Chipset};
pub use platform::{Platform, DriveStatus};
pub use scsi::ScsiTransport;
pub use speed::DriveSpeed;
pub use disc::{Disc, Title, Stream, StreamKind, Codec, HdrFormat, ColorSpace, Extent, ContentReader, AacsState, ScanOptions};
pub use disc::{Disc, Title, Stream, StreamKind, Codec, HdrFormat, ColorSpace,
Extent, ContentReader, AacsState, KeySource, ScanOptions};