Spice86.Storage.Cd 15.0.0

Spice86.Storage.Cd

Read CD-ROM disc images (ISO 9660, CUE/BIN, Alcohol 120% MDS/MDF) and decode CDDA audio (WAVE) from .NET, without any native dependency.

This assembly ships as a standalone NuGet package. It has no project references (no Spice86 dependency) and uses only the .NET base class library. The behavioural reference is dosbox-staging's CD-ROM stack in dosbox-staging/src/dos/cdrom_image.cpp and cdrom_mds.h.

CD-ROM standards (the "rainbow books")

CD-ROM image formats are layered on top of the physical CD specifications known as the "rainbow books". This assembly is concerned with the data geometry described by Red Book, Yellow Book and parts of Green Book / White Book; ISO 9660 / Joliet sit on top.

ISO 9660 and the Joliet supplementary volume descriptor describe the logical filesystem. track. Both are parsed by IsoImage and used by CueBinImage and MdsImage to expose PrimaryVolume / JolietVolume metadata.

Supported image formats

Namespace root: Spice86.Shared.Emulator.Storage.CdRom.

All readers expose the same ICdRomImage interface:

public interface ICdRomImage : IDisposable {
 IReadOnlyList<CdTrack> Tracks { get; }
 int TotalSectors { get; }
 int Read(int lba, Span<byte> destination, CdSectorMode mode);
 IsoVolumeDescriptor PrimaryVolume { get; }
 string? UpcEan { get; }
 string ImagePath { get; }
}

A factory selects the implementation from the file extension:

using Spice86.Shared.Emulator.Storage.CdRom;

using ICdRomImage disc = CdRomImageFactory.Open(@"C:\game.cue");
Span<byte> buffer = stackalloc byte[2048];
disc.Read(lba: 16, buffer, CdSectorMode.CookedData2048); // ISO 9660 PVD

Sector modes

CdSectorMode captures the on-disc encodings recognised by this assembly. They correspond one-to-one to the modes accepted by dosbox-staging's CUE parser (MODE1/2048, MODE1/2352, MODE2/2336, MODE2/2352, AUDIO):

SectorFraming and CueFrameMapper handle the byte-offset arithmetic for Mode 1 / Mode 2 sync, header and sub-header sizes, so the Read(lba, ...) API always returns user data in the requested mode.

CUE/BIN parser

CueSheetParser.Parse(cuePath) is a tolerant CUE sheet parser that implements the directives required by real-world DOS game images:

• CATALOG <upc-ean> (13 ASCII digits) — exposed as ICdRomImage.UpcEan.
• FILE "<name>" <type> — file reference. Supported types are listed in CueFileType: BINARY, MOTOROLA, WAVE, AIFF, MP3, FLAC, OGG, OPUS. Audio decoding is dispatched through IAudioCodecFactory.
• TRACK <nn> <mode> — track number 1..99 with one of the modes mapped above.
• PREGAP MM:SS:FF and POSTGAP MM:SS:FF — silent frames before/after a track. Parsed and surfaced as CueTrackLayout.PregapFrames / PostgapFrames.
• INDEX <nn> MM:SS:FF — multiple index points per track. Index 00 is the pregap start, index 01 is the track start.
• ISRC <code> — accepted and ignored (no MSCDEX consumer in scope).
• REM ... — comments are ignored.

CueFrameMapper.BuildLayout resolves absolute LBA positions across all tracks and BIN files, including implicit pregap derived from the difference between INDEX 00 and INDEX 01.

Audio support is intentionally limited to WAV (WavAudioCodec / WavAudioCodecFactory). DefaultAudioCodecFactory.Create() returns a CompositeAudioCodecFactory wired with WAV only. Callers can extend the factory by composing additional IAudioCodecFactory implementations; the CUE parser will then accept the corresponding FILE ... <TYPE> references.

MDS / MDF parser

MdsImage opens the .mds descriptor file, defers parsing to MdsParser, and binds the resolved tracks to one or more .mdf data files via FileBackedDataSource.

