rommapp/romm 5.3.0-beta.1

on GitHub

filesystem:
  structure:
    default: "roms/{platform}/{game}"
    firmware: "bios/{platform}"

filesystem:
  structure:
    default: "{platform}/roms/{game}"
    firmware: "{platform}/bios"

Highlights

Custom library structure

Instead of guessing between two folder structures, describe your exact library layout in config.yml. {platform} is the platform folder, the final {game} is where a game starts, and anything else in {braces} is just a folder you use to organize things. You can override the layout per platform, and give a platform a list of layouts when its games sit at more than one depth. #3571

ROM identity is now content-hashed, so you can move files around and keep their saves, favorites, play history and collections. And if you came from Batocera, RetroBat or ES-DE, their platform folder names are recognized out of the box, so most libraries need no mapping at all. #4345

filesystem:
  structure:
    default: "roms/{platform}/{game}"
    firmware: "bios/{platform}"
    ps3: "roms/{platform}/{category}/{game}"
    snes: "roms/{platform}/{region}/{game}"
    nes:
      - "roms/{platform}/{game}"
      - "roms/{platform}/{category}/{game}"

Docs: Custom library structure, Folder name aliases

Emulator streaming V2

A massive update to emulator streaming. You configure one entry per container instead of one per emulator, a platform can pool several containers and grab whichever one is free, and platforms that do both browser and streamed play now get separate Play and Stream buttons. #4314

Saves and save states made while streaming are pulled back into your library with history and thumbnails. Multi-disc games get a disc-swap control, and whichever disc was mounted when you saved is the one remounted when you load. PS2 and GameCube can sync a whole memory card instead of individual save files, with a memory card library to create, rename, version, share and download them. Admins get a desktop session for setting up an emulator with no game running, plus a fleet view to force-release sessions across every container.

Docs: Emulator Streaming

Physical games

Own a game on a cartridge or disc, but have no ROM for it? You can now add it anyway, by name or by scanning its barcode with your camera, and it gets matched to metadata like any other game. #3848

Docs: Physical Games

Walkthroughs

Walkthroughs are now documents on a game, sitting next to its manuals. Upload your own, or paste a GameFAQs URL and have it fetched directly (as plain text). It'll even remember where you left off and show a progress bar for each user. #3816

Docs: Walkthroughs

Title IDs read from the binary

Scans now pull a game's native Title ID straight out of its binary on PSX, PS2, PS3, PSP, PS Vita, Switch, 3DS, Wii, Wii U, GameCube, Dreamcast, Xbox and Xbox 360. It identifies games on the platforms we don't hash, so a renamed or moved file keeps its saves and collections, and it tells the system where a game writes its saves, so device sync knows what to look for. #3925

Docs: Title ids read from the binary

Jukebox

A soundtrack player for your whole library that follows you as a mini player anywhere in the app. Browse by album, platform, artist or genre, or just put a playlist on: Free Radio picks a randomized, album-balanced hour, and there's a Decade Mix, recently added, and your personal favorites. #4197

Docs: Jukebox

JS-DOS and PICO-8 in the browser

Windows 3.x and 9x games now run on js-dos and its DOSBox-X backend. Note that js-dos saves stay in your browser and are not synced back to the server. #4061

PICO-8 cartridges (.p8 and .p8.png) are also now playable, on FAKE-08, with keyboard + mouse, gamepad, or touch input. #4400

Docs: js-dos, PICO-8

Four new metadata sources

Steam is now a metadata source for the win, linux and mac platforms, no API key required! #4241

Demozoo, Pouët and CSDb cover demoscene productions on platforms we already support. Tag a file (demozoo-108), or paste an id or a production URL into the ROM editor. #4221

scan:
  priority:
    metadata:
      - steam # PC platforms only

Docs: Metadata Providers

EmulatorJS cores and multi-disc games

A multi-disc game is handed to EmulatorJS all at once now, so you can swap discs from the emulator's own menu instead of going back and reloading. Set emulatorjs.disable_batch_bootup to boot only the disc you launched, if a core mishandles the batch. #3988

You can also preselect a core per platform with emulatorjs.default_cores. That sets the starting point, and anyone who has already picked a core on their device keeps their choice. #4452

