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空间音频管理主要包含空间音频相关状态和能力的查询、设置与监听。 10 11空间音频管理仅开放给系统级应用，主要包括空间音频相关状态（空间音频渲染的开启与关闭、头动跟踪的开启与关闭）的查询、设置与监听，空间音频相关能力（空间音频渲染能力、头动跟踪能力）的查询，空间化设备状态的更新，以及空间音频渲染场景类型的查询与设置。 12 13对于播放音频类的系统级应用，开发者可以查询空间音频渲染与头动跟踪的开关状态，系统/指定设备是否支持空间音频渲染与头动跟踪能力，以及当前使用的空间音频渲染场景类型。 14 15对于空间音频控制类的系统级应用（比如空间音频UX等），开发者在查询上述状态和能力之外，还可以对空间音频渲染开关、头动跟踪开关以及空间音频渲染场景类型进行设置，以及更新空间化设备的状态，指明特定空间化设备是否支持空间音频渲染和头动跟踪能力。 16在使用此功能前，应用需要先申请权限`ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS`，申请方式请参考：[申请应用权限](../../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)。 17 18## 获取空间音频管理接口 19 20创建AudioSpatializationManager实例。在使用AudioSpatializationManager的API前，需要使用getSpatializationManager()创建一个AudioSpatializationManager实例。 21 22 ```ts 23 import { audio } from '@kit.AudioKit'; 24 25 let audioManager = audio.getAudioManager(); 26 let audioSpatializationManager = audioManager.getSpatializationManager(); 27 ``` 28 29## 查询系统是否支持空间音频渲染能力 30 31系统应用开发者可以通过[isSpatializationSupported](../../reference/apis-audio-kit/js-apis-audio-sys.md#isspatializationsupported11)接口查询当前系统是否具有空间音频渲染的能力。 32 33 ```ts 34 import { BusinessError } from '@kit.BasicServicesKit'; 35 36 try { 37 let isSpatializationSupported: boolean = audioSpatializationManager.isSpatializationSupported(); 38 console.info(`AudioSpatializationManager isSpatializationSupported: ${isSpatializationSupported}`); 39 } catch (err) { 40 let error = err as BusinessError; 41 console.error(`ERROR: ${error}`); 42 } 43 ``` 44 45## 查询指定设备是否支持空间音频渲染能力 46 47系统应用开发者可以通过[isSpatializationSupportedForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#isspatializationsupportedfordevice11)接口查询指定设备是否具有空间音频渲染的能力，开发者需要使用AudioDeviceDescriptor作为入参来指定设备，建议通过音频框架中其他接口来获取当前已连接设备或当前发声设备的AudioDeviceDescriptor。AudioDeviceDescriptor的具体信息可以参考[AudioDeviceDescriptor](../../reference/apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)。 48 49 ```ts 50 import { audio } from '@kit.AudioKit'; 51 import { BusinessError } from '@kit.BasicServicesKit'; 52 53 let deviceDescriptor: audio.AudioDeviceDescriptor = { 54 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 55 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 56 id : 1, 57 name : "", 58 address : "123", 59 sampleRates : [44100], 60 channelCounts : [2], 61 channelMasks : [0], 62 networkId : audio.LOCAL_NETWORK_ID, 63 interruptGroupId : 1, 64 volumeGroupId : 1, 65 displayName : "" 66 }; 67 try { 68 let isSpatializationSupportedForDevice: boolean = audioSpatializationManager.isSpatializationSupportedForDevice(deviceDescriptor); 69 console.info(`AudioSpatializationManager isSpatializationSupportedForDevice: ${isSpatializationSupportedForDevice}`); 70 } catch (err) { 71 let error = err as BusinessError; 72 console.error(`ERROR: ${error}`); 73 } 74 ``` 75 76## 查询系统是否支持头动跟踪能力 77 78系统应用开发者可以通过[isHeadTrackingSupported](../../reference/apis-audio-kit/js-apis-audio-sys.md#isheadtrackingsupported11)接口查询当前系统是否具有头动跟踪的能力。 79 80 ```ts 81 import { BusinessError } from '@kit.BasicServicesKit'; 82 83 try { 84 let isHeadTrackingSupported: boolean = audioSpatializationManager.isHeadTrackingSupported(); 85 console.info(`AudioSpatializationManager isHeadTrackingSupported: ${isHeadTrackingSupported}`); 86 } catch (err) { 87 let error = err as BusinessError; 88 console.error(`ERROR: ${error}`); 89 } 90 ``` 91 92## 查询指定设备是否支持头动跟踪能力 93 94系统应用开发者可以通过[isHeadTrackingSupportedForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#isheadtrackingsupportedfordevice11)接口查询指定设备是否具有头动跟踪的能力，开发者需要使用AudioDeviceDescriptor作为入参来指定设备，建议通过音频框架中其他接口来获取当前已连接设备或当前发声设备的AudioDeviceDescriptor。AudioDeviceDescriptor的具体信息可以参考[AudioDeviceDescriptor](../../reference/apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)。 95 96 ```ts 97 import { audio } from '@kit.AudioKit'; 98 import { BusinessError } from '@kit.BasicServicesKit'; 99 100 let deviceDescriptor: audio.AudioDeviceDescriptor = { 101 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 102 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 103 id : 1, 104 name : "", 105 address : "123", 106 sampleRates : [44100], 107 channelCounts : [2], 108 channelMasks : [0], 109 networkId : audio.LOCAL_NETWORK_ID, 110 interruptGroupId : 1, 111 volumeGroupId : 1, 112 displayName : "" 113 }; 114 115 try { 116 let isHeadTrackingSupportedForDevice: boolean = audioSpatializationManager.isHeadTrackingSupportedForDevice(deviceDescriptor); 117 console.info(`AudioSpatializationManager isHeadTrackingSupportedForDevice: ${isHeadTrackingSupportedForDevice}`); 118 } catch (err) { 119 let error = err as BusinessError; 120 console.error(`ERROR: ${error}`); 121 } 122 ``` 123 124## 开启/关闭指定设备的空间音频渲染效果 125 126系统应用开发者可以通过[setSpatializationEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#setspatializationenabled12)接口开启/关闭指定设备的空间音频渲染效果，该接口需要传递两个参数：AudioDeviceDescriptor和enabled。 127 128AudioDeviceDescriptor：用于指定音频设备。建议通过音频框架中其他接口来获取当前已连接设备或当前发声设备的AudioDeviceDescriptor。AudioDeviceDescriptor的具体信息可以参考[AudioDeviceDescriptor](../../reference/apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)。 129enabled：布尔值类型，用于控制指定设备的空间音频渲染开关。入参为true时为开启空间音频渲染，入参为false时为关闭空间音频渲染。 130 131在使用此功能前，应用需要先申请权限`ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS`，申请方式请参考：[申请应用权限](../../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)。 132 133在开启空间音频渲染时，需要先确保系统和指定设备都具有空间音频渲染的能力。 134 135 ```ts 136 import { audio } from '@kit.AudioKit'; 137 import { BusinessError } from '@kit.BasicServicesKit'; 138 139 let deviceDescriptor: audio.AudioDeviceDescriptor = { 140 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 141 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 142 id : 1, 143 name : "", 144 address : "123", 145 sampleRates : [44100], 146 channelCounts : [2], 147 channelMasks : [0], 148 networkId : audio.LOCAL_NETWORK_ID, 149 interruptGroupId : 1, 150 volumeGroupId : 1, 151 displayName : "" 152 }; 153 let enabled: boolean = true; 154 155 audioSpatializationManager.setSpatializationEnabled(deviceDescriptor, enabled).then(() => { 156 console.info(`setSpatializationEnabled success`); 157 }).catch((err: BusinessError) => { 158 console.error(`Result ERROR: ${err}`); 159 }); 160 ``` 161 162## 查询指定设备的空间音频渲染效果开关状态 163 164系统应用开发者可以通过[isSpatializationEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#isspatializationenabled12)接口查询指定设备的空间音频渲染效果开关状态，开发者需要使用AudioDeviceDescriptor作为入参来指定设备，建议通过音频框架中其他接口来获取当前已连接设备或当前发声设备的AudioDeviceDescriptor。AudioDeviceDescriptor的具体信息可以参考[AudioDeviceDescriptor](../../reference/apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)。该接口返回为true表示空间音频渲染开启，false表示空间音频渲染关闭。返回值为setSpatializationEnabled接口中成功设置的指定设备空间音频渲染开关状态，默认为关闭。该状态仅为开关状态，实际是否生效还需依赖系统和指定设备是否支持空间音频渲染。 165 166 ```ts 167 import { audio } from '@kit.AudioKit'; 168 import { BusinessError } from '@kit.BasicServicesKit'; 169 170 let deviceDescriptor: audio.AudioDeviceDescriptor = { 171 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 172 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 173 id : 1, 174 name : "", 175 address : "123", 176 sampleRates : [44100], 177 channelCounts : [2], 178 channelMasks : [0], 179 networkId : audio.LOCAL_NETWORK_ID, 180 interruptGroupId : 1, 181 volumeGroupId : 1, 182 displayName : "" 183 } 184 185 try { 186 let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(deviceDescriptor); 187 console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`); 188 } catch (err) { 189 let error = err as BusinessError; 190 console.error(`ERROR: ${error}`); 191 } 192 ``` 193 194## 订阅空间音频渲染效果的开关状态变化事件 195 196系统应用开发者可以通过[on('spatializationEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#onspatializationenabledchangeforanydevice12)接口订阅空间音频渲染效果的开关状态变化事件，回调包含AudioSpatialEnabledStateForDevice参数，AudioSpatialEnabledStateForDevice包含deviceDescriptor和enabled属性，其中deviceDescriptor为被改变设备的描述信息，enabled为true表示空间音频渲染被开启，false表示空间音频渲染被关闭，具体信息可以参考[AudioSpatialEnabledStateForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatialenabledstatefordevice12)。当开发者通过setSpatializationEnabled接口成功地改变了任一设备的空间音频渲染开关状态时，回调将被触发。 197 198 ```ts 199 import { audio } from '@kit.AudioKit'; 200 201 audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 202 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 203 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 204 }); 205 ``` 206 207## 取消订阅空间音频渲染效果的开关状态变化事件 208 209系统应用开发者可以通过[off('spatializationEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#offspatializationenabledchangeforanydevice12)接口取消订阅空间音频渲染效果的开关状态变化事件。 210 211 ```ts 212 import { audio } from '@kit.AudioKit'; 213 audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice'); 214 ``` 215 216## 开启/关闭指定设备的头动跟踪效果 217 218系统应用开发者可以通过[setHeadTrackingEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#setheadtrackingenabled12)接口开启/关闭指定设备的空间音频渲染效果，该接口需要传递两个参数：AudioDeviceDescriptor和enabled。 219 220AudioDeviceDescriptor：用于指定音频设备。建议通过音频框架中其他接口来获取当前已连接设备或当前发声设备的AudioDeviceDescriptor。AudioDeviceDescriptor的具体信息可以参考[AudioDeviceDescriptor](../../reference/apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)。 221enabled：布尔值类型，用于控制指定设备的头动跟踪开关。入参为true时为开启头动跟踪，入参为false时为关闭头动跟踪。 222 223在使用此功能前，应用需要先申请权限`ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS`，申请方式请参考：[申请应用权限](../../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)。 224 225在开启头动跟踪时，需要先确保系统和指定设备都具有头动跟踪的能力，同时头动跟踪效果的生效依赖于空间音频渲染开关打开。 226 227 ```ts 228 import { audio } from '@kit.AudioKit'; 229 import { BusinessError } from '@kit.BasicServicesKit'; 230 231 let deviceDescriptor: audio.AudioDeviceDescriptor = { 232 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 233 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 234 id : 1, 235 name : "", 236 address : "123", 237 sampleRates : [44100], 238 channelCounts : [2], 239 channelMasks : [0], 240 networkId : audio.LOCAL_NETWORK_ID, 241 interruptGroupId : 1, 242 volumeGroupId : 1, 243 displayName : "" 244 }; 245 let enable: boolean = true; 246 247 audioSpatializationManager.setHeadTrackingEnabled(deviceDescriptor, enable).then(() => { 248 console.info(`setHeadTrackingEnabled success`); 249 }).catch((err: BusinessError) => { 250 console.error(`Result ERROR: ${err}`); 251 }); 252 ``` 253 254## 查询指定设备的头动跟踪效果开关状态 255 256系统应用开发者可以通过[isHeadTrackingEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#isheadtrackingenabled12)接口查询指定设备的头动跟踪效果开关状态，开发者需要使用AudioDeviceDescriptor作为入参来指定设备，建议通过音频框架中其他接口来获取当前已连接设备或当前发声设备的AudioDeviceDescriptor。AudioDeviceDescriptor的具体信息可以参考[AudioDeviceDescriptor](../../reference/apis-audio-kit/arkts-apis-audio-i.md#audiodevicedescriptor)。该接口返回为true表示头动跟踪开启，false表示头动跟踪关闭。返回值为setHeadTrackingEnabled接口中成功设置的指定设备头动跟踪开关状态，默认为关闭。该状态仅为开关状态，实际是否生效还需依赖系统和指定设备是否支持头动跟踪，以及指定设备空间音频渲染开关是否打开。 257 258 ```ts 259 import { audio } from '@kit.AudioKit'; 260 import { BusinessError } from '@kit.BasicServicesKit'; 261 262 let deviceDescriptor: audio.AudioDeviceDescriptor = { 263 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 264 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 265 id : 1, 266 name : "", 267 address : "123", 268 sampleRates : [44100], 269 channelCounts : [2], 270 channelMasks : [0], 271 networkId : audio.LOCAL_NETWORK_ID, 272 interruptGroupId : 1, 273 volumeGroupId : 1, 274 displayName : "" 275 }; 276 277 try { 278 let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(deviceDescriptor); 279 console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 280 } catch (err) { 281 let error = err as BusinessError; 282 console.error(`ERROR: ${error}`); 283 } 284 ``` 285 286## 订阅头动跟踪效果的开关状态变化事件 287 288系统应用开发者可以通过[on('headTrackingEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#onheadtrackingenabledchangeforanydevice12)接口订阅头动跟踪效果的开关状态变化事件，回调包含AudioSpatialEnabledStateForDevice参数，AudioSpatialEnabledStateForDevice包含deviceDescriptor和enabled属性，其中deviceDescriptor为被改变设备的描述信息，enabled为true表示头动跟踪被开启，false表示头动跟踪被关闭。具体信息可以参考[AudioSpatialEnabledStateForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatialenabledstatefordevice12)。当开发者通过setHeadTrackingEnabled接口成功地改变了任一设备的头动跟踪开关状态时，回调将被触发。 289 290 ```ts 291 import { audio } from '@kit.AudioKit'; 292 293 audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 294 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 295 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 296 }); 297 ``` 298 299## 取消订阅头动跟踪效果的开关状态变化事件 300 301系统应用开发者可以通过[off('headTrackingEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#offheadtrackingenabledchangeforanydevice12)接口取消订阅头动跟踪效果的开关状态变化事件。 302 303 ```ts 304 import { audio } from '@kit.AudioKit'; 305 audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice'); 306 ``` 307 308## 更新空间化设备状态 309 310系统应用开发者可以通过[updateSpatialDeviceState](../../reference/apis-audio-kit/js-apis-audio-sys.md#updatespatialdevicestate11)接口更新空间化设备状态，空间化设备状态包含设备的地址、是否具有空间音频渲染的能力、是否具有头动跟踪的能力和设备的形态类型。 311 312在使用此功能前，应用需要先申请权限`ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS`，申请方式请参考：[申请应用权限](../../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)。 313 314空间化设备状态AudioSpatialDeviceState的具体信息可以参考[AudioSpatialDeviceState](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatialdevicestate11)。 315 316 ```ts 317 import { audio } from '@kit.AudioKit'; 318 import { BusinessError } from '@kit.BasicServicesKit'; 319 320 let spatialDeviceState: audio.AudioSpatialDeviceState = { 321 address: "123", 322 isSpatializationSupported: true, 323 isHeadTrackingSupported: true, 324 spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE 325 }; 326 327 try { 328 audioSpatializationManager.updateSpatialDeviceState(spatialDeviceState); 329 console.info(`AudioSpatializationManager updateSpatialDeviceState success`); 330 } catch (err) { 331 let error = err as BusinessError; 332 console.error(`ERROR: ${error}`); 333 } 334 ``` 335 336## 设置空间音频渲染场景类型 337 338系统应用开发者可以通过[setSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#setspatializationscenetype12)接口设置空间音频渲染场景类型，可以选择默认场景、音乐场景、电影场景或有声读物场景，默认为默认场景。空间音频渲染场景类型的生效依赖空间音频渲染开关的打开。 339 340在使用此功能前，应用需要先申请权限`ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS`，申请方式请参考：[申请应用权限](../../security/AccessToken/determine-application-mode.md#system_basic等级应用申请权限的方式)。 341 342空间音频渲染场景类型AudioSpatializationSceneType的具体信息可以参考[AudioSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatializationscenetype12)。 343 344 ```ts 345 import { audio } from '@kit.AudioKit'; 346 import { BusinessError } from '@kit.BasicServicesKit'; 347 348 try { 349 audioSpatializationManager.setSpatializationSceneType(audio.AudioSpatializationSceneType.DEFAULT); 350 console.info(`AudioSpatializationManager setSpatializationSceneType success`); 351 } catch (err) { 352 let error = err as BusinessError; 353 console.error(`ERROR: ${error}`); 354 } 355 ``` 356 357## 查询空间音频渲染场景类型 358 359系统应用开发者可以通过[getSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#getspatializationscenetype12)接口查询当前空间音频渲染场景类型。该接口将返回setSpatializationSceneType()接口中成功设置的值，默认为默认场景。 360 361空间音频渲染场景类型AudioSpatializationSceneType的具体信息可以参考[AudioSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatializationscenetype12)。 362 363 ```ts 364 import { audio } from '@kit.AudioKit'; 365 import { BusinessError } from '@kit.BasicServicesKit'; 366 367 try { 368 let spatializationSceneType: audio.AudioSpatializationSceneType = audioSpatializationManager.getSpatializationSceneType(); 369 console.info(`AudioSpatializationManager spatializationSceneType: ${spatializationSceneType}`); 370 } catch (err) { 371 let error = err as BusinessError; 372 console.error(`ERROR: ${error}`); 373 } 374 ```