Audio¶

功能概述¶

本文档描述音频功能的接口定义、使用流程及示例代码。音频模块支持WAV、MP3、AMR-NB、PCM等格式，提供统一的流式API用于音频数据的写入（播放）和读取（录制）。

使用流程¶

初始化与打开音频流¶

播放或录制音频前，应用层需要先调用 qcm_aud_stream_open() 函数来初始化音频流管理器。通过配置结构体 qosa_aud_stream_cfg_t 中的 is_record 字段区分播放模式和录制模式：

is_record = QOSA_FALSE：播放模式
is_record = QOSA_TRUE：录制模式

播放流程¶

向流中写入数据¶

调用 qcm_aud_stream_write() 函数将音频数据写入播放流。

播放回调函数¶

当底层驱动需要更多音频数据时，会触发 QOSA_AUD_STREAM_RX_LOW 事件，通过 qosa_aud_stream_cfg_t 中注册的 callback 回调函数通知应用层。此时应调用 qcm_aud_stream_write()，该函数为 非阻塞 调用，它会尽可能多地将音频数据写入内部缓冲区后立即返回。
随着数据不断写入，当缓冲区空间已满时，系统会触发 QOSA_AUD_STREAM_RX_HIGH 事件，通过 qosa_aud_stream_cfg_t 中注册的 callback 回调函数（类型为 qosa_aud_callback_t）通知应用层。

录制流程¶

录制回调函数¶

当音频硬件缓冲区中有足够多的数据时，系统会触发 QOSA_AUD_DRIVER_RX_HIGH 事件，并调用您在 qosa_aud_stream_cfg_t 中注册的类型为 qosa_aud_callback_t 的回调函数通知应用层。

从流中读取数据¶

收到 QOSA_AUD_DRIVER_RX_HIGH 事件通知后，调用 qcm_aud_stream_read() 获取录制的音频数据。

关闭音频流¶

播放或录制完成后，必须调用 qcm_aud_stream_close() 来释放资源。

Audio API¶

头文件¶

qcm_audio.h

函数概览¶

函数	说明
qcm_aud_stream_open()	初始化音频流管理器
qcm_aud_stream_write()	向播放流写入音频数据
qcm_aud_stream_read()	从录制流读取音频数据
qcm_aud_stream_close()	关闭音频流并释放资源
qosa_aud_callback_t()	处理音频事件通知

函数详解¶

qcm_aud_stream_open¶

功能描述
初始化音频流管理器，支持格式：WAV、MP3、AMR-NB、PCM。
函数原型

qosa_aud_errcode_e qcm_aud_stream_open(qosa_aud_stream_cfg_t *config, qosa_aud_handle_t *handle)

参数说明

参数名	输入/输出	类型	说明
config	输入	qosa_aud_stream_cfg_t*	音频流配置结构体指针，用于设置音频流的各项参数；详见 qosa_aud_stream_cfg_t
handle	输出	qosa_aud_handle_t *	返回创建的音频流句柄

返回值说明
QOSA_AUD_SUCCESS：函数执行成功
错误码（详见 qosa_aud_errcode_e）：函数执行失败

qcm_aud_stream_write¶

功能描述
向播放流写入音频数据。
函数原型

qosa_int32_t qcm_aud_stream_write(qosa_aud_handle_t handle, qosa_uint8_t *data, qosa_uint32_t size)

参数说明

参数名	输入/输出	类型	说明
handle	输入	qosa_aud_handle_t	由 qcm_aud_stream_open() 返回的播放流句柄
data	输入	qosa_uint8_t *	指向待播放音频数据的缓冲区
size	输入	qosa_uint32_t	待写入数据的字节数；单位：字节

返回值说明
实际写入的字节数：函数执行成功
错误码（详见 qosa_aud_errcode_e）：函数执行失败

qcm_aud_stream_read¶

功能描述
从录制流读取音频数据。此函数仅当 sync_mode= QOSA_FALSE，即异步模式下有效。
函数原型

