libfreemkv

Rust library for 4K UHD / Blu-ray optical drives. Drive access, disc scanning, stream labels, AACS decryption, KEYDB updates, and content reading in one crate. Bundled drive profiles — no external files needed.

12+ MB/s sustained read speeds on BD. Full init: unlock, firmware upload, speed calibration — all from pure Rust.

Multi-lingual by design — the library outputs structured data and numeric error codes, never English text. Build any UI or localization on top.

API Documentation · Technical Docs

Part of the freemkv project.

Install

[dependencies]
libfreemkv = "0.6"

Quick Start

use libfreemkv::{DriveSession, Disc, ScanOptions};
use std::path::Path;

// Open drive — profiles are bundled, auto-identified
let mut session = DriveSession::open(Path::new("/dev/sr0"))?;
session.wait_ready()?;            // wait for disc
session.init()?;                   // unlock + firmware upload
session.probe_disc()?;             // probe disc surface for optimal speeds

// Scan disc — UDF, playlists, streams, AACS (all automatic)
let disc = Disc::scan(&mut session, &ScanOptions::default())?;

for title in &disc.titles {
    println!("{} — {} streams", title.duration_display(), title.streams.len());
}

// Read content (decrypted transparently if AACS keys available)
let mut reader = disc.open_title(&mut session, 0)?;
while let Some(unit) = reader.read_unit()? {
    // 6144 bytes of content per aligned unit
}

What It Does

• Drive access — open, identify, unlock, firmware upload, speed calibration, eject
• 12+ MB/s reads — auto-detects kernel transfer limits, sustained full speed
• Disc scanning — UDF 2.50 filesystem, MPLS playlists, CLPI clip info
• Stream labels — 5 BD-J format parsers (Paramount, Criterion, Pixelogic, CTRM, Deluxe)
• AACS decryption — transparent key resolution and content decrypt (1.0 + 2.0 bus decryption)
• KEYDB updates — download, verify, save from any HTTP URL (zero deps, raw TCP)
• Content reading — adaptive batch reads with automatic decryption and error recovery
• Stream I/O — unified stream pipeline for reading and writing any format

Streams

Stream	Input	Output	Transport
DiscStream	Yes	--	Optical drive via SCSI
IsoStream	Yes	--	Blu-ray ISO image file
MkvStream	Yes	Yes	Matroska container
M2tsStream	Yes	Yes	BD transport stream with FMKV metadata header
NetworkStream	Yes (listen)	Yes (connect)	TCP with FMKV metadata header
StdioStream	Yes (stdin)	Yes (stdout)	Raw byte pipe
NullStream	--	Yes	Discard sink (byte counter for benchmarks)

All streams implement the IOStream trait. open_input() and open_output() resolve URL strings to stream instances. All URLs use the scheme://path format — bare paths are rejected.

AACS decryption requires a KEYDB.cfg file. If available at ~/.config/aacs/KEYDB.cfg or passed via ScanOptions, the library handles everything — handshake, key derivation, and per-sector decryption — without the application needing to know anything about encryption.

Architecture

DriveSession           — open any drive, identify, init (optional), read sectors
  ├── ScsiTransport    — SG_IO (Linux), IOKit (macOS)
  ├── DriveProfile     — per-drive unlock parameters (bundled)
  └── PlatformDriver   — MediaTek (supported), Renesas (planned)

Disc                   — scan titles, streams, AACS state
  ├── UDF reader       — Blu-ray UDF 2.50 with metadata partitions
  ├── MPLS parser      — playlists → titles + clips + streams
  ├── CLPI parser      — clip info → EP map → sector extents
  ├── Labels           — 5 BD-J format parsers (detect + parse)
  ├── AACS             — key resolution + content decryption
  └── KEYDB            — download + verify + save

See docs/ for detailed technical documentation on each module.

Error Codes

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)
E3xxx	Unlock errors (failed, signature)
E4xxx	SCSI errors (command failed, timeout)
E5xxx	I/O errors
E6xxx	Disc format errors
E7xxx	AACS errors
E8xxx	KEYDB update errors

Platform Support

Platform	Status	Backend
Linux	Supported	SG_IO ioctl
macOS	Supported	IOKit SCSITask
Windows	Supported	SPTI

Contributing

Run freemkv drive-info --share with the freemkv CLI to contribute your drive's profile.

License

AGPL-3.0-only