AudioStream

Class Summary

Audio::AudioStreamIn

音频输入流，用于音频采集与录制。

• 构造：无

• 成员函数：

  接口名称	功能简述
  Init	使用采集配置参数初始化音频输入流
  GetCurrentDeviceId	获取当前输入设备 ID
  GetCurrentChannelId	获取输入流的当前通道 ID
  AttachBackend	将后端附加到输入流
  GetTimestamp	获取输入流的时间戳
  Start	启动音频输入流
  Stop	停止音频输入流
  SetInputDevice	设置输入流的采集设备
  ObtainBuffer	从输入流获取采集缓冲区
  Release	释放音频输入流资源
  SetParam	设置输入流的键值对参数
  GetParam	获取输入流的键值对参数

• 使用包含头文件：#include "audio_stream_in.h"

• 声明头文件：middleware/services/media/foundation/audiomanager/frameworks/audiostream/include/cpp/audio_stream_in.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

Audio::AudioStreamOut

音频输出流，用于音频播放与渲染。

• 构造：无

• 成员函数：

  接口名称	功能简述
  Init	使用渲染配置参数初始化音频输出流
  Play	启动音频播放
  Pause	暂停音频播放
  Stop	停止音频输出流
  Release	释放音频输出流资源
  SetPlayBackSpeed	设置播放速度
  SetMute	设置输出流静音状态
  SetVolume	设置输出流音量
  GetCurrentDeviceId	获取当前输出设备 ID
  GetCurrentChannelId	获取输出流的当前通道 ID
  AttachFrontend	将前端附加到输出流
  StreamWrite	向输出流写入音频数据
  GetPosition	获取输出流的渲染位置
  GetTimestamp	获取输出流的时间戳
  Flush	刷新输出流缓冲区
  SetOutputDevice	设置输出流的播放设备
  GetBufferFrameSize	获取输出流缓冲区帧大小
  GetBufferUnderflowTimes	获取输出流缓冲区欠载次数
  DumpInfo	导出输出流调试信息
  SetParam	设置输出流的键值对参数
  GetParam	获取输出流的键值对参数

• 使用包含头文件：#include "audio_stream_out.h"

• 声明头文件：middleware/services/media/foundation/audiomanager/frameworks/audiostream/include/cpp/audio_stream_out.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

Functions

Audio::AudioStreamIn

Init

int32_t Init(const CapturerInputConfig &config, CapturerCallback cbk = nullptr, const void *caller = nullptr)

功能说明

• 核心用途：使用采集配置参数初始化音频输入流
• 设计目的：创建音频输入流句柄并注册采集回调函数
• 使用场景：音频录制前调用，完成输入流的初始化与回调注册

前置条件

• 对象已通过 AudioStreamIn() 默认构造完成，且未调用过 Init
• 传入的 config 参数中各字段取值需符合音频流配置约束

入参

名称	参数类型	详细说明	约束取值范围
config	const CapturerInputConfig &	入参只读引用，音频采集配置信息	参见 CapturerInputConfig 结构体
cbk	CapturerCallback	采集回调函数指针，缺省值为 nullptr	有效函数指针或 nullptr
caller	const void *	调用者标识指针，缺省值为 nullptr	有效指针或 nullptr

返回值

• 返回类型：int32_t

返回初始化结果

返回值	触发场景
AUDIO_SUCCESS(0)	初始化成功
AUDIO_ERROR(-1)	创建输入流失败

GetCurrentDeviceId

int32_t GetCurrentDeviceId() const

功能说明

• 核心用途：获取当前音频输入流绑定的设备 ID
• 设计目的：查询当前输入流所关联的音频采集设备
• 使用场景：需要确认当前输入设备时调用

返回值

• 返回类型：int32_t

返回当前设备 ID

返回值	触发场景
deviceId	当前输入流绑定的设备 ID

GetCurrentChannelId

int32_t GetCurrentChannelId(uint32_t &channelId) const

功能说明

• 核心用途：获取当前音频输入流的通道 ID
• 设计目的：查询输入流当前使用的音频通道标识
• 使用场景：需要获取当前采集通道信息时调用

出参

名称	数据类型	输出说明
channelId	uint32_t &	出参引用，当前通道 ID

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取通道 ID 成功
AUDIO_ERROR(-1)	获取通道 ID 失败

AttachBackend

int32_t AttachBackend(uint32_t &backendId) const

功能说明

• 核心用途：将后端附加到音频输入流
• 设计目的：建立输入流与后端处理的关联
• 使用场景：音频采集链路需要后端处理时调用

