4. User Guide

The main window has five tabs: Convert to CHD, Verify CHD Files, Extract CHD Files, Recompress CHD, and Explorer. A terminal-style log view sits on the right, stat cards and the progress bar at the bottom, and a status bar with the CHDSharp and CHDMAN encoder indicators at the very bottom.

Title-bar buttons: Donate (opens the project’s donation page), About (info dialog, scrollable), AppData (opens %LocalAppData%\CHDStudio), Exit.


4.1 Convert to CHD

Workflow

  1. Source Files — select the folder containing images/archives (or pass it as a command-line argument).
  2. Output CHD — select the destination folder.
  3. Adjust options (below).
  4. Review the file list, uncheck anything you don’t want, then click Start Conversion.

Options

Option Effect
Search subfolders (recursive search) Recursively scans the source folder; the output mirrors the directory hierarchy (relative paths are preserved).
Delete originals after a successful conversion Removes the source file — and its dependencies (.bin, .sub, etc. for cue sets; .img/.sub for CCD sets) — only after the CHD was produced successfully.
Process smaller files first Sorts the batch by ascending file size so quick conversions finish first.
Time limit per file (minutes, default 15) Aborts a single conversion that exceeds the limit; the file is marked failed and the batch continues. The app enforces a hard cap of 4 hours (AppConfig.MaxConversionTimeoutHours).
Force CD / Force DVD Overrides automatic command detection (createcd / createdvd). The two checkboxes are mutually exclusive.
Compression Codec preset for new CHDs: Default (chdman-compatible), Smallest (zstd/cdzs, requires a recent MAME/libchdr reader), Most compatible (zlib/cdzl), Auto (per-platform preset), or Uncompressed (raw/DVD/HDD/CD; laserdisc output always uses AVHuff).
Create a delta (child) CHD against a parent Stores only the hunks that differ from the selected parent. The parent’s hunk and unit sizes must match the selected command.

File list

  • Every file matching the supported extensions (see Overview → Supported Formats) is listed pre-selected.
  • Select All / Deselect All toggle the whole list; Select Failed selects only the rows marked Failed after a batch so they can be retried without reconverting the successful files.
  • The Status column shows the outcome of the current or last batch: Pending, Converting, OK, Failed, or Skipped (a companion data file covered by a descriptor, or a duplicate output).
  • The list is loaded in chunks (100 items at background priority) to stay responsive on huge folders.
  • When recursive search is on, the File Name column shows the path relative to the source folder.

What happens during conversion

  1. Archives (.zip/.7z/.rar) are extracted to a temp directory first (SharpCompress, with a bundled 7-Zip fallback — 7za on Windows, 7zz on Linux/macOS — for archives the built-in extractor cannot read), then each supported file inside is converted. Multi-part RAR sets (.partNN.rar, .001 volumes) are decoded from their first volume; only that volume is offered as an input. Cue/GDI/TOC entries whose referenced data files are missing are skipped with a warning.
  2. .cso is decompressed to a temp ISO (CSOSharp), then converted.
  3. .pbp is extracted to CUE/BIN (PBPSharp), then converted. Files without a PlayStation disc image (PSP homebrew, corrupt variants) are skipped with an informational message.
  4. .ccd is converted to CUE/BIN (CCDSharp), then converted.
  5. Everything else (.cue, .gdi, .toc, .iso, .img, .raw, .avi) goes straight to the encoder — chdman on Windows, the built-in CHDSharp encoder on Linux/macOS — after cue normalization when applicable and a dependent-file check. On Windows a missing or failing chdman also routes the file to the built-in encoder. A laserdisc AVI (.avi) is encoded with createld (the A/V avhu codec, one frame per hunk); this is how Daphne/laserdisc dumps are stored.

Each file’s encoder mode is chosen automatically (see Technical Logic) unless Force CD/DVD is set.

