HarmonyOS 6实战（源码解析篇）：音乐播放器的音频焦点管理（上）——AudioSession与打断机制

HarmonyOS 6实战（源码解析篇）：音乐播放器的音频焦点管理（上）——AudioSession与打断机制

• HarmonyOS 6实战（源码解析篇）：音乐播放器的音频焦点管理（上）——AudioSession与打断机制
• • 前言
  • 音频焦点基础
  • • 什么是音频焦点
    • 音频流类型的重要性
    • 申请和释放焦点
  • 音频打断机制详解
  • • 打断类型
    • • 1. 强制打断 (INTERRUPT_FORCE)
      • 2. 共享打断 (INTERRUPT_SHARE)
    • 打断提示类型
  • 实现音频焦点管理
  • • 场景1：TextReader朗读时
    • 场景2：来电时
    • 步骤1：基础打断处理
    • • 1. 核心状态
      • 2. 监听系统打断
      • 3. 处理不同中断类型
      • 4. 用户主动操作
    • 步骤2：设置焦点模式
    • 步骤3：实现静音播放模式
  • 总结
  • • 核心知识点
    • 下篇预告
  • 参考资源

HarmonyOS 6实战（源码解析篇）：音乐播放器的音频焦点管理（上）——AudioSession与打断机制

前言

大家好！我是你们的老朋友木斯佳，是华为云 HDE 认证专家和 OpenTiny 开源社区的布道师。在上一篇分享中，我们为 HarmonyOS 音乐播放器集成了 Speech Kit 的 TextReader 能力，让应用能够清晰流畅地朗读歌曲信息。

然而，当多个声音同时响起时，美好的体验也可能被打断——想象一下，正用 TextReader 听着歌词解读，背景音乐却依然播放；开车时，突然有电话进来，音乐与电话铃声交杂在一起。 这些声音的“冲突”，不仅影响使用感受，更可能让核心信息淹没在嘈杂的音频流中。

为了解决这类问题，HarmonyOS 提供了完善的音频管理机制。继为应用装上“耳朵”和“嗓音”之后，本篇我们将聚焦于赋予它智慧的“听觉协调能力”。我们将一起探讨如何通过 AudioSession 管理与音频打断策略，让应用能够智能协调多个音频流的并发与中断，确保在任何场景下，声音都能有序、清晰地传递。

音频焦点基础

什么是音频焦点

音频焦点是HarmonyOS音频系统的核心机制，用于协调多个应用或同一应用内多个音频流的播放。

核心原则：

• 同一时刻只有一个音频流拥有焦点
• 拥有焦点的音频流可以正常播放
• 失去焦点的音频流需要暂停或降低音量
• 焦点可以在不同音频流之间转移

音频流类型的重要性

在启动播放前，必须正确设置音频流类型（StreamUsage），系统会根据此类型应用不同的焦点策略：

// 正确设置音频流类型是良好音频体验的基础
let audioStreamInfo: audio.AudioStreamInfo = {
samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
channels: audio.AudioChannel.CHANNEL_2,
sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
// 关键：根据用途设置正确的音频流类型
usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // 音乐类型
};

申请和释放焦点

根据官方文档，音频焦点的申请和释放是自动完成的：

• 申请焦点：调用AudioRenderer.start()时，系统自动申请焦点
• 释放焦点：调用AudioRenderer.pause()/stop()/release()时，系统自动释放焦点

音频打断机制详解

音频焦点争夺是指多个应用同时请求音频播放权限时产生的冲突。比如同时播放：当音乐软件）播放时，打开视频软件，两者声音重叠。或者播放中断：看视频时突然来电话，视频声音被暂停或降低音量。这时就涉及到了音频打断机制。

打断类型

HarmonyOS定义了两种打断类型，处理方式有所不同：

1. 强制打断 (INTERRUPT_FORCE)

系统已强制执行相应操作，应用只需更新状态：

