显示屏

Changes Display Screens settings shared by every facility in the facility's brand: the boot screen shown while screens start up, the settings new screens start with, and what templated content shows. Organisation admins only; read the current values and canEdit with display_settings_read boot_screen, screen_defaults or templated.

Actions:

• save_boot_screen: Save the boot screen. Sets the boot screen image (PNG, JPEG or WebP, up to 10 MB, from a public https imageUrl or imageBase64) and/or how it is laid out. Without an image, fit and background re-render the current one. Screens pick it up when they next start. Asks for confirmation.
• reset_boot_screen: Reset the boot screen. Removes the brand's boot screen; screens go back to the default one when they next start. Asks for confirmation.
• save_screen_defaults: Save the screen defaults. The settings a screen starts with when it is paired at one of the brand's facilities. Only the settings you pass change. Screens that are already paired keep their own settings; change those with device_inventory_write configure_screen. Asks for confirmation.
• save_templated: Save templated content settings. What templated content screens and the Schedule show: the data source name, workout names, programs in the Schedule and how far ahead, training phases and how far ahead, and Program Builder training camps (one banner per week) and how far ahead. Asks for confirmation.

在设施中创建、重命名和删除 Display Screen 分组，并设置分组包含哪些屏幕。分组可作为发布目标（display_publish targets.groupIds）和命令目标（display_screen_command groupIds）。提供多个屏幕、分组或目标时，一次调用会作用于全部对象；对大量对象执行操作前请先与用户确认。

操作：

• save：保存分组。创建：name（可选 screenIds）。重命名：groupId（ID 或当前名称）和 name。screenIds 会替换成员；未列出的屏幕会离开该分组，但保留其所属的其他分组。
• delete：删除分组。删除分组后，其屏幕会离开该分组（保留其他分组），发布到该分组的内容会从排程中移除。需要 groupId。需要确认。

为 Display Screens 发布静态 HTML 应用（“托管应用”）。请先调用 display_library_read app_guidelines 了解屏幕尺寸、设计规则、限制和 SDK，之后调用 display_screenshot 在屏幕上检查效果。提供多个屏幕、分组或目标时，一次调用会作用于全部对象；对大量对象执行操作前请先与用户确认。

操作：

• publish：发布托管应用。创建托管应用（name + files）或发布新版本（appId + files；新版本会在所有显示该应用的位置上线，rollback 可撤销）。publishTo 还会像 display_publish 一样将其放到屏幕上；以品牌或组织为目标时需要 confirm。需要 files。可能需要确认。
• rollback：回滚托管应用。在所有显示该应用的位置重新将较早的版本设为当前版本。可通过 display_library_read app_versions 列出版本。需要 appId、version。

读取设施可见的 Display Screens 内容库：媒体（图片、视频）、应用（网页、托管 HTML 应用、AI Agent 应用、CCTV 视图）和播放列表，以及可添加的 AI Agent 应用和 CCTV 来源。

每个项目都有一个 contentRef（media#…、app#…、playlist#…），供 display_publish 和播放列表使用。ownerScope 表示其所有者（facility#、brand# 或 org#）；内容只能在其所有者范围内发布。状态为 processing 的媒体尚未就绪；failed 表示需要重新上传。frameable: false 的网页无法在播放列表中播放，只能作为整页屏幕显示。带有 displayIssue 的项目会被屏幕跳过：未发布、已暂停、display-off、受众受限或没有 Custom Apps 的 AI Agent 应用；以及状态为 no-cctv、cctv-off（由设施管理员在 Display Screens 设置中为屏幕开启 CCTV）或 no-cameras 的 CCTV 视图。

操作：

• list：列出内容库项目。媒体和应用（分页；可按 type、kind、tag 或 name 筛选），或使用 type agent-apps 列出允许在屏幕上显示、可通过 display_publish content.agentAppId 发布的 AI Agent 应用。每个项目都有一个 type：media、app 或 agent-app。
• cctv_sources：列出 CCTV 来源。设施的摄像头和共享的 Live Views，供 display_publish content.cctv 使用，以及屏幕上的 CCTV 是否已开启。需要该设施的 CCTV 访问权限。
• get：获取内容库项目。按 contentRef 获取一个媒体项目、应用或播放列表。需要 contentRef。
• usages：内容的使用位置。使用某个媒体项目或应用的当前排程分配和播放列表（或某个播放列表的分配）。正在使用的内容无法删除。需要 contentRef。
• app_versions：列出托管应用版本。托管应用的各个版本及当前版本，供 display_hosted_apps_write rollback 使用。需要 appId。
• app_guidelines：托管应用指南。屏幕尺寸、设计规则、包大小限制、Display App SDK 和入门模板。为 display_hosted_apps_write publish 构建应用前请先调用。
• check_url：检查网页。网页能否在播放列表中显示（部分网站拒绝被嵌入框架），并提供显示效果的提示。拒绝嵌入的网页仍可作为整页屏幕显示。需要 url。
• playlists：列出播放列表。设施可见的播放列表（分页），每个都包含其项目（contentRef、duration、fit）。

