Crate libfreemkv 

libfreemkv – Open source optical drive library for 4K UHD / Blu-ray / DVD.

Handles drive access, disc structure parsing, AACS decryption, and raw sector reading. Drive unlocking is pluggable: libfreemkv owns only the Unlocker seam and registry — firmware blobs and unlock CDBs live in an external crate (e.g. freemkv-unlock-ld).

Quick Start

use libfreemkv::{Drive, Disc, ScanOptions, find_drive};

let mut drive = find_drive().expect("no optical drive found");
drive.wait_ready().unwrap();
drive.init().unwrap();
let disc = Disc::scan(&mut drive, &ScanOptions::default()).unwrap();

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

Muxing to an output container runs through the PES pipeline. A live disc:// cannot be opened via input — it returns Error::DiscUrlNotDirect by design (use Drive + Disc::scan + DiscStream::new directly for a live drive). Any file-backed source (iso://, m2ts://) opens through input:

let opts = libfreemkv::InputOptions::default();
let mut input = libfreemkv::input("iso://disc.iso", &opts)?;
let title = input.info().clone();
let mut output = libfreemkv::output("mkv://Movie.mkv", &title)?;
// Propagate read errors instead of silently stopping on the first one.
while let Some(frame) = input.read()? {
    output.write(&frame)?;
}
output.finish()?;

Architecture

Drive           -- open, identify, unlock, read sectors
  ├── ScsiTransport    -- SG_IO (Linux), IOKit (macOS)
  ├── DriveId          -- INQUIRY + GET_CONFIG identification
  └── Unlocker         -- pluggable, external (e.g. freemkv-unlock-ld);
                          libfreemkv owns only the trait + registry

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. 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 errors (fetch, parse, load)
E9xxx	Stream / mux errors (URL, PES, pipeline)

Re-exports

pub use verify::SectorRange;

pub use verify::SectorStatus;

pub use verify::VerifyResult;

pub use verify::verify_title;

pub use drive::capture::CapturedFeature;

pub use drive::capture::DriveCapture;

pub use drive::capture::capture_drive_data;

pub use drive::capture::mask_bytes;

pub use drive::capture::mask_string;

pub use drive::Drive;

pub use drive::DriveStatus;

pub use drive::find_drive;

pub use error::Error;

pub use error::Result;

pub use halt::Halt;

pub use io::pipeline::DEFAULT_PIPELINE_DEPTH;

pub use io::pipeline::Flow;

pub use io::pipeline::Pipeline;

pub use io::pipeline::READ_PIPELINE_DEPTH;

pub use io::pipeline::Sink;

pub use io::pipeline::WRITE_PIPELINE_DEPTH;

pub use io::pipeline::WRITE_THROUGH_DEPTH;

pub use event::BatchSizeReason;

pub use event::Event;

pub use event::EventKind;

pub use unlock::UnlockError;

pub use unlock::Unlocker;

pub use unlock::register_unlocker;

pub use decrypt::DecryptKeys;

pub use decrypt::decrypt_sectors;

pub use decrypt::decrypt_threads;

pub use decrypt::set_decrypt_threads;

pub use disc::AacsState;

pub use disc::AudioChannels;

pub use disc::AudioStream;

pub use disc::Clip;

pub use disc::Codec;

pub use disc::ColorSpace;

pub use disc::ContentFormat;

pub use disc::DamageSeverity;

pub use disc::Disc;

pub use disc::DiscFormat;

pub use disc::DiscId;

pub use disc::DiscTitle;

pub use disc::DriveCredentials;

pub use disc::Extent;

pub use disc::ExtractOptions;

pub use disc::ExtractResult;

pub use disc::FileResult;

pub use disc::FrameRate;

pub use disc::HdrFormat;

pub use disc::Key;

pub use disc::KeyOrigin;

pub use disc::LabelPurpose;

pub use disc::LabelQualifier;

pub use disc::PatchOptions;

pub use disc::PatchOutcome;

pub use disc::Resolution;

pub use disc::SampleRate;

pub use disc::ScanOptions;

pub use disc::Stream;

pub use disc::SubtitleStream;

pub use disc::SweepOptions;

pub use disc::VideoStream;

pub use disc::classify_damage;

pub use keysource::DiscInputs;

pub use keysource::KeySource;

pub use keysource::read_encrypted_units;

pub use keysource::resolve_and_apply;

pub use pes::PesFrame;

pub use pes::Stream as PesStream;

pub use mux::DiscStream;

pub use mux::M2tsStream;

pub use mux::MkvStream;

pub use mux::NetworkStream;

pub use mux::NullStream;

pub use mux::StdioStream;

pub use mux::WriteSeek;

pub use mux::InputOptions;

pub use mux::StreamUrl;

pub use mux::input;

pub use mux::output;

pub use mux::parse_url;

pub use mux::build_iso_pipeline;

pub use scsi::DriveInfo;

pub use scsi::ScsiSense;

pub use scsi::ScsiTransport;

pub use scsi::drive_has_disc;

pub use scsi::list_drives;

pub use sector::DecryptingSectorSource;

pub use sector::FileSectorSink;

pub use sector::FileSectorSource;

pub use sector::KeyFetch;

pub use sector::PrefetchedSectorSource;

pub use sector::SectorSink;

pub use sector::SectorSource;

Modules

aacs

AACS decryption — Volume Unique Key lookup and title key derivation.

consts

Physical media constants — the single source of truth.

css

CSS (Content Scramble System) — DVD disc encryption.

decrypt

Decrypt-on-read layer.

diag

Structured scan diagnostics — the --log-level 3 self-diagnosing dump.

disc

Disc structure – scan titles, streams, and sector ranges from a Blu-ray disc.

drive

Drive session — open, identify, and read from optical drives.

dvdnav

DVD-Video navigation — read-only resolver for the main-feature start point (issue #40). Mirrors what a DVD player’s nav VM resolves: First-Play → menu “Play” → title dispatch → the first cell of the feature, so the rip starts at the movie rather than at raw cell 0 (e.g. skipping a leading logo/warning segment when the disc’s own navigation does).

error

Error types for libfreemkv.

event

Event system for progress and status reporting.

halt

One-bit cooperative cancellation flag.

io

File I/O helpers that bound kernel cache pressure on big writes.

keysource

Key sources — the layer that hands libfreemkv a disc’s terminal Unit Keys.

labels

Stream label extraction from BD-J disc files.

mux

Stream-based I/O pipeline.

pes

Stream — read PES frames in, write PES frames out.

progress

Pipeline-progress reporting for the rip pipeline.

scsi

SCSI/MMC command interface.

sector

Sector-level I/O traits.

unlock

Pluggable drive-unlock seam.

verify

Disc sector verification — read every sector and classify health.

Structs

DriveId

Drive identity from standard SCSI commands.

UdfFs

A UDF filesystem parsed from disc.

Enums

DriveSpeed

Common optical drive speeds with KB/s values for SET_CD_SPEED.

Constants

MUX_APP

The muxing/writing-application string written into MKV output ("freemkv <version> (g<hash>)").

VERSION_LABEL

Single source of truth for every freemkv version surface.

Functions

read_filesystem

Read the UDF filesystem from a Blu-ray disc.