audio_capturer

Class Summary

OHOS::Audio::Timestamp

提供时间戳信息，包含帧位置信息与高精度时间源

• 构造：无
• 成员函数：无
• 使用包含头文件：#include "audio_capturer.h"
• 声明头文件：middleware/services/media/foundation/audio_capturer/interfaces/kits/audio_capturer.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：Timebase（公有嵌套枚举类）
• 模板形参：无

OHOS::Audio::Timestamp::Timebase

枚举时间戳的时间基准类型，支持不同的计时方式

• 构造：无
• 成员函数：无
• 使用包含头文件：#include "audio_capturer.h"
• 声明头文件：middleware/services/media/foundation/audio_capturer/interfaces/kits/audio_capturer.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

OHOS::Audio::AudioCapturer

提供音频采集功能，支持设置采集参数、启动/停止录制、读取音频数据等操作

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetMinFrameCount	获取指定条件下的最小帧数
  GetFrameCount	获取当前条件下的帧数
  SetCapturerInfo	设置音频采集参数
  GetCapturerInfo	获取音频采集参数
  Start	启动音频录制
  Read	读取音频数据
  GetStatus	获取音频采集状态
  GetAudioTime	获取时间戳
  Stop	停止音频录制
  Release	释放 AudioCapturer 对象
  DumpInfo	获取采集调试信息

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

• 声明头文件：middleware/services/media/foundation/audio_capturer/interfaces/kits/audio_capturer.h
• 公有运算符：无
• 继承关系：无
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::Audio::AudioCapturer

GetMinFrameCount

static bool GetMinFrameCount(int32_t sampleRate, int32_t channelCount, AudioCodecFormat audioFormat, size_t &frameCount)

功能说明

• 核心用途：获取指定采样率、通道数和音频格式条件下的最小帧数
• 使用场景：在创建音频采集器前确定缓冲区帧数要求
• 静态方法，无需创建 AudioCapturer 对象即可调用

入参

名称	参数类型	详细说明	约束取值范围
sampleRate	int32_t	音频采样率，单位 Hz	有效的音频采样率值
channelCount	int32_t	音频录制通道数	大于 0
audioFormat	AudioCodecFormat	音频数据格式	AudioCodecFormat 枚举值
frameCount	size_t &	出参引用，由被调用方写入最小帧数	-

出参

名称	数据类型	输出说明
frameCount	size_t &	出参引用，返回最小帧数，单位为每采样字节数

返回值

• 返回类型：bool

返回最小帧数获取结果

返回值	触发场景
true	成功获取最小帧数
false	获取最小帧数失败

GetFrameCount

uint64_t GetFrameCount()

功能说明

• 核心用途：获取当前条件下所需的帧数，单位为每采样字节数
• 使用场景：在调用 Read 前确定缓冲区大小要求
• 返回值为当前采集配置下的帧数

返回值

• 返回类型：uint64_t

返回当前条件下的帧数

返回值	触发场景
有效帧数(>0)	成功获取帧数
-1	发生异常

SetCapturerInfo

int32_t SetCapturerInfo(const AudioCapturerInfo &info)

功能说明

• 核心用途：设置音频采集参数，包括输入源、音频格式、采样率、通道数等
• 使用场景：在启动录制前配置采集参数
• 入参为只读引用，不修改传入的参数对象

前置条件

• AudioCapturer 对象已构造完成，尚未进入录制状态
• 传入的 AudioCapturerInfo 参数字段值须在合法范围内

入参

名称	参数类型	详细说明	约束取值范围
info	const AudioCapturerInfo &	入参只读引用，音频采集参数信息	参考 AudioCapturerInfo 结构体各字段约束

返回值

• 返回类型：int32_t

返回设置结果

返回值	触发场景
SUCCESS(0)	设置成功
ERR_ILLEGAL_STATE	AudioCapturer 实例状态异常
ERR_INVALID_PARAM	输入参数不正确

GetCapturerInfo

int32_t GetCapturerInfo(AudioCapturerInfo &info)

功能说明

• 核心用途：获取当前音频采集参数
• 使用场景：在 SetCapturerInfo 设置成功后查询已配置的采集参数
• 出参引用由被调用方写入采集参数信息

前置条件

• 已通过 SetCapturerInfo 成功设置采集参数

入参

名称	参数类型	详细说明	约束取值范围
info	AudioCapturerInfo &	出参引用，用于接收音频采集参数信息	-

出参

