opticaldiscs

Format-agnostic optical disc image reading and filesystem browsing for Rust.

Provides a unified SectorReader abstraction that handles the cooked/raw sector translation across container formats — ISO, BIN/CUE, CHD, CloneCD, Nero (NRG), Alcohol 120% (MDS/MDF), DiscJuggler (CDI), DAEMON Tools (MDX), PSP CSO, gzip, and Nintendo (GameCube/Wii) — with filesystem browsers for ISO 9660, UDF, HFS/HFS+, SGI EFS, and many more on top.

Status: Published on crates.io. Disc reading, detection, and filesystem browsing are complete and in production use; physical-disc ripping is the next milestone. See PLAN.md for the roadmap.

CHD support

opticaldiscs-rs reads CHD optical images via libchdman-rs, which wraps MAME's official chd_file core. This provides byte-for-byte parity with the chdman tool — including subcode handling, audio byte-swapping, and per-track frame semantics — at the cost of needing to link MAME's C++ code.

libchdman-rs 0.288.10 is a hard floor (since opticaldiscs 0.14.0). Earlier versions abort the process when handed a CHD without CD track metadata — a hard-disk, DVD, or A/V image — and since .chd detection keys on magic bytes common to every CHD, that was reachable from DiscImageInfo::open.

CHD is a container, not a disc format

The same MComprHD magic fronts CD, GD-ROM, DVD, hard-disk and A/V images, so identifying a file as a CHD says nothing about how to read it. chd::chd_media() classifies it from the info record (cheap — no track parsing), and the media kind picks the reader:

DiscImageInfo::open and browse::open_disc_filesystem do this dispatch internally, so callers just pass a .chd path and get the right reader.

This lives behind the chd feature, on by default. Because linking MAME's C++ core isn't possible everywhere, it can be dropped entirely with default-features = false — libchdman-rs then leaves the dependency graph, and every other container and filesystem keeps working. .chd files stay recognised either way; see Feature Flags for the runtime is_supported() queries.

By default, opticaldiscs-rs enables libchdman-rs's prebuilt feature, which downloads a pre-built static archive matching the build target from libchdman-rs's GitHub Releases instead of compiling MAME from source. This keeps CI build times in seconds, not minutes.

When you might need to override prebuilt behavior

See libchdman-rs's README for the full list of supported targets, glibc floors, and escape hatches.

Features

Quick Example

use opticaldiscs::detect::DiscImageInfo;
use opticaldiscs::browse;

let info = DiscImageInfo::open("disc.iso")?;
println!("Volume: {:?}", info.volume_label);
println!("Filesystem: {}", info.filesystem.display_name());

let mut fs = browse::open_disc_filesystem(&info)?;
let root = fs.root()?;
for entry in fs.list_directory(&root)? {
    println!("{:<40} {}", entry.name, entry.size_string());
}

Cargo.toml

opticaldiscs = "0.14"

# with optional features
opticaldiscs = { version = "0.14", features = ["toc", "drives", "mdx"] }

# without CHD — no libchdman-rs, no MAME C++ core, no build-time download.
# For targets its prebuilt matrix doesn't cover and that can't compile MAME
# (i486/i586, PowerPC, vintage macOS/Windows, offline builds).
opticaldiscs = { version = "0.14", default-features = false, features = ["toc"] }

To track unreleased changes, depend on the git repository instead:

opticaldiscs = { git = "https://github.com/danifunker/opticaldiscs-rs" }

Feature Flags

chd and mdx gate a container's read path, not its recognition. Without either one, matching files are still identified — DiscFormat::Chd / DiscFormat::Mdx from the extension and from magic bytes — and opening one returns UnsupportedFormat with a message naming the missing feature. That lets a caller say "this is a CHD, but CHD support wasn't built in" instead of "unknown file".

Asking at runtime what this build supports

Rather than sprinkling cfg!(feature = "chd") through your own code, query the crate:

use opticaldiscs::DiscFormat;

// Direct: is CHD reading compiled in?
if opticaldiscs::chd::is_supported() {
    // `.chd` can be opened and browsed.
}

// General: works for any conditionally-compiled format.
assert!(DiscFormat::Iso.is_supported());
if !DiscFormat::Chd.is_supported() {
    // Grey out the CHD entry in the UI instead of failing on open.
}

// File-open dialogs: `supported_extensions()` is everything the crate can
// identify; `enabled_extensions()` is what this build can actually open.
let filter = opticaldiscs::enabled_extensions();

// Enumerate every known format and filter it yourself.
let usable: Vec<_> = DiscFormat::ALL
    .iter()
    .copied()
    .filter(|f| f.is_supported())
    .collect();

The chd module itself always compiles: ChdTrack, ChdTrackType, ChdInfo and their helpers are plain Rust and stay available in a lean build, so code that names those types keeps compiling. Only open_chd and ChdSectorReader — the parts that touch MAME's C++ core — are gated.

Used By

• rusty-backup — vintage disc backup/restore tool
• ODE-artwork-downloader — USBODE cover art downloader

License

GPL-3.0 — see LICENSE.