前言：为什么需要“外挂字幕”？
在视频播放场景中，用户常需要外挂字幕（如 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 示例）
100:00:01,000 --> 00:00:04,000这是第一行字幕。200: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 成为你开发路上的得力助手，开启你的音视频播放新纪元！ 🚀