出参

名称	数据类型	输出说明
backendId	uint32_t &	出参引用，后端标识 ID

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	附加后端成功
AUDIO_ERROR(-1)	附加后端失败

GetTimestamp

int32_t GetTimestamp(struct timespec &timestamp, Timebase base) const

功能说明

• 核心用途：获取音频输入流的时间戳
• 设计目的：获取输入流当前的采集时间信息，支持不同时间基准
• 使用场景：音视频同步、时间戳校准等场景

入参

名称	参数类型	详细说明	约束取值范围
base	Timebase	时间基准类型	Timebase 枚举值

出参

名称	数据类型	输出说明
timestamp	struct timespec &	出参引用，采集时间戳

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取时间戳成功
AUDIO_ERROR(-1)	获取时间戳失败

Start

int32_t Start() const

功能说明

• 核心用途：启动音频输入流，开始音频采集
• 设计目的：使输入流进入运行状态，开始接收音频数据
• 使用场景：初始化完成后，准备采集音频数据时调用

前置条件

• 已调用 Init 完成输入流初始化

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	启动成功
AUDIO_ERROR(-1)	启动失败

Stop

int32_t Stop() const

功能说明

• 核心用途：停止音频输入流，停止音频采集
• 设计目的：使输入流进入停止状态，不再接收音频数据
• 使用场景：音频采集完成后调用

前置条件

• 输入流已处于启动状态

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	停止成功
AUDIO_ERROR(-1)	停止失败

SetInputDevice

int32_t SetInputDevice(int32_t deviceId, AudioRendererConfig &renderConfig) const

功能说明

• 核心用途：设置音频输入流的输入设备
• 设计目的：切换输入流关联的音频采集设备
• 使用场景：需要切换采集设备（如从内置麦克风切换到 USB 麦克风）时调用

入参

名称	参数类型	详细说明	约束取值范围
deviceId	int32_t	目标输入设备 ID	有效的音频设备 ID
renderConfig	AudioRendererConfig &	入参引用，渲染配置信息（当前未使用）	-

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	设置输入设备成功
AUDIO_ERROR(-1)	设置输入设备失败

ObtainBuffer

int32_t ObtainBuffer(CapturerBuffer &buffer, bool isBlocking) const

功能说明

• 核心用途：从音频输入流获取采集缓冲区
• 设计目的：读取已采集的音频数据到缓冲区中
• 使用场景：音频采集过程中，循环调用以获取音频帧数据

入参

名称	参数类型	详细说明	约束取值范围
isBlocking	bool	是否阻塞等待数据（当前未使用）	true / false

出参

名称	数据类型	输出说明
buffer	CapturerBuffer &	出参引用，采集的音频缓冲区数据

返回值

• 返回类型：int32_t

返回采集结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取缓冲区成功
Other	获取缓冲区返回的底层错误码

Release

int32_t Release() const

功能说明

• 核心用途：释放音频输入流资源
• 设计目的：销毁输入流句柄，释放关联的系统资源
• 使用场景：音频采集完全结束后调用，释放输入流占用的资源

前置条件

• 输入流已初始化

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	释放成功
AUDIO_ERROR(-1)	释放失败

SetParam

int32_t SetParam(const char *keyValueList, int32_t len) const

功能说明

• 核心用途：设置音频输入流的键值对参数
• 设计目的：向输入流传递运行时参数配置
• 使用场景：需要动态调整输入流参数时调用

入参

名称	参数类型	详细说明	约束取值范围
keyValueList	const char *	入参指针，键值对参数字符串	非 nullptr，指向有效字符串
len	int32_t	键值对字符串长度	大于 0

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	设置参数成功
AUDIO_ERROR(-1)	设置参数失败

GetParam

int32_t GetParam(char *keyValueList, int32_t len)

功能说明

• 核心用途：获取音频输入流的键值对参数
• 设计目的：从输入流读取当前运行时参数配置
• 使用场景：需要查询输入流当前参数时调用

入参

名称	参数类型	详细说明	约束取值范围
keyValueList	char *	出参指针，存储键值对参数字符串	非 nullptr，指向有效缓冲区
len	int32_t	缓冲区长度	大于 0

出参

名称	数据类型	输出说明
keyValueList	char *	出参指针，键值对参数字符串

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取参数成功
AUDIO_ERROR(-1)	获取参数失败

Audio::AudioStreamOut

Init

int32_t Init(AudioRendererConfig &config, RendererCallback cbk = nullptr, const void *caller = nullptr)

