pulse-signage/docs/websocket.md

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.