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