引言：当听书遇到广告

许多HarmonyOS应用开发者都遇到过这样一个令人头疼的场景：用户正在使用听书功能，沉浸在精彩的有声内容中，此时应用需要展示一个广告页面或启动其他音频功能。结果，听书音频被无情中断，即使用户关闭广告返回应用，听书也无法自动恢复。这种糟糕的体验不仅让用户感到困惑，更可能导致用户流失。

这个问题的根源并非简单的代码bug，而是HarmonyOS为管理多音频流并发播放而设计的音频焦点（Audio Focus）机制。本文将深入剖析这一机制，并提供一套完整的解决方案，确保你的应用能够优雅地处理音频冲突，提供流畅的听觉体验。

问题根源：音频焦点机制解析

1. 系统默认的音频焦点策略

HarmonyOS采用音频焦点机制来解决多音频流播放冲突问题。简单来说，系统就像一个音频调度员，当多个应用或同一应用内的多个音频流同时请求播放时，调度员需要决定谁可以"发言"。

系统提供了四种标准的中断策略：

策略类型

行为描述

适用场景

终止策略（Stop）​

停止先播音频流，使其永久失焦，后播音频流结束后不恢复

高优先级音频打断低优先级音频

暂停策略（Pause）​

暂停先播音频流，使其暂时失焦，后播音频流结束后恢复播放

临时性音频打断（如通知音）

降音策略（Duck）​

与先播音频流并发播放，但降低先播音频流的音量

导航语音与音乐同时播放

并发策略（Mix）​

与先播音频流并发播放，音量不变

游戏音效与背景音乐

2. 问题定位：为什么听书会被中断？

根据华为官方文档的分析，问题通常出现在以下场景：

