5.0.0

Highlights

UI overhaul

A ground-up redesign of the UI, with a new design system, fresh visual language, and a universal input model that feels at home with mouse, touch, keyboard and gamepad alike. With a stronger emphasis on performance, responsiveness, ease-of-use and accessibility, the new UI should be a joy on any device. #3436

Shared savestates

Share your game saves and savestates with other users; useful for speedrunning, special unlocks, new game +, or just showing off your progress. #3569

Interactive 3D boxart

Boxart go weeeeeeeeeeeeeeeeeeeeeeeeeeeee! #3580

CRT mode

Take me back to the 90s with a CRT shader that simulates the look of those old displays we love dearly. #3552

Server-side ROM patching

We've unlocked the full power of ROM patching by moving it to the server. Simply apply patches to your ROMs, now with the option to use stored or uploaded patch files. #3225

QR code pairing

Quickly pair your PC, TV or handheld device with your server by scanning a QR code (currently available on Argosy Launcher and Playnite). #3308

Real-time logs

Tired of SSHing into your server to tail the logs when something breaks? Now you can view the backend logs in real-time directly from the web UI. #3557

Controller debug view

Test your controller inputs and mappings in real-time with a new debug view. #3581

Changelog preview

A quick peak at the changes in the current version, with links to the full changelog. #3560

Granular permission system

Tweak access to your library with per-user and per-group permissions, with one configurable default group for new users. Tri-state grant/revoke on top of the group, and per-entity overrides, allow for fine-grained control over who can see what. #3605

Music player

Music files stored within a ROMs' soundtrack folder can now be played directly from details page (#3610), and queried directly from the API (#3640). This opens the door to future features like background music playback and soundtrack playlists.

Minor changes

