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

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

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

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

前言

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

然而，当多个声音同时响起时，美好的体验也可能被打断------想象一下，正用 TextReader 听着歌词解读，背景音乐却依然播放；开车时，突然有电话进来，音乐与电话铃声交杂在一起。

这些声音的"冲突"，不仅影响使用感受，更可能让核心信息淹没在嘈杂的音频流中。

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

音频焦点基础

什么是音频焦点

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

核心原则：

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

音频流类型的重要性

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

typescript 复制代码

// 正确设置音频流类型是良好音频体验的基础
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)

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

typescript 复制代码

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

典型场景:

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

2. 共享打断 (INTERRUPT_SHARE)

应用需要主动执行操作：

typescript 复制代码

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

典型场景:

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

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

打断提示类型

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

提示类型	系统操作	应用职责
`INTERRUPT_HINT_PAUSE`	已暂停音频	更新UI状态
`INTERRUPT_HINT_STOP`	已停止音频	更新UI状态
`INTERRUPT_HINT_DUCK`	已降低音量	可选：显示音量降低提示
`INTERRUPT_HINT_UNDUCK`	已恢复音量	可选：显示音量恢复提示
`INTERRUPT_HINT_RESUME`	无（共享打断）	必须主动恢复播放

实现音频焦点管理

场景1：TextReader朗读时

typescript 复制代码

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

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

复制代码

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

场景2：来电时

typescript 复制代码

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

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

步骤1：基础打断处理

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

1. 核心状态

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

typescript 复制代码

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

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

2. 监听系统打断

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

typescript 复制代码

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

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

3. 处理不同中断类型

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

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

typescript 复制代码

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

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

情况B：收到恢复信号

typescript 复制代码

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

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

情况C：音量临时调整

typescript 复制代码

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

4. 用户主动操作

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

typescript 复制代码

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

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

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

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

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

步骤2：设置焦点模式

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

系统提供两种模式：

SHARE_MODE（共享模式）：应用内音频共用焦点，适合音乐播放器

INDEPENDENT_MODE（独立模式）：每个音频独立管理，适合音视频编辑器

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

typescript 复制代码

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：实现静音播放模式

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

这个功能很有趣：

开启时：你的音频会静音播放，但不争夺音频焦点
效果：其他应用（如导航、通话）可以正常播放声音，不受影响
用途：适合后台缓冲、无声预览、或需要同时听其他音频的场景

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

typescript 复制代码

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)}`);
    }
  }
}

总结

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

核心知识点

音频焦点机制：系统如何协调多个音频流
打断类型区分：强制打断 vs 共享打断
正确的事件处理：大多数情况系统已处理，应用只需更新状态
音频流类型的重要性：正确设置StreamUsage是良好体验的基础

下篇预告

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

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

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

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

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

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