feat: Emulator streaming

[LoneAngelFayt]

Description

This PR adds a streaming framework to RomM that enables launching games directly from the RomM UI into a native emulator running in a separate container, with full session management, save state control, and volume control, all without leaving the browser.

The emulator runs in a linuxserver Docker container with a Selkies WebRTC stream. A small HTTP broker sidecar inside that container handles game launch, extraction, and I/O. RomM communicates with the broker via a new /api/streaming backend endpoint and displays the stream in an embedded player.

This initial PR covers four emulators. Additional integrations (PS3/rpcs3, etc.) will follow in separate PRs once the framework is established.

Supported emulators

Platform slug	Emulator	Save states	Slots	Autosave slot	Archive extraction
ps2	PCSX2	✅	9	Slot 10	❌ direct file only
ngc, wii, wiiu	Dolphin	✅	7	Slot 8	❌ direct file only
xbox	xemu	✅	9	Slot 10	❌ direct file only
switch	Eden	❌	-	-	❌ direct file only

Architecture

RomM frontend
  └── StreamingStore (Pinia)
        ├── fetchConfig()       - loads container list from backend on app start
        ├── claimSession()      - POST /api/streaming/sessions
        ├── saveState/loadState - proxied to broker via backend
        ├── saveAndExit()       - save + release session
        └── setVolume/setMute   - PulseAudio control via broker

