pacnpal/compressatorium

Compressatorium

Fork notice: This is a fork of MarcTV's Docker CHD Converter. It adds a Web UI and more conversion tools on top of the original CLI converter. Thanks to https://github.com/MarcTV for the original.

A disc image converter that wraps six tools: CHDMAN (MAME), dolphin-tool (Dolphin Emulator), z3ds_compressor (Nintendo 3DS), nsz (Nintendo Switch), maxcso (PSP/PS2 CSO/ZSO), and 7z (handheld ROM archives). Pick the tool that matches your files and convert from a browser, or run it headless from the command line.

Features

• Six tools in one. CHDMAN, Dolphin, 3DS, Switch, CSO/ZSO, or handheld ROM (GB/GBC/GBA/DS) compression, chosen per job.
• Web UI for browsing files and converting them. The tool picker filters the whole interface down to the tool you chose.
• Nested directories and archives. Browse subfolders and look inside ZIP, 7z, and RAR archives.
• Multiple volume mounts so you can keep separate game libraries separate.
• File detection that works out which files each tool can convert.
• Existing-output detection with skip, rename, or overwrite.
• Delete-on-verify. Optionally remove the source after a conversion verifies. Off by default.
• Progress tracking through a live job queue.
• File info for CHD, Dolphin, 3DS, Switch, CSO, and handheld ROM files.

Supported Conversions

Every conversion above is lossless and fully reversible — including 3DS, which now decompresses back to the original ROM as well. This uses https://github.com/pacnpal/z3ds_compress (a fork that adds a decompression mode and .cxi/.3dsx support to the original https://github.com/energeticokay/z3ds_compress). The compressed .z3ds can be read directly by Azahar, or restored to .cci/.cia/.3ds with z3ds_decompress; see Nintendo 3DS Support. Each tool's full mode list (e.g. CHDMAN's createcd/extractcd, CSO's cso2_compress, the ROM packer's romz_7z/romz_zip/romz_extract) is in Supported Operations.

Archive inputs: most input formats above can be converted straight from inside a ZIP, 7z, or RAR archive, including 3DS ROMs, Dolphin disc images, and Switch dumps. Browse into the archive, pick a member, and convert. This even covers CHDMAN's extract modes pulling a .chd out of an archive and decompressing it back to a disc image. Two exceptions: CHDMAN's copy/recompress mode is not offered from an archive (recompressing an already-finished .chd would be a pointless round trip); and Handheld ROM does not accept loose ROMs from inside an archive — its .7z/.zip are the packed product, so to unpack one select the archive file itself and run romz_extract, rather than browsing into it for a member.

MAME Redump DAT Integration

Compressatorium can sync https://github.com/MetalSlug/MAMERedump DAT files (Logiqx XML) in one click and check your compressed files against known-good Redump hashes. The same hashes let tools like https://github.com/gaseous-project/hasheous and https://github.com/rommapp/romm match your library.

• One-click sync: Click "Sync from MAME Redump" in the DAT panel to download all ~69 DATs automatically from GitHub
• Auto-sync: Set MAMEREDUMP_AUTO_SYNC=true to sync DATs on container startup when none are loaded
• CHD files: Matched via the embedded header / data SHA1 (codec-independent, works with any compression setting on chdman 0.285)
• Dolphin RVZ/WIA/GCZ: Matched via the disc image's content SHA1 reconstructed by dolphin-tool verify — the same hash MAME Redump records for GameCube/Wii discs — so compressed Dolphin outputs match without the container bytes having to be identical
• Everything else (3DS/Switch/CSO·ZSO·DAX/.iso/.bin): Matched via file-level SHA1
• Library scan: The background scan discovers and DAT-matches every registered tool's output (CHD, Dolphin RVZ/WIA/GCZ, 3DS, Switch, CSO/ZSO, .iso, and the .bin data track from CHDMAN extract), not just CHDs, so non-CHD libraries get cached match results too. Heavy Dolphin disc-hashing during the scan honors MATCH_MAX_FILE_SIZE and stops pro***ly if you cancel the scan.
• DAT management: Import, list, and delete DATs via the web UI "DAT Files" button
• Match badges: Files matching a DAT entry show a blue "DAT" badge in the file list

