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.

[thelamer]

A team member linked me to this PR, cool stuff.

If you need anything upstream we can add things like env vars to pass in rom paths to pass to the emulator that is completely possible just let me know the spec. I do something similar with sealskin e.g. https://github.com/linuxserver/sealskin-apps/blob/master/autostart/eden-wayland. Just need new env vars in the autostart files to ingest paths to stuff to launch and possible raw CLI for specific launch options.

Just a heads up the RPCS3 image needs some attention I will try to prioritize it as it is pinned back now, last time it was at head a bunch of stuff was busted because it expected more host level access and docker was not cutting it. I do not have much more of a summary than that at this time. (the gamepad interposer was a major blocker, but lots of /sys probing stuff)

Also wanted to mention https://github.com/linuxserver/docker-shadps4, it runs a lot of stuff surprisingly well I even got a bunch of indies running on my little intel n97 box.

Another mention is https://github.com/linuxserver/docker-webstation, I personally use this with ESDE fully setup on it, but it might be easier to focus on one container that has every single emu in it like this does and this has the flexibility to add odd ones if needed.
Yet another 2 mentions https://github.com/linuxserver/docker-flycast and https://github.com/linuxserver/docker-ppsspp.

The gpu setup on wayland/nvidia can get hairy let me know if you need any help with that. with 595+ drivers dummy plugs and kernel params are not needed anymore I can get it running with just :

docker run --rm -it --shm-size=1gb --runtime nvidia --gpus all --device /dev/nvidia-modeset -p 3001:3001 linuxserver/eden bash

On some hosts need to run nvidia-modprobe --modeset on the host to activate that device though I no longer need to.

Another thing that comes to mind is more automated emulator setup pointing at files (bios, dash, firmware)

Sorry for the rant, but I literally made all this stuff to play games with my friends after hitting a wall with emscripten on my old emulatorjs fork based around making a coinops web version https://github.com/linuxserver/emulatorjs. So this type of integration is one that is particularly of interest to me. Couch play is completely possible with controller passing and is why the sealskin collaboration feature exists in the first place. https://github.com/selkies-project/sealskin/blob/master/server/app/collaboration.py. This is all open feel free to rip anything you need for your solution no accreditation is needed.

If you have any questions feel free to reach out on our lsio discord I will setup a collab and show you what I am talking about.

[LoneAngelFayt]

A team member linked me to this PR, cool stuff.

If you need anything upstream we can add things like env vars to pass in rom paths to pass to the emulator that is completely possible just let me know the spec. I do something similar with sealskin e.g. https://github.com/linuxserver/sealskin-apps/blob/master/autostart/eden-wayland. Just need new env vars in the autostart files to ingest paths to stuff to launch and possible raw CLI for specific launch options.

Just a heads up the RPCS3 image needs some attention I will try to prioritize it as it is pinned back now, last time it was at head a bunch of stuff was busted because it expected more host level access and docker was not cutting it. I do not have much more of a summary than that at this time. (the gamepad interposer was a major blocker, but lots of /sys probing stuff)

Also wanted to mention https://github.com/linuxserver/docker-shadps4, it runs a lot of stuff surprisingly well I even got a bunch of indies running on my little intel n97 box.

Another mention is https://github.com/linuxserver/docker-webstation, I personally use this with ESDE fully setup on it, but it might be easier to focus on one container that has every single emu in it like this does and this has the flexibility to add odd ones if needed. Yet another 2 mentions https://github.com/linuxserver/docker-flycast and https://github.com/linuxserver/docker-ppsspp.

The gpu setup on wayland/nvidia can get hairy let me know if you need any help with that. with 595+ drivers dummy plugs and kernel params are not needed anymore I can get it running with just :

docker run --rm -it --shm-size=1gb --runtime nvidia --gpus all --device /dev/nvidia-modeset -p 3001:3001 linuxserver/eden bash

On some hosts need to run nvidia-modprobe --modeset on the host to activate that device though I no longer need to.

Another thing that comes to mind is more automated emulator setup pointing at files (bios, dash, firmware)

Sorry for the rant, but I literally made all this stuff to play games with my friends after hitting a wall with emscripten on my old emulatorjs fork based around making a coinops web version https://github.com/linuxserver/emulatorjs. So this type of integration is one that is particularly of interest to me. Couch play is completely possible with controller passing and is why the sealskin collaboration feature exists in the first place. https://github.com/selkies-project/sealskin/blob/master/server/app/collaboration.py. This is all open feel free to rip anything you need for your solution no accreditation is needed.

If you have any questions feel free to reach out on our lsio discord I will setup a collab and show you what I am talking about.

@thelamer This is great! I'll reach out!

[thelamer]

Just looking over the integration I think you might be able to save a lot of headache by having the broker be a single container with a docker socket mounted into it to launch containers and act as a proxy to them. That way you don't have to worry about container states and every container is ephemeral for a play session.

I refer back to https://github.com/selkies-project/sealskin/blob/master/server/app/collaboration.py and https://github.com/selkies-project/sealskin/blob/master/server/app/providers/docker_provider.py. Basically the idea would be rip out the core components of sealskin that are needed to make a broker. (caddy integration, container launching, and collaboration) like a mini sealskin that passes in env vars and mounts to individual containers on demand and can run multiple container sessions until the user "powers them off".

The broker could have its own web interface for configuring how containers are launched (gpu to use and defaults). Then I can modify the emulator images to accept a series of env vars to pass into the underlying app or to make it more universal in init have it detect a specific toml/yaml file and use that for launching the underlying emulator so you could have the flexibility of modifying it to your needs without needs for container changes.

Just spit balling here, more expand the broker to be its own universal thing instead of emulator specific and most of the hard work is already done what is left is boring data structure stuff.