Audio Playback Stream

Audio Playback Stream allows for control of playback streams such as pausing, flushing, and writing to the playback buffer.

• 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 services:

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

Types Used

Refer to Audio core types

• AudioStatus
• AudioAttributes
• AudioConfig
• AudioPlaybackEvent
• AudioVolumeType
• StreamDuckingPolicy
• DuckingMode

Methods

initCheckAsync()

Description

Checks if the playback stream has been initialized.

Return Value

Returns a promise resolving to an AudioStatus type.

Example code

/*
Gets the status of the audio playback stream and stores it in status

Assume playbackStream is an AudioPlaybackStream object
*/
const status = playbackStream.initCheckAsync()
.then((status) => {return status;}).catch((error) => console.log(error));

getAudioConfigAsync()

Description

Gets the audio configuration of a playback stream.

Return Value

Returns a promise resolving to an AudioConfig object.

Example code

/*
Gets the audio configuration for the playback stream and stores it in config after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const config = playbackStream.getAudioConfigAsync()
.then((config) => {return config;}).catch((error) => console.log(error));

getAudioAttributesAsync()

Description

Gets the audio attributes of a playback stream.

Return Value

Returns a promise resolving to an AudioAttributes object.

Example code

/*
Gets the audio attributes for the playback stream and stores it in attributes after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const attributes = playbackStream.getAudioAttributesAsync()
.then((attributes) => {return attributes;}).catch((error) => console.log(error));

getSampleRateAsync()

Description

Gets the sample rate of a playback stream.

Return Value

Returns a promise resolving to an Int32 representing the sample rate.

Example code

/*
Gets the sample rate for the playback stream and stores it in sample_rate after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const sample_rate= playbackStream.getSampleRateAsync()
.then((rate) => {return rate;}).catch((error) => console.log(error));

getChannelCountAsync()

Description

Gets the channel count of a playback stream.

Return Value

Returns a promise resolving to an Int32 representing the channel count.

Example code

/*
Gets the channel count for the playback stream and stores it in channel_count after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const channel_count = playbackStream.getChannelCountAsync()
.then((count) => {return count;}).catch((error) => console.log(error));

getSampleSizeAsync(**)

Description

Gets the sample size of a playback stream.

Return Value

Returns a promise resolving to an Int32 representing the sample size.

Example code

/*
Gets the sample size for the playback stream and stores it in sample_size after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const sample_size = playbackStream.getSampleSizeAsync()
.then((sample_size) => {return sample_size;}).catch((error) => console.log(error));

getNumBytesInPipelineAsync()

Description

Gets the number of bytes in the pipeline waiting to be consumed by audio pipeline between clients and audio server.

Return Value

Returns a promise resolving to an Int32 representing the number of bytes in the pipeline.

Example code

/*
Gets the number of bytes in the pipeline and stores it in pipeline_bytes after the
promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const pipeline_bytes = playbackStream.getNumBytesInPipelineAsync()
.then((bytes) => {return bytes;}).catch((error) => console.log(error));

getNumBytesOfNativeBufferAsync()

Description

Gets the number of bytes representing the size of the shared buffer between the client and audio server.

Return Value

Returns a promise resolving to an Int32 representing the number of bytes in the native buffer.

Example code

/*
Gets the number of bytes in the native buffer and stores it in buffer_bytes after the
promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const buffer_bytes = playbackStream.getNumBytesOfNativeBufferAsync()
.then((bytes) => {return bytes;}).catch((error) => console.log(error));

getFramesPerBufferAsync()

Description

Gets the number of frames per buffer.

Return Value

Returns a promise resolving to an Int32 representing the frames per buffer.

Example code

/*
Gets the number of frames in the native buffer and stores it in buffer_frames after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const buffer_frames = playbackStream.getFramesPerBufferAsync()
.then((frames) => {return frames;}).catch((error) => console.log(error));

getAudioFocusSessionIdAsync()

Description

Gets the focus session ID.

Return Value

Returns a promise resolving to an Int32 representing the focus session ID.

Example code

/*
Gets the focus session and stores it in session_id after the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const session_id = playbackStream.getAudioFocusSessionIdAsync()
.then((id) => {return id;}).catch((error) => console.log(error));

getLatencyInMsAsync()

Description

Gets the latency in milliseconds.

Return Value

Returns a promise resolving to an Int32 representing the latency in milliseconds.

Example code

/*
Gets the latency in ms and stores it in latency after the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*/

const latency = playbackStream.getLatencyInMsAsync()
.then((latency) => {return latency;}).catch((error) => console.log(error));

pauseAsync()

Description

Pauses the playback stream.

Return Value

Returns a promise that resolves to an AudioStatus type.

Example code

/*
Pauses the audio playback stream and stores returned AudioStatus type in status after
promise resolves

Assume playbackStream is an AudioPlaybackStream object
*/

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

startAsync()

Description

Starts the playback stream.

Return Value

