AudioFocusSession - Amazon Vega Docs

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

​Required services

​Types Used

​Constructors

​new AudioFocusSession()

​Parameters

id

​Returns

​Properties

​sessionId

​focusUsage

​Methods

​getAudioSessionId()

​Returns

​Examples

​getUsage()

​Returns

​Examples

​registerAudioFocusListenerAsync()

​Parameters

callback

​Returns

​Examples

​releaseAudioFocusAsync()

​Returns

​Examples

​requestAudioFocusAsync()

​Parameters

attr?

​Returns

​Examples

​unregisterAudioFocusListenerAsync()

​Returns

​Examples

Required services

Types Used

Constructors

new AudioFocusSession()

Parameters

Returns

Properties

sessionId

focusUsage

Methods

getAudioSessionId()

Returns

Examples

getUsage()

Returns

Examples

registerAudioFocusListenerAsync()

Parameters

Returns

Examples

releaseAudioFocusAsync()

Returns

Examples

requestAudioFocusAsync()

Parameters

Returns

Examples

unregisterAudioFocusListenerAsync()

Returns

Examples