Optimisations and updated readme

2026-07-14 12:50:52 +01:00
parent 9709457b73
commit ff23474a54
33 changed files with 3073 additions and 2426 deletions
@@ -0,0 +1,175 @@
+# Player WebSocket Reference
+
+## Overview
+
+Player service websocket base URL: `ws://localhost:3001`
+
+This document uses OpenAPI-style sections, but stays in plain markdown.
+
+## Channels
+
+### `GET /ws/screens/{slug}`
+Player control channel.
+
+This is the bidirectional socket used by the player page. The player sends status messages to the server, and the server sends commands back to the player.
+
+### `GET /ws/screens/{slug}/events`
+Player snapshot channel.
+
+This is the server-to-dashboard snapshot stream for live player connection state.
+
+## Player Control Channel
+
+### Messages from player to server
+
+The player sends two message types:
+
+- `hello`
+- `state`
+
+#### `hello`
+
+Example payload:
+
+```json
+{
+  "type": "hello",
+  "clientId": "client-id",
+  "userAgent": "browser ua",
+  "page": "http://.../screen/demo",
+  "viewport": { "width": 1920, "height": 1080 },
+  "paused": false,
+  "blackout": false,
+  "currentSlide": null
+}
+```
+
+#### `state`
+
+Example payload:
+
+```json
+{
+  "type": "state",
+  "clientId": "client-id",
+  "userAgent": "browser ua",
+  "page": "http://.../screen/demo",
+  "viewport": { "width": 1920, "height": 1080 },
+  "paused": false,
+  "blackout": false,
+  "currentSlide": {
+    "id": 12,
+    "title": "Main Slide",
+    "kind": "image",
+    "playlistSignature": "..."
+  }
+}
+```
+
+### Messages from server to player
+
+The server sends command messages with:
+
+- `type: "command"`
+- `command`
+- optional `sentAt`
+- optional `targetConnectionId`
+- optional `blackout` for blackout commands
+
+Supported commands:
+
+- `refresh`
+- `reload`
+- `pause`
+- `blackout`
+- `previous`
+- `next`
+- `left`
+- `right`
+
+#### `refresh`
+Asks the player to refetch the current playlist.
+
+#### `reload`
+Forces a browser page reload.
+
+#### `pause`
+Toggles paused state on the player.
+
+#### `blackout`
+Sets blackout state explicitly.
+
+Example payload:
+
+```json
+{
+  "type": "command",
+  "command": "blackout",
+  "blackout": false
+}
+```
+
+Use `false` to restore and `true` to blackout.
+
+#### `previous` / `left`
+Moves to the previous slide.
+
+#### `next` / `right`
+Moves to the next slide.
+
+## Snapshot Channel
+
+### Messages from server to client
+
+The server sends snapshot payloads on `/ws/screens/{slug}/events`.
+
+Example payload:
+
+```json
+{
+  "type": "snapshot",
+  "slug": "demo",
+  "connections": [],
+  "sentAt": "2026-07-14T12:00:00.000Z"
+}
+```
+
+The snapshot channel is server-to-client only.
+
+## Data Models
+
+### Connection Snapshot
+
+- `id`
+- `clientId`
+- `label`
+- `userAgent`
+- `viewport`
+- `page`
+- `currentSlide`
+- `paused`
+- `blackout`
+- `clientIp`
+- `remoteAddress`
+- `connectedAt`
+- `lastSeenAt`
+
+### Command Message
+
+- `type`
+- `command`
+- `sentAt`
+- `targetConnectionId`
+- `blackout`
+
+### Snapshot Message
+
+- `type`
+- `slug`
+- `connections`
+- `sentAt`
+
+## Notes
+
+- This document covers only the player websocket channels.
+- Web UI/admin websocket behavior is intentionally omitted.