CHDSharp 1.0.0

CHDSharpLib

Pure C# read-only CHD (Compressed Hunks of Data) library — V1–V5, all 10 codecs, parent/child chaining, parallel verification, 100% match with MAME chdman.

Fork of RomVault/CHDSharp by Gordon Jefferyes, extended with Zstd, AVHuff, V5 compressed map, random-access API, parent/child chaining, and parallel verification.

Installation

dotnet add package CHDSharp

Targets net8.0, net9.0, and net10.0. No native dependencies — all codecs (except Zstd via the pure-C# ZstdSharp.Port) are implemented from scratch in C#.

Quick Start

Verify a standalone CHD (parallel, fast)

using CHDSharp;
using CHDSharp.Models;

using Stream s = File.OpenRead("game.chd");
var result = Chd.CheckFile(s, "game.chd", deepCheck: true);

if (result.IsSuccess)
    Console.WriteLine($"V{result.Version} — SHA1: {result.Sha1Hex}");
else
    Console.WriteLine($"Error: {result.Error.GetMessage()}");

Verify a child (differential) CHD against its parent

var result = Chd.CheckFileWithParent("child.chd", "parent.chd");

Random-access reading

var err = ChdFile.Open("game.chd", out var chd);
if (err != ChdError.Chderrnone) return;

using (chd)
{
    // Inspect metadata (game name, disc label, etc.)
    foreach (var meta in chd.Metadata)
        Console.WriteLine(meta.ToString());

    // Read a single decompressed hunk
    byte[] hunk = new byte[chd.HunkBytes];
    chd.ReadHunk(42, hunk);

    // Read arbitrary byte range (handles hunk boundaries)
    byte[] buf = new byte[1024];
    chd.Read(offset: 0x10000, buf, 0, buf.Length);
}

Async random-access reading

var (err, chd) = await ChdFile.OpenAsync("game.chd");
if (err != ChdError.Chderrnone) return;

await using (chd)
{
    byte[] hunk = new byte[chd.HunkBytes];
    await chd.ReadHunkAsync(42, hunk);
}

Quick file checking

bool isChd = Chd.IsChdFile("game.chd", out uint version);
// isChd=true, version=5 for a V5 CHD

// Or just yes/no:
bool yesNo = Chd.IsChdFile("game.chd");

Decompress entire image to a byte array

ChdFile.Open("game.chd", out var chd);
using (chd)
{
    chd.ReadAllBytes(out byte[] image);
    // image now contains the full decompressed image
}

Iterate hunks one at a time

ChdFile.Open("game.chd", out var chd);
using (chd)
{
    foreach (byte[] hunk in chd.EnumerateHunks())
    {
        // Process each decompressed hunk; buffer is reused — copy if needed
    }
}

Logging

The library uses Microsoft.Extensions.Logging.Abstractions. By default, logging is discarded. To enable logging (e.g., with Serilog):

using Serilog;
using Serilog.Extensions.Logging;

var serilogLogger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.Console()
    .CreateLogger();

Chd.LoggerFactory = new SerilogLoggerFactory(serilogLogger);

// All subsequent Chd/ChdFile operations will log through Serilog

You can use any ILoggerFactory-compatible provider (NLog, Microsoft.Extensions.Logging.Console, etc.).

API Reference

Chd — Static class

ChdResult — Verification result

Supports deconstruction: var (err, ver, sha1, md5) = result;

ChdFile — Random-access reader

All Open overloads seek from the start. The reader is not thread-safe — serialize all calls.

Static factory methods

Instance methods

Properties

ChdMetadataEntry — Metadata record

ChdError.GetMessage() — Extension method

ChdError err = ChdFile.Open("bad.chd", out _);
Console.WriteLine(err.GetMessage());
// "File not found"

Supported Formats

CHD Versions

Compression Codecs

Common Usage Patterns

Pattern 1: Fast batch verification

var files = Directory.GetFiles(@"D:\CHD", "*.chd");
foreach (var path in files)
{
    using var s = File.OpenRead(path);
    var result = Chd.CheckFile(s, Path.GetFileName(path), deepCheck: true);
    Console.WriteLine($"{Path.GetFileName(path)}: {result.Error.GetMessage()}");
}

Pattern 2: Universal verification (standalone or child)

static ChdError UniversalVerify(string path, string? parentPath = null)
{
    if (parentPath != null)
    {
        var r = Chd.CheckFileWithParent(path, parentPath);
        return r.Error;
    }

    using var s = File.OpenRead(path);
    var result = Chd.CheckFile(s, Path.GetFileName(path), deepCheck: true);
    if (result.Error == ChdError.Chderrrequiresparent)
        Console.WriteLine("  -> requires parent CHD");
    return result.Error;
}

Pattern 3: Working with child (differential) CHDs

// Option A: Let the library manage parent lifetime
ChdFile.Open("child.chd", "parent.chd", out var child);
child?.Dispose();

// Option B: Share parent across multiple children
ChdFile.Open("parent.chd", out var parent);
using (parent)
{
    foreach (var childPath in new[] { "child1.chd", "child2.chd" })
    {
        ChdFile.Open(childPath, parent, out var c);
        using (c) { /* read hunks */ }
    }
}

Pattern 4: Computing SHA1 while streaming

using var sha1 = System.Security.Cryptography.SHA1.Create();
ChdFile.Open("game.chd", out var chd);
using (chd)
{
    var buf = new byte[chd.HunkBytes];
    var remaining = chd.TotalBytes;
    ulong offset = 0;
    while (remaining > 0)
    {
        var chunk = (int)Math.Min((ulong)buf.Length, remaining);
        chd.Read(offset, buf, 0, chunk);
        sha1.TransformBlock(buf, 0, chunk, null, 0);
        offset += (ulong)chunk;
        remaining -= (ulong)chunk;
    }
    sha1.TransformFinalBlock([], 0, 0);
    Console.WriteLine($"SHA1: {Convert.ToHexString(sha1.Hash!).ToLower()}");
}

Performance

Tuning parallelism

Chd.TaskCount = 16; // set before calling CheckFile
var result = Chd.CheckFile(s, name, deepCheck: true);

Architecture

┌────────────────────────────────────────────────────┐
│                    Public API                       │
│  Chd.CheckFile()  ChdFile.Open()  ChdFile.Read()   │
├────────────────────────────────────────────────────┤
│  CHDHeaders    →  Parse V1–V5 headers + maps       │
│  CHDBlockRead  →  Dispatch hunk → codec delegate   │
│  CHDReaders    →  Decompression delegates (10)     │
│  CHDCodec      →  Per-codec reusable state         │
│  CHDMetaData   →  Metadata traversal + SHA1 check   │
├────────────────────────────────────────────────────┤
│  Utils/                                             │
│  CRC · CRC16 · BitStream · HuffmanDecoder ·        │
│  HuffmanDecoderRLE · BigEndian · ArrayPool · cdRom  │
├────────────────────────────────────────────────────┤
│  LZMA/                                              │
│  LzmaStream · LzmaDecoder · RangeCoder ·           │
│  LzBinTree · LzInWindow · LzOutWindow               │
├────────────────────────────────────────────────────┤
│  Flac/                                              │
│  AudioDecoder · FlacFrame · FlacSubframe ·         │
│  BitReader · LPC · RiceContext · WindowFunction     │
├────────────────────────────────────────────────────┤
│  ZstdSharp.Port  (NuGet)                            │
└────────────────────────────────────────────────────┘

Building

dotnet build CHDSharpLib/CHDSharpLib.csproj -c Release
dotnet pack CHDSharpLib/CHDSharpLib.csproj -c Release

Dependencies

Limits

• Read-only — Cannot create, modify, or repack CHD files
• Not thread-safe — ChdFile instances must be used from a single thread
• No lossy video — Lossy AVHuff video variants are not supported
• Stream must be seekable — for ChdFile.Open stream overloads
• V6+ not supported — MAME has not released a V6 format

License

MIT License — see LICENSE.

Acknowledgments

• Gordon Jefferyes — original C# CHDSharp implementation
• MAME — CHD format specification and chdman reference
• libchdr — C reference library by Romain Tisseraud
• ZstdSharp — pure C# Zstd decompressor