xt_audio_types - 音频公共类型定义

版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_audio/

---

一、概述

xt_audio_types 是 xt_audio 子系统的公共类型定义模块，声明所有子模块（设备层、驱动层、TTS、服务层）共享的句柄、枚举、回调类型和格式结构体。本模块为纯类型定义，无 API 函数。

1.1 设计原则

• 句柄统一 ：设备、TTS、服务层均使用同一个 xt_audio_t 句柄类型，便于模块间传递
• 模式位掩码 ：IN/OUT 方向用位标志表示，支持按位或组合全双工模式

1.2 依赖

依赖	用途
xt_error.h	错误码类型定义

---

二、核心概念

2.1 句柄类型

xt_audio_t 是 void * 的别名，设备、TTS 实例、服务实例均通过该类型引用。不同模块的句柄不可混用。

2.2 模式枚举

6 个预定义值是 2 个方向的 4 种语义别名：

枚举值	值	语义
XT_AUDIO_MODE_OUT	(1 << 0)	输出/播放方向
XT_AUDIO_MODE_IN	(1 << 1)	输入/录音方向
XT_AUDIO_MODE_WRITE	(1 << 0)	写模式（等同 OUT）
XT_AUDIO_MODE_READ	(1 << 1)	读模式（等同 IN）
XT_AUDIO_MODE_PLAY	(1 << 0)	播放模式（等同 OUT）
XT_AUDIO_MODE_RECORD	(1 << 1)	录音模式（等同 IN）

另有编码/解码语义别名 XT_AUDIO_MODE_ENC / XT_AUDIO_MODE_DEC ，值同 OUT/IN。全双工模式通过 XT_AUDIO_MODE_IN | XT_AUDIO_MODE_OUT 组合使用。

2.3 音频格式

struct xt_audio_format 描述音频数据格式：

字段	类型	说明
sample_freq	uint16_t	采样率（如 8000、16000）
sample_bits	uint8_t	采样位深（如 16）
channel_num	uint8_t	通道数（如 1）
frame_size	uint16_t	帧大小（字节）

frame_size 计算公式：

frame_size = sample_freq * (sample_bits / 8) * channel_num * frame_ms / 1000

---

三、类型参考

以下为类型签名大纲，完整的字段说明、枚举值请查看 xt_audio_types（音频类型定义） 。

3.1 句柄

类型签名	说明
typedef void *xt_audio_t	音频句柄类型

3.2 模式

类型签名	说明
typedef uint8_t xt_audio_mode_t	音频模式类型，值为 OUT/IN 等枚举
typedef uint8_t xt_audio_prior_t	音频优先级类型

3.3 回调

类型签名	说明
void (*xt_audio_cb_t)(xt_audio_t hdl, int evt, void *info)	通用回调函数类型

3.4 结构体

类型签名	说明
struct xt_audio_format	音频格式描述（采样率、位深、通道、帧大小）