Audio Focus Session

Audio Focus Session allows audio focus management such as requesting audio focus and releasing audio focus. Audio Focus session is used by playback streams to request audio focus or release audio focus. A playback stream builder can specify an audio focus session to use by using playback stream builder's setAudioFocusSessionId.

Required services

The API requires declaration of the system audio service:

[wants]
[[wants.service]]
id = "com.amazon.audio.control"

Types Used

Refer to Audio core types

• AudioFocusAttributes
• AudioFocusStatus
• AudioFocusChange

Methods

requestAudioFocusAsync(attr)

Description

Requests audio focus in the session with the selected audio usage type.

Return Value

Returns a promise resolving to a AudioFocusStatus type.

Parameters

Parameter Name	Type	Required	Description
attr	AudioFocusAttributes	No	Determines how to handle audio focus. Creates a new attribute if one is not specified.

Example code

/*
Requests audio focus, returns a AudioFocusStatus type when the promise is resolved

Assume session is an AudioFocusSession object
*/
const attr: AudioFocusAttributes = {
    usage: audioSource.usage
};
const status = session.requestAudioFocusAsync(attr)
.then((status) => {return status;}).catch((error) => console.log(error));

releaseAudioFocusAsync()

Description

Releases audio focus in the session.

Return Value

Returns a promise resolving to a AudioFocusStatus type.

Example code

/*
Releases audio focus, returns a AudioFocusStatus type when the promise is resolved

Assume session is an AudioFocusSession object
*/

const status = session.releaseAudioFocusAsync()
.then((status) => {return status;}).catch((error) => console.log(error));

registerAudioFocusListenerAsync(callback)

Description

Registers a callback function that executes anytime an audio focus event is detected. Only one callback function can be registered at a time.

Return Value

Returns a promise that resolves to an AudioFocusStatus type.

Parameters

Parameter Name	Type	Required	Description
callback	function	Yes	The callback function that takes in an event and outputs something based on that event

Example code

/*
Creates a function and registers it in the Audio Focus Listener to execute this
function whenever an audio focus change happens and stores returned AudioFocusStatus
type in status after promise resolves

Assume session is an AudioFocusSession object

*/

const callbackFunction = (event: any) => {
    switch (event.focusChange) {
        case AudioFocusChange.GRANTED:
            // Triggered when audio focus is granted
            break;

        case AudioFocusChange.RELEASED:
            // Triggered when audio focus is released
            break;

        case AudioFocusChange.DUCKED:
            // Triggered when audio should be ducked (reduced in volume)
            break;

        case AudioFocusChange.PAUSED:
            // Triggered when audio should be paused
            break;

        case AudioFocusChange.STOPPED:
            // Triggered when audio should be stopped
            break;

        case AudioFocusChange.MUTED:
            // Triggered when audio should be muted (Currently no product supports this)
            break;
    }
};
const status = session.registerAudioFocusListenerAsync(callbackFunction)
.then((status) => {return status;}).catch((error) => console.log(error));

unregisterAudioFocusListenerAsync()

Description

Unregisters any callback function that is currently registered for audio focus.

Return Value

Returns a promise that resolves to an AudioFocusStatus type.

Example code

/*
Unregisters callback function and stores returned AudioFocusStatus
type in status after promise resolves
*/

const status = session.unregisterAudioFocusListenerAsync()
.then((status) => {return status;}).catch((error) => console.log(error));

getAudioSessionId()

Description

Gets the value of the member variable sessionId, which represents the session id for a given focus session.

Return Value

Returns a number representing the session id.

Example code

/*
Returns the session id and stores it in sessionId
*/

const session = new AudioFocusSession(1);
const sessionId = session.getAudioSessionId(); //value should be 1

getUsage()

Description

Gets audio focus usage value

Return Value

Returns a number representing the audio focus usage.

Example code

/*
Requests audio focus, returns a AudioFocusStatus type when the promise is resolved

Assume session is an AudioFocusSession object
*/
const attr: AudioFocusAttributes = {
    usage: audioSource.usage
};
const status = session.requestAudioFocusAsync(attr)
.then((status) => {return status;}).catch((error) => console.log(error));

let usage = session.getUsage(); // Must be equal to the usage used to request the focus.

---

Last updated: Oct 02, 2025