176 lines
2.8 KiB
Markdown
176 lines
2.8 KiB
Markdown
# 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.
|