跳转至

媒体播放

OpenClaw 聊天客户端会内联播放助手的音频和视频附件。 Gateway 将这些附件置于会话级访问控制之后,提供可定位的字节范围,并可为并非在所有客户端都安全的已识别格式准备可移植播放版本。

本页介绍 OpenClaw 客户端中的播放。通道投递、入站媒体理解和实时语音对话使用独立路径;参见 图像和媒体支持、 媒体理解 和 Talk mode。

客户端支持

客户端 播放路径 操作员说明
Control UI 主题化内联音频卡片和原生视频控件 音频卡片提供播放/暂停、定位、已播放和总时长、下载、语音留言徽章以及键盘控制。空格键切换播放;左/右方向键按五秒定位。开始一个音频卡片会暂停前一个。可从聊天附件选择器上传视频。
iOS and macOS 音频使用 AVAudioPlayer,视频使用 AVPlayer 内联媒体与 Talk 和 Listen 协调,使两条语音路径不会互相覆盖。对于固定 TLS 的 Gateway,应用会在视频播放前执行有界认证下载,而不是绕过证书固定。
Android Media3 ExoPlayer 应用通过已认证的 Gateway HTTP 客户端流式传输视频,请求 Android 音频焦点,并与 Talk/TTS 协调附件播放。缓存的转录媒体行在离线时仍可见,但播放需要连接以获取新的媒体票据。
Linux companion 伴侣应用 WebView 中的 Control UI 编解码器可用性来自 GStreamer。已发布包包含或声明预期的编解码器插件;参见 Linux 媒体编解码器。

可移植格式

Gateway 将这些格式归类为浏览器、Apple 播放器和 Android Media3 共享的可移植原生集合:

类型 可移植原生输入 已识别转码输入 播放目标
音频 MP3;M4A/MP4 中的 AAC;PCM WAV AAC、AIFF、AMR/AMR-WB、CAF、FLAC、Ogg/Opus/Vorbis、WebM 音频、WMA M4A 中的 AAC(audio/mp4)
视频 具有可移植配置文件和 4:2:0 像素格式的 H.264 MP4;存在时使用 AAC 或 MP3 音频 AVI、FLV、Matroska/MKV、QuickTime/MOV、WebM、ASF、WMV 4:2:0 像素格式的 H.264/AAC MP4,最大 1920×1080

Linux companion 还可以播放其已安装 GStreamer 插件提供的格式。浏览器和操作系统更新可能会添加原生格式,但上表是 OpenClaw 面向的跨客户端约定。

延迟播放版本

两个 Gateway 字节路由都接受 ?playback=1:/api/chat/media/outgoing/.../full 下的托管附件路由,以及 Control UI 助手媒体路由。附件元数据可以报告 playback: "native" 或 playback: "transcode",以便客户端明确选择播放版本。

播放转换是延迟的:

  1. 原生源原样通过。
  2. 已识别的非可移植源会启动一个有界的 ffmpeg 任务。在播放版本准备期间,路由返回 HTTP 202 和 { "status": "preparing" }。
  3. 后续请求会收到缓存的 M4A 或 MP4 播放版本。
  4. 如果检查或转换不可用、失败或超出限制,路由会回退到原始字节。客户端随后可以显示其不可播放媒体回退,并保持下载操作可用。

Control UI 在加载内联播放器之前使用 HEAD 检查播放版本就绪状态。转换待处理时,它显示 正在准备播放,并在播放不可用时保持下载操作可用。

转码接受最长 20 分钟的源,并且不会提高常规音频或视频字节上限。缓存的播放版本使用固定的七天保留期,Gateway 维护会在启动时和每小时强制执行,独立于 attachments.ttlHours。

托管附件和访问

要在助手回复中附加本地文件,请将 MEDIA:/absolute/path/movie.mp4 单独放在一行。会话现有的媒体访问策略必须允许该路径。 Control UI 会以有界流式方式暂存允许的本地音频和视频,并通过 Gateway 的已认证、可定位媒体路由播放它们。对于应用或开发服务器,请使用门户;对于文件,请使用 MEDIA:<path>。

远程 MEDIA: 引用必须是无需凭据的公共 HTTPS URL。 被拒绝的引用会产生可见的附件失败,并说明使用允许的 URL 或本地路径;它们不会显示为原始指令链接。 提及 MEDIA: 的内联文本和围栏代码示例仍保持为文本。

