AVSession 音频会话管理类（Markdown版）

ohpm install @zyl/audio_player_manager

一、文档概述

本文档对应基于鸿蒙（HarmonyOS）系统套件封装的 AVSession 类，该类采用单例模式，核心职责是统一管理音频播放会话的创建、激活、系统媒体控制事件监听，以及音频后台播放任务的启停，旨在简化鸿蒙应用中音频播放场景的会话管理逻辑，降低开发复杂度。

适用场景：鸿蒙应用音频播放功能开发（如音乐播放、有声读物、语音播报等），需实现系统媒体控制（播放/暂停/切歌）、后台持续播放等核心能力。

二、前置依赖

2.1 系统套件依赖

该类依赖鸿蒙多个核心系统套件，项目中需确保正确引入以下依赖包：

import { Context, WantAgent, wantAgent, bundleManager } from “@kit.AbilityKit”;
import { backgroundTaskManager } from “@kit.BackgroundTasksKit”;
import { BusinessError } from “@kit.BasicServicesKit”;
import { avSession as AVSessionManager } from ‘@kit.AVSessionKit’;

2.2 类型定义依赖

需提前在 interfaces.ts 文件中定义 AudioSessionCallbacksTs 接口（用于约束音频事件回调函数类型），代码如下：

// interfaces.ts
import type { AVSessionManager } from ‘@kit.AVSessionKit’;

/** 音频会话事件回调接口 - 对应系统媒体控制命令 */
export interface AudioSessionCallbacksTs {
play?: () => void; // 播放命令回调
pause?: () => void; // 暂停命令回调
stop?: () => void; // 停止命令回调
playNext?: () => void; // 播放下一首命令回调
playPrevious?: () => void; // 播放上一首命令回调
fastForward?: () => void; // 快进命令回调
rewind?: () => void; // 快退命令回调
playFromAssetId?: () => void; // 根据资源ID播放命令回调
seek?: () => void; // 进度跳转命令回调
setSpeed?: () => void; // 设置播放速率命令回调
setLoopMode?: () => void; // 设置循环模式命令回调
toggleFavorite?: () => void; // 收藏切换命令回调
skipToQueueItem?: () => void; // 切换播放列表项命令回调
handleKeyEvent?: () => void; // 按键事件回调
commonCommand?: () => void; // 自定义控制命令回调
}

三、快速开始（核心使用流程）

以下是 AVSession 类最常用的完整使用流程，覆盖从初始化到销毁的全生命周期，可直接复制到项目中适配业务场景：

import { AvSessionInstance } from “./AVSession”; // 引入单例实例
import { AVSessionManager } from ‘@kit.AVSessionKit’;
import { Context } from “@kit.AbilityKit”;

// 1. 初始化（建议在Ability的onCreate生命周期中执行，传入应用上下文）
const appContext: Context = getContext(); // 替换为实际应用上下文（如Ability上下文）
AvSessionInstance.init(appContext);

// 2. 创建并激活音频会话（必执行步骤，否则无法监听事件和播放音频）
async function initAudioSession() {
try {
// 创建会话：可自定义tag（会话标识），类型默认audio
await AvSessionInstance.createAVSession(“MY_APP_AUDIO_SESSION”, “audio”);
// 激活会话：使会话具备系统媒体控制交互能力
await AvSessionInstance.activate();
console.log(“音频会话创建并激活成功”);
} catch (error) {
console.error(“音频会话初始化失败：”, error);
}
}

// 3. 注册系统媒体控制事件监听（按需实现回调方法）
function registerAudioListeners() {
AvSessionInstance.registerSessionListener({
play: () => {
console.log(“系统触发播放命令（如耳机播放键、控制中心播放按钮）”);
// 播放时启动后台任务，保证退到后台仍能持续播放
AvSessionInstance.startContinuousTask();
// 此处添加业务层播放逻辑（如调用播放器播放音频）
},
pause: () => {
console.log(“系统触发暂停命令”);
// 暂停时停止后台任务，释放资源
AvSessionInstance.stopContinuousTask();
// 此处添加业务层暂停逻辑
},
stop: () => {
console.log(“系统触发停止命令”);
AvSessionInstance.stopContinuousTask();
// 此处添加业务层停止逻辑
},
playNext: () => {
console.log(“系统触发下一首命令”);
// 此处添加业务层切下一首逻辑
},
playPrevious: () => {
console.log(“系统触发上一首命令”);
// 此处添加业务层切上一首逻辑
}
// 其他事件回调按需补充
});
}

// 4. 设置音频元数据（用于系统媒体控制中心展示，如歌曲名、歌手等）
async function setAudioMetadata() {
const audioMetadata: AVSessionManager.AVMetadata = {
title: “童年”, // 音频标题
artist: “罗大佑”, // 歌手/创作者
album: “之乎者也”, // 专辑名
coverUri: “https://example.com/cover.jpg”, // 封面图片URI（可选）
duration: 245000 // 音频时长（ms，可选）
};
await AvSessionInstance.setAVMetadata(audioMetadata);
}

