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

前提条件

• 外挂字幕为高级版或企业版功能。请确保您已购买高级版或企业版 License，购买方式详见 License 包管理。

  注意

  自 1.36.1 版本起，外挂字幕功能由增值服务调整至高级版和企业版。如您集成 1.36.1 之前的版本且想要使用此功能，请升级至最新版本。

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

  • 如果您已有单独的字幕文件，可选择在视频点播控制台指定空间内的视频管理 > 视频详情页面上传字幕文件，如下图所示：
    
  • 如果您没有单独的字幕文件，可通过视频点播媒体处理服务生成字幕文件，具体请见智能字幕。

• 在接入外挂字幕功能前，请阅读集成准备以及快速开始 - 初始化点播 SDK 章节，确保已经完成 SDK 的初始化。

开启外挂字幕功能

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

// 外挂字幕功能总开关，play 前调用
// 0: 关闭外挂字幕功能；1: 开启外挂字幕功能
mVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_OPEN_SUB_THREAD, 1);
// 外挂字幕加载优化开关
// 0: 关闭外挂字幕加载优化；1: 开启外挂字幕加载优化
mVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_OPT_SUB_LOAD_TIME, 1);

设置字幕源

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

使用 Vid + SubtitleToken 方式

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

String vid = "YOUR_VIDEO_ID"; // AppServer 下发
String playAuthToken = "YOUR_PLAYAUTHTOKEN"; // AppServer 下发
String subAuthToken = "YOUR_SUBAUTHTOKEN"; // AppServer 下发

// 设置 Vid 播放源
VidPlayAuthTokenSource vidSource = new VidPlayAuthTokenSource.Builder()
        .setVid(vid)
        .setPlayAuthToken(playAuthToken)
        .build();
mVideoEngine.setStrategySource(vidSource);
// 设置字幕鉴权 token
mVideoEngine.setSubAuthToken(subAuthToken);
// 设置播放源获取成功回调
mVideoEngine.setVideoInfoListener(new VideoInfoListener() {
    @Override
    public boolean onFetchedVideoInfo(VideoModel videoModel) {
        // 获取视频数据成功回调
        Log.v("VideoPlay", "onFetchedVideoInfo " + videoModel);
        if (videoModel == null) return false;
        if (mVideoEngine == null) return false;
        
        // 请求中、英字幕文件的 ID 数组
        List<String> subtitleIds = new ArrayList<>();
        // 获取当前所有字幕语言的接口
        List<SubInfo> subInfoList = mVideoEngine.supportedSubInfoList();
        // 字幕语言映射表见：https://www.volcengine.com/docs/4/1186356
        if (subInfoList != null && subInfoList.size() > 0) {
            for (SubInfo info : subInfoList) {
                if (info.mLanguageId == 1) { 
                    subtitleIds.add(info.mSubId); // CN
                } else if (info.mLanguageId == 2) {
                    subtitleIds.add(info.mSubId); // EN
                }
            }
        }
        String subIds = trans(subtitleIds); // 省略实现，将 subtitleIds 转为逗号分割的字符串，如："1111,2222"
        // 传入字幕语言 ID 列表
        mVideoEngine.setStringOption(PLAYER_OPTION_SUB_IDS, subIds);
        return false;
    }
});

使用 DirectURL 方式

使用 DirectURL 方式设置字幕源，您需要实现 SubDesInfoModelProvider 协议构建外挂字幕源，参考 JSON 字幕信息示例。示例代码如下：

final String vid = "YOUR_VIDEO_ID"; // 视频源与 vid 必须一一对应
final String url = "http://www.example.com/h264.mp4";
final String cacheKey = TTVideoEngine.computeMD5(url);
final String subtitleJSONStr = ""; // 详见本文 JSON 字幕信息示例章节

