04 user guide

4. User Guide

The main window has four tabs: Convert to CHD, Verify CHD Files, Extract CHD Files, 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.

File list

• Every file matching the supported extensions (see Overview → Supported Formats) is listed pre-selected.
• Select All / Deselect All toggle the whole list.
• 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.

---

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. Click Start Verification.

Details

• Verification is fully local: it uses the CHDSharp library (Chd.CheckFile) to check structural integrity and checksums — no chdman process is launched.
• 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. 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 Explorer

1. CHD File — pick a .chd image.
2. Choose the File System parser matching the console/system (PlayStation (Auto) is the default 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, image type, codecs, metadata tags, the CD/GD-ROM track table, and the per-codec hunk distribution (the scan is capped at the first 1,000,000 hunks for very large images).

---

4.5 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.6 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).