AudioPlaybackStreamBuilder
音频播放流构建器允许配置、创建和销毁音频播放流。
所需服务
API需要声明系统音频服务：
[wants]
[[wants.service]]
id = "com.amazon.audio.stream"
[[wants.service]]
id = "com.amazon.audio.control"
使用的类型
请参阅
- *
构造函数
new AudioPlaybackStreamBuilder()
new AudioPlaybackStreamBuilder(): AudioPlaybackStreamBuilder
返回值
属性
args
args:
Object={}
方法
buildAsync()
buildAsync():
Promise<AudioPlaybackStream>
使用当前的构建器配置，新建AudioPlaybackStream。构建前务必调用setAudioConfig和setAudioSource。
返回值
Promise<AudioPlaybackStream>
Promise 解析为如下的Promise：
- 如果成功，则会创建新的AudioPlaybackStream实例
或显示以下拒绝结果：
STATUS_BAD_VALUE (-2)： 缺少必要配置STATUS_NO_INIT (-3)： 音频系统未初始化STATUS_NO_MEMORY (-1)： 资源分配失败STATUS_DEAD_OBJECT (-5)： 服务器通信错误STATUS_INVALID_OPERATION (-8)： 配置组合无效
示例
/*
返回解析为AudioPlaybackStream对象的Promise并将其存储在
playbackStream
*\/
const builder = new AudioPlaybackStreamBuilder();
const playbackStream = builder.buildAsync()
.then((stream) => {return stream;}).catch((error) => console.log(error));
destroyAsync()
staticdestroyAsync(playbackStream: AudioPlaybackStream):Promise<AudioStatus>
销毁现有的AudioRecordStream。这会释放所有与流相关的资源。调用此方法后不得使用流对象。任何正在进行的播放都将停止。
参数
playbackStream
要销毁的流
返回值
Promise<AudioStatus>
Promise 解析为如下的Promise：
STATUS_NO_ERROR (0)： 已成功销毁的流STATUS_BAD_VALUE (-2)： 流对象无效STATUS_NO_INIT (-3)： 音频系统未初始化STATUS_INVALID_OPERATION (-8)： 流已销毁
示例
/*
销毁playbackStream并返回，然后将返回的AudioStatus类型
存储在状态中
假设playbackStream是一个AudioPlaybackStream对象
*\/
const status = AudioPlaybackStreamBuilder.destroyAsync(playbackStream)
.then((status) => {return status;}).catch((error) => console.log(error));
reset()
reset():
void
重置所有构建器配置并设为默认值。
借此复用构建器，创建不同的流配置。
示例
/*
重置音频播放构建器配置
假设构建器是一个AudioPlaybackStreamBuilder对象
*\/
builder.reset();
setAudioAttributes()
setAudioAttributes(attributes: AudioAttributes):
void
为要构建的流设置音频属性。必须在buildAsync之前调用。这些属性会影响直播与音频焦点系统的交互方式。
参数
attributes
音频属性对象包含以下项。
- contentType： 来自types/AudioCoreClientTypes.AudioContentType枚举的内容类型
- usage: 来自types/AudioCoreClientTypes.AudioUsageType枚举的使用场景
- flags: 来自types/AudioCoreClientTypes.AudioFlags枚举的行为标记
示例
/*
将音频属性设置为属性中指定的内容
通过调用buildAysnc()创建的任何播放流现在都将包含这些音频
attributes
假设构建器是一个AudioPlaybackStreamBuilder对象
*\/
const attributes: AudioAttributes = {
contentType： AudioContentType.CONTENT_TYPE_NONE,
usage: AudioUsageType.USAGE_NONE,
flags: AudioFlags.FLAG_NONE
};
builder.setAudioAttributes(attributes);
setAudioConfig()
setAudioConfig(config: AudioConfig):
void
为要构建的流设置音频配置。必须在buildAsync之前调用。
参数
config
音频配置对象包含：
sampleRate： 来自types/AudioCoreClientTypes.AudioSampleRate枚举的采样率（单位：Hz）channelMask： 来自types/AudioCoreClientTypes.AudioChannelMask枚举的频道配置format： 来自types/AudioCoreClientTypes.AudioSampleFormat枚举的采样格式
示例
/*
将音频播放配置设置为配置中指定的内容
通过调用buildAysnc()创建的任何播放流现在都将包含此音频
configuration
假设构建器是一个AudioPlaybackStreamBuilder对象
*\/
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
为流设置自定义音效会话ID。这允许对该流应用自定义音频效果。
参数
effectSessionId
Int32
效果会话ID获取自：
setAudioFocusSessionId()
setAudioFocusSessionId(focusSessionId:
Int32):void
设置流的音频焦点会话ID。这会将流与特定的焦点会话关联，以进行焦点管理。
参数
focusSessionId
Int32
焦点会话ID获取自：
- 现有
示例
/*
将会话ID设置为1
假设构建器是一个AudioPlaybackStreamBuilder对象
*\/
builder.setAudioFocusSessionId(session.getAudioSessionId());
注意： 上面的示例假设会话是一个AudioFocusSession object。
setBufferCount()
setBufferCount(bufferCount:
Int32):void
设置用于流的缓冲区数量。更多的缓冲区会增加延迟，但可以更好地防止欠载。
参数
bufferCount
Int32
缓冲区数量。必须大于0。典型值： 2, 3, 4
setDuckingPolicy()
setDuckingPolicy(duckPolicy: StreamDuckingPolicy):
void
为流设置放弃策略。这决定了放弃音频焦点时处理音量减小的方式。
如果放弃策略等于StreamDuckingPolicy::EXPLICIT，则应用需要调用duckVolume API来放弃流音量，否则音量将无法更改；如果设置为StreamDuckingPolicy::SYSTEM（默认设置），则流音量放弃由系统处理。
参数
duckPolicy
放弃策略：
SYSTEM (0)： 系统自动处理音量减小问题EXPLICIT (1)： 应用程序必须使用AudioPlaybackStream.duckVolumeAsync调用来处理音量减小问题
示例
const createAudioSourceInstance = async () => {
const builder = new AudioPlaybackStreamBuilder();
/* 其他配置
...
...
...*\/
builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT); // 将策略设置为显式
const stream = await builder.buildAsync();
playbackStream.current = stream;
}
createAudioSourceInstance();
setFramesPerBuffer()
setFramesPerBuffer(framesPerBuffer:
Int32):void
设置流中每个缓冲区的帧数。这用于确定共享内存缓冲区队列中每个插槽的缓冲区大小。值越大，延迟越大，但能效越高。值越小，延迟越小，但可能导致欠载。
参数
framesPerBuffer
Int32
每个缓冲区的帧数。必须大于0。典型值： 256、512、1024、2048
示例
/*
为构建器设置每个缓冲区的帧数
假设构建器是一个AudioPlaybackStreamBuilder对象
*\/const framesPerBuffer = 200;
builder.setFramesPerBuffer(framesPerBuffer);
setUnderrunThreshold()
setUnderrunThreshold(framesThreshold:
Int32):void
设置报告缓冲区欠载的阈值。当播放缓冲区变为空时，会出现欠载。
参数
framesThreshold
Int32
帧数阈值。当可用帧数降至该值以下时，将触发欠载事件。必须大于0。
示例
const createAudioSourceInstance = async () => {
const builder = new AudioPlaybackStreamBuilder();
/* 其他配置
...
...
...*\/
builder.setUnderrunThreshold(3); // 将阈值设置为3
const stream = await builder.buildAsync();
playbackStream.current = stream;
}
createAudioSourceInstance();
Last updated: 2026年7月22日