功能说明

• 核心用途：使用渲染配置参数初始化音频输出流
• 设计目的：创建音频输出流句柄并注册渲染回调函数
• 使用场景：音频播放前调用，完成输出流的初始化与回调注册

前置条件

• 对象已通过 AudioStreamOut() 默认构造完成，且未调用过 Init
• 传入的 config 参数中各字段取值需符合音频流配置约束

入参

名称	参数类型	详细说明	约束取值范围
config	AudioRendererConfig &	入参引用，音频渲染配置信息	参见 AudioRendererConfig 结构体
cbk	RendererCallback	渲染回调函数指针，缺省值为 nullptr	有效函数指针或 nullptr
caller	const void *	调用者标识指针，缺省值为 nullptr	有效指针或 nullptr

返回值

• 返回类型：int32_t

返回初始化结果

返回值	触发场景
AUDIO_SUCCESS(0)	初始化成功
AUDIO_ERROR(-1)	创建输出流失败

Play

int32_t Play() const

功能说明

• 核心用途：启动音频输出流，开始音频播放
• 设计目的：使输出流进入运行状态，开始输出音频数据
• 使用场景：初始化完成后，准备播放音频数据时调用

前置条件

• 已调用 Init 完成输出流初始化

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	播放启动成功
Other	播放启动返回的底层错误码

Pause

int32_t Pause() const

功能说明

• 核心用途：暂停音频输出流播放
• 设计目的：使输出流进入暂停状态，保留流资源但不输出数据
• 使用场景：需要临时暂停播放时调用

前置条件

• 输出流已处于播放状态

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	暂停成功
AUDIO_ERROR(-1)	暂停失败

Stop

int32_t Stop() const

功能说明

• 核心用途：停止音频输出流
• 设计目的：使输出流进入停止状态，停止音频数据输出
• 使用场景：音频播放完成后调用

前置条件

• 输出流已处于播放或暂停状态

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	停止成功
AUDIO_ERROR(-1)	停止失败

Release

int32_t Release() const

功能说明

• 核心用途：释放音频输出流资源
• 设计目的：销毁输出流句柄，释放关联的系统资源
• 使用场景：音频播放完全结束后调用，释放输出流占用的资源

前置条件

• 输出流已初始化

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	释放成功
AUDIO_ERROR(-1)	释放失败

SetPlayBackSpeed

int32_t SetPlayBackSpeed(float speed) const

功能说明

• 核心用途：设置音频输出流的播放速度
• 设计目的：调整输出流的播放速率，支持倍速播放
• 使用场景：需要变速播放音频时调用

入参

名称	参数类型	详细说明	约束取值范围
speed	float	播放速度倍率	正浮点数

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	设置播放速度成功
AUDIO_ERROR(-1)	设置播放速度失败

SetMute

int32_t SetMute(bool mute) const

功能说明

• 核心用途：设置音频输出流的静音状态
• 设计目的：控制输出流是否静音输出
• 使用场景：需要静音或取消静音时调用

入参

名称	参数类型	详细说明	约束取值范围
mute	bool	静音标志	true：静音；false：取消静音

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	设置静音成功
AUDIO_ERROR(-1)	设置静音失败

SetVolume

int32_t SetVolume(float volume) const

功能说明

• 核心用途：设置音频输出流的音量
• 设计目的：调整输出流的播放音量，综合考虑类型音量与混音权重
• 使用场景：需要调节播放音量时调用

入参

名称	参数类型	详细说明	约束取值范围
volume	float	音量值	0.0 ~ 1.0

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	设置音量成功
AUDIO_ERROR(-1)	设置音量失败

GetCurrentDeviceId

int32_t GetCurrentDeviceId() const

功能说明

• 核心用途：获取当前音频输出流绑定的设备 ID
• 设计目的：查询当前输出流所关联的音频播放设备
• 使用场景：需要确认当前输出设备时调用

返回值

• 返回类型：int32_t

返回当前设备 ID

返回值	触发场景
deviceId	当前输出流绑定的设备 ID

GetCurrentChannelId

int32_t GetCurrentChannelId(uint32_t &channelId) const

功能说明

• 核心用途：获取当前音频输出流的通道 ID
• 设计目的：查询输出流当前使用的音频通道标识
• 使用场景：需要获取当前播放通道信息时调用

出参

名称	数据类型	输出说明
channelId	uint32_t &	出参引用，当前通道 ID

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取通道 ID 成功
AUDIO_ERROR(-1)	获取通道 ID 失败

