AudioPlaybackStreamBuilder - Amazon Vega Docs

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

​Required services

​Types Used

​Constructors

​new AudioPlaybackStreamBuilder()

​Returns

​Properties

​args

​Methods

​buildAsync()

​Returns

​Examples

​destroyAsync()

​Parameters

playbackStream

​Returns

​Examples

​reset()

​Examples

​setAudioAttributes()

​Parameters

attributes

​Examples

​setAudioConfig()

​Parameters

config

​Examples

​setAudioEffectSessionId()

​Parameters

effectSessionId

​setAudioFocusSessionId()

​Parameters

focusSessionId

​Examples

​setBufferCount()

​Parameters

bufferCount

​setDuckingPolicy()

​Parameters

duckPolicy

​Examples

​setFramesPerBuffer()

​Parameters

framesPerBuffer

​Examples

​setUnderrunThreshold()

​Parameters

framesThreshold

​Examples

Required services

Types Used

Constructors

new AudioPlaybackStreamBuilder()

Returns

Properties

args

Methods

buildAsync()

Returns

Examples

destroyAsync()

Parameters

Returns

Examples

reset()

Examples

setAudioAttributes()

Parameters

Examples

setAudioConfig()

Parameters

Examples

setAudioEffectSessionId()

Parameters

setAudioFocusSessionId()

Parameters

Examples

setBufferCount()

Parameters

setDuckingPolicy()

Parameters

Examples

setFramesPerBuffer()

Parameters

Examples

setUnderrunThreshold()

Parameters

Examples