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

一、概述

xt_audio_tts 是将 UTF-8 文本合成为 PCM 音频数据的 TTS 引擎模块。引擎分块返回合成结果，用户通过回调接收 PCM 数据后，自行调用 xt_audio_dev_write() 写入设备播放。分离 TTS 合成与音频输出，用户可自行决定是否播放（如仅保存为文件）。

1.1 设计原则

合成与播放分离 ：TTS 只负责文本→PCM 转换，不直接操作音频设备
分块回调 ：每次合成一段音频块即通过 SYNTHESIZE_CHUNK 回调推送，适合实时播放
资源位置可配 ：支持内部资源和外置 Flash 两种资源存储位置

1.2 依赖

依赖	用途
xt_audio_types.h	音频句柄、格式、通用回调类型

二、核心概念

2.1 TTS 合成流程

xt_audio_tts_play(text)
    → 引擎逐块合成
    → SYNTHESIZE_CHUNK 回调（每块 PCM）
        → 用户在回调中 write 到设备
    → SYNTHESIZE_CMPLT 回调（全部完成）

合成过程中，用户需在 SYNTHESIZE_CHUNK 回调中将 info->data 写入音频设备。回调中的 info->fmt 包含本次合成数据的音频格式（与设备格式可能存在差异）。

2.2 TTS 事件

事件	说明
XT_AUDIO_TTS_EVT_NO_ERR	无错误
XT_AUDIO_TTS_EVT_SYNTHESIZE_CHUNK	合成了一块音频数据， info->data / info->size 有效
XT_AUDIO_TTS_EVT_SYNTHESIZE_CMPLT	全部合成完成
XT_AUDIO_TTS_EVT_SYNTHESIZE_ABORT	合成被中止（调用 stop 或资源冲突）
XT_AUDIO_TTS_EVT_SYNTHESIZE_ERROR	合成出错

2.3 TTS 配置与播放参数

参数	所在结构体	说明
wq_num	config	工作队列个数
user_cb	config / info	用户回调（config 中为默认回调，info 中为单次覆盖）
user_data	config / info	回调用户数据
prior	config / info	优先级
level	config / info	音量等级
prior	play_ext.info	优先级
level	play_ext.info	音量等级

2.4 资源位置

枚举值	说明
XT_AUDIO_TTS_RES_LOC_INTERNAL	内部资源（默认）
XT_AUDIO_TTS_RES_LOC_EXTERNAL	外置 Flash ，需通过 part_name 指定分区名

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_audio_tts（TTS 语音合成）。

3.1 资源管理

函数签名	说明
xt_err_t xt_audio_tts_set_resource_location(enum xt_tts_res_location loc, char *part_name)	设置 TTS 资源位置

3.2 生命周期

函数签名	说明
xt_err_t xt_audio_tts_setup(struct xt_audio_tts_config cfg, xt_audio_t hdl)	初始化 TTS 模块
xt_err_t xt_audio_tts_close(xt_audio_t hdl)	关闭 TTS 模块

3.3 播放与控制

函数签名	说明
int xt_audio_tts_play_ext(xt_audio_t hdl, const char text, uint32_t size, struct xt_audio_tts_info info)	TTS 播放（扩展版，info 可为 NULL ）
#define xt_audio_tts_play(_hdl, _text, _size, _prior, _level)	TTS 播放（简化版，设优先级和音量）
xt_err_t xt_audio_tts_stop(xt_audio_t hdl)	停止 TTS 合成
int xt_audio_tts_is_stopping(xt_audio_t hdl)	查询是否正在停止

3.4 类型

类型签名	说明
typedef struct xt_audio_tts（TTS 语音合成） *xt_audio_tts_t	TTS 实例句柄
enum xt_audio_tts_evt	TTS 事件枚举（ CHUNK / CMPLT / ABORT / ERROR ）
struct xt_audio_tts_cb_info	TTS 回调信息（ data / size / fmt / prior / level ）
void (xt_audio_tts_cb_t)(xt_audio_t hdl, enum xt_audio_tts_evt evt, struct xt_audio_tts_cb_info info)	TTS 回调类型
struct xt_audio_tts_config	TTS 配置（ wq_num + 默认回调/参数）
struct xt_audio_tts_info	TTS 播放扩展参数

四、常见模式

4.1 TTS 播放——回调中写入设备

#include "xt_audio_dev.h"
#include "xt_audio_tts.h"
 
static xt_audio_t s_dev = NULL;
 
static void _tts_cb(xt_audio_t hdl, enum xt_audio_tts_evt evt,
                    struct xt_audio_tts_cb_info *info)
{
    switch (evt) {
    case XT_AUDIO_TTS_EVT_SYNTHESIZE_CHUNK:
        /* 每合成一块就写入设备 */
        {
            int r;
            do {
                r = xt_audio_dev_write(s_dev, info->data, info->size, info->level);
                if (r == XT_EFULL) osDelay(5);
            } while (r == XT_EFULL);
        }
        break;
    case XT_AUDIO_TTS_EVT_SYNTHESIZE_CMPLT:
        /* 合成完成 */
        break;
    case XT_AUDIO_TTS_EVT_SYNTHESIZE_ERROR:
        /* 出错处理 */
        break;
    default:
        break;
    }
}
 
void tts_example(void)
{
    /* 1. 初始化设备 */
    struct xt_audio_dev_config dev_cfg = {
        .drv_name = "codec",
        .mode = XT_AUDIO_MODE_OUT,
        .sample_freq = 8000,
        .sample_bits = 16,
        .channel_num = 1,
        .frame_size = 640,
        .write_wq_num = 8,
    };
    xt_audio_dev_setup(&dev_cfg, &s_dev);
 
    /* 2. 初始化 TTS */
    xt_audio_t tts = NULL;
    struct xt_audio_tts_config tts_cfg = {
        .wq_num = 4,
        .user_cb = _tts_cb,
    };
    xt_audio_tts_setup(&tts_cfg, &tts);
 
    /* 3. 播放 */
    const char *text = "你好，这是 T T S 播放测试";
    xt_audio_tts_play(tts, text, strlen(text), 0, 70);
 
    /* 4. 等待合成完成（实际应通过回调通知） */
    osDelay(3000);
 
    /* 5. 清理 */
    xt_audio_tts_close(tts);
    xt_audio_dev_close(s_dev);
}

4.2 中途停止播放

/* 发起播放 */
xt_audio_tts_play(tts, long_text, sizeof(long_text), 0, 70);
 
/* 中途停止 */
osDelay(2000);
xt_audio_tts_stop(tts);
/* 等待停止完成 */
while (xt_audio_tts_is_stopping(tts)) {
    osDelay(10);
}
/* 此时可再次播放 */

五、已知行为与限制

行为	说明
合成与输出分离	TTS 不自动写入设备，用户必须在回调中手动 xt_audio_dev_write
play_ext 的 info 可为 NULL	为 NULL 时使用 setup 时传入的默认回调
SYNTHESIZE_CHUNK 的数据一次性	回调返回后数据即失效，用户必须及时消费或拷贝
stop 异步	xt_audio_tts_stop 返回后合成仍在终止中，需通过 is_stopping 或 SYNTHESIZE_ABORT 回调确认
外部资源需先调用 set_resource_location	使用外置 Flash 资源时，setup 前必须先设置资源位置