AudioPlaybackStream - Amazon Vega Docs

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

所需权限

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)：错误的放弃原则

示例

/* 其他配置
Assume playbackStream is an AudioPlaybackStream object
/*在500毫秒内最多降低50%*\/

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)：服务器通信错误

示例

/*
Flushes the audio playback stream and stores returned AudioStatus type in status
after promise resolves

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the audio attributes for the playback stream and stores it in attributes after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the audio configuration for the playback stream and stores it in config after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：未分配焦点会话

示例

/*
Gets the focus session and stores it in session_id after the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the channel count for the playback stream and stores it in channel_count after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the number of frames in the native buffer and stores it in buffer_frames after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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

getLatencyInMsAsync()

getLatencyInMsAsync(): Promise<Int32> 以毫秒为单位获取播放流的当前延迟。这包括缓冲和硬件延迟。

返回值

Promise<Int32> Promise 解析为如下的Promise：

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

示例

/*
Gets the latency in ms and stores it in latency after the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the number of bytes in the pipeline and stores it in pipeline_bytes after the
promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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

getNumBytesOfNativeBufferAsync()

getNumBytesOfNativeBufferAsync(): Promise<Int32> 获取用于播放的原生缓冲区的大小。这表示可以排队等待播放的最大数据量。

返回值

Promise<Int32> Promise 解析为如下的Promise：

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

示例

/*
Gets the number of bytes in the native buffer and stores it in buffer_bytes after the
promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the sample rate for the playback stream and stores it in sample_rate after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the sample size for the playback stream and stores it in sample_size after
the promise is resolved

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/* 其他配置
Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Gets the status of the audio playback stream and stores it in status

Assume playbackStream is an AudioPlaybackStream object
*\/
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)：服务器通信错误

示例

/*
Pauses the audio playback stream and stores returned AudioStatus type in status after
promise resolves

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/* 其他配置
Assume playbackStream is an AudioPlaybackStream object
/*假设有一种方法可以播放与当前播放流相关的音频*\/

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)：服务器通信错误

示例

/*
Starts the audio playback stream and stores returned AudioStatus type in status after
promise resolves

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Stops the audio playback stream and stores returned AudioStatus type in status after
promise resolves

Assume playbackStream is an AudioPlaybackStream object
*\/

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

unregisterEventObserverAsync()

unregisterEventObserverAsync(): Promise<AudioStatus> 取消注册之前注册的事件回调。

返回值

Promise<AudioStatus> Promise 解析为如下的Promise：

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

示例

/*
Unregisters callback function and stores returned AudioStatus type in status after
promise resolves

Assume playbackStream is an AudioPlaybackStream object
*\/

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)：服务器通信错误

示例

/*
Writes to the playback buffer and stores returned AudioStatus type in status after
promise resolves

Assume buffer is an Uint8Array containing the bytes to write to the buffer

Assume playbackStream is an AudioPlaybackStream object
*\/

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

​所需权限

​使用的类型

​构造函数

​new AudioPlaybackStream()

​参数

id

​返回值

​属性

​streamId

​方法

​duckVolumeAsync()

​参数

mode

值

rampDurationMs

​返回值

​示例

​flushAsync()

​返回值

​示例

​getAudioAttributesAsync()

​返回值

​示例

​getAudioConfigAsync()

​返回值

​示例

​getAudioEffectSessionIdAsync()

​返回值

​getAudioFocusSessionIdAsync()

​返回值

​示例

​getBufferCountAsync()

​返回值

​getChannelCountAsync()

​返回值

​示例

​getDuckingPolicyAsync()

​返回值

​示例

​getFramesPerBufferAsync()

​返回值

​示例

​getLatencyInMsAsync()

​返回值

​示例

​getMajorVersion()

​返回值

​getMinorVersion()

​返回值

​getNumBytesInPipelineAsync()

​返回值

​示例

​getNumBytesOfNativeBufferAsync()

​返回值

​示例

​getPatchVersion()

​返回值

​getPresentedFrameCountAsync()

​返回值

​示例

​getSampleRateAsync()

​返回值

​示例

​getSampleSizeAsync()

​返回值

​示例

​getUnderrunCountAsync()

​返回值

​示例

​getUnderrunSizeAsync()

​返回值

​示例

​getVolumeAsync()

​返回值

​示例

​initCheckAsync()

​返回值

​示例

​pauseAsync()

​返回值

所需权限

使用的类型

构造函数

new AudioPlaybackStream()

参数

返回值

属性

streamId

方法

duckVolumeAsync()

参数

返回值

示例

flushAsync()

返回值

示例

getAudioAttributesAsync()

返回值

示例

getAudioConfigAsync()

返回值

示例

getAudioEffectSessionIdAsync()

返回值

getAudioFocusSessionIdAsync()

返回值

示例

getBufferCountAsync()

返回值

getChannelCountAsync()

返回值

示例

getDuckingPolicyAsync()

返回值

示例

getFramesPerBufferAsync()

返回值

示例

getLatencyInMsAsync()

返回值

示例

getMajorVersion()

返回值

getMinorVersion()

返回值

getNumBytesInPipelineAsync()

返回值

示例

getNumBytesOfNativeBufferAsync()

返回值

示例

getPatchVersion()

返回值

getPresentedFrameCountAsync()

返回值

示例

getSampleRateAsync()

返回值

示例

getSampleSizeAsync()

返回值

示例

getUnderrunCountAsync()

返回值

示例

getUnderrunSizeAsync()

返回值

示例

getVolumeAsync()

返回值

示例

initCheckAsync()

返回值

示例

pauseAsync()

返回值

示例

queryMinimumBufferInfoAsync()

返回值

registerEventObserverAsync()