外挂字幕指与视频文件分离的字幕文件，用户可在播放时按需导入。播放器 SDK 支持添加 WebVTT (Web Video Text Tracks) 和 SRT (SubRip Text) 格式的外挂字幕。外挂字幕的优势在于其灵活性，用户可按需选择是否加载字幕以及加载何种语言的字幕，且无需进行视频转码，只需在播放端设置即可显示。本文介绍如何使用播放器 SDK 添加外挂字幕。
注意
自 1.36.1 版本起，外挂字幕功能由增值服务调整至高级版和企业版。若您集成 1.36.1 之前的版本且想要使用此功能，请升级至最新版本。
参考以下示例代码开启外挂字幕功能：
// 外挂字幕功能总开关，play 前调用 // 0: 关闭外挂字幕功能；1: 开启外挂字幕功能 mVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_OPEN_SUB_THREAD, 1); // 外挂字幕加载优化开关 // 0: 关闭外挂字幕加载优化；1: 开启外挂字幕加载优化 mVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_OPT_SUB_LOAD_TIME, 1); // 使用数据加载模块 MDL 加载外挂字幕，提升加载成功率 // 0: 不使用 MDL 加载外挂字幕；1: 使用 MDL 加载外挂字幕 mVideoEngine.setIntOption(PLAYER_OPTION_SUB_ENABLE_MDL, 1);
播放器 SDK 支持以下两种方式设置字幕源。您需根据实际情况选择。
使用 Vid + SubtitleToken 方式设置字幕源的示例代码如下：
说明
您可在应用服务端通过视频点播服务端 SDK 签发字幕鉴权 Token。
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 方式设置字幕源，您需要实现 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(); mVideoEngine.setStrategySource(directUrlSource); // 设置 DirectURL 模式下的字幕源 SubDesInfoModel subtitleModel = null; try { JSONObject subtitleJSON = new JSONObject(subtitleJSONStr); subtitleModel = new SubDesInfoModel(subtitleJSON); } catch (JSONException e) { e.printStackTrace(); } // 必须在设置播放源之后且在 play 之前设置 subtitleModel if (subtitleModel != null) { mVideoEngine.setSubDesInfoModel(subtitleModel); }
参考以下示例代码在起播时或者播放过程中控制开启或者关闭字幕输出：
// 字幕开关，起播时或者播放过程中控制打开或者关闭字幕 // 1: 输出字幕；0: 停止输出字幕 mVideoEngine.setIntOption(PLAYER_OPTION_ENABLE_OPEN_SUB, 1); // 显示字幕 TextView textView.setVisibility(View.VISIBLE);
参考以下示例代码切换不同语言的字幕：
说明
您需传入字幕语言 ID，详见语言。
// 业务端维护字幕 ID 与语言的对应关系，方便扩展 mVideoEngine.setIntOption(PLAYER_OPTION_SWITCH_SUB_ID, sub_id);
在调用 play 播放前，调用 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) { // 字幕文件下载结果回调 } });
可通过实现字幕预加载功能提升用户观看视频时字幕的加载速度和成功率。
在初始化 SDK 前，开启预加载策略 V2 版本，并启用预加载策略。
// 开启预加载策略 V2 版本 StrategyManager.setVersion(StrategyManager.VERSION_2); // 初始化播放器 SDK Env.init(/* 省略初始化代码 */); // 开启并使用预加载策略 TTVideoEngine.enableEngineStrategy(STRATEGY_TYPE_PRELOAD, STRATEGY_SCENE_SMALL_VIDEO);
构建字幕源和播放源。
// 1. 创建字幕源 Model SubDesInfoModelProvider subtitleModel = null; String subtitleJson = "{ \"list\": [ { \"language\": \"cmn-Hans-CN\", \"language_id\": 1, \"url\": \"https://example.com/subtitle1.vtt\", \"cache_key\": \"cachekey_1\", // 字幕缓存 key \"expire\": 1618253637, \"format\": \"webvtt\", \"sub_id\": 0 }, { \"language\": \"eng-US\", \"language_id\": 2, \"url\": \"https://example.com/subtitle2.vtt\", \"cache_key\": \"cachekey_2\", // 字幕缓存 key \"expire\": 1618253637, \"format\": \"webvtt\", \"sub_id\": 1 } ] }"; try { subtitleModel = new SubDesInfoModel(new JSONObject(subtitleJson)); } cache (JSONException e) { e.printStackTrace(); } int subtitleId = ""; // 预加载的字幕 ID String vid = ""; String videoUrl = ""; String videoCacheKey = ""; // 2. 在播放源中设置字幕源 Model DirectUrlSource directUrlSource = new DirectUrlSource.Builder() .setVid(vid) .addItem(new UrlItem.Builder() .setUrl(videoUrl) .setCacheKey(videoCacheKey) .build()) .setSubtitleModel(subtitleModel) .setSubtitleId(subtitleId) .build(); // 3. 跟随策略模块设置播放源列表，SDK 内部会自动预加载字幕源 TTVideoEngine.setStrategySources(list); // TTVideoEngine.addStrategySources(list);
在初始化 SDK 前，开启预加载策略 V2 版本，并启用预加载策略。
// 开启预加载策略 V2 版本 StrategyManager.setVersion(StrategyManager.VERSION_2); // 初始化播放器 SDK Env.init(/* 省略初始化代码 */); // 开启并使用预加载策略 TTVideoEngine.enableEngineStrategy(STRATEGY_TYPE_PRELOAD, STRATEGY_SCENE_SMALL_VIDEO); // 设置预加载任务工厂，用于预加载策略内部构件预加载任务 StrategyManager.instance().setPreloadTaskFactory(new PreloadTaskFactory() { @Override public PreloaderVidSubtitleItem createSubtitleVidItem(VidPlayAuthTokenSource vidSource, long preloadSize) { final PreloaderVidSubtitleItem item = PreloadTaskFactory.super.createSubtitleVidItem(vidSource, preloadSize); item.setFetchEndListener(new PreloaderVidSubtitleItemFetchListener() { @Override public void onGetPlayInfoResult(VideoModel videoModel, Error error) { // 若支持用户切换视频清晰度，需要通过 item.setResolution 方法重新设置清晰度，覆盖 VidPlayAuthTokenSource 中的清晰度 if (videoModel == null) return; Resolution resolution = Resolution.High; // 480P resolution = TTVideoEngine.findDefaultResolution(videoModel, resolution); final VideoInfo videoInfo = videoModel.getVideoInfo(resolution, false); if (videoInfo == null) return; item.setResolution(videoInfo.getResolution()); } @Override public void onGetSubtitleInfoResult(SubDesInfoModel subDesInfoModel, Error error) { // 若下发多个语言的字幕文件，则需要根据语言来查找对应的字幕 id，通过 item.setSubtitleId 设置后才能预加载对应语言字幕 if (subDesInfoModel == null) return; final List<SubModelProvider> subInfos = subDesInfoModel.getSubModelList(); if (subInfos == null || subInfos.isEmpty()) return; // 语言 ID 枚举参考官网文档：https://www.volcengine.com/docs/4/1186356 final int languageId = 1; // 用户默认选中字幕语言，比如：中文 Integer subtitleId = findPreloadSubtitleIdByLanguageId(subInfos, languageId); if (subtitleId != null) { item.setSubtitleId(subtitleId); } } }); return item; } });
构造用于预加载的 Vid 播放源时，除了视频的 vid 和 playAuthToken，还需提供字幕鉴权 token。
// 1. 构造 Vid 播放源 String vid = "your video id"; String playAuthToken = "your video playAuthToken"; Resolution resolution = Resolution.SuperHigh; // 720P String subtitleAuthToken = "your subtitleAuthToken"; // 字幕鉴权 token VidPlayAuthTokenSource vidSource = new VidPlayAuthTokenSource.Builder() .setVid(vid) .setPlayAuthToken(playAuthToken) .setResolution(resolution) .setSubtitleAuthToken(subtitleAuthToken) .build(); // 2. 跟随策略模块设置播放源列表，内部会自动预加载字幕源。 TTVideoEngine.setStrategySources(list); TTVideoEngine.addStrategySources(list);
使用字幕预加载必须要开启数据加载模块 MDL 来加载外挂字幕。
// 0: 不使用 MDL 加载外挂字幕；1: 使用 MDL 加载外挂字幕 mVideoEngine.setIntOption(PLAYER_OPTION_SUB_ENABLE_MDL, 1);
指定播放的字幕 ID。确保播放时设置的字幕 ID 与预加载播放源中的字幕 ID 一致。
mVideoEngine.setIntOption(PLAYER_OPTION_SWITCH_SUB_ID, sub_id);
监听命中回调：通过 VideoEngineInfoListener 监听 USING_MDL_HIT_CACHE_SIZE_SUBTITLE 事件。通过判断 cacheSize 是否大于 0，可以确认是否命中了字幕缓存。若未命中，请检查预加载任务是否成功，以及播放和预加载的 subtitleId 是否匹配。
// TTVideoEngine 实例设置监听 mVideoEngine.setVideoEngineInfoListener(new VideoEngineInfoListener() { @Override public void onVideoEngineInfos(VideoEngineInfos videoEngineInfos) { if (videoEngineInfos == null) { return; } // 字幕缓存命中监听 if (videoEngineInfos.getKey().equals(USING_MDL_HIT_CACHE_SIZE_SUBTITLE)) { // 起播命中缓存判断 String taskKey = videoEngineInfos.getUsingMDLPlayTaskKey();// 使用的 key 信息 long cacheSize = videoEngineInfos.getUsingMDLHitCacheSize();// 命中缓存文件 size // cacheSize > 0 , 表示命中缓存 // cacheSize = 0 , 未命中缓存，请排查预加载任务是否成功，如果字幕描述信息中包含多个字幕语言，请查看播放和预加载的 subtitleId 是否一致 } } });
JSON 字幕信息包含以下字段：
字段 | 说明 |
|---|---|
sub_id | （必填）字幕 ID，用于在播放器中区分不同的字幕。
|
language_id | （必填）语言 ID。取值详见语言。您需要自行维护字幕 ID 与语言 ID 的映射关系。 |
language | （必填）语言。取值详见语言。 |
url | （必填）字幕文件 URL。 |
format | （必填）字幕格式，支持 |
示例如下：
{ "list": [ { "language": "rus-RU", "language_id": 6, "url": "https://example.volcengine.com/cbebedaade0947ce51a*******17f0b13/6087d12f/video/tos/cn/tos-cn-o-0004/52ce3882d70941d5b660913cbd83d969/", "format": "webvtt", "sub_id": 328934091 }, { "language": "cmn-Hans-CN", "language_id": 1, "url": "https://example.volcengine.com/93adb942***bdfce8cb/6087d12f/video/tos/***a4122dac42d69e8233a4dfda82fe/", "format": "webvtt", "sub_id": 429984091 }, { "language": "cmn-Hans-CN|eng-US", "language_id": 5, "url": "https://***.com/d782d36702***7b9719/6087d12f/video/tos/***5f0d106146a19ad566b967211091/", "format": "webvtt", "sub_id": 829987091 } ] }