// 问题代码示例：简单的音频播放
audioRenderer.start((err: BusinessError) => {
  if (err) {
    console.error(`Renderer start failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info('Renderer start success.');
  }
});

// 或者使用AVPlayer
avPlayer.play((err: BusinessError) => {
  if (err) {
    console.error(`Failed to play, error message is ${err.message}`);
  } else {
    console.info('Succeeded in playing');
  }
});

关键问题：上述代码没有配置音频会话（AudioSession），系统会采用默认的焦点策略。当听书音频（类型为STREAM_USAGE_MEDIA）遇到广告音频（类型也为STREAM_USAGE_MEDIA）时，系统默认采用终止策略，导致听书被永久中断。

解决方案：使用AudioSession精细化控制

1. AudioSession的核心作用

AudioSession是HarmonyOS提供的音频会话管理机制，它允许应用在系统默认策略的基础上进行自定义调整。通过AudioSession，你可以：

  • 定义音频流的并发模式

  • 监听音频焦点变化事件

  • 在焦点丢失/恢复时执行自定义逻辑

  • 协调应用内多个音频流的播放关系

2. 完整实现方案

步骤1：创建并配置AudioSession
// AudioSessionManager.ets - 音频会话管理类
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@ohos.base';

export class AudioSessionManager {
  private audioSessionManager: audio.AudioSessionManager;
  private currentSession: audio.AudioSession | null = null;
  private isPlaying: boolean = false;
  private resumePosition: number = 0; // 用于记录播放位置

  constructor() {
    this.audioSessionManager = audio.getAudioSessionManager();
  }

  /**
   * 创建听书专用的音频会话
   */
  createAudiobookSession(): audio.AudioSession {
    try {
      // 创建音频会话，类型为MEDIA，模式为独立
      const session = this.audioSessionManager.createAudioSession(
        audio.AudioSessionType.MEDIA,
        audio.AudioSessionMode.INDEPENDENT
      );

      // 配置会话参数
      const parameters: audio.AudioSessionParameters = {
        sessionId: session.sessionId,
        audioEffectMode: audio.AudioEffectMode.EFFECT_DEFAULT,
        deviceFlag: audio.DeviceFlag.OUTPUT_DEVICES_FLAG,
        streamUsage: audio.StreamUsage.STREAM_USAGE_MEDIA, // 媒体流类型
        contentType: audio.ContentType.CONTENT_TYPE_MUSIC, // 内容类型为音乐
        audioInterruptMode: audio.AudioInterruptMode.AUDIO_INTERRUPT_MODE_INDEPENDENT
      };

      // 激活会话
      session.activate(parameters);
      
      // 设置并发模式为MIX_WITH_OTHERS，允许与其他音频并发播放
      session.audioConcurrencyMode = audio.AudioConcurrencyMode.CONCURRENCY_MIX_WITH_OTHERS;

      this.currentSession = session;
      this.setupInterruptListener(session);
      
      return session;
    } catch (error) {
      const err = error as BusinessError;
      console.error(`创建音频会话失败: ${err.code}, ${err.message}`);
      throw err;
    }
  }

  /**
   * 设置音频中断监听器
   */
  private setupInterruptListener(session: audio.AudioSession): void {
    session.on('interrupt', (interruptEvent: audio.InterruptEvent) => {
      console.info(`音频中断事件: type=${interruptEvent.eventType}, forcePaused=${interruptEvent.forcePaused}`);
      
      switch (interruptEvent.eventType) {
        case audio.InterruptType.INTERRUPT_TYPE_BEGIN:
          // 音频焦点被其他音频抢占
          this.handleInterruptBegin(interruptEvent);
          break;
          
        case audio.InterruptType.INTERRUPT_TYPE_END:
          // 音频焦点恢复
          this.handleInterruptEnd(interruptEvent);
          break;
      }
    });
  }

  /**
   * 处理中断开始事件
   */
  private handleInterruptBegin(event: audio.InterruptEvent): void {
    if (event.forcePaused && this.isPlaying) {
      // 记录当前播放位置
      this.resumePosition = this.getCurrentPlayPosition();
      // 暂停播放
      this.pausePlayback();
      console.info('听书播放被暂停，已记录当前位置');
    }
  }

  /**
   * 处理中断结束事件
   */
  private handleInterruptEnd(event: audio.InterruptEvent): void {
    if (event.forceResumed && !this.isPlaying) {
      // 询问用户是否恢复播放
      this.promptResumePlayback();
    }
  }

  /**
   * 提示用户恢复播放
   */
  private async promptResumePlayback(): Promise<void> {
    try {
      const promptAction = this.getUIContext().getPromptAction();
      const result = await promptAction.showDialog({
        title: '听书恢复',
        message: '广告播放结束，是否继续听书？',
        buttons: [
          { text: '继续播放', color: '#007DFF' },
          { text: '取消', color: '#999999' }
        ]
      });

      if (result.index === 0) {
        // 用户选择继续播放
        this.resumePlayback();
      }
    } catch (error) {
      console.error('恢复播放提示失败:', error);
    }
  }

  /**
   * 释放音频会话资源
   */
  releaseSession(): void {
    if (this.currentSession) {
      this.currentSession.off('interrupt'); // 取消事件监听
      this.currentSession.deactivate();
      this.audioSessionManager.releaseAudioSession(this.currentSession.sessionId);
      this.currentSession = null;
    }
  }

  // 其他辅助方法...
  private getCurrentPlayPosition(): number {
    // 实现获取当前播放位置逻辑
    return 0;
  }

  private pausePlayback(): void {
    // 实现暂停播放逻辑
    this.isPlaying = false;
  }

  private resumePlayback(): void {
    // 实现恢复播放逻辑
    this.isPlaying = true;
  }
}
步骤2：在听书播放器中应用AudioSession
// AudiobookPlayer.ets - 听书播放器组件
import { media } from '@kit.MediaKit';
import { AudioSessionManager } from './AudioSessionManager';

@Component
export struct AudiobookPlayer {
  private avPlayer: media.AVPlayer = media.createAVPlayer();
  private audioSessionManager: AudioSessionManager = new AudioSessionManager();
  private audioSession: audio.AudioSession | null = null;
  
  @State currentBook: Audiobook | null = null;
  @State isPlaying: boolean = false;
  @State currentPosition: number = 0;

  aboutToAppear(): void {
    // 初始化音频会话
    this.initializeAudioSession();
  }

  aboutToDisappear(): void {
    // 释放资源
    this.releaseResources();
  }

  /**
   * 初始化音频会话
   */
  private initializeAudioSession(): void {
    try {
      // 创建听书专用的音频会话
      this.audioSession = this.audioSessionManager.createAudiobookSession();
      
      // 将音频会话关联到AVPlayer
      this.avPlayer.audioSession = this.audioSession;
      
      // 配置AVPlayer
      this.configureAVPlayer();
    } catch (error) {
      console.error('初始化音频会话失败:', error);
    }
  }

  /**
   * 配置AVPlayer
   */
  private configureAVPlayer(): void {
    // 设置音频流类型为媒体
    this.avPlayer.audioStreamType = media.AudioStreamType.STREAM_MUSIC;
    
    // 监听播放状态
    this.avPlayer.on('stateChange', (state: string) => {
      console.info(`播放器状态变化: ${state}`);
      this.isPlaying = state === 'playing';
    });
    
    // 监听播放进度
    this.avPlayer.on('timeUpdate', (time: number) => {
      this.currentPosition = time;
    });
  }

  /**
   * 开始播放听书
   */
  async playAudiobook(book: Audiobook): Promise<void> {
    try {
      this.currentBook = book;
      
      // 设置播放源
      this.avPlayer.url = book.audioUrl;
      await this.avPlayer.prepare();
      
      // 开始播放
      await this.avPlayer.play();
      console.info(`开始播放: ${book.title}`);
    } catch (error) {
      const err = error as BusinessError;
      console.error(`播放失败: ${err.code}, ${err.message}`);
      this.showErrorMessage('播放失败，请重试');
    }
  }

  /**
   * 暂停播放
   */
  async pausePlayback(): Promise<void> {
    try {
      await this.avPlayer.pause();
      console.info('播放已暂停');
    } catch (error) {
      console.error('暂停播放失败:', error);
    }
  }

  /**
   * 恢复播放
   */
  async resumePlayback(): Promise<void> {
    try {
      await this.avPlayer.play();
      console.info('播放已恢复');
    } catch (error) {
      console.error('恢复播放失败:', error);
    }
  }

  /**
   * 释放资源
   */
  private releaseResources(): void {
    if (this.avPlayer) {
      this.avPlayer.release();
    }
    if (this.audioSession) {
      this.audioSessionManager.releaseSession();
    }
  }

  build() {
    Column() {
      // 听书播放器UI
      if (this.currentBook) {
        AudiobookPlayerUI({
          book: this.currentBook,
          isPlaying: this.isPlaying,
          currentPosition: this.currentPosition,
          onPlayPause: () => {
            if (this.isPlaying) {
              this.pausePlayback();
            } else {
              this.resumePlayback();
            }
          }
        })
      }
    }
  }
}
步骤3：广告播放器的优化配置
// AdPlayer.ets - 广告播放器组件
import { media } from '@kit.MediaKit';
import { audio } from '@kit.AudioKit';

@Component
export struct AdPlayer {
  private avPlayer: media.AVPlayer = media.createAVPlayer();
  private audioSessionManager: audio.AudioSessionManager;
  private adAudioSession: audio.AudioSession | null = null;

  aboutToAppear(): void {
    this.audioSessionManager = audio.getAudioSessionManager();
    this.initializeAdAudioSession();
  }

  /**
   * 初始化广告音频会话
   * 关键：将广告音频类型设置为游戏或通知，避免中断听书
   */
  private initializeAdAudioSession(): void {
    try {
      // 方案1：设置为游戏类型（与听书并发播放）
      this.adAudioSession = this.audioSessionManager.createAudioSession(
        audio.AudioSessionType.GAME,
        audio.AudioSessionMode.INDEPENDENT
      );

      // 方案2：设置为通知类型（暂停听书，广告结束后恢复）
      // this.adAudioSession = this.audioSessionManager.createAudioSession(
      //   audio.AudioSessionType.NOTIFICATION,
      //   audio.AudioSessionMode.INDEPENDENT
      // );

      const parameters: audio.AudioSessionParameters = {
        sessionId: this.adAudioSession.sessionId,
        audioEffectMode: audio.AudioEffectMode.EFFECT_DEFAULT,
        deviceFlag: audio.DeviceFlag.OUTPUT_DEVICES_FLAG,
        streamUsage: audio.StreamUsage.STREAM_USAGE_GAME, // 关键：游戏流类型
        contentType: audio.ContentType.CONTENT_TYPE_MOVIE,
        audioInterruptMode: audio.AudioInterruptMode.AUDIO_INTERRUPT_MODE_SHAREABLE
      };

      this.adAudioSession.activate(parameters);
      
      // 设置并发模式为DUCK_OTHERS，降低其他音频音量
      this.adAudioSession.audioConcurrencyMode = audio.AudioConcurrencyMode.CONCURRENCY_DUCK_OTHERS;
      
      // 关联到AVPlayer
      this.avPlayer.audioSession = this.adAudioSession;
      
    } catch (error) {
      console.error('广告音频会话初始化失败:', error);
    }
  }

  /**
   * 播放广告
   */
  async playAd(adUrl: string): Promise<void> {
    try {
      this.avPlayer.url = adUrl;
      await this.avPlayer.prepare();
      
      // 监听广告播放结束
      this.avPlayer.on('endOfStream', () => {
        console.info('广告播放结束');
        this.releaseAdSession();
      });
      
      await this.avPlayer.play();
    } catch (error) {
      console.error('广告播放失败:', error);
    }
  }

  /**
   * 释放广告音频会话
   */
  private releaseAdSession(): void {
    if (this.adAudioSession) {
      this.adAudioSession.deactivate();
      this.audioSessionManager.releaseAudioSession(this.adAudioSession.sessionId);
      this.adAudioSession = null;
    }
  }

  aboutToDisappear(): void {
    this.releaseAdSession();
    if (this.avPlayer) {
      this.avPlayer.release();
    }
  }
}

最佳实践与进阶技巧

1. 音频流类型选择策略

根据业务场景选择合适的音频流类型，可以有效避免不必要的音频冲突：

音频场景

推荐StreamUsage

行为特点

听书/音乐播放

STREAM_USAGE_MEDIA

标准媒体流，可被高优先级音频中断

游戏音效

STREAM_USAGE_GAME

与媒体流并发播放，不会中断媒体

通知/提醒

STREAM_USAGE_NOTIFICATION

短暂播放，采用暂停策略

闹钟

STREAM_USAGE_ALARM

高优先级，会中断其他音频

语音消息

STREAM_USAGE_VOICE_MESSAGE

采用暂停策略，播放后恢复

2. 多音频场景协调策略

对于复杂的多音频应用（如既有听书又有语音识别），可以采用分层管理策略：

// AudioCoordinator.ets - 音频协调管理器
export class AudioCoordinator {
  private sessions: Map<string, audio.AudioSession> = new Map();
  
  /**
   * 注册音频会话
   */
  registerSession(sessionId: string, session: audio.AudioSession, priority: number): void {
    this.sessions.set(sessionId, { session, priority });
    this.coordinateSessions();
  }
  
  /**
   * 协调多个音频会话
   */
  private coordinateSessions(): void {
    // 根据优先级调整各个会话的并发模式
    const sortedSessions = Array.from(this.sessions.values())
      .sort((a, b) => b.priority - a.priority);
    
    sortedSessions.forEach((sessionInfo, index) => {
      if (index === 0) {
        // 最高优先级会话使用独立模式
        sessionInfo.session.audioConcurrencyMode = 
          audio.AudioConcurrencyMode.CONCURRENCY_MIX_WITH_OTHERS;
      } else {
        // 低优先级会话使用降音或暂停模式
        sessionInfo.session.audioConcurrencyMode = 
          audio.AudioConcurrencyMode.CONCURRENCY_DUCK_OTHERS;
      }
    });
  }
}

3. 用户体验优化建议

  1. 智能恢复策略：不要总是自动恢复播放，根据中断时长决定是否恢复

    private shouldResumePlayback(interruptDuration: number): boolean {
  // 中断时间小于30秒，自动恢复
  // 中断时间大于30秒，询问用户
  return interruptDuration < 30000;
}

  2. 渐进式音量调整：在音频焦点变化时，使用渐变效果避免突兀

    private async fadeOutVolume(duration: number): Promise<void> {
  const steps = 10;
  const stepDuration = duration / steps;

  for (let i = steps; i >= 0; i--) {
    const volume = i / steps;
    this.avPlayer.volume = volume;
    await this.sleep(stepDuration);
  }
}

  3. 状态持久化：保存播放状态，即使应用被杀死也能恢复

    private savePlaybackState(): void {
  const state = {
    bookId: this.currentBook?.id,
    position: this.currentPosition,
    timestamp: Date.now()
  };
  PersistentStorage.persistProp('audiobook_state', JSON.stringify(state));
}

常见问题排查

Q1: 设置了AudioSession，但听书仍然被中断？

  • 检查音频流类型：确认听书和广告的StreamUsage配置是否正确

  • 验证并发模式：检查audioConcurrencyMode是否设置为CONCURRENCY_MIX_WITH_OTHERS

  • 查看系统日志：使用hilog命令过滤AVSession相关日志，确认焦点变化过程

Q2: 如何测试音频焦点行为？

  • 使用音频焦点测试工具模拟不同场景

  • 在不同优先级音频间切换，观察行为是否符合预期

  • 测试应用被杀后恢复播放的场景

Q3: 音频恢复后出现卡顿或不同步？

  • 检查播放位置记录是否准确

  • 确认缓冲区状态，必要时重新缓冲

  • 考虑使用seek方法精确定位到中断位置

Q4: 多语言音频内容如何处理？

  • 为不同语言内容设置相同的音频会话配置

  • 确保语言切换时音频焦点策略一致

  • 考虑为每种语言创建独立的音频会话进行精细控制

总结

HarmonyOS的音频焦点机制为多音频应用提供了强大的管理能力，但需要开发者深入理解并正确使用。通过本文的实战解析，你应该掌握：

  1. 理解机制：音频焦点四种策略（终止、暂停、降音、并发）的应用场景

  2. 正确配置：使用AudioSession精细化控制音频行为

  3. 优雅处理：监听中断事件，实现智能恢复策略

  4. 优化体验：根据业务场景选择合适的音频流类型和并发模式

记住，优秀的音频体验不仅仅是技术实现，更是对用户使用场景的深度理解。当你的应用能够智能地处理音频冲突，在听书、广告、通知等多种音频场景间无缝切换时，用户将获得更加沉浸和愉悦的使用体验。

核心要点总结：

  • 默认音频策略可能导致听书被永久中断

  • AudioSession是精细化控制的关键

  • 合理选择StreamUsage可以避免不必要的冲突

  • 始终以用户体验为中心设计音频交互逻辑

通过本文的实践方案，你的HarmonyOS应用将能够提供专业级的音频体验，让用户在享受听书的同时，不会因为必要的广告或通知而被打断沉浸感。

# harmonyos # 学习 # 音视频
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙实战：用 want.param 实现视频播放器跨端迁移续播

avatar HarmonyOS开发者社区
cover

鸿蒙游戏 UI 怎么设计才不乱？

avatar HarmonyOS开发者社区
cover

HarmonyOS 6学习：解决应用打开中断听书功能——音频焦点与AudioSession实战

avatar HarmonyOS开发者社区