if (interruptEvent.forceType === audio.InterruptForceType.INTERRUPT_FORCE) {
// 系统已执行操作，应用更新UI和状态即可
}

典型场景:

• 来电：音乐必须暂停
• 闹钟：音乐必须暂停
• 系统通知：音乐可能需要降低音量

2. 共享打断 (INTERRUPT_SHARE)

应用需要主动执行操作：

if (interruptEvent.forceType === audio.InterruptForceType.INTERRUPT_SHARE) {
// 应用需要主动执行恢复等操作
}

典型场景:

• 导航语音：音乐可以选择降低音量或暂停
• TextReader朗读：音乐可以选择暂停或静音

官方说明：默认焦点策略下，除INTERRUPT_HINT_RESUME外，其他hintType均为INTERRUPT_FORCE类型。

打断提示类型

系统通过不同的提示类型告知应用如何处理：

实现音频焦点管理

场景1：TextReader朗读时

// 当TextReader开始朗读歌词时：
// 音乐收到 INTERRUPT_HINT_PAUSE（强制打断）
// 系统已暂停音乐，应用更新UI显示暂停状态

// 当TextReader结束朗读时：
// 音乐收到 INTERRUPT_HINT_RESUME（共享打断）
// 应用需要主动调用start()恢复播放

用户操作 音频焦点变化 应用响应
────────────────────────────────────────────────────────────
播放音乐 → AudioRenderer 获得焦点 → 音乐正常播放
点击朗读 → TextReader 请求焦点 → 系统发送打断事件
→ AudioRenderer 失去焦点 → 音乐暂停/降低音量
→ TextReader 获得焦点 → 开始语音朗读
朗读结束 → TextReader 释放焦点 → 停止朗读
→ AudioRenderer 可恢复焦点 → 音乐恢复播放

场景2：来电时

// 来电响铃时：
// 音乐收到 INTERRUPT_HINT_PAUSE（强制打断）
// 系统已暂停音乐，应用更新UI

// 电话结束后：
// 音乐收到 INTERRUPT_HINT_RESUME（共享打断）
// 应用主动恢复播放

步骤1：基础打断处理

修改 AudioRendererController.ets，实现官方推荐的打断处理逻辑：音频焦点争夺需要优雅处理。核心是监听系统事件，并区分“用户暂停”与“系统打断”。以下是实现该逻辑的关键部分：

1. 核心状态

首先，我们需要一个状态来记录暂停原因：

private wasPausedByInterrupt: boolean = false;
// true = 被系统打断 | false = 用户主动暂停

这个标记决定了收到恢复信号时是否自动重启播放。

2. 监听系统打断

接下来，设置系统音频中断事件的监听器：

this.audioRenderer.on('audioInterrupt', this.interruptCallback);

当有其他应用（如电话、导航）请求音频焦点时，系统会通过这个回调通知我们。

3. 处理不同中断类型

最重要的部分是处理各种中断情况，我将其分为三类：

情况A：被系统暂停或停止

case INTERRUPT_HINT_PAUSE: // 如来电
this.wasPausedByInterrupt = true; // 标记为系统打断
break;
case INTERRUPT_HINT_STOP: // 被更高优先级应用占用
this.wasPausedByInterrupt = false;
break;

这里只需更新状态，系统已实际暂停了音频。

情况B：收到恢复信号

case INTERRUPT_HINT_RESUME: // 系统通知可以恢复了
if (this.wasPausedByInterrupt) { // 如果是系统打断的
await this.audioRenderer?.start(); // 才自动恢复播放
this.wasPausedByInterrupt = false;
}
break;

这是最关键的逻辑：只有之前被系统打断的情况才自动恢复。

情况C：音量临时调整

case INTERRUPT_HINT_DUCK: // 音量被降低（如导航播报）
// 通常只需UI提示，系统已处理音量
break;

4. 用户主动操作

最后，当用户自己点击暂停时，要重置状态：

