Game Streaming API

List games, start game streams, and manage save states.

List games

GET /api/games
Authorization: Bearer <token>

Query parameters:

Parameter	Type	Description
platform	string	Filter by platform (e.g., snes, n64, psx)
search	string	Search by title
sort	string	Sort field: title, platform, addedAt
limit	number	Max results
offset	number	Pagination offset

Response:

{
  "items": [
    {
      "id": 1,
      "title": "Super Mario World",
      "platform": "snes",
      "filePath": "/data/games/snes/Super Mario World.sfc",
      "coverUrl": "/artwork/games/1/cover.jpg",
      "metadata": {
        "igdbId": 1070,
        "genres": ["Platform"],
        "releaseDate": "1990-11-21",
        "summary": "Super Mario World is a 2D platform game..."
      }
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Get game detail

GET /api/games/:id
Authorization: Bearer <token>

Returns full game detail with metadata, save states, and streaming status.

Start game stream

POST /api/games/:id/stream
Authorization: Bearer <token>
Content-Type: application/json

{
  "saveStateId": null
}

Starts the game on the server and returns the stream manifest URL.

Response:

{
  "streamId": "game-stream-abc123",
  "manifestUrl": "/api/games/1/stream/manifest.m3u8",
  "wsUrl": "/api/games/1/stream/input"
}

• manifestUrl — HLS manifest for video output
• wsUrl — WebSocket endpoint for input relay

Pass saveStateId to resume from a save state.

Game stream manifest

GET /api/games/:id/stream/manifest.m3u8
Authorization: Bearer <token>

HLS manifest for the game video stream. Connect to this with an HLS player (hls.js in the browser).

Save states

Save state

POST /api/games/:id/save-state
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Before boss fight"
}

Response:

{
  "id": 1,
  "gameId": 1,
  "name": "Before boss fight",
  "createdAt": "2024-01-01T12:00:00Z",
  "thumbnailUrl": "/api/games/1/save-states/1/thumbnail.jpg"
}

List save states

GET /api/games/:id/save-states
Authorization: Bearer <token>

Response:

[
  {
    "id": 1,
    "gameId": 1,
    "name": "Before boss fight",
    "createdAt": "2024-01-01T12:00:00Z",
    "thumbnailUrl": "/api/games/1/save-states/1/thumbnail.jpg"
  }
]

WebSocket: game input relay

Connect to the WebSocket endpoint returned by POST /api/games/:id/stream to send controller input.

Message format (client to server):

{
  "type": "input",
  "buttons": {
    "a": true,
    "b": false,
    "start": false,
    "select": false,
    "up": false,
    "down": false,
    "left": true,
    "right": false,
    "l": false,
    "r": false
  },
  "axes": {
    "leftX": 0.0,
    "leftY": 0.0,
    "rightX": 0.0,
    "rightY": 0.0
  },
  "timestamp": 1704067200000
}

Input messages are sent at 60 Hz for responsive gameplay.