Advanced behaviors you may observe in the log

  • “Retrying with createdvd (unrecognized track type)” — a createcd attempt failed because chdman did not recognize the track type; the app automatically retries with createdvd.
  • “chdman exited with code N but produced a valid output file” — a non-zero exit that still produced a non-empty output CHD is treated as success.
  • “Falling back to the built-in CHDSharp encoder…“ and “CHDSHARP: createcd game.cue” — Windows: chdman failed or is missing, so the in-process CHDSharp encoder is encoding the file instead. This is routine and conversion continues automatically.
  • “CHDSHARP: Compressing, N% complete… (ratio=…)” — progress from the built-in encoder, logged every 10% (chdman progress is shown as [CHDMAN] lines).
  • “Prepared self-contained cue set …“ — the cue was normalized (BOM, encoding, zero-padding, MP3 tracks) into a work directory before conversion.
  • “Falling back to system temp” — the preferred temp drive was not writable; the system temp is used instead.
  • “TIMEOUT: Conversion … exceeded N minute(s). Marking as failed.” — the per-file timeout fired.

Space and failure summaries

The batch summary measures the source set (a cue and every data file it references, every part of a split image, or the archive/PBP/CSO itself) and the CHDs that were produced. The completion dialog and the activity log report the totals and the measured saving, for example:

Space: 22.8 GB of converted source -> 20.0 GB of CHD (saved 2.8 GB / 12.1%).

CHD is a container with compression, not a general-purpose archiver. It shrinks uncompressed BIN/CUE, ISO and raw images well, but it cannot shrink data that is already compressed: .pbp, .cso, .isz, .ecm and .zip/.7z/.rar inputs, and images whose payload is itself compressed or encrypted, can produce a CHD close to the source size. The summary says so explicitly when no space was saved. The space is only reclaimed when the sources are removed — enable Delete originals after a successful conversion, or delete them manually.

Files that fail are marked Failed in the list and listed in failed-conversions.txt in the output folder (next to the CHDs, with the source folder, output folder and one path per failed input). Use Select Failed to select exactly those rows and click Start Conversion to retry them; the activity log and the application log file still contain the per-file error.


4.2 Verify CHD Files

Workflow

  1. CHD Files — select the folder containing .chd files.
  2. Enable Search subfolders if needed.
  3. Optionally enable Move successful to ‘Success’ folder, Move failed to ‘Failed’ folder, and/or Write a checksum report (.checksums.txt) next to each verified CHD.
  4. For a differential child CHD, select its Parent CHD or leave Find the parent automatically in the child’s folder enabled. Child CHDs cannot be verified without their parent.
  5. Optionally enable Repair header hashes when verification finds a mismatch to rewrite only the V3-V5 header hash fields (chdman verify --fix parity). Child CHDs are verified against their parent and are not rewritten.
  6. Click Start Verification.

Details

  • Verification is fully local: it uses the CHDSharp library (Chd.CheckFile, Chd.CheckFileWithParent or Chd.CheckFileAndRepair) to check structural integrity and checksums - no chdman process is launched.
  • A differential child is verified against its parent; if auto-detection cannot find the parent, select it explicitly. Header repair is standalone-only because a child’s data is resolved through its parent.
  • Success lines show the CHD version and SHA-1, e.g. V5 — SHA1: 1f2e3d....
  • Checksum report: when enabled, each verified CHD gets a <name>.checksums.txt next to it (following the file into the Success folder) with the whole-image SHA-1, CRC-32 and XXH3-64 plus SHA-1, CRC-32 and XXH3-64 for every track of a CD/GD-ROM image. The whole-image hashes cover the decompressed image (the CHD header’s combined SHA-1 is not a content hash, so it is not reused). The hashing pass logs CHDSHARP: Hashing, N% complete... and a failure to write the report is a warning, never a verification failure.
  • Moved files land in inputFolder\Success and inputFolder\Failed (created automatically). These folders are excluded from subsequent recursive scans.
  • With subfolder search, the relative directory structure is preserved under Success/Failed.
  • Moving uses retry-with-backoff so transient locks (antivirus/indexer) don’t fail the move; a persistent failure is logged and reported but does not abort the batch.

4.3 Extract CHD Files

Workflow

  1. CHD Files — select the folder containing .chd files.
  2. Output Folder — where the extracted files go (structure is preserved when searching subfolders).
  3. Choose the output format.
  4. For a differential child CHD, select its Parent CHD or leave Find the parent automatically in the child’s folder enabled.
  5. Click Start Extraction.

Output format

Choice Command Output
Auto (default) Detected from CHD flags .cue, .iso, .gdi, .img, or .avi
CD (.cue) extractcd .cue + track .bin files
DVD (.iso) extractdvd single .iso
GDI (.gdi) extractcd .gdi + track .bin files
HDD (.img) extracthd single .img
Laserdisc (.avi) extractld single .avi (A/V CHD)

