@ohos.multimedia.audio (Audio Management) (System API)

The Audio module provides basic audio management capabilities, including audio volume and audio device management, and audio data collection and rendering.

This module provides the following common audio-related functions:

• AudioManager: audio management.
• TonePlayer: tone player, used to manage and play Dual Tone Multi Frequency (DTMF) tones, such as dial tones and ringback tones.

NOTE

• The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.multimedia.audio (Audio Management).

Modules to Import

import audio from '@ohos.multimedia.audio';

Constants

audio.createTonePlayer⁹⁺

createTonePlayer(options: AudioRendererInfo, callback: AsyncCallback<TonePlayer>): void

Creates a TonePlayer instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Audio.Tone

System API: This is a system API.

Parameters

Example

import audio from '@ohos.multimedia.audio';

let audioRendererInfo: audio.AudioRendererInfo = {
  usage : audio.StreamUsage.STREAM_USAGE_DTMF,
  rendererFlags : 0
}
let tonePlayer: audio.TonePlayer;

audio.createTonePlayer(audioRendererInfo, (err, data) => {
  console.info(`callback call createTonePlayer: audioRendererInfo: ${audioRendererInfo}`);
  if (err) {
    console.error(`callback call createTonePlayer return error: ${err.message}`);
  } else {
    console.info(`callback call createTonePlayer return data: ${data}`);
    tonePlayer = data;
  }
});

audio.createTonePlayer⁹⁺

createTonePlayer(options: AudioRendererInfo): Promise<TonePlayer>

Creates a TonePlayer instance. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Audio.Tone

System API: This is a system API.

Parameters

Return value

Example

import audio from '@ohos.multimedia.audio';

let tonePlayer: audio.TonePlayer;
async function createTonePlayerBefore(){
  let audioRendererInfo: audio.AudioRendererInfo = {
    usage : audio.StreamUsage.STREAM_USAGE_DTMF,
    rendererFlags : 0
  }
  tonePlayer = await audio.createTonePlayer(audioRendererInfo);
}

AudioVolumeType

Enumerates the audio stream types.

System capability: SystemCapability.Multimedia.Audio.Volume

InterruptRequestResultType⁹⁺

Enumerates the result types of audio interruption requests.

System capability: SystemCapability.Multimedia.Audio.Interrupt

System API: This is a system API.

DeviceFlag

Enumerates the audio device flags.

System capability: SystemCapability.Multimedia.Audio.Device

DeviceUsage¹¹⁺

Enumerates the audio device flags.

System capability: SystemCapability.Multimedia.Audio.Device

System API: This is a system API.

StreamUsage

Enumerates the audio stream usage.

System capability: SystemCapability.Multimedia.Audio.Core

InterruptRequestType⁹⁺

Enumerates the audio interruption request types.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Interrupt

InterruptResult⁹⁺

Describes the audio interruption result.

System capability: SystemCapability.Multimedia.Audio.Interrupt

System API: This is a system API.

VolumeEvent⁹⁺

Describes the event received by the application when the volume is changed.

System capability: SystemCapability.Multimedia.Audio.Volume

ConnectType⁹⁺

Enumerates the types of connected devices.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

VolumeGroupInfos⁹⁺

Describes the volume group information. The value is an array of VolumeGroupInfo and is read-only.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

VolumeGroupInfo⁹⁺

Describes the volume group information.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

SourceType⁸⁺

Enumerates the audio source types.

AudioScene⁸⁺

Enumerates the audio scenes.

System capability: SystemCapability.Multimedia.Audio.Communication

VolumeAdjustType¹⁰⁺

Enumerates the volume adjustment types.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

AudioManager

Implements audio volume and audio device management. Before calling any API in AudioManager, you must use getAudioManager to create an AudioManager instance.

setExtraParameters¹¹⁺

setExtraParameters(mainKey: string, kvpairs: Record<string, string>): Promise<void>

Sets extended audio parameters. This API uses a promise to return the result.

