Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

Ring

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

AudioPlaybackStream

音频播放流允许控制播放流，例如暂停、刷新和写入播放缓冲区。

所需权限

API需要特定权限才能执行某些操作：

[[needs.privilege]]
id = "com.amazon.audio.privilege.settings.control"

API还需要声明系统音频服务：

[wants]
[[wants.service]]
id = "com.amazon.audio.stream"
[[wants.service]]
id = "com.amazon.audio.control"

使用的类型

请参阅

构造函数

new AudioPlaybackStream()

new AudioPlaybackStream(id): AudioPlaybackStream

参数

id

number

内部流标识符

返回值

AudioPlaybackStream

属性

streamId

streamId: number

方法

duckVolumeAsync()

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

调整用于放弃的流音量。仅在使用EXPLICIT放弃策略时有效。

参数

mode

Int32

(0) 或 (1)

值

Int32

音量的减小量：

对于DB：减小0-144dB
对于PERCENTAGE：减小0-100%

值 = 0表示流将降至原始流音量

rampDurationMs

Int32

从当前音量到目标音量所需的时间（以毫秒为单位）

返回值

Promise<Int32>

Promise 解析为如下的Promise：

(0)：音量放弃成功
(-3)：流未初始化
(-2)：参数无效
(-8)：错误的放弃原则

示例