• Add ES-DE <sortname> import and edit support for ROM ordering by @gantoine in #3460
• fix(ra): hash PSP compressed-ISO containers natively (#3600) by @gantoine in #3609
• feat(roms): filter games by matched metadata provider by @Spinnich in #3615
• feat(roms): filter games by custom tags by @Spinnich in #3629
• Add ROM revision field to game details overview by @gantoine in #3631
• Add Artwork subtab to Media tab with scraped art gallery by @gantoine in #3634 and #3700
• Add filters for has save/state by @gantoine in #3642
• Support markdown manuals and enforce allowed file types by @gantoine in #3683
• feat(player): remember emulator core per-game by @gantoine in #3701
• feat: Add debug overlay by @zurdi15 in #3554

Fixes

• fix: Refresh platforms on scan by @zurdi15 in #3555
• Handle missing ROM files during delete-from-filesystem requests by @zurdi15 in #3562
• fix: guard SiblingBadge against missing sibling_roms (scan crash with Group ROMs) by @androosio in #3568
• Permission fix for exported game lists and Pegasus platform slugs mapping by @ametis70 in #3587
• fix(platform): accept embedded custom_name body on platform update by @gantoine in #3597
• fix(webp): backfill cover conversion on startup when enabled by @gantoine in #3602
• fix(scan): prevent duplicate ROM entries from racing scans by @gantoine in #3606
• fix(scan): make scan tracker totals reflect platforms actually scanned by @gantoine in #3607
• Fix state/save injection timing and corruption in EmulatorJS by @gantoine in #3624
• fix(scan): Normalize Sony serial codes to uppercase before cache lookup by @gantoine in #3622
• Fix ROM name handling in UNMATCHED scans to replace placeholders by @gantoine in #3623
• fix(backend): load platform_id on siblings to avoid DetachedInstanceError by @gantoine in #3635
• Fix ROM upload temp directory to use RESOURCES_BASE_PATH by @gantoine in #3632
• fix(roms): namespace filter-values cache by schema version by @Spinnich in #3638
• fix(retroachievements): match MSX2 against RetroAchievements (#3644) by @Spinnich in #3645
• fix(retroachievements): match Famicom Disk System (FDS) against RetroAchievements by @Spinnich in #3647
• fix(retroachievements): match SuperGrafx against RetroAchievements by @Spinnich in #3652
• Fix typo in core mapping from 'zsx' to 'zxs' by @sildur in #3656
• Refine filename version-tag parsing to avoid swallowing generic v* tags by @gantoine in #3658
• fix: make 1.8 migration re-entrant so fresh installs stop crash-looping on MariaDB by @mvanhorn in #3669
• fix(retroachievements): hash GameCube and Wii RVZ/WIA images natively by @Spinnich in #3657
• fix(collections): download whole collections as a single zip by @Spinnich in #3661
• fix: display selected firmware in player by @chiyi-creator in #3673
• fix: stop mapping Public Domain ROMs to Poland by @chiyi-creator in #3671
• fix: allow NAT64-wrapped public IPs through SSRF filter by @gantoine in #3675
• Use parsed filename for unmatched ROM titles instead of raw filename by @gantoine in #3681
• fix(scan): fall back to other providers when ScreenScraper quota is exhausted by @gantoine in #3686
• fix(launchbox): import local media when matching via update_rom by @gantoine in #3687
• feat: default UI language to browser language when available by @gantoine in #3690
• fix(platforms): stop platform variants from renaming the parent platform by @gantoine in #3693
• fix: generate virtual collections from all metadata sources by @gantoine in #3694
• fix(sockets): require TASKS_RUN scope for scan and scan:stop by @gantoine in #3698
• fix(roms): enforce parent ROM visibility on direct file endpoints by @gantoine in #3703
• fix(backend): correct M4A embedded cover extraction and validation by @VoidHandler in #3705
• fix(launchbox): match remote cover art region to ROM region by @gantoine in #3709
• fix(backend): serve PDF/Markdown m...

5.0.0-beta.5

What's Changed

• fix: remove deleted games from gallery store by @gantoine in #3745

Full Changelog: 5.0.0-beta.4...5.0.0-beta.5

5.0.0-beta.4

What's Changed

• fix(frontend): restore manual display and extract ManualSubtab by @gantoine in #3717
• Fixed the translation of "player-count" by @wolfg1969 in #3719
• fix(scan): make Hasheous and SteamGridDB scan lookups fault-tolerant in the metadata handlers by @TowyTowy in #3716
• ci: fail PRs that modify the frozen frontend v1 UI by @gantoine in #3723
• fix(backend): discard ScreenScraper chroma-key green placeholder art by @gantoine in #3724
• Add Freegosy to community tab in README by @abduznik in #3729
• Hotfix upload buttons in media tabs by @gantoine in #3732
• Update README featured projects by @QuaiGoner in #3738
• feat: inject ScreenScraper dev credentials at build time by @gantoine in #3740
• fix(ui): remove cover-art attribution link on details pages by @gantoine in #3737

New Contributors

• @wolfg1969 made their first contribution in #3719
• @TowyTowy made their first contribution in #3716
• @abduznik made their first contribution in #3729
• @QuaiGoner made their first contribution in #3738

Full Changelog: 5.0.0-beta.3...5.0.0-beta.4

5.0.0-beta.3

What's Changed

• fix(backend): correct M4A embedded cover extraction and validation by @VoidHandler in #3705
• fix(launchbox): match remote cover art region to ROM region by @gantoine in #3709
• fix(backend): serve PDF/Markdown manuals inline so the viewer can render them by @gantoine in #3714
• fix: surface config.yml parse errors instead of silently using defaults by @gantoine in #3713

New Contributors

• @VoidHandler made their first contribution in #3705

Full Changelog: 5.0.0-beta.2...5.0.0-beta.3

5.0.0-beta.2

What's Changed

• fix: allow NAT64-wrapped public IPs through SSRF filter by @gantoine in #3675
• Use parsed filename for unmatched ROM titles instead of raw filename by @gantoine in #3681
• docs(claude): add PR linking and template conventions by @gantoine in #3682
• Support markdown manuals and enforce allowed file types by @gantoine in #3683
• fix(v2): surface an error when clipboard copy fails over HTTP by @gantoine in #3684
• fix(v2): wrap 3D box side scan onto all four edges by @gantoine in #3685
• fix(scan): fall back to other providers when ScreenScraper quota is exhausted by @gantoine in #3686
• fix(launchbox): import local media when matching via update_rom by @gantoine in #3687
• i18n: rename "Duplicates" filter to "Versions" in the UI by @gantoine in #3688
• feat: default UI language to browser language when available by @gantoine in #3690
• test(v2): add axe accessibility gate + keyboard nav tests to Storybook by @gantoine in #3691
• Readme badges by @gantoine in #3692
• fix(platforms): stop platform variants from renaming the parent platform by @gantoine in #3693
• fix(v2): gallery focus-ring and tab-order polish by @gantoine in #3696
• fix: generate virtual collections from all metadata sources by @gantoine in #3694
• feat(patcher): always show patcher tab and allow uploading a patch by @gantoine in #3695
• fix(sockets): require TASKS_RUN scope for scan and scan:stop by @gantoine in #3698
• docs(sync): clarify slot pairing behavior in negotiate OpenAPI spec by @gantoine in #3699
• feat(playmatch): move integration to API v2 by @DevYukine in #3689
• feat(player): remember emulator core per-game by @gantoine in #3701
• perf(v2): use static background SVG in Firefox to stop GPU repaint by @gantoine in #3702
• fix(roms): enforce parent ROM visibility on direct file endpoints by @gantoine in #3703
• feat(roms): serve and display media files inline in details tab by @gantoine in #3700

Full Changelog: 5.0.0-beta.1...5.0.0-beta.2

5.0.0-beta.1

Warning

This is the first beta of v5.0.0. It ships a brand-new frontend that lives alongside the current one. Expect rough edges, and please report anything you find. The new UI is still on beta: enable it from your user settings (UI version). The classic UI remains the default and is untouched.

Note

Environment Variables

OIDC_ALLOW_REGISTRATION: Gate automatic user registration on OIDC login (default false)
DISABLE_LOGS_VIEWER: Disable the logs viewer for every user, including admins (default false)

Highlights

A brand-new frontend

v5 kicks off the biggest visual overhaul in RomM's history: a ground-up frontend with a new design system, a fresh visual language, and a universal input model that feels at home with mouse, touch, keyboard and gamepad alike. This first beta is your early look, opt in and let us know what you think. #3436

Note

Controller support

This new frontend has been designed to make it controller friendly from the beginning. Some controls and navigation has been already implemented but it's half baked, not every piece of the UI is wired to the controller yet.

Live playing sessions

See what's being played, as it happens. Active game sessions are now tracked in real time, so you always know what's running across your library. #3272

Live logs

Tail your server logs straight from the UI, streamed live, now with semantic module names and a module filter to cut through the noise. Debugging a scan or a player issue no longer means digging through the container. #3557 #3578

Shared savestates

Pick up where someone else left off. Saves and savestates can now be shared with other users, so progress travels with the game instead of being locked to a single device. #3569

Shared screenshots

Captured a great moment? Screenshots are now first-class shared assets, complete with the uploader's avatar, making it easy to show off (or get help with) what's happening on screen. #3549

Interactive 3D boxart

Covers get a new dimension. Boxart can now be rendered as an interactive 3D box on the game detail hero, bringing a bit of shelf-appeal back to your digital collection. Can be enabled selecting 3D box boxart in the UI settings. #3580

Overlay debug mode

A new debug overlay draws live diagnostics right on top of the UI, perfect for tracking down layout and rendering issues without leaving the app. It can be enabled from the UI settings #3554

Controller debug view

Wondering if your gamepad is mapped correctly? The new controller debug view shows inputs as you press them, making setup and troubleshooting a breeze. #3436

Changelog preview

What's new is now front and center. A built-in changelog dialog, reachable from the user menu, surfaces release highlights directly in the app so you never miss what changed. #3436

QR auth for TV-like devices

Signing in on a TV or other input-limited device just got painless. RomM now implements the OAuth device authorization flow (RFC 8628): scan a QR code with your phone to pair and authenticate, no on-screen keyboard wrestling required. #3308

Note

API Changes

5.0.0 is a major release with several breaking changes (⚠️) and large new subsystems: a fine-grained permissions engine, an OAuth device-authorization flow, a music library, an activity feed, a logs viewer, and first-class ROM soundtracks / screenshots / manuals / patching.

New endpoints

Device authorization (OAuth device flow) - new device_auth.py

• POST /api/auth/device/init (public): start a device-auth request; returns device_code, user_code, polling interval.
• POST /api/auth/device/token (public): poll/exchange a device_code for an access token.
• GET /api/auth/device/pending/{user_code}: details of a pending request for approval.
• POST /api/auth/device/approve: approve with approved_scopes.
• POST /api/auth/device/deny: deny a pending request.

Permissions engine - new permissions.py

• GET /api/permissions/catalog: available entities + actions.
• GET /api/permissions/me: current user's effective grants + hidden entities.
• GET /api/permissions/groups: list permission groups.
• POST /api/permissions/groups: create a permission group.
• PUT /api/permissions/groups/{id}: update a permission group.
• DELETE /api/permissions/groups/{id}: delete a permission group.
• GET /api/permissions/users/{user_id}: get a user's group + overrides + hidden entities.
• PUT /api/permissions/users/{user_id}: update a user's permission group and overrides.
• POST /api/permissions/hidden: hide an entity for a user or group.
• DELETE /api/permissions/hidden: un-hide an entity.

Music library - new music.py

• GET /api/music/tracks: paginated music-track listing (with facet filters).
• GET /api/music/albums
• GET /api/music/artists
• GET /api/music/genres
• GET /api/music/years

Activity feed - new activity.py

• GET /api/activity: global activity feed.
• GET /api/activity/rom/{rom_id}: activity for a single ROM.
• POST /api/activity/heartbeat: report an active play-session heartbeat.
• DELETE /api/activity/heartbeat: end a play session / clear heartbeat.

Logs viewer - new logs.py

• GET /api/logs: fetch application log entries (gated by the new DISABLE_LOGS_VIEWER config flag).

ROM soundtracks - new roms/soundtrack.py

• GET /api/roms/{id}/soundtracks/metadata: track metadata for a ROM's soundtrack files.
• POST /api/roms/{id}/soundtracks: upload soundtrack file(s).
• DELETE /api/roms/{id}/soundtracks/{file_id}: delete a soundtrack file.

ROM screenshots - new roms/screenshot.py

• POST /api/roms/{id}/screenshots: upload screenshot(s).
• DELETE /api/roms/{id}/screenshots/{file_id}: delete a screenshot file.

ROM manuals - new roms/manual.py

• POST /api/roms/{id}/manuals/files: upload manual file(s).
• DELETE /api/roms/{id}/manuals/files/{file_id}: delete a manual file.
• POST /api/roms/{id}/manuals/redownload: re-fetch the manual from the metadata source.

ROM patching - new roms/patch.py

• POST /api/roms/{id}/patch: apply a patch file (PatchRequest) to produce a patched ROM.

Other ROM endpoints

• GET /api/roms/{id}/simple: lightweight SimpleRomSchema fetch for a single ROM.
• POST /api/roms/{id}/convert-to-folder: convert a single-file ROM into a multi-file (folder) ROM.

Asset visibility & content serving

• PUT /api/saves/{id}/visibility: set a save public/private ({ is_public }).
• PUT /api/states/{id}/visibility: set a state public/private ({ is_public }).
• GET /api/states/{id}/content: download a state's binary content.
• PUT /api/screenshots/{id}: update a screenshot (visibility).
• DELETE /api/screenshots/{id}: delete a screenshot.
• GET /api/screenshots/{id}/content: download a screenshot's binary content.
• GET /api/users/{id}/avatar: serve a user's avatar image.

Changed endpoints

ROM schemas (affect GET /api/roms, GET /api/roms/{id}, and related listings)

• SimpleRomSchema and DetailedRomSchema: added name_sort_key, has_manual_files, has_soundtrack.
  • SimpleRomSchema also added screenshot_path.
  • DetailedRomSchema also added all_user_saves, all_user_states, all_user_screenshots.
• SiblingRomSchema: added is_main_sibling.
• RomFileSchema: added is_top_level and track_meta (music metadata).
• RomFiltersDict: added tags.
• ⚠️ RomFileCategory enum: added soundtrack and screenshot.
• PUT /api/roms/{id} (Body_update_rom): added name_sort_key.
• RomGamelistMetadata: added sort_name.

Platforms

• ⚠️ PlatformSchema: removed aspect_ratio.
• ⚠️ PUT /api/platforms/{id} (Body_update_platform): removed aspect_ratio.

Saves / States / Screenshots

• SaveSchema and `StateSc...

5.0.0-alpha.2

What's Changed

• Exclude served resources from Vite dev watcher by @gantoine in #3586
• Add test data generator script by @gantoine in #3585
• Permission fix for exported game lists and Pegasus platform slugs mapping by @ametis70 in #3587
• Test Build GitHub Action improvements by @ametis70 in #3588
• Add server-side ROM patching endpoint by @gantoine in #3225
• fix(deps): bump dependencies to patch reported vulnerabilities by @gantoine in #3592
• Turkish language support tr_TR by @y1lm-z in #3593
• perf(roms): speed up the gallery/search list endpoint on large libraries by @gantoine in #3595
• fix: Light theme by @zurdi15 in #3596
• fix(platform): accept embedded custom_name body on platform update by @gantoine in #3597
• fix(webp): backfill cover conversion on startup when enabled by @gantoine in #3602
• fix(frontend): contain hover-video to miximage frame + restore dev HMR by @gantoine in #3603
• fix(scan): prevent duplicate ROM entries from racing scans by @gantoine in #3606
• fix(scan): make scan tracker totals reflect platforms actually scanned by @gantoine in #3607
• fix(v2): correct route name when navigating after platform/collection delete by @gantoine in #3608
• fix(v2): stop gamepad B/cancel from backing out of controller test and games by @gantoine in #3604
• Stop spamming PRs with coverage reports by @gantoine in #3625
• Fix state/save injection timing and corruption in EmulatorJS by @gantoine in #3624
• fix(ra): hash PSP compressed-ISO containers natively (#3600) by @gantoine in #3609
• Normalize Sony serial codes to uppercase before cache lookup by @gantoine in #3622
• Fix ROM name handling in UNMATCHED scans to replace placeholders by @gantoine in #3623
• feat(roms): filter games by matched metadata provider by @Spinnich in #3615
• build(deps): bump python-engineio from 4.12.2 to 4.13.2 by @dependabot[bot] in #3626
• feat: granular permission system (groups, overrides, per-entity hiding) by @zurdi15 in #3605
• build(deps): bump joserfc from 1.6.3 to 1.6.7 by @dependabot[bot] in #3627
• build(deps): bump python-socketio from 5.14.0 to 5.16.2 by @dependabot[bot] in #3628
• feat(roms): filter games by custom tags by @Spinnich in #3629
• fix(backend): load platform_id on siblings to avoid DetachedInstanceError by @gantoine in #3635
• Add ROM revision field to game details overview by @gantoine in #3631
• Fix ROM upload temp directory to use RESOURCES_BASE_PATH by @gantoine in #3632
• Add Artwork subtab to Media tab with scraped art gallery by @gantoine in #3634

New Contributors

• @ametis70 made their first contribution in #3587
• @y1lm-z made their first contribution in #3593

Full Changelog: 5.0.0-alpha.1...5.0.0-alpha.2

5.0.0-alpha.1

Warning

This is the first alpha of v5.0.0. It ships a brand-new frontend that lives alongside the current one. Expect rough edges, and please report anything you find. The new UI is still on beta: enable it from your user settings (UI version). The classic UI remains the default and is untouched.

Note

Environment Variables

OIDC_ALLOW_REGISTRATION: Gate automatic user registration on OIDC login (default false)
DISABLE_LOGS_VIEWER: Disable the logs viewer for every user, including admins (default false)

Highlights

A brand-new frontend

v5 kicks off the biggest visual overhaul in RomM's history: a ground-up frontend with a new design system, a fresh visual language, and a universal input model that feels at home with mouse, touch, keyboard and gamepad alike. This first alpha is your early look, opt in and let us know what you think.
The mobile version of the new frontend it's currently being worked on, so expect it to not be really smooth. #3436

Note

Controller support

This new frontend has been designed to make it controller friendly from the beginning. Some controls and navigation has been already implemented but it's half baked, not every piece of the UI is wired to the controller yet.

Live playing sessions

See what's being played, as it happens. Active game sessions are now tracked in real time, so you always know what's running across your library. #3272

Live logs

Tail your server logs straight from the UI, streamed live, now with semantic module names and a module filter to cut through the noise. Debugging a scan or a player issue no longer means digging through the container. #3557 #3578

Shared savestates

Pick up where someone else left off. Saves and savestates can now be shared with other users, so progress travels with the game instead of being locked to a single device. #3569

Shared screenshots

Captured a great moment? Screenshots are now first-class shared assets, complete with the uploader's avatar, making it easy to show off (or get help with) what's happening on screen. #3549

Interactive 3D boxart

Covers get a new dimension. Boxart can now be rendered as an interactive 3D box on the game detail hero, bringing a bit of shelf-appeal back to your digital collection. Can be enabled selecting 3D box boxart in the UI settings. #3580

Overlay debug mode

A new debug overlay draws live diagnostics right on top of the UI, perfect for tracking down layout and rendering issues without leaving the app. It can be enabled from the UI settings #3554

Controller debug view

Wondering if your gamepad is mapped correctly? The new controller debug view shows inputs as you press them, making setup and troubleshooting a breeze. #3436

Changelog preview

What's new is now front and center. A built-in changelog dialog, reachable from the user menu, surfaces release highlights directly in the app so you never miss what changed. #3436

QR auth for TV-like devices

Signing in on a TV or other input-limited device just got painless. RomM now implements the OAuth device authorization flow (RFC 8628): scan a QR code with your phone to pair and authenticate, no on-screen keyboard wrestling required. #3308

Minor changes

• Faster search with full-text indexes and caching by @bonofiglio in #3540
• Add ES-DE <sortname> import and edit support for ROM ordering by @gantoine with @Copilot in #3460
• Backend connection status notice + offline-aware boot by @zurdi15 in #3550
• Add user avatar to shared assets like notes and screenshots by @zurdi15 in #3551
• CRT mode as a theme setting by @zurdi15 in #3552
• Add dropzone to saves/states by @zurdi15 in #3556
• Unify upload UX across Game Details subtabs by @zurdi15 in #3570
• Restore "remove from continue playing" action by @zurdi15 in #3572
• Render cover art at its natural aspect ratio by @gantoine in #3573
• Improve gallery responsiveness by @zurdi15 in #3576
• Add tile animations to the gallery by @zurdi15 in #3578
• Various v2 UI tweaks by @gantoine in #3579
• Add OIDC_ALLOW_REGISTRATION toggle to gate OIDC auto-registration by @Spinnich in #3577

Fixes

• Fix gallery animation by @zurdi15 in #3553
• Refresh platforms on scan by @zurdi15 in #3555
• Handle missing ROM files during delete-from-filesystem requests by @zurdi15 with @Copilot in #3562
• Guard SiblingBadge against missing sibling_roms (scan crash with Group ROMs) by @androosio in #3568

Other changes

• Integrate Hypothesis property-based testing for the backend by @gantoine in #3403
• Run backend tests in parallel with pytest-xdist by @gantoine in #3559
• Split v2 constitution into focused agent skills and make CLAUDE.md holistic by @gantoine in #3581

New Contributors

• @bonofiglio made their first contribution in #3540
• @androosio made their first contribution in #3568

Full Changelog: 4.9.2...5.0.0-alpha.1

4.9.2

What's Changed

• fix: Crash on startup when no library by @zurdi15 in #3544
• build(deps-dev): bump js-yaml from 4.1.1 to 4.2.0 in /frontend by @dependabot[bot] in #3525
• build(deps): bump tornado from 6.5.6 to 6.5.7 by @dependabot[bot] in #3528
• build(deps): bump python-multipart from 0.0.22 to 0.0.31 by @dependabot[bot] in #3527
• build(deps): bump aiohttp from 3.13.4 to 3.14.1 by @dependabot[bot] in #3530
• build(deps): bump markdown-it from 14.1.1 to 14.2.0 in /frontend by @dependabot[bot] in #3533
• build(deps): bump ws and engine.io-client in /frontend by @dependabot[bot] in #3532

Full Changelog: 4.9.1...4.9.2

4.9.1

What's Changed

• fix: Structure A always takes priority over Structure B in library detection by @gantoine in #3508
• build(deps): bump tornado from 6.5.5 to 6.5.6 by @dependabot[bot] in #3513
• build(deps): bump esbuild, vite, @tailwindcss/vite, @vitejs/plugin-vue, vite-plugin-pwa and vite-plugin-static-copy in /frontend by @dependabot[bot] in #3514
• Fix config.yml serialization breaking folder-to-platform mappings by @gantoine in #3516
• Override rolldown version by @gantoine in #3524
• Fix bypass_autologin overwritten by 403 interceptor during app initialization by @gantoine in #3523

Full Changelog: 4.9.0...4.9.1