Required permissions: ohos.permission.MODIFY_AUDIO_SETTINGS

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Core

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

let kvpairs = {} as Record<string, string>;
kvpairs = {
  'key_example': 'value_example'
}
audioManager.setExtraParameters('key_example', kvpairs).then(() => {
  console.info('Promise returned to indicate a successful setting of the extra parameters.');
}).catch ((err: BusinessError) => {
    console.error(`Failed to set the audio extra parameters ${err}`);
});

getExtraParameters¹¹⁺

getExtraParameters(mainKey: string, subKeys?: Array<string>): Promise<Record<string, string>>

Obtains the value of an audio parameter. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Core

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

let subKeys: Array<String> = ['key_example'];
audioManager.getExtraParameters('key_example', subKeys).then((value: Record<string, string>) => {
  console.info(`Promise returned to indicate that the value of the audio extra parameters is obtained ${value}.`);
}).catch ((err: BusinessError) => {
    console.error(`Failed to get the audio extra parameters ${err}`);
});

setAudioScene⁸⁺

setAudioScene(scene: AudioScene, callback: AsyncCallback<void>): void

Sets an audio scene. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Communication

Parameters

Example

import { BusinessError } from '@ohos.base';

audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set the audio scene mode. ${err}`);
    return;
  }
  console.info('Callback invoked to indicate a successful setting of the audio scene mode.');
});

setAudioScene⁸⁺

setAudioScene(scene: AudioScene): Promise<void>

Sets an audio scene. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Communication

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';

audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL).then(() => {
  console.info('Promise returned to indicate a successful setting of the audio scene mode.');
}).catch ((err: BusinessError) => {
  console.error(`Failed to set the audio scene mode ${err}`);
});

getSpatializationManager¹¹⁺

getSpatializationManager(): AudioSpatializationManager

Obtains an AudioSpatializationManager instance.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
let audioSpatializationManager: audio.AudioSpatializationManager = audioManager.getSpatializationManager();

on('volumeChange')^(deprecated)

on(type: 'volumeChange', callback: Callback<VolumeEvent>): void

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use on('volumeChange') in AudioVolumeManager.

Subscribes to system volume change events. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Currently, when multiple AudioManager instances are used in a single process, only the subscription of the last instance takes effect, and the subscription of other instances is overwritten (even if the last instance does not initiate a subscription). Therefore, you are advised to use a single AudioManager instance.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Example

audioManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => {
  console.info(`VolumeType of stream: ${volumeEvent.volumeType} `);
  console.info(`Volume level: ${volumeEvent.volume} `);
  console.info(`Whether to updateUI: ${volumeEvent.updateUi} `);
});

on('ringerModeChange')^(deprecated)

on(type: 'ringerModeChange', callback: Callback<AudioRingMode>): void

Subscribes to ringer mode change events. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use on('ringerModeChange') in AudioVolumeGroupManager.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Communication

Parameters

Example

audioManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => {
  console.info(`Updated ringermode: ${ringerMode}`);
});

AudioVolumeManager⁹⁺

Implements audio volume management. Before calling an API in AudioVolumeManager, you must use getVolumeManager to obtain an AudioVolumeManager instance.

getVolumeGroupInfos⁹⁺

getVolumeGroupInfos(networkId: string, callback: AsyncCallback<VolumeGroupInfos>): void

Obtains the volume groups. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Example

import { BusinessError } from '@ohos.base';

audioVolumeManager.getVolumeGroupInfos(audio.LOCAL_NETWORK_ID, (err: BusinessError, value: audio.VolumeGroupInfos) => {
  if (err) {
    console.error(`Failed to obtain the volume group infos list. ${err}`);
    return;
  }
  console.info('Callback invoked to indicate that the volume group infos list is obtained.');
});

getVolumeGroupInfos⁹⁺

getVolumeGroupInfos(networkId: string): Promise<VolumeGroupInfos>

Obtains the volume groups. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Example

async function getVolumeGroupInfos(){
  let volumegroupinfos: audio.VolumeGroupInfos = await audio.getAudioManager().getVolumeManager().getVolumeGroupInfos(audio.LOCAL_NETWORK_ID);
  console.info('Promise returned to indicate that the volumeGroup list is obtained.'+JSON.stringify(volumegroupinfos))
}

getVolumeGroupInfosSync¹⁰⁺

getVolumeGroupInfosSync(networkId: string): VolumeGroupInfos

Obtains the volume groups. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  let volumegroupinfos: audio.VolumeGroupInfos = audioVolumeManager.getVolumeGroupInfosSync(audio.LOCAL_NETWORK_ID);
  console.info(`Indicate that the volumeGroup list is obtained. ${JSON.stringify(volumegroupinfos)}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`Failed to obtain the volumeGroup list ${error}`);
}