添加和更改 Display Screens 内容库中的内容：上传图片和视频，创建网页、AI Agent 应用和 CCTV 视图应用，编辑名称、标签、时长和日期，删除未使用的项目，以及刷新应用预览。托管 HTML 应用通过 display_hosted_apps_write 发布；播放列表通过 display_playlists_write 管理。

图片请按 1920×1080（横屏）或 1080×1920（竖屏）设计。新媒体在生成网页版本期间状态为 processing；可以立即加入播放列表，就绪后即开始播放。ownerScope：facility（默认）、brand 或 organisation（brand 和 organisation 需要组织范围的访问权限）。

操作：

• upload_media：上传图片或视频。从公开的 https url（推荐；图片最大 25 MB，视频最大 200 MB）或带 mimeType 的 base64（最大 20 MB）添加图片或视频。支持 JPEG、PNG、WebP、GIF 图片；MP4、WebM、MOV 视频（转换为最高 1080p 的 H.264 MP4）。更大的视频：使用 create_video_upload。
• create_video_upload：开始上传大视频。适用于最大 2 GB 的视频：记录视频并返回预签名上传地址（在 upload.expiresAt 之前使用 upload.headers 将文件 PUT 到 upload.url），然后用其 contentRef 调用 transcode。需要 name、mimeType、bytes。
• transcode：处理视频。为屏幕转换视频：在 create_video_upload 之后、失败后重试，或用于屏幕无法播放的旧视频。需要 contentRef。
• create_app：添加应用。添加网页（kind url，传入 url；会检查能否嵌入框架）、AI Agent 应用（kind agent-app，传入来自 display_library_read list type agent-apps 的 agentAppId）或 CCTV 视图（kind cctv-view，归设施所有，需要 CCTV 访问权限）。需要 kind、name。
• update：更新内容库项目。更改媒体项目或应用的名称、标签或时长；媒体项目的 validFrom/validTo（ISO，null 表示清除；超出该时间范围时会被跳过）；网页的 url；或 CCTV 视图的摄像头、视图、布局或画质。需要 contentRef。
• delete：删除内容库项目。删除媒体项目或应用。当其位于当前排程或播放列表中时无法删除：错误信息会列出这些位置（请先通过 display_schedule_write delete 或 display_playlists_write save 移除）。需要 contentRef。需要确认。
• refresh_preview：刷新应用预览。为应用重新截图，用作其内容库预览（例如在页面更改后）。需要 contentRef。

创建、更新和删除 Display Screens 播放列表：按顺序循环播放的媒体和应用。更改会在数秒内同步到所有显示该播放列表的屏幕。使用 display_publish content.contentRef "playlist#" 发布播放列表。

操作：

• save：保存播放列表。创建：name + items（items 可以为空）。更新：playlistId + name、items、transition 中的任意项；items 会替换整个列表，因此请按顺序发送所有项目。
• delete：删除播放列表。删除一个播放列表。当其在任何位置处于发布状态时无法删除：错误信息会列出需要先移除的分配（display_schedule_write delete）。需要 playlistId。需要确认。

将内容放到 Display Screens 上：媒体项目、播放列表、应用、网页、AI Agent 应用或 CCTV 实时画面，目标可以是屏幕、分组、设施、其品牌或其组织。

mode：now（默认）替换目标平时显示的内容；scheduled 仅在每周时间段（设施时区）内和/或 from 与 to 之间显示；takeover 在 durationMin 内（或直到某个时间）中断所有内容，然后自动结束（可用 display_takeover_stop 提前停止）。屏幕先按层级决定显示内容（takeover > scheduled > default），再按目标的具体程度决定（screen > group > facility > brand > organisation）。

CCTV：屏幕附近的任何人都能看到实时摄像头画面。第一次调用会返回 requiresConfirmation（代码 CCTV_CONFIRMATION_REQUIRED）；请询问用户，然后使用 confirmCctv: true 再次调用。设施必须开启 "Allow CCTV on display screens"。

只有播放器模式的屏幕会显示已发布的内容；其他屏幕会列在 warnings 中。返回一个 batchId；使用它调用 display_schedule_write delete 可撤销整个发布。提供多个屏幕、分组或目标时，一次调用会作用于全部对象；对大量对象执行操作前请先与用户确认。

读取发布到 Display Screens 的内容：对于单个屏幕，读取其在某一时刻及某一时间范围内显示的内容（综合其继承的所有层级和目标得出）以及作用于它的分配；或读取发布到某个分组、设施、其品牌或其组织的分配。