Returns a promise that resolves to an AudioStatus type.

Example code

/*
Starts the audio playback stream and stores returned AudioStatus type in status after
promise resolves

Assume playbackStream is an AudioPlaybackStream object
*/

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

stopAsync()

Description

Stops the playback stream.

Return Value

Returns a promise that resolves to an AudioStatus type.

Example code

/*
Stops the audio playback stream and stores returned AudioStatus type in status after
promise resolves

Assume playbackStream is an AudioPlaybackStream object
*/

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

flushAsync()

Description

Flushes the playback stream.

Return Value

Returns a promise that resolves to an AudioStatus type.

Example code

/*
Flushes the audio playback stream and stores returned AudioStatus type in status
after promise resolves

Assume playbackStream is an AudioPlaybackStream object
*/

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

registerEventObserverAsync(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 playback Event Observer to execute this
function whenever an playback change happens and stores returned AudioStatus type in status
after promise resolves

Assume playbackStream is an AudioPlaybackStream object
*/

const playbackStreamEventHandler = (event: any) => {
    console.debug('playbackStreamEventHandler event received ->', event);
    switch (event.playbackStreamEvent) {
      case AudioPlaybackEvent.DIED:
        console.debug('Stream died for stream id: ', playbackStream.current);
        break;
      case AudioPlaybackEvent.RECOVERED:
        console.debug('Stream recovered for stream id: ', playbackStream.current);
        break;
      case AudioPlaybackEvent.STOPPED:
        console.debug('Stream stopped for stream id: ', playbackStream.current);
        break;
      case AudioPlaybackEvent.MUTE_STATE_UPDATE:
        console.debug('Stream mute state changed for stream id: ', playbackStream.current);
        console.debug('MuteState: ', event.muteState);
        break;
      case AudioPlaybackEvent.FRAME_UNDERRUN:
        console.debug('Stream underrun for stream id: ', playbackStream.current);
        console.debug('Underrun count: ', event.underrunCount);
        break;
      default:
        break;
    }
  };
const status = playbackStream.registerEventObserverAsync(playbackStreamEventHandler)
.then((status) => {return status;}).catch((error) => console.log(error));

unregisterEventObserverAsync(**)

Description

Unregisters any callback function that is currently registered.

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

Assume playbackStream is an AudioPlaybackStream object
*/

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

writeAsync(buffer)

Description

Writes to the playback buffer using bytes stored in buffer parameter.

Return Value

Returns a promise that resolves to an AudioStatus type.

Parameters

Parameter Name	Type	Required	Description
buffer	ArrayBuffer	Yes	A buffer containing the bytes to be written to the playback buffer

Example code

/*
Writes to the playback buffer and stores returned AudioStatus type in status after
promise resolves

Assume buffer is an Uint8Array containing the bytes to write to the buffer

Assume playbackStream is an AudioPlaybackStream object
*/

const status = playbackStream.writeAsync(buffer).then((status) => {return status;}).catch((error) => console.log(error));

getUnderrunSizeAsync()

Description

Get API for querying underrun size.

If a client has set a buffer underrun threshold and playback buffer is in underrun state, this API will return the difference between the buffer size and the threshold value.

Otherwise, this API will return 0.

Return Value

Returns a promise (Int32) with difference in frames between buffer size and underrun threshold. Frame value is rounded up.

Example code

/*
Assume playbackStream is an AudioPlaybackStream object
*/

const getUnderrunSizeAsyncTest = async () => {
    try {
      let underRunSize = await playbackStream.current?.getUnderrunSizeAsync();
      console.debug("getUnderrunSizeAsync() : ", underRunSize);
    } catch (error) {
      console.debug('Error: getUnderrunSizeAsync(): ', error);
    }
}

getUnderrunSizeAsyncTest();

getUnderrunCountAsync()

Description

Get API for querying number of underruns that occurred during stream lifetime.

Return Value

Returns a promise (Int32) with number of underrun ocurrences that occurred during stream lifetime.

Example code

/*
Assume playbackStream is an AudioPlaybackStream object
*/

const getUnderrunCountAsyncTest = async () => {
    try {
      let underRunCount = await playbackStream.current?.getUnderrunCountAsync();
      console.debug("getUnderrunCountAsync() : ", underRunCount);
    } catch (error) {
      console.debug('Error: getUnderrunCountAsync(): ', error);
    }
}

getUnderrunCountAsyncTest();

getPresentedFrameCountAsync()

Description

Query api for number of audio frames already presented and accepted by audio pipeline.

Return Value

Returns a promise (Int32) with number of audio frames presented to audio pipeline on success.

Example code

/*
Assume playbackStream is an AudioPlaybackStream object
*/

const getPresentedFrameCountAsyncTest = async () => {
    try {
      let presentedFrameCount = await playbackStream.current?.getPresentedFrameCountAsync();
      console.debug("getPresentedFrameCountAsync() : ", presentedFrameCount);
    } catch (error) {
      console.debug('Error: getPresentedFrameCountAsync(): ', error);
    }
}

getPresentedFrameCountAsyncTest();

getDuckingPolicyAsync()

Description

Query api for number of audio frames already presented and accepted by audio pipeline.

Return Value

Returns a promise (Int32) with the duckingPolicy for the current AudioPlaybackStream object

Example code

/*
Assume playbackStream is an AudioPlaybackStream object
*/

const getDuckingPolicyAsyncTest = async () => {
    try {
      const duckingPolicy = await playbackStream.current?.getDuckingPolicyAsync();
      console.debug("getDuckingPolicyAsync : ", duckingPolicy);
    } catch (err) {
      console.debug("getDuckingPolicyAsync() ERR: ", err);
    }
}

getDuckingPolicyAsyncTest();

duckVolumeAsync(mode, value, rampDuration)

Description

Api to duck/unduck the stream by specified db/percentage duck/unduck volume based on specific stream instance's volume.

Return Value

Returns a promise that resolves to an AudioStatus type (Int32).

Parameters

Parameter Name	Type	Required	Description
mode	DuckingMode	Yes	Specify the mode used to duck volume.
value	ArrayBuffer	Yes	For DuckingMode::DB, value indicates reduced dB from current stream volume (range: 0 to 144). For DuckingMode::PERCENTAGE, value indicates specific pecentage reduced from current stream volume (range: 0 to 100). value = 0 means the stream will be unducked to original stream volume
rampDuration	ArrayBuffer	Yes	Ramp duration in milliseconds to go from current volume to target volume.

Example code

/*
Assume playbackStream is an AudioPlaybackStream object
*/

const createAudioSourceInstance = async () => {
    const builder = new AudioPlaybackStreamBuilder();
    /*Other confingurations
    ...
    ...
    ...*/
    builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT); // Set policy to explicit
    const stream = await builder.buildAsync();
    playbackStream.current = stream;
}

