Implementing External Subtitles with HarmonyOS AVPlayer: A Step-by-Step ArkTS Guide

Core Capability: AVPlayer subtitleUpdate Event

HarmonyOS AVPlayer provides a subtitleUpdate event that fires when the current playback frame has associated subtitle data. The callback receives a SubtitleInfo object containing:

interface SubtitleInfo {
  text: string;      // subtitle text
  startTime: number; // start time in milliseconds from playback start
  endTime: number;   // end time in milliseconds
}

Example registration:

avPlayer.on('subtitleUpdate', async (info: media.SubtitleInfo) => {
  if (info) {
    let text = info.text || '';
    let startTime = info.startTime || 0;
    let duration = info.duration || 0;
    console.info(`subtitleUpdate info: text=${text} startTime=${startTime} duration=${duration}`);
  } else {
    console.info('subtitleUpdate info is null');
  }
});

Implementation Steps for External Subtitles

Subtitle File Format (SRT Example)

1
00:00:01,000 --> 00:00:04,000
This is the first subtitle.
2
00:00:05,000 --> 00:00:08,000
This is the second subtitle.

Step 1: Load Subtitle via addSubtitleFromFd

Obtain a file descriptor for the raw subtitle resource (e.g., xxx.srt) and pass it to the AVPlayer instance before playback.

import { media } from '@kit.MediaKit';
import { common } from '@kit.AbilityKit';

private avPlayer: media.AVPlayer | null = null;
private context: common.UIAbilityContext | undefined = undefined;

// In setup function:
this.avPlayer = await media.createAVPlayer();
this.context = this.getUIContext().getHostContext() as common.UIAbilityContext;
// Set video source (omitted)
let fileDescriptorSub = await this.context?.resourceManager.getRawFd('xxx.srt');
this.avPlayer.addSubtitleFromFd(fileDescriptorSub.fd, fileDescriptorSub.offset, fileDescriptorSub.length);

Step 2: Register subtitleUpdate Callback

Use a @State variable to hold the current subtitle text for UI rendering.

import { media } from '@kit.MediaKit';

@State subtitle: string = 'subtitleUpdate info';
private avPlayer: media.AVPlayer | null = null;
private tag: string = '';

this.avPlayer = await media.createAVPlayer();
this.avPlayer.on('subtitleUpdate', (info: media.SubtitleInfo) => {
  if (info) {
    let text = info.text || '';
    let startTime = info.startTime || 0;
    let duration = info.duration || 0;
    console.info(`${this.tag}: text=${text} startTime=${startTime} duration=${duration}`);
    this.subtitle = text;
  } else {
    console.info(`${this.tag}: subtitleUpdate info is null`);
  }
});

Step 3: Unregister Callback (Optional)

Call off('subtitleUpdate') when subtitles should no longer be displayed.

this.avPlayer?.off('subtitleUpdate');

Key Limitation: Subtitle Must Be Set Before Playback

AVPlayer does not support dynamic switching of subtitle sources (e.g., changing language during playback).

Subtitle files must be loaded and parsed before playback starts.

Advantages of this approach:

Precise synchronization between subtitle and video playback time.

Support for custom subtitle styling, positioning, and animation effects.

Well-suited for offline videos, teaching materials, and local subtitle scenarios.

Conclusion

By combining the subtitleUpdate event with timeUpdate, developers can achieve accurate time synchronization, parse SRT/VTT formats, and build a customizable, extensible subtitle system. For complete examples and API reference, see the HarmonyOS Media Kit documentation: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/media-kit-intro#avplayer