媒体
媒体对象是一张静态图片、一段视频片段或一条 MP3 音轨，只存储为一个版本。没有按设备的回退方案，因此每块屏幕都必须能解码 media upload 存储的内容。
媒体文件夹组织库。文件夹 ID 以 mfd_ 开头，文件 ID 以 med_ 开头。上传默认存放在库根目录，除非 --folder 指定文件夹，media move 和 media folder update 重新排列树结构，播放列表 by:folder 选择器仅播放某文件夹内的文件，不包括子文件夹。组织跨其所有项目最多包含 1000 个文件夹，嵌套深度最多 10 层，名称长度为 1 到 100 个字符。
文件更改后，媒体保留其 ID：media replace 就地替换文件，因此使用它的每个播放列表和日程都会播放新文件，media versions 会列出该条目曾有的所有文件。
media upload#
将本地文件转换为传输字节，上传并等待对象准备就绪。
media upload <file> [--content-type TYPE] [--tag TAG] [--folder ID] [--no-wait] [--poll-ms MS]
[--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
[--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<file> | 路径 | 是 | 无 | 源静态图像、剪辑或音轨。文件名成为列表、播放列表和播放报告中的人类可读标识，请根据内容命名。 |
--content-type TYPE | string | 否 | 文件扩展名对应的类型 | 为扩展名无法表明类型的文件声明源的媒体类型。与文件字节不符的类型会在任何转换之前被拒绝（usage_error，退出码 2）。 |
--tag TAG | string | 否 | 无 | 一到 32 个字母或数字，匹配 ^[A-Za-z0-9]{1,32}$。不接受连字符。标签使 media list --tag TAG 成为可靠的文件名到 ID 映射。 |
--folder ID | string | 否 | 库根目录 | 一个现有的 mfd_ 媒体文件夹，在任何工作开始前检查。文件准备好时直接放入该文件夹，之后不再移动，并由 data.folder_id 报告。可与 --no-wait 一起使用。上传者必须指定其文件夹之一；见 上传者。 |
--no-wait | boolean | 否 | 关闭 | 提交被接受后立即返回。对象尚未准备好；请使用 operations wait 完成。 |
--poll-ms MS | integer | 否 | 1000 | 等待时操作轮询间隔。 |
--timeout MS | integer | 否 | 120000 | 等待的截止时间。它也限制每个底层请求。 |
--no-transcode | boolean | 否 | 关闭 | 上传源字节，不做更改。ffmpeg、ffprobe 和 cwebp 不会运行。文件必须已经是 PNG、JPEG、WebP、GIF、MP4、WebM 或 MP3，无损 WebP 仍被拒绝。不能与 --codec、--max-fps、--max-edge、--webp-quality、--preset 或 --no-audio 同时使用。 |
--codec | string | 否 | h264 | h264 或 hevc。仅当所有播放剪辑的屏幕都是原生播放器时使用 hevc。 |
--max-fps N | number | 否 | 30 | 恒定输出帧率。每个视频无论源帧率如何，均以此速率编码，确保连续剪辑帧率不变。大于 0，最多 240。 |
--max-edge PIXELS | integer | 否 | 3840 | 对每条边设置范围，范围为 16 到 3840。保持宽高比，不会对较小的源进行放大。 |
--webp-quality | integer | 否 | 90 | WebP 编码的静态质量，范围从 1 到 100。 |
--preset | string | 否 | 未设置 | signage-1080p30 或 signage-4k30。支持方向感知视频尺寸和恒定 30 fps。--max-edge 和 --max-fps 可收紧预设但不能放大。仅限视频；不能与 --no-transcode 结合。 |
--no-audio | boolean | 否 | 关闭 | 视频传输时省略音轨。仅视频；不能与 --no-transcode 组合。 |
--no-progress | boolean | 否 | 关闭 | 不输出进度信息。进度始终输出到 stderr；stdout 仅保留用于单个结果封装。 |
screenrig media upload ./lobby-welcome-loop.mp4 --tag LobbyLoop视频转为 MP4：H.264 High 配置文件，级别取适合尺寸和帧率的最低一级（4.2、5.1 或 5.2）；使用 --codec hevc 时为 H.265 Main 配置文件，级别 5.1 或 5.2；采用 yuv420p 并标记为 Rec. 709，单帧最大 3840 × 2160 像素。HDR 源映射至 Rec. 709。音频（若有）为 AAC，192 kbit/s，48 kHz，立体声。
静态图像在质量 90 时变为有损 WebP，保留源图像的透明通道。动画源无限循环。已符合大小限制的 WebP 直接传递，不重新编码。
音频变为播放列表配乐的 MP3。MP3 源保持不变上传；WAV、AAC、M4A、OGG 和 FLAC 源转换为 128 kb/s MP3，需带 libmp3lame 的 ffmpeg 构建。曲目时长 1 秒至 3 小时。playlist init 将音频输入变为配乐曲目而非页面。准备好的对象是带时长的 audio 媒体对象。不能放置在页面上；在播放列表中命名为 audio 配乐。
准备就绪的对象 ID 是 data.media_id。相同的值是 data.id 和 data.operation.result.media_id。该 ID 是播放列表选择器使用的。
若已有字节、文件名和标签都相同的就绪媒体，则直接返回它而不再上传（data.reused 为 true），因此重新运行被中断的上传会返回其媒体 ID。data.timing 报告各阶段的毫秒数：prepare_ms（转换和哈希）、declare_ms、transfer_ms、commit_ms 和 processing_ms（直到就绪，精度同 --poll-ms；使用 --no-wait 时不出现）。
低信息量文件名如 video.mp4 会在信封中添加建议性 generic_filename 警告。上传仍成功，CLI 不会重命名文件；请在运行命令前选择名称。
转换运行 ffmpeg 和 ffprobe，来源于 PATH，或来自 SCREENRIG_FFMPEG 和 SCREENRIG_FFPROBE 中的绝对路径。静态图像优先使用 ffmpeg libwebp 编码器，遇 PATH 或 SCREENRIG_CWEBP 时回退到 cwebp。会话首次上传前运行 doctor。
--preset signage-1080p30 将长边限制为 1920，短边限制为 1080，帧率恒定为 30 fps。signage-4k30 将长边限制为 3840，短边限制为 2160，帧率恒定为 30 fps。两者均支持横屏、竖屏和方形内容。--no-audio 对静音片段不进行音频编码。这些选项仅适用于视频。
screenrig media upload ./lobby.mov --preset signage-1080p30 --no-audioscreenrig media upload ./menu.png --folder mfd_01EXAMPLEFOLDER000000000media upload-batch --folder 以同样方式把每个上传的项目放入该文件夹。
图像或视频的宽和高最多 16383 像素，单帧最多 67,108,864 像素（8192 × 8192）；更大的会被 invalid_request 拒绝。默认转换会把每条边限制在 3840 像素内，因此 9216 × 2160 或 12000 × 540 这样的超宽母版请用 --no-transcode 上传。单个视频上传最大不能超过项目套餐允许的最大视频上传大小（project capabilities 将其报告为 media_video_bytes，见定价）；更大的视频在读取前就会被拒绝，所以请先剪短。CLI 以固定质量编码视频，因此较长的视频在编码后仍可能超出限制并被拒绝；使用 --no-transcode 时，文件本身必须在限制之内。
中断的存储传输会在其上传 URL 有效期间最多尝试 4 次。若仍然失败，错误会指明该上传的 operation_id，并取消该上传以免占用存储；使用 --idempotency-key 时则保留以供重新运行。请再次运行同一条命令。
在提议访问权限下，或项目要求审核代理更改时，新上传内容需等待人工审核后，标签、文件夹或all选择器才能播放；详见审核。
media upload-batch#
从清单上传多个本地文件，可从状态文件恢复。
media upload-batch <manifest.json> [--state FILE] [--concurrency N] [--tag TAG] [--folder ID]
[--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc]
[--max-fps N] [--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<manifest.json> | 路径 | 是 | 无 | { "items": [ { "path": "./a.png", "tag"?: "Lobby", "content_type"?: "image/png" } ] }，包含 1 到 1000 个项目。路径相对于清单文件。 |
--state FILE | 路径 | 否 | 配置旁的私有文件 | 一个以每个源文件本地字节的 SHA-256 为键的 0600 JSON 文件；默认每个项目、API 地址和清单对应一个文件。已存在的项目用 media_id 报告为 resumed。不要在项目间共享同一个状态文件。 |
--concurrency N | integer | 否 | 4 | 并行上传数，1 到 8。 |
--no-transcode | boolean | 否 | 关闭 | 上传源字节，不做更改，如 media upload 所示。不能与 --codec、--max-fps、--max-edge、--webp-quality、--preset 或 --no-audio 同时使用。 |
--poll-ms MS | integer | 否 | 1000 | 等待时操作轮询间隔。 |
--timeout MS | integer | 否 | 120000 | 等待的截止时间。它也限制每个底层请求。 |
--codec | string | 否 | h264 | h264 或 hevc。仅当所有播放剪辑的屏幕都是原生播放器时使用 hevc。 |
--max-fps N | number | 否 | 30 | 恒定输出帧率。每个视频无论源帧率如何，均以此速率编码，确保连续剪辑帧率不变。大于 0，最多 240。 |
--max-edge PIXELS | integer | 否 | 3840 | 对每条边设置范围，范围为 16 到 3840。保持宽高比，不会对较小的源进行放大。 |
--webp-quality | integer | 否 | 90 | WebP 编码的静态质量，范围从 1 到 100。 |
--preset | string | 否 | 未设置 | signage-1080p30 或 signage-4k30。支持方向感知视频尺寸和恒定 30 fps。--max-edge 和 --max-fps 可收紧预设但不能放大。仅限视频；不能与 --no-transcode 结合。 |
--no-audio | boolean | 否 | 关闭 | 视频传输时省略音轨。仅视频；不能与 --no-transcode 组合。 |
--tag TAG | string | 否 | 无 | 当项目省略自身标签时应用。 |
--folder ID | string | 否 | 库根目录 | 一个现有的 mfd_ 媒体文件夹，在任何工作开始前检查。每个项目准备好时直接放入该文件夹，并由 data.folder_id 报告。上传者必须指定其文件夹之一。 |
--no-progress | boolean | 否 | 关闭 | 不输出进度信息。 |
screenrig media upload-batch ./images.json --state ./upload-state.json信封按清单顺序携带 data.items[]，每个包含 path、source_filename、sha256、outcome（accepted 或 resumed）和 media_id。data.failed[] 携带未落地的项目，每个带有其 path 和 problem；data.accepted、data.resumed、data.attempts、data.rate_limited、data.wait_ms 和 data.transfer_ms 统计本次运行。只要响应是速率限制或服务器错误，每个项目最多尝试 8 次，每次之间会等待。
出现失败时，退出码取决于最后一个失败的项目：速率限制为 7，服务器错误为 9，用法错误为 2，其他情况为 8。使用同一份清单再次运行同一条命令，即可只上传未落地的项目。
media replace#
就地替换媒体的文件。其 ID、播放列表和日程继续有效。
media replace <id> <file> [--expect-rev REVISION] [--note TEXT] [--content-type TYPE] [--no-wait]
[--poll-ms MS] [--timeout MS] [--no-transcode] [--codec h264|hevc] [--max-fps N]
[--max-edge PIXELS] [--webp-quality 1-100] [--no-progress]
[--preset signage-1080p30|signage-4k30] [--no-audio]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
<file> | 路径 | 是 | 无 | 新的静态图片、视频片段或音频轨道。它必须与媒体种类相同：图片对图片、视频对视频、音频对音频。在开始任何工作之前检查（usage_error，退出码 2）。 |
--expect-rev REVISION | string | 否 | 无 | 可选的修订前提条件。提供的过期值为 revision_conflict，并且已声明的上传会被取消：请读取 media show ID 后再次运行命令。 |
--note TEXT | string | 否 | 无 | 与新版本一同保存，并显示给审核者。最多 280 个字符。 |
--content-type TYPE | string | 否 | 从上传的字节检测 | 自行声明媒体类型，而不是让 CLI 检测。 |
--no-wait | boolean | 否 | 关闭 | 替换被接受后立即返回。新文件尚未投入使用；请使用 operations wait 完成。 |
--poll-ms MS | integer | 否 | 1000 | 等待时操作轮询间隔。 |
--timeout MS | integer | 否 | 120000 | 等待的截止时间。它也限制每个底层请求。 |
--no-transcode | boolean | 否 | 关闭 | 上传源字节，不做更改。ffmpeg、ffprobe 和 cwebp 不会运行。文件必须已经是 PNG、JPEG、WebP、GIF、MP4、WebM 或 MP3，无损 WebP 仍被拒绝。不能与 --codec、--max-fps、--max-edge、--webp-quality、--preset 或 --no-audio 同时使用。 |
--codec | string | 否 | h264 | h264 或 hevc。仅当所有播放剪辑的屏幕都是原生播放器时使用 hevc。 |
--max-fps N | number | 否 | 30 | 恒定输出帧率。每个视频无论源帧率如何，均以此速率编码，确保连续剪辑帧率不变。大于 0，最多 240。 |
--max-edge PIXELS | integer | 否 | 3840 | 对每条边设置范围，范围为 16 到 3840。保持宽高比，不会对较小的源进行放大。 |
--webp-quality | integer | 否 | 90 | WebP 编码的静态质量，范围从 1 到 100。 |
--preset | string | 否 | 未设置 | signage-1080p30 或 signage-4k30。支持方向感知视频尺寸和恒定 30 fps。--max-edge 和 --max-fps 可收紧预设但不能放大。仅限视频；不能与 --no-transcode 结合。 |
--no-audio | boolean | 否 | 关闭 | 视频传输时省略音轨。仅视频；不能与 --no-transcode 组合。 |
--no-progress | boolean | 否 | 关闭 | 不输出进度信息。进度始终输出到 stderr；stdout 仅保留用于单个结果封装。 |
screenrig media replace med_01EXAMPLEIMAGE0000000000 ./menu-v2.png
screenrig media replace med_01EXAMPLEVIDEO0000000000 ./intro.mp4 --expect-rev 3 --note "Spring cut"媒体保留其 ID、标签和文件夹，因此每个引用它的播放列表和日程都会在下一个清单中播放新文件，按标签、文件夹和 all 的选择器也会选中它。不会重新安排任何内容。该命令执行与 media upload 相同的步骤（转换、套餐的视频字节上限、尺寸限制、套餐的存储上限、签名传输），然后替换，而不是添加新媒体。它不接受 --tag 或 --folder。
默认情况下，命令会等待处理完成。data.media_id 和 data.id 是媒体 ID，data.version 是新文件在 media versions 中的编号，data.revision 是媒体的新修订。data.warnings、data.operation、data.upload、data.transcode 和耗时的报告方式与 media upload 相同，操作 ID 位于信封中。使用 --no-wait 时，data.operation 是已接受的操作，data.version 和 data.warnings 不会出现。
允许更改宽高比。信封中带有 aspect_ratio_changed 警告，data.warnings[].playlists 会列出使用该媒体的播放列表，请检查它们的显示效果。与当前文件字节相同的文件会被拒绝，返回 resource_conflict（退出码 13）。
每个先前的文件都保留在媒体的历史记录中，并计入已存储字节，直到其版本被删除；参见 media versions。
在 Propose 访问权限下，或项目要求对代理更改进行审核时，替换会等待人工审核，命令成功返回（退出码 0）：data.status 为 pending_review，data.review_id 指明审核，警告 pending_review 给出其 URL，data.next 为 screenrig reviews show ID。在有人批准之前，媒体继续播放其当前文件，因此请告知对方它正在等待，且不要重复写入。同一媒体较新的替换会取代正在等待的那个。参见审核。
media versions#
列出媒体曾有的文件，当前使用的文件排在最前。
media versions <id> [--limit N] [--cursor CURSOR]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
--limit N | integer | 否 | 每一页 | 读取包含此数量版本的一页，范围为 1 到 100。 |
--cursor CURSOR | string | 否 | 无 | 读取上一页 data.next_cursor 之后的那一页。 |
screenrig media versions med_01EXAMPLEIMAGE0000000000data.items 为媒体曾有的每个文件提供一个条目：number, current, filename, source_filename, content_type, sha256, bytes, width, height, duration_ms, codecs、source（upload、replace、sync 或 restore）、note、by（种类为 person、agent、client 或 sync，含 ID 和名称）、restored_from 以及 created_at。当前使用的文件排在最前（current: true），其余按从新到旧排列。版本 1 是首次上传；每次替换、恢复或媒体同步更改都会增加下一个编号。
不带 --limit 和 --cursor 时会读取所有页面，且 data.next_cursor 为 null。带其中任意一个时只读取一页：只要 data.next_cursor 是字符串，就用设为该值的 --cursor 再次运行命令。只读访问权限即可。过去版本的字节会一直保存并计入项目的已存储字节，直到 media version delete 将其删除；保留的版本数量没有限制，超出套餐免费存储的已存储字节与其他存储一样计费。
media restore#
将过去的版本作为新版本重新投入使用。
media restore <id> --number N [--expect-rev REVISION] [--note TEXT]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
--number N | integer | 是 | 无 | 要重新投入使用的版本号，与 media versions 所列相同。 |
--expect-rev REVISION | string | 否 | 无 | 可选的修订前提条件。提供的过期值为 revision_conflict：请读取 media show ID 后再次运行命令。 |
--note TEXT | string | 否 | 无 | 与新版本一同保存，并显示给审核者。最多 280 个字符。 |
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2
screenrig media restore med_01EXAMPLEIMAGE0000000000 --number 2 --expect-rev 5 --note "Back to the winter menu"媒体保留其 ID 并进入新的修订，引用它的每个播放列表和日程都会再次播放该文件。被复制的版本仍保留在历史记录中并共用其字节；新版本与其他版本一样计入已存储字节。data.media 是媒体，当恢复的文件宽高比不同时，data.warnings 带有 aspect_ratio_changed，列出使用该媒体的播放列表。
当前使用的版本不能恢复（resource_conflict，退出码 5），未知版本为 not_found（退出码 4）。在 Propose 访问权限下，或项目要求对代理更改进行审核时，恢复会等待人工审核，命令成功返回（退出码 0）：data.status 为 pending_review，并带有 data.review，警告 pending_review 给出其 URL，data.next 为 screenrig reviews show ID。在有人批准之前，媒体继续播放其当前文件，因此请勿重复写入。
media version delete#
删除过去的版本及其已存储的字节。
media version delete <id> --number N| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
--number N | integer | 是 | 无 | 要删除的版本号，与 media versions 所列相同。 |
screenrig media version delete med_01EXAMPLEIMAGE0000000000 --number 2该版本的记录被删除，其字节立即从项目的已存储字节中扣除。已存储的对象在 24 小时后被移除，除非另一个版本或当前使用的文件持有同一文件。已删除的版本无法恢复。当前使用的版本不能被删除，并且在媒体的替换等待审核期间，任何版本都不能被删除；这两种情况均为 resource_conflict（退出码 5），media versions ID 会显示哪个版本正在使用。未知版本为 not_found（退出码 4）。删除需要 Manage 访问权限：Propose 凭据会被拒绝并返回 insufficient_access，删除操作绝不会被提交审核。
media show#
读取一个媒体对象，包括其当前版本。
media show <id>| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
screenrig media show med_01EXAMPLEIMAGE0000000000media download#
写入存储的渲染文件以供检查。切勿打印字节。
media download <id> [--output FILE]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
--output FILE | 路径 | 否 | ./<id>.<ext> 位于当前目录 | 文件路径，不是目录。现有文件将被覆盖。扩展名遵循内容类型。 |
screenrig media download med_01EXAMPLEIMAGE0000000000 --output ./lobby.webp结果报告 media_id、path、bytes、sha256、content_type、primitive、filename、可选的 source_filename，以及 width / height。它从不携带像素。用它在图片上屏之前先检查一遍。
media list#
列出媒体对象，可按标签、原始类型和文件夹筛选。
media list [--tag TAG] [--primitive image|video|audio] [--folder ID|root] [--library]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
--tag TAG | string | 否 | 无 | 匹配 ^[A-Za-z0-9]{1,32}$。存在此筛选器时，未标记对象将被省略。 |
--primitive | string | 否 | 全部 | image，video，或 audio。限制列表仅显示静态图像、剪辑或配乐轨道。 |
--folder ID|root | string | 否 | 每个文件夹 | 仅此 mfd_ 文件夹内的文件，不含子文件夹，或带 root 时仅库根目录文件。API 应用筛选。 |
--library | boolean | 否 | 关闭 | 改为以只读方式列出组织媒体库的媒体：每行带有 library: true。可在播放列表页面中使用它们的 ID；只能在媒体库项目中修改它们。 |
screenrig media list --tag LobbyLoop --primitive video
screenrig media list --folder mfd_01EXAMPLEFOLDER000000000
screenrig media list --library每一行都包含 folder_id，但在库根目录下没有。
media selector-preview#
预览动态媒体选择器当前匹配的就绪文件，不发布播放列表，也不推进播放器。
media selector-preview <selector.json> --primitive image|video [--rect WxH] [--timezone IANA]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<selector.json> | 路径 | 是 | 无 | 包含一个 all、tag 或 folder 媒体选择器的 JSON 文件，或用 - 从标准输入读取。含屏幕令牌的标签无法预览。 |
--primitive | string | 是 | 无 | image 或 video：选择器匹配的文件类型。 |
--rect WxH | string | 配合 fit: "aspect" | 无 | 原语矩形的大小，例如 1080x1920，两个数字都必须大于 0。 |
--timezone IANA | string | 否 | UTC | 读取文件可用性规则所用的时区，例如 America/New_York。 |
screenrig media selector-preview selector.json --primitive video
screenrig media selector-preview selector.json --primitive image --timezone America/New_York选择器的键（order、batch_size、one_at_a_time、weights 和 fit）见标记筛选器和播放批次以及加权轮换和宽高比适配。
响应包含 matched_count、按文件名排序的 candidates（media_id、filename、tags、width、height）、规范化后的 selector，以及在 excluded 中被排除的文件及其 reason：aspect_mismatch 对应 fit: "aspect"，outside_window 对应此刻可用性规则不成立的文件。使用 order: "weighted" 时，每个候选带有 weight 和 share_percent，cycle 是每个条目恰好播放其权重次数所需的播放次数。匹配超过 1024 个会返回 invalid_request。只读访问即可。预览读取已认证的项目，从不推进游标，也不更改清单，之后的目录更改会在每个播放器的下一个循环边界生效。
media update#
替换或清除单个对象的标签。其可用性规则通过 media availability 设置。
media update <id> (--tag TAG | --tags TAG1,TAG2 | --clear-tag) [--expect-rev REVISION]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
--tag TAG | string | 三者之一 | 无 | 替换标签，1 到 32 个字母或数字。它会成为该对象唯一的标签。 |
--tags TAG1,TAG2 | string | 三者之一 | 无 | 替换标签集：1 到 32 个以逗号分隔的唯一标签，每个标签 1 到 32 个字母或数字。 |
--clear-tag | boolean | 三者之一 | 关闭 | 移除所有标签，使对象保持无标签状态。 |
--expect-rev REVISION | string | 否 | 无 | 可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。 |
screenrig media update med_01EXAMPLEIMAGE0000000000 --tag LobbyLoop
screenrig media update med_01EXAMPLEIMAGE0000000000 --tags Summer,Drinks在提议访问权限下，或项目要求审核代理更改时，重新标记已批准的媒体会以警告media_review_pending回应ok：屏幕继续使用其已批准的标签播放，直到人工批准更改，拒绝则恢复标签。审核结果几秒内显示在reviews list；未更改任何已批准播放列表或待审核播放列表的重新标记自动生效。详见审核。
media availability#
设置或清除动态选择器何时可以选取某个文件。
media availability <id> (--file FILE | --clear) [--expect-rev REVISION]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
--file FILE | 路径 | 两者之一 | 无 | 一条 JSON 可用性规则，或用 - 从标准输入读取。 |
--clear | boolean | 两者之一 | 关闭 | 移除规则；文件始终可用。 |
--expect-rev REVISION | string | 否 | 当前修订版本 | 可选修订前提条件。省略时，命令会先读取媒体的当前修订版本。提供的过期值为 revision_conflict：重新获取，重新应用，重试。 |
screenrig media availability med_01EXAMPLEIMAGE0000000000 --file rule.json规则的成员和行为见媒体可用性。等待人工审核的文件会被 media_pending_review 拒绝：请先决定该审核。
media delete#
删除一个媒体对象。
media delete <id> [--expect-rev REVISION]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | med_ 对象 ID。 |
--expect-rev REVISION | string | 否 | 无 | 可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。 |
screenrig media delete med_01EXAMPLEIMAGE0000000000media move#
将媒体文件和文件夹移动到某个文件夹，或移回库根目录。
media move <id>... (--folder ID | --root)| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id>... | string | 是 | 无 | 一个或多个 med_ 文件 ID 和 mfd_ 文件夹 ID，总数最多 1000 个。 |
--folder ID | string | 两者之一 | 无 | 目标 mfd_ 文件夹。 |
--root | boolean | 两者之一 | 关闭 | 移动到库根目录。 |
screenrig media move med_01EXAMPLEIMAGE0000000000 med_01EXAMPLEVIDEO0000000000 --folder mfd_01EXAMPLEFOLDER000000000
screenrig media move mfd_01EXAMPLEFOLDER000000000 --root移动为全有或全无请求。文件夹不能移动到自身或其内部文件夹，文件夹最多嵌套10层。目标中已有项保持不变。data.media 和 data.folders 统计移动数量。
移动文件会改变其旧文件夹和新文件夹的 by:folder 选择器的播放内容，从每个屏幕的下一个选择器解析开始；移动文件夹不会改变任何文件夹自身的文件。在 Propose access 下，或当项目需要代理变更审核时，每个移动的文件需等待人工审核（reviews list），已批准的播放列表继续按批准时所在文件夹播放；详见 审核。
media folder list#
列出项目的媒体文件夹。
media folder list [--library]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
--library | boolean | 否 | 关闭 | 改为以只读方式列出组织媒体库的文件夹：每行带有 library: true，by:folder 选择器可以指定其中一个来播放其中的文件。 |
screenrig media folder list
screenrig media folder list --library返回项目的所有文件夹，最多 1000 个，按名称排序：data.items 包含 id、name、parent_id（null 位于库根目录）和 revision。从 parent_id 构建树。文件的文件夹在 media list 上的 folder_id 和 media show；在库根目录则不存在。
media folder show#
读取一个媒体文件夹。
media folder show <id>| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | mfd_ 文件夹 ID。 |
screenrig media folder show mfd_01EXAMPLEFOLDER000000000信封携带文件夹的 name、parent_id 和 revision。
media folder create#
在库根目录或另一个文件夹内创建媒体文件夹。
media folder create --name NAME [--parent ID]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
--name NAME | string | 是 | 无 | 1 到 100 个字符，修剪。名称可重复。 |
--parent ID | string | 否 | 库根目录 | 创建它的 mfd_ 文件夹。 |
screenrig media folder create --name Menus
screenrig media folder create --name Lunch --parent mfd_01EXAMPLEFOLDER000000000组织跨其所有项目最多持有 1000 个文件夹，嵌套深度最多 10 级。播放列表通过 by:folder 选择器播放文件夹中的文件。
media folder update#
重命名媒体文件夹，或将其连同内部所有内容移动到另一个文件夹。
media folder update <id> [--name NAME] [--parent ID | --root] [--expect-rev REVISION]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | mfd_ 文件夹 ID。 |
--name NAME | string | 至少包含 --name、--parent、--root 之一 | 未更改 | 新名称，1至100字符。 |
--parent ID | string | 至少包含 --name、--parent、--root 之一 | 未更改 | 将文件夹及其所有内容移动到此 mfd_ 文件夹。不支持 --root。 |
--root | boolean | 至少包含 --name、--parent、--root 之一 | 关闭 | 将文件夹移动到库根目录。不支持 --parent。 |
--expect-rev REVISION | string | 否 | 无 | 可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。 |
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --name Archive
screenrig media folder update mfd_01EXAMPLEFOLDER000000000 --root文件夹不能移动到自身或其内部的文件夹，且移动必须保持所有文件夹层级不超过 10 级。发送当前值为无操作。
media folder delete#
删除媒体文件夹。其文件和文件夹上移一级。
media folder delete <id> [--expect-rev REVISION]| 参数 | 类型 | 必填 | 默认 | 备注 |
|---|---|---|---|---|
<id> | string | 是 | 无 | mfd_ 文件夹 ID。 |
--expect-rev REVISION | string | 否 | 无 | 可选修订前提条件。省略则写入当前资源。提供的过期值为 revision_conflict：重新获取，重新应用，重试。 |
screenrig media folder delete mfd_01EXAMPLEFOLDER000000000仅删除文件夹。其文件和文件夹上移至其父级，或无父级时上移至库根目录。命名该文件夹的 by:folder 选择器将不匹配任何内容，请先重新指向这些播放列表。
标记筛选器和播放批次
媒体最多携带 32 个唯一标签，每个标签由 1 到 32 个字母或数字组成。用 screenrig media update med_ID --tags Summer,Drinks 替换整个集合。--tag Summer 用一个标签替换；--clear-tag 清除所有标签。media list --tag Summer 匹配集合中任何位置的成员。标签区分大小写，且绝不用于授权。
动态选择器可使用一个 tag 或一个 tags 过滤对象：
{
"by": "tag",
"tags": { "all": ["Summer", "Drinks"], "any": ["Lobby", "Patio"], "none": ["Expired"] },
"order": "random",
"one_at_a_time": false,
"batch_size": 3
}
all 需要所有列出的标签，any 至少需要一个，none 排除任何列出的标签。存在的组用 AND 连接；省略的组不施加条件。至少提供一个非空组。每组最多接受 32 个唯一标签。tag 和 tags 互斥。仅 none 过滤器选择该原语的所有就绪媒体，除排除标签外。图像选择器选择图像，视频选择器选择视频。
folder 选择器 { "by": "folder", "folder_id": "mfd_…" } 播放某个媒体文件夹中直接包含的就绪文件，不包含其子文件夹中的文件；media folder list 会显示这些 ID。它与 all 和 tag 一样可使用 order、one_at_a_time 和 batch_size；删除文件夹会把其中的文件上移一级，并使该选择器变空。
候选池每个选择器最多包含 1,024 个就绪媒体，整个循环快照中共有 1,024 个媒体引用。写入时，每个 all、tag 或 folder 选择器按其中 32 个引用计算，ids 选择器按其长度计算。匹配数更多会返回错误；请缩小筛选条件。batch_size 是另一项限制，每次访问页面为 1 到 1,024 个条目。在 media_end 页面上，one_at_a_time: false 按顺序播放下一批；省略 batch_size 则播放剩余的一轮。one_at_a_time: true 每次出现播放一个条目，只允许省略批大小或 batch_size: 1。在时长、应用和 audio_end 页面上，每个 all、tag、folder 和多 ID 的 ids 选择器都需要 one_at_a_time: true，dwell_ms 会被拒绝。media_end 上的图片同样需要 dwell_ms；视频无法在该页面上循环。
播放器在播放列表启动和每个循环边界时，一次请求解析所有动态媒体原语。循环期间成员冻结。上传、移除、标签变更和可用时段边界不重新生成清单。下次刷新时，移除或新排除项离开待处理队列；新匹配项在当前轮次结束时加入。最终批次可能少于请求数；不会从下一轮补充。文件名排序按文件名再媒体 ID。随机排序每轮完整播放洗牌一次，保持循环刷新间剩余顺序。加权排序遵循其权重，见下文。光标本地于屏幕、播放列表、页面和原语，重启持续，过滤、排序或批次策略变更时重置。离线播放使用最后成功快照。空匹配跳过原语及任何空页面。
将上面的选择器对象保存为 selector.json，然后在发布前检查其当前候选目录：
screenrig media selector-preview selector.json --primitive video
预览返回 matched_count，按文件名排序的 candidates（包含媒体 ID 和标签），以及规范化的 selector 策略。随机顺序显示池和洗牌策略；不选择播放器的洗牌，不推进光标，不创建播放授权，也不更改清单。加权顺序下，它会返回每个候选项的 weight 和 share_percent，以及 cycle。--rect WxH（API 为 rect: {width, height}）是版位的尺寸，与 fit: "aspect" 一起使用时必填；被排除的匹配项列在 excluded 中，原因为 aspect_mismatch。图像选择器传入 --primitive image。API 与 POST /api/selectors/preview 结合 { "primitive": "video", "selector": ... } 使用。它使用经过身份验证的项目和与播放相同的匹配规则。预览后的目录更改将在播放的下一个循环边界解决。
静态包导出将动态匹配冻结为精确 ID，并将 random 选择器随机排序一次。它保留一次或完整播放；使用带有 batch_size 和 one_at_a_time: false 的有界运行时序列时，需要在导出前移除该字段或选择明确的 ID。这防止在静态包中静默丢失运行时批次游标。
加权轮换和宽高比适配
order: "weighted" 按权重轮换一个版位的素材，使每个赞助商保持其播放占比。weights 将媒体 ID（med_...）或 tag:NAME 映射为 1 到 1,000 的整数，最多 64 个键。它适用于 by 为 all、tag 或 folder 时：
{
"by": "all",
"order": "weighted",
"one_at_a_time": true,
"weights": { "tag:Acme": 50, "tag:Globex": 30, "tag:Initech": 20 },
"fit": "aspect"
}
权重 50、30 和 20 在每个周期中恰好交付每 10 次播放中的 5、3 和 2 次，重启后从周期中途继续。条目的权重是其媒体 ID 键（若存在）；否则取它所带标签中按字母顺序第一个 tag:NAME 键，在所选条目中带有该键的条目之间平均分配，因此无论赞助商有多少素材，其占比都保持不变；否则该条目自成一组，权重为 1。一个周期最多 4,096 次播放；仅当精确比例需要更长周期时，占比才会按其取整。
加权顺序每次访问播放一个条目，因此请设置 one_at_a_time: true 或 batch_size: 1。加权顺序必须提供 weights，且仅允许与其一起使用；否则写入返回 invalid_request。加权轮播属于 Plus 功能：没有该功能时，为项目设置其尚未有的权重的写入会返回 feature_not_in_plan，而均等轮播、保留已存储的权重以及清除权重仍可使用。所有播放器都支持加权顺序。未声明 selector.weighted 主机能力的播放器会收到 random，清单诊断中带有 selector_order_downgraded。
动态选择器上的 fit: "aspect" 只保留宽高比与版位矩形（包括视频墙或显示器边框）的宽高比相差在 5% 以内的文件，在选择器解析时读取。竖屏版位不会播放横屏文件。无需更改播放器。
screenrig media selector-preview 会输出加权选择器中每个文件的预期占比，并在使用 fit: aspect 时列出被排除的文件；控制台的页面编辑器也在检查器中显示同一张表。静态包导出将加权选择器冻结为按文件名排序的精确 ID，不保留权重。
标签选择器中的屏幕令牌
标签选择器的 tag，以及其 tags 过滤器的每个条目，可以是 {screen.field.NAME} 或 {screen.id}（不带 scr_ 前缀的屏幕标识符，它本身就是标签）。令牌可与字母和数字一起出现在最长 128 个字符的模板中。服务器在构建每块屏幕的清单和选择器快照时为其填充令牌，因此一个播放列表即可播放每块屏幕各自的媒体。为媒体打上 Lobby 或 Garage 标签，用 screenrig screen update scr_ID --field zone=Lobby 设置每块屏幕的字段，然后为版位指定这个选择器：
{ "by": "tag", "tag": "{screen.field.zone}", "one_at_a_time": true }
填充后的值遵循标签规则：1 到 32 个字母或数字。没有该字段、或字段值不是标签的屏幕不选择任何内容：它不会播放该版位中的任何文件，清单诊断中带有 screen_fact_missing 或 screen_fact_invalid。更改字段会为该屏幕重新生成清单。带令牌的选择器无法预览（media selector-preview 需要具体标签），也无法被 playlist export 冻结。
iframe 地址和应用参数中的屏幕令牌
iframe 的 src 和 fallback_src 可在 http 或 https 地址的路径、查询或片段中携带屏幕令牌，application 原语的可选 params 也可以：最多 16 个名称，每个由 1 到 32 个小写字母、数字或下划线组成（ticket 和 policy 为保留名称），值最多 512 个字符。服务器会为每个屏幕填入：
| 令牌 | 值 |
|---|---|
{screen.id} | 屏幕的标识符，不含其 scr_ 前缀。 |
{screen.name} | 屏幕的名称。 |
{screen.timezone} | 屏幕生效的 IANA 时区：其覆盖值，否则为其播放器报告的时区，否则为 UTC。 |
{screen.field.NAME} | 屏幕的字段 NAME，由 1 到 32 个小写字母、数字或下划线组成。 |
{screen.location.lat}, {screen.location.lon} | 其位置，以十进制度数表示。 |
{screen.location.name}, {screen.location.address} | 其地名和街道地址。 |
{
"primitive": "iframe",
"src": "https://maps.example.com/directory?kiosk={screen.field.kiosk_id}&level={screen.field.level}",
"title": "Directory"
}
写入时按原样存储模板，包括花括号。每个屏幕的清单携带其自己的地址，每个值都按其在 URL 中的位置进行百分号编码：kiosk_id 为 B 2&3 会变成 B%202%263。位于协议、凭据、主机或端口，或 YouTube 链接、Google 或 Microsoft 文档链接或 BI 视图地址中的令牌，在 src（或 fallback_src）处为 invalid_request。含模板的 src 在发布时跳过嵌入检查，预览则按原样显示模板。
缺少某个值（未设置的字段、无位置），或其值填入后得到超过 2048 个字符的地址，或路径段为 . 或 .. 的屏幕，不会获得此类 iframe 或应用，其清单诊断携带 screen_fact_missing 或 screen_fact_invalid；留空的页面会被丢弃。每个作用于此类屏幕的写入（播放列表写入、screen assign、screen update、机群分配、已批准的审核）都会返回 screen_fact_missing 警告，其中列出令牌、前 20 个屏幕 id 及总数。更改字段或位置会重新生成其所影响屏幕的清单。
对于应用，填入的参数在百分号编码后合计最多 4096 个字符，会在每个播放器上通过 context.params 交给它（SDK）。播放器 Web 应用及运行它的播放器（Samsung Tizen、BrightSign、LG webOS 和 Vega）还会在 ticket 之后把每个参数以百分号编码追加到启动地址，因此应用可以读取 location.search。模板的 url 字段可以是整个 iframe src，其值本身也可携带屏幕令牌，在构建清单时填入。标签选择器以同样方式使用 {screen.id} 和 {screen.field.NAME}（见上文）。卡片保留自己的 {screen.…} 令牌。
同一播放列表中固定同一版本的应用原语携带相同的 params。
媒体可用性
screenrig media availability med_ID --file rule.json 设置动态选择器（all、tag 和 folder）何时可以选取某个文件。--clear 移除规则，--expect-rev N 保护媒体修订版本。API 为 PATCH /api/media/{id}/availability，使用 If-Match 和 { "availability": {...} | null }。设置规则需要 Manage 访问权限；Propose 凭据会收到 insufficient_access。省略 --expect-rev 时，命令会先读取媒体的当前修订版本。等待人工审核的文件会被 media_pending_review 拒绝。
规则采用排程的时钟语法，按每块屏幕的时区解读，至少包含一个成员：from 和 until（民用时间 YYYY-MM-DDTHH:MM，until 不含），windows（每周 {days, start, end}），monthly（{day} 或 {nth, weekday}，各自带可选的 start 和 end），dates（{date, start, end}）以及 except（移除某次出现的日期，包括跨午夜的尾段），其中 windows 最多 16 个，monthly 最多 16 项，dates 最多 100 个，except 日期最多 100 个。它没有 data 或 interaction。赞助商在长周末的素材，仅在时段内的工作日晚间可用：
{
"from": "2026-11-27T00:00",
"until": "2026-11-30T23:59",
"windows": [{ "days": ["mon", "tue", "wed", "thu", "fri"], "start": "17:00", "end": "22:00" }]
}
只有选择器会读取该规则：显式的 id 或 ids 选择器会忽略它，卡片的媒体引用、配乐音频和广告素材同样不受影响。文件会在每块屏幕的下一个播放列表循环离开或重新进入选择，在边界后约一分钟内生效。播放列表和清单的修订版本都不会变化，离线的播放器会保留其上一次的选择，直到重新连接。media selector-preview配合 --timezone ZONE（默认 UTC）会按该时区读取规则，并在 excluded 中列出此刻处于规则之外的文件，原因为 outside_window。