AudioPlaybackStream

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

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

• *

Constructors

new AudioPlaybackStream()

new AudioPlaybackStream(id): AudioPlaybackStream

Parameters

id

number

Internal stream identifier

Returns

AudioPlaybackStream

Properties

streamId

streamId: number

Methods

duckVolumeAsync()

duckVolumeAsync(mode: Int32, value: Int32, rampDurationMs: Int32): Promise<Int32>

Adjusts the volume of the stream for ducking purposes. Only effective when using EXPLICIT ducking policy.

Parameters

mode

Int32

(0) or (1)

value

Int32

Amount to reduce volume:

• For DB: 0-144 dB reduction
• For PERCENTAGE: 0-100% reduction

value = 0 means the stream will be unducked to original stream volume

rampDurationMs

Int32

Time in milliseconds to go from current volume to target volume

Returns

Promise<Int32>

Promise A promise that resolves to:

• (0): Volume ducked successfully
• (-3): Stream not initialized
• (-2): Invalid parameters
• (-8): Wrong ducking policy

Examples

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

---

flushAsync()

flushAsync(): Promise<AudioStatus>

Flushes all buffered data without changing the playback state.

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• (0): Successfully flushed
• (-3): Stream not initialized
• (-8): Cannot flush while playing
• (-5): Server communication error

Examples

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

---

getAudioAttributesAsync()

getAudioAttributesAsync(): Promise<AudioAttributes>

Retrieves the current audio attributes of the playback stream.

Returns

Promise<AudioAttributes>

Promise A promise that resolves to an object containing:

• contentType: Type of content being played
• usage: Usage category of the stream
• flags: Current behavior flags Or rejects with:
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getAudioConfigAsync()

getAudioConfigAsync(): Promise<AudioConfig>

Retrieves the current audio configuration of the playback stream.

Returns

Promise<AudioConfig>

Promise A promise that resolves to an object containing:

• sampleRate: Current sample rate in Hz
• channelMask: Current channel configuration
• format: Current sample format Or rejects with:
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getAudioEffectSessionIdAsync()

getAudioEffectSessionIdAsync(): Promise<Int32>

Gets the custom audio effect session ID associated with this stream.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: The effect session ID
• (-3): Stream not initialized
• (-2): No effect session assigned

---

getAudioFocusSessionIdAsync()

getAudioFocusSessionIdAsync(): Promise<Int32>

Gets the audio focus session ID associated with this stream.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: The focus session ID
• (-3): Stream not initialized
• (-2): No focus session assigned

Examples

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

---

getBufferCountAsync()

getBufferCountAsync(): Promise<Int32>

Gets the number of buffers configured for this stream.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Number of buffers
• (-3): Stream not initialized
• (-5): Server communication error

---

getChannelCountAsync()

getChannelCountAsync(): Promise<Int32>

Gets the channel count of the playback stream.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Number of channels
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getDuckingPolicyAsync()

getDuckingPolicyAsync(): Promise<Int32>

Gets the current ducking policy of the stream.

Returns

Promise<Int32>

Promise A promise that resolves to :

• (0): System handles duckicking automatically
• (1): Application must handle ducking

Or rejects with:

• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getFramesPerBufferAsync()

getFramesPerBufferAsync(): Promise<Int32>

Gets the number of frames per buffer configured for this stream.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Frames per buffer
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getLatencyInMsAsync()

getLatencyInMsAsync(): Promise<Int32>

Gets the current latency of the playback stream in milliseconds. This includes both buffer and hardware latency.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Latency in milliseconds
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getMajorVersion()

static getMajorVersion(): number

Gets the major version number of the implementation. Can be used to make version checks.

Returns

number

number The major version number

---

getMinorVersion()

static getMinorVersion(): number

Gets the minor version number of the implementation. Can be used to make version checks.

Returns

number

number The minor version number

---

getNumBytesInPipelineAsync()

getNumBytesInPipelineAsync(): Promise<Int32>

Gets the number of bytes currently in the playback pipeline waiting to be played.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Number of bytes in pipeline
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

getNumBytesOfNativeBufferAsync(): Promise<Int32>

Gets the size of the native buffer used for playback. This represents the maximum amount of data that can be queued for playback.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Buffer size in bytes
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getPatchVersion()

static getPatchVersion(): number

Gets the patch version number of the implementation. Can be used to make version checks.

Returns

number

number The patch version number

---

getPresentedFrameCountAsync()

getPresentedFrameCountAsync(): Promise<Int32>

Gets the total number of frames that have been played.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Number of frames played to audio pipeline on success.
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getSampleRateAsync()

