外挂字幕是指字幕文件与视频文件分开存储，用户在播放视频时按需导入字幕文件。播放器 SDK 当前支持添加 WebVTT (Web Video Text Tracks) 格式的字幕文件。这种方式的优势在于其灵活性，用户可以根据实际需求选择是否导入字幕文件，或者选择加载不同语言的字幕。更重要的是，您无需进行额外的视频转码，只需要在播放端进行适当设置，便可显示字幕。本文为您介绍使用播放器 SDK 时如何添加外挂字幕。

前提条件

如果您通过 Vid 方式播放视频，需要准备字幕文件：

• 如果您已有单独的字幕文件，可将字幕文件上传至视频点播服务并与 Vid 绑定。具体请见上传字幕文件并绑定 Vid。
• 如果您没有单独的字幕文件，可通过视频点播媒体处理服务生成字幕文件。具体请见智能生成字幕文件。

开启外挂字幕功能

参考以下示例代码开启外挂字幕功能：

// 开启外挂字幕
player.setSubtitleEnabled(true); // prepare 之前调用，开启外挂字幕

设置字幕源

播放器 SDK 支持以下两种方式设置字幕源。您需根据实际情况选择。

使用 Vid + SubtitleToken 方式

使用 Vid + SubtitleToken 方式设置字幕源的示例代码如下：

// 设置  Vid 字幕源
Future<void> setSubtitleAuthToken(String subtitleAuthToken)

使用 DirectURL 方式

使用 DirectURL 方式设置字幕源的示例代码如下：

// 设置  DirectURL 字幕源
// createPlayer 之后，prepare 之前调用
Future<void> setSubtitles(List<TTSubtitle> subtitles)

控制字幕

开启/关闭字幕输出

参考以下示例代码在起播时或者播放过程中控制开启或者关闭字幕输出：

// 开启或者关闭字幕输出
// createPlayer 之后调用
player.setSubtitleShow(true);

切换字幕

参考以下示例代码在起播时或者播放过程中切换字幕：

// 切换字幕
// createPlayer 之后调用
Future<void> setSelectedSubtitle(int subtitleId); 

设置字幕回调

参考以下示例代码接收字幕回调。设置字幕回调前需要先调用 setSubtitleShow(true) 开启字幕显示。

// vid + subTitleToken 播放，字幕列表信息回调
Future<void> Function(bool success, List<TTSubtitle>? subtitles, TTError? error)? onSubtitlesFetched;

// 字幕文件加载结果回调
Future<void> Function(bool success)? onSubtitleFileLoadResult;

// 字幕语言切换回调
Future<void> Function(bool success, int subtitleId)? onSubtitleSelected;

// 字幕信息回调
Future<void> Function(String? content, double pts, double duration)? onSubtitleShow;