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 StateSchema: added is_public.
• ScreenshotSchema: added is_gallery and is_public.

Users / auth / devices

• ⚠️ Role enum: viewer | editor | admin → user | admin (roles collapsed; permissions now handled by the new permissions engine).
• UserSchema: added permission_group_id.
• UserNoteSchema: added user_avatar_path, user_updated_at.
• DeviceSchema: added client_device_identifier.
• ClientTokenSchema / ClientTokenCreateSchema / ClientTokenAdminSchema: added device_id; ClientTokenAdminSchema also added user_avatar_path, user_updated_at.
• SyncNegotiatePayload: device_id is now optional (was required).

Config / metadata

• FrontendDict: added DISABLE_LOGS_VIEWER.
• MetadataMediaType enum: added box2d_side.

Removed endpoints

• ⚠️ GET /api/raw/assets/{path:path} - removed (the whole raw.py router is gone).
• ⚠️ HEAD /api/raw/assets/{path:path} - removed.
  • Generic raw-asset serving is replaced by dedicated content endpoints: GET /api/screenshots/{id}/content, GET /api/states/{id}/content, and GET /api/users/{id}/avatar.

What's Changed

• Frontend migration to the new visual language by @zurdi15 in #3436
• fix(search): full-text indexes+caching by @bonofiglio in #3540
• Add ES-DE <sortname> import and edit support for ROM ordering by @gantoine with @Copilot in #3460
• Integrate Hypothesis property-based testing for the backend by @gantoine in #3403
• feat: User screenshots support + dropzone refactor by @zurdi15 in #3549
• Fix/gallery animation by @zurdi15 in #3553
• feat: backend connection status notice + offline-aware boot by @zurdi15 in #3550
• feat: Add user avatar to shared assets like notes or screenshots by @zurdi15 in #3551
• feat: CRT mode as a theme setting by @zurdi15 in #3552
• fix: Refresh platforms on scan by @zurdi15 in #3555
• feat: Add dropzone to saves/states by @zurdi15 in #3556
• feat: Add debug overlay by @zurdi15 in #3554
• Run backend tests in parallel with pytest-xdist by @gantoine in #3559
• feat: real-time backend logs view by @zurdi15 in #3557
• Handle missing ROM files during delete-from-filesystem requests by @zurdi15 with @Copilot in #3562
• fix: guard SiblingBadge against missing sibling_roms (scan crash with Group ROMs) by @androosio in #3568
• Add real-time activity tracking for active game sessions by @gantoine in #3272
• feat: share saves & states with other users by @zurdi15 in #3569
• refactor: unify upload UX across GameDetails subtabs by @zurdi15 in #3570
• feat(v2): restore "remove from continue playing" action by @zurdi15 in #3572
• Add device authorization flow for TV-app-style pairing (RFC 8628) by @tmgast in #3308
• feat(v2): render cover art at its natural aspect ratio by @gantoine in #3573
• feat(v2): improve gallery responsiveness by @zurdi15 in #3576
• feat: tile animations, semantic log module names, and log module filter by @zurdi15 in #3578
• V2 UI tweaks gg by @gantoine in #3579
• feat(auth): add OIDC_ALLOW_REGISTRATION toggle to gate OIDC auto-registration by @Spinnich in #3577
• feat(v2): interactive 3D box art on the game detail hero by @gantoine in #3580
• docs: split v2 constitution into focused agent skills, make CLAUDE.md holistic by @gantoine in #3581
• 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
• fix(roms): namespace filter-values cache by schema version by @Spinnich in #3638
• Fix 3D box size calculation for landscape spine images by @gantoine in #3639
• Add filters for has save/state by @gantoine in #3642
• 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
• Fix v2 save-state screenshot rendering for filenames with special characters by @gantoine with @Copilot in #3660
• Refine filename version-tag parsing to avoid swallowing generic v* tags by @gantoine with @Copilot 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
• feat(v2): responsive/mobile pass over the v2 UI by @zurdi15 in #3664
• Add a music query API for soundtracks by @tmgast in #3640
• Posthog code/squash legacy migrations by @gantoine in #3670
• chore(deps): bump joserfc from 1.6.7 to 1.6.8 by @dependabot[bot] in #3672
• 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

New Contributors

• @bonofiglio made their first contribution in #3540
• @androosio made their first contribution in #3568
• @ametis70 made their first contribution in #3587
• @y1lm-z made their first contribution in #3593
• @sildur made their first contribution in #3656
• @mvanhorn made their first contribution in #3669
• @chiyi-creator made their first contribution in #3673

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