VGMPlay

VGMPlay is a fast, local-first player for preserved video game music discs. It reads Redump DAT catalogs, matches local releases by exact disc/track filenames, streams loose CDDA directly from its source BIN, retains compressed-archive support, and enriches the library with VGMdb track names and artwork.

The Rust backend and embedded web interface ship as one executable. Media stays on the local machine; only explicit VGMdb enrichment and optional UPnP discovery use the network.

Requirements

• Windows 10 or newer for the notification-area application and authenticated VGMdb integration.
• The Microsoft Edge WebView2 Runtime. It is included with current Windows installations.
• A current stable Rust toolchain when building from source.
• Redump Audio CD and/or BD-Video DAT files downloaded separately from Redump.

Quick start

1. Place the Redump .dat files in dats, or set VGMPLAY_DAT_PATH to another DAT directory. Catalog files are local data and are not included in the repository.

2. Copy .env.example to .env.

3. Set AUDIO_CD_PATH and, optionally, BLURAY_PATH.

4. Run:

   cargo run --release
   

5. Open VGMPlay and create the first local account. The first account is the administrator; other people can then register listener accounts or be created from Account → Manage users.

On Windows, VGMPlay lives in the notification area. Right-click the disc icon and select Open VGMPlay to open http://127.0.0.1:4816. The server binds only to localhost by default.

UPnP port mapping

Set VGMPLAY_UPNP="true" to discover an IGD-compatible router and map the VGMPlay TCP port automatically. When enabled, a loopback VGMPLAY_BIND is automatically widened to 0.0.0.0 so the router can reach it. The tray menu reports whether the mapping opened, and /api/status includes the LAN and external URLs. VGMPlay renews the one-hour lease every 30 minutes and removes it when Quit VGMPlay is selected. VGMPLAY_UPNP_PORT can select a different external port; when empty, it uses the listening port.

All library, artwork, media-stream, scan, favorite, and management endpoints require a signed-in local VGMPlay account. UPnP exposes the protected sign-in surface to the internet, so use strong, unique passwords and only enable it when remote access is intentional. A router mapping does not automatically create a Windows Firewall rule.

Example for the current test library:

AUDIO_CD_PATH="D:/Music/RomRoot/ReDump/ReDump/Audio CD"
BLURAY_PATH=""
VGMDB_USERNAME="your-user-name"
VGMDB_PASSWORD="your-password"

Never commit .env; it is ignored by Git.

Local accounts and favorites

VGMPlay starts in first-run setup mode when no local accounts exist. The first account becomes the administrator. After setup, the sign-in screen offers listener registration; self-registered accounts can keep their own favorites and playback preferences but never receive administrator access. Administrators can also create, promote, disable, and delete accounts from the user-management panel. Disabled accounts lose their active sessions immediately, and the final enabled administrator cannot be removed.

Passwords are hashed with Argon2id. Browser sessions use random HTTP-only, SameSite cookies and expire after 30 days. Session tokens are hashed before they are stored. The local account database is .vgmplay-cache/accounts.sqlite3 by default.

Track favorites and listened-track history are stored in that database per user. A track is marked listened only after playback runs from the beginning to its natural end without seeking; completed tracks, discs, and release covers receive distinct library styling. A grouped multi-disc release is complete only after every disc slot is complete, while alternate dumps of the same disc are not required twice. Playback position, volume, shuffle, repeat, and library-view preferences are also namespaced to the signed-in user in the browser. The VGMdb login remains a separate server-side integration and is never used as a VGMPlay account.

Supported media

• Redump Audio CD BIN/CUE sets in folders or ZIP archives. Folder tracks stream directly from the original BIN files with a virtual WAV header and byte-range seeking.
• Numbered (Disc 1), (Disc 2), and (Alt) archives grouped as one release, with automatic playback handoff between numbered discs and selectable alternate variants.
• CUE INDEX 01 boundaries, including per-track pregaps and single-BIN multi-track discs.
• ZIP Deflate and Deflate64 entries.
• ZIP Zstandard entries (compression method 93).
• Whole ZIP files wrapped as .zip.zst.
• Loose FLAC, WAV, MP3, Ogg Vorbis, Opus, M4A, and AAC files.
• Redump BD-Video ISO discovery. ISO releases appear in the library, but encrypted or archived Blu-ray title playback is not decoded in this first version.

