# TTS语音合成API **本文档引用的文件** - [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts) - [tts.service.ts](file://server/src/modules/tts/tts.service.ts) - [aliyun.provider.ts](file://server/src/modules/tts/aliyun.provider.ts) - [minimax.provider.ts](file://server/src/modules/tts/minimax.provider.ts) - [mock.provider.ts](file://server/src/modules/tts/mock.provider.ts) - [audio-merger.ts](file://server/src/modules/tts/audio-merger.ts) - [types/index.ts](file://server/src/types/index.ts) - [config/index.ts](file://server/src/config/index.ts) - [config/models.json](file://server/src/config/models.json) - [API.md](file://docs/API.md) ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构概览](#架构概览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考虑](#性能考虑) 8. [故障排除指南](#故障排除指南) 9. [结论](#结论) ## 简介 TTS语音合成模块是AI有声书系统的核心组件，提供高质量的文本转语音服务。该模块支持多种音色提供商，包括阿里云百炼、MiniMax等，并具备智能降级机制，确保在各种网络环境下都能稳定运行。 主要功能特性： - 多音色支持：10种不同风格的音色选择 - 智能参数调节：速度、音调、音量三参数控制 - 多提供商集成：阿里云、MiniMax、模拟服务 - 异步生成：支持大文本的异步音频生成 - 智能降级：API Key缺失时自动使用模拟服务 - 文件管理：完整的音频文件存储和生命周期管理 ## 项目结构 TTS模块采用清晰的分层架构设计，按照职责分离的原则组织代码： ```mermaid graph TB subgraph "TTS模块架构" Controller[tts.controller.ts
HTTP接口控制器] Service[tts.service.ts
业务逻辑服务] subgraph "Provider层" Aliyun[AliyunTtsProvider
阿里云百炼] MiniMax[MiniMaxTtsProvider
MiniMax] Mock[MockTtsProvider
模拟服务] end subgraph "工具层" Merger[AudioMerger
音频合并器] Config[配置管理] Types[类型定义] end Controller --> Service Service --> Aliyun Service --> MiniMax Service --> Mock Service --> Merger Service --> Config Service --> Types end ``` **图表来源** - [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274) - [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715) **章节来源** - [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274) - [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715) ## 核心组件 ### 音色列表管理 系统提供10种精心挑选的音色，涵盖不同性别和风格： | 音色ID | 名称 | 性别 | 描述 | |--------|------|------|------| | cherry | 芊悦 | 女性 | 阳光积极、亲切自然 | | serena | 苏瑶 | 女性 | 温柔女声 | | ethan | 晨煦 | 男性 | 阳光温暖、活力男声 | | chelsie | 千雪 | 女性 | 二次元虚拟女友 | | momo | 茉兔 | 女性 | 撒娇搞怪 | | vivian | 十三 | 女性 | 可爱小暴躁 | | moon | 月白 | 男性 | 率性帅气 | | maia | 四月 | 女性 | 知性温柔 | | kai | 凯 | 男性 | 舒缓放松 | | nofish | 不吃鱼 | 男性 | 不会翘舌音 | ### 音频参数配置 音色参数通过统一的VoiceParams接口进行管理： ```mermaid classDiagram class VoiceParams { +number speed +number pitch +number volume } class AliyunTtsProvider { +synthesize(text, voiceId, params, outputPath) string -apiKey string -model string -voice string } class MiniMaxTtsProvider { +synthesize(text, voiceId, params, outputPath) string -apiKey string -createTask(text, voiceId, params) Promise -queryTask(task_id, task_token) Promise } VoiceParams --> AliyunTtsProvider : "配置参数" VoiceParams --> MiniMaxTtsProvider : "配置参数" ``` **图表来源** - [types/index.ts:40-44](file://server/src/types/index.ts#L40-L44) - [aliyun.provider.ts:21-29](file://server/src/modules/tts/aliyun.provider.ts#L21-L29) - [minimax.provider.ts:237-278](file://server/src/modules/tts/minimax.provider.ts#L237-L278) **章节来源** - [types/index.ts:40-44](file://server/src/types/index.ts#L40-L44) - [tts.service.ts:24-36](file://server/src/modules/tts/tts.service.ts#L24-L36) ## 架构概览 TTS模块采用多提供商架构，支持动态切换和智能降级： ```mermaid sequenceDiagram participant Client as 客户端 participant Controller as 控制器 participant Service as 服务层 participant Provider as 供应商 participant Storage as 存储服务 Client->>Controller : POST /api/tts/generate Controller->>Service : generateAudio(userId, text, voiceId, params) Service->>Service : getTtsProvider(text, voiceId) alt 阿里云可用 Service->>Provider : AliyunTtsProvider Provider-->>Service : 音频文件路径 else MiniMax可用 Service->>Provider : MiniMaxTtsProvider Provider-->>Service : 音频文件路径 else 模拟服务 Service->>Provider : MockTtsProvider Provider-->>Service : 占位音频文件 end Service->>Storage : 上传音频文件 Storage-->>Service : 文件URL Service-->>Controller : 音频信息 Controller-->>Client : 生成结果 Note over Service,Storage : 异步处理，立即返回任务ID ``` **图表来源** - [tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127) - [tts.service.ts:200-280](file://server/src/modules/tts/tts.service.ts#L200-L280) ## 详细组件分析 ### 音色列表接口（GET /api/tts/voices） 该接口提供可用音色的完整列表，支持客户端音色选择和预览功能。 **请求格式** - 方法：GET - 路径：/api/tts/voices - 认证：可选 **响应结构** ```json { "code": 0, "message": "success", "data": { "voices": [ { "id": "cherry", "name": "芊悦", "gender": "female", "description": "阳光积极、亲切自然" } ] } } ``` **章节来源** - [tts.controller.ts:12-21](file://server/src/modules/tts/tts.controller.ts#L12-L21) - [tts.service.ts:599-602](file://server/src/modules/tts/tts.service.ts#L599-L602) ### 音频生成接口（POST /api/tts/generate） 异步音频生成接口，支持大文本处理和多种音色提供商。 **请求格式** - 方法：POST - 路径：/api/tts/generate - 认证：可选 - 内容类型：application/json **请求参数** ```json { "text": "要转换的文本内容", "voiceId": "cherry", "voiceParams": { "speed": 1.0, "pitch": 0, "volume": 50 }, "bookId": "123", "chapterTitle": "第一章", "ttsProvider": "minimax" } ``` **响应结构** ```json { "code": 0, "message": "音频生成任务已创建", "data": { "audioId": "550e8400-e29b-41d4-a716-446655440000", "audioUrl": "" } } ``` **章节来源** - [tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127) - [tts.service.ts:200-280](file://server/src/modules/tts/tts.service.ts#L200-L280) ### 音频参数配置详解 #### 速度参数（speed） - 范围：0.5 - 2.0 - 默认值：1.0 - 影响：控制语音播放速度 - 调优建议： - 0.8-1.2：正常语速范围 - 1.2-1.5：稍快，适合新闻播报 - 1.5以上：快速阅读场景 #### 音调参数（pitch） - 范围：-500 - 500 - 默认值：0 - 影响：控制声音高低 - 调优建议： - -200-200：自然音域 - -500-(-200)：低沉磁性 - 200-500：清脆明亮 #### 音量参数（volume） - 范围：0 - 100 - 默认值：50 - 影响：控制音频响度 - 调优建议： - 30-70：标准音量 - 70以上：响亮场景 - 30以下：轻声细语 ### 音色提供商集成 #### 阿里云百炼（DashScope） - 适用场景：高质量中文语音合成 - 特点：支持指令模型，参数控制精确 - 配置要求：需要有效的API Key #### MiniMax - 适用场景：异步长文本处理 - 特点：支持长文本一次性合成 - 配置要求：需要有效的API Key #### 模拟服务 - 适用场景：开发调试和演示 - 特点：无需外部API，快速响应 - 限制：质量较低，仅作占位 **章节来源** - [tts.service.ts:160-190](file://server/src/modules/tts/tts.service.ts#L160-L190) - [aliyun.provider.ts:21-150](file://server/src/modules/tts/aliyun.provider.ts#L21-L150) - [minimax.provider.ts:53-278](file://server/src/modules/tts/minimax.provider.ts#L53-L278) ### 音频文件存储与管理 #### 存储位置 - 本地路径：`{项目根目录}/uploads/{audioId}/output.mp3` - 访问方式：通过`/uploads/{audioId}/output.mp3`访问 - 生命周期：生成后长期保存，支持重复访问 #### 文件结构 ``` uploads/ ├── 550e8400-e29b-41d4-a716-446655440000/ │ ├── segment_0.mp3 │ ├── segment_1.mp3 │ └── output.mp3 └── b42de876-f54c-42e5-b827-557766551100/ └── output.mp3 ``` #### 生命周期管理 1. **生成阶段**：创建临时目录，保存分段音频 2. **合并阶段**：合并所有分段为完整音频 3. **上传阶段**：上传到存储服务，生成永久URL 4. **清理阶段**：保留必要文件，定期清理临时文件 **章节来源** - [tts.service.ts:218-225](file://server/src/modules/tts/tts.service.ts#L218-L225) - [audio-merger.ts:11-36](file://server/src/modules/tts/audio-merger.ts#L11-L36) ## 依赖关系分析 TTS模块的依赖关系呈现清晰的单向依赖结构： ```mermaid graph TD subgraph "外部依赖" Axios[Axios HTTP库] FS[文件系统] Path[路径处理] Child[子进程] end subgraph "核心模块" Controller[tts.controller.ts] Service[tts.service.ts] Types[types/index.ts] Config[config/index.ts] end subgraph "Provider实现" Aliyun[aliyun.provider.ts] MiniMax[minimax.provider.ts] Mock[mock.provider.ts] end subgraph "工具组件" Merger[audio-merger.ts] Models[config/models.json] end Controller --> Service Service --> Types Service --> Config Service --> Merger Service --> Aliyun Service --> MiniMax Service --> Mock Service --> Models Aliyun --> Axios MiniMax --> Axios Mock --> Child Service --> FS Service --> Path Merger --> FS Merger --> Child ``` **图表来源** - [tts.controller.ts:1-10](file://server/src/modules/tts/tts.controller.ts#L1-L10) - [tts.service.ts:1-15](file://server/src/modules/tts/tts.service.ts#L1-L15) **章节来源** - [tts.service.ts:1-25](file://server/src/modules/tts/tts.service.ts#L1-L25) ## 性能考虑 ### 并发处理 - **分段并发**：默认并发2个分段同时生成 - **长文本处理**：MiniMax支持单次异步处理 - **重试机制**：提供指数退避重试，避免服务过载 ### 缓存策略 - **配置缓存**：模型配置一次性加载 - **音色映射**：音色ID到提供商音色的映射缓存 - **日志文件**：统一的日志文件记录，便于性能监控 ### 内存管理 - **流式处理**：大型音频文件采用流式下载 - **分段处理**：避免大文本一次性加载内存 - **及时清理**：生成完成后及时释放资源 ## 故障排除指南 ### 常见错误及解决方案 #### 1. API Key配置错误 **症状**：服务调用失败，返回401或403错误 **解决方案**： - 检查`.env`文件中的API Key配置 - 验证API Key的有效性和权限 - 确认网络连接正常 #### 2. 速率限制 **症状**：请求被拒绝，返回429状态码 **解决方案**： - 实现指数退避重试 - 降低请求频率 - 考虑升级服务套餐 #### 3. 网络超时 **症状**：请求超时，服务不可用 **解决方案**： - 增加超时时间配置 - 检查网络连接稳定性 - 考虑使用CDN加速 #### 4. 音频生成失败 **症状**：生成任务失败，文件损坏 **解决方案**： - 检查磁盘空间充足 - 验证FFmpeg安装正确 - 查看日志文件定位具体错误 ### 调试工具 #### 日志文件 - **位置**：`tts-debug.log` - **内容**：详细的生成过程日志 - **用途**：问题诊断和性能分析 #### 状态检查 ```bash # 检查服务状态 curl -X GET http://localhost:3000/api/tts/test-db # 获取音色列表 curl -X GET http://localhost:3000/api/tts/voices # 检查提供商状态 curl -X GET http://localhost:3000/api/tts/providers ``` **章节来源** - [tts.service.ts:16-22](file://server/src/modules/tts/tts.service.ts#L16-L22) - [tts.controller.ts:34-50](file://server/src/modules/tts/tts.controller.ts#L34-L50) ## 结论 TTS语音合成模块通过精心设计的架构和完善的错误处理机制，为AI有声书系统提供了稳定可靠的语音合成服务。模块的主要优势包括： 1. **多提供商支持**：灵活的提供商选择和自动降级机制 2. **智能参数控制**：精确的音色参数调节能力 3. **异步处理**：高效的长文本处理和并发控制 4. **完整生命周期管理**：从生成到存储的全流程管理 5. **完善的错误处理**：多层次的错误检测和恢复机制 通过合理的配置和调优，该模块能够满足不同场景下的语音合成需求，为用户提供优质的AI有声书体验。