AttachFrontend

int32_t AttachFrontend(uint32_t &frontendId) const

功能说明

• 核心用途：将前端附加到音频输出流
• 设计目的：建立输出流与前端处理的关联
• 使用场景：音频播放链路需要前端处理时调用

出参

名称	数据类型	输出说明
frontendId	uint32_t &	出参引用，前端标识 ID

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	附加前端成功
AUDIO_ERROR(-1)	附加前端失败

StreamWrite

int32_t StreamWrite(const uint8_t *buffer, uint64_t userSize, uint64_t &writtenSize, AudioRendererConfig &renderConfig) const

功能说明

• 核心用途：向音频输出流写入音频数据
• 设计目的：将音频数据送入输出流进行播放
• 使用场景：音频播放过程中，循环调用以写入音频帧数据

入参

名称	参数类型	详细说明	约束取值范围
buffer	const uint8_t *	入参指针，待写入的音频数据缓冲区	非 nullptr，指向有效数据
userSize	uint64_t	请求写入的数据大小（字节）	大于 0
renderConfig	AudioRendererConfig &	入参引用，渲染配置信息（当前未使用）	-

出参

名称	数据类型	输出说明
writtenSize	uint64_t &	出参引用，实际写入的数据大小（字节）

返回值

• 返回类型：int32_t

返回写入结果

返回值	触发场景
AUDIO_SUCCESS(0)	写入成功
AUDIO_ERROR(-1)	写入失败

GetPosition

int32_t GetPosition(int64_t &position) const

功能说明

• 核心用途：获取音频输出流的渲染位置
• 设计目的：查询当前输出流的渲染帧位置信息
• 使用场景：音视频同步、进度跟踪等场景

出参

名称	数据类型	输出说明
position	int64_t &	出参引用，当前渲染位置

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取渲染位置成功
Other	获取渲染位置返回的底层错误码

GetTimestamp

int32_t GetTimestamp(struct timespec &timeStamp) const

功能说明

• 核心用途：获取音频输出流的时间戳
• 设计目的：获取输出流当前的播放时间信息
• 使用场景：音视频同步、时间戳校准等场景

出参

名称	数据类型	输出说明
timeStamp	struct timespec &	出参引用，播放时间戳

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取时间戳成功
AUDIO_ERROR(-1)	获取时间戳失败

Flush

int32_t Flush() const

功能说明

• 核心用途：刷新音频输出流缓冲区
• 设计目的：清空输出流中的缓冲数据
• 使用场景：需要丢弃缓冲区中未播放的音频数据时调用

前置条件

• 输出流已初始化

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	刷新成功
AUDIO_ERROR(-1)	刷新失败

SetOutputDevice

int32_t SetOutputDevice(int32_t deviceId, AudioRendererConfig &renderConfig) const

功能说明

• 核心用途：设置音频输出流的输出设备
• 设计目的：切换输出流关联的音频播放设备
• 使用场景：需要切换播放设备（如从内置扬声器切换到蓝牙设备）时调用

入参

名称	参数类型	详细说明	约束取值范围
deviceId	int32_t	目标输出设备 ID	有效的音频设备 ID
renderConfig	AudioRendererConfig &	入参引用，渲染配置信息（当前未使用）	-

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	设置输出设备成功
AUDIO_ERROR(-1)	设置输出设备失败

GetBufferFrameSize

int32_t GetBufferFrameSize() const

功能说明

• 核心用途：获取音频输出流的缓冲区帧大小
• 设计目的：查询输出流每个缓冲区的帧数
• 使用场景：需要确定每次写入的音频帧大小时调用

返回值

• 返回类型：int32_t

返回缓冲区帧大小

返回值	触发场景
frameSize	缓冲区帧大小

GetBufferUnderflowTimes

int32_t GetBufferUnderflowTimes() const

功能说明

• 核心用途：获取音频输出流的缓冲区欠载次数
• 设计目的：统计输出流缓冲区数据不足导致欠载的次数
• 使用场景：音频播放质量诊断与调试

返回值

• 返回类型：int32_t

返回缓冲区欠载次数

返回值	触发场景
underflowTimes	缓冲区欠载次数

DumpInfo

StreamDebugInfo DumpInfo() const

功能说明

• 核心用途：导出音频输出流的调试信息
• 设计目的：获取输出流的内部状态信息用于诊断
• 使用场景：音频播放问题排查与调试

返回值

• 返回类型：StreamDebugInfo

返回输出流的调试信息结构体