名称	数据类型	输出说明
info	AudioCapturerInfo &	出参引用，由被调用方写入当前采集参数信息

返回值

• 返回类型：int32_t

返回获取结果

返回值	触发场景
SUCCESS(0)	成功获取参数信息
ERR_ILLEGAL_STATE	AudioCapturer 实例状态异常

Start

bool Start()

功能说明

• 核心用途：启动音频录制
• 使用场景：在 SetCapturerInfo 配置采集参数成功后调用，开始录制音频
• 调用后 AudioCapturer 进入 RECORDING 状态

前置条件

• 已通过 SetCapturerInfo 成功设置采集参数

返回值

• 返回类型：bool

返回启动结果

返回值	触发场景
true	成功启动录制
false	启动录制失败

Read

int32_t Read(uint8_t *buffer, size_t userSize, bool isBlockingRead)

功能说明

• 核心用途：从音频设备读取音频数据到指定缓冲区
• 使用场景：在录制状态下循环调用以持续获取音频数据
• 缓冲区大小须满足 userSize >= frameCount * channelCount * BytesPerSample

前置条件

• AudioCapturer 处于 RECORDING 状态
• buffer 不为 nullptr，且指向的内存空间已申请成功，长度不小于 userSize

入参

名称	参数类型	详细说明	约束取值范围
buffer	uint8_t *	入参指针，指向写入音频数据的缓冲区，不可为 nullptr	非空，长度 >= userSize
userSize	size_t	缓冲区大小，单位字节	>= frameCount * channelCount * BytesPerSample
isBlockingRead	bool	指定是否阻塞读取	true：阻塞；false：非阻塞

返回值

• 返回类型：int32_t

返回读取的音频数据大小

返回值	触发场景
0 ~ userSize	成功读取的音频数据大小，单位字节
ERR_INVALID_PARAM	输入参数不正确
ERR_ILLEGAL_STATE	AudioCapturer 实例未初始化
ERR_SOURCE_NOT_SET	硬件设备实例状态异常

GetStatus

State GetStatus()

功能说明

• 核心用途：获取当前音频采集状态
• 使用场景：查询采集器当前处于初始化、准备、录制、停止或释放状态
• 返回值为 State 枚举类型

返回值

• 返回类型：State

返回音频采集状态

返回值	触发场景
INITIALIZED(0)	已初始化
PREPARED(1)	已准备
RECORDING(2)	录制中
STOPPED(3)	已停止
RELEASED(4)	已释放

GetAudioTime

bool GetAudioTime(Timestamp &timestamp, Timestamp::Timebase base)

功能说明

• 核心用途：获取当前音频采集的时间戳信息
• 使用场景：在录制过程中获取帧位置与高精度时间信息
• 支持两种时间基准：MONOTONIC 和 BOOTTIME

入参

名称	参数类型	详细说明	约束取值范围
timestamp	Timestamp &	出参引用，由调用方提供 Timestamp 实例	-
base	Timestamp::Timebase	时间基准类型	Timebase 枚举值：MONOTONIC / BOOTTIME

出参

名称	数据类型	输出说明
timestamp	Timestamp &	出参引用，由被调用方写入帧位置与时间信息

返回值

• 返回类型：bool

返回时间戳获取结果

返回值	触发场景
true	成功获取时间戳
false	获取时间戳失败

Stop

bool Stop()

功能说明

• 核心用途：停止音频录制
• 使用场景：在录制状态下调用以停止音频采集
• 调用后 AudioCapturer 进入 STOPPED 状态

前置条件

• AudioCapturer 处于 RECORDING 状态

返回值

• 返回类型：bool

返回停止结果

返回值	触发场景
true	成功停止录制
false	停止录制失败

Release

bool Release()

功能说明

• 核心用途：释放本地 AudioCapturer 对象及其关联资源
• 使用场景：在停止录制后调用，释放采集器占用的资源
• 调用后 AudioCapturer 进入 RELEASED 状态，不可再用于采集

前置条件

• AudioCapturer 对象已停止录制或处于非 RECORDING 状态

返回值

• 返回类型：bool

返回释放结果

返回值	触发场景
true	成功释放对象
false	释放对象失败

DumpInfo

int32_t DumpInfo(AudioCapturerDebugInfo &capturerInfo)

功能说明

• 核心用途：获取当前音频采集器的调试信息
• 使用场景：在调试或诊断场景下获取采集器的帧计数、采样率、状态等内部信息
• 出参引用由被调用方写入调试信息

