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  try {
109    let isHeadTrackingSupportedForDevice: boolean = audioSpatializationManager.isHeadTrackingSupportedForDevice(deviceDescriptor);
110    console.info(`AudioSpatializationManager isHeadTrackingSupportedForDevice: ${isHeadTrackingSupportedForDevice}`);
111  } catch (err) {
112    let error = err as BusinessError;
113    console.error(`ERROR: ${error}`);
114  }
115  ```
116
117## Enabling or Disabling Spatial Audio Rendering
118
119Call [setSpatializationEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#setspatializationenabled11) to enable or disable spatial audio rendering. Pass in **true** to enable spatial audio rendering, and pass in **false** to disable it.
120
121To 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).
122
123Before enabling spatial audio rendering, ensure that both the system and the current audio device support spatial audio rendering.
124
125  ```ts
126  import { BusinessError } from '@kit.BasicServicesKit';
127
128  let enable: boolean = true
129  audioSpatializationManager.setSpatializationEnabled(enable, (err: BusinessError) => {
130    if (err) {
131      console.error(`Result ERROR: ${err}`);
132    } else {
133      console.info(`setSpatializationEnabled success`);
134    }
135  });
136  ```
137
138## Checking the Status of Spatial Audio Rendering
139
140Call [isSpatializationEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#isspatializationenabled11) to check whether spatial audio rendering is enabled. 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 **true**. Note that spatial audio rendering takes effect only when the system and the current audio device support spatial audio rendering.
141
142  ```ts
143  import { BusinessError } from '@kit.BasicServicesKit';
144
145  try {
146    let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled();
147    console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`);
148  } catch (err) {
149    let error = err as BusinessError;
150    console.error(`ERROR: ${error}`);
151  }
152  ```
153
154## Subscribing to Spatial Audio Rendering Status Changes
155
156Call [on('spatializationEnabledChange')](../../reference/apis-audio-kit/js-apis-audio-sys.md#onspatializationenabledchange11) to subscribe to spatial audio rendering status changes. In the callback, the value **true** means that spatial audio rendering is enabled, and **false** means the opposite. The callback is triggered when spatial audio rendering is enabled or disabled through **setSpatializationEnabled()**.
157
158  ```ts
159  import { BusinessError } from '@kit.BasicServicesKit';
160
161  audioSpatializationManager.on('spatializationEnabledChange', (isSpatializationEnabled: boolean) => {
162    console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`);
163  });
164  ```
165
166## Unsubscribing from Spatial Audio Rendering Status Changes
167
168Call [off('spatializationEnabledChange')](../../reference/apis-audio-kit/js-apis-audio-sys.md#offspatializationenabledchange11) to unsubscribe from spatial audio rendering status changes.
169
170  ```ts
171  import { BusinessError } from '@kit.BasicServicesKit';
172
173  audioSpatializationManager.off('spatializationEnabledChange');
174  ```
175
176## Enabling or Disabling Head Tracking
177
178Call [setHeadTrackingEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#setheadtrackingenabled11) to enable or disable head tracking. Pass in **true** to enable head tracking, and pass in **false** to disable it.
179
180To 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).
181
182Before enabling head tracking, ensure that both the system and the current audio device support head tracking and when spatial audio rendering is enabled.
183
184  ```ts
185  import { BusinessError } from '@kit.BasicServicesKit';
186
187  let enable: boolean = true;
188  audioSpatializationManager.setHeadTrackingEnabled(enable, (err: BusinessError) => {
189    if (err) {
190      console.error(`Result ERROR: ${err}`);
191    } else {
192      console.info(`setHeadTrackingEnabled success`);
193    }
194  });
195  ```
196
197## Checking the Status of Head tracking
198
199Call [isHeadTrackingEnabled](../../reference/apis-audio-kit/js-apis-audio-sys.md#isheadtrackingenabled11) to check whether head tracking is enabled. 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 current audio device support head tracking and spatial audio rendering is enabled.
200
201  ```ts
202  import { BusinessError } from '@kit.BasicServicesKit';
203
204  try {
205    let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled();
206    console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
207  } catch (err) {
208    let error = err as BusinessError;
209    console.error(`ERROR: ${error}`);
210  }
211  ```
212
213## Subscribing to Head Tracking Status Changes
214
215Call [on('headTrackingEnabledChange')](../../reference/apis-audio-kit/js-apis-audio-sys.md#onheadtrackingenabledchange11) to subscribe to head tracking status changes. In the callback, the value **true** means that head tracking is enabled, and **false** means the opposite. The callback is triggered when head tracking is enabled or disabled through **setHeadTrackingEnabled()**.
216
217  ```ts
218  audioSpatializationManager.on('headTrackingEnabledChange', (isHeadTrackingEnabled: boolean) => {
219    console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
220  });
221  ```
222
223## Unsubscribing from Head Tracking Status Changes
224
225Call [off('headTrackingEnabledChange')](../../reference/apis-audio-kit/js-apis-audio-sys.md#offheadtrackingenabledchange11) to unsubscribe from head tracking status changes.
226
227  ```ts
228  audioSpatializationManager.off('headTrackingEnabledChange');
229  ```
230
231## Updating the State Information of a Spatial Device
232
233Call [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.
234
235To 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).
236
237For details about the state information, see [AudioSpatialDeviceState](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatialdevicestate11).
238
239  ```ts
240  import { audio } from '@kit.AudioKit';
241  import { BusinessError } from '@kit.BasicServicesKit';
242
243  let spatialDeviceState: audio.AudioSpatialDeviceState = {
244    address: "123",
245    isSpatializationSupported: true,
246    isHeadTrackingSupported: true,
247    spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE
248  }
249  try {
250    audioSpatializationManager.updateSpatialDeviceState(spatialDeviceState);
251    console.info(`AudioSpatializationManager updateSpatialDeviceState success`);
252  } catch (err) {
253    let error = err as BusinessError;
254    console.error(`ERROR: ${error}`);
255  }
256  ```
257
258## Setting the Spatial Audio Rendering Scene Type
259
260Call [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.
261
262To 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).
263
264For details about the spatial audio rendering scene type, see [AudioSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatializationscenetype12).
265
266  ```ts
267  import { audio } from '@kit.AudioKit';
268  import { BusinessError } from '@kit.BasicServicesKit';
269  try {
270    audioSpatializationManager.setSpatializationSceneType(audio.AudioSpatializationSceneType.DEFAULT);
271    console.info(`AudioSpatializationManager setSpatializationSceneType success`);
272  } catch (err) {
273    let error = err as BusinessError;
274    console.error(`ERROR: ${error}`);
275  }
276  ```
277
278## Querying the Spatial Audio Rendering Scene Type
279
280Call [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**.
281
282For details about the spatial audio rendering scene type, see [AudioSpatializationSceneType](../../reference/apis-audio-kit/js-apis-audio-sys.md#audiospatializationscenetype12).
283
284  ```ts
285  import { audio } from '@kit.AudioKit';
286  import { BusinessError } from '@kit.BasicServicesKit';
287  try {
288    let spatializationSceneType: audio.AudioSpatializationSceneType = audioSpatializationManager.getSpatializationSceneType();
289    console.info(`AudioSpatializationManager spatializationSceneType: ${spatializationSceneType}`);
290  } catch (err) {
291    let error = err as BusinessError;
292    console.error(`ERROR: ${error}`);
293  }
294  ```
295