const duckVolumeAsyncTest = async () => {
    try {
      /*Duck up to 50% in 500 milliseconds*/
      let duckStatus = await playbackStream.current?.duckVolumeAsync(DuckingMode.PERCENTAGE, 50, 500);
    } catch (err) {
      console.debug("duckVolumeAsync() ERR: ", err);
    }

    /*Assume there is a method which is going to play the audio associated to the current playbackstream*/

    playClipDucked();
}

createAudioSourceInstance();
duckVolumeAsyncTest();

setVolumeAsync(gain)

Description

Set individual stream volume by absolute gain in percentage.set gain of individual stream; It will be multiplied on stream volume.

Return Value

Returns a promise (Int32) with the duckingPolicy for the current AudioPlaybackStream object

Parameters

Parameter Name	Type	Required	Description
gain	Int32	Yes	Gain applied on volume of current stream type.

Example code

/*
Assume playbackStream is an AudioPlaybackStream object
*/

const createAudioSourceInstance = async () => {
    const builder = new AudioPlaybackStreamBuilder();
    /*Other confingurations
    ...
    ...
    ...*/
    builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT);
    const stream = await builder.buildAsync();
    playbackStream.current = stream;
}

const setVolumeAsyncTest = async () => {
    try {
      let setVolumeStatus = await playbackStream.current?.setVolumeAsync(70);
    } catch (err) {
      console.debug("setVolumeAsync() ERR: ", err);
    }

    /*Assume there is a method which is going to play the audio associated to the current playbackstream*/

    playClip();
}

createAudioSourceInstance();
setVolumeAsyncTest();

getVolumeAsync()

Description

Set individual stream volume by absolute gain in percentage.set gain of individual stream; It will be multiplied on stream volume.

Return Value

Returns a promise (Int32) with the duckingPolicy for the current AudioPlaybackStream object

Parameters

| Parameter Name | Type | Required | Description | | ————– | —- | ——– | ———– |

Example code

/*
Assume playbackStream is an AudioPlaybackStream object
*/

const createAudioSourceInstance = async () => {
    const builder = new AudioPlaybackStreamBuilder();
    /*Other confingurations
    ...
    ...
    ...*/
    builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT);
    const stream = await builder.buildAsync();
    playbackStream.current = stream;
}

const setVolumeAsyncTest = async () => {
    try {
      let setVolumeStatus = await playbackStream.current?.setVolumeAsync(70);
    } catch (err) {
      console.debug("setVolumeAsync() ERR: ", err);
    }
}

const getVolumeAsyncTest = async () => {
    try {
      let currentStreamVolume = await playbackStream.current?.getVolumeAsync();
      console.log("getVolumeAsync() Current stream volume: ", currentStreamVolume);
    } catch (err) {
      console.debug("getVolumeAsync() ERR: ", err);
    }
}

createAudioSourceInstance();
setVolumeAsyncTest();
getVolumeAsyncTest();

---

Last updated: Oct 02, 2025