# 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.