AudioPlaybackStreamBuilder

Audio Playback Stream Builder allows for the configuration, creation, and destruction of Audio Playback Streams.

Required services

The API 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 AudioPlaybackStreamBuilder()

new AudioPlaybackStreamBuilder(): AudioPlaybackStreamBuilder

Returns

AudioPlaybackStreamBuilder

Properties

args

args: Object = {}

Methods

buildAsync()

buildAsync(): Promise<AudioPlaybackStream>

Creates a new AudioPlaybackStream using the current builder configuration. Must call and before building.

Returns

Promise<AudioPlaybackStream>

Promise A promise that resolves to:

• New instance if successful

Or rejects with:

• STATUS_BAD_VALUE (-2): Missing required configuration
• STATUS_NO_INIT (-3): Audio system not initialized
• STATUS_NO_MEMORY (-1): Failed to allocate resources
• STATUS_DEAD_OBJECT (-5): Server communication error
• STATUS_INVALID_OPERATION (-8): Invalid configuration combination

Examples

/*
Returns a promise resolving to an AudioPlaybackStream object and stores it in
playbackStream
*\/
const builder = new AudioPlaybackStreamBuilder();
const playbackStream = builder.buildAsync()
.then((stream) => {return stream;}).catch((error) => console.log(error));

---

destroyAsync()

static destroyAsync(playbackStream: AudioPlaybackStream): Promise<AudioStatus>

Destroys an existing . This releases all resources associated with the stream. The stream object Must not be used after calling this method. Any ongoing playback will be stopped.

Parameters

playbackStream

AudioPlaybackStream

The stream to destroy

Returns

Promise<AudioStatus>

Promise A promise that resolves to:

• STATUS_NO_ERROR (0): Stream destroyed successfully
• STATUS_BAD_VALUE (-2): Invalid stream object
• STATUS_NO_INIT (-3): Audio system not initialized
• STATUS_INVALID_OPERATION (-8): Stream already destroyed

Examples

/*
Destroys playbackStream and returns and stores returned AudioStatus type in
status after promise resolves

Assume playbackStream is an AudioPlaybackStream object
*\/

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

---

reset()

reset(): void

Resets all builder configuration to default values.

Use this to reuse the builder for creating a different stream configuration.

Examples

/*
Resets audio playback builder configuration

Assume builder is a AudioPlaybackStreamBuilder object
*\/

builder.reset();

---

setAudioAttributes()

setAudioAttributes(attributes: AudioAttributes): void

Sets the audio attributes for the stream to be built. This must be called before . These attributes affect how the stream interacts with the audio focus system.

Parameters

attributes

AudioAttributes

Audio attributes object containing:

• contentType: Type of content from enum
• usage: Usage scenario from enum
• flags: Behavior flags from enum

Examples

/*
Sets audio attributes to what is specified in attributes
Any playback stream that is created by calling buildAysnc() will now have these audio
attributes
Assume builder is a AudioPlaybackStreamBuilder object
*\/
const attributes: AudioAttributes = {
    contentType: AudioContentType.CONTENT_TYPE_NONE,
    usage: AudioUsageType.USAGE_NONE,
    flags: AudioFlags.FLAG_NONE
};

builder.setAudioAttributes(attributes);

---

setAudioConfig()

setAudioConfig(config: AudioConfig): void

Sets the audio configuration for the stream to be built. This must be called before .

Parameters

config

AudioConfig

Audio configuration object containing:

• sampleRate: Sample rate in Hz from enum
• channelMask: Channel configuration from enum
• format: Sample format from enum

Examples

/*
Sets audio playback configuration to what is specified in config
Any playback stream that is created by calling buildAysnc() will now have this audio
configuration

Assume builder is a AudioPlaybackStreamBuilder object
*\/
const config: AudioConfig = {
    sampleRate: AudioSampleRate.SAMPLE_RATE_8_KHZ,
    channelMask: AudioChannelMask.CHANNEL_STEREO,
    format: AudioSampleFormat.FORMAT_PCM_16_BIT,
};

builder.setAudioConfig(config);

---

setAudioEffectSessionId()

setAudioEffectSessionId(effectSessionId: Int32): void

Sets custom audio effect session ID for the stream. This allows applying custom audio effects to this stream.

Parameters

effectSessionId

Int32

Effect session ID obtained from:

---

setAudioFocusSessionId()

setAudioFocusSessionId(focusSessionId: Int32): void

Sets the audio focus session ID for the stream. This associates the stream with a specific focus session for focus management.

Parameters

focusSessionId

Int32

Focus session ID obtained from:

• An existing

Examples

/*
Sets session id to 1

Assume builder is a AudioPlaybackStreamBuilder object
*\/

builder.setAudioFocusSessionId(session.getAudioSessionId());

Note: The above example assumes the session is an AudioFocusSession object.

---

setBufferCount()

setBufferCount(bufferCount: Int32): void

Sets the number of buffers to use for the stream. More buffers increase latency but provide better protection against underruns.

Parameters

bufferCount

Int32

Number of buffers. Must be greater than 0. Typical values: 2, 3, 4

---

setDuckingPolicy()

setDuckingPolicy(duckPolicy: StreamDuckingPolicy): void

Sets the ducking policy for the stream. This determines how volume reduction is handled when audio focus is ducked.

If ducking policy equals to StreamDuckingPolicy::EXPLICIT, the app needs to call duckVolume API to duck the stream volume, otherwise the volume won't be changed; If set to StreamDuckingPolicy::SYSTEM (by default), the stream volume ducking is handled by the system.

Parameters

duckPolicy

StreamDuckingPolicy

The ducking policy:

• SYSTEM (0): System handles volume reduction automatically
• EXPLICIT (1): Application must handle volume reduction using calls

Examples

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

createAudioSourceInstance();

---

setFramesPerBuffer()

setFramesPerBuffer(framesPerBuffer: Int32): void

Sets the number of frames per buffer for the stream. This is used to determine the buffer size per slot in the shared memory buffer queue. Larger values increase latency but improve power efficiency. Smaller values decrease latency but may cause underruns.

Parameters

framesPerBuffer

Int32

Number of frames per buffer. Must be greater than 0. Typical values: 256, 512, 1024, 2048

Examples

/*
Sets frames per buffer for the builder

Assume builder is a AudioPlaybackStreamBuilder object
*\/const framesPerBuffer = 200;
builder.setFramesPerBuffer(framesPerBuffer);

---

setUnderrunThreshold()

setUnderrunThreshold(framesThreshold: Int32): void

Sets the threshold for reporting buffer underruns. An underrun occurs when the playback buffer becomes empty.

Parameters

framesThreshold

Int32

Number of frames threshold. When available frames drops below this value, an underrun event will be triggered. Must be greater than 0.

Examples

const createAudioSourceInstance = async () => {
    const builder = new AudioPlaybackStreamBuilder();
    /*Other confingurations
    ...
    ...
    ...*\/
    builder.setUnderrunThreshold(3); // Set threshold to 3
    const stream = await builder.buildAsync();
    playbackStream.current = stream;
}

createAudioSourceInstance();

---

Last updated: Jul 22, 2026