# Audio

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

本文档描述音频功能的接口定义、使用流程及示例代码。音频模块支持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。

- **函数原型**

```c
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*](#qosaaudstreamcfgt) |
| *handle* | 输出 | qosa_aud_handle_t * | 返回创建的音频流句柄 |

- **返回值说明**  
  *QOSA_AUD_SUCCESS*：函数执行成功  
  错误码（详见 [*qosa_aud_errcode_e*](#qosaauderrcode_e)）：函数执行失败

### qcm_aud_stream_write

- **功能描述**  
  向播放流写入音频数据。

- **函数原型**

```c
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*](#qosaauderrcode_e)）：函数执行失败

### qcm_aud_stream_read

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

- **函数原型**

```c
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*](#qosaauderrcode_e)）：函数执行失败

### qcm_aud_stream_close

- **功能描述**  
  关闭音频流并释放资源。

- **函数原型**

```c
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*](#qosaauderrcode_e)）：函数执行失败

### qosa_aud_callback_t

- **功能描述**  
  处理音频事件通知。 

- **函数原型**

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

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *param* | 输入 | *qosa_aud_cb_param_t** | 回调参数结构体指针；详见 [*qosa_aud_cb_param_t*](#qosaaudcbparamt) |

## 结构体定义

### qosa_aud_stream_cfg_t

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

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

### qosa_aud_cb_param_t

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

```c
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*](#qosastreamevt_e) |
| *size* | qosa_uint32_t | 数据大小字节数；单位：字节 |
| *ctx* | qosa_uint8_t * | 用户上下文指针，对应 *qosa_aud_stream_cfg_t* 中配置的 *ctx* |

## 枚举定义

### qosa_aud_errcode_e

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

```c
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

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

```c
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

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

```c
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* | 驱动接收缓冲区数据充足，通知上层及时读取数据，防止缓冲区溢出 |

# 应用逻辑流程图

## 播放流程图

```{figure} images/board_JiNowZ1X2h8hneboZMRc308InKx.jpg
:align: center
:alt: image
```

## 录制流程图

```{figure} images/board_RLO6wjwUUhl6Nobz0kvcxcuznF7.jpg
:align: center
:alt: image
```

# 示例代码

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

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