Client development

The iTally server provides three public, read-only endpoints for standalone clients such as phone apps, Apple Watch and simple hardware. They require no authentication, and clients never send control commands. The console’s management API is not publicly documented.

Endpoint	Purpose
GET /healthz	Confirms the address is iTally
/ws/v1	WebSocket that pushes full snapshots, for web pages and phone apps
GET /poll/v1	Long poll with the same content as the WebSocket, for devices that cannot use WebSocket

1. Get the server address from the QR code

The QR code on the console’s Phone access page contains http://<IP>:<port>/t (all cameras) or http://<IP>:<port>/t/<camera ID> (one camera). Camera IDs are eight lowercase letters and digits, and the address always includes the port.

const m = /^http:\/\/([^/:]+):(\d+)\/t(?:\/([a-z0-9]{8}))?\/?$/.exec(qr.trim())
if (!m) throw new Error('Not an iTally QR code')
const base = `http://${m[1]}:${m[2]}`   // e.g. http://192.168.1.20:7777
const deviceId = m[3] ?? null           // null: let the user pick from the snapshot's devices

2. Confirm the server is iTally

GET <base>/healthz returns:

{ "ok": true, "version": "1.0.0" }

If the status is not 200 or ok is not true, tell the user the address is not iTally. The endpoint checks only the server itself, so it returns 200 even when the switcher is offline.

3. Choose an endpoint

Client	Endpoint	Why
Web pages, phone apps (iOS, Android)	WebSocket /ws/v1	Fastest updates over one open connection
Apple Watch, simple hardware	Long poll /poll/v1	Standard watchOS apps cannot use WebSocket on a real watch (Apple TN3135); plain HTTP requests work

Both return the same snapshot. To turn a snapshot into a colour, see Display rules. Apps must allow plain HTTP on the local network; see Plain HTTP on the local network.

The snapshot

{
  "type": "snapshot",
  "source": { "type": "vmix", "state": "ready", "error": null },
  "devices": [{ "id": "k3m9x2qa", "name": "Camera 1", "program": true, "preview": false }]
}

• program and preview are each true, false or null (Unknown).
• source.type is the current switcher type, or null if none is set; source.state is connecting, ready or disconnected; source.error is the latest error, or null.
• While the switcher is not ready, every camera’s program and preview are null. They are also null for a camera with no input for the current switcher, or whose input is not in the current tally.