AudioFocusSession

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

• *

Constructors

new AudioFocusSession()

new AudioFocusSession(id): AudioFocusSession

Parameters

id

number

Session ID obtained from

Returns

AudioFocusSession

Properties

sessionId

sessionId: number

---

focusUsage

focusUsage: number

Methods

getAudioSessionId()

getAudioSessionId(): number

Gets the session ID for this instance.

Returns

number

number The session ID assigned to this instance

Examples

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

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

---

getUsage()

getUsage(): number

Gets the current audio usage type for this focus session. Returns USAGE_NONE if no focus has been requested.

Returns

number

number The current audio usage type from enum

Examples

/*
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.

---

registerAudioFocusListenerAsync()

registerAudioFocusListenerAsync(callback: (value: any) => void): Promise<AudioFocusStatus>

Registers a callback to receive audio focus change notifications. Only one callback can be registered per session at a time.

Parameters

callback

(value: any) => void

Function to receive focus change events. Events include:

• GRANTED (0): Focus was granted
• RELEASED (1): Focus was released
• DUCKED (2): Audio ducked (reduced volume)
• PAUSED (3): Audio paused
• STOPPED (4): Audio stop

Returns

Promise<AudioFocusStatus>

Promise A promise that resolves to:

• AUDIO_FOCUS_STATUS_NO_ERROR (0): Callback registered successfully
• AUDIO_FOCUS_STATUS_BAD_VALUE (-2): Invalid callback
• AUDIO_FOCUS_STATUS_NO_INIT (-3): Session not initialized
• AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8): Callback already registered

Examples

/*
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));

---

releaseAudioFocusAsync()

releaseAudioFocusAsync(): Promise<AudioFocusStatus>

Releases previously requested audio focus. This must be called when audio playback is completed or when focus is no longer needed.

Returns

Promise<AudioFocusStatus>

Promise A promise that resolves to:

• AUDIO_FOCUS_STATUS_NO_ERROR (0): Focus released successfully
• AUDIO_FOCUS_STATUS_BAD_VALUE (-2): Invalid session state
• AUDIO_FOCUS_STATUS_NO_INIT (-3): Session not initialized
• AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8): No focus held

Examples

/*
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));

---

requestAudioFocusAsync()

requestAudioFocusAsync(attr?: AudioFocusAttributes | undefined): Promise<AudioFocusStatus>

Requests audio focus for the session with specified attributes. When focus is granted, any previously focused audio may be ducked, paused, or stopped based on the usage type.

Parameters

attr?

AudioFocusAttributes | undefined

Optional configuration for focus request. If not provided, defaults to USAGE_MEDIA.

Returns

Promise<AudioFocusStatus>

Promise A promise that resolves to:

• AUDIO_FOCUS_STATUS_NO_ERROR (0): Focus granted successfully
• AUDIO_FOCUS_STATUS_DENIED (1): Focus request denied
• AUDIO_FOCUS_STATUS_DELAYED (2): Focus request delayed
• AUDIO_FOCUS_STATUS_BAD_VALUE (-2): Invalid attributes
• AUDIO_FOCUS_STATUS_NO_INIT (-3): Session not initialized
• AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8): Invalid operation

Examples

/*
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));

---

unregisterAudioFocusListenerAsync()

unregisterAudioFocusListenerAsync(): Promise<AudioFocusStatus>

Unregister the previously registered focus change callback.

Returns

Promise<AudioFocusStatus>

Promise A promise that resolves to:

• AUDIO_FOCUS_STATUS_NO_ERROR (0): Callback unregistered successfully
• AUDIO_FOCUS_STATUS_BAD_VALUE (-2): Invalid session state
• AUDIO_FOCUS_STATUS_NO_INIT (-3): Session not initialized
• AUDIO_FOCUS_STATUS_INVALID_OPERATION (-8): No callback registered

Examples

/*
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));

---

Last updated: Jul 22, 2026