132 lines
2.2 KiB
Markdown
132 lines
2.2 KiB
Markdown
# 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.
|