/*
假设playbackStream是一个AudioPlaybackStream对象
*\/

const createAudioSourceInstance = async () => {
    const builder = new AudioPlaybackStreamBuilder();
    /* 其他配置
    ...
    ...
    ...*\/
    builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT); // 将策略设置为显式
    const stream = await builder.buildAsync();
    playbackStream.current = stream;
}

const duckVolumeAsyncTest = async () => {
    try {
      /*在500毫秒内最多降低50%*\/
      let duckStatus = await playbackStream.current?.duckVolumeAsync(DuckingMode.PERCENTAGE, 50, 500);
    } catch (err) {
      console.debug("duckVolumeAsync() ERR: ", err);
    }

    /*假设有一种方法可以播放与当前播放流相关的音频*\/

    playClipDucked();
}

createAudioSourceInstance();
duckVolumeAsyncTest();

flushAsync()

flushAsync(): Promise<AudioStatus>

在不更改播放状态的情况下清空所有缓冲的数据。

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

(0)：成功清空
(-3)：流未初始化
(-8)：播放时无法清空
(-5)：服务器通信错误

示例

/*
刷新音频播放流，并在解析Promise之后
将返回的AudioStatus类型存储在status中

假设playbackStream是一个AudioPlaybackStream对象
*\/

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

getAudioAttributesAsync()

getAudioAttributesAsync(): Promise<AudioAttributes>

检索播放流的当前音频属性。

返回值

Promise<AudioAttributes>

Promise 解析为含有以下内容的对象的Promise：

contentType：正在播放的内容类型
usage: 流的使用类别
flags: 当前行为标记，或者通过以下项拒绝：
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取播放流的音频属性，并在解析Promise之后
将其存储在attributes中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const attributes = playbackStream.getAudioAttributesAsync()
.then((attributes) => {return attributes;}).catch((error) => console.log(error));

getAudioConfigAsync()

getAudioConfigAsync(): Promise<AudioConfig>

检索播放流的当前音频配置。

返回值

Promise<AudioConfig>

Promise 解析为含有以下内容的对象的Promise：

sampleRate：当前采样率（单位：Hz）
channelMask：当前频道配置
format：当前样本格式，或者通过以下项拒绝：
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取播放流的音频配置，并在解析Promise之后
将其存储在config中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const config = playbackStream.getAudioConfigAsync()
.then((config) => {return config;}).catch((error) => console.log(error));

getAudioEffectSessionIdAsync()

getAudioEffectSessionIdAsync(): Promise<Int32>

获取与流相关的自定义音效会话ID。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：效果会话ID
(-3)：流未初始化
(-2)：未分配效果会话

getAudioFocusSessionIdAsync()

getAudioFocusSessionIdAsync(): Promise<Int32>

获取与流相关的音频焦点会话ID。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：焦点会话ID
(-3)：流未初始化
(-2)：未分配焦点会话

示例

/*
获取焦点会话，并在解析Promise之后将其存储在session_id中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const session_id = playbackStream.getAudioFocusSessionIdAsync()
.then((id) => {return id;}).catch((error) => console.log(error));

getBufferCountAsync()

getBufferCountAsync(): Promise<Int32>

获取为此流配置的缓冲区数量。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：缓冲区数量
(-3)：流未初始化
(-5)：服务器通信错误

getChannelCountAsync()

getChannelCountAsync(): Promise<Int32>

获取播放流的频道数。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：频道数量
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取播放流的频道数，并在解析Promise之后
将其存储在channel_count中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const channel_count = playbackStream.getChannelCountAsync()
.then((count) => {return count;}).catch((error) => console.log(error));

getDuckingPolicyAsync()

getDuckingPolicyAsync(): Promise<Int32>

获取流的当前放弃策略。

返回值

Promise<Int32>

Promise 解析为如下的 Promise：

(0)：系统会自动处理放弃
(1)：应用必须处理放弃

或显示以下拒绝结果：

(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
假设playbackStream是一个AudioPlaybackStream对象
*\/

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>

获取为此流配置的每个缓冲区的帧数。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：每个缓冲区的帧数
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取原生缓冲区中的帧数，并在解析Promise之后
将其存储在buffer_frames中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const buffer_frames = playbackStream.getFramesPerBufferAsync()
.then((frames) => {return frames;}).catch((error) => console.log(error));

getLatencyInMsAsync()

getLatencyInMsAsync(): Promise<Int32>

以毫秒为单位获取播放流的当前延迟。这包括缓冲和硬件延迟。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：延迟（单位：毫秒）
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取以ms为单位的延迟时间，并在解析promise之后将其存储在延迟时间中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const latency = playbackStream.getLatencyInMsAsync()
.then((latency) => {return latency;}).catch((error) => console.log(error));

getMajorVersion()

static getMajorVersion(): number

获取AudioRecordStream实现的主版本号。可用于进行版本检查。

返回值

number

number 主版本号

getMinorVersion()

static getMinorVersion(): number

获取AudioRecordStream实现的次版本号。可用于进行版本检查。

返回值

number

number 次版本号

getNumBytesInPipelineAsync()

getNumBytesInPipelineAsync(): Promise<Int32>

获取当前播放管道中等待播放的字节数。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：管道中的字节数
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取管道中的字节数，并在解析promise之后
将其存储在pipeline_bytes中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const pipeline_bytes = playbackStream.getNumBytesInPipelineAsync()
.then((bytes) => {return bytes;}).catch((error) => console.log(error));

getNumBytesOfNativeBufferAsync()

getNumBytesOfNativeBufferAsync(): Promise<Int32>

获取用于播放的原生缓冲区的大小。这表示可以排队等待播放的最大数据量。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：缓冲区大小（单位：字节）
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取原生缓冲区中的字节数，并在解析promise之后
将其存储在buffer_bytes中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const buffer_bytes = playbackStream.getNumBytesOfNativeBufferAsync()
.then((bytes) => {return bytes;}).catch((error) => console.log(error));

getPatchVersion()

static getPatchVersion(): number

获取AudioRecordStream实现的补丁版本号。可用于进行版本检查。

返回值

number

number 补丁版本号

getPresentedFrameCountAsync()

getPresentedFrameCountAsync(): Promise<Int32>

获取已播放的总帧数。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：成功时播放到音频管道的帧数。
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
假设playbackStream是一个AudioPlaybackStream对象
*\/

const getPresentedFrameCountAsyncTest = async () => {
    try {
      let presentedFrameCount = await playbackStream.current?.getPresentedFrameCountAsync();
      console.debug("getPresentedFrameCountAsync() : ", presentedFrameCount);
    } catch (error) {
      console.debug('错误：getPresentedFrameCountAsync(): ', error);
    }
}

getPresentedFrameCountAsyncTest();

getSampleRateAsync()

getSampleRateAsync(): Promise<Int32>

获取播放流的采样率。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：采样率（单位：Hz）
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取播放流的采样率，并在解析Promise之后
将其存储在sample_rate中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const sample_rate= playbackStream.getSampleRateAsync()
.then((rate) => {return rate;}).catch((error) => console.log(error));

getSampleSizeAsync()

getSampleSizeAsync(): Promise<Int32>

获取播放流的样本大小（单位：位）。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：以位为单位的样本大小（例如16、24、32）
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取播放流的样本大小，并在解析Promise之后
将其存储在sample_size中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const sample_size = playbackStream.getSampleSizeAsync()
.then((sample_size) => {return sample_size;}).catch((error) => console.log(error));

getUnderrunCountAsync()

getUnderrunCountAsync(): Promise<Int32>

获取欠载出现次数的总数。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：流生命周期内发生的欠载次数。
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
假设playbackStream是一个AudioPlaybackStream对象
*\/

const getUnderrunCountAsyncTest = async () => {
    try {
      let underRunCount = await playbackStream.current?.getUnderrunCountAsync();
      console.debug("getUnderrunCountAsync() : ", underRunCount);
    } catch (error) {
      console.debug('错误：getUnderrunCountAsync(): ', error);
    }
}

getUnderrunCountAsyncTest();

getUnderrunSizeAsync()

getUnderrunSizeAsync(): Promise<Int32>

获取欠载大小（以帧为单位）。当播放缓冲区变为空时，会出现欠载。

如果客户端设置了缓冲区欠载阈值且播放缓冲区处于欠载状态，此API将返回缓冲区大小和阈值之间的差值。

否则，此API将返回0。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

正值：缓冲区大小和欠载阈值之间的帧数差异。帧值向上舍入。
0：没有欠载
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
假设playbackStream是一个AudioPlaybackStream对象
*\/

const getUnderrunSizeAsyncTest = async () => {
    try {
      let underRunSize = await playbackStream.current?.getUnderrunSizeAsync();
      console.debug("getUnderrunSizeAsync() : ", underRunSize);
    } catch (error) {
      console.debug('错误：getUnderrunSizeAsync(): ', error);
    }
}

getUnderrunSizeAsyncTest();

getVolumeAsync()

getVolumeAsync(): Promise<Int32>

获取流的当前音量水平。

返回值

Promise<Int32>

Promise 解析为如下的Promise：

0-100：当前音量水平
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
假设playbackStream是一个AudioPlaybackStream对象
*\/

const createAudioSourceInstance = async () => {
    const builder = new AudioPlaybackStreamBuilder();
    /* 其他配置
    ...
    ...
    ...*\/
    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() 流的当前音量：", currentStreamVolume);
    } catch (err) {
      console.debug("getVolumeAsync() ERR: ", err);
    }
}

createAudioSourceInstance();
setVolumeAsyncTest();
getVolumeAsyncTest();

initCheckAsync()

initCheckAsync(): Promise<AudioStatus>

验证播放流是否已正确初始化。必须在使用其他方法之前调用，以确保流准备就绪。

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

(0)：流已正确初始化
(-3)：流未初始化
(-5)：服务器通信错误

示例

/*
获取音频播放流的状态并将其存储在status中

假设playbackStream是一个AudioPlaybackStream对象
*\/
const status = playbackStream.initCheckAsync()
.then((status) => {return status;}).catch((error) => console.log(error));

pauseAsync()

pauseAsync(): Promise<AudioStatus>

暂停流的播放。缓冲区中的数据会被保留，可以使用startAsync恢复播放。

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

(0)：成功暂停
(-3)：流未初始化
(-8)：流已经暂停
(-5)：服务器通信错误

示例

/*
暂停音频播放流，并在解析Promise之后
将返回的AudioStatus类型存储在status中

假设playbackStream是一个AudioPlaybackStream对象
*\/

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

queryMinimumBufferInfoAsync()

queryMinimumBufferInfoAsync(): Promise<Object>

获取最小缓冲区信息

返回值

Promise<Object>

Promise 包含字段minFramesPerBuffer和minBufferCount的对象

registerEventObserverAsync()

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

注册一个回调来接收播放流事件。一次只能注册一个回调。

参数

callback

(value: any) => void

接收事件的函数。事件包括：

(0)：流失败
(1)：流已从故障中恢复
(2)：播放已停止
(3)：流静音状态已更改
(4)：出现缓冲区欠载的情况

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

(0)：回调注册成功
(-3)：流未初始化
(-2)：回调无效
(-4)：回调已注册

示例

/*
创建一个函数并将其注册到记录Event Observer中，
以便在播放发生更改时执行此函数，并在解析Promise之后
将返回的AudioStatus类型存储在status中

假设playbackStream是一个AudioPlaybackStream对象
*\/

const playbackStreamEventHandler = (event: any) => {
    console.debug('已接收playbackStreamEventHandler事件 ->', event);
    switch (event.playbackStreamEvent) {
      case AudioPlaybackEvent.DIED:
        console.debug('播放流已终止。流ID：', playbackStream.current);
        break;
      case AudioPlaybackEvent.RECOVERED:
        console.debug('播放流已恢复。流ID：', playbackStream.current);
        break;
      case AudioPlaybackEvent.STOPPED:
        console.debug('播放流已停止。流ID：', playbackStream.current);
        break;
      case AudioPlaybackEvent.MUTE_STATE_UPDATE:
        console.debug('播放流静音状态已更改。流ID：', playbackStream.current);
        console.debug('MuteState: ', event.muteState);
        break;
      case AudioPlaybackEvent.FRAME_UNDERRUN:
        console.debug('发生了播放流欠载。流ID：', playbackStream.current);
        console.debug('欠载发生次数：', 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>

按百分比形式的绝对增益设置单个流的音量。设置单个流的增益；它将乘以流音量。这与系统音量无关。

参数

gain

Int32

音量水平 (0-100)

返回值

Promise<Int32>

Promise 解析为如下的Promise：

(0)：音量设置成功
(-3)：流未初始化
(-2)：增益值无效
(-5)：服务器通信错误

示例

/*
假设playbackStream是一个AudioPlaybackStream对象
*\/

const createAudioSourceInstance = async () => {
    const builder = new AudioPlaybackStreamBuilder();
    /* 其他配置
    ...
    ...
    ...*\/
    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);
    }

    /*假设有一种方法可以播放与当前播放流相关的音频*\/

    playClip();
}

createAudioSourceInstance();
setVolumeAsyncTest();

setVolumeWithFadeAsync()

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

使用渐变效果设置流的音量。

参数

volume

Int32

目标音量 (0-100)

duration

Int32

持续时间（单位：毫秒）

fadeType

AudioFadeType

渐变曲线类型

返回值

Promise<Int32>

Promise 发起fade时解析的Promise

(0)：音量设置成功
(-3)：流未初始化
(-2)：增益值无效
(-5)：服务器通信错误

startAsync()

startAsync(): Promise<AudioStatus>

开始或恢复流的播放。

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

(0)：成功启动
(-3)：流未初始化
(-8)：流已经在播放
(-5)：服务器通信错误

示例

/*
开始音频播放流，并在解析Promise之后
将返回的AudioStatus类型存储在status中

假设playbackStream是一个AudioPlaybackStream对象
*\/

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

stopAsync()

stopAsync(): Promise<AudioStatus>

停止播放并清除所有缓冲区。与pauseAsync不同，这会丢弃所有缓冲的数据。

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

(0)：成功停止
(-3)：流未初始化
(-8)：流已经停止
(-5)：服务器通信错误

示例

/*
停止音频播放流，并在解析Promise之后
将返回的AudioStatus类型存储在status中

假设playbackStream是一个AudioPlaybackStream对象
*\/

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

unregisterEventObserverAsync()

unregisterEventObserverAsync(): Promise<AudioStatus>

取消注册之前注册的事件回调。

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

(0)：回调注销成功
(-3)：流未初始化
(-2)：未注册任何回调

示例

/*
取消注册回调函数，并在解析promise后
将返回的AudioStatus类型存储在中

假设playbackStream是一个AudioPlaybackStream对象
*\/

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

writeAsync()

writeAsync(buffer: ArrayBuffer): Promise<AudioStatus>

将音频数据写入播放缓冲区。

参数

buffer

ArrayBuffer

要写入的音频数据

返回值

Promise<AudioStatus>

Promise 解析为如下的Promise：

正值：写入的字节数
(-3)：流未初始化
(-2)：缓冲区无效
(-8)：写入操作失败
(-6)：缓冲区已满
(-5)：服务器通信错误

示例

/*
写入播放缓冲区，并在解析Promise之后
将返回的AudioStatus类型存储在status中

假设缓冲区是一个Uint8Array，其中包含要写入缓冲区的字节

假设playbackStream是一个AudioPlaybackStream对象
*\/

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

Last updated: 2026年7月22日