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

disclady

disclady is a disc image inspection library and command-line tool. It reads optical disc images, physical optical drives, raw hard drive dumps, and CHD containers, identifies their media type, extracts track layouts, detects the target gaming platform, extracts game title and serial IDs, and matches metadata against an online database to suggest standardized filenames.

What It Inspects

The tool analyzes disc headers, sector structures, native platform signatures, and filesystem volume descriptors to classify files into five media categories:

  • CD: Cue sheets (.cue with .bin or .wav files), CloneCD descriptors (.ccd with .img and .sub), Alcohol 120% descriptors (.mds with .mdf, supporting v1.x and v2.0), DAEMON Tools containers (.mdx), Nero Burning ROM containers (.nrg), standalone raw disc images (.bin, .img, 2352 or 2448 bytes per sector), and ISO images.
  • DVD: Single and dual-layer DVD images (.iso), DVD-Video structures with VIDEO_TS, and DVD-Audio with AUDIO_TS.
  • GDI: Dreamcast Gigabyte Disc sets with low-density and high-density partition layouts (LBA 45000).
  • Hard Disk: Raw sector dumps (.img, .raw, 512 bytes per sector), MBR/GPT partition tables, and arcade drive images (Midway, Konami, Capcom, Namco, Sega).
  • LaserDisc: Uncompressed video captures (.avi) with PCM audio and YUY2/UYVY video frames.
  • CHD Containers: Reverse inspection of CHD files (v3, v4, v5) without decompressing audio or data hunks, including raw subcode detection and extraction format viability analysis.
  • Physical Optical Discs: Direct drive hardware inspection on Linux (/dev/sr0, /dev/cdrom) and Windows (D:, \\.\D:) via SCSI/MMC commands (READ TOC, READ DVD STRUCTURE, GET CONFIGURATION).

Console and Computer Platforms

It recognizes gaming and computer platforms from native boot sectors, volume descriptors, and internal executables via a Tiered Fallback Pipeline:

  • Sony PlayStation (SYSTEM.CNF, PS-X EXE, licensing strings)
  • Sony PlayStation 2 (SYSTEM.CNF)
  • Sony PlayStation Portable (UMD_DATA.BIN, PSP_GAME/PARAM.SFO)
  • Sega Mega-CD / Sega CD (SEGADISCSYSTEM, SEGADISC volume headers)
  • Sega Saturn (SEGA SEGASATURN system identifier)
  • Sega Dreamcast (SEGA SEGAKATANA IP.BIN headers)
  • Nintendo GameCube & Wii (boot.bin header structures)
  • Microsoft Xbox & Xbox 360 (XDVDFS volume descriptors)
  • 3DO Interactive Multiplayer (3DO filesystem volume headers)
  • SNK Neo Geo CD (NEO-GEO CD system signatures)
  • NEC PC Engine CD / TurboGrafx-CD (PC-Engine CD-ROM SYSTEM headers)
  • NEC PC-FX (PC-FX native boot headers)
  • Commodore Amiga CD32 (Rigid Disk Block, filesystem headers)

Platforms

disclady runs identically on Linux and Windows. Format decoders and inspection routines use standard binary readers with no external system dependencies or platform-specific calls. Physical drive inspection uses native kernel pass-through mechanisms (SG_IO on Linux, SPTI on Windows).

Installation

Pre-compiled Releases

Download release bundles from the project Releases page on Codeberg. Each archive packages both chdress (GUI) and disclady (CLI):

  • Linux (x86_64, aarch64): chdress-<version>-<target>.tar.xz
  • Windows (x86_64): chdress-<version>-x86_64-pc-windows-gnu.zip

Extract the archive and move disclady (or disclady.exe on Windows) to a directory listed in your PATH.

Building from Source

Build the CLI using make:

# Build the disclady binary
make disclady

# Build release package with stripped and compressed binaries
make release

Or install with Cargo:

cargo install --path crates/disclady

Cargo Features

  • physical (enabled by default): Enables physical optical drive hardware probing and enumeration.
  • online (enabled by default): Enables remote database downloading and metadata matching via ureq and zstd.

CLI Usage

Run inspection on a disc image, directory, or physical drive:

disclady game.cue

Example output:

================================================================================
File:         game.cue
File Size:    131 bytes
================================================================================
Classification:
  Media Type:          CD
  Confidence:          Definitive
  Primary Sector Size: 2352 bytes
  Total Sectors:       22
  Total Calculated:    51,744 bytes (50.53 KiB)

Filesystem & Volume Info:
  Title:               RIDGE RACER TYPE 4
  Platform:            Sony PlayStation
  Serial / Game ID:    SLUS-00797
  Primary Volume:      ISO 9660 PVD
  System Identifier:   PLAYSTATION

Track Layout (2 tracks):
  Trk  Type         Sector Size Start LBA    Sectors    Pregap   File
  ---  ----         ----------- ---------    -------    ------   ----
  01   MODE1/2352   2352 B      0            11         -        game.bin
  02   AUDIO        2352 B      1            11         150      game.bin

Diagnostic Verdict:
  CUE sheet contains Red Book audio tracks or WAV files (CD-DA)
================================================================================

Online Database Matching