Auto-detection reads the CHD flags (via CHDSharp): DVD → .iso, hard disk → .img, CD/GD-ROM → .cue (or .gdi when the metadata says gd-rom), and a CHD with no CD/DVD/HDD metadata is treated as an A/V (laserdisc) image and extracted to .avi.

Notes

  • Multi-track (CD/GDI) extraction writes into a _extract_temp_<guid> directory inside the target folder, then moves the files out; on success the temp dir is removed, on failure it is kept and a warning tells you how many files remain.
  • A/V (laserdisc) CHDs are extracted in-process by CHDSharp (ExtractLaserDisc, MAME-parity AVI output) — chdman is only a fallback.
  • Corrupt CHD files fail fast with the CHDSharp error message (“Not a valid CHD file”, “Invalid or corrupt data”, “Cannot open file”, …) and the batch continues.
  • Delete original CHD after a successful extraction removes the source CHD only on success.
  • Cancellation deletes partially extracted single-file (DVD/HDD/laserdisc) outputs.
  • Extraction enables CHDSharp read-ahead (16 hunks) so sequential decompression overlaps the disk writes.

4.4 Recompress CHD Files

  1. CHD Files - select the folder containing .chd files.
  2. Output Folder - where the recompressed CHDs go. If it is the same as the input folder, the output is named <name>.recompressed.chd so the source is never overwritten.
  3. Choose a Compression preset (Default, Smallest, Most compatible, Auto, or Uncompressed).
  4. For a differential child CHD, select its Parent CHD or leave auto-detection enabled. The output is written as a standalone CHD, which also makes it usable in the Explorer.
  5. Optionally enable deep verification, legacy metadata upgrade, or deleting the original after success.
  6. Click Start Recompression.

Recompression uses CHDSharp’s ChdEncoder.Copy, so metadata is preserved (and legacy CD/GD tags can be upgraded). A child source is resolved through its parent and consolidated into a standalone output. Uncompressed output is available for raw/DVD/HDD and CD CHDs; laserdisc sources fall back to the compatible AVHuff codec set.

4.5 Explorer

  1. CHD File - pick a .chd image.
  2. The app detects the disc platform from sector content and preselects the matching File System parser; you can still override it manually. PlayStation (Auto) remains the fallback and parses ISO 9660 on both CD and DVD images.
  3. Browse folders in the grid; double-click a folder to enter it, a file to extract and open it, or use Extract… to save the selected file/folder.

Image Info (expander under the parser drop-down) shows a read-only report built from the CHD header and map: version, hunk/unit sizes, logical size, unit count, header/map/metadata offsets, raw and combined SHA-1, image type, codecs, metadata tags, the CD/GD-ROM track table (including pregap/postgap/start/padding), the per-codec hunk distribution with stored bytes, and the detected platform/title/serial (the scan is capped at the first 1,000,000 hunks for very large images).

A differential child CHD cannot be parsed directly by the Explorer; use the Recompress CHD tab to consolidate it with its parent into a standalone CHD first.


4.6 Screenshot Hotkey (F8)

While the application window is focused, pressing F8 captures that window and saves it as screenshot_yyyy-MM-dd_HH-mm-ss-fff.png in %LocalAppData%\CHDStudio\screenshots. When AppData is not writable, the capture falls back to a screenshots folder next to the executable.

The path is shown in the log (“Screenshot saved: …”). Capture uses Avalonia’s RenderTargetBitmap; if the capture fails, a message is logged instead.

4.7 Status Bar & Stats

  • Status bar: current operation message + the CHDSharp and CHDMAN encoder indicators. CHDSharp is always green (built-in, always available). CHDMAN is green when found, red when missing on Windows (conversions then use the built-in encoder) and gray on Linux/macOS, where it is optional and never used for encoding.
  • Stat cards: TOTAL FILES, SUCCESS, FAILED, ELAPSED, SPEED (disk write/read MB/s, sampled while an operation runs; for a chdman conversion the speed is read from the chdman child process, and for the in-process CHDSharp encoder from the app itself).
  • Progress bar: per-batch progress with a Cancel button that stops the current operation (cancelling chdman kills the process and cleans up temp files).

This site uses Just the Docs, a documentation theme for Jekyll.