screenRIG
登录开始使用

文档

播放列表 CLI 命令

准备、验证、创建、修改、导出和导入播放列表，管理页面、修订和实例，替换应用发布版本。

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

播放列表

播放列表是页面的 JSON 文档。playlist init 从有序输入准备全屏文档。playlist create 和 playlist update 从文件读取该文档；playlist patch、playlist rename 和 playlist page add|replace|remove 更改其中一部分。形状在命令下总结。

playlist init#

从本地媒体文件、准备好的媒体ID、应用发布ID、HTTP 或 HTTPS URL，或粘贴的 iframe 嵌入代码准备可编辑的全屏播放列表。

playlist init <inputs...> --name NAME --output FILE [--overwrite] [--screen-id ID]
              [--target-width PX --target-height PX] [--duration-ms MS] [--fit contain|cover|fill] [--sound]
              [--no-transcode] [--no-progress] [--poll-ms MS]
参数类型必填默认备注
<inputs...>文件、med_ ID、rel_ ID、HTTP 或 HTTPS URL，或粘贴的 <iframe> 嵌入代码是无播放顺序。本地图像、视频和音频文件上传后等待准备，除非有 --no-transcode。现有媒体必须已准备好。音频文件或就绪的音频 med_ ID 按输入顺序成为配乐，而不是页面；至少有一个输入必须是页面。HTTP 和 HTTPS URL 可以包含局域网主机、嵌入的凭据以及 {screen.field.kiosk_id} 等屏幕令牌，按原样保留，不会获取页面。粘贴的嵌入代码会读取其 src。Player 网页应用要求 HTTPS URL 中不包含用户名或密码。
--name NAMEstring是无播放列表显示名称。
--output FILE路径是无写入可编辑的播放列表文档。自动创建父目录。默认独占：已存在的非空文件会以 usage_error 失败（退出码 2），且保持原样。
--overwriteboolean否关闭用根据这些输入构建的文档原子性替换现有输出文件。
--screen-id IDstring否无读取目标屏幕的尺寸和修订版。带视频墙的屏幕会给出墙的画布和对应的 format。
--target-width PX / --target-height PXinteger一起未设置覆盖画布大小。两者都覆盖或都不覆盖。未提供屏幕或屏幕报告未知或多个表面时必需。
--duration-ms MSinteger否8000非视频页面的时长。除非提供此项，应用页面停留 24 小时（86400000）。
--fitstring否containcontain，cover，或 fill 用于图像和视频页面。应用和 iframe 使用 fill。
--soundboolean否关闭播放视频页面的音频。不使用时，所有视频页面都是静音的。带声音的页面在显示期间会暂停配乐。
--no-transcodeboolean否关闭上传的文件字节未改变。
--no-progressboolean否关闭抑制 stderr 上的上传进度。
--poll-ms MSinteger否1000上传轮询间隔。
screenrig playlist init med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --name "Lobby loop" --screen-id scr_01EXAMPLESCREEN00000000 --output lobby.json

准备写入本地文档并可能上传媒体；不创建远程播放列表或分配屏幕。检查文档，然后screen publish。参见准备、发布和编辑播放列表。

data 报告 output、width、height、page_count、soundtrack_tracks、release_ids、media_ids 和 uploads，使用 --screen-id 时还报告 screen_id、screen_revision 和 publish.argv；带视频墙的屏幕会增加 format。设置为不足 60 秒的应用页面会收到 application_page_short 警告。

playlist validate#

在创建或更新前本地验证播放列表文档。无需网络。

playlist validate <file>
参数类型必填默认备注
<file>路径是无播放列表文档，或 - 表示标准输入。
screenrig playlist validate ./lobby-loop.json

错误精确指明 JSON 路径。通过表示本地结构和跨字段语义有效；授权、媒体准备、动态选择器计数、持续时间和远程可用性仍需服务器检查。playlist create、playlist update 和 screen publish 在写入前执行此检查。data 报告 valid、scope 和 server_checks，并带有不会使检查失败的几何 lint 发现项，每项含 page_id、code、id 和 message：motion_overuse、collision、safe_margin 和 adjacent_repeat。在 60 秒内前进的应用页面会收到 application_page_short 警告。要查看页面外观，请发布它并运行 screen screenshot。

playlist create#

根据 JSON 文档、模板或内置的“紧急通知”模板创建播放列表。

playlist create [file] [--from-template ID --name NAME [--set NAME=VALUE...] [--dry-run]] [--starter KEY [--name NAME]] [--format-region REGION --format-orientation ORIENTATION] [--note TEXT]
参数类型必填默认备注
[file]路径否无播放列表文档，或 - 表示标准输入。提供它、--from-template 或 --starter。它包含 name、pages，以及可选的 audio、format 和 fields；任何其他成员都是 usage_error。
--from-template IDstring否无根据此模板（pl_ ID）创建播放列表：使用其当前页面并填入 --set 的值，与任何播放列表一样接受检查。
--name NAMEstring配合 --from-template无新播放列表的名称。--dry-run 不需要它，--starter 可选接受它。
--set NAME=VALUEstring否无与 --from-template 搭配使用：字段的值；媒体字段则为就绪图片或视频的 ID。可重复使用。NAME 是由 1 到 32 个小写字母、数字或下划线组成的字段名，只能给出一次。
--dry-runboolean否关闭与 --from-template 搭配使用：检查值并报告页数，但不创建任何内容。
--starter KEYstring否无添加内置模板：urgent-notice，包含标题和消息，适用于快速公告。
--format-region REGIONstring否无header、footer 或 side：把播放列表变成沿该边缘绘制在页面之上的条带，并替换文件中的 format。请与 --format-orientation 一起给出。参见条带。
--format-orientation ORIENTATIONstring配合 --format-region无landscape 或 portrait：条带所针对显示器的方向，以观看者看到的方向为准。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig playlist create ./lobby-loop.json
screenrig playlist create --from-template pl_01EXAMPLETEMPLATE00000 --name "Monday notice" --set headline="Open late"

