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

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

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

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

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

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

 

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

 

SubtitleInfo 结构如下：

 

interface SubtitleInfo {
  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。
 private avPlayer: media.AVPlayer | null = null;
 private context: common.UIAbilityContext | undefined = undefined;
 
 // 在业务函数中（示例工程函数名为avSetupVideoAndSubtitle）：
 // 创建avPlayer实例对象。
 this.avPlayer = await media.createAVPlayer();
 this.context = this.getUIContext().getHostContext() as common.UIAbilityContext;
 // 设定视频源（此处省略）。
 // 设定字幕。
 let fileDescriptorSub = await this.context?.resourceManager.getRawFd('xxx.srt');
 this.avPlayer.addSubtitleFromFd(fileDescriptorSub.fd, fileDescriptorSub.offset, fileDescriptorSub.length);

 

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

 

import { media } from '@kit.MediaKit';
 // 类成员定义用来显示的字幕字符串。
 @State subtitle: string = 'subtitleUpdate info';
 private avPlayer: media.AVPlayer | null = null;
 private tag: string = '';
 // 创建avPlayer实例对象。
 this.avPlayer = await media.createAVPlayer();
 // 字幕回调函数。
 this.avPlayer.on('subtitleUpdate', (info: media.SubtitleInfo) => {
   if (!!info) {
     let text = (!info.text) ? '' : info.text;
     let startTime = (!info.startTime) ? 0 : info.startTime;
     let duration = (!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。
 private avPlayer: media.AVPlayer | null = null;
 // 创建avPlayer实例对象。
 this.avPlayer = await media.createAVPlayer();
 this.avPlayer?.off('subtitleUpdate');

 

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

重要限制：

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

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

但优势在于：

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

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

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

四、结语

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

实现精准时间同步

支持 SRT/VTT 等格式解析

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