---

Installation

The Docker image is available from two registries:

Docker Hub

bash
docker pull pacnpal/compressatorium

GitHub Container Registry

bash
docker pull ghcr.io/pacnpal/compressatorium

Both registries provide identical images with multi-architecture support (linux/amd64 and linux/arm64).

Note: Use either registry: replace pacnpal/compressatorium with ghcr.io/pacnpal/compressatorium for the same image.

Available Tags

Opting in to beta updates

To track pre-release builds, pull the :beta tag instead of :latest:

bash
docker pull pacnpal/compressatorium:beta

Or pin to a specific pre-release (recommended if you want to control when you upgrade):

bash
docker pull pacnpal/compressatorium:3.7.0-beta-3

Warning: beta builds can cause data loss. Pre-releases may carry unfinished migrations, experimental conversion logic, or breaking changes to the job database. Running a beta against a database that a stable release created can corrupt it or migrate it past the point of return, and downgrading back to :latest afterwards is not supported. Before you pull :beta:

• Back up your SQLite database (compressatorium.db in your data volume) and any in-flight output files.
• Prefer a separate data volume for beta testing rather than pointing a beta container at your production volume.
• Do not use beta builds for batches you cannot afford to redo.

---

Quick Start Guide

1. Select Your Primary Tool

When you open the Web UI, you'll see the tool options at the top:

• CHDMAN - For converting CD/DVD/LaserDisc images to CHD format
• Dolphin - For GameCube/Wii disc image conversions
• 3DS - For compressing Nintendo 3DS ROMs
• Switch - For compressing/decompressing Nintendo Switch dumps (needs your own prod.keys)
• CSO - For compressing/decompressing PSP/PS2 ISO images to CSO/ZSO
• Handheld ROM - For compressing/extracting GB/GBC/GBA/DS ROM dumps to .7z/.zip archives

Choose the tool that matches your files. The interface then shows only the modes and file types that tool can use.

2. Browse and Select Files

• Navigate through your mounted volumes using the left panel
• Click on folders to browse subdirectories
• Check the boxes next to files you want to convert
• Archives (.zip, .7z, .rar) can be browsed by clicking them

3. Configure and Convert

• Select the appropriate conversion mode from the dropdown
• Adjust compression settings if available (see Compression Settings)
• Click the action button (Create/Convert/Compress depending on mode)
• Monitor progress in the job queue panel

---

Usage Guide

This is the global guide to the workflow and the features shared by every tool — browsing, modes, compression, verifying/deleting, archives, DAT matching, and troubleshooting. The per-tool sections further down only document what's specific to each tool (its formats, modes, env vars, and quirks). The same material is available in-app under Help.

Browsing and finding files