返回值	触发场景
StreamDebugInfo	包含当前流状态、流索引、流信息、音量等调试信息

SetParam

int32_t SetParam(const char *keyValueList, int32_t len) const

功能说明

• 核心用途：设置音频输出流的键值对参数
• 设计目的：向输出流传递运行时参数配置
• 使用场景：需要动态调整输出流参数时调用

入参

名称	参数类型	详细说明	约束取值范围
keyValueList	const char *	入参指针，键值对参数字符串	非 nullptr，指向有效字符串
len	int32_t	键值对字符串长度	大于 0

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	设置参数成功
AUDIO_ERROR(-1)	设置参数失败

GetParam

int32_t GetParam(char *keyValueList, int32_t len)

功能说明

• 核心用途：获取音频输出流的键值对参数
• 设计目的：从输出流读取当前运行时参数配置
• 使用场景：需要查询输出流当前参数时调用

入参

名称	参数类型	详细说明	约束取值范围
keyValueList	char *	出参指针，存储键值对参数字符串	非 nullptr，指向有效缓冲区
len	int32_t	缓冲区长度	大于 0

出参

名称	数据类型	输出说明
keyValueList	char *	出参指针，键值对参数字符串

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
AUDIO_SUCCESS(0)	获取参数成功
AUDIO_ERROR(-1)	获取参数失败

Enumerations

Timebase

enum Timebase : int32_t {
    MONOTONIC = 0,
    BOOTTIME = 1
};

枚举成员	取值	描述
MONOTONIC	0	单调递增时间，不包含系统休眠时间
BOOTTIME	1	单调递增时间，包含系统休眠时间

Structures

CapturerInputConfig

typedef struct {
    AudioCodecFormat audioFormat;
    AudioStreamType streamType;
    uint32_t sampleRate;
    uint32_t sessionID;
    uint32_t channelCount;
    AudioLinkDirection linkDir;
    bool disableSEA;
    uint32_t micType;
    AudioBitWidth bitWidth;
    bool isAlwaysWake;
    uint32_t frameLength;
} CapturerInputConfig;

成员说明：

成员名称	数据类型	描述
audioFormat	AudioCodecFormat	音频编解码格式
streamType	AudioStreamType	音频流类型
sampleRate	uint32_t	采样率
sessionID	uint32_t	会话 ID
channelCount	uint32_t	通道数
linkDir	AudioLinkDirection	链接方向
disableSEA	bool	是否禁用语音增强算法
micType	uint32_t	麦克风类型
bitWidth	AudioBitWidth	位宽
isAlwaysWake	bool	是否常唤醒
frameLength	uint32_t	帧长度

AudioRendererConfig

typedef struct {
    AudioCodecFormat audioFormat;
    AudioStreamType streamType;
    uint32_t sampleRate;
    uint32_t sessionID;
    uint32_t channelCount;
    uint32_t deviceId;
    uint32_t connectedId;
    AudioLinkDirection linkDir;
    uint16_t sampleFmt;
    AudioBitWidth bitWidth;
    bool isSync;
    uint32_t frameLength;
} AudioRendererConfig;

成员说明：

成员名称	数据类型	描述
audioFormat	AudioCodecFormat	音频编解码格式
streamType	AudioStreamType	音频流类型
sampleRate	uint32_t	采样率
sessionID	uint32_t	会话 ID
channelCount	uint32_t	通道数
deviceId	uint32_t	设备 ID
connectedId	uint32_t	已连接设备 ID
linkDir	AudioLinkDirection	链接方向
sampleFmt	uint16_t	采样格式
bitWidth	AudioBitWidth	位宽
isSync	bool	是否同步模式
frameLength	uint32_t	帧长度

CapturerBuffer

typedef struct {
    uint32_t frameCount;
    uint32_t size;
    uint8_t *data;
} CapturerBuffer;

成员说明：

成员名称	数据类型	描述
frameCount	uint32_t	帧数量
size	uint32_t	数据大小（字节）
data	uint8_t *	音频数据指针

StreamDebugInfo

typedef struct {
    uint32_t state;
    int32_t  streamIndex;
    AudioStreamInfo streamInfo;
    float streamVolume;
    float mixWeight;
    uint32_t curDevice;
} StreamDebugInfo;

成员说明：

成员名称	数据类型	描述
state	uint32_t	流状态
streamIndex	int32_t	流索引
streamInfo	AudioStreamInfo	流信息
streamVolume	float	流音量
mixWeight	float	混音权重
curDevice	uint32_t	当前设备