2. Getting Started

2.1 Requirements

Runtime (end users)

  • OS: Windows 10 / 11, Linux and macOS (x64 or ARM64); release bundles are published for win-x64, win-arm64, linux-x64, linux-arm64, osx-x64 and osx-arm64
  • Runtime: .NET 11.0 Desktop Runtime on Windows; the .NET 11.0 runtime on Linux and macOS
  • Bundled executables (shipped with the app, must stay next to CHDStudio.exe):
    • Windows: chdman.exe / chdman_arm64.exe (0.289) — MAME CHD tool (primary encoder and extraction fallback); 7za.exe / 7za_arm64.exe — 7-Zip fallback extractor
    • Linux/macOS: 7zz (official 7-Zip 26.03 console build, copied from tools/ at publish time) — 7-Zip fallback extractor
  • Built-in encoder: CHDSharp (CHDSharpLib 1.7.1) runs in-process on every platform — the automatic fallback behind chdman on Windows and the only encoder on Linux/macOS. Its output is byte-identical to chdman 0.289, and being a managed assembly there is no encoder executable to ship.
  • Nothing else to install — CSO, ISZ, ECM, Alcohol .mds/.mdf and split volume sets are all handled inside the application, so x64 and ARM64 get the same feature set.

Build (developers)

  • .NET SDK 11.0.x (global.json pins 11.0.0 with rollForward: latestMajor)
  • No Windows SDK required — Avalonia 12.1 and the Windows-only NAudio package are restored via NuGet, and the project sets EnableWindowsTargeting for the Windows TFM
  • No other global tools required

2.2 Installation (End Users)

  1. Download the latest bundle from the Releases page, picking your platform and architecture: the .zip for Windows (win-x64/win-arm64), the .tar.gz for Linux (linux-x64/linux-arm64), or the .dmg for macOS (osx-x64/osx-arm64).
  2. Extract the archive (Windows/Linux) or mount the disk image (macOS) and move the contents to a permanent folder (do not run from a temp/Downloads folder if you want update behavior to be predictable).
  3. Important (Windows): keep all .exe files (including ARM64 variants) in the same directory as CHDStudio.exe — tool discovery probes the app’s base directory first, then PATH (MainWindow.axaml.cs). On Linux and macOS, 7zz ships next to the app and other tools are discovered on PATH; the built-in CHDSharp encoder needs nothing on disk.
  4. Launch CHDStudio.exe on Windows or CHDStudio on Linux/macOS.

Release bundles are named release_<version>_<rid>.zip (Windows), release_<version>_<rid>.tar.gz (Linux) and release_<version>_<rid>.dmg (macOS). They contain the framework-dependent single-file app, its native libraries, the matching chdman/7-Zip tools, LICENSE.txt, ReadMe.md and WhatsNew.md. The Linux and macOS bundles place these files in a CHDStudio/ folder; the Windows zip is flat. The .NET 11 runtime is not embedded, so install the runtime listed above. Keep the whole bundle together in one folder: copying only CHDStudio.exe leaves the native rendering libraries behind and the app will refuse to start with a missing-library message.


2.3 Building from Source

# Clone
git clone https://github.com/purelogiccode/CHDStudio.git
cd CHDStudio

# Build the whole solution
dotnet build CSharp_CHDStudio.sln -c Release

# Run the tests
dotnet test CSharp_CHDStudio.sln -c Release

# Or just the application
dotnet build CHDStudio/CHDStudio.csproj -c Release

The solution contains seven projects:

Project Kind Target framework
CHDStudio Avalonia application (WinExe) net11.0;net11.0-windows
CHDStudio.Tests xUnit test suite net11.0-windows
MDSSharp class library (Alcohol 120% .mds/.mdf parsing) net8.0;net9.0;net10.0;net11.0
CCDSharp class library (CloneCD parsing) net8.0;net9.0;net10.0;net11.0
CSOSharp class library (CSO decompression) net8.0;net9.0;net10.0;net11.0
PBPSharp class library (PBP/SFO parsing) net8.0;net9.0;net10.0;net11.0
ISZSharp class library (ISZ decompression) net8.0;net9.0;net10.0;net11.0

Note: on Windows, chdman.exe and 7za.exe are copied to the output directory by the build (CHDStudio.csproj); on Linux and macOS the matching tools/7zz* binary (official 7-Zip 26.03) is copied as 7zz, while a chdman on PATH is only used for extraction fallback and never for encoding. The libraries are referenced as project references, not NuGet packages, except CHDSharp (NuGet 1.7.1) and other packages listed below.

NuGet dependencies (application)

Package Version Purpose
CHDSharp 1.7.1 Pure C# CHD reading, verification, extraction, and creation (chdman byte-identical output)
Avalonia (+ Desktop, Fluent theme, DataGrid) 12.1.6 Cross-platform Fluent Design UI framework and controls
SharpCompress 0.50.9 Archive extraction (7z/rar), and bzip2 decompression for ISZ chunks
NAudio 3.3.0 MP3 decoding via Media Foundation
Serilog 4.4.0 Structured logging
Serilog.Sinks.File 7.0.0 Rolling file logs
Serilog.Sinks.Debug 3.0.0 Debugger sink
SharpZipLib 1.4.2 Reference-compatible inflater for PBP PSAR blocks (via PBPSharp)
Meziantou.Analyzer 3.0.339 Roslyn analyzers (build-time only)
Roslynator.Analyzers 5.0.1 Roslyn analyzers (build-time only)

2.4 Running the Application

From the command line

The application accepts an optional folder path argument to pre-populate the Convert to CHD source folder:

CHDStudio.exe "C:\ROMs\MyGames"

The path is applied in MainWindow_LoadedAsync via SetInputFolder (MainWindow.axaml.cs:148–153).

First launch

  1. The built-in CHDSharp encoder is always available, so a batch can never be refused for a missing encoder. On Windows only, when the bundled chdman.exe is missing or fails the startup probe, a notice explains that every conversion will run on the built-in encoder (status bar indicators + a message box).
  2. Usage statistics are recorded once (anonymous { applicationId, version } POST — see Services Reference).
  3. An update check against GitHub releases runs in the background.
  4. Leftover temp directories from crashed sessions (older than one hour) and legacy files are cleaned up after a short delay.

Single-instance behavior

Only one instance can run: a global mutex Global\CHDStudio_SingleInstance is acquired at startup; a second launch shows “Another instance of CHDStudio is already running.” and exits (App.axaml.cs:80–105).


2.5 First Conversion in 30 Seconds

  1. Open the Convert to CHD tab.
  2. Source Files → browse to your folder of images/archives.
  3. Output CHD → browse to your target folder.
  4. Click Start Conversion.

Files appear in the list pre-selected; uncheck any you want to skip. The log pane shows live chdman output; the status bar and stat cards show progress, speed, and elapsed time.

See the User Guide for all options and the other two workflows (extraction and verification).


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