1# Spatial Audio Management (for System Applications Only)
2
3Spatial audio management includes querying, setting, and listening for spatial audio status and capabilities.
4
5Spatial audio management is available only for system applications. It enables a system application to obtain, set, and listen for spatial audio status (enabled/disabled status of spatial audio rendering and head tracking), obtain spatial audio capabilities (support for spatial audio rendering and head tracking), update the state information of spatial devices, and obtain and set the spatial audio rendering scene type.
6
7A system application that plays audio can query whether the system or a device supports spatial audio rendering or head tracking, whether spatial audio rendering or head tracking is enabled, and the spatial audio rendering scene type in use.
8
9A system application with spatial audio setting capabilities (for example, a setting screen where users can change the spatial audio status) can enable or disable spatial audio rendering or head tracking, set the spatial audio rendering scene type, and update the state information of a spatial device, in addition to the query operation.
10To use this feature, the application must request the **ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS** permission. For details, see [Requesting Permissions for system_basic Applications](../../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
11
12## Obtaining an AudioSpatializationManager Instance
13
14Before using **AudioSpatializationManager** APIs, you must use **getSpatializationManager()** to obtain an **AudioSpatializationManager** instance.
15
16  ```ts
17  import { audio } from '@kit.AudioKit';
18
19  let audioManager = audio.getAudioManager();
20  let audioSpatializationManager = audioManager.getSpatializationManager();
21  ```
22
23## Checking Whether the System Supports Spatial Audio Rendering
24
25Call [isSpatializationSupported](../../reference/apis-audio-kit/js-apis-audio-sys.md#isspatializationsupported11) to check whether the system supports spatial audio rendering.
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## Checking Whether a Device Supports Spatial Audio Rendering
40
41Call [isSpatializationSupportedForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#isspatializationsupportedfordevice11) to check whether a device (specified by **AudioDeviceDescriptor**) supports spatial audio rendering. You are advised to use other audio APIs to obtain **AudioDeviceDescriptor** of a connected device or the current audio device. For details, see [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## Checking Whether the System Supports Head Tracking
71
72Call [isHeadTrackingSupported](../../reference/apis-audio-kit/js-apis-audio-sys.md#isheadtrackingsupported11) to check whether the system supports head tracking.
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## Checking Whether a Device Supports Head Tracking
87
88Call [isHeadTrackingSupportedForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#isheadtrackingsupportedfordevice11) to check whether a device (specified by **AudioDeviceDescriptor**) supports head tracking. You are advised to use other audio APIs to obtain **AudioDeviceDescriptor** of a connected device or the current audio device. For details, see [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## Enabling or Disabling Spatial Audio Rendering for a Device
119
120Call [setSpatializationEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#setspatializationenabled12) to enable or disable spatial audio rendering for a device. This API contains two parameters:
121
122- **AudioDeviceDescriptor**: specifies an audio device. You are advised to use other audio APIs to obtain **AudioDeviceDescriptor** of a connected device or the current audio device. For details, see [AudioDeviceDescriptor](../../reference/apis-audio-kit/js-apis-audio.md#audiodevicedescriptor).
123- **enabled**: specifies the status of spatial audio rendering of the specified device. The value **true** means to enable spatial audio rendering, and **false** means to disable it.
124
125To use this feature, the application must request the **ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS** permission. For details, see [Requesting Permissions for system_basic Applications](../../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
126
127Before enabling spatial audio rendering, ensure that both the system and the specified device support spatial audio rendering.
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## Checking the Status of Spatial Audio Rendering of a Device
157
158Call [isSpatializationEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#isspatializationenabled12) to check whether spatial audio rendering is enabled for a device (specified by **AudioDeviceDescriptor**). You are advised to use other audio APIs to obtain **AudioDeviceDescriptor** of a connected device or the current audio device. For details, see [AudioDeviceDescriptor](../../reference/apis-audio-kit/js-apis-audio.md#audiodevicedescriptor). If **true** is returned, spatial audio rendering is enabled. If **false** is returned, it is disabled. This API returns the value passed in **setSpatializationEnabled**. The default value is **false**. Note that spatial audio rendering takes effect only when the system and the specified device support spatial audio rendering.
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## Subscribing to Spatial Audio Rendering Status Changes
189
190Call [on('spatializationEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#onspatializationenabledchangeforanydevice12) to subscribe to spatial audio rendering status changes. In the callback, the **AudioSpatialEnabledStateForDevice** parameter contains **deviceDescriptor** and **enabled**. **deviceDescriptor** specifies the device descriptor, and **enabled** specifies the enabled status, where **true** means that spatial audio rendering is enabled and **false** means the opposite. For details, see [AudioSpatialEnabledStateForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatialenabledstatefordevice12). The callback is triggered when spatial audio rendering is enabled or disabled for any device through **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## Unsubscribing from Spatial Audio Rendering Status Changes
202
203Call [off('spatializationEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#offspatializationenabledchangeforanydevice12) to unsubscribe from spatial audio rendering status changes.
204
205  ```ts
206  import { audio } from '@kit.AudioKit';
207  audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice');
208  ```
209
210## Enabling or Disabling Head Tracking for a Device
211
212Call [setHeadTrackingEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#setheadtrackingenabled12) to enable or disable head tracking for a device. This API contains two parameters:
213
214- **AudioDeviceDescriptor**: specifies an audio device. You are advised to use other audio APIs to obtain **AudioDeviceDescriptor** of a connected device or the current audio device. For details, see [AudioDeviceDescriptor](../../reference/apis-audio-kit/js-apis-audio.md#audiodevicedescriptor).
215- **enabled**: specifies the status of head tracking of the specified device. The value **true** means to enable head tracking, and **false** means to disable it.
216
217To use this feature, the application must request the **ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS** permission. For details, see [Requesting Permissions for system_basic Applications](../../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
218
219Before enabling head tracking, ensure that both the system and the specified device support head tracking and when spatial audio rendering is enabled.
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## Checking the Status of Head Tracking of a Device
249
250Call [isHeadTrackingEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#isheadtrackingenabled12) to check whether head tracking is enabled for a device (specified by **AudioDeviceDescriptor**). You are advised to use other audio APIs to obtain **AudioDeviceDescriptor** of a connected device or the current audio device. For details, see [AudioDeviceDescriptor](../../reference/apis-audio-kit/js-apis-audio.md#audiodevicedescriptor). If **true** is returned, head tracking is enabled. If **false** is returned, it is disabled. This API returns the value passed in **setHeadTrackingEnabled**. The default value is **false**. Note that head tracking takes effect only when the system and the specified device support head tracking and spatial audio rendering is enabled.
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## Subscribing to Head Tracking Status Changes
281
282Call [on('headTrackingEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#onheadtrackingenabledchangeforanydevice12) to subscribe to head tracking status changes. In the callback, the **AudioSpatialEnabledStateForDevice** parameter contains **deviceDescriptor** and **enabled**. **deviceDescriptor** specifies the device descriptor, and **enabled** specifies the enabled status, where **true** means that head tracking is enabled and **false** means the opposite. For details, see [AudioSpatialEnabledStateForDevice](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatialenabledstatefordevice12). The callback is triggered when head tracking is enabled or disabled for any device through **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## Unsubscribing from Head Tracking Status Changes
294
295Call [off('headTrackingEnabledChangeForAnyDevice')](../../reference/apis-audio-kit/js-apis-audio-sys.md#offheadtrackingenabledchangeforanydevice12) to unsubscribe from head tracking status changes.
296
297  ```ts
298  import { audio } from '@kit.AudioKit';
299  audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice');
300  ```
301
302## Updating the State Information of a Spatial Device
303
304Call [updateSpatialDeviceState](../../reference/apis-audio-kit/js-apis-audio-sys.md#updatespatialdevicestate11) to update the state information of a spatial device. The state information includes the device address, support for spatial audio rendering and head tracking, and device form.
305
306To use this feature, the application must request the **ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS** permission. For details, see [Requesting Permissions for system_basic Applications](../../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
307
308For details about the state information, see [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## Setting the Spatial Audio Rendering Scene Type
331
332Call [setSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#setspatializationscenetype12) to set the spatial audio rendering scene type, which can be **DEFAULT** (default value), **MUSIC**, **MOVIE**, or **AUDIOBOOK**. The spatial audio rendering scene type takes effect only when spatial audio rendering is enabled.
333
334To use this feature, the application must request the **ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS** permission. For details, see [Requesting Permissions for system_basic Applications](../../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
335
336For details about the spatial audio rendering scene type, see [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## Querying the Spatial Audio Rendering Scene Type
352
353Call [getSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#getspatializationscenetype12) to obtain the spatial audio rendering scene type in use. This API returns the value passed in **setSpatializationSceneType()**. The default value is **DEFAULT**.
354
355For details about the spatial audio rendering scene type, see [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  ```
369