【HarmonyOS-媒体技术-AVPlayer】手把手教你用 AVPlayer 实现外挂字幕(ArkTS 详解)

HarmonyOS开发者社区

发布于 2025-11-3 15:45

浏览

0收藏

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

在视频播放场景中，用户常需要外挂字幕（如 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');