// 5. 设置音频播放状态（同步到系统媒体控制中心，如播放/暂停、当前进度）
async function updatePlaybackState(isPlaying: boolean, currentTime: number) {
const playbackState: AVSessionManager.AVPlaybackState = {
state: isPlaying
? AVSessionManager.PlaybackState.PLAYBACK_STATE_PLAY
: AVSessionManager.PlaybackState.PLAYBACK_STATE_PAUSE,
position: {
elapsedTime: currentTime, // 当前播放进度（ms）
updateTime: new Date().getTime() // 状态更新时间戳（ms）
},
speed: 1.0 // 播放速率（默认1.0，可选）
};
await AvSessionInstance.setAVPlaybackState(playbackState);
}

// 6. 销毁音频会话（应用退出/音频功能关闭时执行，避免内存泄漏）
async function destroyAudioSession() {
try {
await AvSessionInstance.destroy();
console.log(“音频会话销毁成功”);
} catch (error) {
console.error(“音频会话销毁失败：”, error);
}
}

// 执行初始化流程（按业务时机调用，如音频播放页面打开时）
initAudioSession()
.then(() => {
registerAudioListeners();
setAudioMetadata();
updatePlaybackState(true, 0); // 初始化为播放状态，进度0ms
})
.catch((err) => console.error(“初始化流程异常：”, err));

四、API 详细说明

4.1 核心属性（私有，外部无需调用）

属性名

类型

默认值

说明

instance

AVSession

undefined

单例实例，保证全局唯一，通过getInstance()获取

tag

string

“SESSION_NAME”

音频会话唯一标识，用于区分不同会话（如有多个音频场景）

type

AVSessionManager.AVSessionType

“audio”

会话类型，固定为audio（音频会话）

context

Context | undefined

undefined

应用上下文，必须通过init()方法初始化，否则所有API失效

session

AVSessionManager.AVSession | undefined

undefined

鸿蒙原生音频会话实例，核心操作载体

callbacks

AudioSessionCallbacksTs | undefined

undefined

存储注册的音频事件回调函数集合

4.2 公共方法（按使用优先级排序）

4.2.1 单例获取：getInstance()

• 作用：获取全局唯一的AVSession实例，单例模式核心方法，确保整个应用仅存在一个会话管理实例

• 参数：无

• 返回值：AVSession（单例实例）

• 使用示例：
  const avSession = AVSession.getInstance(); // 直接获取实例
  // 或使用导出的便捷实例（推荐）
  import { AvSessionInstance } from “./AVSession”;

4.2.2 初始化上下文：init(context: Context)

• 作用：设置应用上下文，必须优先执行，否则后续所有API都会抛出"context is undefined"错误

• 参数：

  • context：鸿蒙应用上下文（如Ability的onCreate中通过getContext()获取）

• 返回值：void

• 使用示例：
  // 在Ability的onCreate生命周期中初始化
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
  super.onCreate(want, launchParam);
  AvSessionInstance.init(this.getContext()); // 传入Ability上下文
  }

4.2.3 创建音频会话：createAVSession(tag?: string, type?: AVSessionManager.AVSessionType)

• 作用：创建鸿蒙原生音频会话实例，初始化会话的标识（tag）和类型（type）

• 参数：

  • tag（可选）：会话标识，默认值"SESSION_NAME"，建议自定义（如应用包名+功能模块名）

  • type（可选）：会话类型，默认值"audio"，无需修改（仅支持音频会话）

• 返回值：Promise

• 注意事项：

  • 调用前必须先执行init()方法设置上下文

  • 仅需创建一次，重复创建会覆盖原有会话实例

4.2.4 激活音频会话：activate()

• 作用：激活音频会话，使其具备监听系统媒体控制事件（如播放/暂停按键）、同步状态到系统控制中心的能力

• 参数：无

• 返回值：Promise

• 注意事项：创建会话后必须调用activate()，否则事件监听和状态同步都会失效

4.2.5 注册事件监听：registerSessionListener(callbacks?: AudioSessionCallbacksTs)

• 作用：注册系统媒体控制事件的回调函数，响应外部控制命令（如耳机按键、系统控制中心操作、蓝牙设备控制等）

• 参数：

  • callbacks：AudioSessionCallbacksTs类型对象，按需实现需要的事件回调（无需实现所有方法）

• 返回值：void

• 注意事项：

  • 仅需注册一次，重复注册会导致同一事件回调多次执行

  • 销毁会话时（destroy()）会自动注销所有监听，无需手动调用unRegisterListener()

4.2.6 设置音频元数据：setAVMetadata(word: AVSessionManager.AVMetadata)

• 作用：设置音频会话的元数据，用于在系统媒体控制中心展示（如标题、歌手、专辑封面等）

• 参数：

  • word：AVSessionManager.AVMetadata类型对象，核心字段包括title（标题）、artist（歌手）、album（专辑）、coverUri（封面URI）、duration（时长）等

• 返回值：Promise

• 使用场景：音频切换时（如下一首、上一首），需重新调用该方法更新元数据

4.2.7 设置播放状态：setAVPlaybackState(playbackState: AVSessionManager.AVPlaybackState)