信封中的 data.id 是 screen assign 所接受的 pl_ ID。当更改等待审阅时，data 为 {status: pending_review, review, playlist, next}：播放列表已存在且 approved_revision: 0，在有人批准前任何屏幕都无法显示它（playlist_not_approved）；next 为 screenrig reviews show ID。模板是声明了 fields 的播放列表，不会显示在屏幕上（playlist_is_template）；由它创建的播放列表是普通播放列表，可分配、排程和修订。

playlist update#

替换播放列表文档。

playlist update <id> <file> [--format-region REGION --format-orientation ORIENTATION] [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
<file>路径是无替换文档，或 - 表示标准输入。它包含 name、pages，以及可选的 audio、format 和 fields；任何其他成员都是 usage_error。省略 audio 会移除配乐，省略 format 会使播放列表成为普通播放列表，省略的 fields 会保留。
--format-region REGIONstring否无header、footer 或 side：把播放列表变成沿该边缘绘制在页面之上的条带，并替换文件中的 format。请与 --format-orientation 一起给出。参见条带。
--format-orientation ORIENTATIONstring配合 --format-region无landscape 或 portrait：条带所针对显示器的方向，以观看者看到的方向为准。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig playlist update pl_01EXAMPLEPLAYLIST000000 ./lobby-loop.json

playlist show ID --output FILE 写入此结构的文件。如只更改播放列表的一部分，请使用 playlist patch、playlist rename 或 playlist page add|replace|remove。

当更改等待审核时，直播播放列表保持不变，直到有人批准提议。

playlist patch#

仅更改播放列表中提供的顶层成员，其余全部保留。

playlist patch <id> [file] [--name NAME] [--clear-audio] [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
[file]路径否无包含 name、pages、audio、format 和 fields 中任意项的部分 JSON 对象，或用 - 从标准输入读取。提供的 pages、audio 和 format 会替换整个值；数组不合并。audio: null 移除配乐，format: null 移除格式。
--name NAMEstring否未更改设置名称，去除首尾空白后为 1 到 120 个字符，无需发送内容。不能与文件中的 name 一起使用。
--clear-audioboolean否关闭移除配乐，与 audio: null 的效果相同。任何页面都不能保留 audio_cue。不能与文件中的 audio 一起使用。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig playlist patch pl_01EXAMPLEPLAYLIST000000 --name "Lobby loop" --expect-rev 7
screenrig playlist patch pl_01EXAMPLEPLAYLIST000000 changes.json --expect-rev 7

提供文件、--name 或 --clear-audio。仅更改名称不会再次检查现有内容。提供的 pages 和 audio 由服务器一并检查。区域 format 为 {"region": "header", "orientation": "landscape"}；参见 条带。在提议访问权限下，或在要求审核智能体更改的项目中，该更改会像 playlist update 一样等待，并返回 pending_review。

playlist rename#

更改播放列表的名称，无需发送其内容。

playlist rename <id> --name NAME [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--name NAMEstring是无新名称，去除首尾空白后为 1 到 120 个字符。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig playlist rename pl_01EXAMPLEPLAYLIST000000 --name "Lobby loop" --expect-rev 7

playlist patch 的仅名称形式：页面、配乐和注释保持不变，也不会再次检查现有内容。提议的重命名与其他任何更改一样，等待人员批准。

playlist page add#

向播放列表添加一个页面，无需发送其他页面。

playlist page add <playlist-id> (--file PAGE.json | --media MED_ID) [--seconds N] [--fit contain|cover] [--sound]
                  [--from WHEN] [--until WHEN] [--before PAGE_ID] [--page-id ID]
                  [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<playlist-id>string是无pl_ 播放列表 ID。
--file PAGE.json路径--file、--media 中恰好一个无按原样添加的页面对象，或用 - 从标准输入读取。--seconds 和 --fit 不适用于它。
--media MED_IDstring--file、--media 中恰好一个无一个就绪的图片或视频。页面在播放列表的画布上全画布显示它（视频墙使用墙的画布，否则使用第一个普通页面的画布），使用第一个普通页面的过渡效果，除非你指定，否则没有日期。图片在 --seconds 后切换；视频静音播放至结束，除非使用 --sound。
--seconds Ninteger否10图片显示的时长，1 到 86400。
--fitstring否containcontain 或 cover。
--soundboolean否关闭播放视频的音频。仅限视频；该页面在显示期间会暂停配乐，且不能携带 audio_cue。不能与 --file 同用，因为其页面自带 muted。
--from WHENstring否无页面首次显示的时间：YYYY-MM-DDTHH:MM，或用 YYYY-MM-DD 表示 00:00，按每个屏幕的时区计算。
--until WHENstring否无页面显示的结束时间，不含该时刻：YYYY-MM-DDTHH:MM，或用 YYYY-MM-DD 表示当天结束。
--before PAGE_IDstring否在末尾将该页面放在此页面之前。
--page-id IDstring否up- 加八个小写字母或数字新页面的 ID：一个字母，后跟字母、数字、- 或 _，最多 64 个字符。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --media med_01EXAMPLEIMAGE0000000000 --from 2026-12-01 --until 2026-12-24
screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --media med_01EXAMPLEVIDEO0000000000 --before up-ab12cd34 --note "Winter menu"
screenrig playlist page add pl_01EXAMPLEPLAYLIST000000 --file page.json --page-id welcome

页面从 --from 起显示，直到 --until（不含）。已结束的页面会保留，直到有人移除它们。返回更新后的播放列表。

在提议访问权限下，在要求审核智能体更改的项目中，或作为更改需经审核的上传者成员，该更改会返回 pending_review（ok: true，退出码 0）。同一提议者之后对同一播放列表的页面更改，在审核等待期间会并入该审核，因此连续的上传不会相互取代。尚无人批准的播放列表返回 playlist_not_approved。上传者只能将其文件夹中的媒体页面添加到自己的播放列表；其他任何情况均为 outside_upload_scope，其 upload_scope 列出可使用的内容。参见 上传者。

playlist page replace#

替换播放列表的一个页面，保留其位置和 ID。

playlist page replace <playlist-id> <page-id> [--file PAGE.json | --media MED_ID] [--seconds N] [--fit contain|cover]
                      [--sound] [--from WHEN] [--until WHEN | --always] [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<playlist-id>string是无pl_ 播放列表 ID。
<page-id>string是无要替换的页面。
--file PAGE.json路径否无完整的新页面，或用 - 从标准输入读取。其 id 必须为 <page-id> 或省略。不能与 --media 一起使用。
--media MED_IDstring否无替换页面的媒体；其余一切（包括日期）保持存储时的样子。以图片替换图片时保留画布、适配方式、秒数和日期，以视频替换视频时同样如此。以图片替换视频或反过来，则在播放列表的画布上重建为媒体页面，并保留 ID、过渡效果和日期。需要只有单个原语的页面。
--seconds Ninteger否未更改图片显示的时长，1 到 86400。不能与 --file 一起使用。
--fitstring否未更改contain 或 cover。不能与 --file 一起使用。
--soundboolean否关闭播放页面中视频的音频，可单独使用，也可与 --media 一起使用。仅限只有一个视频图元的页面；不使用时，替换会保留页面原有的声音设置。不能与 --file 同用。
--from WHENstring否未更改页面首次显示的时间：YYYY-MM-DDTHH:MM，或用 YYYY-MM-DD 表示 00:00，按每个屏幕的时区计算。单独更改该边界。
--until WHENstring否未更改页面显示的结束时间，不含该时刻：YYYY-MM-DDTHH:MM，或用 YYYY-MM-DD 表示当天结束。单独更改该边界。
--alwaysboolean否关闭移除页面的日期，即 from 和 until。项目设置的关闭开关、每周时间窗或数据条件保持不变。不能与 --from 或 --until 一起使用。
--expect-rev REVISIONstring否无可选修订前提条件。除非你指定，否则由已存储页面派生的页面以其读取时的修订为前提。过期值为 revision_conflict。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --media med_01EXAMPLEIMAGE0000000000
screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --until 2026-12-31
screenrig playlist page replace pl_01EXAMPLEPLAYLIST000000 up-ab12cd34 --always

至少提供 --file、--media、--sound、--from、--until 或 --always 之一。日期标志也适用于有多个原语的页面；更改媒体、适配方式或秒数需要只有单个原语的页面，或在 --file 中提供整个页面。未知的页面 ID 会被拒绝。审核和上传者规则与 playlist page add 相同；上传者只能替换其文件夹中的媒体页面。

playlist page remove#

从播放列表中移除一个页面。

playlist page remove <playlist-id> <page-id> [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<playlist-id>string是无pl_ 播放列表 ID。
<page-id>string是无要移除的页面。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
--note TEXTstring否无给审核变更者的备注：纯文本，最多 280 字符。变更即时生效时忽略此备注。
screenrig playlist page remove pl_01EXAMPLEPLAYLIST000000 up-ab12cd34

播放列表须保留 1 到 100 个页面，以及一个没有 visibility 的普通页面，因此移除最后一个无日期页面会返回 invalid_request。未知页面返回 not_found。审核和上传者规则与 playlist page add 相同。

playlist show#

读取一个播放列表，包括其当前版本，或将其写成可编辑文档。

playlist show <id> [--output FILE [--overwrite]] [--editable]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--output FILE路径否无将可编辑文档写入 FILE 并报告其路径、playlist_id 和 revision。该文件按原样即可用于 playlist update。自动创建父目录。默认独占。优先于 --editable。
--overwriteboolean否关闭原子性替换现有的 --output 文件。中断运行留下的空文件无需此标志即可被替换。
--editableboolean否关闭在信封中以 data.document、data.playlist_id 和 data.revision 返回可编辑文档及其修订。
screenrig playlist show pl_01EXAMPLEPLAYLIST000000
screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --output playlist.json
screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --editable

纯 show 是检查响应。返回实时版本。approved_revision 对于无人批准的播放列表为 0，等待变更时 approval 显示开放审核，reviews show ID 返回提案。当有未关闭的备注涉及该播放列表时，警告 notes_about_resource 会统计它们并指明 screenrig notes --about ID，--human 最多列出五条。

playlist list#

列出项目的播放列表。

playlist list [--templates] [--library]
参数类型必填默认备注
--templatesboolean否关闭仅模板：声明了字段的播放列表。
--libraryboolean否关闭改为以只读方式列出组织媒体库的播放列表：可将其分配给屏幕、日程和堆叠，或用 playlist create --from-template 复制一个；只能在媒体库项目中修改它们。
screenrig playlist list --templates
screenrig playlist list --library

playlist fields#

显示模板的字段或副本的值，或更改值并使副本保持最新。

playlist fields <id> [--set NAME=VALUE...] [--clear NAME...] [--refresh] [--expect-rev REVISION] [--note TEXT]
参数类型必填默认备注
<id>string是无模板或由模板创建的播放列表的 pl_ ID。
--set NAME=VALUEstring否无设置字段的值。可重复使用；NAME 是由 1 到 32 个小写字母、数字或下划线组成的字段名，只能给出一次。
--clear NAMEstring否无清除可选字段的值。可重复使用。
--refreshboolean否关闭无论值是否更改，都根据模板的当前修订版重新生成页面。
--expect-rev REVISIONstring否无可选：要求此资源修订版。
--note TEXTstring否无给审阅此变更的人的备注。
screenrig playlist fields pl_01EXAMPLECOPY00000000 --set headline="Closed today"

不带选项时，显示模板的字段及由其创建的播放列表数量，或副本的值、其所基于的模板修订版以及模板是否有更新的修订版。data.kind 是 template 或 instance：模板报告 fields 和 instances，副本报告 template_id、template_revision、template_current_revision、outdated 和 values。每次更改以及单独使用 --refresh，都会根据模板的当前修订版重新生成副本的页面，对模板所做的品牌变更正是这样传到现有副本的；不会自动推送。值的检查方式与创建时相同。在 Propose 访问下，更改会成为审阅。

playlist instances#

列出由模板创建的播放列表及各自所基于的模板修订版。

playlist instances <id>
参数类型必填默认备注
<id>string是无模板的 pl_ ID。
screenrig playlist instances pl_01EXAMPLETEMPLATE00000

outdated 表示由模板的较旧修订版创建的播放列表；playlist fields ID --refresh 可使其保持最新。

playlist revisions#

列出播放列表的各个版本，最新的在前。

playlist revisions <id> [--after CURSOR]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--after CURSORstring否无上一页的 data.next_cursor。
screenrig playlist revisions pl_01EXAMPLEPLAYLIST000000

data.items 中的每个版本都说明由什么产生（created、edited、promoted（以 restored_from 给出其所复制的版本），或 baseline，即播放列表在其历史开始时所处的版本）、由谁产生、何时产生、名称、包含多少页面以及是否为 current。每页最多包含 50 个版本；当 data.next_cursor 为字符串时，仍有更早的版本，null 标记最后一页。版本与播放列表一样长期保留。

playlist revision show#

读取一个版本以及该版本时的播放列表。

playlist revision show <id> --revision N
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--revision Ninteger是无要读取的版本。
screenrig playlist revision show pl_01EXAMPLEPLAYLIST000000 --revision 3

data.revision 包含 playlist revisions 列出的字段，data.playlist 为该播放列表当时的状态：名称、页面、配乐和格式，其中 revision 设为此修订。播放列表从未有过的修订，或早于其历史开始的修订，为 not_found。

playlist promote#

将较早的版本复制为新版本，使其重新成为当前版本。

playlist promote <id> --revision N --expect-rev CURRENT
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--revision Ninteger是无要复制的版本。
--expect-rev CURRENTstring是无播放列表的当前版本（playlist show）。过期值为 revision_conflict：重新读取播放列表后重试。
screenrig playlist promote pl_01EXAMPLEPLAYLIST000000 --revision 3 --expect-rev 9

该版本的页面、配乐和格式成为下一个版本。名称保持不变，较早的版本仍保留在列表中，所有显示该播放列表的屏幕都会更新；播放列表写入后命令即返回，不等待播放器。页面会像任何写入一样重新解析：选择器匹配当前的媒体，而该版本所用的媒体或应用若已不存在或未就绪，提升会被拒绝，并返回写入时会得到的同一问题。提升需要可直接发布的凭据；变更需等待审核的凭据会得到 forbidden，尚无人批准的播放列表为 playlist_not_approved。内容已是当前内容的版本不会产生任何变化。提升属于 Premium 功能：没有该功能的套餐会返回 feature_not_in_plan（退出码 8），而 playlist revisions 和 playlist revision show 在每个套餐中都可用。

playlist delete#

删除一个播放列表。

playlist delete <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--expect-rev REVISIONstring否无可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。
screenrig playlist delete pl_01EXAMPLEPLAYLIST000000

只要有屏幕（含已归档或仍在配对的屏幕）将其作为默认播放列表、放在其播放列表排程中或作为其接管，只要有屏幕文件夹将其作为默认，或只要有活动正在播放它，该播放列表就不会被删除：返回 resource_conflict（退出码 5）。请先更改这些设置。

playlist export#

将图像和视频文件、背景音轨音频以及 iframe URL 导出为可移植的播放列表包。

playlist export <id> --output DIRECTORY [--skip-applications]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--output DIRECTORY路径是无目标目录。该目录必须不存在；捆绑包通过临时同级目录写入后重命名到位。
--skip-applicationsboolean否关闭移除应用程序基元，以及空页面或由应用程序控制的页面。必须至少保留一个页面。结果会列出已跳过的基元和页面 ID。
screenrig playlist export pl_01EXAMPLEPLAYLIST000000 --output ./lobby-bundle

包中包含清单、播放列表文档，以及按内容寻址的图像、视频和背景音轨音频文件。它携带 name、audio 和 pages；format 和模板的 fields 不会保留。动态选择器 all、tag 和 folder 会固定为确切的 ID，iframe URL 会保留，注释会被排除。

卡片、流和 adslot 页面会在下载媒体前阻止导出。应用程序默认也会阻止导出；--skip-applications 会移除应用程序基元，以及空页面或由应用程序控制的页面，并报告已跳过的基元和页面 ID。必须至少保留一个页面。使用此标志时，卡片、流和 adslot 页面仍会阻止导出。

如需保留卡片和应用程序引用的可编辑文档，请使用 screenrig playlist show pl_01EXAMPLEPLAYLIST000000 --output playlist.json。该文档使用同一项目中的现有资源。

playlist import#

从捆绑目录创建播放列表，或从中更新现有播放列表。

playlist import <directory> [--name NAME] [--update ID [--expect-rev REVISION]] [--poll-ms MS] [--note TEXT]
参数类型必填默认备注
<directory>路径是无由 playlist export 写入的捆绑目录。
--name NAMEstring否包的播放列表名称1 到 120 个字符。为新播放列表命名，或重命名 --update 所替换的播放列表。
--update IDstring否创建了新的播放列表更新此 pl_ 播放列表而非创建新列表。影响所有分配给它的屏幕。可选接受 --expect-rev。
--expect-rev REVISIONstring否无与 --update 搭配使用：目标播放列表的当前修订版本。
--poll-ms MSinteger否1000媒体就绪期间轮询上传的间隔。
--note TEXTstring否无变更等待审核时，给审核变更人员的备注，最多 280 字符。
screenrig playlist import ./lobby-bundle
screenrig playlist import ./lobby-bundle --name "Lobby loop (copy)"
screenrig playlist import ./lobby-bundle --update pl_01EXAMPLEPLAYLIST000000

播放列表显示名称可能重复。导入时即使名称相同也会创建独立播放列表；使用带 ID 的 --update 替换现有播放列表。

导入在触及项目之前本地验证整个包：清单、文档、路径、媒体类型、长度和哈希。现有媒体在文件名、媒体类型、字节长度、哈希和标签完全匹配时重用；其余无转换上传，且仅在所有对象准备好后写入播放列表。data 报告 mode（create 或 update）、source_playlist_id、playlist、directory 以及带有 total、reused 和 uploaded 的 media。

在提议访问权限下，或在要求审核智能体更改的项目中，媒体仍会上传，播放列表写入则成为审核：data.status 为 pending_review，data.review 指明该审核，data.next 为 screenrig reviews show ID。在有人批准之前，屏幕上不会有任何变化。

导入绝不删除或修剪远程媒体。如果上传开始后后续步骤失败，错误会列出确认准备好的对象，并说明播放列表写入是否开始。重试同一包会重用这些对象。

playlist replace-release#

预览或应用播放列表中的一次应用发布替换，含其涉及的屏幕。

playlist replace-release <id> --page PAGE_ID --primitive PRIMITIVE_ID --release-id REL_ID
                         [--apply [--expect-rev REVISION] [--expect-impact TOKEN] [--note TEXT]]
参数类型必填默认备注
<id>string是无pl_ 播放列表 ID。
--page PAGE_IDstring是无包含该应用的页面的确切 ID。
--primitive PRIMITIVE_IDstring是无该页面上 application 原语的确切 ID。
--release-id REL_IDstring是无新的不可变 rel_ 发布，来自 app update 的 data.application.release_id。
--applyboolean否关闭写入替换内容。没有它时，命令只是只读预览。
--expect-rev REVISIONstring否无与 --apply 搭配使用：来自预览的播放列表修订。当前修订不同时为 revision_conflict，服务器会原子性地检查。
--expect-impact TOKENstring否无与 --apply 搭配使用：来自预览的 data.impact。如果替换内容或受影响的屏幕此后已变化，写入为 resource_conflict：请重新预览。
--note TEXTstring否无使用 --apply：变更等待审核时，给审核变更人员的备注。
screenrig playlist replace-release pl_01EXAMPLEPLAYLIST000000 --page board-page --primitive board --release-id rel_NEW
screenrig playlist replace-release pl_01EXAMPLEPLAYLIST000000 --page board-page --primitive board --release-id rel_NEW --apply

预览会列出已启用、待配对和已归档的屏幕，只要其默认分配、已存储的排程条目（包括已暂停和未来的条目）、接管或当前生效的播放列表（包括活动和继承的文件夹播放）引用了该播放列表。data 携带 previous_release_id、release_id、revision、affected_screens（每项含 id、label、state 和 revision）、impact 和 applied。直接的 --apply 会跳过屏幕检查，因此除非提供 --expect-impact，否则省略 affected_screens。已固定的发布会成功且不写入。审核中，--apply 提议新的固定。参见 替换一个应用版本。

播放列表文档

播放列表由 name（1 到 120 个字符）加 pages（1 到 100）组成，另有可选的 audio 配乐和可选的 format。每个页面带有 id、canvas、transition、advance、可选的 visibility、可选的 audio_cue 以及 primitives（1 到 24）。页面、原语和曲目 ID 是一个字母，后跟最多 63 个字母、数字、_ 或 -；页面 ID 在播放列表内唯一，原语 ID 在其页面内唯一。canvas 接受 1 到 1,000,000 的 width 和 height、一个 background 和可选的 viewport_fit：参见 页面背景与动画。

format 使播放列表成为视频墙（{displays, arrangement, orientation}，其中 columns 用于 grid）或条带（{region, orientation}）。视频墙包含 2 到 12 个 1920 x 1080 的显示器（竖屏为 1080 x 1920），每个普通页面都使用墙的画布，原语的 displays 指明其覆盖的方块，取代 rect。参见 视频墙 和 条带。广告位页面（{id, type: "adslot", adslot_id}，可选带 visibility）不包含画布或原语；一个播放列表最多包含 16 个，并保留一个不带 visibility 的普通页面。

模板会在文档中添加 fields，[{name, label, type, required, max_length?}] 的 type 为 text、media 或 url，并可将任何图元标记为 locked: true。页面读取字段的方式：在卡片的 params 中为 {field.NAME}（文本和地址字段），作为图片或视频的 selector.media_id（媒体字段），或作为 iframe 的整个 src（地址字段）。每个标记都必须指向类型正确的已声明字段，每个字段都必须被读取，已锁定的图元不读取任何字段；playlist validate 会离线检查这些。只有所有者或可以审批的成员才能更改已锁定的图元（primitive_locked）。模板最多声明 16 个字段：name 为 1 到 32 个小写字母、数字或下划线，label 最多 60 个字符，文本字段的 max_length（默认 200）最多 2000。留空的可选媒体或地址字段会省略读取它的图元。声明 fields 和锁定基元属于播放列表模板，是 Premium 功能。2 或 3 台显示器的视频墙 format 需要 Plus，4 到 12 台显示器的需要 Enterprise。没有该功能的套餐会返回 feature_not_in_plan 和 required_plan，而保留播放列表已有内容的写入仍可进行。根据模板创建副本在所有计划中均可使用。

六种基元是 image、上传的 video、实时 stream、网页 iframe 和 application，以及 card。文案和装饰不是传输类型：对实时文字请放置 card，或上传您的智能体制作的成品静态图片并将其作为图片放置。

流接收一个或两个有序源，协议唯一，备用媒体为同项目的已准备图像 fallback_media_id。每页及基于时长的前进最多用一个流。HLS 使用公共 HTTPS URL；Android 和 Qt 播放器直接连接 RTSP 摄像头源，包括登录信息。请参阅摄像头传输详情，了解各播放器能打开的 URL 格式；Android 和 Qt 可选的直接 UDP/MPEG-TS 多播使用 239/8 内的 IPv4 组和端口。源可以只给出 url，由 URL 方案决定协议。其他播放器选择 HLS 备选或显示备用。流字节不缓存重播。音频默认静音；将 muted 设为 false 即可播放，规则同下文视频的声音。播放列表包导入和导出不支持流。

{
  "id": "live",
  "primitive": "stream",
  "sources": [
    {
      "protocol": "udp-mpegts",
      "group": "239.10.0.1",
      "port": 5000
    },
    {
      "protocol": "hls",
      "url": "https://example.com/live.m3u8"
    }
  ],
  "fallback_media_id": "med_fallback",
  "muted": true,
  "rect": {
    "x": 0,
    "y": 0,
    "width": 1920,
    "height": 1080
  },
  "layer": 0,
  "content_fit": "contain"
}

在带有 advance: {"mode":"duration","after_ms":30000} 的页面上使用此原语。替换示例源和备用 ID。播放器要求和传输设置。

每个原语都是扁平的：id、primitive、该原语自身字段，然后是rect、layer、content_fit，以及可选的enter和motion。没有嵌套的内容对象。rect为画布单位的x、y、width和height，layer为 0 到 1024 的整数。rect可以延伸到画布之外作为出血：播放器会将内容适配到整个rect，然后裁剪到画布，因此请使用 content_fit cover 或 fill 来填满可见画布。卡片由layout放置，只有free才需要rect；在视频墙播放列表上，displays取代rect。

图片和视频原语需要 selector。selector.by 为：id 并带有一个就绪的 media_id，且 one_at_a_time 为 false；ids 带有 1 到 1,024 个唯一的就绪 media_ids；all 表示该原语的每个就绪对象；tag 匹配 ^[A-Za-z0-9]{1,32}$；或 folder 带有现有 mfd_ 媒体文件夹的 folder_id，它直接播放文件夹内的就绪文件，不含任何子文件夹。不要在原语本身上放置 media_id，也不要发送服务器解析的项目。application 原语固定一个 release_id，iframe 原语接受 src 和一个 1 到 200 个字符的 title，因此这两者都不接受选择器。src 是屏幕可以访问的任何 http 或 https 页面，包括局域网页面或需要登录的页面；YouTube 链接存储为其自动播放的嵌入形式。src，以及 iframe 的可选 fallback_src，可携带屏幕令牌，例如 {screen.field.kiosk_id}，application 原语可携带使用相同令牌的 params，因此一个播放列表可为每个屏幕提供各自的页面。Android、Amazon Signage Stick、Linux、Raspberry Pi 和 Windows 播放器直接打开该页面。Player 网页应用以及 macOS、Samsung Tizen、LG webOS 和 BrightSign 播放器会将其嵌入框架，因此发送 X-Frame-Options（DENY、SAMEORIGIN 或已废弃的 ALLOW-FROM）的页面，或 Content-Security-Policy frame-ancestors 列表中不含播放器源的页面，在这些播放器上会显示被阻止的框架，而且 Player 网页应用只显示地址中不含登录信息的 https 页面。当发布检测到拒绝嵌入的公共 HTTPS 页面时，写入仍然成功，CLI 会打印服务器的 warnings 条目：代码 iframe_framing_refused、page_id、primitive_id 和 src、拒绝的标头，以及下一步（使用允许从播放器源嵌入的页面，或请其所有者允许该源）。服务器还会向事件日志追加 playlist.iframe_framing_refused 警告，每个拒绝的页面一条，events list 会用 primitive_id 打印。局域网页面、http 页面以及服务器在几秒内无法访问的页面不会被检查。播放器在清单显示于屏幕上后才报告播放列表在播放，因此已验证的发布并不证明 iframe 页面已渲染：请根据警告采取行动，或查看屏幕。两种 Web 原语都需要 content_fit 为 fill，因为二者都没有固有尺寸。

iframe 还接受 reload_s（0 为默认值，从不重新加载；60 到 86400 表示页面在屏幕上时每隔 reload_s 秒重新加载一次 src）、fallback_src（src 无法加载时显示的页面，格式和规则与 src 相同；恢复后的 src 会在下次重新加载时取代它）以及 navigation_allowlist（1 到 64 个形如 [scheme://]host[:port][path] 的主机源，例如 example.com、*.example.com 或 https://example.com/docs/；有列表时，页面的链接、脚本导航和重定向只能到达 src、fallback_src 和匹配的地址；省略则不受限制，空列表会被拒绝）。粘贴的 <iframe> 嵌入代码会读取其 src。Google 幻灯片、文档或表格的共享链接、发布到网络链接或嵌入链接，以及 Microsoft 365 嵌入链接，会为屏幕重建后存储：幻灯片和 PowerPoint 演示文稿循环播放，幻灯片演示文稿按链接自身的延迟前进，并限制在页面时长内（请给页面设置整个演示文稿的时长），文档、表格、Word 和 Excel 每 5 分钟重新加载。要求查看者登录的文件会被拒绝并返回 document_not_shared，其详情指明需要更改的共享设置。参见 显示网页、视频或文档。

advance.mode 是 duration，带有 after_ms；在恰好有一个 YouTube 视频的页面上（播放列表或直播除外），还可以带有设为 video_end 的 until，使页面持续到视频播放结束，此时 after_ms 是屏幕无法读取视频时长时页面的显示时间；media_end 用于页面上只有一个图片或视频原件时，audio_end 用于页面的 audio_cue 指定了音轨时，或 application 带有 max_ms，当应用通过调用 window.screenrig.nextPage() 主动结束自己的回合时。一个 application 页面必须有且仅有一个标记为 controller 的原件；其他所有模式都禁止使用。after_ms、max_ms 和 dwell_ms 是 1,000 到 86,400,000 的整毫秒数，media_end 页面上的图片需要 dwell_ms。一个页面最多包含一个 stream，以及最多两个 application 或 iframe 原件，media_end 则禁止这两者。

transition.type 是 crossfade、swipe-left、swipe-right、swipe-up、swipe-down、dip、wipe-left、wipe-right、wipe-up、wipe-down、slide-left、slide-right、slide-up、slide-down 或 stinger 之一。duration_ms 是必需的，范围为 0 到 60000。playlist init 写入 200 毫秒交叉淡入淡出。滑动会使两个页面像旋转木马一样一起移动。滑动效果是新页面覆盖旧页面，旧页面漂移四分之一距离。擦除效果是通过移动的硬边缘揭示新页面。浸入效果是先将旧页面淡出为纯色，然后淡入新页面；color 是可选的 #RRGGBB，默认 #000000，仅在 dip 上有效。方向名称表示运动方向：wipe-left 是向左移动的边缘。ease 是可选的：linear、in、out 或 in-out；默认是 linear 用于 crossfade 和 swipe-*，in-out 用于 dip、wipe-* 和 slide-*；不允许用于 stinger。新页面拥有其过渡效果。播放列表的第一页不播放过渡效果。

Stinger 是覆盖出站页面的主题全屏图形，在屏幕被覆盖时切换入站页面，然后揭开。用它命名播放列表的一个部分：放在该部分的第一页。stinger 对象是 type: "stinger" 所必需，且其他类型不允许。其所有成员均为可选。theme 是 neomustard（默认）、cyanotype、propaganda、signal、avant-garde、bloom 或 primetime 之一，匹配卡片主题。title 最多 40 字符，subtitle 最多 60 字符，设置于主题显示类型。logo 是 media: 加上项目中已准备图像的 ID，例如 media:med_01EXAMPLE。accent 是可选的 #RRGGBB，替换主题强调色。duration_ms 对 stinger 为 2000 至 6000，覆盖整个过渡；典型长度为 2700 至 4000。标题完整显示时间为 hang_ms，范围 0 至 6000，默认 1000（1 秒），hang_ms 最多为 duration_ms 的 60%；更长停留需更长 duration_ms。无法绘制 stinger 的播放器播放同长度交叉淡入。参见直播 Stinger 卡片 页面观看过渡效果。

以下示例展示了过渡页切换效果：

{ "type": "stinger", "duration_ms": 3500, "stinger": { "theme": "primetime", "title": "BREAKFAST", "subtitle": "Served until 11", "logo": "media:med_01EXAMPLE", "hang_ms": 1000 } }

原语上的可选 enter 对象添加一个对象动画：fade-up、fade-down、fade-left、fade-right、fade-in、zoom-in 或 zoom-out，可选的 stagger（0 到 8）每一步将其开始时间延迟 120 毫秒。可选的 motion 使原语在进入后继续运动：spin 和 drift 使图片或视频旋转或滑动，path 使图片、视频、应用或 iframe 沿路径点移动。参见 页面背景与动画。

可选的页面visibility对象限制页面播放时间：必需的enabled布尔值，可选的民用from和until边界，以及最多16个重复的windows，包含天数和民用时间。from和until是每个屏幕时区中的YYYY-MM-DDTHH:MM，from含边界，until不含边界且晚于from；时间窗由days（mon至sun）以及start和end（格式为HH:MM）组成，后两者须同时给出，或同时省略表示整天，end等于或早于start时跨越午夜。enabled: false隐藏页面；enabled: true至少需要from、until、windows或data之一。每个播放列表至少保留一个完全没有visibility字段的页面。屏幕按其有效时区读取这些时间：其覆盖值，否则为其播放器报告的时区，否则为 UTC。

页面的visibility.data条件{key, path?, equals?}仅在某个卡片数据文档匹配时才显示该页面：key是卡片数据键或卡片 ID，path是指向文档内部的 RFC 6901 指针，equals是字符串、数字、布尔值或 null（省略则测试该值是否存在）。键{screen.weather}读取每个屏幕自身所在位置的天气，位置由screen update ID --location LAT,LON设置：{"enabled":true,"data":{"key":"{screen.weather}","path":"/condition","equals":"rain"}}仅在该屏幕所在地下雨时显示该页面。天气文档包含condition（clear、cloud、fog、rain、snow、storm或wind）、band（freezing低于 0 °C，cold为 0 到 9，mild为 10 到 17，warm为 18 到 24，hot为 25 及以上）、以整数度表示的temperatureC以及isDay。它是屏幕所在 0.25 度单元的当前天气，约每小时刷新一次，不是预报。没有位置的屏幕永远不会显示该页面，发布时会拒绝文档无法包含的path或equals，例如用cloudy代替cloud。未声明page.conditions主机能力的播放器会将这样的页面禁用。数据条件属于 Plus 功能：没有该功能时，为页面添加其尚未有的 visibility.data 条件的写入会返回 feature_not_in_plan，而保留或删除已存储的条件以及按时间段显示仍可使用。请保留一个没有visibility的普通页面作为后备。

video 或 stream 原语默认静音播放，除非将 muted 设为 false。设置后，它会在其页面为当前页面期间以屏幕音量播放声音，该页面会暂停播放列表配乐，配乐在下一个无声音的页面从同一位置继续播放。同一页面上的多个原语都会播放各自的声音。带声音的页面不能携带 audio_cue：添加它的写入会在 pages[i].audio_cue 处返回 invalid_request，信息为“a page with sound cannot cue the soundtrack”，而已存储的同时含有两者的旧页面会继续播放。广告始终保持静音。

可选的顶层audio对象添加一个在页面切换时持续播放、在有声页面上暂停的配乐。tracks列出1到128个条目，按播放顺序排列，每个条目具有唯一的id（页面ID模式）和准备好的audio媒体对象的media_id。loop默认true，在最后一首曲目后重新开始第一首；volume默认1，范围0到1，乘以播放器音量；cued默认false，true在每首曲目后停止配乐，使曲目仅在页面audio_cue启动时播放。普通页面可携带audio_cue，其trackID来自该列表，并可选带restart布尔值（默认false）：页面出现时，播放器从头切换到该曲目，仅当曲目正在播放且restart为true时才重启。提示为线索，广告位页面不可携带，且无配乐的提示被拒绝。带有advance {"mode":"audio_end"}的页面在其audio_cue指定的曲目结束时结束，因此需要该提示和配乐，不接受after_ms，并遵循图像和视频原始元素的duration规则；stream原始元素仍需duration页面，页面上的应用永远不是其控制器；max_ms为服务器覆盖的可选提示。playlist update替换整个文档，省略audio则移除配乐；playlist patch会保留配乐，除非提供了audio，而--clear-audio或audio: null会将其移除。条带没有配乐。配乐创作。

其他命令组