Audio Manager
Audio Manager allows audio management such as volume adjustment and mute control.
- TOC
Required privileges
The API requires specific privileges for certain operations:
[[needs.privilege]]
id = "com.amazon.audio.privilege.settings.control"
The API also requires declaration of the system audio service:
[wants]
[[wants.service]]
id = "com.amazon.audio.control"
Types Used
Refer to Audio core types
AudioVolumeTypeAudioVolumeFlagsAudioStatusAudioEventAudioDeviceAudioRoleAudioAttributesAudioContentTypeAudioUsageTypeAudioFlagsSinkFormatsSelectionPolicy
Static Methods
AudioManager.setVolumeAsync(type, volume, flags)
Description
Sets the volume of a type of audio to a specified volume. If a volume larger than 100 is input, it will set the volume to 100. If a volume less than than 0 is input, it will set the volume to 0.
Return Value
Returns a promise that resolves to an AudioStatus type.
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| type | AudioVolumeType | Yes | Represents the type of audio for volume adjustment. |
| volume | Int32 | Yes | Integer value that represents volume percent of an audio source |
| flags | AudioVolumeFlags | No | Sets the flag, defaults to AudioVolumeFlags.VOLUME_FLAG_NONE if not inputted |
Example code
/*
Sets volume of audio type alarm to 50% and stores returned AudioStatus type in
status after the promise resolves, otherwise stores undefined and prints an error
if promise fails
*/
const status = AudioManager.setVolumeAsync(AudioVolumeType.VOLUME_TYPE_ALARM, 50)
.then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.getVolumeAsync(type)
Description
Retrieves volume of a specified audio type.
Return Value
Returns a promise that resolves to an integer representing what percentage the volume for a specific type is currently at.
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| type | AudioVolumeType | Yes | Represents the type of audio for volume adjustment. |
Example code
/*
Retrieves volume percent of audio type media and stores it in volume after promise resolves
*/
const volume = AudioManager.getVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA)
.then((volume) => {return volume;}).catch((error) => console.log(error));
AudioManager.setMicMuteAsync(mute)
Description
Mutes or unmutes all microphone input based on the boolean input.
Return Value
Returns a promise that resolves to an AudioStatus type.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| mute | boolean | Yes | Boolean value representing whether to mute or unmute microphone input. Inputting True will mute microphone input and inputting false will unmute microphone input. |
Example code
/*
Mutes microphone input and stores returned AudioStatus type in status after promise
resolves
*/
const status = AudioManager.setMicMuteAsync(true).then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.getMicMuteAsync()
Description
Retrieves the mute status of microphone input.
Return Value
Returns a promise that resolves to a boolean representing mute status of microphone input.
Example code
/*
Gets mute status of microphone input and stores the returned boolean in mute_status
after promise resolves
*/
const mute_status = AudioManager.getMicMuteAsync()
.then((mute_status) => {return mute_status;}).catch((error) => console.log(error));
AudioManager.setGlobalVolumeMuteAsync(mute, flags)
Description
Mutes or unmutes all audio source types globally based on the boolean input.
Return Value
Returns a promise that resolves to an AudioStatus type.
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| mute | boolean | Yes | Boolean value representing whether to mute or unmute all audio source types |
| flags | AudioVolumeFlags | No | Sets the flag, defaults to AudioVolumeFlags.VOLUME_FLAG_NONE if not inputted |
Example Code
/*
Sets global mute to true and stores returned AudioStatus type in status after
promise resolves
*/
const status = AudioManager.setGlobalVolumeMuteAsync(true).then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.getGlobalVolumeMuteAsync()
Description
Retrieves global mute status.
Return Value
Returns a promise that resolves to a boolean representing global mute status.
Example Code
/*
Gets global mute status and stores the boolean in global_mute after promise resolves
*/
const global_mute = AudioManager.getGlobalVolumeMuteAsync().then((global_mute) => {return global_mute;}).catch((error) => console.log(error));
AudioManager.registerAudioEventObserverAsync(callback)
Description
Registers a callback function that executes anytime an audio change event is detected. Only one callback function can be registered at a time.
Return Value
Returns a promise that resolves to an AudioStatus type.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| callback | function | Yes | callback function that takes in an event and does something based on that event |
Example code
/*
Creates a function and registers it in the Audio Event Observer to execute this
function whenever an audio change happens and stores returned AudioStatus
type in status after promise resolves
*/
// Register for system-wide audio events
await AudioManager.registerAudioEventObserverAsync((event) => {
// Event object will contain different properties based on the event type
switch (event.audioEvent) {
case AudioEvent.DEVICE_STATE_UPDATE:
// Triggered when an audio device's connection state changes
// Parameters:
// - device: AudioDevice enum value
// - role: AudioRole enum value
// - connect: boolean indicating if device was connected (true) or disconnected (false)
console.log(`Device ${event.device} with role ${event.role} ${event.connect ? 'connected' : 'disconnected'}`);
break;
case AudioEvent.VOLUME_UPDATE:
// Triggered when volume changes for any audio type
// Parameters:
// - type: AudioVolumeType enum value
// - volume: number (0-100)
console.log('Volume changed for:', event.audioEvent, 'to:', event.volume);
break;
case AudioEvent.GLOBAL_VOLUME_MUTE_UPDATE:
// Triggered when global mute state changes
// Parameters:
// - mute: boolean indicating if system is muted
console.log('Global mute updated to state: ', event.mute);
break;
case AudioEvent.SERVER_DOWN:
// Triggered when audio server becomes unavailable
console.log('Audio server is down');
break;
case AudioEvent.SERVER_UP:
// Triggered when audio server becomes available
console.log('Audio server is up');
break;
case AudioEvent.AUDIO_USAGE_STATE_CHANGE:
// Triggered when audio usage state changes
// Parameters:
// - usage: AudioUsageType enum value
// - active: boolean indicating if usage became active
console.log('Usage: ', event.usage);
console.log('Active status: ', event.active);
break;
case AudioEvent.MIC_MUTE_STATE_UPDATE:
// Triggered when microphone mute state changes
// Parameters:
// - state: boolean indicating if mic is muted
console.log('Mic mute state changed: ', event.muteState);
break;
case AudioEvent.VOLUME_MUTE_UPDATE:
// Triggered when volume mute state changes for specific volume type
// Parameters:
// - volumeType: AudioVolumeType enum value
// - mute: boolean indicating if type is muted
console.log('Volume type: ', event.volumeType);
console.log('Mute state: ', event.muteState);
break;
case AudioEvent.TELEPHONY_MUTE_UPDATE:
// Triggered when telephony mute state changes
// Parameters:
// - deviceType: AudioDevice enum value
// - address: string representing device address
// - deviceName: string representing device name
// - mute: boolean indicating if telephony is muted
console.log('Telephony mute update!: ');
console.log('Device type: ', event.deviceType);
console.log('Device address: ', event.deviceAddress);
console.log('Device name: ', event.deviceName);
console.log('Device mute state: ', event.muteState);
break;
}
});
// Cleanup
await AudioManager.unregisterAudioEventObserverAsync();
AudioManager.unregisterAudioEventObserverAsync()
Description
Unregisters any callback function that is currently registered. If there are no callbacks registered, nothing happens.
Return Value
Returns a promise that resolves to an AudioStatus type.
Example code
/*
Unregisters callback function and stores returned AudioStatus type in status after
promise resolves
*/
const status = AudioManager.unregisterAudioEventObserverAsync().then((status) => {return status;}).catch((error) => console.log(error));
AudioManager.isServerReadyAsync()
Description
Checks if the AudioServer is ready to process commands.
Return Value
Returns a promise resolving to a boolean value that indicates whether the server is ready.
Example code
//Returns true if server is ready to receive commands, false if not ready
const server_ready = AudioManager.isServerReadyAsync()
.then((ready) => {return ready;}).catch((error) => console.log(error));
AudioManager.setTelephonyMuteAsync(device, address, mute)
Description
Mute/unmute the telephony uplink.
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| device | AudioDevice | Yes | Device type to set muted state |
| address | string | yes | Address pointing to the requested device |
| mute | boolean | yes | Requested mute state |
Example code
let muteStatus = await AudioManager.setTelephonyMuteAsync(AudioDevice.DEVICE_TELEPHONY, "0X859978AF", true);
if (muteStatus == 0) {
console.log("setTelephonyMuteAsync(): Result: SUCCESS")
status = status + "setTelephonyMuteAsync():\nResult: SUCCESS\n";
} else {
console.log("setTelephonyMuteAsync(): Result: ERROR: ", muteStatus);
status = status + "setTelephonyMuteAsync():\nResult: ERROR: " + muteStatus.toString() + "\n";
}
AudioManager.getTelephonyMuteAsync(device, address)
Description
Mute/unmute the telephony uplink.
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| device | AudioDevice | Yes | Device type to set muted state |
| address | string | yes | Address pointing to the requested device |
Example code
let muteStatus = await AudioManager.getTelephonyMuteAsync(AudioDevice.DEVICE_TELEPHONY, "0X859978AF");
console.log("getTelephonyMuteAsync(): SUCCESS, Mute state: ", Boolean(muteStatus));
AudioManager.setActiveVolumeAsync(volume)
Description
Set volume of active stream.
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| volume | Int32 / number | Yes | Requested volume from 0 to 100 |
Example code
export const testSetActiveVolumeAsync = async (volume: number) => {
let requestStatus = await AudioManager.setActiveVolumeAsync(parseInt(volume));
if (requestStatus == 0) {
console.log("setActiveVolumeAsync SUCCESS");
} else {
console.log("setActiveVolumeAsync(): ERROR: " + requestStatus);
}
};
AudioManager.updateVolumeAsync(type, mode)
Description
Update volume of a specific type (for e.g. Music / Notification etc.)
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| type | AudioVolumeType | Yes | Volume type to be updated |
| mode | Int32 | Yes | 0 = Increase, 1 = Decrease |
Example code
const testUpdateVolumeAsync = async () => {
let updateStatus = await AudioManager.updateVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA, 0);
if (updateStatus == 0) {
console.log("updateVolumeAsync() SUCCESS");
} else {
console.log("updateVolumeAsync(): ERROR: " + updateStatus);
}
};
AudioManager.updateActiveVolumeAsync(update, fallbackType)
Description
Update volume of active stream If there is no active stream, audio server will set volume for fallback type
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
|Parameter Name |Type |Required |Description |
|— |— |— |— |
|update |Int32 |Yes |0 = Increase, 1 = Decrease |
|fallbackType |VolumeType |Yes |Volume type to be updated |
Example code
const testUpdateActiveVolumeAsync = async () => {
let updateStatus = await AudioManager.updateActiveVolumeAsync(0, AudioVolumeType.VOLUME_TYPE_MEDIA);
if (updateStatus == 0) {
console.log("updateActiveVolumeAsync() SUCCESS");
} else {
console.log("updateActiveVolumeAsync(): ERROR: " + updateStatus);
}
};
AudioManager.setMuteAsync(volType, mute)
Description
Set mute for audio volume type. Mute when true, audio output for volume type will be silenced regardless of individual stream volumes.
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| volType | AudioVolumeType | Yes | Volume type to be muted |
| mute | boolean | Yes | Mute state requested |
Example code
const testSetMuteAsync = async () => {
let updateStatus = await AudioManager.setMuteAsync(AudioVolumeType.VOLUME_TYPE_MEDIA, true);
if (updateStatus == 0) {
console.log("setMuteAsync() SUCCESS");
} else {
console.log("setMuteAsync(): ERROR: " + updateStatus);
}
};
AudioManager.getMuteAsync(volType)
Description
Query current mute for audio volume type
Return Value
Returns Promise with mute state (boolean)
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| volType | AudioVolumeType | Yes | Volume type to query mute state |
Example code
const testGetMuteAsync = async () => {
let muteStatus = await AudioManager.setMuteAsync(AudioVolumeType.VOLUME_TYPE_MEDIA);
console.log("setMuteAsync(): SUCCESS, Mute state: ", Boolean(muteStatus));
};
AudioManager.setMaxVolumeAsync(maxVolume)
Description
Set max volume limit. Clients can use this API to set maximum limit on all types of volume levels. By default the maximum volume limit is 100, using this API it can be set to 0 - 100.
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
Needs privilege com.amazon.audio.privilege.settings.control
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| maxVolume | Int32 | Yes | new max limit as a percentage of true max volume |
Example code
const testSetMaxVolume = async () => {
let volumeChangeStatus = await AudioManager.setMaxVolumeAsync(50);
if (volumeChangeStatus == 0) {
console.log("setMaxVolumeAsync() SUCCESS");
} else {
console.log("setMaxVolumeAsync(): ERROR: " + volumeChangeStatus);
}
};
AudioManager.getMaxVolumeAsync()
Description
Get max volume limit Retrieve previously set max volume limit using setMaxVolume() api or system default, value 0 - 100.
Return Value
Returns Promise with current max volume limit (Int32).
Parameters
| Parameter Name | Type | Required | Description | | ————– | —- | ——– | ———– |
Example code
const testGetMaxVolume = async () => {
let maxVolume = await AudioManager.getMaxVolumeAsync();
console.log("getMaxVolumeAsync(): SUCCESS, Max volume: ", maxVolume);
};
AudioManager.getSupportedPlaybackConfigurationsAsync(attributes, deviceType)
Description
Set max volume limit. Clients can use this API to set maximum limit on all types of volume levels. By default the maximum volume limit is 100, using this API it can be set to 0 - 100.
Return Value
Returns Promise with an array of objects which containins all the supported audio configurations for the given parameters. The structure of the received objects contains: {
- sampleRate: AudioSampleRate
- channelMask: AudioChannelMask
- format: AudioSampleFormat
- layout: SampleLayout
}
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| attributes | AudioAttributes | Yes | Audio attributes to query |
| deviceType | AudioDevice | Yes | Audio device type to query |
Note: Use AudioDevice.DEVICE_DEFAULT for the current audio device.
Example code
let supportedAudioConfigs = await AudioManager.getSupportedPlaybackConfigurationsAsync(configAttr, AudioDevice.DEVICE_DEFAULT);
for (let audioConfig: supportedAudioConfigs) {
console.log("format", audioConfig.format);
console.log("sample rate", audioConfig.sampleRate);
console.log("channel mask", audioConfig.channelMask);
console.log("layout", audioConfig.layout);
}
AudioManager.setSinkFormatsSelectionPolicyAsync(policy)
Description
Set audio sink formats selection policy
Return Value
Returns Promise with audio status code (AudioStatus type)
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| policy | SinkFormatsSelectionPolicy | Yes | The sink policy that is going to be applied |
Example code
const testSetSinkFormatsSelectionPolicyAsync = async () => {
let sinkStatus = await AudioManager.setSinkFormatsSelectionPolicyAsync(SinkFormatsSelectionPolicy.AUTO);
if (sinkStatus == 0) {
console.log("setSinkFormatsSelectionPolicyAsync(): Result: SUCCESS")
} else {
console.log("setSinkFormatsSelectionPolicyAsync(): Result: ERROR: ", sinkStatus);
}
};
AudioManager.getSinkFormatsSelectionPolicyAsync()
Description
Get the current audio sink mode format selection policy
Return Value
Returns Promise with current selection policy (Int32)
Parameters
| Parameter Name | Type | Required | Description | | ————– | —- | ——– | ———– |
Example code
const testGetSinkFormatsSelectionPolicyAsync = async () => {
let currentSinkPolicy = await AudioManager.getSinkFormatsSelectionPolicyAsync();
console.log("getSinkFormatsSelectionPolicyAsync() Current format: ", currentSinkPolicy);
};
AudioManager.getSupportedSinkFormatsSelectionPoliciesAsync()
Description
Get the list of all supported sink formats selection policies
Return Value
Returns Promise with an array ofall the supported policies.
Parameters
| Parameter Name | Type | Required | Description | | ————– | —- | ——– | ———– |
Example code
const testGetSupportedSinkFormatsSelectionPoliciesAsync = async () => {
let supportedSinkFormats = await AudioManager.getSupportedSinkFormatsSelectionPoliciesAsync();
if (supportedSinkFormats.length > 0) {
supportedSinkFormats.forEach(data => {
console.log("Supported policy (integer representation): ", parseInt(data), "\n");
});
}
};
Last updated: Oct 02, 2025