RomM backend  (/api/streaming/*)
  ├── GET  /config              - returns enabled flag + container list
  ├── POST /sessions            - claims a session, proxies launch to broker
  ├── POST /sessions/{platform}/save-state
  ├── POST /sessions/{platform}/load-state
  ├── POST /sessions/{platform}/save-and-exit
  ├── POST /sessions/{platform}/volume
  ├── POST /sessions/{platform}/mute
  └── DELETE /sessions/{platform} - releases session

Emulator container (linuxserver + broker sidecar)
  ├── POST /launch              - kill current game, launch the requested ROM
  ├── GET  /status              - current session state
  ├── POST /save-state          - hotkey inject, poll for write confirmation
  ├── POST /load-state          - hotkey inject (fire-and-forget)
  ├── POST /save-and-exit
  ├── POST /volume              - pactl set-sink-volume
  └── POST /mute

Configuration (config.yml)

streaming:
  enabled: true
  containers:
    - platform: ps2
      host: https://192.168.1.51:3001       # Selkies WebRTC UI (browser-facing, must be HTTPS)
      broker_host: http://192.168.1.51:8000 # Broker API (server-to-container, HTTP ok)
      label: PCSX2
    - platform: ngc
      host: https://192.168.1.51:3002
      broker_host: http://192.168.1.51:8001
      label: Dolphin

Each emulator is its own container entry. Multiple platforms can share a container (e.g. ngc/wii/wiiu all pointing at the same Dolphin instance) or use separate ones. The host is the URL the browser loads the stream from; broker_host is the server-side URL RomM uses to send commands.

Two optional env vars: BROKER_SECRET authenticates broker API calls (set on both the RomM container and the emulator container), and STREAMING_SAVE_TIMEOUT raises the save-and-exit wait for brokers that save slowly (default 45s).

Changes

Backend

• backend/endpoints/streaming.py - new router: session management, broker proxy, config endpoint. Sessions are claimed by ROM id (the filesystem path is derived server-side from the database, never taken from the client), stored in Redis via atomic SET NX (multi-worker safe), and bound to the claiming user; only the owner or an admin can control or release one.
• backend/tests/endpoints/test_streaming.py - 19 endpoint tests: auth scopes, claim races, ownership, broker failure paths, force-release.
• backend/config/config_manager.py - STREAMING_ENABLED + STREAMING_CONTAINERS config fields
• backend/main.py - registers streaming router

Frontend

• frontend/src/stores/streaming.ts - Pinia store: config, session lifecycle, per-platform capabilities
• frontend/src/views/Player/Stream/Player.vue - streaming player view: Selkies iframe, loading overlay, save state controls, volume/mute
• frontend/src/components/common/Game/PlayBtn.vue - "Play on [label]" button appears when a streaming container is configured for the platform
• frontend/src/layouts/Main.vue - streaming config fetched on app start
• frontend/src/plugins/router.ts - rom/:rom/stream route

Config

• examples/config.example.yml - streaming config example with comments
• env.template - BROKER_SECRET and STREAMING_SAVE_TIMEOUT variables

The player view follows the existing v1 player pattern (same shape as the EmulatorJS/Ruffle views). The route also registers a v2 named view via v2For, so v2 users get the standard "not ready yet" fallback; a native v2 player is planned as a follow-up once this framework lands.

Broker containers

Each emulator has a companion Docker mod repo with the broker sidecar (stdlib-only Python, no extra dependencies):

• PCSX2: https://github.com/LoneAngelFayt/pcsx2-romm-integration
• Dolphin: https://github.com/LoneAngelFayt/dolphin-romm-integration
• xemu: https://github.com/LoneAngelFayt/xemu-romm-integration
• Eden: https://github.com/LoneAngelFayt/eden-romm-integration

Each repo includes a docker-compose.yml showing the full setup.

UX flow

1. User clicks Play on PCSX2 (button appears only when a container is configured for that platform)
2. RomM claims a session; the broker kills any running game and launches the requested ROM
3. Loading overlay shows a spinner while the emulator starts
4. Once running: stream fills the player; save state controls and volume appear in the toolbar
5. Save & Exit saves state then returns to library; session is released for other users

AI assistance disclosure

This PR was developed with substantial AI assistance (Claude Code). I designed the architecture, made the design decisions, and tested everything against real emulator containers on my own hardware; the majority of the code was written by the AI under my direction and review, and the branch went through multiple AI-assisted review passes before submission.

Checklist
^{Please check all that apply.}

• I've tested the changes locally
• I've updated relevant comments
• I've assigned reviewers for this PR
• I've added unit tests that cover the changes

Screenshots (if applicable)

[LoneAngelFayt]

here is the broker that goes into the pcsx2 container if you want to take a look at the api inside

https://github.com/LoneAngelFayt/pcsx2-romm-integration

[LoneAngelFayt]

I've finished setting up the integration for dolphin as well, I'm going to split it out into a different PR for each integration

There is thankfully minimal changes but I turn some hardcoding into variables

Once you get done looking through this I'll adapt the others and put them in as I have them completed

[LoneAngelFayt]

@gantoine I changed my mind, and just added all the emulators I've gotten working along with their respective changes.

I recruited Claude to help make my PR description a little better as well. Should outline everything I've touched and how it all works.

[gantoine]

@LoneAngelFayt alright i'm happy with the state of this PR, want to give it a spin and see if everything still works?

[LoneAngelFayt]

Gladly!

[LoneAngelFayt]

@gantoine looks like its all working. One thing to note though. Since the v2 migration, it looks like controller inputs are being snagged by the UI as well as the stream. I fix this in a commit I have later, along with a lot of other cool features I've been working on.

Fix: re-add the setPlaying wiring in Stream.vue (set it while launching/playing, clear it on teardown):

import storePlaying from "@/stores/playing";
const playingStore = storePlaying();

const sessionActive = computed(
  () => playerState.value === "playing" || playerState.value === "loading",
);
watch(sessionActive, (active) => playingStore.setPlaying(active));
// and playingStore.setPlaying(false) in onBeforeUnmount

in case you wanted to just drop in the fix for this, or we can let it slide till the next PR i have around the corner

[gantoine]

@LoneAngelFayt two things:

• i think emulatorjs controls are also being swallowed by the ui navigation, can you try to fix both?
• i want to land this in 5.1 but we need to release a patch first, so you can either push to this branch or stack a PR

[LoneAngelFayt]

@gantoine i got you.

I can push everything to this branch.

I also cleaned up the way the stream page looks, as well as adding some save/state sync since that was opened up since this originally dropped. Need me to prune anything out or are you ok with a larger review all at once?

[LoneAngelFayt]

got them, it was the global hotkeys that were slipping through (G and H most likely culprits) found ruffle didn't even set playing tag at all so that was just waiting to fail sometime.

now they all set playing flag when a game starts and release it on exit, tested end to end.

Should be good to go.