subtitle

为播放器提供字幕服务。用户在播放器中使用已启用的字幕扩展，此过程与条目的来源 widget 无关，也不使用 detail / playback 的同源解析流程。

字段

字段	必填	含义
type	是	"subtitle"
id / title	是	服务选择器名称
accepts	否	播放器不会根据 accepts 筛选扩展。媒体库文件、Emby 和 Plex 条目可能不包含 MediaRef
cache	否	match / search 默认 ttlSeconds: 3600；file 默认 0
match / search / file	是	protocol

Protocol

match(ctx, input) => Promise<SubtitleHit[]>
input: {
  title?: string;
  season?: number;
  episode?: number;
  fileName?: string;
  fileSize?: number;
  fileHash?: string;   // 仅当用户打开「本地文件 Hash」：前 16MB MD5
  duration?: number;
  ref?: MediaRef;      // 有 TMDB 等身份时带上，不再必填
}

search(ctx, input) => Promise<SubtitleHit[]>
input: { query: string; ref?: MediaRef; season?: number; episode?: number }

file(ctx, input) => Promise<SubtitleFile | null>
input: { hit: SubtitleHit }

SubtitleHit: {
  id: string;
  title: string;
  language: string;    // BCP 47
}

SubtitleFile: {
  url: string;         // http(s) 或 bundle://，指向单个字幕文件
  fileName?: string;
}

match 用于播放开始时的自动匹配，search 用于处理用户输入的关键词。没有匹配字幕时返回空数组。

SubtitleHit 必须能够被完整保存并再次传入 file。下次播放时，宿主会使用保存的 hit 重新获取文件，不要求该 hit 再次出现在 match 结果中。

url 必须指向单个字幕文件，支持 srt、ass、ssa、vtt、sub 和 sup。对于压缩包，扩展应在 file 中完成解压，并返回其中目标字幕文件的地址。