WebSocket Protocol

Connection

Overlay clients connect to the VMSC overlay server over a standard WebSocket. No special headers or subprotocols are required.

After the TCP handshake completes, the client must send an init message within a few seconds or the server will close the connection.

Client → Server Messages

The client sends JSON messages to subscribe to overlay updates and acknowledge commands.

init

Subscribe to a specific overlay's real-time updates. The overlayId and token are injected into the overlay HTML page by the server at load time.

{
  "action": "init",
  "overlayId": "uuid-string",
  "token": "auth-token-from-html"
}

Server → Client Messages

All server messages are JSON objects with a type field identifying the message kind.

init

Sent in response to a successful client init message. Contains the full overlay configuration and all current widgets.

{
  "type": "init",
  "overlay": {
    "name": "My Stream Overlay",
    "width": 1920,
    "height": 1080
  },
  "widgets": [
    { "id": "w-abc123", "type": "text", "x": 100, "y": 50, "content": "Hello" }
  ]
}

overlay-update

Broadcast whenever widget positions, properties, or the overlay layout changes. The client should replace its local state with the new data.

{
  "type": "overlay-update",
  "overlayId": "uuid-string",
  "overlay": { "name": "...", "width": 1920, "height": 1080 },
  "widgets": [ ... ]
}

The overlay and widgets fields follow the same schema as the init response. This is a full-state replacement, not a diff.

stream-event

Fired when a live stream event occurs (gift, follow, like, chat message, etc.). Widgets use this to display real-time activity.

{
  "type": "stream-event",
  "event": {
    "type": "gift",
    "user": { "uniqueId": "viewer123", "nickname": "CoolViewer" },
    "data": { "giftName": "Rose", "repeatCount": 5 }
  }
}

The event.type field corresponds to the TikTok event types: gift, follow, like, chat, share, subscribe, and viewer.

overlay-command

Sent when a rule action targets the overlay. Used to trigger animations, play audio, show alerts, or execute custom commands on specific widgets.

{
  "type": "overlay-command",
  "command": "show-alert",
  "widgetId": "w-abc123",
  "payload": { "text": "New follower!", "duration": 5000 }
}

The command and payload structure depends on the action type configured in the rule. Widgets that do not recognize a command should ignore it silently.

Authentication

WebSocket connections are authenticated using a short-lived token:

1. When the overlay HTML page is served via GET /overlay/:overlayId, the server generates a random token and injects it into the page as a global variable.
2. The overlay client reads the token from the page context and includes it in the init message.
3. The server validates the token and binds the connection to the requested overlay.

Tokens are single-use and scoped to a single overlay session. Refreshing the overlay page generates a new token.