Docs: Cores, Multi-disc games

Library-aware recommendations

Recommendations are now built from your own library, blending metadata overlap, the list pulled from IGDB, and what you actually play. You'll find them under Similar games on a game's page, and in a new Recommended for you row on the home screen. Enable it by setting ENABLE_SCHEDULED_BUILD_RECOMMENDATIONS=true in your env vars. #4174

Docs: Recommendations

Automatic save sync

A save reaches the server when you save and quit, which means a closed tab, a browser crash or a laptop going to sleep leaves it on the device. Turn on emulatorjs.auto_save_sync and the player uploads the save whenever the emulator writes one instead, so there's nothing to lose by closing the tab mid-game. It's off by default because a game that saves often uploads often, and each upload is the whole save file. #4378

Docs: Automatic save sync

Sort and filter by game length

You can now sort and filter the gallery by how long a game takes, straight from the gallery rather than having to build a collection for it. It's based on the HowLongToBeat main story time, so it needs HLTB_API_ENABLED and a scan that matched the game. #4392

Docs: Game length

Minor changes

• feat(v2): link Server Stats platform rows to their platform by @sdornan in #4252
• feat(gallery): pick a game's default version by region priority by @sdornan in #4260
• feat: split company metadata into publishers and developers by @gantoine in #3898
• feat(saves): scope save discovery to a set of ROM IDs by @gantoine in #4304
• feat(hasheous): make the Hasheous API URL configurable by @closer in #4300
• feat(scan): refresh files scan and uploads into rom folders by @zurdi15 in #4277
• feat(player): confirm before leaving a running game by @gantoine in #4308
• feat(v2): make game header tags clickable by @gantoine in #4372
• feat(v2): zoom the game cover, and dismiss the lightbox from anywhere on the backdrop by @gantoine in #4373
• feat(home): add a game anniversary widget by @Spinnich in #4396
• feat(firmware): let missing firmware be found, cleaned up, and kept out of the player by @Spinnich in #4077
• feat(v2): show a reading-progress bar in the manual and walkthrough viewers by @gantoine in #4470
• feat: offer Steam as a match provider for PC platforms by @sdornan in #4498
• feat: offer Steam as a cover art provider by @zurdi15 in #4500
• feat(streaming): let the launch screen pick which save to restore by @LoneAngelFayt in #4507
• feat(player): slot-aware saves list, server-side slot retention and launch-screen fixes by @zurdi15 in #4540
• feat(player): sync in-game saves seconds after the game writes them by @zurdi15 in #4558
• feat(v2): polish upload actions and pickers across details, player and scan settings by @zurdi15 in #4576
• feat(v2): open the EmulatorJS and js-dos launch views without a page load by @zurdi15 in #4567
• feat(v2): phone-friendly tabs, subtabs and patch picker in game details by @zurdi15 in #4578
• feat(v2): phone-friendly list rows, soundtrack header and mini player by @zurdi15 in #4580
• feat(player): keep unsynced saves and states in the browser and retry them by @zurdi15 in #4600
• feat(player): load saves and states from one in-game picker by @zurdi15 in #4615
• feat(v2): unify platform/collection settings and fill the viewport by @zurdi15 in #4618

Fixes

