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

在視頻播放場(chǎng)景中，用戶常需要外掛字幕（如 SRT、VTT 等格式）來提升觀看體驗(yàn)，尤其是在外語教學(xué)、影視解說、直播回放等場(chǎng)景中。

HarmonyOS 通過 ArkTS + AVPlayer 的 subtitleUpdate 事件機(jī)制，我們可以實(shí)現(xiàn)視頻播放前預(yù)加載字幕，并動(dòng)態(tài)顯示字幕內(nèi)容，真正實(shí)現(xiàn)“外掛字幕”功能！

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

HarmonyOS 的 AVPlayer 提供了以下關(guān)鍵接口，用于實(shí)現(xiàn)外掛字幕：

// 注冊(cè)字幕更新事件
 avPlayer.on('subtitleUpdate',async(info: media.SubtitleInfo) => {
 // 獲取當(dāng)前播放幀對(duì)應(yīng)的字幕信息
 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 結(jié)構(gòu)如下：

interfaceSubtitleInfo{
text:string;  // 字幕文本
startTime:number;// 字幕開始顯示的時(shí)間（毫秒），以視頻播放開始的時(shí)刻為 0 點(diǎn)
endTime:number; // 字幕結(jié)束顯示的時(shí)間（毫秒）
}

二、實(shí)現(xiàn)方案：外掛字幕

字幕文件格式（SRT 示例）

1
0001,000 --> 0004,000
這是第一行字幕。
2
0005,000 --> 0008,000
這是第二行字幕。

步驟 1：調(diào)用addSubtitleFromFd，使用視頻播放的AVPlayer實(shí)例設(shè)置外掛字幕資源。

import{ media }from'@kit.MediaKit';
import{ common }from'@kit.AbilityKit';
// 類成員定義avPlayer和context。
privateavPlayer: media.AVPlayer|null=null;
privatecontext: common.UIAbilityContext|undefined=undefined;

// 在業(yè)務(wù)函數(shù)中（示例工程函數(shù)名為avSetupVideoAndSubtitle）：
// 創(chuàng)建avPlayer實(shí)例對(duì)象。
this.avPlayer=awaitmedia.createAVPlayer();
this.context=this.getUIContext().getHostContext()ascommon.UIAbilityContext;
// 設(shè)定視頻源（此處省略）。
// 設(shè)定字幕。
letfileDescriptorSub =awaitthis.context?.resourceManager.getRawFd('xxx.srt');
this.avPlayer.addSubtitleFromFd(fileDescriptorSub.fd, fileDescriptorSub.offset, fileDescriptorSub.length);

步驟 2：調(diào)用on('subtitleUpdate')接口，注冊(cè)字幕回調(diào)函數(shù)。

import{ media }from'@kit.MediaKit';
// 類成員定義用來顯示的字幕字符串。
@Statesubtitle:string='subtitleUpdate info';
privateavPlayer: media.AVPlayer|null=null;
privatetag:string='';
// 創(chuàng)建avPlayer實(shí)例對(duì)象。
this.avPlayer=awaitmedia.createAVPlayer();
// 字幕回調(diào)函數(shù)。
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：(可選)當(dāng)需要不顯示字幕的時(shí)候，使用視頻播放的AVPlayer實(shí)例注銷字幕回調(diào)函數(shù)。

import{ media }from'@kit.MediaKit';
// 類成員定義avPlayer和context。
privateavPlayer: media.AVPlayer|null=null;
// 創(chuàng)建avPlayer實(shí)例對(duì)象。
this.avPlayer=awaitmedia.createAVPlayer();
this.avPlayer?.off('subtitleUpdate');

三、關(guān)鍵說明：當(dāng)前僅支持“播放前設(shè)置字幕”

重要限制：

當(dāng)前 HarmonyOS 的 AVPlayer 不支持動(dòng)態(tài)切換字幕源（如切換不同語言字幕）

僅支持在播放前完成字幕文件加載與解析

但優(yōu)勢(shì)在于：

字幕與視頻播放時(shí)間精準(zhǔn)同步

支持自定義字幕樣式、位置、動(dòng)畫效果

適合離線視頻、教學(xué)課件、本地字幕場(chǎng)景

四、結(jié)語

借助 subtitleUpdate 事件與 timeUpdate 的聯(lián)動(dòng)機(jī)制實(shí)現(xiàn)外掛字母的自動(dòng)加載：

實(shí)現(xiàn)精準(zhǔn)時(shí)間同步

支持 SRT/VTT 等格式解析

構(gòu)建可自定義、可擴(kuò)展的字幕系統(tǒng)