getSampleRateAsync(): Promise<Int32>

Gets the sample rate of the playback stream.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Sample rate in Hz
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getSampleSizeAsync()

getSampleSizeAsync(): Promise<Int32>

Gets the sample size in bits of the playback stream.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Sample size in bits (e.g., 16, 24, 32)
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getUnderrunCountAsync()

getUnderrunCountAsync(): Promise<Int32>

Gets the total number of underrun occurrences.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Number of underrun occurrences during stream lifetime.

• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getUnderrunSizeAsync()

getUnderrunSizeAsync(): Promise<Int32>

Gets the underrun size in frames. An underrun occurs when the playback buffer becomes empty.

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.

Returns

Promise<Int32>

Promise A promise that resolves to:

• Positive value: Difference in frames between buffer size and underrun threshold. Frame value is rounded up.

• 0: No underrun

• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

getVolumeAsync()

getVolumeAsync(): Promise<Int32>

Gets the stream's current volume level.

Returns

Promise<Int32>

Promise A promise that resolves to:

• 0-100: Current volume level
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

initCheckAsync()

initCheckAsync(): Promise<AudioStatus>

Verifies if the playback stream has been properly initialized. Must be called before using other methods to ensure the stream is ready.

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• (0): Stream is properly initialized
• (-3): Stream not initialized
• (-5): Server communication error

Examples

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

---

pauseAsync()

pauseAsync(): Promise<AudioStatus>

Pauses playback of the stream. Data in the buffer is retained and playback can be resumed with .

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• (0): Successfully paused
• (-3): Stream not initialized
• (-8): Stream already paused
• (-5): Server communication error

Examples

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

---

queryMinimumBufferInfoAsync()

queryMinimumBufferInfoAsync(): Promise<Object>

Get minimum buffer information

Returns

Promise<Object>

Promise object with fields minFramesPerBuffer and minBufferCount

---

registerEventObserverAsync()

registerEventObserverAsync(callback: (value: any) => void): Promise<AudioStatus>

Registers a callback to receive playback stream events. Only one callback can be registered at a time.

Parameters

callback

(value: any) => void

Function to receive events. Events include:

• (0): Stream has failed
• (1): Stream has recovered from failure
• (2): Playback has stopped
• (3): Stream mute state changed
• (4): Buffer underrun occurred

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• (0): Callback registered successfully
• (-3): Stream not initialized
• (-2): Invalid callback
• (-4): Callback already registered

Examples

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

---

setVolumeAsync()

setVolumeAsync(gain: Int32): Promise<Int32>

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

Parameters

gain

Int32

Volume level (0-100)

Returns

Promise<Int32>

Promise A promise that resolves to:

• (0): Volume set successfully
• (-3): Stream not initialized
• (-2): Invalid gain value
• (-5): Server communication error

Examples

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

---

setVolumeWithFadeAsync()

setVolumeWithFadeAsync(volume: Int32, duration: Int32, fadeType: AudioFadeType): Promise<Int32>

Sets the stream's volume with fade effect.

Parameters

volume

Int32

Target volume (0-100)

duration

Int32

Duration in milliseconds

fadeType

AudioFadeType

Fade curve type

Returns

Promise<Int32>

Promise A promise that resolves when fade is initiated

• (0): Volume set successfully
• (-3): Stream not initialized
• (-2): Invalid gain value
• (-5): Server communication error

---

startAsync()

startAsync(): Promise<AudioStatus>

Starts or resumes playback of the stream.

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• (0): Successfully started
• (-3): Stream not initialized
• (-8): Stream already playing
• (-5): Server communication error

Examples

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

stopAsync(): Promise<AudioStatus>

Stops playback and clears all buffers. Unlike , this discards any buffered data.

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• (0): Successfully stopped
• (-3): Stream not initialized
• (-8): Stream already stopped
• (-5): Server communication error

Examples

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

---

unregisterEventObserverAsync()

unregisterEventObserverAsync(): Promise<AudioStatus>

Unregister the previously registered event callback.

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• (0): Callback unregistered successfully
• (-3): Stream not initialized
• (-2): No callback was registered

Examples

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

writeAsync(buffer: ArrayBuffer): Promise<AudioStatus>

Writes audio data to the playback buffer.

Parameters

buffer

ArrayBuffer

Audio data to write

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• Positive value: Number of bytes written
• (-3): Stream not initialized
• (-2): Invalid buffer
• (-8): Write operation failed
• (-6): Buffer full
• (-5): Server communication error

Examples

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

---

Last updated: Jul 22, 2026