Pass -o or --online to query the remote title database (https://chdress.8101987.xyz/lib.db.zst) and suggest a canonical filename:

disclady -o game.cue
Filesystem & Volume Info:
  Suggested Filename:  R4 - Ridge Racer Type 4 (USA).cue
  Matched Game:        R4 - Ridge Racer Type 4 (USA) [SLUS-00797]
  Title:               RIDGE RACER TYPE 4
  Platform:            Sony PlayStation
  Serial / Game ID:    SLUS-00797

If no match is found, an explicit [No match in database] marker is displayed.

Listing Optical Drives

List optical drive devices available on the host machine:

disclady --drives
Detected Optical Drives:
  - /dev/sr0 (ASUS DRW-24D5MT)

You can directly inspect a physical disc inside an optical drive:

disclady /dev/sr0

JSON Output

Add --json for machine-readable output:

disclady --json -o game.iso
{
  "file": "game.iso",
  "file_size_bytes": 734003200,
  "disc_type": "CD",
  "confidence": "Definitive",
  "primary_sector_size": 2048,
  "total_sectors": 358400,
  "total_size_bytes": 734003200,
  "summary": "ISO 9660 PVD detected with Sony PlayStation license strings",
  "suggested_filename": "Wipeout (USA).iso",
  "matched_game": "Wipeout (USA)",
  "matched_serial": "SCUS-94301",
  "match_score": 1300,
  "volume_info": {
    "title": "WIPEOUT",
    "disc_id": "SCUS-94301",
    "platform": "Sony PlayStation",
    "volume_identifier": "SCUS_94301",
    "system_identifier": "PLAYSTATION",
    "volume_space_size": 358400,
    "logical_block_size": 2048,
    "has_iso9660": true,
    "has_udf": false,
    "has_dvd_video": false,
    "has_dvd_audio": false
  },
  "tracks": [
    {
      "track_number": 1,
      "track_type": "MODE1/2048",
      "sector_size": 2048,
      "start_lba": 0,
      "sector_count": 358400,
      "file_path": "game.iso",
      "is_audio": false
    }
  ]
}

Batch Directory Scanning

Pass a directory path to scan all images recursively:

disclady /path/to/roms/psx/

Library Usage

Add disclady to your dependencies:

[dependencies]
disclady = { path = "path/to/disclady" }

Inspect an image and read its metadata:

use disclady::{inspect_disc, DiscType};
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let descriptor = inspect_disc(Path::new("game.cue"))?;

    println!("Media Type: {}", descriptor.disc_type);
    println!("Sector Size: {} bytes", descriptor.primary_sector_size);

    for track in &descriptor.tracks {
        println!(
            "Track #{:02}: {} ({} bytes, LBA {})",
            track.track_number, track.track_type, track.sector_size, track.start_lba
        );
    }

    if let Some(platform) = descriptor.platform() {
        println!("Platform: {platform}");
    }
    if let Some(title) = descriptor.title() {
        println!("Title: {title}");
    }
    if let Some(disc_id) = descriptor.disc_id() {
        println!("Serial ID: {disc_id}");
    }

    Ok(())
}

If you only need the media classification without parsing full track tables:

use disclady::{detect_disc_type, DiscType};
use std::path::Path;

let disc_type = detect_disc_type(Path::new("game.iso"))?;
assert_eq!(disc_type, DiscType::Cd);

How Detection Works

Detection runs in layers to avoid unnecessary reading:

  1. Format-specific parsers: Files with .cue, .gdi, .ccd, .mds, .mdx, or .nrg extensions go directly to dedicated descriptor and container parsers that validate syntax, resolve child track files, and extract sector layouts.
  2. CHD metadata traversal: Files starting with MComprHD are parsed through CHD v3, v4, or v5 header decoders to read hunk maps and FourCC tags (CHT2, CHGT, DVD , GDDD, AVAV), detect raw subcode presence (has_raw_subcode), and determine extraction format viability (viable_extraction_formats) without decompressing data.
  3. Sector synchronization: Raw 2352-byte and 2448-byte CD tracks are identified by scanning for standard Red Book synchronization patterns (00 FF FF FF FF FF FF FF FF FF FF 00) at sector intervals.
  4. Volume recognition: Standard ISO images are scanned for ISO 9660 Primary Volume Descriptors at sector 16 (LBA 16), UDF Volume Recognition Sequences (BEA01, NSR02, NSR03), and Anchor Volume Descriptor Pointers at LBA 256.
  5. Physical boundary checks: Images over 900 MiB cannot physically be single-density Compact Discs and fall through to DVD or storage heuristics.
  6. Hard disk partition inspection: Raw drive images are validated by checking 512-byte sector alignment, partition tables (MBR/GPT), filesystem superblocks, and arcade copyright headers.

Testing

Run unit tests and doctests:

cargo test -p disclady

Or run all workspace quality checks:

make check

Testing Against Real Collections

You can run detection against an external directory of disc images without modifying test files:

DISCLADY_REAL_TEST_DIR=/path/to/collection cargo test test_external_sandbox_discs

The runner supports two modes:

  • Manifest mode: Put a manifest.tsv in the test folder with <file_or_folder>\t<expected_type> lines (such as cd, dvd, gdi, harddisk, laserdisc).
  • Convention mode: Name subdirectories with media tags (such as 01_cd/, ps2_dvd/, dreamcast_gdi/, arcade_hdd/). The test runner discovers image entry points automatically.

Documentation

API documentation is published on docs.rs. Generate and view local docs:

cargo doc --open -p disclady

License

Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).