AudioVolumeGroupManager⁹⁺

Manages the volume of an audio group. Before calling any API in AudioVolumeGroupManager, you must use getVolumeGroupManager to obtain an AudioVolumeGroupManager instance.

setVolume⁹⁺

setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void

Sets the volume for a stream. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Example

import { BusinessError } from '@ohos.base';

audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set the volume. ${err}`);
    return;
  }
  console.info('Callback invoked to indicate a successful volume setting.');
});

setVolume⁹⁺

setVolume(volumeType: AudioVolumeType, volume: number): Promise<void>

Sets the volume for a stream. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Example

audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => {
  console.info('Promise returned to indicate a successful volume setting.');
});

mute⁹⁺

mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void

Mutes or unmutes a stream. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Example

import { BusinessError } from '@ohos.base';

audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to mute the stream. ${err}`);
    return;
  }
  console.info('Callback invoked to indicate that the stream is muted.');
});

mute⁹⁺

mute(volumeType: AudioVolumeType, mute: boolean): Promise<void>

Mutes or unmutes a stream. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Example

audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => {
  console.info('Promise returned to indicate that the stream is muted.');
});

setRingerMode⁹⁺

setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void

Sets the ringer mode. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Example

import { BusinessError } from '@ohos.base';

audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set the ringer mode. ${err}`);
    return;
  }
  console.info('Callback invoked to indicate a successful setting of the ringer mode.');
});

setRingerMode⁹⁺

setRingerMode(mode: AudioRingMode): Promise<void>

Sets the ringer mode. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Example

audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => {
  console.info('Promise returned to indicate a successful setting of the ringer mode.');
});

setMicMute¹¹⁺

setMicMute(mute: boolean): Promise<void>

Mutes or unmutes the microphone. This API uses a promise to return the result.

Required permissions: ohos.permission.MANAGE_AUDIO_CONFIG

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

audioVolumeGroupManager.setMicMute(true).then(() => {
  console.info('Promise returned to indicate that the mic is muted.');
});

adjustVolumeByStep¹⁰⁺

adjustVolumeByStep(adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void

Adjusts the volume of the stream with the highest priority by step. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to adjust the volume by step. ${err}`);
    return;
  } else {
    console.info('Success to adjust the volume by step.');
  }
});

adjustVolumeByStep¹⁰⁺

adjustVolumeByStep(adjustType: VolumeAdjustType): Promise<void>

Adjusts the volume of the stream with the highest priority by step. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP).then(() => {
  console.info('Success to adjust the volume by step.');
}).catch((error: BusinessError) => {
  console.error('Fail to adjust the volume by step.');
});

adjustSystemVolumeByStep¹⁰⁺

adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void

