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.