display_schedule_write 更新或删除的对象就是分配 ID（as_…）和批次 ID（bt_…）。时间采用 ISO 格式；时间段使用设施时区。

操作：

• get：获取屏幕的排程。屏幕在 at（默认当前）显示的内容、从 from 到 to 的时间线（默认 24 小时），以及作用于它的每个分配。需要 screenId。
• list_assignments：列出分配。发布到某个分组（groupId），或发布到设施、其品牌或其组织（target，默认 facility）的分配。分页，最新更改在前。

更改发布到 Display Screens 的内容：编辑分配的时间、优先级或内容（可选择作用于整个发布），或移除一个分配或整个发布。可通过 display_schedule_read 查找 ID。从排程中移除内容不会将其从内容库中删除；如需提前结束接管但保留其历史记录，请使用 display_takeover_stop。

操作：

• update：更新分配。更改分配的时间（每周时间段、from/to；null 表示清除日期）、优先级或内容。applyToBatch 会对该发布的每个目标进行相同的更改。接管只能设置新的结束时间。CCTV 内容需要在用户同意后提供 confirmCctv。需要 assignmentId。
• delete：从排程中移除。移除一个分配（assignmentId）或某次发布的全部内容（batchId）。屏幕会在数秒内恢复为原本应显示的内容。需要确认。

向设施中的 Display Screens 发送实时命令：reload（播放器屏幕重新获取排程）、identify（闪烁显示屏幕名称和代码，以便在现场找到它）、displayOn/displayOff（电视面板）、rebootDevice（重启屏幕的电脑，黑屏 1–2 分钟；需要 confirm: true）或 osd（简短的屏幕消息；传入 message）。

通过 screenIds 和/或 groupIds（设施中这些分组的所有屏幕）选择屏幕，或使用 allScreens: true 选择设施中的所有屏幕（此时 displayOn/displayOff 也会作用于 Templated content 屏幕）。返回每个屏幕的结果。提供多个屏幕、分组或目标时，一次调用会作用于全部对象；对大量对象执行操作前请先与用户确认。

读取设施的 Display Screens：列出屏幕及其状态、当前和接下来显示的内容（可按分组、状态或显示模式筛选），获取单个屏幕的完整详情和时间线，或列出屏幕分组及其屏幕。

显示模式在用户界面中显示为 "Data Source"：player 为 "User managed content"，program-builder 为 "Templated content"（切勿对用户说 "Program Builder"），url 为 "Full-page website (Kiosk Mode)"。时间采用 ISO 格式；会返回设施时区。

操作：

• list：列出屏幕。设施中的屏幕（分页），每个都包含状态、最后心跳、分组、标签以及当前和接下来显示的内容。同时返回分组。
• get：获取屏幕。单个屏幕的完整详情（状态、心跳、播放器版本、最近错误），对于播放器屏幕，还包括其在某一时间范围内显示的内容（默认接下来 24 小时，最长 14 天）。需要 screenId。
• groups：列出屏幕分组。设施中的屏幕分组（分页），每个都包含其屏幕。

更改 Display Screens：通过配对码配对新屏幕；重命名屏幕、设置其分组和标签，或切换其显示模式（在用户界面中显示为 "Data Source"）；轮换播放器屏幕的令牌；为屏幕或内容创建限时预览链接；或将屏幕恢复出厂设置（将其从设施中移除）。

显示模式：player（"User managed content"）、url（"Full-page website (Kiosk Mode)"，传入 url，仅限 https）、program-builder（"Templated content"；切勿对用户说 "Program Builder"）。更改模式会立即重新加载屏幕并改变会员看到的内容，因此需要用户确认。

操作：

• update：更新屏幕。设置屏幕的名称、分组（ID 或名称；替换当前分组）、标签（替换现有标签）和/或显示模式。更改模式时会先返回 requiresConfirmation。需要 screenId。可能需要确认。
• rotate_token：轮换屏幕令牌。为播放器屏幕签发新令牌并重新加载；旧令牌随即失效。当屏幕的播放器 URL 可能已泄露时使用。需要 screenId。需要确认。
• create_preview_link：创建预览链接。一个限时有效的链接，用于显示屏幕当前显示的内容或内容的显示效果，也可指定未来的某个时间。在链接过期前，任何拥有该链接的人都能查看。
• reset：将屏幕恢复出厂设置。将屏幕从设施中移除并恢复出厂设置；已关机的屏幕会在下次上线时重置，然后显示其配对页面。传入 confirmName：与用户输入完全一致的屏幕名称。需要设备管理权限。需要 screenId、confirmName。需要确认。
• pair：配对新屏幕。通过配对页面上的 6 位字符代码将新屏幕添加到设施，然后重新加载。仅有 Display Screens 的设施会以 player 模式启动；同时拥有 Templated content 的设施由 mode 决定（默认 program-builder）。需要设备管理权限。需要 pairingCode、name。需要确认。