public async pause(): Promise<void> {
await this.audioRenderer.pause();
this.wasPausedByInterrupt = false; // 清除自动恢复标记
}

这样确保用户手动暂停后，即使收到系统恢复信号也不会意外播放。

整个逻辑的核心就是 “谁暂停的，谁负责恢复”：

• 系统暂停的 → 系统通知恢复时自动播放
• 用户暂停的 → 保持暂停，等待用户操作

这样既保证了电话挂断后音乐能自动回来，又避免了用户手动暂停后被意外打扰。

步骤2：设置焦点模式

焦点模式决定了应用内多个音频如何共存。

系统提供两种模式： SHARE_MODE（共享模式）：应用内音频共用焦点，适合音乐播放器 INDEPENDENT_MODE（独立模式）：每个音频独立管理，适合音视频编辑器

这里选择SHARE_MODE是因为对于音乐/视频播放应用，通常希望应用内只有一个声音在播放。当开始播新音频时，系统会自动暂停之前的音频，避免内部冲突。

export class AudioRendererController {
/**
* 初始化音频渲染器
*/
public async initAudioRenderer(context: common.UIAbilityContext): Promise<void> {
// … 创建AudioRenderer …

// 设置焦点模式（默认是SHARE_MODE）
this.setFocusMode();

// 设置打断回调
this.setInterruptCallback();
}

/**
* 设置焦点模式
*/
private setFocusMode(): void {
if (!this.audioRenderer) {
return;
}

// SHARE_MODE: 同一应用内音频流共享焦点（默认）
// INDEPENDENT_MODE: 每个音频流独立拥有焦点
this.audioRenderer.setInterruptMode(audio.InterruptMode.SHARE_MODE);
Logger.info(TAG, '设置焦点模式为SHARE_MODE');
}
}

步骤3：实现静音播放模式

静音模式让音频“只播不争”，实现无干扰的背景播放。

这个功能很有趣：

• 开启时：你的音频会静音播放，但不争夺音频焦点

• 效果：其他应用（如导航、通话）可以正常播放声音，不受影响

• 用途：适合后台缓冲、无声预览、或需要同时听其他音频的场景

简单说，就像“静音看电视”——画面在播，但不妨碍你听别人说话。

export class AudioRendererController {
/**
* 设置静音并发播放模式
* @param enabled true: 静音播放，不影响其他音频；false: 正常模式
*/
public async setSilentModeAndMixWithOthers(enabled: boolean): Promise<void> {
if (!this.audioRenderer) {
return;
}

try {
// 设置静音并发播放模式
this.audioRenderer.setSilentModeAndMixWithOthers(enabled);

if (enabled) {
Logger.info(TAG, '启用静音并发播放模式');
// 此时音乐静音播放，但不影响其他音频流获得焦点
// 适合场景：背景音乐、缓冲加载时
} else {
Logger.info(TAG, '关闭静音并发播放模式');
// 恢复正常播放模式
}

// 保存设置
AppStorage.setOrCreate('isSilentMode', enabled);

} catch (err) {
Logger.error(TAG, `设置静音模式失败: ${JSON.stringify(err)}`);
}
}
}

总结

通过本文的学习，我们掌握了：

核心知识点

下篇预告

在下一篇中，我们将深入探讨：

• AudioSession的高级配置
• 多音频流并发控制
• 性能优化策略
• 复杂场景下的焦点管理

音频焦点管理是专业音频应用的基础。通过理解系统协调机制、正确处理打断事件、区分用户与系统操作，你的应用能够优雅应对各类播放冲突，为用户提供流畅无缝的音频体验。

掌握了这些核心能力后，你的播放器已经具备了应对日常场景的稳健性。而在进阶篇中，我们将探讨更精细的音频会话管理、多流并发的复杂控制以及性能优化策略，帮助构建真正专业级的音频应用。

参考资源

• 音频焦点介绍
• 音频流类型详解