• 作用：设置音频播放状态，同步到系统媒体控制中心（如播放/暂停状态、当前播放进度、播放速率等）

• 参数：

  • playbackState：AVSessionManager.AVPlaybackState类型对象，核心字段：

    • state：播放状态（PLAYBACK_STATE_PLAY/PLAYBACK_STATE_PAUSE/PLAYBACK_STATE_STOP）

    • position：播放进度（elapsedTime：已播放时长ms；updateTime：更新时间戳ms）

    • speed：播放速率（默认1.0，支持0.5~2.0等范围）

• 返回值：Promise

• 使用场景：播放状态变更时（如播放/暂停切换、进度跳转、速率调整），需及时调用更新状态

4.2.8 启动后台播放任务：startContinuousTask(wantAgentInfos?: wantAgent.WantAgentInfo)

• 作用：启动鸿蒙后台持续任务（音频播放模式），保证应用退到后台（或锁屏）后音频仍能持续播放，不会被系统回收资源

• 参数：

  • wantAgentInfos（可选）：WantAgent配置，用于设置点击后台播放通知时拉起的应用/Ability，默认配置如下：
    {
    wants: [
    {
    bundleName: “com.baicizhan.bcz.hm”, // 应用包名（默认，可替换为实际包名）
    abilityName: “EntryAbility” // 拉起的Ability（默认入口Ability）
    }
    ],
    operationType: wantAgent.OperationType.START_ABILITY, // 操作类型：启动Ability
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] // 更新通知标识
    }

• 返回值：Promise

• 使用建议：在play回调中调用，启动后台任务；在pause/stop回调中调用stopContinuousTask()停止任务

4.2.9 停止后台播放任务：stopContinuousTask()

• 作用：停止音频后台持续任务，释放后台资源，避免不必要的资源占用

• 参数：无

• 返回值：Promise

• 使用场景：音频暂停、停止播放，或应用退出音频播放功能时

4.2.10 销毁音频会话：destroy()

• 作用：注销所有已注册的音频事件监听，销毁鸿蒙原生音频会话实例，释放所有相关资源

• 参数：无

• 返回值：Promise

• 使用建议：

  • 应用退出时（如Ability的onDestroy生命周期）必须调用

  • 音频播放功能关闭时（如用户退出播放页面）必须调用，避免内存泄漏

4.2.11 其他辅助方法

方法名

作用

参数

使用说明

setLaunchAbility

设置后台通知拉起的应用能力

agent?: WantAgent

内部方法，一般无需外部调用，startContinuousTask()会自动处理

unRegisterListener

注销所有事件监听

无

内部方法，destroy()会自动调用，无需手动执行

getBundleName

获取应用包名

无

内部预留方法，返回应用包名（Promise）

五、注意事项（核心避坑指南）

1. 初始化顺序不可乱：必须严格遵循「init(context) → createAVSession() → activate()」的顺序，否则会导致会话创建失败、事件监听无效等问题。

2. 单例模式使用规范：全局仅需一个AVSession实例，务必通过导出的AvSessionInstance使用，或调用getInstance()获取，禁止通过new AVSession()创建实例（构造函数为私有）。

3. 后台任务启停时机：仅在音频播放时启动后台任务（startContinuousTask()），暂停/停止播放时必须停止任务（stopContinuousTask()），否则会被系统判定为无效后台占用，可能导致应用被强制回收。

4. 事件监听注册时机：需在会话激活（activate()）后注册监听，否则可能无法正常接收系统事件；同时避免重复注册，防止回调多次执行。

5. 资源释放必须执行：应用退出或音频功能关闭时，必须调用destroy()方法销毁会话，否则会导致内存泄漏（如事件监听未注销、会话实例未释放）。

6. 错误处理补充：文档中快速开始和API示例仅包含基础错误捕获，实际业务开发中需根据场景补充额外错误处理（如会话激活失败后重试、后台任务启动失败提示用户等）。

7. 包名配置核对：startContinuousTask()中默认包名为"com.baicizhan.bcz.hm"，实际使用时需替换为当前应用的真实包名，否则点击后台通知无法正常拉起应用。

六、总结

6.1 核心价值

AVSession类通过封装鸿蒙原生音频会话API，解决了音频播放场景中「会话管理、系统控制交互、后台持续播放」三大核心问题，简化了开发流程：

• 单例模式保证全局会话唯一，避免多实例冲突；

• 统一的事件监听注册方式，无需关注原生API的复杂配置；

• 封装后台任务启停逻辑，快速实现后台持续播放功能；

• 标准化的元数据和播放状态设置，同步系统媒体控制中心更便捷。

6.2 关键流程回顾

使用AVSession的核心流程可总结为「3步初始化 + 业务操作 + 1步销毁」：

1. 初始化：init(context) → createAVSession() → activate()

2. 业务操作：registerSessionListener() → 播放/暂停/切歌等业务逻辑 → setAVMetadata()/setAVPlaybackState() → startContinuousTask()/stopContinuousTask()

3. 销毁：destroy()

遵循以上流程和注意事项，可快速在鸿蒙应用中集成稳定的音频播放功能，适配系统媒体控制和后台播放场景。