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,131 @@
+# Player API Reference
+
+## Overview
+
+Player service base URL: `http://localhost:3001`
+
+This document uses OpenAPI-style sections, but stays in plain markdown.
+
+## Endpoints
+
+### `GET /`
+Returns a plain-text landing response for the player service.
+
+### `GET /screen/{slug}`
+Returns the rendered player page for a screen.
+
+### `GET /api/screens/{slug}/playlist`
+Returns the current playlist payload for a screen.
+
+### `GET /api/screens/{slug}/connections`
+### `GET /api/screens/{slug}/clients`
+Returns the live player connection snapshot for a screen.
+
+### `POST /api/screens/{slug}/commands`
+Sends a command to the player connections for a screen.
+
+Accepted request fields:
+
+- `command` required
+- `connectionId` optional
+- `clientId` optional
+- `blackout` optional when `command=blackout`
+
+Supported commands:
+
+- `refresh`
+- `reload`
+- `pause`
+- `blackout`
+- `previous`
+- `next`
+- `left`
+- `right`
+
+If `connectionId` or `clientId` is provided, the command targets a single player connection. Otherwise it is broadcast to all connections for that screen.
+
+## Response Shapes
+
+### Playlist Response
+
+`GET /api/screens/{slug}/playlist` returns an object with:
+
+- `screen`
+- `playlist`
+- `slides`
+
+### Connections Response
+
+`GET /api/screens/{slug}/connections` and `GET /api/screens/{slug}/clients` return an object with:
+
+- `screen`
+- `screenSlug`
+- `count`
+- `connections`
+
+### Command Response
+
+`POST /api/screens/{slug}/commands` returns an object with:
+
+- `screen`
+- `screenSlug`
+- `command`
+- `connectionId`
+- `sent`
+
+## Data Models
+
+### Screen
+
+- `id`
+- `name`
+- `slug`
+- `playlist_id`
+- `created_at`
+- `modified_at`
+
+### Playlist
+
+- `id`
+- `name`
+- `fade_between_slides`
+
+### Slide
+
+- `id`
+- `title`
+- `body`
+- `duration_seconds`
+- `schedule_mode`
+- `schedule_start_datetime`
+- `schedule_end_datetime`
+- `schedule_start_time`
+- `schedule_end_time`
+- `schedule_days_json`
+- `media_url`
+- `media_type`
+- `kind`
+- `template_id`
+- `template`
+- `content`
+
+### Connection
+
+- `id`
+- `clientId`
+- `label`
+- `userAgent`
+- `viewport`
+- `page`
+- `currentSlide`
+- `paused`
+- `blackout`
+- `clientIp`
+- `remoteAddress`
+- `connectedAt`
+- `lastSeenAt`
+
+## Notes
+
+- The player API is the only surface documented here.
+- Web UI/admin routes are intentionally omitted.
@@ -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.