客户端开发

iTally 服务提供三个公开的只读接口，供手机 App、Apple Watch、简单硬件等独立客户端使用。这些接口无需鉴权，客户端也不发送任何控制指令。控制台使用的管理接口不在公开文档范围内。

接口	用途
GET /healthz	确认该地址是 iTally
/ws/v1	WebSocket，推送完整快照，适用于网页和手机 App
GET /poll/v1	长轮询，内容与 WebSocket 相同，适用于无法使用 WebSocket 的设备

1. 从二维码获取服务器地址

控制台「手机扫码」页生成的二维码内容为 http://<IP>:<端口>/t（全部机位）或 http://<IP>:<端口>/t/<机位 ID>（单个机位）。机位 ID 为 8 位小写字母和数字；网址中始终包含端口。

const m = /^http:\/\/([^/:]+):(\d+)\/t(?:\/([a-z0-9]{8}))?\/?$/.exec(qr.trim())
if (!m) throw new Error('不是 iTally 的二维码')
const base = `http://${m[1]}:${m[2]}`   // 例如 http://192.168.1.20:7777
const deviceId = m[3] ?? null           // null：让用户从快照的 devices 里选一个

2. 确认服务器是 iTally

GET <base>/healthz 返回：

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

如果状态码不是 200 或缺少 ok: true，请提示用户「这个地址不是 iTally」。该接口只检查服务本身，切换台离线时同样返回 200。

3. 选择接口

客户端	接口	理由
网页、手机 App（iOS、Android）	WebSocket /ws/v1	保持长连接，推送最快
Apple Watch、简单硬件	长轮询 /poll/v1	watchOS 普通 App 在真机上无法使用 WebSocket（Apple TN3135），只能发送普通 HTTP 请求

两者返回的快照内容相同。如何根据快照决定颜色，请参阅显示规则；App 需允许局域网明文连接，请参阅局域网明文连接。

快照

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

• program、preview 的值分别为 true、false 或 null（Unknown）。
• source.type 为当前切换台类型，未设置时为 null；source.state 是 connecting、ready 或 disconnected；source.error 为最近一次错误，没有错误时为 null。
• 切换台不处于 ready 时，所有机位的 program、preview 均为 null。机位在当前切换台下未对应画面，或对应画面不在当前 Tally 中时，同样为 null。