Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
AWS
文档
Support
Contact Us
My Cases

Console

as

新手入门
设计和开发
应用发布
参考
支持

音频播放流

音频播放流

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

  • TOC

所需权限

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"

使用的类型

请参阅音频核心类型

  • AudioStatus
  • AudioAttributes
  • AudioConfig
  • AudioPlaybackEvent
  • AudioVolumeType
  • StreamDuckingPolicy
  • DuckingMode

方法

initCheckAsync()

描述

检查播放流是否已初始化。

返回值

返回解析为AudioStatus类型的promise。

代码示例

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

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

getAudioConfigAsync()

描述

获取播放流的音频配置。

返回值

返回解析为AudioConfig对象的Promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getAudioAttributesAsync()

描述

获取播放流的音频属性。

返回值

返回解析为AudioAttributes对象的Promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getSampleRateAsync()

描述

获取播放流的采样率。

返回值

返回解析为Int32（代表采样率）的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getChannelCountAsync()

描述

获取播放流的频道数。

返回值

返回解析为Int32（代表通道计数）的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getSampleSizeAsync(**)

描述

获取播放流的样本大小。

返回值

返回解析为Int32（代表样本大小）的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getNumBytesInPipelineAsync()

描述

获取管道中等待客户端和音频服务器之间音频管道使用的字节数。

返回值

返回解析为Int32（代表管道中的字节数）的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getNumBytesOfNativeBufferAsync()

描述

获取代表客户端和音频服务器之间共享缓冲区大小的字节数。

返回值

返回解析为Int32（代表原生缓冲区中的字节数）的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getFramesPerBufferAsync()

描述

获取每个缓冲区的帧数。

返回值

返回解析为Int32（代表每个缓冲区的样本大小）的Promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getAudioFocusSessionIdAsync()

描述

获取焦点会话ID。

返回值

返回解析为Int32（代表焦点会话ID）的Promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getLatencyInMsAsync()

描述

获取以毫秒为单位的延迟时间。

返回值

返回解析为Int32（代表以毫秒为单位的延迟时间）的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

pauseAsync()

描述

暂停播放流。

返回值

返回解析为AudioStatus类型的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

startAsync()

描述

开始播放流。

返回值

返回解析为AudioStatus类型的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

stopAsync()

描述

停止播放流。

返回值

返回解析为AudioStatus类型的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

flushAsync()

描述

刷新播放流。

返回值

返回解析为AudioStatus类型的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

registerEventObserverAsync(callback)

描述

注册一个回调函数，一旦检测到音频更改事件即会执行该函数。一次只能注册一个回调函数。

返回值

返回解析为AudioStatus类型的Promise

参数

参数名 类型 是否必需 描述
callback 函数 是 回调函数，该函数接收一个事件并根据该事件执行某些操作

代码示例

/*
创建一个函数并将其注册到记录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));

unregisterEventObserverAsync(**)

描述

取消注册任何当前注册的回调函数。

返回值

返回解析为AudioStatus类型的promise。

代码示例

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

writeAsync(buffer)

描述

使用存储在缓冲区参数中的字节写入播放缓冲区。

返回值

返回解析为AudioStatus类型的promise。

参数

参数名 类型 是否必需 描述
buffer ArrayBuffer 是 包含要写入播放缓冲区的字节的缓冲区

代码示例

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

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

假设playbackStream是一个AudioPlaybackStream对象
*/

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

getUnderrunSizeAsync()

描述

获取用于查询欠载大小的API。

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

否则，此API将返回0。

返回值

返回一个Promise (Int32)，其中包含缓冲区大小和欠载阈值之间的帧数差异。帧值向上舍入。

代码示例

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

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

getUnderrunSizeAsyncTest();

getUnderrunCountAsync()

描述

获取用于查询流生命周期内发生的欠载次数的API。

返回值

返回一个Promise (Int32)，其中包含在流生命周期内发生的欠载次数。

代码示例

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

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

getUnderrunCountAsyncTest();

getPresentedFrameCountAsync()

描述

查询API以获取音频管道已经呈现和接受的音频帧数。

返回值

返回一个Promise (Int32)，其中包含成功时向音频管道呈现的音频帧数。

代码示例

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

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

getPresentedFrameCountAsyncTest();

getDuckingPolicyAsync()

描述

查询API以获取音频管道已经呈现和接受的音频帧数。

返回值

返回一个Promise (Int32)，其中包含当前AudioPlaybackStream对象的duckingPolicy

代码示例

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

const getDuckingPolicyAsyncTest = async () => {
    try {
      const duckingPolicy = await playbackStream.current?.getDuckingPolicyAsync();
      console.debug("getDuckingPolicyAsync : ", duckingPolicy);
    } catch (err) {
      console.debug("getDuckingPolicyAsync() ERR: ", err);
    }
}

getDuckingPolicyAsyncTest();

duckVolumeAsync(mode, value, rampDuration)

描述

根据特定流实例的音量，按指定的分贝/百分比放弃/取消放弃音量放弃/取消放弃流的API。

返回值

返回解析为AudioStatus类型 (Int32) 的Promise。

参数

参数名 类型 是否必需 描述
mode DuckingMode 是 指定用于放弃音量的模式。
value ArrayBuffer 是 对于DuckingMode::DB，值表示当前流音量降低的分贝（范围： 0到144）。对于DuckingMode::PERCENTAGE，值表示当前流音量降低的具体百分比（范围： 0到100）。值 = 0表示流将降至原始流音量
rampDuration ArrayBuffer 是 从当前音量增加到目标音量所需的时间（以毫秒为单位）。

代码示例

/*
假设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();

setVolumeAsync(gain)

描述

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

返回值

返回一个Promise (Int32)，其中包含当前AudioPlaybackStream对象的duckingPolicy

参数

参数名 类型 是否必需 描述
gain Int32 是 增益应用于当前流类型的音量。

代码示例

/*
假设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();

getVolumeAsync()

描述

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

返回值

返回一个Promise (Int32)，其中包含当前AudioPlaybackStream对象的duckingPolicy

参数

| 参数名称 | 类型 | 必填项 | 描述 | | ————– | —- | ——– | ———– |

代码示例

/*
假设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();

Last updated: 2025年10月2日

关注我们:
amazon_developer_logo

© 2010-2025 年，亚马逊公司或其附属公司. 保留所有权利。

协议

开发人员博客

联系我们