screenRIG
登录开始使用

文档

设备健康 CLI 命令

重启和更新设备，安排显示和重启计划，设置亮度、输出模式和电视输入切换，锁定自助终端，查看运行时间、健康状况和存储。

这里的每个命令都按 CLI 参考所述运行：全局标志、JSON 输出、退出代码、修订和重试。

设备健康和电源

每个配对的播放器在会话开始、每十五分钟以及显示连接或电源变化时报告设备健康状态。它还声明支持的主机功能：在各设备上可用的 reboot、volume、clear_cache、restart_app 和 update，以及可用的显示电源方法（display_power.serial，显示器的 RS-232 控制端口；display_power.cec、display_power.ddc、display_power.backlight 或 display_power.scrim，屏幕黑屏），另有用于下述设置的 display_power.idle、brightness.auto 和 kiosk_lock。screen show 返回两者。

screen show 返回健康状态为 data.health，带服务器的 reported_at；无报告 35 分钟后 stale 变为真，最后报告保持可见。带 --human 时打印 Health 块：报告时间、设备和播放器运行时间、内存使用、CPU 负载和核心数、温度、显示连接和电源、网络类型和 Wi-Fi 信号、电池电量、带电池设备的充电状态和供电来源，以及过去 24 小时内的崩溃和渲染器重启。screen list --human 添加 HEALTH 列，当任何列出的屏幕需要关注：display disconnected、hot（80 °C 或以上）、on battery、crashing（24 小时内 3 次或以上崩溃）或 stale；已上报且没有问题的屏幕显示 ok。

播放器还会上报其可使用的存储空间。screen show 会将其作为 storage 返回，并在播放列表放不下时附带 storage_shortfall；screen storage-forecast 会在分配播放列表之前，对照它检查该播放列表。

转换以 screen.health_changed 事件形式到达，由 events list 和 events follow 以紧凑的 changes= 值打印，例如 display_disconnected,temperature_high temperature_c=82。screen reboot 会追加 screen.reboot_requested（reboot_id、expires_at、state、source），screen clear-cache、screen restart-app 和 screen update-software 会追加 screen.command_requested（command_id、command、expires_at、state）；播放器的上报会追加 screen.command_result（command_id、command、state done 或 failed，以及其 cause 和 detail）。显示器覆盖或排程会追加 screen.display_changed。音量变更会追加 screen.volume_requested（volume_id、level、muted）。重启排程在被设置或清除时会追加 screen.reboot_schedule_changed，在某个窗口过去而未重启时会追加 screen.reboot_skipped，其 reason 为 reboot_pending（有人请求的重启仍在等待）、reboot_unsupported（播放器未声明 reboot）、window_missed（窗口已结束，或被夏令时切换吞掉）或 not_permitted（项目不允许使用屏幕）。screen.reboot_requested 在由排程发出时携带 source schedule，否则为 manual。与每个 screen.* 事件一样，它们在监听流上和作为 webhook 投递时免费。通知会在显示器断开、设备过热或使用电池供电、或播放器持续崩溃时，向你发送电子邮件，或 POST 签名的 webhook。

screen uptime，screen presence 和 screen health-history 读取单个屏幕随时间的操作：每日可用性，在线和离线转换，以及其报告的健康状况。project uptime 和 project health-trend 读取整个设备群。离线状态在屏幕无法访问 60 秒后记录，历史数据根据计划的事件保留期限保存。

问题代码退出含义
reboot_unsupported5该屏幕的播放器未声明 reboot。未发送也未存储任何内容；screen reload 刷新内容而不重启设备。
command_unsupported5屏幕的播放器未声明命令所需的能力 clear_cache、restart_app 或 update。未发送任何内容；screen show 列出主机功能，screen reload 刷新内容。
volume_unsupported5屏幕的播放器未声明 volume。未发送也未存储任何内容；请更新播放器，或在其设置菜单中设置音量。
resource_conflict5屏幕仍在等待配对，尚无播放器可切换。仍可设置显示排程。
invalid_request8显示器或重启排程文件格式错误。
protected_target5屏幕位于受保护文件夹中，且该更改没有审核形式：显示器电源及其排程、display-idle、brightness 和 volume。重启和维护命令不受限制。
rate_limited7重启：每个屏幕每 10 分钟 2 次。清除缓存、重启应用和更新软件合计：每个屏幕每 10 分钟 2 次。两者另外还限制为每个组织每分钟 600 次、每个 IP 每分钟 60 次。显示器、重启排程和音量写入：每个屏幕 10 次，每个组织每分钟 600 次，每个 IP 每分钟 60 次。请等待 retry_after_seconds。

