opticaldiscs 0.4.4

Format-agnostic optical disc image reading and filesystem browsing (ISO, BIN/CUE, CHD)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# opticaldiscs

[![CI](https://github.com/dani/opticaldiscs-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/dani/opticaldiscs-rs/actions)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE)

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

Provides a unified `SectorReader` abstraction that handles the cooked/raw sector
translation across three container formats — **ISO**, **BIN/CUE**, and **CHD** — with
filesystem browsers for **ISO 9660**, **HFS**, **HFS+**, and **SGI EFS** on top.

> **Status:** Early development. See [PLAN.md](PLAN.md) for the implementation roadmap.

## CHD support

opticaldiscs-rs reads CHD optical images via [libchdman-rs](https://github.com/danifunker/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.

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

| Situation | Set env var |
|---|---|
| Target triple isn't covered by libchdman-rs's prebuilt matrix | `LIBCHDMAN_PREBUILT_FALLBACK=1` |
| Local development without network access | `LIBCHDMAN_FORCE_SOURCE=1` |
| Linux: pick a specific glibc floor for the prebuilt archive | `LIBCHDMAN_GLIBC=2.31` (or `2.35`, `2.39`) |

See [libchdman-rs's README](https://github.com/danifunker/libchdman-rs#pre-built-static-archives-faster-ci-builds)
for the full list of supported targets, glibc floors, and escape hatches.

## Features

| Capability | Status |
|---|---|
| ISO sector reader | Phase 2 |
| BIN/CUE sector reader (raw 2352-byte) | Phase 3 |
| CHD sector reader | Phase 4 |
| TOC + MusicBrainz/FreeDB DiscID | Phase 5 (`toc` feature) |
| Disc format + filesystem auto-detection | Phase 6 |
| ISO 9660 filesystem browser | Phase 7 |
| HFS / HFS+ filesystem browser | Phase 8 |
| SGI Volume Header + EFS filesystem browser (IRIX CDs) | 0.3.0 |
| Physical optical drive enumeration | Phase 9 (`drives` feature) |

## Quick Example

```rust
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

```toml
# git dependency while API stabilises
opticaldiscs = { git = "https://github.com/dani/opticaldiscs-rs" }

# with optional features
opticaldiscs = { git = "...", features = ["toc", "drives"] }
```

## Feature Flags

| Flag | Enables | Extra deps |
|---|---|---|
| `toc` | `DiscTOC`, MusicBrainz DiscID, FreeDB ID | `sha1`, `base64` |
| `drives` | `list_drives()` — enumerate physical optical drives | — |

## Used By

- [rusty-backup](https://github.com/dani/rusty-backup) — vintage disc backup/restore tool
- [ODE-artwork-downloader](https://github.com/dani/ODE-artwork-downloader) — USBODE cover art downloader

## License

GPL-3.0 — see [LICENSE](LICENSE).