截取 Display Screen 当前显示的画面并返回图片，便于在发布后检查效果（布局、文字大小、没有内容被截断或滚动）。最多等待 15 秒让屏幕响应；离线屏幕会超时。同时返回该 JPEG 的门户 URL（仅限已登录用户，保留 10 分钟）。

截图可能包含实时 CCTV 画面和画面中的会员；请勿在对话之外分享。

Reads Display Screens settings for a facility: the fallback slate, polling and nightly reload, CCTV on screens; the screen power schedule (with the next days' on/off times); automations (brightness, bell volume, check-in power, round timer state); the brand's boot screen, screen defaults and templated content settings; and, with templated content, the scheduled program dates and the templated schedule.

Actions:

• settings: Get facility display settings. The fallback slate (message, background, logo, facility name), polling interval, nightly reload time and whether CCTV may be shown on screens.
• power_schedule: Get the power schedule. When screens turn on and off: the saved schedule (or the older automations' equivalent), the facility time zone and the on/off times for the next 7 days.
• power_schedule_preview: Preview a power schedule. The on/off times a schedule would give over the next 7 days, without saving it. Needs schedule.
• automations: Get display automations. Automatic brightness (day/night levels and triggers), bell volume levels and schedule (decimal hours, 6.5 = 06:30), check-in power, and the round timer state, for one or several facilities. usesGlobalDefaults is true until the facility saves its own.
• boot_screen: Get the brand's boot screen. The image the facility's brand shows while screens start up (fit, background, image URLs) and whether you can change it (organisation admins).
• screen_defaults: Get the brand's screen defaults. The settings a screen starts with when it is paired at one of the brand's facilities (orientation, screen mirroring, session timer, speaker control, duress monitoring, camera restreaming, Wi-Fi support) and whether you can change them (organisation admins). Screens that are already paired keep their own settings; see device_inventory_read for those.
• templated: Get the brand's templated content settings. What templated content screens and the Schedule show for the facility's brand (source name, workout names, programs and training phases, look-ahead days) and whether you can change it (organisation admins).
• program_dates: List scheduled program dates. The dates with a workout program, from the start of this month to the brand's look-ahead. Needs templated content (Program Builder) at the facility.
• templated_schedule: Get the templated schedule. Programs and training phases between two dates (YYYY-MM-DD, at most 62 days), as the brand shows them. Needs templated content (Program Builder) at the facility. Needs from, to.

更改设施的 Display Screens 设置：备用画面、轮询和夜间重新加载，以及 "Allow CCTV on display screens"；屏幕电源排程；以及自动化（亮度、铃声音量、签到开屏）。未提供的字段保留当前值。品牌范围的设置（启动画面、Templated content）请使用 display_brand_settings_write。

操作：

• save_settings：保存设施显示设置。没有排程内容时显示的备用画面、轮询间隔（30–300 秒）、夜间重新加载时间（HH:mm）和 allowCctv。开启 allowCctv 需要用户确认，并需要具有 CCTV 访问权限的设施管理员。可能需要确认。
• save_power_schedule：保存电源排程。更改屏幕开关的时间；传入的字段会合并到已保存的排程中。返回未来 7 天的开关时间。请先通过 display_settings_read power_schedule_preview 检查。需要 schedule。
• save_automations：保存显示自动化。更改自动亮度、铃声音量和签到开屏设置。此后设施将使用自己的设置，而不是全局默认值。

立即结束正在进行的 Display Screens 接管：针对某次发布（来自 display_publish 的 batchId）、针对目标（默认：发布到整个设施的接管），或使用 allScreens 结束发布到该设施、其屏幕或其分组的所有接管。品牌和组织级接管只能通过 batchId 停止。屏幕会在数秒内恢复为排程内容或默认内容；返回已停止的数量。提供多个屏幕、分组或目标时，一次调用会作用于全部对象；对大量对象执行操作前请先与用户确认。

控制 Templated content 屏幕（display_screens_read 中显示模式为 "Templated content" 的屏幕）：在屏幕上加载某天的训练课程，或控制轮次计时器。User managed content 屏幕和整页网站屏幕不受影响。

操作：

• load_program：加载训练课程。从设施的数据源，在一个或多个设施的每个 Templated content 屏幕上加载某个日期的训练课程（YYYY-MM-DD，默认今天）；屏幕会在数秒内重新加载。用于显示今天或其他日期的训练，或在屏幕显示错误的训练时使用。涉及多个设施时需要 confirm。可能需要确认。
• clock：控制轮次计时器。在 Templated content 屏幕上播放、暂停、重新开始或停止轮次计时器，将轮次声音静音或取消静音，设置铃声音量（setvolume 配合 volume 0–100）或查询其状态。需要设施拥有 Templated content。需要 command。