You need to enable JavaScript to run this app.
导航
外挂字幕
最近更新时间:2024.09.19 12:05:35首次发布时间:2023.11.09 11:10:28

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

前提条件

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

    注意

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

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

    • 如果您已有单独的字幕文件,可选择在视频点播控制台指定空间内的视频管理 > 视频详情页面上传字幕文件,如下图所示:
      图片
    • 如果您没有单独的字幕文件,可在视频点播控制台配置智能字幕模板,生成字幕文件。
  • 在接入外挂字幕功能前,请阅读集成准备以及快速开始 - 初始化 SDK 章节,确保已经完成 SDK 的初始化。

API 调用时序

图片

开启外挂字幕功能

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

// 外挂字幕功能总开关,建议在设置 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#>)];

说明

  • 使用 Vid 方式设置字幕源时,传入 SubtitleIdSubtitleId 可通过 -[TTVideoEngine subtitleIDs] 获取。
  • 使用 DirectURL 方式设置字幕源时,传入字幕信息 JSON 中的 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 字幕首次出现的时间戳
   }
}

参考信息

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 的映射关系。
  • languagelanguage_id 的取值可参考字幕语言
  • url 为字幕文件 URL。
  • id 可设为索引 Index。
  • expire 为字幕 URL 过期时间。如果没有过期时间,则可不传。