前言：為什么需要“外掛字幕”？

在視頻播放場景中，用戶常需要外掛字幕（如 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 等格式解析

構建可自定義、可擴展的字幕系統