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

在视频播放场景中，用户常需要外挂字幕（如 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
00:00:01,000 –> 00:00:04,000
这是第一行字幕。

2
00:00:05,000 –> 00:00:08,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 等格式解析
 构建 可自定义、可扩展的字幕系统

 五、立即行动，开启你的音视频播放开发之旅！

👉 点击了解完整开发示例与 API 文档
HarmonyOS AVPlayer 官方文档

 加入 HarmonyOS 社区，共创未来！

我们诚邀广大开发者一起参与 HarmonyOS 技术生态建设，共建更开放、更智能的未来世界！

加入开发者社区，获取最新资讯和技术支持
HarmonyOS 官方社区

如果你觉得这篇指南有用，欢迎点赞、收藏、分享给更多开发者！
 让 AVPlayer 成为你开发路上的得力助手，开启你的音视频播放新纪元！ 🚀