WebSocket

Introduction

PalcoTimer uses WebSocket for real-time synchronization between all connected devices. Any change (play, pause, timer change, message) is propagated instantly.

Connecting

Connect to the WebSocket using the URL:

wss://app.palcotimer.com/ws/{roomId}?output={tipo}&name={nome}

Client → Server Messages

Request state

{
  "type": "request_state"
}

Ping (keep connection)

{
  "type": "ping"
}

Playback controls

// Play
{ "type": "control", "action": "play" }

// Pause
{ "type": "control", "action": "pause" }

// Stop
{ "type": "control", "action": "stop" }

// Reset
{ "type": "control", "action": "reset" }

// Next timer
{ "type": "control", "action": "next" }

// Previous timer
{ "type": "control", "action": "previous" }

// Go to specific timer
{ "type": "control", "action": "go_to", "timer_id": "uuid" }

// Add time (ms)
{ "type": "control", "action": "add_time", "value": 60000 }

// Set time (ms)
{ "type": "control", "action": "set_time", "value": 300000 }

Display modes

// Toggle blackout
{ "type": "control", "action": "blackout" }
{ "type": "control", "action": "stop_blackout" }

// Toggle flash
{ "type": "control", "action": "flash" }
{ "type": "control", "action": "stop_flash" }

// Toggle focus (message only)
{ "type": "control", "action": "focus" }
{ "type": "control", "action": "stop_focus" }

Messages

// Show message
{ "type": "control", "action": "show_message", "timer_id": "message_uuid" }

// Hide message
{ "type": "control", "action": "hide_message" }

Server → Client Messages

Room state

{
  "type": "room",
  "room": { "id": "...", "name": "...", ... },
  "timers": [ ... ],
  "messages": [ ... ],
  "playback": {
    "state": "running",
    "current_timer_id": "uuid",
    "elapsed_ms": 60000,
    "blackout": false,
    "flash": false,
    "focus": false
  },
  "server_time": 1704067200000
}

Playback status

{
  "type": "playback_status",
  "state": "running",
  "timer_id": "uuid",
  "elapsed_ms": 65000,
  "duration_ms": 300000,
  "server_time": 1704067200000,
  "blackout": false,
  "flash": false,
  "focus": false
}

Timer update

{
  "type": "timer_update",
  "timer": {
    "action": "update",
    "timer": { ... }
  }
}

Pong

{
  "type": "pong",
  "server_time": 1704067200000
}

Complete Example

// JavaScript - Connect and control
const ws = new WebSocket('wss://app.palcotimer.com/ws/ABC123?output=controller');

ws.onopen = () => {
  console.log('Connected!');
  // Request initial state
  ws.send(JSON.stringify({ type: 'request_state' }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'room':
      console.log('Room state:', data);
      break;
    case 'playback_status':
      console.log('Playback:', data.state, data.elapsed_ms);
      break;
  }
};

// Control
function play() {
  ws.send(JSON.stringify({ type: 'control', action: 'play' }));
}

function pause() {
  ws.send(JSON.stringify({ type: 'control', action: 'pause' }));
}