当命令接受多个 ID、--tag TAG 或 --folder ID 时，它们作为一个 fleet 请求 运行，带有 fleet 信封和退出规则。--tag 和 --folder 只选择活动屏幕，--folder 会覆盖该屏幕文件夹及其内部的每个文件夹。--expect-rev 只接受一个屏幕 ID。

screen reboot#

重启屏幕设备或机群设备。

screen reboot (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--yesboolean多个 ID 时，--tag 或 --folder关闭确认群组重启。CLI从不提示。
--expires-in DURATIONstring否24h，由服务器应用请求等待离线屏幕上线的时间：90s、30m、2h 或 1d，范围从 60s 到 24h。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen reboot scr_LOBBY
screenrig screen reboot scr_LOBBY --expires-in 2h
screenrig screen reboot --tag Lobby --yes
screenrig screen reboot --folder sfd_01EXAMPLEFOLDER000000000 --yes

播放器重启的是设备，而不仅是自身。在线的屏幕会立即收到重启（state sent）；离线的屏幕会将其保持为 queued，并在 expires_at 之前上线时收到，除非 --expires-in 另有说明，否则为请求后 24 小时。响应中包含 reboot_id、state 和 expires_at。较新的重启会取代仍在排队的重启。screen show 列出屏幕的 commands：已发送的重启在设备报告已启动后变为 done，screen command cancel 取消仍在排队的重启。在车队中，每个结果的 reboot 带有相同的 state。被拒绝或失败的请求，以及完全相同请求的重放，不计入每屏幕限额。从发出重启起，直到设备报告已启动或十分钟过去，屏幕不会开启 screen_offline 或 display_disconnected 警报；这期间到期的任一类提醒会等到该时段结束再加上其保持时间，而 crashing 提醒会作为 planned_reboot 被跳过。之后仍成立的条件会正常开启。

screen clear-cache#

清除屏幕播放器的缓存，或车队中各播放器的缓存。

screen clear-cache (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--yesboolean多个 ID 时，--tag 或 --folder关闭确认车队请求。CLI 从不提示。
--expires-in DURATIONstring否24h，由服务器应用请求等待离线屏幕上线的时间：90s、30m、2h 或 1d，范围从 60s 到 24h。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen clear-cache scr_LOBBY
screenrig screen clear-cache scr_LOBBY --expires-in 2h
screenrig screen clear-cache --tag Lobby --yes

播放器删除已下载的媒体、应用包和数据缓存，保留其配对、身份和设置，然后重新获取清单和内容；内容重新填充期间，屏幕可能显示其加载状态。它只送达声明 clear_cache 的播放器。在线屏幕会立即收到请求（state sent）；离线屏幕将其保持为 queued，并在 expires_at 之前上线时收到，即请求后 24 小时，除非 --expires-in 另有规定。响应携带 command_id、command、state 和 expires_at。未声明该能力的播放器返回 409 command_unsupported，不发送任何内容；在车队中该屏幕单独失败。screen show 在 commands 下列出该命令，播放器报告后，将其标记为 done 或 failed，附带 cause 和简短的 detail：缓存已清除且重新获取已开始时为 cleared，缓存无法清除时为 clear_failed。没有报告的 sent 命令保持 sent。同类型的较新命令会取代仍在排队的命令，screen command cancel 取消仍在排队的命令。在车队中，每个结果的 command 带有相同的 state。车队（多个 ID、--tag 或 --folder）需要 --yes。被拒绝或失败的请求，以及完全相同请求的重放，不计入每屏每 10 分钟合计 2 次清除缓存、重启应用和更新软件请求的限制。

screen restart-app#

重启屏幕播放器的应用，或车队中各播放器的应用。

screen restart-app (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--yesboolean多个 ID 时，--tag 或 --folder关闭确认车队请求。CLI 从不提示。
--expires-in DURATIONstring否24h，由服务器应用请求等待离线屏幕上线的时间：90s、30m、2h 或 1d，范围从 60s 到 24h。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen restart-app scr_LOBBY
screenrig screen restart-app scr_LOBBY --expires-in 2h
screenrig screen restart-app --tag Lobby --yes

播放器重启其应用，而非设备（Web 播放器重新加载其页面），并从重启后的进程报告。它只送达声明 restart_app 的播放器；screen reboot 重启设备。在线屏幕会立即收到请求（state sent）；离线屏幕将其保持为 queued，并在 expires_at 之前上线时收到，即请求后 24 小时，除非 --expires-in 另有规定。响应携带 command_id、command、state 和 expires_at。未声明该能力的播放器返回 409 command_unsupported，不发送任何内容；在车队中该屏幕单独失败。screen show 在 commands 下列出该命令，播放器报告后，将其标记为 done 或 failed，附带 cause 和简短的 detail：restarted，或重启无法开始时为 restart_failed。没有报告的 sent 命令保持 sent。同类型的较新命令会取代仍在排队的命令，screen command cancel 取消仍在排队的命令。在车队中，每个结果的 command 带有相同的 state。车队（多个 ID、--tag 或 --folder）需要 --yes。被拒绝或失败的请求，以及完全相同请求的重放，不计入每屏每 10 分钟合计 2 次清除缓存、重启应用和更新软件请求的限制。

screen update-software#

将屏幕的播放器更新到最新版本，或更新车队中的各播放器。

screen update-software (<id>... | --tag TAG | --folder ID) [--yes] [--expires-in DURATION] [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--yesboolean多个 ID 时，--tag 或 --folder关闭确认车队请求。CLI 从不提示。
--expires-in DURATIONstring否24h，由服务器应用请求等待离线屏幕上线的时间：90s、30m、2h 或 1d，范围从 60s 到 24h。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen update-software scr_LOBBY
screenrig screen update-software scr_LOBBY --expires-in 2h
screenrig screen update-software --tag Lobby --yes

播放器立即检查最新的播放器版本，并在其平台允许播放器自行更新时安装；Web 播放器更新其 service worker，然后重新加载。它只送达声明 update 的播放器：通过商店安装或由设备管理器管理的播放器通过该渠道更新。在线屏幕会立即收到请求（state sent）；离线屏幕将其保持为 queued，并在 expires_at 之前上线时收到，即请求后 24 小时，除非 --expires-in 另有规定。响应携带 command_id、command、state 和 expires_at。未声明该能力的播放器返回 409 command_unsupported，不发送任何内容；在车队中该屏幕单独失败。screen show 在 commands 下列出该命令，播放器报告后，将其标记为 done 或 failed，附带 cause 和简短的 detail：最新版本已在运行时为 up_to_date，新版本已启动后为 updated，失败时为 update_check_failed、download_failed、install_failed 或 no_update_channel。没有报告的 sent 命令保持 sent。同类型的较新命令会取代仍在排队的命令，screen command cancel 取消仍在排队的命令。在车队中，每个结果的 command 带有相同的 state。车队（多个 ID、--tag 或 --folder）需要 --yes。被拒绝或失败的请求，以及完全相同请求的重放，不计入每屏每 10 分钟合计 2 次清除缓存、重启应用和更新软件请求的限制。

screen command cancel#

取消仍为离线屏幕排队的命令。

screen command cancel <id> <command_id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
<command_id>string是无来自 screen show 中 commands 的 ID，或该请求返回的 reboot_id、reload_id 或 command_id。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen command cancel scr_01EXAMPLESCREEN00000000 rbt_01EXAMPLEREBOOT00000000

它会取消正在等待离线屏幕的 reboot、reload、clear_cache、restart_app 或 update，使其永远不会被发送。只有排队中的命令可以取消。已发送的命令（sent 或 done）返回 409 resource_conflict，并附带 "The command was already sent."；不再排队的命令（expired、cancelled 或 superseded）返回 409 resource_conflict，并附带 "The command is no longer queued."；屏幕未列出的 ID 返回 404 not_found。响应是该命令状态为 cancelled 的屏幕，屏幕版本不变。

screen display#

立即开启或关闭屏幕的显示，或清除该覆盖设置。

screen display [set] (<id>... | --tag TAG | --folder ID) --power on|off [--until TIME | --for DURATION] [--expect-rev REVISION]
screen display clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。ID 后的尾随 on 或 off 等同于 --power。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--power on|offstring是，针对 set无立即应用的权限。
--until TIMEstring否显示排程的下一个边界严格 RFC 3339 时间点，含秒和偏移，发送时归一化为 UTC；严格未来且最多提前 7 天。不能与 --for 一起使用。
--for DURATIONstring否显示排程的下一个边界30m，2h，或 3d，最多 6d23h59m。不适用于 --until。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen display scr_LOBBY --power off --for 2h
screenrig screen display --tag Lobby --power on
screenrig screen display scr_A scr_B --power off --for 8h
screenrig screen display clear --tag Lobby

screen display ID 是 screen display set ID 的简写；clear 不接受 --power、--until 或 --for。screen display 是显示器排程的手动覆盖。没有 --until 或 --for 时，会在排程的下一个边界结束；后续更改显示器排程或时区会将结束时间移动到新的边界。如果接下来八天内没有边界，例如没有启用排程，则会持续到 screen display clear 或被替换。screen display clear 结束覆盖，显示器排程重新生效；若没有，则显示器保持开启。

保存覆盖设置时不会等待播放器。display.override_status 会将较新的显示器上报与其比较：matches、mismatch、pending、stale 或 unknown；matches 描述的是上报情况，而不是命令已执行。警告 display_power_mismatch 指出有一份较新的上报与设置不一致，display_power_unconfirmed 表示还需要一份更新且可用的上报；因此截图前请先查看 screen show。display_scrim_only 表示播放器只控制一层黑色遮罩：on 会移除该遮罩，且不会发送硬件唤醒命令。位于受保护文件夹中的屏幕会拒绝显示器变更（protected_target）。

screen display-schedule#

显示、设置或清除屏幕显示器的开关状态。

screen display-schedule show <id>
screen display-schedule set (<id>... | --tag TAG | --folder ID) --file FILE [--expect-rev REVISION]
screen display-schedule clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID；show 接受一个。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--file FILE路径是，针对 set无显示排程，或使用 - 读取标准输入。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen display-schedule set scr_LOBBY --file hours.json
screenrig screen display-schedule set --tag Cafe --file hours.json

显示器排程为 {enabled, windows}，两者都必填，windows 按屏幕时区列出 1 到 16 个显示器开启的时间窗口；任何窗口之外，显示器进入待机。播放器在设备上评估排程，离线时仍有效。窗口的 end 在或早于 start 跨越午夜，且无 start 和 end 的窗口覆盖全天。enabled: false 保持窗口并保持显示器开启。display-schedule show 返回 display_schedule（没有时为 null）以及屏幕的 display 状态。其保存的输出可以编辑后用 set --file 再次发送。位于受保护文件夹中的屏幕会拒绝更改其显示排程（protected_target）。

{"enabled": true, "windows": [{"days": ["mon", "tue", "wed", "thu", "fri"], "start": "07:00", "end": "19:00"}, {"days": ["sat"]}]}

screen show --human 打印 Display: 及请求的功率、其来源（手动覆盖、显示计划或默认）及屏幕时区的截止时间、计划窗口和播放器报告的功率，超过 35 分钟无报告则标记为过时。

screen volume#

设置屏幕音量，或将其静音，可针对单个屏幕或整个设备群。

screen volume (<id>... | --tag TAG) [--level 0-100] [--mute | --unmute] [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id> 或 --tag 之一无一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id> 或 --tag 之一无每个带此标签的活动屏幕。
--level 0-100integer--level、--mute、--unmute 中至少一个无音量，0 到 100。省略时，播放器保持其音量级别。
--muteboolean--level、--mute、--unmute 中至少一个关闭将屏幕静音并保留其音量级别。不能与 --unmute 同用。
--unmuteboolean--level、--mute、--unmute 中至少一个关闭恢复以该音量级别播放。不可与 --mute 组合。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen volume scr_LOBBY --level 40
screenrig screen volume scr_LOBBY --mute
screenrig screen volume scr_LOBBY --unmute
screenrig screen volume --tag Lobby --level 25 --unmute

一个屏幕只有一个音量：0 到 100 的音量级别，外加静音状态。静音会保留音量级别，因此取消静音即恢复原级别。在线的屏幕会立即应用变更；离线的屏幕会在重新上线时应用最新的请求，较新的请求会替换较早的请求。之后在播放器自身设置菜单中所做的更改优先生效，直到下一个 screen volume，在那里更改音量级别会取消静音。screen show 报告 volume，带有最新的 requested 变更，并以 reported 给出播放器达到的 level 和 muted 以及 hardware：音量级别到达设备或面板输出时为 true，为播放器自身增益时为 false；stale 在 35 分钟没有报告后变为 true。只有声明 volume 能力的播放器才会应用它：任何其他屏幕返回 409 volume_unsupported（退出码 5），且不记录任何内容。归档屏幕返回 screen_archived，仍在等待配对的屏幕返回 resource_conflict。受保护文件夹中的屏幕会拒绝该更改（protected_target），在设备群中只要有一个受保护屏幕，整个请求都会被拒绝。控制台的屏幕页面提供同样的音量控件。

screen display-idle#

在一段时间无人使用后让屏幕变暗，或关闭此功能。

screen display-idle <id> --after SECONDS --wake WAKE [--expect-rev REVISION]
screen display-idle <id> --off [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--after SECONDSinteger--after 或 --off 之一无在无人使用达这么多秒后变暗，30 到 86400。需要 --wake。
--wake WAKEstring配合 --after无重新点亮屏幕的方式：touch、presence 或 touch,presence。presence 在设备本地读取设备的摄像头；不会有图像离开设备。
--offboolean--after 或 --off 之一关闭关闭空闲变暗。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen display-idle scr_LOBBY --after 300 --wake touch
screenrig screen display-idle scr_LOBBY --after 600 --wake touch,presence --expect-rev 4
screenrig screen display-idle scr_LOBBY --off

在没有触摸或按键、或（在 --wake 列出 presence 时）屏幕前无人的情况下持续 --after 秒后，屏幕变暗。变暗期间，播放器暂停播放（无播放记录，无广告），并报告显示电源关闭；唤醒事件会立即让屏幕重新亮起并恢复播放，唤醒变暗屏幕的那次触摸不会传给页面。让面板保持关闭的显示排程或覆盖优先，页面在屏幕上时持有 device.display 的应用程序同样优先。只有 display.idle 会更改。当 screen show 在其主机能力中列出 display_power.idle 时，播放器才会应用它；无论如何设置都会被存储，screen show 将其列为 Display idle。Propose 访问权限无法更改它（insufficient_access），受保护文件夹中的屏幕会拒绝它（protected_target）。

screen brightness#

设置屏幕亮度是否跟随设备的光线传感器。

screen brightness <id> --mode auto|fixed [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--mode auto|fixedstring是无auto 根据设备的光线传感器设置亮度；fixed 保持操作员设定的亮度，这是默认值。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen brightness scr_LOBBY --mode auto
screenrig screen brightness scr_LOBBY --mode fixed --expect-rev 4

只有 display.brightness 会更改。当 screen show 在其主机能力中列出 brightness.auto 时（设备仅在具备光线传感器时才声明它），播放器才会应用 auto；设置显示器亮度的应用程序在其页面显示期间优先。无论如何设置都会被存储，screen show 将其列为 Display brightness。适用 screen display-idle 的访问规则。

screen display-output#

设置屏幕的播放器输出的视频模式，或清除。

screen display-output <id> (--mode MODE | --clear) [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--mode MODEstring--mode 或 --clear 之一无auto 将模式交由显示器自身的首选模式。否则使用 WIDTHxHEIGHTxFPS，并可附带可选的 p 或 i，按 BrightSign 对模式的命名方式，例如 3840x2160x60p。
--clearboolean--mode 或 --clear 之一关闭移除该设置。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen display-output scr_LOBBY --mode 3840x2160x60p
screenrig screen display-output scr_LOBBY --mode auto --expect-rev 4
screenrig screen display-output scr_LOBBY --clear

screen show 在 Output modes the Player can set 下列出播放器当前可以设置的模式，以及当前生效的模式。播放器报告这些模式后，不在该列表中的模式为 invalid_request，因此请选择其列出的模式。只有 display.output 会更改。当 screen show 在其主机能力中列出 display_output.mode 时，播放器才会应用它，BrightSign 播放器会声明这一点；在其他播放器上，除 auto 以外的任何模式都会返回 display_output_unsupported，而清除始终有效。播放器只应用一次模式，可能为此重启，并报告其达到的模式。适用 screen display-idle 的访问规则。

screen display-cec#

让屏幕的播放器通过 CEC 接管电视的 HDMI 输入，或停止。

screen display-cec <id> (--on | --off | --clear) [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--on, --off, --clearboolean三者之一无--on 让播放器在启动时以及显示器电源开启时声明 HDMI-CEC 活动源，使电视切换到播放器的输入。--off 保留该设置但不占用输入。--clear 将其移除。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen display-cec scr_LOBBY --on
screenrig screen display-cec scr_LOBBY --off --expect-rev 4
screenrig screen display-cec scr_LOBBY --clear

只有 display.cec 会更改。当 screen show 在其主机能力中列出 display_power.cec_active_source 时，播放器才会应用它，BrightSign 播放器会声明这一点；在其他播放器上 --on 会返回 display_cec_unsupported，而 --off 和 --clear 始终有效。显示排程或覆盖使显示器保持关闭期间，播放器不发送任何内容，CEC 故障也绝不会影响播放。screen show 将该设置列为 Display CEC。适用 screen display-idle 的访问规则。

screen kiosk-lock#

将屏幕的播放器固定在屏幕上，或解除固定。

screen kiosk-lock <id> (--on | --off) [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--on, --offboolean两者之一无--on 将播放器固定在屏幕上；--off 解除固定。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig screen kiosk-lock scr_LOBBY --on
screenrig screen kiosk-lock scr_LOBBY --off --expect-rev 4

--on 使用 Android 屏幕固定：屏幕前的人员首次需要确认，播放器被固定期间，状态栏、主屏幕和最近任务均被禁用。操作员设置面板可以退出该锁定，直到下一次清单或重启再次应用它。当 screen show 在其主机能力中列出 kiosk_lock 时，播放器才会应用它；无论如何设置都会被存储，开启期间 screen show 会列出 Kiosk lock。Propose 权限无法更改它（insufficient_access）。

screen reboot-schedule#

显示、设置或清除后端重启屏幕设备的时间。

screen reboot-schedule show <id>
screen reboot-schedule set (<id>... | --tag TAG | --folder ID) (--window SPEC... | --file FILE) [--disabled] [--expect-rev REVISION]
screen reboot-schedule clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION]
参数类型必填默认备注
<id>...string<id>、--tag 或 --folder 之一无一个或多个 scr_ 屏幕 ID；show 接受一个。多个 ID 作为一个舰队请求运行。
--tag TAGstring<id>、--tag 或 --folder 之一无每个带此标签的活动屏幕。
--folder IDstring<id>、--tag 或 --folder 之一无此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。
--window SPECstring--window 或 --file 之一，用于 set无在此每周窗口开始时重启，DAYS HH:MM-HH:MM 按屏幕时区，例如 "Mon-Sun 04:00-04:30"（DAYS@HH:MM-HH:MM 也可用）。DAYS 为 daily、某一天、类似 Mon-Fri 的范围，或类似 Sat,Sun 的列表。最多重复 16 次；每个窗口持续 5 分钟到 24 小时。
--file FILE路径--window 或 --file 之一，用于 set无JSON 格式的重启排程，或用 - 表示标准输入，取代 --window。
--disabledboolean否关闭保留时间窗口，但不重启任何设备。不能与 --file 同用；请改在文件中写 "enabled": false。
--expect-rev REVISIONstring否无仅一个屏幕 ID。可选的修订前提。
screenrig screen reboot-schedule set scr_LOBBY --window "Mon-Sun 04:00-04:30"
screenrig screen reboot-schedule set --tag Cafe --window "Mon-Fri 04:00-04:30" --window "Sat,Sun 05:00-06:00"
screenrig screen reboot-schedule set scr_LOBBY --file reboots.json --expect-rev 4
screenrig screen reboot-schedule set --folder sfd_01EXAMPLEFOLDER000000000 --window "Mon-Sun 04:00-04:30"

在屏幕时区的每个窗口开始时，screenRIG 发出与 screen reboot 相同的重启，因此 "Mon-Sun 04:00-04:30" 会让屏幕每天本地时间 04:00 重启。screen show 中的 commands 以 source schedule 列出它，screen show 和 reboot-schedule show 打印 next_reboot_at。结束时间等于或早于开始时间的窗口跨越午夜，没有时间的窗口覆盖全天。reboot-schedule show 保存的输出可以编辑后用 set --file 发回：

{"enabled": true, "windows": [{"days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"], "start": "04:00", "end": "04:30"}]}

在线屏幕会立即收到重启。离线屏幕只在其窗口结束之前保持排队，因此重启绝不会落在窗口之外：窗口之后才恢复的屏幕不会收到重启。落在春季拨快间隙内的开始时间，在窗口的第一个有效分钟触发；秋季回拨造成的重复时间，每个窗口每个本地日期只触发一次。排程重启绝不会取代人工请求且仍在等待屏幕的重启；该次执行会以 screen.reboot_skipped（reboot_pending）被跳过。屏幕需要声明了 reboot 的播放器；之后失去 reboot 的屏幕会跳过每个窗口并保留其排程。更改时区会取消仍在等待的排程重启，并将 next_reboot_at 移到新的时区。排程发出的重启不会触发离线警报，与 screen reboot 下相同。screen.reboot_schedule_changed 记录每次设置或清除。文件为 {enabled, windows}，两者都必填。重启排程在每个套餐中都可用。在机群中，每个结果属于该屏幕自己：播放器无法重启的屏幕为 reboot_unsupported。

screen uptime#

读取屏幕的每日可用性，按 UTC 天计算。

screen uptime <id> [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD] [--format json|csv|xlsx|pdf] [--output FILE]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--day-from YYYY-MM-DDstring否提前 29 天 --day-to首个 UTC 天（含）。
--day-to YYYY-MM-DDstring否今天最后的UTC日，含当日。与 --day-from 一起使用时，范围包含首尾两天，最多 366 天。
--format FORMATstring否jsonjson 是命令的应答。csv、xlsx 或 pdf 会把所有行写入 --output，并返回该文件的 path、bytes、sha256、content_type 和 format。
--output FILE路径否./screen-uptime.FORMAT用于 csv、xlsx 或 pdf 的文件：必须是文件路径，不能是目录，也不能是 -。已有的文件会被替换。不能与 json 一起使用。
screenrig screen uptime scr_01EXAMPLESCREEN00000000
screenrig screen uptime scr_01EXAMPLESCREEN00000000 --day-from 2026-09-01 --day-to 2026-09-30
screenrig screen uptime scr_01EXAMPLESCREEN00000000 --format xlsx --output uptime.xlsx

data.items 按 UTC 天列出每个有记录状态的行，最旧的在前：online_s、offline_s、availability（记录时间内在线；无记录时为 null）、coverage（有记录状态的当天份额）、intervals 和包含至今开放区间的 live。无记录状态的时间降低 coverage，但从不算作停机。无记录的天没有行。

screen presence#

列出屏幕的在线和离线转换，最新优先。

screen presence <id> [--since TIME] [--until TIME]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--since TIMEstring否提前 30 天 --until转换时间的包含起点：带秒和偏移（归一化为 UTC）的 RFC 3339 时间点，now，或类似 7d、12h 或 30m 的时长。
--until TIMEstring否现在独占结束，形式相同。最多在 --since 后366天内。
screenrig screen presence scr_01EXAMPLESCREEN00000000 --since 7d
screenrig screen presence scr_01EXAMPLESCREEN00000000 --since 2026-09-01T00:00:00Z --until 2026-09-08T00:00:00Z

data.items 在服务器仅在屏幕重新连接时才注意到的离线状态下，携带 at、state 和 detected_on_reconnect（此时 at 表示其存在租约结束的时间）。CLI 会跟随 next_cursor 到最后，并对每一次状态变更以 next_cursor null 进行响应，因此可用 --since 缩小长时间范围。

screen health-history#

列出屏幕随时间报告的健康状况，每小时一条报告或汇总。

screen health-history <id> [--from TIME] [--to TIME] [--resolution raw|hour] [--format json|csv|xlsx|pdf] [--output FILE]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--from TIMEstring否提前 24 小时 --to报告时间的包含起点：带秒和偏移（归一化为 UTC）的 RFC 3339 时间点，now，或类似 7d、12h 或 30m 的时长。
--to TIMEstring否现在独占结束，形式相同。最多在 --from 后31天内，使用 --resolution hour 时最多93天。
--resolution raw|hourstring否rawraw 列出每个接受的报告；hour 汇总每个 UTC 小时。
--format FORMATstring否jsonjson 是命令的应答。csv、xlsx 或 pdf 会把所有行写入 --output，并返回该文件的 path、bytes、sha256、content_type 和 format。
--output FILE路径否./screen-health-history.FORMAT用于 csv、xlsx 或 pdf 的文件：必须是文件路径，不能是目录，也不能是 -。已有的文件会被替换。不能与 json 一起使用。
screenrig screen health-history scr_01EXAMPLESCREEN00000000 --from 6h
screenrig screen health-history scr_01EXAMPLESCREEN00000000 --from 30d --resolution hour
screenrig screen health-history scr_01EXAMPLESCREEN00000000 --from 30d --resolution hour --format csv --output health.csv

raw 回答 data.samples，每个被接受的报告格式与 screen show 的 health 相同，但没有 stale。hour 回答 data.hours，每个 UTC 小时一份摘要：报告数、最高和平均温度、峰值负载和内存占比、最弱的 Wi-Fi 信号、display_disconnected，以及最高崩溃和渲染器重启次数。CLI 会跟随 next_cursor 到末尾，因此可缩小长原始区间或使用 --resolution hour。原始报告几秒内送达，小时摘要约 5 分钟内送达。

screen storage-forecast#

在分配播放列表之前，检查它是否放得进屏幕的播放器最近上报的存储空间。

screen storage-forecast <id> --playlist-id ID [--playlist-rev REVISION]
参数类型必填默认备注
<id>string是无scr_ 屏幕 ID。
--playlist-id IDstring是无要检查的 pl_ 播放列表。
--playlist-rev REVISIONinteger否无当播放列表不是此版本时拒绝检查（revision_conflict，退出码 6）。
screenrig screen storage-forecast scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000
screenrig screen storage-forecast scr_01EXAMPLESCREEN00000000 --playlist-id pl_01EXAMPLEPLAYLIST000000 --playlist-rev 7

它不会写入任何内容：没有分配，没有屏幕版本变化，也没有事件。只读访问权限即可，每个屏幕每分钟最多可检查 30 次。data.fit 为 fits、partial（部分页面被排除）、none_fit（什么都加载不了）或 unknown（屏幕从未上报过存储，或播放列表的内容尚未就绪）。data.excluded_page_count 统计被排除的页面数，data.required_bytes 是整个播放列表所需的空间，data.capacity_bytes 是播放器上报的可用空间，data.basis 为 reported_capacity，data.received_at 是播放器上报的时间。当 fit 为 unknown 时，字节数和 received_at 为 null。超过 24 小时的上报会被标记为过期，但仍会被使用。播放列表放不下时，应答会带有 storage_full 警告：请释放运行播放器的设备上的存储空间，然后再次检查。缓存与存储说明了这一规划。已保存的分配并不能确认播放。

其他命令组