大屏接口

基础地址 https://show.piotcode.com/api，请求和响应都是 JSON。查询不用登录，可以跨站读取；控制要带口令。

查询

接口	说明
`GET /api/screen`	大屏现在的节目、内容和进度
`GET /api/catalog`	课件和影片目录、轮播清单
`GET /api/health`	服务是否正常、版本号

例子

curl https://show.piotcode.com/api/screen

{
  "mode": "deck",
  "now": { "kind": "deck", "id": "arduino-hardware", "title": "Arduino 硬件开发（实训）", "page": 5, "pages": 22 },
  "screen": { "online": true, "lastSeen": "2026-11-04T03:12:09.000Z", "applied": true, "size": [8944, 1404], "cache": { "done": 540, "total": 540 } },
  "rev": 12,
  "changedAt": "2026-11-04T03:10:00.000Z"
}

字段	含义
`mode`	下发的节目：`deck` 课件、`video` 影片、`loop` 轮播、`home` 待机画面、`off` 黑屏
`now`	此刻画面上的内容。课件有 `page` / `pages`，影片有 `time` / `duration` / `paused`。轮播时是当前这一项
`screen.online`	大屏 25 秒内上报过就算在线（正常每 10 秒报一次）
`screen.applied`	大屏是否已经执行了最新的指令
`screen.size`	大屏的分辨率
`screen.cache`	大屏电脑本机已存的文件数和总数，两个数相等时断网也能放
`rev`	节目版本号，每次切换节目加一

控制

带控制口令：Authorization: Bearer <口令>。控制台登录后用 Cookie，不用另外传。

curl -X POST https://show.piotcode.com/api/screen/command \
  -H "Authorization: Bearer $PIOT_SHOW_CONTROL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"deck","id":"smart-port-ai","page":3}'

指令	参数	作用
`deck`	`id`，可选 `page`	放课件
`video`	`id`，可选 `loop`、`muted`	放影片（默认循环、静音）
`loop`		按轮播清单循环
`home`	可选 `text`（40 字以内）	待机画面。带 `text` 时整墙显示这句欢迎词，公开接口里看不到这句话
`off`		黑屏
`next` / `prev`		课件翻页、换影片、轮播跳项
`goto`	`page`	课件跳到某页
`pause` / `play`		影片暂停、继续
`seek`	`time`（秒）	影片跳到某时间
`mute`	`muted`	影片静音、取消静音
`reload`		让大屏刷新页面

成功返回 { "ok": true, "rev": 13, "status": { … } }。出错时返回 { "error": "代码", "message": "说明" }：401 没登录，403 没权限，400 参数不对，409 当前节目不支持这个操作。

GET /api/screen/log 返回最近 50 条操作记录，需要控制口令。

实时推送

GET /api/screen/stream 是 Server-Sent Events，需要控制口令或大屏密钥。连上先收到当前节目和状态，之后有变化就推送。

事件	内容
`state`	节目变了：`{ "rev": 13, "program": { … } }`
`status`	状态变了，格式同 `GET /api/screen`
`action`	一次性动作：`next`、`prev`、`seek`、`reload`

大屏接入

展厅电脑用全屏浏览器打开带密钥的接入链接，密钥只在网址的 # 后面，不会发给服务器的日志，打开后保存在这台电脑上：

https://show.piotcode.com/screen/#key=<大屏密钥>

播放页用 POST /api/screen/report 上报实际进度。没有密钥打开 /screen/ 是同步观看，只跟随，不影响大屏。

宽高比 4:1 以上的屏幕（展厅 8944×1404）自动分成三区：中间放 16:9 内容，两侧放课程和影片信息。第一次接入后，大屏会把全部课件和影片存到本机，之后播放不走外网，断网也能接着放。三块屏分别开窗口时，用 /screen/?zone=left、center、right 显示其中一段，密钥只给中间那一块。