Adjusts the volume of a stream by step. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to adjust the system volume by step ${err}`);
  } else {
    console.info('Success to adjust the system volume by step.');
  }
});

adjustSystemVolumeByStep¹⁰⁺

adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType): Promise<void>

Adjusts the volume of a stream by step. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

This permission is required only for muting or unmuting the ringer when volumeType is set to AudioVolumeType.RINGTONE.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Volume

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP).then(() => {
  console.info('Success to adjust the system volume by step.');
}).catch((error: BusinessError) => {
  console.error('Fail to adjust the system volume by step.');
});

AudioRoutingManager⁹⁺

Implements audio routing management. Before calling any API in AudioRoutingManager, you must use getRoutingManager to obtain an AudioRoutingManager instance.

getAvailableDevices¹¹⁺

getAvailableDevices(deviceUsage: DeviceUsage): AudioDeviceDescriptors

Obtains the available audio devices. This API returns the result synchronously.

System capability: SystemCapability.Multimedia.Audio.Device

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  let data: audio.AudioDeviceDescriptors = audioRoutingManager.getAvailableDevices(audio.DeviceUsage.MEDIA_OUTPUT_DEVICES);
  console.info(`Indicate that the device list is obtained ${data}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`Failed to obtain the device list. ${error}`);
}

on('availableDeviceChange')¹¹⁺

on(type: 'availableDeviceChange', deviceUsage: DeviceUsage, callback: Callback<DeviceChangeAction>): void

Subscribes to available audio device change events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Audio.Device

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, (deviceChanged: audio.DeviceChangeAction) => {
  console.info('device change type : ' + deviceChanged.type);
  console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length);
  console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole);
  console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType);
});

off('availableDeviceChange')¹¹⁺

off(type: 'availableDeviceChange', callback?: Callback<DeviceChangeAction>): void

Unsubscribes from available audio device change events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Audio.Device

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

audioRoutingManager.off('availableDeviceChange');

selectInputDevice⁹⁺

selectInputDevice(inputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void

Selects an audio input device. Currently, only one input device can be selected. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Device

Parameters

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
  deviceRole : audio.DeviceRole.INPUT_DEVICE,
  deviceType : audio.DeviceType.MIC,
  id : 1,
  name : "",
  address : "",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : "",
}];

async function selectInputDevice(){
  audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor, (err: BusinessError) => {
    if (err) {
      console.error(`Result ERROR: ${err}`);
    } else {
      console.info('Select input devices result callback: SUCCESS');
    }
  });
}

selectInputDevice⁹⁺

selectInputDevice(inputAudioDevices: AudioDeviceDescriptors): Promise<void>

System API: This is a system API.

Selects an audio input device. Currently, only one input device can be selected. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Audio.Device

Parameters

Return value

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
  deviceRole : audio.DeviceRole.INPUT_DEVICE,
  deviceType : audio.DeviceType.MIC,
  id : 1,
  name : "",
  address : "",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : "",
}];

async function getRoutingManager(){
  audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor).then(() => {
    console.info('Select input devices result promise: SUCCESS');
  }).catch((err: BusinessError) => {
    console.error(`Result ERROR: ${err}`);
  });
}

selectOutputDevice⁹⁺

selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void

Selects an audio output device. Currently, only one output device can be selected. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Device

Parameters

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
  deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
  deviceType : audio.DeviceType.SPEAKER,
  id : 1,
  name : "",
  address : "",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : "",
}];

async function selectOutputDevice(){
  audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor, (err: BusinessError) => {
    if (err) {
      console.error(`Result ERROR: ${err}`);
    } else {
      console.info('Select output devices result callback: SUCCESS'); }
  });
}

selectOutputDevice⁹⁺

selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors): Promise<void>

System API: This is a system API.

Selects an audio output device. Currently, only one output device can be selected. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Audio.Device

Parameters

Return value

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
  deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
  deviceType : audio.DeviceType.SPEAKER,
  id : 1,
  name : "",
  address : "",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : "",
}];

async function selectOutputDevice(){
  audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor).then(() => {
    console.info('Select output devices result promise: SUCCESS');
  }).catch((err: BusinessError) => {
    console.error(`Result ERROR: ${err}`);
  });
}

selectOutputDeviceByFilter⁹⁺

selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void

System API: This is a system API.

