响应输出设备变更时合理暂停
=============

开发者可以了解音频流输出设备变更信息，并完成相应适配，比如：应用在播放音乐时发现输出设备下线，为避免打扰用户，应该立即暂停音乐。

开发者可使用AudioRenderer的[on('outputDeviceChangeWithInfo')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiorenderer#onoutputdevicechangewithinfo11)或AudioSessionManager的[on('currentOutputDeviceChanged')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager#oncurrentoutputdevicechanged20)，用于监听音频流输出设备变化及原因。当系统出现音频输出设备的上下线、用户强选、设备抢占或设备选择策略变更等情况，导致音频流输出设备变更时，系统将通过该接口通知应用当前音频流设备变更信息，包含当前音频流输出设备信息和设备变更原因。

#### 音频流输出设备信息

在AudioRenderer的[on('outputDeviceChangeWithInfo')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiorenderer#onoutputdevicechangewithinfo11)或AudioSessionManager的[on('currentOutputDeviceChanged')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-audiosessionmanager#oncurrentoutputdevicechanged20)返回的音频流设备变更信息中，包含当前音频流输出设备信息，以数组形式发送，一般该列表仅包含一个设备信息，具体可参考[AudioDeviceDescriptors](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-t#audiodevicedescriptors)（设备信息列表）。

#### 音频流输出设备变更原因

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/46/v3/oFIhPmUhROGoNeuN5SF7Kg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073506Z&HW-CC-Expire=86400&HW-CC-Sign=3B3DE98A9CFC209BAE8AACD9051B8B9002F42A0100AF02F5CEA5ABE5AE784052)

当发生下述四种情况（[AudioStreamDeviceChangeReason](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-audio-e#audiostreamdevicechangereason11)）时，系统将向应用发送设备变更回调。

*   **REASON\_NEW\_DEVICE\_AVAILABLE**：新设备可用。
    
    **触发场景：**
    
    普通蓝牙设备（耳机、眼镜、音箱、车机等）连接、支持佩戴检测的蓝牙设备（耳机、眼镜等）佩戴、有线设备（3.5mm耳机、Type-C耳机、USB耳机、USB音箱等）插入、分布式设备上线等。
    
*   **REASON\_OLD\_DEVICE\_UNAVAILABLE**：旧设备不可用。
    
    当报告此原因时，应用程序应考虑暂停音频播放。
    
    **触发场景：**
    
    普通蓝牙设备（耳机、眼镜、音箱、车机等）断开、支持佩戴检测的蓝牙耳机双耳摘下、支持佩戴检测的蓝牙眼镜摘下、有线设备（3.5mm耳机、Type-C耳机、USB耳机、USB音箱等）拔出、分布式设备下线等。
    
    针对此场景，常用业务场景的**处理建议**如下：
    
    *   游戏场景：不暂停
    *   听书场景：暂停
    *   音乐场景：暂停
    *   视频场景：暂停
*   **REASON\_OVERRODE**：用户强制选择设备。
    
    **触发场景：**
    
    用户从界面选择切换音频流输出设备、从外设选择接听蜂窝或VoIP来电。
    
*   **REASON\_UNKNOWN**：未知原因。
    

#### 参考示例

以下各步骤示例为片段代码，可通过示例代码右下方链接获取[完整示例](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/Media/Audio/AudioRoutingManagerSampleJS)。

#### \[h2\]AudioRenderer示例

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let audioRenderer: audio.AudioRenderer | undefined = undefined;
let audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE\_RATE\_48000, // 采样率。
  channels: audio.AudioChannel.CHANNEL\_2, // 通道。
  sampleFormat: audio.AudioSampleFormat.SAMPLE\_FORMAT\_S16LE, // 采样格式。
  encodingType: audio.AudioEncodingType.ENCODING\_TYPE\_RAW // 编码格式。
};
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM\_USAGE\_MUSIC, // 音频流使用类型:音乐。根据业务场景配置,参考StreamUsage。
  rendererFlags: 0 // 音频渲染器标志。
};
let audioRendererOptions: audio.AudioRendererOptions = {
  streamInfo: audioStreamInfo,
  rendererInfo: audioRendererInfo
};
// ...

  // 创建AudioRenderer实例。
  audio.createAudioRenderer(audioRendererOptions).then((data) => {
    audioRenderer = data;
    console.info('AudioFrameworkRenderLog: AudioRenderer Created : Success : Stream Type: SUCCESS');
    // ...
  }).catch((err: BusinessError) => {
    console.error(\`AudioFrameworkRenderLog: AudioRenderer Created : ERROR : ${err}\`);
    // ...
  });

  if (audioRenderer) {
    // 订阅监听音频流输出设备变化及原因。
    (audioRenderer as audio.AudioRenderer).on('outputDeviceChangeWithInfo', async (deviceChangeInfo: audio
    .AudioStreamDeviceChangeInfo) => {
      switch (deviceChangeInfo.changeReason) {
        case audio.AudioStreamDeviceChangeReason.REASON\_OLD\_DEVICE\_UNAVAILABLE:
          // 响应设备不可用事件,如果应用处于播放状态,应暂停播放,更新UX界面。
          // await audioRenderer.pause();
          break;
        case audio.AudioStreamDeviceChangeReason.REASON\_NEW\_DEVICE\_AVAILABLE:
          // 应用根据业务情况响应设备可用事件。
          break;
        case audio.AudioStreamDeviceChangeReason.REASON\_OVERRODE:
          // 应用根据业务情况响应设备强选事件。
          break;
        case audio.AudioStreamDeviceChangeReason.REASON\_UNKNOWN:
          // 应用根据业务情况响应未知原因事件。
          break;
      }
    });
  }

#### \[h2\]AudioSessionManager示例

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

let audioRenderer: audio.AudioRenderer | undefined = undefined;
let audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE\_RATE\_48000, // 采样率。
  channels: audio.AudioChannel.CHANNEL\_2, // 通道。
  sampleFormat: audio.AudioSampleFormat.SAMPLE\_FORMAT\_S16LE, // 采样格式。
  encodingType: audio.AudioEncodingType.ENCODING\_TYPE\_RAW // 编码格式。
};
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM\_USAGE\_MUSIC, // 音频流使用类型：音乐。根据业务场景配置，参考StreamUsage。
  rendererFlags: 0 // 音频渲染器标志。
};
let audioRendererOptions: audio.AudioRendererOptions = {
  streamInfo: audioStreamInfo,
  rendererInfo: audioRendererInfo
};

// 创建AudioRenderer实例。
audio.createAudioRenderer(audioRendererOptions).then((data) => {
  audioRenderer = data;
  console.info('AudioFrameworkRenderLog: AudioRenderer Created : Success : Stream Type: SUCCESS');
}).catch((err: BusinessError) => {
  console.error(\`AudioFrameworkRenderLog: AudioRenderer Created : ERROR : ${err}\`);
});

if (audioRenderer) {
  try {
    let sessionManager = audio.getAudioManager().getSessionManager();
    sessionManager.activateAudioSession({ concurrencyMode: audio.AudioConcurrencyMode.CONCURRENCY\_MIX\_WITH\_OTHERS });
    // 订阅监听音频流输出设备变化及原因。
    sessionManager.on('currentOutputDeviceChanged', async (deviceChangeInfo: audio.CurrentOutputDeviceChangedEvent) => {
      switch (deviceChangeInfo.changeReason) {
        case audio.AudioStreamDeviceChangeReason.REASON\_OLD\_DEVICE\_UNAVAILABLE:
          // 响应设备不可用事件，如果应用处于播放状态，应暂停播放，更新UX界面。
          // await audioRenderer.pause();
          console.info('REASON\_OLD\_DEVICE\_UNAVAILABLE, pause audio is recommended');
          break;
        case audio.AudioStreamDeviceChangeReason.REASON\_NEW\_DEVICE\_AVAILABLE:
          // 应用根据业务情况响应设备可用事件。
          break;
        case audio.AudioStreamDeviceChangeReason.REASON\_OVERRODE:
          // 应用根据业务情况响应设备强选事件。
          break;
        case audio.AudioStreamDeviceChangeReason.REASON\_UNKNOWN:
          // 应用根据业务情况响应未知原因事件。
          break;
      }
    });
  } catch (err) {
    console.error(\`on sessionManager#currentOutputDeviceChanged fail: ${err}\`);
  }
}