xt_audio_svc - 音频服务

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

---

一、概述

xt_audio_svc 是音频服务层，封装了 TTS 合成、文件解码和音频设备写入的完整链路。用户只需一行调用即可完成 TTS 播放或音频文件播放，无需关心底层 TTS 回调、写入重试、格式匹配等细节。

1.1 设计原则

• 一行调用 ： xt_audio_svc_tts_play() / xt_audio_svc_file_play() 封装了 dev + tts 的完整流程
• 事件驱动 ：播放完成/出错/中止通过全局或局部回调通知用户
• 互斥执行 ：同一时间只允许一个服务运行，再次调用返回 XT_EBUSY
• stop 异步 ： xt_audio_svc_stop() 返回后仍需等待回调确认

1.2 依赖

依赖	用途
xt_audio_types.h	音频句柄类型

1.3 与其他模块的关系

xt_audio_svc （统一入口）
    ├── 内部管理 xt_audio_tts （TTS 合成）
    ├── 内部管理文件解码器（支持 .amr/.mp3/.wav/.opus）
    └── 内部调用 xt_audio_dev_write() （写入设备）

---

二、核心概念

2.1 服务类型

枚举值	说明
XT_AUDIO_SVC_TTS	TTS 服务
XT_AUDIO_SVC_FILE	文件播放服务
XT_AUDIO_SVC_ANY	任意服务（stop 时用于停止所有）

2.2 服务事件

事件	说明
XT_AUDIO_SVC_EVT_TTS_CMPLT	TTS 播放完成
XT_AUDIO_SVC_EVT_TTS_ERROR	TTS 播放出错
XT_AUDIO_SVC_EVT_TTS_ABORT	TTS 播放被中止
XT_AUDIO_SVC_EVT_FILE_CMPLT	文件播放完成
XT_AUDIO_SVC_EVT_FILE_ERROR	文件播放出错
XT_AUDIO_SVC_EVT_FILE_ABORT	文件播放被中止

2.3 回调机制

支持两种回调注册方式：

方式	函数	作用范围
全局回调	xt_audio_svc_register_evt_cb()	所有服务的默认回调
局部回调	xt_audio_svc_tts_info.cb / xt_audio_svc_file_info.cb	单次播放的专用回调（非 NULL 时优先于全局）

2.4 文件格式支持

xt_audio_svc_file_play() 支持以下音频格式：

格式	扩展名	说明
AMR	.amr	8kHz 单声道
MP3	.mp3	16kHz 单声道
WAV	.wav	16kHz 单声道
OPUS	.opus	16kHz 单声道

设备采样率需与文件格式匹配（如 AMR 用 8kHz，其他用 16kHz）。

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_audio_svc（音频服务） 。

3.1 回调注册

函数签名	说明
xt_err_t xt_audio_svc_register_evt_cb(xt_audio_svc_evt_cb_t cb, void *user_data)	注册全局事件回调

3.2 TTS 播放

函数签名	说明
xt_err_t xt_audio_svc_tts_play_ext(xt_audio_t dev, const char *text, uint32_t size, uint8_t level, struct xt_audio_svc_tts_info *info)	TTS 播放（扩展版），返回 XT_EBUSY 表示有服务占用
#define xt_audio_svc_tts_play(_dev, _text, _size, _level)	TTS 播放（简化版，无局部回调）

3.3 文件播放

函数签名	说明
xt_err_t xt_audio_svc_file_play_ext(xt_audio_t dev, const char *path, uint8_t level, struct xt_audio_svc_file_info *info)	文件播放（扩展版），返回 XT_EBUSY 表示有服务占用
#define xt_audio_svc_file_play(_dev, _path, _level)	文件播放（简化版，无局部回调）

3.4 停止

函数签名	说明
xt_err_t xt_audio_svc_stop(xt_audio_t dev, enum xt_audio_svc_type type)	停止指定类型的服务， XT_AUDIO_SVC_ANY 停止所有

3.5 类型

类型签名	说明
enum xt_audio_svc_evt	服务事件枚举（ TTS_CMPLT/ERROR/ABORT + FILE_CMPLT/ERROR/ABORT ）
enum xt_audio_svc_type	服务类型（ TTS / FILE / ANY ）
void (*xt_audio_svc_evt_cb_t)(xt_audio_t dev, enum xt_audio_svc_evt evt, void *user_data)	事件回调类型
struct xt_audio_svc_tts_info	TTS 播放扩展参数（局部回调 + 用户数据）
struct xt_audio_svc_file_info	文件播放扩展参数（局部回调 + 用户数据）

---

四、常见模式

