鸿蒙OS AVPlayer 音频播放功能开发教程

一、概述

在鸿蒙OS应用开发中，AVPlayer是一个强大的音频播放器，它允许开发者实现端到端的原始媒体资源播放。本文将详细介绍AVPlayer的使用方法，包括创建、设置资源、控制播放等功能，并提供完整的示例代码。

二、基本概念

1. 状态机

AVPlayer拥有多个状态，用于反映当前播放器的状态，例如：

idle: 空闲状态，表示播放器未被初始化。
initialized: 初始化状态，表示播放器已创建，并设置了播放资源。
prepared: 预备状态，表示播放器已准备就绪，可以开始播放。
playing: 播放状态，表示播放器正在播放音频。
paused: 暂停状态，表示播放器暂停播放音频。
completed: 完成状态，表示音频播放完成。
stopped: 停止状态，表示播放器停止播放音频。
released: 释放状态，表示播放器已销毁。

开发者可以通过 state 属性获取当前状态，或使用 on('stateChange') 方法监听状态变化。

2. 资源类型

AVPlayer 支持两种类型的播放资源：

URL: 使用 url 属性设置播放资源，支持沙箱地址，例如 fd:// 开头的文件路径。
FD Src: 使用 fdSrc 属性设置播放资源，支持获取打包在 HAP 内的媒体资源，返回类型为 {fd, offset, length}，包含 HAP 包 FD 地址、媒体资源偏移量和播放长度。

3. 控制方法

AVPlayer 提供了丰富的播放控制方法：

prepare(): 准备播放，将播放器状态从 initialized 转为 prepared。
play(): 开始播放，将播放器状态从 prepared 转为 playing。
pause(): 暂停播放，将播放器状态从 playing 转为 paused。
seek(seekDoneTime): 跳转到指定时间点，参数为 seekDoneTime，单位为毫秒。
stop(): 停止播放，将播放器状态从 playing 或 paused 转为 stopped。
reset(): 重置播放器，将播放器状态从 initialized、prepared、playing、paused 或 stopped 转为 idle。
release(): 释放播放器资源，将播放器状态从 idle 转为 released。

三、示例代码

以下代码演示了如何使用 AVPlayer 播放音频：

import media from '@ohos.multimedia.media';
import fs from '@ohos.file.fs';
import common from '@ohos.app.ability.common';

export class AVPlayerDemo {
  private avPlayer;
  private isSeek: boolean = true; // 用于区分模式是否支持seek操作
  private count: number = 0;

  // 注册avplayer回调函数
  setAVPlayerCallback() {
    // seek操作结果回调函数
    this.avPlayer.on('seekDone', (seekDoneTime) => {
      console.info(`AVPlayer seek succeeded, seek time is ${seekDoneTime}`);
    });

    // error回调监听函数,当avPlayer在操作过程中出现错误时调用reset接口触发重置流程
    this.avPlayer.on('error', (err) => {
      console.error(`Invoke avPlayer failed, code is ${err.code}, message is ${err.message}`);
      this.avPlayer.reset(); // 调用reset重置资源，触发idle状态
    });

    // 状态机变化回调函数
    this.avPlayer.on('stateChange', async (state, reason) => {
      switch (state) {
        case 'idle': // 成功调用reset接口后触发该状态机上报
          console.info('AVPlayer state idle called.');
          this.avPlayer.release(); // 调用release接口销毁实例对象
          break;
        case 'initialized': // avplayer 设置播放源后触发该状态上报
          console.info('AVPlayerstate initialized called.');
          this.avPlayer.prepare().then(() => {
            console.info('AVPlayer prepare succeeded.');
          }, (err) => {
            console.error(`Invoke prepare failed, code is ${err.code}, message is ${err.message}`);
          });
          break;
        case 'prepared': // prepare调用成功后上报该状态机
          console.info('AVPlayer state prepared called.');
          this.avPlayer.play(); // 调用播放接口开始播放
          break;
        case 'playing': // play成功调用后触发该状态机上报
          console.info('AVPlayer state playing called.');
          if (this.count !== 0) {
            console.info('AVPlayer start to seek.');
            this.avPlayer.seek(this.avPlayer.duration); //seek到音频末尾
          } else {
            this.avPlayer.pause(); // 调用暂停接口暂停播放
          }
          this.count++;
          break;
        case 'paused': // pause成功调用后触发该状态机上报
          console.info('AVPlayer state paused called.');
          this.avPlayer.play(); // 再次播放接口开始播放
          break;
        case 'completed': // 播放结束后触发该状态机上报
          console.info('AVPlayer state completed called.');
          this.avPlayer.stop(); //调用播放结束接口
          break;
        case 'stopped': // stop接口成功调用后触发该状态机上报
          console.info('AVPlayer state stopped called.');
          this.avPlayer.reset(); // 调用reset接口初始化avplayer状态
          break;
        case 'released':
          console.info('AVPlayer state released called.');
          break;
        default:
          console.info('AVPlayer state unknown called.');
          break;
      }
    });
  }

  // 以下demo为使用fs文件系统打开沙箱地址获取媒体文件地址并通过url属性进行播放示例
  async avPlayerUrlDemo() {
    // 创建avPlayer实例对象
    this.avPlayer = await media.createAVPlayer();
    // 创建状态机变化回调函数
    this.setAVPlayerCallback();
    let fdPath = 'fd://';
    // 通过UIAbilityContext获取沙箱地址filesDir，以下为Stage模型获方式，如需在FA模型上获取请参考《访问应用沙箱》获取地址
    let context = getContext(this) as common.UIAbilityContext;
    let pathDir = context.filesDir;
    let path = pathDir + '/01.mp3';
    // 打开相应的资源文件地址获取fd，并为url赋值触发initialized状态机上报
    let file = await fs.open(path);
    fdPath = fdPath + '' + file.fd;
    this.avPlayer.url = fdPath;
  }

  // 以下demo为使用资源管理接口获取打包在HAP内的媒体资源文件并通过fdSrc属性进行播放示例
  async avPlayerFdSrcDemo() {
    // 创建avPlayer实例对象
    this.avPlayer = await media.createAVPlayer();
    // 创建状态机变化回调函数
    this.setAVPlayerCallback();
    // 通过UIAbilityContext的resourceManager成员的getRawFd接口获取媒体资源播放地址
    // 返回类型为{fd,offset,length},fd为HAP包fd地址，offset为媒体资源偏移量，length为播放长度
    let context = getContext(this) as common.UIAbilityContext;
    let fileDescriptor = await context.resourceManager.getRawFd('01.mp3');
    // 为fdSrc赋值触发initialized状态机上报
    this.avPlayer.fdSrc = fileDescriptor;
    this.isSeek = false; // 不支持seek操作
  }
}

四、总结

本文介绍了鸿蒙OS AVPlayer 的基本概念、使用方法和示例代码。通过使用 AVPlayer，开发者可以轻松实现音频播放功能，并根据需要控制播放过程。