外挂字幕是指字幕文件与视频文件分开存储，用户在播放视频时按需导入字幕文件。播放器 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 完成后调用 player.setSelectedSubtitle，传入目标 TTSubtitle.subtitleId。Vid 源可从 onSubtitlesFetched 返回的字幕列表中选择目标字幕，DirectURL 源使用设置字幕源时提供的字幕 ID。以下函数中的 player 为已创建的播放器实例，subtitleId 为实际目标字幕 ID：

Future<void> switchSubtitle(VodPlayerFlutter player, int subtitleId) async {
  await player.setSelectedSubtitle(subtitleId);
}

设置字幕回调 #

在已创建的 player 实例上赋值以下回调，并在准备播放前完成注册。调用 setSubtitleShow(true) 开启字幕输出。回调参数由 SDK 传入，可在回调中更新业务界面或记录结果。

// Vid + SubtitleToken 字幕列表请求结果
player.onSubtitlesFetched = (success, subtitles, error) {
  if (!success || subtitles == null) {
    print('字幕列表获取失败：$error');
    return;
  }
  for (final subtitle in subtitles) {
    print('可用字幕 ID：${subtitle.subtitleId}');
  }
};

// 字幕文件加载结果
player.onSubtitleFileLoadResult = (success) {
  print('字幕文件加载成功：$success');
};

// 字幕切换结果
player.onSubtitleSelected = (success, subtitleId) {
  print('字幕 $subtitleId 切换成功：$success');
};

// 当前字幕内容及时间信息
player.onSubtitleShow = (content, pts, duration) {
  print('字幕：$content，时间：$pts，时长：$duration');
};

player.setSubtitleShow(true);

#