入参

名称	参数类型	详细说明	约束取值范围
capturerInfo	AudioCapturerDebugInfo &	出参引用，用于接收采集器调试信息	-

出参

名称	数据类型	输出说明
capturerInfo	AudioCapturerDebugInfo &	出参引用，由被调用方写入帧计数、帧时间戳、采样率等调试信息

返回值

• 返回类型：int32_t

返回获取结果

返回值	触发场景
SUCCESS(0)	成功获取调试信息
ERR_ILLEGAL_STATE	AudioCapturer 实例状态异常

Type definitions

AudioSession

typedef uint32_t AudioSession;

使用说明：用于 AudioCapturerInfo 结构体的 sessionID 字段类型

Enumerations

Timestamp::Timebase

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

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

State

enum State : uint32_t {
    INITIALIZED,
    PREPARED,
    RECORDING,
    STOPPED,
    RELEASED
};

枚举成员	取值	描述
INITIALIZED	0	已初始化
PREPARED	1	已准备
RECORDING	2	录制中
STOPPED	3	已停止
RELEASED	4	已释放

AudioCodecFormat

typedef enum {
    AUDIO_DEFAULT    = 0,
    PCM              = 1,
    AAC_LC           = 2,
    AAC_HE_V1        = 3,
    AAC_HE_V2        = 4,
    AAC_LD           = 5,
    AAC_ELD          = 6,
    G711A            = 7,
    G711U            = 8,
    G726             = 9,
    OPUS             = 10,
    FLAC             = 11,
    VORBIS           = 12,
    APE              = 13,
    MP3              = 14,
    mSBC             = 15,
    SILK             = 16,
    SBC              = 17,
    L2HC             = 18,
    AMR_WB           = 19,
    LHDC             = 20,
    LDAC             = 21,
    L2HC_VOICE       = 22,
    AUDIO_FORMAT_MAX,
    FORMAT_INVALID = 0xFFFFFFFF,
} AudioCodecFormat;

枚举成员	取值	描述
AUDIO_DEFAULT	0	默认音频格式
PCM	1	PCM 格式
AAC_LC	2	高级音频编码低复杂度(AAC-LC)
AAC_HE_V1	3	高效高级音频编码(AAC-HE)，即 AAC+ 或 aacPlus v1
AAC_HE_V2	4	AAC++ 或 aacPlus v2
AAC_LD	5	高级音频编码低时延(AAC-LD)
AAC_ELD	6	高级音频编码增强型低延迟(AAC-ELD)
G711A	7	G711A 格式
G711U	8	G711U 格式
G726	9	G726 格式
OPUS	10	OPUS 格式
FLAC	11	FLAC 格式
VORBIS	12	VORBIS 格式
APE	13	APE 格式
MP3	14	MP3 格式
mSBC	15	mSBC 格式
SILK	16	SILK 格式
SBC	17	SBC 格式
L2HC	18	L2HC 格式
AMR_WB	19	AMR_WB 格式
LHDC	20	LHDC 格式
LDAC	21	LDAC 格式
L2HC_VOICE	22	L2HC_VOICE 格式
AUDIO_FORMAT_MAX	23	格式上限值
FORMAT_INVALID	0xFFFFFFFF	无效格式

AudioSourceType

typedef enum {
    AUDIO_SOURCE_INVALID = 0xFFFFFFFF,
    AUDIO_SOURCE_DEFAULT = 0,
    AUDIO_MIC = 1,
    AUDIO_VOICE_UPLINK = 2,
    AUDIO_VOICE_DOWNLINK = 3,
    AUDIO_VOICE_CALL = 4,
    AUDIO_CAMCORDER = 5,
    AUDIO_VOICE_RECOGNITION = 6,
    AUDIO_VOICE_COMMUNICATION = 7,
    AUDIO_REMOTE_SUBMIX = 8,
    AUDIO_UNPROCESSED = 9,
    AUDIO_VOICE_PERFORMANCE = 10,
    AUDIO_ECHO_REFERENCE = 1997,
    AUDIO_RADIO_TUNER = 1998,
    AUDIO_HOTWORD = 1999,
    AUDIO_REMOTE_SUBMIX_EXTEND = 10007,
} AudioSourceType;

