pulse-signage/docs/websocket.md

Player WebSocket Reference

Overview

Player service websocket base URL: ws://localhost:8081

This document uses OpenAPI-style sections, but stays in plain markdown.

The PULSE_SIGNAGE_SHARED_SECRET setting does not change the websocket message format here. It is used to sign the player control socket URL and the server-side snapshot subscription; the message payloads themselves remain the same.

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.

Access: the player page must include a valid auth query parameter signed with the shared secret. The browser page refreshes this token automatically while it is active.

GET /ws/screens/{slug}/events

Player snapshot channel.

This is the server-to-dashboard snapshot stream for live player connection state.

Access: internal-only. The web backend subscribes with signed request headers; browsers should not connect directly.

Player Control Channel

Messages from player to server

The player sends a state snapshot message.

state

Example payload:

{
  "type": "state",
  "clientId": "client-id",
  "clientName": "friendly label",
  "deviceId": "device-id",
  "userAgent": "browser ua",
  "page": "http://.../screen/demo",
  "viewport": { "width": 1920, "height": 1080 },
  "paused": false,
  "blackout": false,
  "currentSlide": null
}

When currentSlide is present, the player includes the active slide id, title, kind, and playlist signature.

The server recognizes clientId, clientName, deviceId, userAgent, page, viewport, paused, blackout, and currentSlide from state messages.

Messages from server to player

The server sends command messages with:

• type: "command"
• command
• optional sentAt
• optional targetConnectionId
• optional blackout for blackout commands
• optional url for redirect commands
• optional clientName and deviceId for client-name updates

Supported commands:

• blackout
• next
• pause
• previous
• refresh
• reload
• redirect
• setclientname

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.

redirect

Requests the player page to navigate to a new location. The destination is supplied as url by the caller that forwarded the command.

previous

Moves to the previous slide.

next

Moves to the next slide.

setclientname

Updates the client name associated with the player session and onboarding record. The command payload should include clientName and may include deviceId when the caller is updating a specific onboarding binding.

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
• clientName
• deviceId
• label
• userAgent
• viewport
• page
• currentSlide
• currentSlideId
• currentSlideTitle
• 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.