qosa_int32_t qcm_aud_stream_read(qosa_aud_handle_t handle, qosa_uint8_t *data, qosa_uint32_t size)

参数说明

参数名	输入/输出	类型	说明
handle	输入	qosa_aud_handle_t	由 qcm_aud_stream_open() 返回的录制流句柄
data	输出	qosa_uint8_t *	存储读取数据的缓冲区
size	输入	qosa_uint32_t	要读取数据的字节数；单位：字节

返回值说明
实际读取的字节数：函数执行成功
错误码（详见 qosa_aud_errcode_e）：函数执行失败

qcm_aud_stream_close¶

功能描述
关闭音频流并释放资源。
函数原型

qosa_int32_t qcm_aud_stream_close(qosa_aud_handle_t handle, qosa_bool_t force)

参数说明

参数名	输入/输出	类型	说明
handle	输入	qosa_aud_handle_t	要关闭的音频流句柄
force	输入	qosa_bool_t	是否强制关闭（当前未使用，保留参数）

返回值说明
0：函数执行成功
错误码（详见 qosa_aud_errcode_e）：函数执行失败

qosa_aud_callback_t¶

功能描述
处理音频事件通知。
函数原型

typedef void (*qosa_aud_callback_t)(qosa_aud_cb_param_t *param);

参数说明

参数名	输入/输出	类型	说明
param	输入	qosa_aud_cb_param_t*	回调参数结构体指针；详见 qosa_aud_cb_param_t

结构体定义¶

qosa_aud_stream_cfg_t¶

音频流配置结构体定义如下：

typedef struct
{
    qosa_bool_t         is_record;
    qosa_uint16_t       samprate;
    qosa_uint8_t        channels;
    qosa_bool_t         sync_mode;
    qosa_aud_fmt_e      format;
    qosa_aud_callback_t callback;
    qosa_uint8_t       *ctx;
    qosa_uint64_t       options;
} qosa_aud_stream_cfg_t;

参数	类型	说明
is_record	qosa_bool_t	是否为录音模式 QOSA_FALSE：播放模式 QOSA_TRUE：录制模式
samprate	qosa_uint16_t	音频采样率；取值范围：8000、16000、22050、32000、44100和48000，单位：Hz。
channels	qosa_uint8_t	音频通道数 1：单声道（mono） 2：立体声（stereo）
sync_mode	qosa_bool_t	同步/异步模式标志 QOSA_TRUE：同步模式 QOSA_FALSE：异步模式
format	qosa_aud_fmt_e	音频格式枚举类型；详见 qosa_aud_fmt_e
callback	qosa_aud_callback_t	回调函数指针，用于接收音频事件通知；详见 qosa_aud_callback_t
ctx	qosa_uint8_t *	用户上下文指针，传递给回调函数
options	qosa_uint64_t	保留字段，用于扩展功能

qosa_aud_cb_param_t¶

回调参数结构体定义如下：

typedef struct
{
    qosa_aud_handle_t handle;   
    qosa_int32_t      event_id; 
    qosa_uint32_t     size;     
    qosa_uint8_t     *ctx;      
} qosa_aud_cb_param_t;

参数	类型	说明
handle	qosa_aud_handle_t	音频流句柄
event_id	qosa_int32_t	事件ID，标识触发回调的具体事件；详见 qosa_stream_evt_e
size	qosa_uint32_t	数据大小字节数；单位：字节
ctx	qosa_uint8_t *	用户上下文指针，对应 qosa_aud_stream_cfg_t 中配置的 ctx

枚举定义¶

qosa_aud_errcode_e¶

音频流操作结果码枚举定义如下：

typedef enum
{
    QOSA_AUD_SUCCESS,
    QOSA_AUD_INVALID_PARAM = 1 | (QOSA_COMPONENT_AUDIO << 16),
    QOSA_AUD_MUTEX_ERR,
    QOSA_AUD_NO_MEMORY_ERR,
    QOSA_AUD_SYSTEM_ERR,
    QOSA_AUD_REOPEN_ERR,
    QOSA_AUD_FILE_OPEN_ERR,
    QOSA_AUD_FILE_WRITE_ERR,
} qosa_aud_errcode_e;