Your mounted volumes appear in the left panel — click a folder to enter, a breadcrumb to go back. Search All walks the whole volume and lists every convertible file at once; the filter dropdown narrows by extension. Both update automatically as tools are added. System clutter (.DS_Store, AppleDouble ._* files, Thumbs.db, desktop.ini, @eaDir, #recycle, lost+found, …) is hidden so listings stay clean.

Modes

Create makes a compressed file, extract/decompress gives the original back, copy recompresses in place. Pick the create mode that matches the media — compressing a PSP/PS2 image with createcd instead of createdvd won't come out right. The full mode list per tool is in Supported Operations.

Compression settings

Every tool that compresses (CHD, Dolphin, Switch, CSO) shares one compression picker in the convert panel:

• Controls differ per tool. chdman takes a codec list, Dolphin and Switch take a single codec/layout plus a numeric level, and CSO takes a Fast/Default/Max effort preset (no numeric level). Decompress/extract modes and 3DS have no compression settings, so the picker is hidden for them.
• Your choice is remembered server-side per tool, so it follows you across sessions and browsers.
• Reset to default. A button under the picker restores that tool's codec/layout/level/effort to its default and confirms with a toast. It's disabled when you're already on the defaults.
• Strong defaults where it helps. CSO defaults to the Max preset (smallest output); the other tools default to broadly-compatible settings (chdman zlib, Dolphin zstd:19, Switch solid:18). See also Compression Compatibility Tips.

Output location and duplicates

By default the output lands next to its source; set a custom output directory instead and it's created for you as long as it's inside a mounted volume. If a matching output already exists the app stops and asks rather than clobbering it: skip keeps the existing file, rename writes under a new name, overwrite replaces it.

The job queue

Every conversion and verify runs through one FIFO queue — one job at a time by default, which keeps the host responsive during big batches. Progress streams live, and jobs run on the server, so closing the browser (or rebooting your laptop) doesn't stop them; reopen the page and it reconnects. The queue has active / completed / failed tabs, plus Cancel All and Clear Done (both confirm first).

Verifying and deleting safely

Converting never deletes anything on its own — the safe order is convert, verify, then delete the source. Verify reads the whole output back and checks it against the file's own hashes/CRC; with delete-on-verify the source is removed only after the output passes, and never if it fails. You get a confirmation list of everything to be deleted first, including the .cue/.gdi track files that ride with a .bin, and the whole archive if the source came from one. Bulk Verify checks a whole selection at once across CHD, Dolphin, 3DS, Switch, and CSO; verification status persists between sessions, and a long verify can be given a timeout so a stalled one doesn't block the queue.

File info

Click a file to open the inspector — it shows the format/version, compression, size, and hashes, plus the raw tool output. For PS1/PS2/PSP/Dreamcast discs it also digs the game serial out of the sector data and shows a human title when it recognizes one. A background scan caches this so the list badges don't recompute on every folder open.

DAT matching

Sync the MAMERedump DATs from the DAT Library (or import your own .dat/.xml from No-Intro/Redump) and converted files are checked against known-good hashes — a blue DAT badge means the file matches. CHDs match on the codec-independent header SHA1, and Dolphin RVZ/WIA/GCZ match on the disc image's content SHA1 reconstructed by dolphin-tool verify --algorithm sha1 (the same hash Redump records), so any compression setting still matches for both. A missing badge usually means the DATs aren't synced, the title isn't in the DAT, or the file is larger than MATCH_MAX_FILE_SIZE (which skips the expensive full-disc reconstruction) — not that the file is bad.

Archives

Browse straight into a ZIP, 7z, or RAR and convert a file from inside it — no need to extract first. The member is unpacked to a temp dir for the conversion and cleaned up afterwards. Any convertible source works this way (CHD create, Dolphin, 3DS, Switch, and CSO — Switch still needs your own prod.keys), and CHDMAN's extract modes can even pull a .chd out of an archive and decompress it back to a disc image. The exception is CHDMAN's copy/recompress mode: it acts on a finished .chd, and recompressing one straight out of an archive is a pointless round trip, so it's not offered there.

Why only certain files show inside an archive

Browsing into an archive does not list everything it contains. It lists the file types the app knows — every extension that some tool recognizes as a convertible source (.iso, .cue/.bin, .gdi, .gcz/.wia/.rvz/.wbfs, .cci/.cia/.3ds/.cxi/.3dsx, .nsp/.xci, .cso/.zso/.dax, the handheld ROMs .gb/.gbc/.gba/.nds, …) plus a .chd you can decompress in place. Anything else is hidden, on purpose:

• Unknown files are filtered out. Read-me text, .nfo/.sfv files, box art, manuals, save states — none of it is something the app can convert or verify, so it would only be clutter in the browser. The listing is global, scoped to known extensions: a member shows up if and only if its extension is one the app understands, regardless of which tool you currently have selected.
• Nested archives are hidden. A .zip inside a .zip (or .7z/.rar) is not listed — there's no point browsing an archive within an archive.
• OS/NAS clutter is ignored. macOS __MACOSX/… resource forks, .DS_Store, Thumbs.db and the like never appear, so a ROM zipped on a Mac or Windows box still reads as a clean single-file archive.

Some members that are shown still can't be converted from inside the archive, and the UI badges them non-convertible:

• A handheld ROM packed by this app (Game.gba inside Game.gba.7z) is shown so you can see and verify it, but it isn't offered for re-conversion — recompressing an already-archived ROM would just be packing a .7z into another .7z. To unpack it, select the archive file itself and run romz_extract.
• A .chd inside an archive can be decompressed in place (chdman's extract modes), but it can't be recompressed — it's already a finished CHD, so chdman's copy/recompress mode is ***ly not offered from an archive.

In short: if a file you expect isn't in the list, it's almost always because its extension isn't one of the convertible/verifiable types the app handles. Loose files on disk follow the same rule — the file list filters to the types the selected tool understands.

Troubleshooting

• An emulator won't read the CHD — almost always the codec; recompress with zlib only using copy mode (see Compression Compatibility Tips).
• "Output already exists" — pick skip / rename / overwrite; nothing is replaced unless you choose overwrite.
• A conversion stalls — big files are slow; an adaptive stall timeout scales with input size, and the queue has a recovery action. Check temp-dir space/speed.
• A file didn't show up — make sure the right tool is selected (the list filters to it); try Search All or clear the extension filter.
• An ISO went to the wrong tool — ISOs can belong to CHDMAN or Dolphin; set the ISO Handling toggle to match the disc.
• The Switch tool is missing or jobs ask for prod.keys — it needs your own keys; see Nintendo Switch Support. Without keys the tool is hidden.

---

Web UI Mode (Default)

The web interface is the easiest way to run Compressatorium:

bash
docker run -d \
  -p 8080:8080 \
  -e PUID=$(id -u) \
  -e PGID=$(id -g) \
  -v /path/to/config:/config \
  -v /path/to/games:/data/games \
  pacnpal/compressatorium

Then open http://localhost:8080 in your browser.

Required: The /config volume must be mounted for persistent data storage.
Volume discovery: If COMPRESSATORIUM_VOLUMES is unset, the app scans /data/* at startup and auto-registers mounted game volumes (restart after mount changes).
Ownership (optional): Set PUID/PGID to match your host user/group (for example Unraid 99:100). If unset, defaults remain 999:999.
Default temp location: /config/temp. To use a different location, set CHD_TEMP_DIR and mount it.

Multiple Volumes

Mount multiple game directories for better organization:

bash
docker run -d \
  -p 8080:8080 \
  -v /path/to/config:/config \
  -v /home/user/dreamcast:/data/dreamcast \
  -v /home/user/psp:/data/psp \
  -v /home/user/ps1:/data/ps1 \
  pacnpal/compressatorium

Custom Output Directory

In the Web UI, you can specify a custom output directory for converted CHD, Dolphin, or 3DS outputs instead of placing them alongside the source files. The directory will be created automatically as long as it is within your configured volumes.

Screenshots

The Web UI ships with light and dark themes and is fully responsive from desktop down to phones. Each surface below is shown as a light / dark pair.

Workspace

A three-pane layout: navigation and tool picker on the left, the volume and file browser in the middle, and a live convert panel with the job queue on the right. Selecting a tool (CHDMAN, Dolphin, or 3DS) refilters the file list and the convert options to match.

Batch selection. Tick multiple files and the convert panel arms itself, showing how many sources are queued and a one-click Start conversion.

Dolphin (GameCube / Wii). Compress discs to RVZ, WIA, or GCZ, with a codec and compression-level picker.

3DS. Compress .cci, .cia, and .3ds ROMs with z3ds_compressor.

Dashboard

An at-a-glance view of the job queue, verification cache, mounted volumes, recent conversions, and quick tool shortcuts.

DAT Library

Import or sync No-Intro / Redump / MAMERedump datasets and match converted files against known-good hashes.

Help

In-app reference for tools, formats, compression, and verification.

Responsive layouts

The interface reflows cleanly across breakpoints:

Desktop (1280px)

!Desktop View

Tablet (768px)

!Tablet View

Mobile (375px)

!Mobile View

On small screens the file list switches to a card layout. Controls use 44 to 48px touch targets, inputs go full width, and the spacing opens up so it stays usable on a phone.

Features

File Browser

• Navigate through mounted volumes and subdirectories
• View file sizes, types, ISO handling, and CHD status indicators
• Recursive search to find all convertible files across the entire volume

Archive Support

• Browse inside ZIP, 7z, and RAR archives without extraction
• Convert files directly from within archives
• Archives extract temporarily during conversion, then clean up automatically
• When a .cue/.gdi is present in the same archive folder, .bin entries are suppressed and batch jobs are deduplicated by output path to avoid stalled conversions.
• Archive listings include safety limits (max entries/size) and expose truncation metadata when limits are hit.
• Browsing is global, scoped to known extensions. When you look inside an archive, the listing shows every member whose extension is one the app understands — every tool's convertible source plus a .chd you can decompress — regardless of which tool is currently selected. That covers CHDMAN (.gdi/.iso/.cue/.bin), Dolphin (.iso/.gcz/.wia/.rvz/.wbfs), 3DS (.cci/.cia/.3ds/.cxi/.3dsx), Switch (.nsp/.xci), CSO (.iso/.cso/.zso/.dax), and Handheld ROM (.gb/.gbc/.gba/.nds). Archive members appear for whichever tool accepts them, exactly like on-disk files.
• Why everything else is hidden. Unknown files (text, .nfo/.sfv, cover art, manuals), nested archives (a .zip inside a .zip), and OS/NAS clutter (__MACOSX/…, .DS_Store, Thumbs.db) are filtered out — they aren't convertible or verifiable, so listing them would only be noise. See Archives → Why only certain files show inside an archive.
• Some shown members are view-only. A handheld ROM this app packed (Game.gba inside Game.gba.7z) is listed for visibility/verification but not offered for re-conversion (recompressing an archived ROM would be recursive); unpack it by selecting the archive and running romz_extract. A .chd inside an archive can be decompressed in place but not recompressed (copy/recompress acts on a finished output). Such members are badged non-convertible.
• The only inputs that can't come from an archive are CHDMAN's copy/recompress mode (recompressing an already-finished .chd would be a pointless round trip — though the extract modes can decompress a .chd straight out of an archive) and Handheld ROM compression, whose .7z/.zip are the packed product.

ISO Handling & Dolphin Tools (GameCube/Wii)

• Toggle ISO handling between CHDMAN and Dolphin (controls ISO info/verify and conversions)
• Convert .iso, .gcz, .wia, .rvz, .wbfs with dolphin-tool (RVZ/WIA/GCZ/ISO output)
• Disc info and verification for Dolphin formats (including batch verification)
• Dolphin sources may be converted directly from inside ZIP/7z/RAR archives (extracted to a temp dir for the conversion, then cleaned up)

Batch Conversion

• Select multiple files and convert them all at once
• Queue-based processing (FIFO), defaulting to serial execution (MAX_CONCURRENT_JOBS=1)
• Real-time progress tracking via Server-Sent Events
• Duplicate detection with options to skip, rename, or overwrite
• Optional delete-on-verify with a preflight confirmation list (includes .cue/.gdi track files)
• Archive conversions can delete the entire archive after verify (explicit warning in the delete plan)
• Job manager controls include Cancel All and Clear Done, both guarded by confirmation dialogs

Bulk Operations

• Bulk Delete: Delete multiple selected files at once