Selects an audio output device based on the filter criteria. Currently, only one output device can be selected. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Audio.Device

Parameters

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let outputAudioRendererFilter: audio.AudioRendererFilter = {
  uid : 20010041,
  rendererInfo : {
    usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
    rendererFlags : 0
  },
  rendererId : 0
};

let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
  deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
  deviceType : audio.DeviceType.SPEAKER,
  id : 1,
  name : "",
  address : "",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : "",
}];

async function selectOutputDeviceByFilter(){
  audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor, (err: BusinessError) => {
    if (err) {
      console.error(`Result ERROR: ${err}`);
    } else {
      console.info('Select output devices by filter result callback: SUCCESS'); }
  });
}

selectOutputDeviceByFilter⁹⁺

selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors): Promise<void>

System API: This is a system API.

Selects an audio output device based on the filter criteria. Currently, only one output device can be selected. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Audio.Device

Parameters

Return value

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let outputAudioRendererFilter: audio.AudioRendererFilter = {
  uid : 20010041,
  rendererInfo : {
    usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
    rendererFlags : 0
  },
  rendererId : 0
};

let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
  deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
  deviceType : audio.DeviceType.SPEAKER,
  id : 1,
  name : "",
  address : "",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : "",
}];

async function selectOutputDeviceByFilter(){
  audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor).then(() => {
    console.info('Select output devices by filter result promise: SUCCESS');
  }).catch((err: BusinessError) => {
    console.error(`Result ERROR: ${err}`);
  })
}

AudioRendererChangeInfo⁹⁺

Describes the audio renderer change event.

System capability: SystemCapability.Multimedia.Audio.Renderer

AudioCapturerChangeInfo⁹⁺

Describes the audio capturer change event.

System capability: SystemCapability.Multimedia.Audio.Capturer

AudioDeviceDescriptor

Describes an audio device.

AudioRendererFilter⁹⁺

Implements filter criteria. Before calling selectOutputDeviceByFilter, you must obtain an AudioRendererFilter instance.

System API: This is a system API.

Example

import audio from '@ohos.multimedia.audio';

let outputAudioRendererFilter: audio.AudioRendererFilter = {
  uid : 20010041,
  rendererInfo : {
    usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
    rendererFlags : 0
  },
  rendererId : 0
};

AudioSpatializationManager¹¹⁺

Implements spatial audio management. Before calling an API in AudioSpatializationManager, you must use getSpatializationManager to obtain an AudioSpatializationManager instance.

isSpatializationSupported¹¹⁺

isSpatializationSupported(): boolean

Checks whether the system supports spatial audio rendering. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';
try {
  let isSpatializationSupported: boolean = audioSpatializationManager.isSpatializationSupported();
  console.info(`AudioSpatializationManager isSpatializationSupported: ${isSpatializationSupported}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`ERROR: ${error}`);
}

isSpatializationSupportedForDevice¹¹⁺

isSpatializationSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean

Checks whether a device supports spatial audio rendering. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
  deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
  deviceType : audio.DeviceType.BLUETOOTH_A2DP,
  id : 1,
  name : "",
  address : "123",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : ""
}
try {
  let isSpatializationSupportedForDevice: boolean = audioSpatializationManager.isSpatializationSupportedForDevice(deviceDescriptor);
  console.info(`AudioSpatializationManager isSpatializationSupportedForDevice: ${isSpatializationSupportedForDevice}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`ERROR: ${error}`);
}

isHeadTrackingSupported¹¹⁺

isHeadTrackingSupported(): boolean

