前言：為什麼需要"外掛字幕"？
在視頻播放場景中，用户常需要外掛字幕（如 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 成為你開發路上的得力助手，開啓你的音視頻播放新紀元！ 🚀
