在HarmonyOS中使用AVPlayer实现外挂字幕

前言：为什么需要“外挂字幕”？

在视频播放场景中，用户常需要外挂字幕（如 SRT、VTT 等格式）来提升观看体验，尤其是在外语教学、影视解说、直播回放等场景中。

HarmonyOS 通过 ArkTS + AVPlayer 的 subtitleUpdate 事件机制，我们可以实现视频播放前预加载字幕，并动态显示字幕内容，真正实现“外挂字幕”功能！

一、核心能力：AVPlayer 支持 subtitleUpdate 事件

HarmonyOS 的 AVPlayer 提供了以下关键接口，用于实现外挂字幕：

// 注册字幕更新事件
 avPlayer.on('subtitleUpdate',async(info: media.SubtitleInfo) => {
 // 获取当前播放帧对应的字幕信息
 if(info) {
  lettext = (!info.text) ?'': info.text
  letstartTime = (!info.startTime) ?0: info.startTime
  letduration = (!info.duration) ?0: info.duration
  console.info('subtitleUpdate info: text='+ text +' startTime='+ startTime +' duration='+ duration);
  }else{
  console.info('subtitleUpdate info is null');
  }
 });
}

SubtitleInfo 结构如下：

interfaceSubtitleInfo{
text:string;  // 字幕文本
startTime:number;// 字幕开始显示的时间（毫秒），以视频播放开始的时刻为 0 点
endTime:number; // 字幕结束显示的时间（毫秒）
}

二、实现方案：外挂字幕

字幕文件格式（SRT 示例）

1
0001,000 --> 0004,000
这是第一行字幕。
2
0005,000 --> 0008,000
这是第二行字幕。

步骤 1：调用addSubtitleFromFd，使用视频播放的AVPlayer实例设置外挂字幕资源。

import{ media }from'@kit.MediaKit';
import{ common }from'@kit.AbilityKit';
// 类成员定义avPlayer和context。
privateavPlayer: media.AVPlayer|null=null;
privatecontext: common.UIAbilityContext|undefined=undefined;

// 在业务函数中（示例工程函数名为avSetupVideoAndSubtitle）：
// 创建avPlayer实例对象。
this.avPlayer=awaitmedia.createAVPlayer();
this.context=this.getUIContext().getHostContext()ascommon.UIAbilityContext;
// 设定视频源（此处省略）。
// 设定字幕。
letfileDescriptorSub =awaitthis.context?.resourceManager.getRawFd('xxx.srt');
this.avPlayer.addSubtitleFromFd(fileDescriptorSub.fd, fileDescriptorSub.offset, fileDescriptorSub.length);

步骤 2：调用on('subtitleUpdate')接口，注册字幕回调函数。

import{ media }from'@kit.MediaKit';
// 类成员定义用来显示的字幕字符串。
@Statesubtitle:string='subtitleUpdate info';
privateavPlayer: media.AVPlayer|null=null;
privatetag:string='';
// 创建avPlayer实例对象。
this.avPlayer=awaitmedia.createAVPlayer();
// 字幕回调函数。
this.avPlayer.on('subtitleUpdate',(info: media.SubtitleInfo) =>{
 if(!!info) {
  lettext = (!info.text) ?'': info.text;
  letstartTime = (!info.startTime) ?0: info.startTime;
  letduration = (!info.duration) ?0: info.duration;
  console.info(`${this.tag}: text=${text}startTime=${startTime}duration=${duration}`);
  this.subtitle= text;
 }else{
  console.info(`${this.tag}: subtitleUpdate info is null`);
 }
});

步骤 3：(可选)当需要不显示字幕的时候，使用视频播放的AVPlayer实例注销字幕回调函数。

import{ media }from'@kit.MediaKit';
// 类成员定义avPlayer和context。
privateavPlayer: media.AVPlayer|null=null;
// 创建avPlayer实例对象。
this.avPlayer=awaitmedia.createAVPlayer();
this.avPlayer?.off('subtitleUpdate');

三、关键说明：当前仅支持“播放前设置字幕”

重要限制：

当前 HarmonyOS 的 AVPlayer 不支持动态切换字幕源（如切换不同语言字幕）

仅支持在播放前完成字幕文件加载与解析

但优势在于：

字幕与视频播放时间精准同步

支持自定义字幕样式、位置、动画效果

适合离线视频、教学课件、本地字幕场景

四、结语

借助 subtitleUpdate 事件与 timeUpdate 的联动机制实现外挂字母的自动加载：

实现精准时间同步

支持 SRT/VTT 等格式解析

构建可自定义、可扩展的字幕系统