Spatial Audio Management

Spatial audio is an advanced audio technology that transforms traditional stereo sound into a three-dimensional experience. It enhances monaural, stereo, and surround sound by adding a sense of height, delivering an all-encompassing audio experience. Spatial audio immerses users in an interactive, spatially aware soundscape, making them feel as though they are truly present in the audio environment.

Audio Vivid is the world’s first AI-driven audio codec standard. It is jointly formulated and released by the UHD World Association (UWA) and the Audio and Video Coding Standard Working Group (AVS). This audio format contains audio Pulse-Code Modulation (PCM) data and metadata, offering a more immersive listening experience over traditional stereo sources. Audio Vivid contains metadata information of audio content sources, which can reproduce the true auditory sensations of the physical and perceptual world.

Spatial audio supports playback of multi-channel, stereo, and Audio Vivid formats, and can render binaural spatial audio through headphones. When paired with Audio Vivid format sources, spatial audio rendering can treat vocals and various instruments in music as independent sound objects. It redefines the position, movement trajectory, and volume of these sound objects, creating a fully immersive experience where sound surrounds and envelops the listener from all directions, including above. This provides a more immersive spatial audio experience, akin to being in a cinema or concert hall. When a device supports spatial audio and the spatial audio feature is enabled, playing Audio Vivid format sources can enhance the audio experience. For details about how to play Audio Vivid sources, see Playing Audio Files in Audio Vivid Format.

How to Use

For audio playback applications, you can check whether the device supports spatial audio and has enabled spatial audio.

Creating a Spatial Audio Instance

Before using any APIs of AudioSpatializationManager, you must call getSpatializationManager to obtain an AudioSpatializationManager instance.

  import { audio } from '@kit.AudioKit';

  let audioManager = audio.getAudioManager();
  let audioSpatializationManager = audioManager.getSpatializationManager();

Checking Whether a Device Supports Spatial Audio Rendering

Use the spatializationSupported property in AudioDeviceDescriptor to check whether a specified device supports spatial audio rendering. You need to use other audio APIs to obtain AudioDeviceDescriptor of a connected device or the current audio device.

  import { audio } from '@kit.AudioKit';
  import { BusinessError } from '@kit.BasicServicesKit';

  const deviceDescriptors: audio.AudioDeviceDescriptors = audioRoutingManager.getDevicesSync(audio.DeviceFlag.OUTPUT_DEVICES_FLAG);
  for (let i = 0; i < deviceDescriptors.length; i++) {
    console.info('deviceDescriptor deviceRole: ${deviceDescriptors[i].deviceRole}');
    console.info('deviceDescriptor deviceType: ${deviceDescriptors[i].deviceType}');
    console.info('deviceDescriptor name: ${deviceDescriptors[i].name}');
    console.info('deviceDescriptor spatializationSupported: ${deviceDescriptors[i].spatializationSupported}');
  }

Checking the Status of Spatial Audio Rendering of the Current Device

Call isSpatializationEnabledForCurrentDevice to check whether spatial audio rendering is enabled for the current device. - If true is returned, spatial audio rendering is enabled for the current device. If false is returned, it is disabled. - Spatial audio rendering takes effect only when the current device support spatial audio rendering.

  import { audio } from '@kit.AudioKit';

  let isSpatializationEnabledForCurrentDevice: boolean = audioSpatializationManager.isSpatializationEnabledForCurrentDevice();
  console.info(`AudioSpatializationManager isSpatializationEnabledForCurrentDevice: ${isSpatializationEnabledForCurrentDevice}`);

Listening for Spatial Audio Rendering Status Changes of the Current Device

Call on(‘spatializationEnabledChangeForCurrentDevice’) to subscribe to the spatial audio rendering status change event of the current device.

If true is returned, spatial audio rendering is enabled. If false is returned, it is disabled.

import { audio } from '@kit.AudioKit';

audioSpatializationManager.on('spatializationEnabledChangeForCurrentDevice', (isSpatializationEnabledForCurrentDevice: boolean) => {
  console.info(`isSpatializationEnabledForCurrentDevice: ${isSpatializationEnabledForCurrentDevice}`);
});

Canceling Listening for Spatial Audio Rendering Status Changes of the Current Device

Call off(‘spatializationEnabledChangeForCurrentDevice’) to unsubscribe from the spatial audio rendering status change event of the current device.

import { audio } from '@kit.AudioKit';
audioSpatializationManager.off('spatializationEnabledChangeForCurrentDevice');

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Audio Kit

harmony 鸿蒙Developing Audio Call

harmony 鸿蒙Audio Call Overview

harmony 鸿蒙Audio Monitoring

harmony 鸿蒙Audio Effect Management

harmony 鸿蒙Global Audio Input Device Management

harmony 鸿蒙Introduction to Audio Kit

harmony 鸿蒙Audio Latency Management

harmony 鸿蒙Responding to Audio Output Device Changes

harmony 鸿蒙Global Audio Output Device Management