disclady 0.4.0

Pure Rust library and CLI utility for optical and storage disc image heuristics, inspection, and format detection (CD, DVD, GDI, Hard Disk, LaserDisc, CHD).
Documentation
#![forbid(unsafe_code)]
//! Heuristic inspection, format classification, and metadata extraction library for optical discs and storage images.
//!
//! `disclady` parses raw byte layouts, sector headers, partition structures, filesystem
//! descriptors, container metadata, and physical optical drive transports without needing
//! external CLI utilities or complete image decompression.
//!
//! # Supported Formats and Transports
//!
//! - **Compact Disc**: CUE sheets (`.cue`), CloneCD descriptors (`.ccd` with `.img`/`.sub`), Alcohol 120% descriptors (`.mds` v1 and v2 with `.mdf`), DAEMON Tools containers (`.mdx`), Nero Burning ROM containers (`.nrg`), standalone raw binary tracks (`.bin`, `.img`, 2352 or 2448 bytes per sector), and ISO 9660 images.
//! - **DVD**: Standard ISO images (`.iso`), ISO 9660 Primary Volume Descriptors, UDF Volume Recognition Sequences, DVD-Video (`VIDEO_TS`), and DVD-Audio (`AUDIO_TS`).
//! - **Dreamcast GD-ROM**: `.gdi` multi-track descriptors with low-density and high-density partition boundaries (LBA 45000).
//! - **Hard Disk**: Raw storage dumps (`.img`, `.raw`, 512 bytes per sector), MBR/GPT partition tables, and arcade drive headers.
//! - **LaserDisc**: Uncompressed video captures (`.avi`) with PCM audio and YUY2/UYVY frames.
//! - **CHD Containers**: Reverse inspection of CHD v3, v4, and v5 containers without decompressing data hunks.
//! - **Physical Optical Discs**: Direct drive hardware inspection via SCSI/MMC pass-through on Linux (`/dev/sr0`, `/dev/cdrom`) and Windows (`\\.\D:`).
//!
//! # Metadata Extraction Pipeline
//!
//! The library includes a Tiered Fallback Pipeline for extracting human-readable game titles and
//! canonical alphanumeric product IDs across 16+ console and computer platforms, including:
//! - Sony PlayStation, PlayStation 2, PlayStation Portable (UMD)
//! - Sega Mega-CD / Sega CD, Sega Saturn, Sega Dreamcast
//! - Nintendo GameCube, Nintendo Wii
//! - Microsoft Xbox, Xbox 360
//! - 3DO Interactive Multiplayer, SNK Neo Geo CD, NEC PC Engine CD, NEC PC-FX, Commodore Amiga CD32
//!
//! # Online Database Matching
//!
//! When built with the optional `online` feature, `disclady` can match extracted disc metadata
//! against a remote compressed TSV database (`lib.db.zst`) to suggest standardized filenames and
//! resolve canonical game titles and serial IDs.
//!
//! # Media Classification
//!
//! Discs and storage images resolve to one of the primary variants in [`DiscType`]:
//! - [`DiscType::Cd`] - Compact Disc image or physical CD.
//! - [`DiscType::Dvd`] - Digital Versatile Disc image or physical DVD.
//! - [`DiscType::Gdi`] - Dreamcast GD-ROM image or physical GD-ROM.
//! - [`DiscType::HardDisk`] - Hard Disk raw storage dump.
//! - [`DiscType::LaserDisc`] - LaserDisc multimedia capture.
//! - [`DiscType::Unknown`] - Unrecognized format or non-media file.
//!
//! # Examples
//!
//! ### Inspecting an image on disk
//!
//! ```no_run
//! use disclady::{inspect_disc, DiscType};
//! use std::path::Path;
//!
//! # fn main() -> Result<(), disclady::DiscError> {
//! let descriptor = inspect_disc(Path::new("game.cue"))?;
//! println!("Media: {}", descriptor.disc_type);
//! if let Some(title) = descriptor.title() {
//!     println!("Title: {title}");
//! }
//! if let Some(disc_id) = descriptor.disc_id() {
//!     println!("Serial ID: {disc_id}");
//! }
//! for track in &descriptor.tracks {
//!     println!("Track {}: {} sectors", track.track_number, track.sector_size);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ### Quick format detection
//!
//! ```no_run
//! use disclady::{detect_disc_type, DiscType};
//! use std::path::Path;
//!
//! # fn main() -> Result<(), disclady::DiscError> {
//! let disc_type = detect_disc_type(Path::new("game.iso"))?;
//! if disc_type == DiscType::Dvd {
//!     println!("Detected DVD image");
//! }
//! # Ok(())
//! # }
//! ```

pub mod ccd;
pub mod chd;
pub mod console;
pub mod cue;
pub(crate) mod detector;
pub mod gdi;
pub(crate) mod harddisk;
pub mod iso;
pub(crate) mod laserdisc;
pub mod mds;
pub mod mdx;
pub mod metadata;
pub mod nrg;
#[cfg(feature = "online")]
pub mod online;
#[cfg(feature = "physical")]
pub mod physical;
pub mod raw;
pub mod types;

pub use chd::{inspect_chd, ChdExtractionPlan};
pub use cue::synthesize_cue_for_image;
pub use detector::{
    detect_disc_from_reader, detect_disc_type, inspect_disc, CD_MAX_PHYSICAL_BYTES,
};
pub use metadata::{DiscMetadata, DiscReader, GameId, MetadataSource, PlatformKind};
#[cfg(feature = "online")]
pub use online::{
    normalize_serial_key, suggest_filename, OnlineDatabase, OnlineDbEntry, OnlineMatch,
    DEFAULT_ONLINE_DB_URL,
};
#[cfg(feature = "physical")]
pub use physical::{
    inspect_physical_disc, inspect_physical_transport, is_physical_disc_path, list_optical_drives,
};
pub use types::{
    Confidence, DiscDescriptor, DiscError, DiscType, Platform, TrackDescriptor, TrackType,
    VolumeInfo,
};

/// Extracts referenced child track files (such as `.bin`, `.wav`, `.raw`, `.img`, `.sub`, or `.mdf`)
/// from multi-file descriptor formats (`.cue`, `.gdi`, `.ccd`, `.mds`).
///
/// Returns an empty list if the path does not point to a supported descriptor format.
///
/// # Examples
///
/// ```no_run
/// use disclady::extract_referenced_files;
/// use std::path::Path;
///
/// let track_files = extract_referenced_files(Path::new("game.cue"));
/// for file in track_files {
///     println!("Referenced child file: {}", file.display());
/// }
/// ```
pub fn extract_referenced_files<P: AsRef<std::path::Path>>(
    descriptor_path: P,
) -> Vec<std::path::PathBuf> {
    let path = descriptor_path.as_ref();
    if let Some(ext) = path.extension().and_then(|e| e.to_str()) {
        if ext.eq_ignore_ascii_case("cue") {
            return cue::extract_cue_referenced_files(path);
        } else if ext.eq_ignore_ascii_case("gdi") {
            return gdi::extract_gdi_referenced_files(path);
        } else if ext.eq_ignore_ascii_case("ccd") {
            return ccd::extract_ccd_referenced_files(path);
        } else if ext.eq_ignore_ascii_case("mds") {
            return mds::extract_mds_referenced_files(path);
        } else if ext.eq_ignore_ascii_case("mdx") {
            return mdx::extract_mdx_referenced_files(path);
        } else if ext.eq_ignore_ascii_case("nrg") {
            return nrg::extract_nrg_referenced_files(path);
        }
    }
    Vec::new()
}