Checks whether the system supports head tracking. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';
try {
  let isHeadTrackingSupported: boolean = audioSpatializationManager.isHeadTrackingSupported();
  console.info(`AudioSpatializationManager isHeadTrackingSupported: ${isHeadTrackingSupported}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`ERROR: ${error}`);
}

isHeadTrackingSupportedForDevice¹¹⁺

isHeadTrackingSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean

Checks whether a device supports head tracking. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';
let deviceDescriptor: audio.AudioDeviceDescriptor = {
  deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
  deviceType : audio.DeviceType.BLUETOOTH_A2DP,
  id : 1,
  name : "",
  address : "123",
  sampleRates : [44100],
  channelCounts : [2],
  channelMasks : [0],
  networkId : audio.LOCAL_NETWORK_ID,
  interruptGroupId : 1,
  volumeGroupId : 1,
  displayName : ""
}
try {
  let isHeadTrackingSupportedForDevice: boolean = audioSpatializationManager.isHeadTrackingSupportedForDevice(deviceDescriptor);
  console.info(`AudioSpatializationManager isHeadTrackingSupportedForDevice: ${isHeadTrackingSupportedForDevice}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`ERROR: ${error}`);
}

setSpatializationEnabled¹¹⁺

setSpatializationEnabled(enable: boolean, callback: AsyncCallback<void>): void

Enables or disables spatial audio rendering. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let enable: boolean = true
audioSpatializationManager.setSpatializationEnabled(enable, (err: BusinessError) => {
  if (err) {
    console.error(`Result ERROR: ${err}`);
  } else {
    console.info(`setSpatializationEnabled success`);
  }
});

setSpatializationEnabled¹¹⁺

setSpatializationEnabled(enable: boolean): Promise<void>

Enables or disables spatial audio rendering. This API uses a promise to return the result.

Required permissions: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let enable: boolean = true
audioSpatializationManager.setSpatializationEnabled(enable).then(() => {
  console.info(`setSpatializationEnabled success`);
}).catch((err: BusinessError) => {
  console.error(`Result ERROR: ${err}`);
});

isSpatializationEnabled¹¹⁺

isSpatializationEnabled(): boolean

Checks whether spatial audio rendering is enabled. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';
try {
  let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled();
  console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`ERROR: ${error}`);
}

on('spatializationEnabledChange')¹¹⁺

on(type: 'spatializationEnabledChange', callback: Callback<boolean>): void

Subscribes to spatial audio rendering status changes.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';

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

off('spatializationEnabledChange')¹¹⁺

off(type: 'spatializationEnabledChange', callback?: Callback<boolean>): void

Unsubscribes from spatial audio rendering status changes.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
audioSpatializationManager.off('spatializationEnabledChange');

setHeadTrackingEnabled¹¹⁺

setHeadTrackingEnabled(enable: boolean, callback: AsyncCallback<void>): void

Enables or disables head tracking. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let enable: boolean = true
audioSpatializationManager.setHeadTrackingEnabled(enable, (err: BusinessError) => {
  if (err) {
    console.error(`Result ERROR: ${err}`);
  } else {
    console.info(`setHeadTrackingEnabled success`);
  }
});

setHeadTrackingEnabled¹¹⁺

setHeadTrackingEnabled(enable: boolean): Promise<void>

Enables or disables head tracking. This API uses a promise to return the result.

Required permissions: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';

let enable: boolean = true
audioSpatializationManager.setHeadTrackingEnabled(enable).then(() => {
  console.info(`setHeadTrackingEnabled success`);
}).catch((err: BusinessError) => {
  console.error(`Result ERROR: ${err}`);
});

isHeadTrackingEnabled¹¹⁺

isHeadTrackingEnabled(): boolean

Checks whether head tracking is enabled. This API returns the result synchronously.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Return value

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';
try {
  let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled();
  console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`ERROR: ${error}`);
}

on('headTrackingEnabledChange')¹¹⁺

on(type: 'headTrackingEnabledChange', callback: Callback<boolean>): void

Subscribes to head tracking status changes.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';

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

off('headTrackingEnabledChange')¹¹⁺

off(type: 'headTrackingEnabledChange', callback?: Callback<boolean>): void

Unsubscribes from head tracking status changes.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
audioSpatializationManager.off('headTrackingEnabledChange');

updateSpatialDeviceState¹¹⁺

