排程和接管
屏幕的活动和播放列表排程条目是同一个堆栈的层级。服务器从顶部开始决定每个屏幕播放什么：它的接管、覆盖它的活动（先是 --priority，然后是最新的）、屏幕自己的排程条目（按顺序）、用 screen assign 分配的播放列表，然后是设置了默认播放列表的最近一个屏幕文件夹的默认播放列表。第一个有内容的层级播放。切换在边界时间点后约一分钟内生效，Player 无需更新。多个屏幕的排程行工作表可一步导入：见排程导入。
层级在其所有规则都生效时生效：from 和 until、每周 windows、monthly 规则、dates、except 日期、data 条件和 interaction 条件。monthly 规则是每月的某个 day（1 到 31；没有该日的月份会跳过）或第 nth 个星期几（1 到 4，-1 表示最后一个），配合 weekday；dates 项是一个 date；两者都可带可选的 start 和 end 时间，否则覆盖全天。except 日期会移除在该日开始的每次出现，包括跨夜的后续部分，跨夜的出现归属于其开始的日期。data 为 {key, path?, equals?}，在该卡片数据存在或等于标量值期间生效。interaction 为 {idle_s}（5 到 3600，默认 60）：有人通过触摸、点击或按键使用屏幕时播放该层级，并在 idle_s 秒无输入后退回，例如叠在展示循环之上的交互页面。displays 列出该层级播放所在的视频墙输出（1 到 12）。covers 为 full（整个页面，默认）、main，或 header、footer、side，后者是绘制在页面之上的条带，需要为该区域制作的播放列表；参见条带。start 为 next_item（默认），等待当前项目结束；或为 on_time，在边界时刻将其中断。能自行解析堆栈的播放器会播放 interaction、data、条带和 displays 层级；对其他任何播放器，campaign explain 会将该层级报告为 off，原因是 stack_only（需要能自行解析堆栈的播放器）。
screen show，screen list，以及下面的排程和接管写入命令返回 effective_playlist（{id, source, entry_id?, until?}，其中 source 是 takeover，campaign，schedule，default，或 folder），takeover，和 playlist_schedule。entry_id 对 campaign 是活动 ID，对 schedule 是条目 ID，对 folder 是文件夹 ID。until 是下一个已知选择变化的时刻。screen show --human 以屏幕时区打印，如 Assigned: pl_LUNCH (schedule entry lunch until 2026-08-14 15:00 America/Los_Angeles) 或 Assigned: pl_LUNCH (campaign cmp_LUNCH until 2026-08-14 15:00 America/Los_Angeles)（UTC，带标签，当屏幕无时区时）；JSON 输出保持 RFC 3339 时间点。人工排程表以屏幕时区标记，且当任何列出的屏幕播放的不是其默认播放列表时，screen list --human 添加 ASSIGNED 列。
| 问题代码 | 退出 | 含义 |
|---|---|---|
invalid_request | 8 | 屏幕无默认播放列表分配（next 为 screen assign），或无法分配命名播放列表。 |
screen_archived | 5 | 归档屏幕拒绝排程和接管。next 是 screen unarchive。 |
revision_conflict | 6 | --expect-rev 版本已过时。 |
playlist_format_mismatch | 5 | 播放列表的格式与屏幕不匹配：视频墙播放列表用在视频墙形状不同的屏幕上，或条带条目（covers header、footer 或 side）无法布置在该屏幕的任何显示器上。 |
feature_not_in_plan | 8 | 计划不含新条目所用的功能：新增 paused 条目需要排程变更控制，displays 指定第 2 个及之后的显示器需要视频墙。定价列出了各个计划。 |
rate_limited | 7 | 排程和接管写入共享每分钟限制：每个组织 600 次，每个屏幕 20 次，每个IP 60 次。请等待 retry_after_seconds。 |
使用一个屏幕 ID，这些命令返回更新后的屏幕，--expect-rev 保护其版本。多个 ID、--tag TAG 或 --folder ID（该屏幕文件夹及其内部每个文件夹中的所有活动屏幕）作为一个 fleet 请求 运行，带有 fleet 信封和退出规则；每个屏幕单独失败，项目预算用尽时 CLI 会自动暂停和恢复。在 Propose 权限下，或在要求审核代理更改的项目中，对单个屏幕或整个 fleet 选择的写入会返回 pending_review：命令成功（退出码 0），带有 data.review 和 pending_review 警告，data.next 为 screenrig reviews show ID，在有人批准之前屏幕上不会有任何变化，因此不要重复写入。--note 会向审阅此变更的人说明原因；参见审核。在受保护文件夹中的屏幕上，写入在任何访问级别下都要等待第二位审批人。
screen schedule show#
显示屏幕的播放列表排程及当前选择的播放列表。
screen schedule show <id>| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | scr_ 屏幕 ID。 |
screenrig screen schedule show scr_CAFEdata 包含 entries（屏幕没有排程时为空）、updated_at 和 effective_playlist。JSON 输出可直接返回至 screen schedule set --file。
screen schedule set#
替换屏幕或车队上的播放列表排程。
screen schedule set (<id>... | --tag TAG | --folder ID) --file FILE [--expect-rev REVISION] [--note TEXT]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id>... | string | <id>、--tag 或 --folder 之一 | 无 | 一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。 |
--tag TAG | string | <id>、--tag 或 --folder 之一 | 无 | 每个带此标签的活动屏幕。 |
--folder ID | string | <id>、--tag 或 --folder 之一 | 无 | 此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。 |
--file FILE | 路径 | 是 | 无 | 排程文档，或 - 表示标准输入。也接受 screen schedule show 输出的 JSON。 |
--expect-rev REVISION | string | 否 | 无 | 仅一个屏幕 ID。可选的修订前提。 |
--note TEXT | string | 否 | 无 | 给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。 |
screenrig screen schedule set scr_CAFE --file dayparts.json
screenrig screen schedule set --tag Cafe --file dayparts.json
screenrig screen schedule set --folder sfd_01EXAMPLEFOLDER000000000 --file dayparts.json每个计划命名的播放列表都作为分配进行验证，屏幕需要分配的默认播放列表。条目的时间按屏幕自己的时区读取。没有条目生效时，播放分配的播放列表。如果计划播放列表之后无法显示，则跳过其条目并记录screen.playlist_unavailable。
screen schedule clear#
从屏幕或设备组移除播放列表排程。
screen schedule clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION] [--note TEXT]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id>... | string | <id>、--tag 或 --folder 之一 | 无 | 一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。 |
--tag TAG | string | <id>、--tag 或 --folder 之一 | 无 | 每个带此标签的活动屏幕。 |
--folder ID | string | <id>、--tag 或 --folder 之一 | 无 | 此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。 |
--expect-rev REVISION | string | 否 | 无 | 仅一个屏幕 ID。可选的修订前提。 |
--note TEXT | string | 否 | 无 | 给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。 |
screenrig screen schedule clear --tag Cafe之后播放的是接管，否则是仍然生效的活动，再否则是已分配的播放列表。没有排程的屏幕会原样应答。
screen schedule preview#
显示替换屏幕播放列表排程会带来哪些变化，但不执行。
screen schedule preview <id> --file FILE [--calendar-from INSTANT] [--calendar-to INSTANT]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | scr_ 屏幕 ID。 |
--file FILE | 路径 | 是 | 无 | screen schedule set 所接受的排程文档，或用 - 表示 stdin。也接受 screen schedule show 输出的 JSON。 |
--calendar-from INSTANT | string | 否 | 现在 | 日历从此带时区的时刻开始，例如 2026-12-01T00:00:00Z。 |
--calendar-to INSTANT | string | 否 | 开始后一周 | 日历在此带时区的时刻结束，最晚为开始后 93 天。 |
screenrig screen schedule preview scr_LOBBY --file dayparts.json
screenrig screen schedule preview scr_LOBBY --file dayparts.json --calendar-from 2026-12-01T00:00:00Z --calendar-to 2027-01-01T00:00:00Z不会写入任何内容。条目的检查方式与 screen schedule set 相同，因此预览会拒绝 set 所拒绝的内容。data.gained 和 data.lost 各为 {count, screen_ids}，说明屏幕会获得还是失去其排程的层级；带有 "paused": true 的条目不在任何屏幕上，因此发布它会增加该条目。data.calendar.before 和 data.calendar.after 是屏幕现状的日历，以及 --calendar-from 至 --calendar-to 之间更改后的日历。
screen schedule revisions#
按从新到旧列出屏幕播放列表排程的修订。
screen schedule revisions <id> [--after CURSOR]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | scr_ 屏幕 ID。 |
--after CURSOR | string | 否 | 第一页 | 从上一页的 data.next_cursor 继续。 |
screenrig screen schedule revisions scr_LOBBY
screenrig screen schedule revisions scr_LOBBY --after CURSORdata.items 最多包含 50 个修订，每个包含 revision（写入时屏幕的修订号，因此屏幕以其他方式变化处的编号有间隔）、created_at、change、current、已知时的 author，以及 entries（该次写入后的完整排程；none 表示屏幕没有排程）。change 为 edited（一次 set、一次 clear 或一次排程导入）、restored（restored_from 所指较早修订的副本）或 baseline（屏幕在其历史开始时持有的排程）。只要 data.next_cursor 是字符串，就还有更早的修订：将 --after 设为该值，再次运行命令。修订随屏幕清除而删除。只读权限即可。
screen schedule restore#
通过向前复制，把较早修订的排程放回屏幕。
screen schedule restore <id> --revision N [--expect-rev REVISION] [--note TEXT]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | scr_ 屏幕 ID。 |
--revision N | integer | 是 | 无 | 要向前复制的修订，按 screen schedule revisions 的编号。 |
--expect-rev REVISION | string | 否 | 刚读取的修订 | 要求当前屏幕修订为此值，而不是 N。省略时，CLI 会在写入前读取屏幕并发送该修订；期间若有更改，则为 revision_conflict（退出码 6）。 |
--note TEXT | string | 否 | 无 | 给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。 |
screenrig screen schedule restore scr_LOBBY --revision 4
screenrig screen schedule restore scr_LOBBY --revision 4 --expect-rev 9修订 N 的条目成为屏幕的排程，这与用这些条目执行 screen schedule set（若该修订没有条目则为 screen schedule clear）是同一次写入，按现在的规则检查：此后被删除的播放列表会导致拒绝。在 Propose 权限下，或在要求审核代理更改的项目中，恢复会像 set 一样等待有人批准，批准前屏幕上不会有任何变化。较早的修订保持原样。
screen takeover#
在屏幕或屏幕组上提前显示一个播放列表，优先于活动、计划和分配。
screen takeover [set] (<id>... | --tag TAG | --folder ID) --playlist-id ID [--until TIME | --for DURATION] [--reason TEXT] [--expect-rev REVISION] [--note TEXT]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id>... | string | <id>、--tag 或 --folder 之一 | 无 | 一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。 |
--tag TAG | string | <id>、--tag 或 --folder 之一 | 无 | 每个带此标签的活动屏幕。 |
--folder ID | string | <id>、--tag 或 --folder 之一 | 无 | 此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。 |
--playlist-id ID | string | 是 | 无 | 要显示的 pl_ 播放列表。 |
--until TIME | string | 否 | 保持直到清除 | 严格 RFC 3339 时间点，含秒和偏移，格式为 YYYY-MM-DDTHH:MM:SSZ 或 YYYY-MM-DDTHH:MM:SS-07:00，发送时归一化为 UTC；严格未来且最多提前 7 天。或 none 保持至 screen takeover clear。 |
--for DURATION | string | 否 | 保持直到清除 | 30m，2h，或 3d，最多 6d23h59m，从此计算机时钟转换为 until。本地拒绝 7d；使用 --until 获取完整 7 天。不适用于 --until。 |
--reason TEXT | string | 否 | 无 | 关于接管及其事件的操作员备注。最多120个字符，且无控制字符。 |
--expect-rev REVISION | string | 否 | 无 | 仅一个屏幕 ID。可选的修订前提。 |
--note TEXT | string | 否 | 无 | 给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。 |
screenrig screen takeover scr_LOBBY --playlist-id pl_DRILL --for 30m --reason "Fire drill"
screenrig screen takeover --tag Lobby --playlist-id pl_LAUNCH --for 2h
screenrig screen takeover --folder sfd_01EXAMPLEFOLDER000000000 --playlist-id pl_LAUNCH --for 2h
screenrig screen takeover scr_A scr_B --playlist-id pl_NOTICE --until nonescreen takeover ID 是 screen takeover set ID 的缩写。新的接管会替换之前的接管，但接管生效期间再次发布的同一播放列表除外：若未带 --reason，或所带的与原来相同，则保留该接管，只改变其结束时间。结束时，屏幕会自动返回生效的活动、其计划或分配的播放列表。无法显示播放列表的接管会结束。模糊失败后的 --for 重跑会重新计算结束时间，并作为新请求发送。
screen takeover clear#
结束屏幕或设备群的接管。
screen takeover clear (<id>... | --tag TAG | --folder ID) [--expect-rev REVISION] [--note TEXT]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id>... | string | <id>、--tag 或 --folder 之一 | 无 | 一个或多个 scr_ 屏幕 ID。多个 ID 作为一个舰队请求运行。 |
--tag TAG | string | <id>、--tag 或 --folder 之一 | 无 | 每个带此标签的活动屏幕。 |
--folder ID | string | <id>、--tag 或 --folder 之一 | 无 | 此 sfd_ 屏幕文件夹及其内部文件夹中的每个活动屏幕。 |
--expect-rev REVISION | string | 否 | 无 | 仅一个屏幕 ID。可选的修订前提。 |
--note TEXT | string | 否 | 无 | 给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。 |
screenrig screen takeover clear --tag Lobby之后播放的是仍然生效的活动，否则是排程，再否则是已分配的播放列表。没有接管的屏幕会原样应答。
排程文件
排程列出 1 到 32 条条目，按优先级排序；第一个生效的条目获胜。条目指定一个 playlist_id，并至少设置层级的一条规则：windows、monthly、dates、except、data、interaction、from 或 until，并可选设置 displays、covers、start 和 paused。windows 有 1 到 16 项，均为屏幕时区：days 使用 mon 至 sun，start 和 end 为 HH:MM；全天省略两者。end 在或早于 start 跨午夜，属于起始日。monthly 有 1 到 16 项，dates 和 except 各有 1 到 100 项，同一个 except 日期只能出现一次。服务器会拒绝落在 from 和 until 之外的 except 日期、起点在其之外的 dates 项，以及同时也是 except 日期的 dates 项。可选的 from（含）和 until（不含）为民用分钟，如 2026-12-24T18:00，无偏移；from 早于 until。covers 为 full（默认）、main、header、footer 或 side，displays 列出 1 到 12 个不同的输出，start 为 next_item（默认）或 on_time，与上文层级规则相同。id 由 1 到 64 个字母、数字、- 或 _ 组成，且只能使用一次；省略 id 时视为 entry_N。带有 "paused": true 的条目是草稿：它不在任何屏幕的层级栈中，screen schedule show 会标记它，日历以虚线绘制。不带 paused 重新发送排程即可发布。CLI 发送前检查此格式。早餐、午餐和晚餐时段：
{
"entries": [
{ "id": "breakfast", "playlist_id": "pl_BREAKFAST",
"windows": [{ "days": ["mon", "tue", "wed", "thu", "fri"], "start": "06:00", "end": "11:00" },
{ "days": ["sat", "sun"], "start": "08:00", "end": "12:00" }] },
{ "id": "lunch", "playlist_id": "pl_LUNCH",
"windows": [{ "days": ["mon", "tue", "wed", "thu", "fri"], "start": "11:00", "end": "15:00" }] },
{ "id": "dinner", "playlist_id": "pl_DINNER",
"windows": [{ "days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"], "start": "17:00", "end": "22:00" }] }
]
}有人使用屏幕时播放的菜单，位于跳过某一日期的每月第一个周日早午餐之上：
{
"entries": [
{ "id": "browse", "playlist_id": "pl_MENU", "interaction": { "idle_s": 90 } },
{ "id": "brunch", "playlist_id": "pl_BRUNCH",
"monthly": [{ "nth": 1, "weekday": "sun", "start": "10:00", "end": "14:00" }],
"except": ["2026-12-06"] }
]
}播放列表排程在播放列表间切换；单个播放列表内的页面 visibility 仍在页面间切换。
排程和接管事件
events list 和 events follow 打印 screen.playlist_switched（playlist_id、previous_playlist_id、source、entry_id、until）、screen.takeover_started（playlist_id、until，其中 none 表示保留直至清除，以及 reason）、screen.takeover_updated（playlist_id、until、previous_until 和 reason，其中 none 表示保留直至清除：同一接管被赋予新的结束时间）、screen.takeover_ended（playlist_id、有结束时间时的 until，以及 reason expired、cleared、replaced、playlist_deleted 或 playlist_unavailable），以及警告 screen.playlist_unavailable（playlist_id、code playlist_deleted 或 playlist_unavailable，还有指向该播放列表的 entry_ids、campaign_ids 或 folder_id）。
只要有屏幕（包括归档屏幕）已分配该播放列表、被计划条目命名、被接管持有或处于生效状态，或有活动或屏幕文件夹的默认播放列表指定了它，删除该播放列表就会失败，错误代码为 resource_conflict（退出码 5）。next 指向 screen list。
排程导入
schedule import 读取一张排程行表（屏幕、文件、开始、结束），对照项目检查每一行，预览它生成的层级和对日历的影响，使用 --commit 时要么全部应用，要么一项都不应用。schedule template 保存一张可供起步的表。排程导入说明列、目标、时间和行错误。单个屏幕自己的排程用 screen schedule set 设置，活动则为一个受众安排排程。
预览和提交属于 Premium 及以上计划：不含排程导入的计划返回 feature_not_in_plan（退出码 8），模板对所有计划开放。限定于屏幕文件夹的调用方无法使用预览和提交（outside_screen_scope，退出码 3）。
schedule import#
检查一张排程行表并预览其效果；--commit 会应用它。
schedule import <file> [--name NAME] [--timezone ZONE] [--code-field FIELD] [--commit]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<file> | 路径 | 是 | 无 | .csv（UTF-8）、.xlsx（读取其第一个工作表）或 .json 工作表，或用 - 从标准输入读取 JSON 行、CSV 文本或 XLSX 工作簿。JSON 工作表是行对象数组，或以列名为键的 {"rows": [...]}。最多 5,000 行和 8 MiB。 |
--name NAME | string | 否 | 不含扩展名的文件名 | 导入的名称，1 到 80 个字符。用同一名称再次导入会更新它创建的层级，移除其行已消失的层级，并使相同的工作表保持不变。 |
--timezone ZONE | string | 否 | 每个屏幕自己的时钟 | 当某行没有 timezone 单元格时，该行时间所采用的 IANA 时区，例如 America/New_York。 |
--code-field FIELD | string | 否 | 任意字段 | 仅从此屏幕字段读取目标的屏幕代码，例如 code 或 room_id。 |
--commit | boolean | 否 | 关闭 | 预览有效时应用导入。有行错误时不会写入任何内容。 |
screenrig schedule import schedule.csv
screenrig schedule import schedule.xlsx --name "Spring promos" --timezone America/Los_Angeles
screenrig schedule import schedule.csv --name "Spring promos" --commit
screenrig schedule import rows.json --code-field room_id
screenrig schedule import - --name "Spring promos" --commit不带 --commit 时不会写入任何内容。data 是预览：valid、fingerprint、summary（rows、rows_with_errors、levels、creates、updates、unchanged、removes、screens、playlists）、rows、levels、removals 和 calendar，ignored_columns 列出没有被读取的列，以及 next，即用于提交的命令。内容、时间、优先级和名称一致的行合成一个层级：一个屏幕对应该屏幕自身排程中的一个条目，多个屏幕、一个文件夹或一个标签则是一个共享层级，也就是优先于屏幕自身层级的活动。
有效的工作表以 0 退出。有错误的行以 8 退出，且 data.valid 为 false：data.rows[].errors 会指明每个单元格的列和代码，不写入任何内容，--commit 也不会提交任何内容，行修正后再次运行同一命令即可。
使用 --commit 时，运行会发送预览的 fingerprint，以及由名称和指纹派生的幂等键，因此重新运行被中断的相同命令是安全的。此时 data 为预览加上 data.applied（creates、updates、unchanged、removes、screens、playlists）以及 data.committed true，并且工作表中文件所需的单文件播放列表会先创建。所有行要么全部应用，要么都不应用。项目在预览之后发生更改，或各行的读取结果不同，会返回 schedule_import_stale（退出码 5）：不会写入任何内容，同一命令会重新预览。涉及受保护文件夹中屏幕的提交会被 protected_target（退出码 5）整体拒绝，更新或删除预留活动的提交会返回 reserved_item（退出码 3），除非由可以审批的人提交。预览需要只读权限，--commit 需要管理权限。CLI 无法读取的文件是 usage_error（退出码 2）。
schedule template#
保存一张包含排程导入所读列和三行示例行的工作表。
schedule template [--format csv|xlsx] [--output FILE] [--overwrite]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
--format FORMAT | string | 否 | csv | csv 或 xlsx。 |
--output FILE | 路径 | xlsx 时需要 | 打印 CSV | 将工作表写入此文件。不指定时会打印 CSV，且 data.content 中包含它。 |
--overwrite | boolean | 否 | 关闭 | 当 --output 已存在时替换它。需要 --output。 |
screenrig schedule template
screenrig schedule template --output schedule.csv
screenrig schedule template --format xlsx --output schedule.xlsx --overwrite示例行分别是屏幕代码、屏幕文件夹和标签。使用 --output 时，data 包含 format、output、bytes，以及 next（针对已保存文件的 schedule import 命令）。已存在且非空的 --output 文件会以 usage_error（退出码 2）失败并保持原样，除非传入 --overwrite。每个屏幕和文件填一行，然后运行 schedule import FILE 预览。