4.1 TTS 服务播放

#include "xt_audio_dev.h"
#include "xt_audio_svc.h"
 
static volatile enum xt_audio_svc_evt s_last_evt = -1;
 
static void _svc_evt_cb(xt_audio_t dev, enum xt_audio_svc_evt evt, void *user_data)
{
    s_last_evt = evt;
}
 
void svc_tts_example(void)
{
    /* 1. 打开设备 */
    xt_audio_t dev = NULL;
    struct xt_audio_dev_config cfg = {
        .drv_name = "codec",
        .mode = XT_AUDIO_MODE_OUT,
        .sample_freq = 8000,
        .sample_bits = 16,
        .channel_num = 1,
        .frame_size = 640,
        .write_wq_num = 20,
    };
    xt_audio_dev_setup(&cfg, &dev);
 
    /* 2. 注册服务层回调 */
    xt_audio_svc_register_evt_cb(_svc_evt_cb, NULL);
 
    /* 3. 一行调用播放 TTS */
    const char *text = "你好，这是音频服务层 T T S 播放例程";
    s_last_evt = (enum xt_audio_svc_evt) - 1;
    xt_err_t ret = xt_audio_svc_tts_play(dev, text, strlen(text), 70);
    if (ret == XT_EBUSY) {
        /* 有服务正在执行，等待或放弃 */
    }
 
    /* 4. 等待播放完成 */
    while (s_last_evt == (enum xt_audio_svc_evt) - 1) {
        osDelay(50);
    }
 
    /* 5. 清理 */
    xt_audio_dev_close(dev);
}

完整示例见： examples/platform_specific/lm620/audio_svc/src/test_tts_play.c

4.2 文件播放

void svc_file_example(void)
{
    xt_audio_t dev = NULL;
    struct xt_audio_dev_config cfg = {
        .drv_name = "codec",
        .mode = XT_AUDIO_MODE_OUT,
        .sample_freq = 8000,
        .sample_bits = 16,
        .channel_num = 1,
        .frame_size = 640,
        .write_wq_num = 20,
    };
    xt_audio_dev_setup(&cfg, &dev);
 
    xt_audio_svc_register_evt_cb(_svc_evt_cb, NULL);
 
    /* 一行调用播放文件 */
    s_last_evt = (enum xt_audio_svc_evt) - 1;
    xt_audio_svc_file_play(dev, "/test.amr", 70);
 
    while (s_last_evt == (enum xt_audio_svc_evt) - 1) {
        osDelay(50);
    }
 
    xt_audio_dev_close(dev);
}

完整示例见： examples/platform_specific/lm620/audio_svc/src/test_file_play.c

4.3 中途停止

/* 发起播放 */
xt_audio_svc_tts_play(dev, long_text, strlen(long_text), 70);
 
/* 中途停止 */
osDelay(3000);
xt_audio_svc_stop(dev, XT_AUDIO_SVC_TTS);
 
/* 停止后等待回调确认 */
osDelay(100);
/* 此时 s_last_evt 应为 XT_AUDIO_SVC_EVT_TTS_ABORT */
 
/* 停止后可复用——再次播放 */
osDelay(2500);
s_last_evt = (enum xt_audio_svc_evt) - 1;
xt_audio_svc_tts_play(dev, text, strlen(text), 70);
 
while (s_last_evt == (enum xt_audio_svc_evt) - 1) {
    osDelay(50);
}

完整示例见： examples/platform_specific/lm620/audio_test/src/test_svc_tts.c

4.4 局部回调（覆盖全局回调）

/* 全局回调适用于所有服务 */
xt_audio_svc_register_evt_cb(_global_cb, NULL);
 
/* 本次播放使用局部回调 */
struct xt_audio_svc_tts_info info = {
    .cb = _local_cb,
    .user_data = &some_data,
};
xt_audio_svc_tts_play_ext(dev, text, len, 70, &info);
/* _local_cb 优先于 _global_cb */

---

五、已知行为与限制

行为	说明
互斥执行	同一时间只允许一个服务运行，再次调用返回 XT_EBUSY
stop 异步	xt_audio_svc_stop() 返回后服务仍在终止中，需等待回调 _ABORT 事件
stop 后需等待	必须在回调确认后才能发起下一次播放
文件格式需匹配采样率	AMR 用 8kHz ，MP3/WAV/OPUS 用 16kHz ，否则解码异常
设备句柄需预先 setup	传入的 dev 必须是 xt_audio_dev_setup() 返回的有效句柄
全局回调作用全部服务	注册一次即可监听 TTS 和 FILE 的所有事件