• fix(v2): Fix missing v2 auth notifications by @Florian-Cullmann in #4246
• fix(v2): remember the core a game was launched with by @gantoine in #4251
• fix(frontend): keep collection ROM counts in step with the gallery by @sdornan in #4261
• fix(hltb): keep a pinned HowLongToBeat match through a rescan by @sdornan in #4262
• fix(roms): Fix N+1 and entity sort in GET /api/roms by @tmgast in #4264
• fix(auth): send PKCE on the OIDC authorization request by @jgarcesres in #4267
• fix: Preserve nested arcade ROM filenames by @mvanhorn in #4271
• fix: map Neo Geo MVS/AES to the RetroAchievements Arcade console by @gantoine in #4282
• fix: restore HowLongToBeat lookups and repair endpoint discovery by @sdornan in #4286
• fix(scan): let update metadata scans refresh artwork, and record uploads explicitly by @sdornan in #4160
• fix(screenscraper): map mega-duck-slash-cougar-boy to ss id 90 by @gantoine in #4307
• fix(platforms): add doom as a platform with its standalone provider mappings by @gantoine in #4309
• fix(roms): stop a racing upload from undoing a folder conversion by @tmgast in #4316
• fix(manual): only ask where a manual goes when the answer is open by @tmgast in #4315
• fix(logs): stop a multi-line record painting over the rows after it by @sdornan in #4303
• fix: allow INI files in library scans by @mvanhorn in #4328
• fix(frontend): Add crossorigin attribute to manifest link so CloudFlare Tunnels does not break site.webmanifest by @Macleykun in #4332
• fix(player): Show a clear message instead of the generic error for threaded cores over non-secure origins by @TRusselo in #4313
• fix(v2): read the date picker's value in UTC, not local time by @sdornan in #4322
• fix(backend): Rate limit the unauthenticated metadata heartbeat endpoint by @gantoine in #4327
• fix(download): make cached zips readable by nginx and serialize their builds by @tmgast in #4329
• fix(scan): Follow-ups to the sigil title ID branch by @gantoine in #4333
• fix(export): write gamelist media where ES-DE and Batocera frontends find it by @sdornan in #4344
• fix(retroachievements): don't match ROMs against games with no achievement set by @Spinnich in #4352
• fix(scan): let a complete rescan clear the ids it rematched by @Spinnich in #4353
• fix(collections): honor "Show autogenerated collections" on the v2 collections page by @Spinnich in #4355
• fix(hashing): read zips zipfile can't decode through 7zz by @sdornan in #4357
• fix(db): make virtual_collections and generated columns collation-agnostic by @gantoine in #4374
• fix(v2): don't reload the page on reconnect while a game is running by @gantoine in #4369
• fix(db): make migrations collation-agnostic on MariaDB by @gantoine in #4371
• fix(export): share the ES-DE media folders with the Pegasus export by @sdornan in #4370
• fix(auth): require platforms.write and enforce platform visibility on the export endpoints by @gantoine in #4376
• fix(export): merge gamelist.xml and metadata.pegasus.txt instead of overwriting by @sdornan in #4368
• fix(screenscraper): let the daily-quota breaker recover by @Spinnich in #4360
• fix(server): default to 4 API workers and fix the WEB_SERVER_CONCURRENCY guidance by @Spinnich in #4385
• fix(gallery): join roms_metadata before the grouped dedup window by @gantoine in #4390
• fix(docker): bump sigil past the zstd asm link failure by @sdornan in #4404
• fix(firmware): 404 the content endpoints when the file is gone by @gantoine in #4405
• fix(v2): read the webp flag the heartbeat actually sends by @gantoine in #4406
• fix(auth): sanitize the username an OIDC provider hands us by @gantoine in #4407
• fix(ra): return achievements in RetroAchievements' display order by @gantoine in #4408
• fix(v2): keep a click in selection mode from navigating away by @gantoine in #4409
• fix(db): recycle pooled connections before the server drops them by @gantoine in #4411
• fix(v2): keep the player from booting a rom's media instead of the game by @gantoine in #4412
• fix(ss): let region_mode decide the title, not just the artwork by @gantoine in #4413
• fix(scan): tell the clients when SCAN_TIMEOUT killed the scan by @gantoine in #4414
• fix(roms): keep unplayed games when sorting by a rom_user column by @zurdi15 in #4424
• fix(player): keep RomM chrome off the emulator on mobile by @zurdi15 in #4425
• fix(tasks): match a running task by its registry key by @sdornan in #4430
• fix(tasks): refill the Switch TitleDB store a schema bump drops by @sdornan in #4432
• fix(frontend): 404 unmatched URLs in v2 instead of "not migrated yet" by @sdornan in #4455
• fix(frontend): stop ESLint and Prettier fighting over formatting by @sdornan in #4456
• fix(v2): announce the hash chip's disclosure state and action by @zurdi15 in #4451
• fix(v2): give the gallery a real Select all in both layouts by @zurdi15 in #4453
• fix(roms): sort unset per-user and metadata keys last on every engine by @zurdi15 in #4454
• fix(migrations): let every 5.3.0 revision be replayed by @gantoine in #4484
• fix(roms): invalidate a user's gallery sidecars on rom_user writes by @zurdi15 in #4463
• fix(roms): sort grouped galleries by the best sibling's key by @zurdi15 in #4465
• fix(v2): dismiss tooltips when an overlay opens over them by @sdornan in #4482
• fix(patcher): apply patches to ROMs inside ZIP archives by @kylebenzo in #4472
• fix(streaming): prefer the emulator's own screenshot for save-state thumbnails by @LoneAngelFayt in #4478
• fix(tasks): fill the scan counters a job's stored stats predate by @sdornan in #4480
• fix(migrations): name the fix when the server denies trigger DDL by @gantoine in #4490
• fix(v2): address review findings on the shared metadata provider card by @zurdi15 in #4516
• fix(frontend-v2): center the recommendation caption under the card by @sdornan in #4510
• fix(player): boot from the picked save and file web saves under sync slots by @zurdi15 in #4517
• fix(scan): send Playmatch as a metadata source so the UI switch works by @gantoine in #4519
• fix(player): stop hiding EmulatorJS's own messages by @gantoine in #4520
• fix(collections): pick the current user's favorites collection by @gantoine in #4521
• fix(player): never boot a multi-disc playlist on its own by @gantoine in #4524
• fix(player): give a gamepad a way onto the Play button by @gantoine in #4525
• fix(v2): compare typed confirmations on the rendered phrase by @gantoine in #4523
• fix(v2): remove double border on selected game cards by @zurdi15 in #4547
• fix(v2): make the Missing games selection actionable by @gantoine in #4527
• fix(v2): stop offering a missing rom's files for download by @gantoine in #4528
• fix(player): attach a real screenshot to a manual save state by @gantoine in #4526
• fix(tasks): refuse a manual task run when no worker is listening by @zurdi15 in #4548
• fix(tasks): read older cleanup stats, and check the worker where it enqueues by @zurdi15 in #4551
• fix: treat every disc descriptor as a disc, not just .cue by @sdornan in #4532
• fix(v2): jukebox in the settings sidebar, launch-view titles, match overlay by @zurdi15 in #4555
• fix(v2): make the player back links and the details Play button real links by @zurdi15 in #4560
• fix(streaming): pool same-origin webstation containers and keep a claim on its own container by @LoneAngelFayt in #4533
• fix(scan): don't report an unanswered lookup as a confirmed miss by @gantoine in #4534
• fix(streaming): make broker save-clearing configurable and date the picker by its sort key by @LoneAngelFayt in #4542
• fix(tools): repair the test-data seeder's imports and rom digests by @sdornan in #4554
• fix(v2): stop the layout's min-height leaking into the gallery shell by @sdornan in #4563
• fix(v2): line the placeholder rows up with the rows they stand in for by @sdornan in #4561
• fix(v2): invoke the view transition callback once by @sdornan in #4574
• fix(v2): stop probing platform icon variants that cannot exist by @sdornan in #4573
• fix(v2): stop the unhandled rejection when a view transition is preempted by @sdornan in #4570
• fix(scan): read PSX and PS2 serials sigil missed and identify multi-disc roms by their first disc by @tmgast in #4566
• fix(deps): bump engine.io-client past the ws memory-exhaustion advisory by @sdornan in #4571
• fix(v2): close the launch-path gaps found by the pr-ready gauntlet by @gantoine in #4579
• fix(frontend): restate the player isolation URLs instead of reading nginx by @gantoine in #4583
• fix(about): show current git branch instead of "development" by @zurdi15 in #4617
• fix(roms): answer the id endpoints without building every Rom by @sdornan in #4584
• fix(backend): return identifiers without building an ORM row per id by @sdornan in #4586
• fix(roms): read note authors off the joined user by @sdornan in #4588
• fix(collections): project identifier columns instead of loading whole collections by @sdornan in #4589
• fix(roms): load the parent rom with a rom file so the file schema validates by @sdornan in #4593
• fix(v2): UI/UX polish: unified empty states, smoother loading, tab query cleanup by @zurdi15 in #4594
• fix(gallery): hold the v2 list-view columns still while rows load by @sdornan in #4598
• fix(v2): drop the box behind platform icons in the list row by @sdornan in #4601
• fix(v2): right-align the list-view quantity columns by @sdornan in #4603
• fix(v2): align HLTB column values across the strip by @sdornan in #4604
• fix(v2): restore blurred glass off Safari and guard the unguarded subgrid by @sdornan in #4607
• fix(upload): accept empty ROM files by @zurdi15 in #4610
• fix(upload): refuse an empty file that declares chunks by @zurdi15 in #4611
• fix(upload): style the pending-files Add button as a primary add action by @zurdi15 in #4612
• fix(covers): keep animated covers animated after they are applied by @zurdi15 in #4613
• fix(states): fold core groups from the whole header, center card actions by @zurdi15 in #4614
• fix(covers): rework the search cover dialog layout by @zurdi15 in #4616
• fix(i18n): route hard-coded UI strings through the locale files by @sdornan in #4619
• fix(a11y): translate the v2 primitives' own control labels by @sdornan in #4620