updateSpatialDeviceState(spatialDeviceState: AudioSpatialDeviceState): void

Updates the state information of a spatial device. This API returns the result synchronously.

Required permissions: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Parameters

Error codes

For details about the error codes, see Audio Error Codes.

Example

import audio from '@ohos.multimedia.audio';
import { BusinessError } from '@ohos.base';
let spatialDeviceState: audio.AudioSpatialDeviceState = {
  address: "123",
  isSpatializationSupported: true,
  isHeadTrackingSupported: true,
  spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE
}
try {
  audioSpatializationManager.updateSpatialDeviceState(spatialDeviceState);
  console.info(`AudioSpatializationManager updateSpatialDeviceState success`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`ERROR: ${error}`);
}

AudioSpatialDeviceState¹¹⁺

Defines the state information of a spatial device.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

Example

import audio from '@ohos.multimedia.audio';

let spatialDeviceState: audio.AudioSpatialDeviceState = {
  address: "123",
  isSpatializationSupported: true,
  isHeadTrackingSupported: true,
  spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE
}

AudioSpatialDeviceType¹¹⁺

Enumerates the types of spatial devices.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Spatialization

ToneType⁹⁺

Enumerates the tone types of the player.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

TonePlayer⁹⁺

Provides APIs for playing and managing DTMF tones, such as dial tones, ringback tones, supervisory tones, and proprietary tones. Before calling any API in TonePlayer, you must use createTonePlayer to create a TonePlayer instance.

System API: This is a system API.

load⁹⁺

load(type: ToneType, callback: AsyncCallback<void>): void

Loads the DTMF tone configuration. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Parameters

Example

import { BusinessError } from '@ohos.base';

tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_5, (err: BusinessError) => {
  if (err) {
    console.error(`callback call load failed error: ${err.message}`);
    return;
  } else {
    console.info('callback call load success');
  }
});

load⁹⁺

load(type: ToneType): Promise<void>

Loads the DTMF tone configuration. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Parameters

Return value

Example

tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_1).then(() => {
  console.info('promise call load ');
}).catch(() => {
  console.error('promise call load fail');
});

start⁹⁺

start(callback: AsyncCallback<void>): void

Starts DTMF tone playing. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Parameters

Example

import { BusinessError } from '@ohos.base';

tonePlayer.start((err: BusinessError) => {
  if (err) {
    console.error(`callback call start failed error: ${err.message}`);
    return;
  } else {
    console.info('callback call start success');
  }
});

start⁹⁺

start(): Promise<void>

Starts DTMF tone playing. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Return value

Example

tonePlayer.start().then(() => {
  console.info('promise call start');
}).catch(() => {
  console.error('promise call start fail');
});

stop⁹⁺

stop(callback: AsyncCallback<void>): void

Stops the tone that is being played. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Parameters

Example

import { BusinessError } from '@ohos.base';

tonePlayer.stop((err: BusinessError) => {
  if (err) {
    console.error(`callback call stop error: ${err.message}`);
    return;
  } else {
    console.error('callback call stop success ');
  }
});

stop⁹⁺

stop(): Promise<void>

Stops the tone that is being played. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Return value

Example

tonePlayer.stop().then(() => {
  console.info('promise call stop finish');
}).catch(() => {
  console.error('promise call stop fail');
});

release⁹⁺

release(callback: AsyncCallback<void>): void

Releases the resources associated with the TonePlayer instance. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Parameters

Example

import { BusinessError } from '@ohos.base';

tonePlayer.release((err: BusinessError) => {
  if (err) {
    console.error(`callback call release failed error: ${err.message}`);
    return;
  } else {
    console.info('callback call release success ');
  }
});

release⁹⁺

release(): Promise<void>

Releases the resources associated with the TonePlayer instance. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Multimedia.Audio.Tone

Return value

Example

tonePlayer.release().then(() => {
  console.info('promise call release');
}).catch(() => {
  console.error('promise call release fail');
});