• 88-byte header. Validated by MdsParser.Signature ("MEDIA DESCRIPTOR").
• Session block (24 bytes) at session_block_offset. num_all_blocks tracks are read consecutively from track_block_offset.
• Each 80-byte track block references an 8-byte extra block (track length in sectors) and a 16-byte footer (filename pointer, ANSI/UTF-16 flag).
• MdsTrackMode recognises Red Book audio (attribute 0x00), Mode 1 data (attribute 0x40, mode2 = false) and Mode 2 data (attribute 0x40, mode2 = true). DVD-only XA forms 4/5/6 are rejected
• Non-track entries (point < 1 or > 99) are skipped.
• A synthetic lead-out entry is appended after the last track so callers can iterate up to the end of the disc.

*.mdf filenames inside the descriptor resolve relative to the directory that contains the .mds. A footer filename of "*.mdf" is rewritten to <descriptor>.mdf (Alcohol 120% convention).

ISO 9660 and Joliet

IsoImage (and the embedded ISO parsing inside CueBinImage / MdsImage) reads the Primary Volume Descriptor at LBA 16, validates the "CD001" signature at offset 1, and exposes:

• Volume identifier (32 ASCII chars, trimmed).
• Logical block size (typically 2048).
• Volume space size in sectors.
• Root directory LBA and size.

IsoSupplementaryVolumeDescriptor decodes the optional Joliet SVD, recognised by the escape sequence at offset 88 being one of %2F40, %2F43, %2F45 (UCS-2 BE levels 1/2/3). When present, IsoImage.JolietVolume is populated and IsoImage.ReadJolietRootDirectory() returns the long-name entries decoded with Encoding.BigEndianUnicode.

Rock Ridge (POSIX file metadata) and El Torito (bootable CDs) are not parsed in this version.

Data sources and lifecycle

All image readers consume sector bytes through IDataSource. The implementations included in this assembly:

• FileBackedDataSource — owns a FileStream, reads sectors from disk with an internal lock for thread safety, exposes LengthBytes.
• MemoryDataSource — wraps a byte[] (used by unit tests and the virtual ISO builder).
• WindowedDataSource — restricts a parent source to a [offset, length) window (used to slice multi-track BIN files into per-track views).
• WavAudioFile — exposes a WAV PCM payload as a IDataSource whose bytes are CDDA-ordered samples.

ICdRomImage is IDisposable; disposing the image disposes every owned FileBackedDataSource and codec instance.

Image construction

VirtualIsoImage builds a minimal ISO 9660 single-track image in memory from a host directory. It writes a Primary Volume Descriptor, a Volume Descriptor Set Terminator and a single-level root directory; it is intended for tests and tooling rather than for authoring distribution discs.

Working set

Implemented:

• ISO 9660 Primary Volume Descriptor (read).
• Joliet Supplementary Volume Descriptor (read, UCS-2 BE).
• CUE/BIN parsing with all five dosbox-staging-recognised track modes.
• WAV audio file decoding for CDDA tracks in CUE sheets.
• Alcohol 120% MDS/MDF parsing with synthetic lead-out (first session only).
• Sector-level Read(lba, span, mode) API on all image types.
• UPC/EAN catalogue passthrough.
• In-memory ISO image construction via VirtualIsoImage.

Example

using Spice86.Shared.Emulator.Storage.CdRom;

using ICdRomImage disc = CdRomImageFactory.Open(@"C:\game.cue");
Console.WriteLine($"Volume: {disc.PrimaryVolume.VolumeIdentifier}");
Console.WriteLine($"Tracks: {disc.Tracks.Count}");
Console.WriteLine($"Sectors: {disc.TotalSectors}");

foreach (CdTrack track in disc.Tracks) {
 Console.WriteLine($" #{track.Number,-2} {track.Mode,-15} start={track.StartLba,-8} length={track.LengthSectors}");
}

byte[] pvdSector = new byte[2048];
disc.Read(16, pvdSector, CdSectorMode.CookedData2048);

DOS CDDA Assembly Example

A standalone 16-bit DOS MSCDEX CDDA player example (ASM + COM + launcher batch) is provided here:

• examples/cdda-assembly/cdda_mscdex_loop.asm
• examples/cdda-assembly/CDDA.COM
• examples/cdda-assembly/launch_mw2_cdda.bat
• examples/cdda-assembly/README.md

This is example content only and is not part of the assembly build output.

License

Apache-2.0. See LICENSE at the root of the Spice86 repository.