代理生成的音频和视频存储为受管媒体工件。图像保留其独立的受管图像工件族。原生客户端通过 artifacts.download 解析工件,当工件以字节存储时返回内联 base64 字节,当它由 Gateway 管理时返回短期有效的票据化 URL。

受管下载票据会检查当前会话访问权限以及可见历史中选定消息的附件引用。对于已索引消息,签发票据不会读取原始文件或验证无关的转录负载。HTTP 请求会单独传输文件。

下载文件名会保留 Unicode 字符和字面百分号序列,例如 %20。

原生客户端会针对已连接的 Gateway URL 解析票据化媒体,并保留其反向代理路径前缀。通过 wss://gateway.example/openclaw 访问的 Gateway 会在 https://gateway.example/openclaw/api/chat/media/outgoing/ 下加载受管媒体,而不是服务器根。

票据化字节路由支持:

  • 用于定位的 Range 请求,返回 HTTP 206 Partial Content
  • 用于安全恢复不可变受管原始文件的 ETag 和 If-Range
  • 具有相同内容元数据且无响应主体的 HEAD 请求

对于不可变原始文件,If-None-Match 使用弱比较来比较完整的带引号标签。带引号标签内的逗号和星号是字面量;只有独立的 * 才是通配符。不匹配的标签会保持正常的完整或范围响应不变。

本地助手文件可能会更改,并且播放版本可能在转换重试后可用。这些响应会在没有可复用验证器的情况下重新验证:缓存的 ETag 或修改日期无法抑制最新字节,并且 If-Range 请求会收到完整表示。普通 Range 请求仍支持定位。受管播放响应仍仅对客户端缓存私有。

不要将票据化 URL 复制到持久配置中。客户端在需要时会从已认证的 Gateway 重新获取票据。

元数据与限制

聊天附件可能包含 sizeBytes、durationMs、width 和 height。OpenClaw 还会在可用时使用 ffprobe 填充音频时长以及视频时长/尺寸,用于媒体事实和 Control UI ?meta=1 可用性检查。视频尺寸会考虑非方形像素和四分之一圈显示旋转;图像尺寸会考虑 EXIF 方向。检查是尽力而为的:缺失或失败的检查会使字段缺失,而不是拒绝附件。Gateway 会共享对同一本地文件的并发元数据检查,并在该文件未更改时复用成功结果。替换或编辑文件会触发新的检查;失败的检查仍可重试。不同文件会在有界的检查队列中等待。如果队列已满,元数据会报告可重试的临时不可用,并且播放保持为准备中。断开连接的请求停止等待,没有剩余查看者的排队检查会立即释放其队列槽位。排队读取在打开并检查文件之前会重新检查当前访问权限。繁忙的检查器不会丢弃出站附件;其可选播放元数据可以保持缺失。出站回复创建使用立即检查准入,不会排在排队查看者请求之后等待。

Control UI 受管助手附件使用以下每个文件的上限:

类型 最大大小
图像 12 MiB
本地音频 4 GiB
本地视频 4 GiB

这些是播放/存储上限,而不是单独的媒体理解限制。更大的本地文件限制不会更改通道出站限制、远程或 data URL 摄取限制,或基于缓冲区的远程工作区读取器的限制。它也不会提高转码预算;大型原生 MP4 文件可以直接播放而无需转换。有关转录和描述限制,请参阅图像和媒体支持。

故障排除

时长或尺寸缺失

检查 ffprobe 是否已安装在 Gateway 主机上,并且在其 PATH 中可见:

ffprobe -version

已经可移植的文件即使没有元数据也可以正常播放。

已识别格式下载而非播放

检查 Gateway 主机上的两个媒体工具:

ffmpeg -version
ffprobe -version

ffprobe 对编解码器和时长进行分类;ffmpeg 创建可移植播放版本。如果任一环节无法安全处理源文件,OpenClaw 会提供原始文件,客户端保留其回退/下载路径。

播放停留在准备中状态

第一个播放版本请求是异步的。请短暂等待后重试。非常大的、时长超过 20 分钟的、无法探测的或不受支持的源会保持原始字节回退,而不是阻塞 Gateway。

Linux 报告编解码器错误

使用Linux 媒体编解码器中的软件包和源码构建说明。.deb 依赖于所需的 GStreamer 插件软件包;AppImage 包含由发布构建安装的媒体框架和编解码器。

Android 离线时显示媒体行

这是预期行为。Android 会缓存转录元数据,而不是附件字节或其短期下载能力。重新连接,然后再次播放,以便应用可以请求新票据。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw