Audio Playback Stream Builder
Audio Playback Stream Builder allows for the configuration, creation, and destruction of Audio Playback Streams.
- TOC
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 Audio core types
AudioStatusAudioAttributesAudioContentTypeAudioUsageTypeAudioFlagsAudioConfigAudioSampleRateAudioSampleFormatAudioSource
Static Methods
AudioPlaybackStreamBuilder.destroyAsync(playbackStream)
Description
Destroys an AudioPlaybackStream object specified in the parameters.
Return Value
Returns a promise that resolves to an AudioStatus type.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| playbackStream | AudioPlaybackStream | Yes | AudioPlaybackStream to be destroyed |
Example code
/*
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));
Methods
buildAsync()
Description
Creates a new AudioPlaybackStream object.
Return Value
Returns a promise that resolves to an AudioPlaybackStream object.
Example code
/*
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));
setAudioConfig(config)
Description
Sets the audio configuration for the playback stream.
Return Value
No return value.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| config | AudioConfig | Yes | Audio configuration details for the playback stream |
Example code
/*
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);
reset()
Description
Resets audio playback builder configuration.
Return Value
No return value.
Example code
/*
Resets audio playback builder configuration
Assume builder is a AudioPlaybackStreamBuilder object
*/
builder.reset();
setAudioAttributes(attributes)
Description
Sets audio playback builder attributes.
Return Value
No return value.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| attributes | AudioAttributes | Yes | Audio attributes of the playback stream builder |
Example code
/*
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);
setFramesPerBuffer(framesPerBuffer)
Description
Configures buffer the capacity for frame count in the shared memory buffer queue. This is used to determine the buffer size per slot in the shared memory buffer queue.
Return Value
No return value.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| framesPerBuffer | Int32 | Yes | Represents the frames per buffer for the builder |
Example code
/*
Sets frames per buffer for the builder
Assume builder is a AudioPlaybackStreamBuilder object
*/const framesPerBuffer = 200;
builder.setFramesPerBuffer(framesPerBuffer);
setAudioFocusSessionId(focusSessionId)
Description
Sets the audio focus session id for the audio playback builder. The focus session id is obtained by creating an AudioFocusSession object and accessing it directly.
Return Value
No return value.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| focusSessionId | Int32 | Yes | Represents the audio focus session id for the builder |
Example code
/*
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.
setUnderrunThreshold(framesThreshold)
Description
Configure when audio server will report buffer underruns back to client.
Return Value
No return value.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| framesThreshold | Int32 | Yes | Frame threshold |
Example code
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();
setDuckingPolicy(duckPolicy)
Description
Used to specify whether using explicitly ducking by app or using automatic ducking by system.
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.
Return Value
No return value.
Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| duckPolicy | StreamDuckingPolicy | Yes | Ducking mode, SYSTEM or EXPLICIT |
Example code
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();
Last updated: Oct 02, 2025