成员	说明
QOSA_AUD_SUCCESS	函数执行成功
QOSA_AUD_INVALID_PARAM	输入参数错误
QOSA_AUD_MUTEX_ERR	互斥锁获取失败
QOSA_AUD_NO_MEMORY_ERR	内存分配失败
QOSA_AUD_SYSTEM_ERR	系统或驱动层错误
QOSA_AUD_REOPEN_ERR	禁止重复打开音频流
QOSA_AUD_FILE_OPEN_ERR	音频文件打开失败
QOSA_AUD_FILE_WRITE_ERR	音频文件写入失败

qosa_aud_fmt_e¶

音频数据格式枚举定义如下：

typedef enum
{
    QOSA_AUD_FMT_UNKNOWN,
    QOSA_AUD_FMT_PCM,
    QOSA_AUD_FMT_WAV,
    QOSA_AUD_FMT_MP3,
    QOSA_AUD_FMT_AMRNB,
    QOSA_AUD_FMT_AMRWB,
} qosa_aud_fmt_e;

成员	说明
QOSA_AUD_FMT_UNKNOWN	未知/未指定格式
QOSA_AUD_FMT_PCM	PCM
QOSA_AUD_FMT_WAV	WAV
QOSA_AUD_FMT_MP3	MP3
QOSA_AUD_FMT_AMRNB	AMR-NB；采样率：8 kHz
QOSA_AUD_FMT_AMRWB	AMR-WB；采样率：16 kHz

qosa_stream_evt_e¶

回调事件类型枚举定义如下：

typedef enum
{
    QOSA_AUD_STREAM_RX_ARRIVE = 100,  
    QOSA_AUD_STREAM_RX_START,         
    QOSA_AUD_STREAM_RX_LOW,          
    QOSA_AUD_STREAM_RX_HIGH,          

    QOSA_AUD_DECODE_COMPLETE = 200,   
    QOSA_AUD_DECODE_START,            
    QOSA_AUD_DECODE_LOW_LEVEL,        
    QOSA_AUD_DECODE_ERROR,           

    QOSA_AUD_DRIVER_TX_COMPLETE = 300,
    QOSA_AUD_DRIVER_TX_LOW,           
    QOSA_AUD_DRIVER_TX_START,         
    QOSA_AUD_DRIVER_RX_OVERFLOW,      
    QOSA_AUD_DRIVER_RX_HIGH,         
} qosa_stream_evt_e;

成员	说明
QOSA_AUD_STREAM_RX_ARRIVE	收到数据
QOSA_AUD_STREAM_RX_START	开始接收数据
QOSA_AUD_STREAM_RX_LOW	接收缓冲区数据不足，通知上层提供更多数据
QOSA_AUD_STREAM_RX_HIGH	接收缓冲区数据充足，通知上层暂停数据传输
QOSA_AUD_DECODE_COMPLETE	解码完成
QOSA_AUD_DECODE_START	开始解码
QOSA_AUD_DECODE_LOW_LEVEL	解码缓冲区数据不足，通知上层提供更多数据
QOSA_AUD_DECODE_ERROR	解码错误
QOSA_AUD_DRIVER_TX_COMPLETE	驱动发送完成
QOSA_AUD_DRIVER_TX_LOW	驱动发送缓冲区数据不足，通知上层提供更多数据
QOSA_AUD_DRIVER_TX_START	驱动开始发送
QOSA_AUD_DRIVER_RX_OVERFLOW	驱动接收溢出
QOSA_AUD_DRIVER_RX_HIGH	驱动接收缓冲区数据充足，通知上层及时读取数据，防止缓冲区溢出

应用逻辑流程图¶

播放流程图¶

录制流程图¶

示例代码¶

播放流程完整示例代码请查看：

https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/peripheral/audio/audio_play.c

录制流程完整示例代码请查看：

https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/peripheral/audio/audio_recording.c