// 设置 DirectURL 播放源
DirectUrlSource directUrlSource = new DirectUrlSource.Builder()
        .setVid(vid)
        .addItem(new DirectUrlSource.UrlItem.Builder()
                .setUrl(url)
                .setCacheKey(cacheKey)
                .build())
        .build();
ttVideoEngine.setStrategySource(directUrlSource);

// 设置 DirectURL 模式下的字幕源
SubDesInfoModel subtitleModel = null;
try {
    JSONObject subtitleJSON = new JSONObject(subtitleJSONStr);
    subtitleModel = new SubDesInfoModel(subtitleJSON);
} catch (JSONException e) {
    e.printStackTrack();
}
// 必须在设置视频源之后设置 subtitleModel
if (subtitleModel != null) {
    mVideoEngine.setSubDesInfoModel(subtitleModel);
}

控制字幕

开启/关闭字幕输出

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

// 字幕开关，起播时或者播放过程中控制打开或者关闭字幕
// 1: 输出字幕；0: 停止输出字幕
mVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_OPEN_SUB, 1);
// 显示字幕 TextView
textView.setVisibility(View.VISIBLE);

切换字幕

参考以下示例代码切换不同语言的字幕：

// 业务端维护字幕 ID 与语言的对应关系，方便扩展
mVideoEngine.setIntOption(PLAYER_OPTION_SWITCH_SUB_ID, sub_id);

设置字幕回调

调用 setSubInfoCallBack 设置字幕相关回调。示例代码如下：

mVideoEngine.setSubInfoCallBack(new SubInfoSimpleCallBack() {
    @Override
    public void onSubPathInfo(String subPathInfoJson, Error error) {
        // vid + subTitleToken 播放，字幕列表信息回调
    }

    @Override
    public void onSubInfoCallback(int code, String infoJson) {
        // 字幕信息回调
        JSONObject jsonObject = new JSONObject(infoJson);
        String subtitle = jsonObject.optString("info");
        textView.setText(subtitle); // 设置给字幕 TextView
    }
        
    @Override
    public void onSubSwitchCompleted(int success, int subId) {
        // 字幕语言切换回调
    }
    
    @Override
    public void onSubLoadFinished(int success) {
        // 字幕文件下载结果回调

    }
})

参考信息

JSON 字幕信息示例

{
  "list": [
    {
      "id": 0,
      "language": "rus-RU",
      "language_id": 6,
      "url": "https://***.com/cbebedaade0947ce51a*******17f0b13/6087d12f/video/tos/cn/tos-cn-o-0004/52ce3882d70941d5b660913cbd83d969/",
      "expire": 1619513647,
      "format": "webvtt",
      "sub_id": 328934091
    },
    {
      "id": 1,
      "language": "cmn-Hans-CN",
      "language_id": 1,
      "url": "https://***.com/93adb942***bdfce8cb/6087d12f/video/tos/***a4122dac42d69e8233a4dfda82fe/",
      "expire": 1619513647,
      "format": "webvtt",
      "sub_id": 429984091
    },
    {
      "id": 2,
      "language": "cmn-Hans-CN|eng-US",
      "language_id": 5,
      "url": "https://***.com/d782d36702***7b9719/6087d12f/video/tos/***5f0d106146a19ad566b967211091/",
      "expire": 1619513647,
      "format": "webvtt",
      "sub_id": 829987091
    }
  ]
}

字段说明：

• sub_id 为字幕 ID，用于在播放器中区分不同的字幕。
  • 如果您是从视频点播服务获取字幕，可使用视频点播服务下发的字幕数据中的 SubtitleId 字段。
  • 如果您是自行拼装字幕 JSON，可以使用 Index 标识来区分字幕。
• language_id 为语言 ID，您需要自行维护字幕 ID 与语言 ID 的映射关系。
• language 和 language_id 的取值可参考字幕语言。
• url 为字幕文件 URL。
• id 可设为索引 Index。
• expire 为字幕 URL 过期时间。如果没有过期时间，则可不传。