Persistent metadata

Successfully downloaded VGMdb metadata and cover artwork are stored under VGMPLAY_CACHE_PATH and restored automatically at startup and after every library rescan. Cache restoration follows the stable Redump disc identity, so moving a release between ZIP and folder storage reuses and migrates its existing cover and track titles without contacting VGMdb again.

Loose raw CDDA streams as 44.1 kHz / 16-bit / stereo WAV directly from its source BIN without being copied. Archived CDDA becomes a cached WAV on first play so compressed ZIP and .zip.zst sources remain supported. Source files are never modified.

VGMdb and cover art

VGMPlay searches the serials supplied by Redump, including comma-separated alternate serials and first-disc catalog numbers derived from later discs. It stores successful metadata as JSON and downloads the selected album cover into .vgmplay-cache/covers.

VGMdb is protected by Cloudflare, so Windows builds use a real Edge/WebView2 sign-in session. Select Sign in to VGMdb from the tray menu. If VGMDB_USERNAME and VGMDB_PASSWORD are set, VGMPlay fills and submits the login form; otherwise, sign in manually. Once VGMdb confirms the login, VGMPlay captures the required HttpOnly session and clearance cookies through WebView2's native cookie manager.

The browser profile is stored in .vgmplay-cache/webview2, and the request cookie plus matching browser user-agent are stored in .vgmplay-cache/auth/vgmdb-session.json. Both paths are local and ignored by Git. Treat the cache and .env like passwords.

On Windows, VGMPlay reads VGMdb search and album pages through the authenticated WebView2 profile first. The browser stays hidden during normal metadata lookups; if Cloudflare requires fresh human verification, the pending lookup opens the verification window and continues after it succeeds. The public vgmdb.info compatibility endpoint is a short-timeout fallback, and incomplete responses without track data are never cached.

VGMDB_COOKIE remains available as a manual fallback, but it is normally unnecessary.

Cache and performance

The default cache directory is .vgmplay-cache:

• audio/ — seekable tracks extracted from archives on first play; loose folder tracks bypass this cache.
• archives/ — materialized ZIPs for whole-file .zip.zst inputs.
• metadata/ — VGMdb JSON responses.
• covers/ — downloaded cover images.
• auth/ — captured VGMdb request session.
• accounts.sqlite3 — local users, hashed sessions, per-user track favorites, and listened-track history.
• webview2/ — persistent Edge sign-in profile.

Scanning reads archive central directories and CUE files; it does not hash or decompress every audio track. This keeps startup work proportional to the number of archives rather than the size of the collection.

Configuration

Variable	Default	Purpose
AUDIO_CD_PATH	empty	Root containing Audio CD folders/archives
BLURAY_PATH	empty	Root containing BD-Video data
VGMDB_USERNAME	empty	Optional VGMdb account name
VGMDB_PASSWORD	empty	Optional VGMdb account password
VGMDB_COOKIE	empty	Optional manual Cloudflare/session cookie fallback
VGMDB_API_BASE	https://vgmdb.info	Compatibility API base URL
VGMPLAY_BIND	127.0.0.1:4816	Local listen address
VGMPLAY_CACHE_PATH	.vgmplay-cache	Cache directory
VGMPLAY_DAT_PATH	dats	Redump DAT directory
VGMPLAY_OPEN_BROWSER	false	Open the UI after startup instead of waiting in the tray
VGMPLAY_UPNP	false	Automatically map the listening TCP port through an UPnP router
VGMPLAY_UPNP_PORT	listening port	Optional external TCP port

.env, .vgmplay-cache, target, output, and local Redump catalog files are ignored by Git. Do not add any of them to a commit: they can contain credentials, browser sessions, local account data, generated media, or machine-specific paths.

Verification

cargo fmt -- --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release

The test suite covers accounts and session safeguards, per-user favorite isolation, DAT/CUE parsing, direct loose-file WAV range streaming, archived-track materialization, VGMdb response parsing, archive-name handling, and actual ZIP method-93 decompression.

License

VGMPlay is available under the MIT License. See LICENSE.