1# 管理全局音频输出设备 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8应用可通过以下两种方式管理全局音频输出设备： 9- 通常情况下，可以通过[AudioRoutingManager管理全局音频输出设备](#通过audioroutingmanager管理全局音频输出设备)。 10- 从API 20开始，AudioSessionManager提供了部分输出设备管理的接口，支持通过[AudioSession管理全局音频输出](#通过audiosession管理全局音频输出设备)，方便在使用AudioSession管理音频焦点的同时管理音频输出。 11## 通过AudioRoutingManager管理全局音频输出设备 12 13本模块提供音频输出设备管理能力，包括查询设备信息和监听连接状态变化。具体API说明请参考文档[AudioRoutingManager](../../reference/apis-audio-kit/arkts-apis-audio-AudioRoutingManager.md)。 14 15### 创建AudioRoutingManager实例 16 17在使用AudioRoutingManager管理音频设备前，需要先导入模块并创建实例。 18 19```ts 20import { audio } from '@kit.AudioKit'; // 导入audio模块。 21 22let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。 23 24let audioRoutingManager = audioManager.getRoutingManager(); // 再调用AudioManager的方法创建AudioRoutingManager实例。 25``` 26 27### 支持的音频输出设备类型 28 29目前支持的输出设备如下表所示： 30 31| 名称 | 值 | 说明 | 32| -------- | -------- | -------- | 33| EARPIECE | 1 | 听筒。 | 34| SPEAKER | 2 | 扬声器。 | 35| WIRED_HEADSET | 3 | 有线耳机，带麦克风。 | 36| WIRED_HEADPHONES | 4 | 有线耳机，无麦克风。 | 37| BLUETOOTH_SCO | 7 | 蓝牙设备SCO（Synchronous Connection Oriented）连接。 | 38| BLUETOOTH_A2DP | 8 | 蓝牙设备A2DP（Advanced Audio Distribution Profile）连接。 | 39| USB_HEADSET | 22 | USB耳机，带麦克风。 | 40 41### 获取输出设备信息 42 43使用getDevices()方法可以获取当前所有输出设备的信息。 44 45```ts 46import { audio } from '@kit.AudioKit'; 47 48audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 49 console.info('Promise returned to indicate that the device list is obtained.'); 50}); 51``` 52 53### 监听设备连接状态变化 54 55设置监听事件以监控设备连接状态的变化，设备连接或断开时触发回调。 56 57> **说明：** 58> 59> 监听设备连接状态变化可以监听到全部的设备连接状态变化，不建议作为应用处理自动暂停的依据。应用如需处理自动暂停相关业务，可参考[音频流输出设备变更原因](audio-output-device-change.md)。 60 61```ts 62import { audio } from '@kit.AudioKit'; 63 64// 监听音频设备状态变化。 65audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (deviceChanged: audio.DeviceChangeAction) => { 66 console.info(`device change type : ${deviceChanged.type}`); // 设备连接状态变化，0为连接，1为断开连接。 67 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length}`); 68 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole}`); // 设备角色。 69 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType}`); // 设备类型。 70}); 71 72// 取消监听音频设备状态变化。 73audioRoutingManager.off('deviceChange'); 74``` 75 76<!--Del--> 77### 选择音频输出设备（仅对系统应用开放） 78 79选择音频输出设备，当前只能选择一个输出设备，以设备ID作为唯一标识。AudioDeviceDescriptors的具体信息可以参考[AudioDeviceDescriptors](../../reference/apis-audio-kit/arkts-apis-audio-t.md#audiodevicedescriptors)。 80 81> **说明：** 82> 83> 用户可以选择连接一组音频设备（如一对蓝牙耳机），但系统侧只感知为一个设备，该组设备共用一个设备ID。 84 85```ts 86import { audio } from '@kit.AudioKit'; 87import { BusinessError } from '@kit.BasicServicesKit'; 88 89let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 90 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 91 deviceType : audio.DeviceType.SPEAKER, 92 id : 1, 93 name : "", 94 address : "", 95 sampleRates : [44100], 96 channelCounts : [2], 97 channelMasks : [0], 98 networkId : audio.LOCAL_NETWORK_ID, 99 interruptGroupId : 1, 100 volumeGroupId : 1, 101 displayName : "" 102}]; 103 104async function selectOutputDevice() { 105 audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor).then(() => { 106 console.info('Invoke selectOutputDevice succeeded.'); 107 }).catch((err: BusinessError) => { 108 console.error(`Invoke selectOutputDevice failed, code is ${err.code}, message is ${err.message}`); 109 }); 110} 111``` 112<!--DelEnd--> 113 114### 获取最高优先级输出设备信息 115 116使用getPreferOutputDeviceForRendererInfo()方法, 可以获取当前最高优先级的输出设备。 117 118> **说明：** 119> 120> 最高优先级输出设备表示声音将在此设备输出的设备。 121 122```ts 123import { audio } from '@kit.AudioKit'; 124import { BusinessError } from '@kit.BasicServicesKit'; 125 126let rendererInfo: audio.AudioRendererInfo = { 127 usage: audio.StreamUsage.STREAM_USAGE_MUSIC,// 音频流使用类型：音乐。根据业务场景配置，参考StreamUsage。 128 rendererFlags: 0 // 音频渲染器标志。 129}; 130 131async function getPreferOutputDeviceForRendererInfo() { 132 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((desc: audio.AudioDeviceDescriptors) => { 133 console.info(`device descriptor: ${desc}`); 134 }).catch((err: BusinessError) => { 135 console.error(`Result ERROR: ${err}`); 136 }) 137} 138``` 139 140### 监听最高优先级输出设备变化 141 142```ts 143import { audio } from '@kit.AudioKit'; 144 145let rendererInfo: audio.AudioRendererInfo = { 146 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // 音频流使用类型：音乐。根据业务场景配置，参考StreamUsage。 147 rendererFlags: 0 // 音频渲染器标志。 148}; 149 150// 监听最高优先级输出设备变化。 151audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, (desc: audio.AudioDeviceDescriptors) => { 152 console.info(`device change descriptor : ${desc[0].deviceRole}`); // 设备角色。 153 console.info(`device change descriptor : ${desc[0].deviceType}`); // 设备类型。 154}); 155 156// 取消监听最高优先级输出设备变化。 157audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo'); 158``` 159 160## 通过AudioSession管理全局音频输出设备 161应用使用播放器的SDK播放音频流，不持有AudioRenderer对象，因此无法灵活控制播放设备的选择和状态监听。从API 20开始，AudioSession不仅增加了焦点管理功能，还提供了音频输出设备管理功能，包括设置默认输出设备和监听设备变化。请参考以下文档获取更多信息： 162- ArkTS API：[AudiSessionManager](../../reference/apis-audio-kit/arkts-apis-audio-AudioSessionManager.md) 163- C API：[OH_AudioSessionManager](../../reference/apis-audio-kit/capi-native-audio-session-manager-h.md) 164 165### 创建AudioSession实例 166在使用AudioSessionManager管理音频设备前，需要先导入模块并创建实例。 167```ts 168import { audio } from '@kit.AudioKit'; // 导入audio模块。 169 170let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。 171 172let audioSessionManager = audioManager.getSessionManager(); // 再调用AudioManager的方法创建AudioSessionManager实例。 173``` 174 175### 设置本机默认音频输出设备 176 177[setDefaultOutputDevice](../../reference/apis-audio-kit/arkts-apis-audio-AudioSessionManager.md#setdefaultoutputdevice20)可以用于设置本机默认输出设备。 178> **说明：** 179>- 由于AudioSession是应用级设置，调用本接口设置默认音频输出设备会覆盖AudioRenderer的`setDefaultOutputDevice`接口设置的音频输出设备信息。 180> - 调用`setDefaultOutputDevice`设置音频输出设备后，如需取消，可将参数设为`audio.DeviceType.DEFAULT`，将音频设备选择权交还给系统。否则，每次调用`activateAudioSession`时，应用选择的默认输出设备将生效。 181 182```ts 183import { BusinessError } from '@kit.BasicServicesKit'; 184 185// 设置默认输出设备为本机扬声器。 186audioSessionManager.setDefaultOutputDevice(audio.DeviceType.SPEAKER).then(() => { 187 console.info('setDefaultOutputDevice Success!'); 188}).catch((err: BusinessError) => { 189 console.error(`setDefaultOutputDevice Fail: ${err}`); 190}); 191 192// 设置默认输出设备为默认设备，即取消应用设置的默认设备，交由系统选择设备。 193audioSessionManager.setDefaultOutputDevice(audio.DeviceType.DEFAULT).then(() => { 194 console.info('setDefaultOutputDevice Success!'); 195}).catch((err: BusinessError) => { 196 console.error(`setDefaultOutputDevice Fail: ${err}`); 197}); 198``` 199 200### 查询本机默认音频输出设备 201 202应用可以通过[getDefaultOutputDevice](../../reference/apis-audio-kit/arkts-apis-audio-AudioSessionManager.md#getdefaultoutputdevice20)查询本机默认输出设备类型。 203> **说明：** 204> 205> 本接口用于查询通过[setDefaultOutputDevice](../../reference/apis-audio-kit/arkts-apis-audio-AudioSessionManager.md#setdefaultoutputdevice20)接口设置的输出设备。 206 207```ts 208let deviceType = audioSessionManager.getDefaultOutputDevice(); 209console.info('getDefaultOutputDevice Success, deviceType: ${deviceType}'); 210``` 211 212### 监听输出设备变化 213 214应用可以通过注册[CurrentOutputDeviceChangedEvent](../../reference/apis-audio-kit/arkts-apis-audio-i.md#currentoutputdevicechangedevent20)监听输出设备的连接状态变化。 215 216> **说明：** 217>`currentOutputDeviceChangedCallback` 包含设备变更的原因及推荐的后续操作。应用应根据不同的变更原因进行处理，并按系统推荐的操作继续或停止当前播放。 218 219```ts 220import { audio } from '@kit.AudioKit'; 221 222// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 223let currentOutputDeviceChangedCallback = (currentOutputDeviceChangedEvent: audio.CurrentOutputDeviceChangedEvent) => { 224 console.info(`reason of audioSessionStateChanged: ${currentOutputDeviceChangedEvent.changeReason} `); 225 226 switch (currentOutputDeviceChangedEvent.changeReason) { 227 case audio.AudioStreamDeviceChangeReason.REASON_OLD_DEVICE_UNAVAILABLE: 228 // 响应设备不可用事件，如果应用处于播放状态，应暂停播放，更新UX界面。 229 break; 230 case audio.AudioStreamDeviceChangeReason.REASON_NEW_DEVICE_AVAILABLE: 231 // 应用根据业务情况响应设备可用事件。 232 break; 233 case audio.AudioStreamDeviceChangeReason.REASON_OVERRODE: 234 // 应用根据业务情况响应设备强选事件。 235 break; 236 case audio.AudioStreamDeviceChangeReason.REASON_SESSION_ACTIVATED: 237 // 应用根据业务情况响应audio session激活时的输出设备信息。 238 break; 239 case audio.AudioStreamDeviceChangeReason.REASON_STREAM_PRIORITY_CHANGED: 240 // 应用根据业务情况响应其它更高优先级的音频流触发的设备变更事件。 241 break; 242 case audio.AudioStreamDeviceChangeReason.REASON_UNKNOWN: 243 // 应用根据业务情况响应未知原因事件。 244 break; 245 } 246}; 247 248audioSessionManager.on('currentOutputDeviceChanged', currentOutputDeviceChangedCallback); 249 250audioSessionManager.off('currentOutputDeviceChanged', currentOutputDeviceChangedCallback); 251 252// 取消该事件的所有监听。 253audioSessionManager.off('currentOutputDeviceChanged'); 254```