Other changes

• chore(agents): add a review-polish skill from recurring PR corrections by @gantoine in #4250
• chore(deps): bump starlette from 1.0.1 to 1.6.0 by @sdornan in #4254
• refactor(v2): give the metadata provider taxonomy one home by @sdornan in #4263
• chore(deps-dev): Bump brace-expansion from 2.0.3 to 2.1.4 in /frontend by @dependabot[bot] in #4266
• chore(deps): Bump asyncssh from 2.23.0 to 2.23.1 by @dependabot[bot] in #4292
• refactor(v2): extract a shared player shell by @gantoine in #4301
• refactor(assets): make rom_ids the only ROM scope on saves and states by @gantoine in #4305
• docs(skills): merge pre-pr-verification into review-polish by @gantoine in #4311
• chore(deps): Bump tornado from 6.5.7 to 6.5.8 by @dependabot[bot] in #4324
• chore(deps-dev): Bump postcss-selector-parser from 7.1.1 to 7.1.5 in /frontend by @dependabot[bot] in #4325
• chore(deps-dev): Bump browserslist from 4.28.1 to 4.28.8 in /frontend by @dependabot[bot] in #4326
• chore(deps-dev): Bump fast-uri from 3.1.5 to 3.1.7 in /frontend by @dependabot[bot] in #4330
• chore(deps-dev): Bump @humanfs/node from 0.16.7 to 0.16.8 in /frontend by @dependabot[bot] in #4331
• chore: drop the vcrpy exclude-newer override by @sdornan in #4334
• refactor(tasks): schedule with RQ instead of rq-scheduler by @sdornan in #4274
• docs(agents): never run the full backend test suite locally by @gantoine in #4336
• perf(scan): give scans their own queue and worker by @sdornan in #4275
• ci: Bump GitHub Actions to Node 24 runtimes by @sdornan in #4341
• chore(deps): Bump cryptography from 49.0.0 to 50.0.0 by @dependabot[bot] in #4342
• perf(scan): coalesce scan progress reports, and give the rom refetch one home by @gantoine in #4340
• chore(dev): move the Authentik stack into docker-compose.oidc.yml by @gantoine in #4367
• chore(python): move the backend to Python 3.14 by @sdornan in #4359
• perf(tests): stop the suite waiting on connections it never wanted by @gantoine in #4375
• perf(backend): add missing gallery indexes and reconcile model/schema index drift by @sdornan in #4384
• perf(scan): read files in 256 KiB chunks instead of 8 KiB by @Spinnich in #4387
• perf(scan): default to 4 scan workers instead of 1 by @Spinnich in #4386
• chore(tasks): Quiet RQ per-tick scheduler heartbeat log line by @gantoine in #4393
• chore(deps-dev): bump vitest from 4.1.8 to 4.1.11 in /frontend by @dependabot[bot] in #4399
• chore(deps-dev): bump js-yaml from 4.3.1 to 4.3.2 in /frontend by @dependabot[bot] in #4401
• security: strip control characters from names reaching the mod_zip manifest by @gantoine in #4402
• perf(gallery): materialize the ids sibling_roms matches on by @Spinnich in #4394
• chore(agents): Add a pr-ready skill chaining the four PR review passes by @sdornan in #4415
• perf(metadata): stop storing the metadata dumps twice over in the cache by @gantoine in #4416
• perf(metadata): compress the cache-only metadata dump records by @sdornan in #4426
• docs: add a one-click deploys section to the README by @gantoine in #4427
• chore(deps): upgrade rq to 2.12 by @sdornan in #4428
• ci: align and manage the Docker service image pins by @sdornan in #4433
• docs: tighten the README copy by @gantoine in #4438
• ci: build each arch on a native runner and cache layers by @sdornan in #4437
• chore(deps): update astral-sh/setup-uv action to v10.1.0 by @renovate[bot] in #4440
• chore(deps): update postgres docker tag to v18 by @renovate[bot] in #4444
• chore(deps): update github actions (major) by @renovate[bot] in #4445
• ci: pin the amd64 image build to ubuntu-24.04 by @sdornan in #4458
• ci: run trunk check on master pushes by @sdornan in #4457
• chore(deps): update ghcr.io/goauthentik/server docker tag to v2024.12.5 by @renovate[bot] in #4441
• docs(examples): drop the gc override from the config example by @sdornan in #4461
• chore(ci): drop the docs and website release triggers by @gantoine in #4491
• perf(migrations): add the 5.3.0 roms columns in one table copy by @gantoine in #4501
• perf(docker): upgrade nginx to 1.29.8 and tune the serving layer by @sdornan in #4468
• docs: correct stale Vuetify claims in v2 skills and architecture doc by @sdornan in #4474
• chore(translation): translate the remaining untranslated zh_CN strings by @wolfg1969 in #4489
• refactor(roms): give the ROM filters a single home, and match them against the facets mirror by @sdornan in #4487
• ci: gate the preview-build report job on the build-preview label by @sdornan in #4475
• perf(frontend): precompress built assets and serve them with gzip_static by @sdornan in #4471
• chore(deps): update github actions by @renovate[bot] in #4513
• chore(uv): bump to 0.12.13 and make pyproject the single source for the version by @sdornan in #4469
• refactor(v2): unify metadata provider cards behind a shared component by @zurdi15 in #4515
• refactor(frontend): native fullscreen where it exists, one path for all players by @sdornan in #4514
• refactor(player): route the mount-time Play focus through the shared check by @gantoine in #4538
• chore(deps): update docker/setup-buildx-action action to v4.4.1 by @renovate[bot] in #4544
• style(player): one presentation for save and state facts by @zurdi15 in #4545
• docs: require screenshots and mermaid diagrams in PR descriptions by @gantoine in #4549
• chore(uploads): manual file uploads into a ROM across the Files and Media tabs by @zurdi15 in #4550
• chore(deps): bump nanoid from 3.3.16 to 3.3.19 in /frontend by @dependabot[bot] in #4530
• chore(deps-dev): bump @babel/core from 7.29.0 to 7.29.7 in /frontend by @dependabot[bot] in #4531
• docs: upload PR screenshots with gh --attach by @gantoine in #4625
• chore(frontend): upgrade vue-tsc to 3.x and raise the TypeScript floor by @sdornan in #4622
• chore(deps): bump md-editor-v3 from 5.8.5 to 6.5.4 in /frontend by @dependabot[bot] in #4627
• chore(storybook): light and dark theme switch work in storybook by @andest01 in #4626
• docs(claude): add a knowledge-base skill for Greptile's repo docs by @zurdi15 in #4595
• perf(backend): resolve roms without the related load in the file and props routes by @sdornan in #4590
• perf(backend): check rom-note visibility without the related load by @sdornan in #4587
• test(backend): stop the suite emitting warnings by @sdornan in #4597

New Contributors

• @jgarcesres made their first contribution in #4267
• @bphenriques made their first contribution in #4061
• @axelquack made their first contribution in #4221
• @closer made their first contribution in #4300
• @Macleykun made their first contribution in #4332
• @TRusselo made their first contribution in #4313
• @kylebenzo made their first contribution in #4472
• @andest01 made their first contribution in #4626

Full Changelog: 5.2.0...5.3.0-beta.1