枚举成员	取值	描述
AUDIO_SOURCE_INVALID	0xFFFFFFFF	无效的音频源
AUDIO_SOURCE_DEFAULT	0	默认音频源
AUDIO_MIC	1	麦克风
AUDIO_VOICE_UPLINK	2	上行语音
AUDIO_VOICE_DOWNLINK	3	下行语音
AUDIO_VOICE_CALL	4	语音通话
AUDIO_CAMCORDER	5	摄录一体机
AUDIO_VOICE_RECOGNITION	6	语音识别
AUDIO_VOICE_COMMUNICATION	7	语音通信
AUDIO_REMOTE_SUBMIX	8	远程分混
AUDIO_UNPROCESSED	9	未处理的音频
AUDIO_VOICE_PERFORMANCE	10	语音性能
AUDIO_ECHO_REFERENCE	1997	回声参考
AUDIO_RADIO_TUNER	1998	收音机调谐器
AUDIO_HOTWORD	1999	热词
AUDIO_REMOTE_SUBMIX_EXTEND	10007	扩展远程子混合

AudioStreamType

typedef enum {
    TYPE_DEFAULT = -1,
    TYPE_MEDIA = 0,
    TYPE_VOICE_COMMUNICATION = 1,
    AUDIO_STREAM_NONE                       = 0x0u,
    AUDIO_STREAM_HEAR_AID                   = 0x00001000u,
    AUDIO_STREAM_ALARM                      = 0x00010000u,
    AUDIO_STREAM_ALARM_SYSTEM               = 0x00010001u,
    AUDIO_STREAM_ALARM_CLOCK                = 0x00010002u,
    AUDIO_STREAM_RING                       = 0x00020000u,
    AUDIO_STREAM_VOICE_CALL                 = 0x00040000u,
    AUDIO_STREAM_VOICE_CALL_VOIP            = 0x00040001u,
    AUDIO_STREAM_VOICE_CALL_BT_SCO          = 0x00040002u,
    AUDIO_STREAM_VOICE_CALL_VOLTE           = 0x00040003u,
    AUDIO_STREAM_LIVE_MIC                   = 0x00040004u,
    AUDIO_STREAM_VOICE_CALL_USB             = 0x00040005u,
    AUDIO_STREAM_VOICE_CALL_NEARLINK        = 0x00040006u,
    AUDIO_STREAM_VOICE_CALL_VOLTE_SPI       = 0x00040008u,
    AUDIO_STREAM_VOICE_ASSISTANT            = 0x00080004u,
    AUDIO_STREAM_TTS                        = 0x00100000u,
    AUDIO_STREAM_NOTIFICATION               = 0x00200000u,
    AUDIO_STREAM_NOTIFICATION_SYSTEM        = 0x00200001u,
    AUDIO_STREAM_NOTIFICATION_PROMPT        = 0x00200002u,
    AUDIO_STREAM_MUSIC                      = 0x00400000u,
    AUDIO_STREAM_A2DP_MUSIC                 = 0x00400001u,
    AUDIO_STREAM_USB_MUSIC                  = 0x00400002u,
    AUDIO_STREAM_NEARLINK_MUSIC             = 0x00400003u,
    AUDIO_STREAM_FITNESS_VIDEO              = 0x00800000u,
    AUDIO_STREAM_VOICE_RECORD               = 0x01000000u,
    AUDIO_STREAM_VOICE_RECOGNITION          = 0x02000000u,
    AUDIO_STREAM_VOICE_PICKUP               = 0x02000001u,
    AUDIO_STREAM_INVALID                    = 0x7FFFFFFFu
} AudioStreamType;

