playback

为播放器提供播放线路。App 会在开始播放、切换线路或手动刷新时调用 playback 扩展。该扩展不会显示在 Dashboard 中。

widget 中的播放按钮和详情页中的播放操作均使用同一套解析流程和此 protocol。请勿在 widget 中返回播放 URL。

字段

字段	必填	含义
type	是	"playback"
id / title	是	服务选择器里的名称
accepts	是	{ sources, mediaTypes? }
cache	否	默认 ttlSeconds: 0
sources	是	protocol 方法

Protocol

sources(ctx, input) => Promise<PlaybackSource[]>

input: {
  ref: MediaRef;
  instanceId?: string;
  params?: Record<string, unknown>;
  season?: number;
  episode?: number;
}

空数组表示当前没有可用线路，不属于错误。上游服务不可用时，应抛出 ExtensionError。

PlaybackSource：

字段	必填	规则
id	是	稳定标识，用于记录用户选中的线路
name	是	线路名
url	是	最终播放地址
description	否	分辨率、编码等
headers	否	播放请求头，不含内部控制键
player	否	system 或 app
skipRedirectProbe	否	为 true 时跳过播放前的 GET 探测，适用于直播或一次性 URL

从哪里点播放

小组件播放按钮 ──┐
                 ├── Open { kind: "play", ref, episode?, origin }
详情页播放 ──────┘
                      → 解析 playback
                      → sources(ctx, { ref, season, episode })
                      → 播放器

从小组件直接播放时不会调用 detail。因此：

• 电影可以直接播放。
• 剧集条目必须包含 episode，否则模板不显示播放按钮。
• 如需先查看简介或选择季、集，应先进入详情页。

sources 默认不缓存。请勿将签名线路或直播地址写入 widget 的 ListItem 或 DetailItem。播放按钮的显示条件见用户指南 · 播放。