diff --git a/docs/Navigation.md b/docs/Navigation.md index 4fca528..53d9b25 100644 --- a/docs/Navigation.md +++ b/docs/Navigation.md @@ -51,6 +51,7 @@ search: - [EmulatorJS](using/in-browser-play/emulatorjs.md) - [MS-DOS](using/in-browser-play/ms-dos.md) - [Ruffle](using/in-browser-play/ruffle.md) + - [Emulator Streaming](using/emulator-streaming.md) - [Saves & States](using/saves-and-states.md) - [RetroAchievements](using/retroachievements.md) - [ROM Patcher](using/rom-patcher.md) diff --git a/docs/reference/configuration-file.md b/docs/reference/configuration-file.md index 90ee538..6225190 100644 --- a/docs/reference/configuration-file.md +++ b/docs/reference/configuration-file.md @@ -434,7 +434,49 @@ Most settings under `emulatorjs.settings` and `emulatorjs.controls` can be overr --- +## `streaming` + +Configure [emulator streaming](../using/emulator-streaming.md), which lets you launch games in native emulator containers and stream them to the browser. The end-user side and full setup walkthrough live in [Using RomM → Emulator Streaming](../using/emulator-streaming.md). + +### `streaming.enabled` + +**Default:** `false` + +```yaml +streaming: + enabled: true +``` + +### `streaming.containers` + +One entry per emulator container, where each entry maps a [platform slug](../platforms/supported-platforms.md) to the container that streams it. + +| Key | Required | Purpose | +| --------------- | -------- | --------------------------------------------------------------------------------------------------------- | +| `platform` | Yes | Platform slug this container serves (e.g. `ps2`, `ngc`, `xbox`, `switch`) | +| `host` | Yes | Browser-facing Selkies web UI (must be reachable from clients and served over **HTTPS**) | +| `broker_host` | No | Server-side broker API (derived from `host` if omitted) | +| `label` | Yes | Text shown on the play action (e.g. `PCSX2`) | +| `broker_secret` | No | Per-container override for the `STREAMING_BROKER_SECRET` env var, for brokers that use a different secret | + +```yaml +streaming: + enabled: true + containers: + - platform: ps2 + host: https://192.168.1.51:3001 # browser-facing, must be HTTPS + broker_host: http://192.168.1.51:8000 # server-to-container, HTTP ok + label: PCSX2 + - platform: ngc # ngc/wii/wiiu can share one Dolphin container + host: https://192.168.1.51:3002 + broker_host: http://192.168.1.51:8001 + label: Dolphin +``` + +--- + ## Related - [Folder Structure](../getting-started/folder-structure.md): how the filesystem shape interacts with `config.yml` - [Metadata Providers](../getting-started/metadata-providers.md): per-provider detail for the `scan.priority.*` slugs +- [Emulator Streaming](../using/emulator-streaming.md): the full setup guide for the `streaming` block diff --git a/docs/using/emulator-streaming.md b/docs/using/emulator-streaming.md new file mode 100644 index 0000000..0eb2e62 --- /dev/null +++ b/docs/using/emulator-streaming.md @@ -0,0 +1,64 @@ +--- +title: Emulator Streaming +description: Launch games into a native emulator running in a container +--- + +# Emulator Streaming + +Emulator streaming launches a game into a **native** emulator running in a separate container and streams the picture, sound, and input back to your browser. Unlike [in-browser play](in-browser-play/emulatorjs.md), the emulation runs server-side on real emulator binaries (PCSX2, Dolphin, xemu, Eden), so the heavy lifting happens on the host rather than in the client. The server claims a session, tells the emulator which ROM to launch, and shows the live stream inside a player view, with save-state and volume controls in the toolbar. + +Each emulator runs in its own [linuxserver](https://docs.linuxserver.io) container with a [Selkies](https://github.com/selkies-project/selkies) WebRTC stream and a small HTTP broker sidecar that RomM talks to. Nothing appears in the UI until you configure at least one container. + + +!!! warning "Work in progress" + This is the first release of the streaming framework and ships with four emulators. More integrations (rpcs3 for PS3, and others) are planned as separate follow-ups. + +## Supported emulators + +Each emulator ships as a companion Docker mod repo with the broker sidecar and a worked `docker-compose.yml`. + +| Platform slug | Emulator | Save states | Manual slots | Autosave slot | Broker repo | +| -------------------- | -------- | ----------- | ------------ | ------------- | ------------------------------------------------------------------------------------- | +| `ps2` | PCSX2 | Yes | 9 | Slot 10 | [pcsx2-romm-integration](https://github.com/LoneAngelFayt/pcsx2-romm-integration) | +| `ngc`, `wii`, `wiiu` | Dolphin | Yes | 7 | Slot 8 | [dolphin-romm-integration](https://github.com/LoneAngelFayt/dolphin-romm-integration) | +| `xbox` | xemu | Yes | 9 | Slot 10 | [xemu-romm-integration](https://github.com/LoneAngelFayt/xemu-romm-integration) | + +The broker launches ROMs as direct files, so **archive extraction is not supported**. + +Only **one session per platform** can be active at a time, since there is a single emulator container behind it. Sessions are stored in [Valkey](../install/redis-or-valkey.md) with an atomic claim, so multiple workers stay consistent. The session is bound to the user who claimed it, and only that owner or an admin can control or release it, though an admin can force-release a stuck session. + +## Save states + +The autosave slot is reserved for **Save & Exit**, so it can be overwritten on the next exit. Save files and states here live inside the emulator container and are **not** the same as RomM's [per-user saves and states](saves-and-states.md) from in-browser play. + +## Setup + +### Run the emulator containers + +Pick the broker repos for the platforms you want and follow each repo's `docker-compose.yml`. Each container exposes two things we need: + +- The **Selkies web UI** the browser loads the stream from (an HTTPS port). +- The **broker API** RomM sends launch, save, and volume commands to (default port `8000`). + +### Setup `config.yml` + +Add a `streaming` block with one entry per emulator container, full schema in [Configuration File → `streaming`](../reference/configuration-file.md#streaming). + +- `host` must be reachable from clients and served over **HTTPS** (Selkies WebRTC requires a secure context). Use the container's built-in self-signed cert or a [reverse proxy with TLS](../install/reverse-proxy.md). +- `broker_host` is called server-side, so HTTP is fine. If the containers share a Docker network, use the container name (e.g. `http://pcsx2:8000`). If `broker_host` is omitted, it gets derived from `host`. +- `label` is the text shown on the play action. + +Multiple platforms can share one container (point `ngc`, `wii`, and `wiiu` at the same Dolphin instance) or each use their own. + +### Set the shared secret + +`STREAMING_BROKER_SECRET` authenticates calls to the broker. Set the **same value** in every container. If a broker slot needs a different secret, a per-container `broker_secret` in `config.yml` overrides the env var for that entry. + +If a broker's save wait exceeds the default 45 seconds, raise `STREAMING_SAVE_TIMEOUT` (seconds) so Save & Exit doesn't time out. Both are set as env vars (see [Environment Variables](../reference/environment-variables.md)). + +## Troubleshooting + +- **No Play on `