Arkadia is a preservation-grade desktop application for managing large offline ROM archives across multiple physical disks, with an integrated metadata catalog, offline-first scraping workflow, and coming Arkadia Media Packs.
It provides a structured, integrity-first approach to organizing, verifying, and distributing artifact collections derived from DAT files — ensuring filesystem state and catalog state are always aligned, and that no artifact is ever considered present without independent verification.
Arkadia is being developed toward a complete personal preservation workflow tool:
- Import DAT files from preservation authorities (No-Intro, Redump, TOSEC, MAME, FBNeo, EggmansWorld)
- Manage a multi-disk physical archive with integrity verification
- Browse the full collection via a rich Catalog with cover art, screenshots, metadata, and media previews
- Scrape metadata and media from online scraping providers with a review-before-apply flow
- Normalize metadata values consistently via configurable mapping rules
Arkadia.sln
├── Arkadia.csproj — Avalonia 11 / .NET 8 desktop app (Windows)
│ ├── Data/ — DatLineStore, CatalogService, MediaStore, normalizers
│ ├── Library/ — LibraryEntry, title resolution
│ ├── Providers/ — scraping provider clients and import services
│ ├── Ingestion/ — DAT parsing and ingest pipeline
│ ├── Themes/ — Theme engine, palette management
│ └── MainWindow.axaml — Single-window UI with view switching
└── Arkadia.Tests.csproj — xUnit test project (~975 tests)
The application is a single-window app with a left nav bar switching between views: Dashboard, Analytics, Providers, Systems, Operations, Catalog, Settings.
At runtime, Arkadia writes all data next to the executable (AppContext.BaseDirectory):
data/
catalog.db — global catalog (systems, DAT lines, settings, mappings)
media/
<hardwareFamilyId>/
<datLineId>/
covers-front/ — regional front covers
covers-back/
covers-spine/
covers-wrap/
screenshots-title/ — title screen shots
screenshots/ — gameplay screenshots
fanart/
videos/
logos-hd/
logos/
marquees/
flyers/
manuals/
physical/ — physical media photos
physical-texture/
metadata/ — raw provider metadata payloads
platforms/
<hardwareFamilyId>/
<datLineId>/
releases.db — per-DAT SQLite DB (releases, artifacts, proposals, etc.)
incoming-media/ — manual media intake source folder
scrape-cache/ — registered provider cache packages
staging-cache/ — provider cache builder staging
libraries/
lib-vlc/win-x64/ — LibVLC runtime (not committed; place manually)
logs/
ingest/
volume-verify/
repair/
imagecache/
integrity/
themes/
visual/default/ — theme and badge icon assets (committed)
tools/
7zip/
7zip.exe — 7-Zip console binary (renamed from 7z.exe or 7zz.exe)
7z.dll — 7-Zip library (required when using 7z.exe variant; omit for 7zz standalone)
chdman/
chdman.exe — MAME chdman tool for CHD compression
dolphintool/
DolphinTool.exe — Dolphin RVZ compression tool
wudcompress/
WudCompress.exe — WUD/WUX compression tool
A DAT provider is an authority that defines release identity and technical catalog data. DAT provider data is canonical technical input — it determines what a release is (name, region, format, size, checksum, parent/clone relationships). It is entirely separate from online scraping providers, which enrich entries with titles, artwork, and descriptions but do not replace DAT identity.
Supported DAT providers:
| Provider | Typical scope |
|---|---|
| No-Intro | Cartridge-based systems (SNES, GBA, N64, …) |
| Redump | Optical disc systems (PS1, PS2, Saturn, …) |
| TOSEC | Broad multi-platform coverage |
| MAME | Arcade drivers, BIOS sets, devices, software lists |
| FBNeo | Arcade (Final Burn Neo) |
| EggmansWorld | Supplemental/community collections |
A Hardware Family groups related DAT lines under one catalog context (e.g., all SNES releases, or all MAME arcade entries). A DAT Line represents one imported DAT scope under a family — each has its own isolated SQLite database. Display labels are generated at runtime from authority + media type (e.g., MAME · ROM, Redump · DVD); the raw dat_lines.name column stores neutral media-type data, not formatted display text.
Deleting a hardware family is blocked while any DAT lines exist under it.
The Catalog view is the primary browsing interface. It shows all releases across a selected system and DAT line, with filtering, search, and a detail panel showing:
- Cover gallery (regional covers: front / back / spine / wrap)
- Media gallery (videos, screenshots, fanart)
- Extras (logos, flyers, marquees)
- Manuals (PDF/image files, opened in the system viewer)
- Physical media photos
- Metadata grid (status, system, year, region, genre, developer, publisher, language, rating, players)
- Metadata quality checklist and quality indicator
- Description and Extra Notes
MAME DATs describe arcade drivers, BIOS sets, devices, and software lists. Release identifiers are shortnames (e.g., anmlbskt) — not human-readable titles. When scraping MAME releases, set Scrape As System to arcade so lookups target the correct external provider system. Because shortnames rarely match title searches, use the exact ROM fallback in ScrapeReviewDialog to locate the correct game by hash.
Future MAME-specific complementary extraction (driver metadata, parent/clone relationships, working state, technical flags) will be stored separately from provider metadata and will not be overwritten by online metadata providers.
| Data | Origin |
|---|---|
| Release identity, shortname | DAT provider |
| Region, format, media type | DAT provider |
| Size, checksum | DAT provider |
| Parent / clone / software-list relationships | DAT provider |
| Technical flags (working state, BIOS, device) | DAT provider |
| Title, original title, description | Online metadata provider |
| Developer, publisher, year, genre | Online metadata provider |
| Rating, players | Online metadata provider |
| Screenshots, video, covers, manuals | Online metadata provider |
DAT-derived facts feed badges, quality indicators, and future filters. They are never overwritten by metadata scraping.
Arkadia is designed around a provider-based scraping model. Online providers can be used to build local, sanitized cache packages. Once registered, those packages allow Arkadia to scrape and curate entirely offline. Provider-specific setup and workflow details are documented in the Cache & Curation Pipeline.
Provider metadata is always saved as pending proposals first — nothing is applied to the catalog without user review in the Merge Metadata dialog. Canonical metadata and DAT identity are kept strictly separate.
- Provider selection — choose an online scraping provider
- ScrapeReviewDialog — search candidates by title, or accept an exact ROM match; review results before committing
- Fetch details — full metadata and media URLs are retrieved
- Import service — normalizes fields, saves proposals as pending (
accepted=0), stores raw metadata payload, downloads all media - MergeMetadataDialog — review each proposed field; fields with existing values show SAME/MANUAL/LOCKED status; user selects which to apply; LOCKED fields cannot be overwritten without explicit override
Standard workflow:
- Create System and set Scrape As System ID if needed
- Import DAT file
- Review Catalog — releases are immediately browsable with DAT-derived identity
- Scrape metadata — provider proposals are saved as pending
- Merge metadata — review proposed fields, apply selections
- Use Edit Metadata for manual corrections or locked-field overrides
MAME / arcade workflow:
- Import MAME-derived DAT — shortnames become release identifiers
- Set Scrape As System =
arcade - For each release, use ScrapeReviewDialog with exact ROM fallback (shortnames don't match title search)
- Future complementary extraction will enrich working state, driver metadata, and parent/clone trees without touching metadata proposals
Manual metadata entry for any release. Each field has a lock checkbox. Controlled-vocabulary fields (genre, release_type, region, etc.) are normalized via the metadata value mapping rules before saving.
Each metadata field can be locked per release. Locked fields are skipped when proposals are auto-applied (during bulk scrape) and show a LOCKED badge in the Merge Metadata dialog. Locks can be toggled per-field in both Edit Metadata and Merge Metadata.
A global table of normalization rules (field, match_value, replacement, enabled). Rules are seeded with defaults (e.g., region/wor → World, release_type/fantranslation → Fan Translation) and can be managed in Settings → Metadata Value Mappings. Applied at proposal-save time, manual-edit time, and badge display.
Media files use indexed stems: <releaseStem>_<index>.<ext> (screenshots, fanart, logos, etc.) or <releaseStem>_<region>_<index>.<ext> (regional covers). The provider import service deduplicates by expected byte size before downloading.
AMP (.amp) is the planned Arkadia-native curated package format: provider-agnostic, suitable for offline reuse and distribution where legally permissible. AMP packages carry accepted media, canonical metadata, credits, Extra Notes, preferred state, and exclusion hashes — but no raw provider payloads and no visible provider provenance.
ARK (.ark) is the Arkadia Backup / Archive format (v0.5 implemented) for database and application state backup/restore. It is not a media pack.
ARK backups are created via the Backups sidebar section. Packages are written to backups\ in the application folder alongside a .ark.sha256 integrity sidecar. The log shows creation progress and automatic verification. Live restore while the application is running is intentionally blocked — a restart-safe restore workflow is planned.
AMP is not a backup. ARK is not a media pack.
AMP v1 specification: docs/SPECS/ARKADIA_MEDIA_PACK_V1_SPEC.md
Arkadia uses bundled external tools for compression and archive extraction. Tools are not committed to the repository. Place them next to the executable before using the features that require them.
Naming convention: tools\<toolname>\<toolname>.exe
| Tool ID | Path | Source | Used for |
|---|---|---|---|
7zip |
tools\7zip\7zip.exe |
7-Zip (7-zip.org) | MAME SFX extraction; .7z and .rar ingest |
chdman |
tools\chdman\chdman.exe |
MAME Tools | CHD compression (CD, DVD, GD, PSP, Dreamcast) |
dolphintool |
tools\dolphintool\DolphinTool.exe |
Dolphin Emulator | RVZ compression |
wudcompress |
tools\wudcompress\WudCompress.exe |
WudCompress | WUX compression |
7-Zip setup: 7-Zip is distributed as either a split package (7z.exe + 7z.dll) or a standalone binary (7zz.exe). Both can be placed in tools\7zip\ after renaming the primary executable to 7zip.exe. Renaming is safe — 7z.dll is loaded by its own hardcoded name and does not depend on the executable filename.
- Split package: place
7zip.exe(renamed from7z.exe) and7z.dllintools\7zip\ - Standalone: place
7zip.exe(renamed from7zz.exe) intools\7zip\— no DLL needed
If 7zip is not present, MAME provider extraction is blocked and .7z/.rar ingest archives are skipped with a log message. ZIP archives work without 7zip.
chdman follows the tools\<toolname>\<toolname>.exe convention exactly.
dolphintool and wudcompress use upstream executable names (DolphinTool.exe, WudCompress.exe) that differ from the folder name casing. These will be normalized in a future migration.
Video previews in the Catalog gallery require LibVLC. Place the libvlc.dll and related files in libraries/lib-vlc/win-x64/ next to the executable. If absent, videos fall back to a text label with a play overlay.
git clone https://github.com/your-org/arkadia.git
cd arkadia
dotnet build
dotnet test
dotnet run --project Arkadia.csprojRequirements: .NET 8 SDK, Windows 10+.
dotnet publish Arkadia.csproj -c Release -r win-x64 --self-contained true \
-p:PublishSingleFile=false -p:PublishReadyToRun=true -o publish/The publish/ directory contains the self-contained executable. Copy libraries/lib-vlc/win-x64/ alongside it for video playback support.
| Area | Status |
|---|---|
| Multi-volume archive management | Stable |
| DAT import (No-Intro, Redump, TOSEC, MAME, FBNeo, EggmansWorld) | Stable |
| SHA1 integrity verification | Stable |
| Volume plan / build / append / reabsorb | Stable |
| Repair workflow | Stable |
| Catalog browse with cover/media gallery | Stable |
| Manual scrape with review-before-apply | Stable |
| Offline scraping from registered cache packages | Stable |
| Bulk scraping from registered cache packages | Stable |
| Online provider cache builder | Stable |
| Metadata proposals + Merge dialog | Stable |
| Edit Metadata with field locks | Stable |
| Metadata value mappings (Settings) | Stable |
| Media curation (Manage Media workbench) | Stable |
| Extra Notes per release | Stable |
| Theme engine with palette support | Stable |
| LibVLC video preview | Stable |
| Arkadia Media Pack (.amp) export | Stable |
| Arkadia Backup / Archive (.ark) — backup creation UI | Stable (v0.5); live restore blocked pending restart-safe flow |
| Additional online providers | Planned |
Curated release view with canonical metadata, covers, video, logos, manuals, physical media, and quality checks.
DAT-backed release inventory with regions, languages, source files, hashes, and preservation status.
|
MAME DAT Generator — Prepare versioned MAME data with driver exploration, family rules, filters, and DAT generation. |
Redump DAT Downloader — Download system DATs from supported preservation sources and track acquisition logs. |
|
Systems and DAT Import — Manage platforms, inspect hardware details, and import DAT lines with progress tracking. |
Disks — Register and monitor archive disks with capacity, filesystem, usage, and volume assignment details. |
- User Manual
- Developer Notes
- Cache & Curation Pipeline — provider cache builder, staging, registered cache manager, verify package, offline / bulk scraping, Manage Media workbench, Extra Notes, AMP direction
- AMP v1 Specification — Arkadia Media Pack format specification
- ARK v0.5 Specification — Arkadia Backup / Archive format specification
- Roadmap
MIT License. See LICENSE for details.