枚举成员	取值	描述
TYPE_DEFAULT	-1	默认音频流类型
TYPE_MEDIA	0	媒体音
TYPE_VOICE_COMMUNICATION	1	语音通信
AUDIO_STREAM_NONE	0x0	无
AUDIO_STREAM_HEAR_AID	0x00001000	助听类型
AUDIO_STREAM_ALARM	0x00010000	报警类
AUDIO_STREAM_ALARM_SYSTEM	0x00010001	设备报警
AUDIO_STREAM_ALARM_CLOCK	0x00010002	闹钟
AUDIO_STREAM_RING	0x00020000	来电铃声
AUDIO_STREAM_VOICE_CALL	0x00040000	语音通话
AUDIO_STREAM_VOICE_CALL_VOIP	0x00040001	VoIP 语音通话
AUDIO_STREAM_VOICE_CALL_BT_SCO	0x00040002	蓝牙通话
AUDIO_STREAM_VOICE_CALL_VOLTE	0x00040003	4G VoLTE 通话
AUDIO_STREAM_LIVE_MIC	0x00040004	直播麦
AUDIO_STREAM_VOICE_CALL_USB	0x00040005	USB 语音通话
AUDIO_STREAM_VOICE_CALL_NEARLINK	0x00040006	星闪语音通话
AUDIO_STREAM_VOICE_CALL_VOLTE_SPI	0x00040008	VoLTE SPI 通话
AUDIO_STREAM_VOICE_ASSISTANT	0x00080004	语音助手
AUDIO_STREAM_TTS	0x00100000	语音合成
AUDIO_STREAM_NOTIFICATION	0x00200000	提示音
AUDIO_STREAM_NOTIFICATION_SYSTEM	0x00200001	设备提示音
AUDIO_STREAM_NOTIFICATION_PROMPT	0x00200002	运动健康提示音
AUDIO_STREAM_MUSIC	0x00400000	媒体音
AUDIO_STREAM_A2DP_MUSIC	0x00400001	蓝牙输入媒体音
AUDIO_STREAM_USB_MUSIC	0x00400002	USB 音乐
AUDIO_STREAM_NEARLINK_MUSIC	0x00400003	星闪音乐
AUDIO_STREAM_FITNESS_VIDEO	0x00800000	健身视频指导提示音
AUDIO_STREAM_VOICE_RECORD	0x01000000	语音采集录制
AUDIO_STREAM_VOICE_RECOGNITION	0x02000000	语音识别
AUDIO_STREAM_VOICE_PICKUP	0x02000001	拾音通路
AUDIO_STREAM_INVALID	0x7FFFFFFF	无效

AudioBitWidth

typedef enum {
    BIT_WIDTH_8   = 8,
    BIT_WIDTH_16  = 16,
    BIT_WIDTH_24  = 24,
    BIT_WIDTH_32  = 32,
    BIT_WIDTH_32_FLOAT = 33,
    BIT_WIDTH_BUTT = 0xFFFFFFFFu,
} AudioBitWidth;

枚举成员	取值	描述
BIT_WIDTH_8	8	8 位位宽
BIT_WIDTH_16	16	16 位位宽
BIT_WIDTH_24	24	24 位位宽
BIT_WIDTH_32	32	32 位位宽
BIT_WIDTH_32_FLOAT	33	32 位浮点位宽
BIT_WIDTH_BUTT	0xFFFFFFFF	无效位宽

Structures

Timestamp

class Timestamp {
public:
    uint32_t framePosition;
    struct timespec time;
};

成员说明：

成员名称	数据类型	描述
framePosition	uint32_t	帧位置
time	struct timespec	高精度时间

AudioCapturerInfo

struct AudioCapturerInfo {
    AudioSourceType inputSource = AUDIO_MIC;
    AudioCodecFormat audioFormat = AUDIO_DEFAULT;
    uint32_t sampleRate = 0;
    uint32_t channelCount = 0;
    uint32_t bitRate = 0;
    AudioStreamType streamType = TYPE_MEDIA;
    AudioBitWidth bitWidth = BIT_WIDTH_16;
    AudioSession sessionID = AUDIO_SESSION_ID_NONE;
};

成员说明：

成员名称	数据类型	描述
inputSource	AudioSourceType	音频源类型，默认值为 AUDIO_MIC
audioFormat	AudioCodecFormat	音频编解码格式，默认值为 AUDIO_DEFAULT
sampleRate	uint32_t	采样率，单位 Hz
channelCount	uint32_t	音频通道数
bitRate	uint32_t	比特率
streamType	AudioStreamType	音频流类型，默认值为 TYPE_MEDIA
bitWidth	AudioBitWidth	音频位宽，默认值为 BIT_WIDTH_16
sessionID	AudioSession	会话 ID，默认值为 AUDIO_SESSION_ID_NONE

AudioCapturerDebugInfo

struct AudioCapturerDebugInfo {
    int64_t frameCount;
    int64_t framePts;
    int32_t sampleRate;
    int32_t channelCount;
    int32_t bitRate;
    AudioBitWidth bitWidth;
    State state;
};

成员说明：

成员名称	数据类型	描述
frameCount	int64_t	帧计数
framePts	int64_t	帧时间戳
sampleRate	int32_t	采样率
channelCount	int32_t	通道数
bitRate	int32_t	比特率
bitWidth	AudioBitWidth	位宽
state	State	采集状态