外挂字幕是指字幕文件与视频文件分开存储,用户在播放视频时按需导入字幕文件。点播 SDK 当前支持 WebVTT (Web Video Text Tracks) 格式的字幕文件。这种方式的优势在于其灵活性,用户可以根据实际需求选择是否导入字幕文件,或者选择加载不同语言的字幕。更重要的是,您无需进行额外的视频转码,只需要在播放端进行适当设置,便可实现外挂字幕的显示。本文为您介绍使用点播 SDK 时如何添加外挂字幕。
外挂字幕为高级版或企业版功能。请确保您已购买高级版或企业版 License 包,购买方式详见 License 包管理。
注意
自 1.36.1 版本起,外挂字幕功能由增值服务调整至高级版和企业版。如您集成 1.36.1 之前的版本且想要使用此功能,请升级至最新版本。
如果您通过 Vid 方式播放视频,需要准备字幕文件:
在接入外挂字幕功能前,请阅读集成准备以及快速开始 - 初始化 SDK 章节,确保已经完成 SDK 的初始化。
参考以下示例代码开启外挂字幕功能:
// 外挂字幕功能总开关,建议在设置 vid 之前调用 [self.videoEngine setOptionForKey:VEKKeyPlayerEnableSubThread_BOOL value:@(YES)]; // 外挂字幕加载优化开关 // NO: 关闭外挂字幕加载优化;YES: 开启外挂字幕加载优化 [self.videoEngine setOptionForKey:VEKKeyPlayerSubtitleOptEnable_BOOL value:@(YES)];
点播 SDK 支持以下两种方式设置字幕源。您需根据实际情况选择。
使用 Vid + SubtitleToken 方式设置字幕源。示例代码如下:
NSString *vid = @"YOUR_VIDEO_ID"; // AppServer 下发 NSString *playAuthToken = @"YOUR_PLAYAUTHTOKEN"; // AppServer 下发 TVideoEngineVidSource *vidSource = [[TTVideoEngineVidSource alloc] initWithVid:vid playAuthToken:playAuthToken resolution:resolution]; // 设置字幕鉴权 token,需在起播前设置 [self.videoEngine setSubtitleAuthToken:@"SUBTITLE_AUTHTOKEN"]; // AppServer 下发 // 设置默认展示语言。如不设置,SDK 会以点播服务端下发的顺序展示第一位语言 // 字幕语言映射表见:https://www.volcengine.com/docs/4/1186356 // 需传入 SubtitleID。SubtitleID 可通过 -[TTVideoEngine subtitleIDs] 获取。 [self.videoEngine setOptionForKey:VEKeyPlayerSwitchSubtitleId_NSInteger value:@(<#SubtitleID#>)]; [self.videoEngine setVideoEngineVideoSource:vidSource]; [self.videoEngine play];
使用 DirectURL 方式设置字幕源。您需要实现 TTVideoEngineSubDecInfoProtocol 协议构建字幕源。示例代码如下:
NSString *url = @"http://www.example.com/h264.mp4"; NSString *cacheKey = [url md5String]; // cacheKey 用作磁盘缓存的文件名,建议采用 URL 中能标识视频文件的部分的 MD5 值 TTVideoEngineUrlSource *source = [[TTVideoEngineUrlSource alloc] initWithUrl:url cacheKey:cacheKey]; [self.videoEngine setVideoEngineVideoSource: source]; // 设置 DirectURL 模式下的字幕源 // 该字幕源需要实现 TTVideoEngineSubDecInfoProtocol 协议 [self.videoEngine setSubDecInfoModel:self]; [self.videoEngine play]; // MARK: - TTVideoEngineSubDecInfoProtocol // 返回包含外挂字幕 URL 等信息的 JSON 字符串,参考 [JSON 字幕信息示例](https://www.volcengine.com/docs/4/1166817#json) - (NSString *_Nullable)jsonString { return subtitleJSONStr; } // 返回字幕 list 包含的字幕数量 - (NSInteger)subtitleCount { return count; }
参考以下示例代码在起播时或者播放过程中控制开启或者关闭字幕:
// 起播时或者播放过程中控制展示或者关闭字幕 // YES: 输出字幕;NO: 停止输出字幕 [self.videoEngine setOptionForKey:VEKKeyPlayerSubEnabled_BOOL value:@(YES)];
参考以下示例代码传入字幕 ID 切换不同的字幕:
[self.videoEngine setOptionForKey:VEKeyPlayerSwitchSubtitleId_NSInteger value:@(<#NSInteger#>)];
说明
SubtitleId
。SubtitleId
可通过 -[TTVideoEngine subtitleIDs] 获取。sub_id
字段。调用 setSubtitleDelegate
设置字幕回调:
// 设置回调接收 [self.videoEngine setSubtitleDelegate:self];
字幕回调的具体使用说明如下:
/** * 字幕回调 * <TTVideoEngineSubtitleDelegate> */ // 每行字幕信息回调。返回视频当前播放进度处的字幕内容。收到字幕信息后,您需要自行渲染字幕。 // content:单行字幕内容 // pts:时间戳 - (void)videoEngine:(TTVideoEngine *)videoEngine onSubtitleInfoCallBack:(NSString *)content pts:(NSUInteger)pts { // 刷新字幕 // 示例: [self.subtitleView refreshContent:content]; } // 每行字幕信息回调,subInfo:TTVideoEngineSubInfo - (void)videoEngine:(TTVideoEngine *)videoEngine onSubtitleInfoCallBack:(TTVideoEngineSubInfo *)subInfo { // subInfo.pts: 字幕开始显示的时间戳 // subInfo.content: 字幕内容 // subInfo.duration: 字幕要持续的时长。 } // 针对 vid 播放,当请求到字幕时播放器回调,可以用来更新字幕列表,也可以用于设置默认字幕 - (void)videoEngine:(TTVideoEngine *)videoEngine onSubtitleInfoRequested:(id _Nullable)info error:(NSError * _Nullable)error { NSArray *supportSubtitlesIds = [videoEngine subtitleIDs]; // 此时获取到了所有支持的 subtitle, 可以进行字幕列表的更新 // [videoEngine setOptionForKey:VEKeyPlayerSwitchSubtitleId_NSInteger value:@(<#NSInteger#>)]; 设置默认字幕或切换字幕 } // 字幕切换完成,currentLangId:当前语言ID - (void)videoEngine:(TTVideoEngine *)videoEngine onSubSwitchCompleted:(BOOL)success currentLangId:(NSInteger)currentLangId { } // 当前字幕加载完成 - (void)videoEngine:(TTVideoEngine *)videoEngine onSubLoadFinished:(BOOL)success info:(TTVideoEngineLoadInfo *)info { if (!success) { // 字幕加载失败。可移除字幕渲染或重新请求 } else { // 字幕加载成功。 // info.firstPts 字幕首次出现的时间戳 } }
{ "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
字段。language_id
为语言 ID,您需要自行维护字幕 ID 与语言 ID 的映射关系。language
和 language_id
的取值可参考字幕语言。url
为字幕文件 URL。id
可设为索引 Index。expire
为字幕 URL 过期时间。如果没有过期时间,则可不传。