# TTS语音合成服务

<cite>
**本文引用的文件**
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [audio-merger.ts](file://server/src/modules/tts/audio-merger.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)
- [aliyun-realtime.provider.ts](file://server/src/modules/tts/aliyun-realtime.provider.ts)
- [ai-summary.service.ts](file://server/src/modules/tts/ai-summary.service.ts)
- [ffmpeg.processor.ts](file://server/src/services/ffmpeg.processor.ts)
- [index.ts](file://server/src/types/index.ts)
- [index.ts](file://server/src/models/index.ts)
- [index.ts](file://server/src/config/index.ts)
- [models.json](file://server/src/config/models.json)
- [models.json](file://deploy-package/server/config/models.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本项目为TTS语音合成服务，提供多供应商音色服务集成（阿里云、MiniMax）、音色选择与管理、参数调节机制，并内置音频合并器、批量音频处理与格式转换能力。系统支持异步生成、状态查询、预览音色、配额控制、AI摘要生成、LRC歌词时间轴生成、以及云端存储上传。文档将从架构、组件、数据流、错误处理、性能优化等方面进行深入说明，并给出实际调用示例与最佳实践。

## 项目结构
TTS模块位于后端server/src/modules/tts下，包含控制器、服务层、各TTS提供商适配器、音频合并器、AI摘要服务等；同时在server/src/services下提供通用的FFmpeg处理器与存储服务；配置文件位于server/src/config与deploy-package/server/config中。

```mermaid
graph TB
subgraph "TTS模块"
C["tts.controller.ts"]
S["tts.service.ts"]
AM["audio-merger.ts"]
AS["ai-summary.service.ts"]
P1["aliyun.provider.ts"]
P2["minimax.provider.ts"]
P3["mock.provider.ts"]
P4["aliyun-realtime.provider.ts"]
end
subgraph "通用服务"
F["ffmpeg.processor.ts"]
CFG["config/index.ts"]
TYPES["types/index.ts"]
PRISMA["models/index.ts"]
end
subgraph "配置"
M1["config/models.json"]
M2["deploy-package/server/config/models.json"]
end
C --> S
S --> P1
S --> P2
S --> P3
S --> P4
S --> AM
S --> AS
AM --> F
S --> CFG
S --> TYPES
S --> PRISMA
CFG --> M1
CFG --> M2
```

**图表来源**
- [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)
- [audio-merger.ts:1-86](file://server/src/modules/tts/audio-merger.ts#L1-L86)
- [ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [models.json:1-186](file://server/src/config/models.json#L1-L186)
- [models.json:1-168](file://deploy-package/server/config/models.json#L1-L168)

**章节来源**
- [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)
- [audio-merger.ts:1-86](file://server/src/modules/tts/audio-merger.ts#L1-L86)
- [ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [models.json:1-186](file://server/src/config/models.json#L1-L186)
- [models.json:1-168](file://deploy-package/server/config/models.json#L1-L168)

## 核心组件
- 控制器层：提供REST接口，负责参数校验、配额检查、调用服务层并返回结果。
- 服务层：封装TTS生成主流程，包括文本分段、并发生成、云端/本地降级、合并与上传、AI摘要、LRC歌词生成、状态查询等。
- 提供商适配器：阿里云HTTP/TTS实时、MiniMax异步长文本、Mock占位。
- 音频合并器：支持本地与远程URL合并、时长探测、格式转换。
- FFmpeg处理器：统一处理远程下载、合并、裁剪、音量调整、格式转换、时长探测等。
- AI摘要服务：生成标题、摘要与标签，支持真实AI与Mock降级。
- 配置与类型：统一模型配置、环境变量、类型定义、数据库连接。

**章节来源**
- [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)
- [aliyun.provider.ts:1-152](file://server/src/modules/tts/aliyun.provider.ts#L1-L152)
- [minimax.provider.ts:1-280](file://server/src/modules/tts/minimax.provider.ts#L1-L280)
- [mock.provider.ts:1-61](file://server/src/modules/tts/mock.provider.ts#L1-L61)
- [aliyun-realtime.provider.ts:1-158](file://server/src/modules/tts/aliyun-realtime.provider.ts#L1-L158)
- [audio-merger.ts:1-86](file://server/src/modules/tts/audio-merger.ts#L1-L86)
- [ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [ai-summary.service.ts:1-169](file://server/src/modules/tts/ai-summary.service.ts#L1-L169)
- [index.ts:1-124](file://server/src/types/index.ts#L1-L124)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)

## 架构总览
系统采用“控制器-服务-适配器-工具”的分层架构。控制器接收请求并进行参数与配额校验，服务层协调提供商适配器与合并器，最终通过存储服务上传至OSS或本地，并持久化到数据库。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Ctrl as "tts.controller"
participant Svc as "tts.service"
participant Prov as "TTS提供商(阿里云/MiniMax/Mock)"
participant Merge as "AudioMerger/FFmpeg"
participant Store as "StorageService"
participant DB as "Prisma"
Client->>Ctrl : POST /tts/generate
Ctrl->>Ctrl : 校验参数/配额
Ctrl->>Svc : generateAudio(userId,text,voiceId,params,options)
Svc->>Svc : 选择提供商/文本分段/并发生成
Svc->>Prov : synthesize(分段, voiceName, params)
Prov-->>Svc : 本地文件路径或云端URL
Svc->>Merge : 合并/时长探测
Merge-->>Svc : 合并后文件/URL
Svc->>Store : uploadAudio(合并文件, audioId)
Store-->>Svc : 返回最终URL
Svc->>DB : 更新AudioRecord/章节状态
Svc-->>Ctrl : 返回audioId/audioUrl
Ctrl-->>Client : 任务创建成功
```

**图表来源**
- [tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [tts.service.ts:200-542](file://server/src/modules/tts/tts.service.ts#L200-L542)
- [audio-merger.ts:9-36](file://server/src/modules/tts/audio-merger.ts#L9-L36)
- [ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

**章节来源**
- [tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [tts.service.ts:200-542](file://server/src/modules/tts/tts.service.ts#L200-L542)
- [audio-merger.ts:9-36](file://server/src/modules/tts/audio-merger.ts#L9-L36)
- [ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

## 详细组件分析

### 控制器层（tts.controller.ts）
- 提供音色列表、可用提供商列表查询。
- 异步生成接口：校验文本与音色、检查用户配额、创建生成任务并立即返回。
- 状态查询接口：基于文件系统与数据库状态返回进度。
- 预览接口：生成短文本预览音频。
- 批量下载接口：返回多个音频的下载信息。

**章节来源**
- [tts.controller.ts:12-274](file://server/src/modules/tts/tts.controller.ts#L12-L274)

### 服务层（tts.service.ts）
- 音色映射与默认书籍管理：维护前端音色ID到阿里云音色的映射，必要时创建默认“我的音频”书籍。
- 文本分段策略：针对阿里云限制进行段落与句子级拆分，保证安全上限。
- 提供商工厂：优先级选择（MiniMax → 阿里云 → Mock），支持显式指定。
- 并发与降级：按提供商类型设置并发度，MiniMax串行，其他并行；云端URL优先下载后统一上传。
- AI摘要与LRC歌词：生成标题、摘要、标签与歌词时间轴。
- 状态查询：基于文件系统与数据库判定处理中/完成/失败。
- 预览生成：短文本快速生成。

```mermaid
flowchart TD
Start(["开始生成"]) --> Split["文本分段"]
Split --> ChooseProv{"选择提供商"}
ChooseProv --> |MiniMax| MM["异步任务创建/轮询/下载"]
ChooseProv --> |阿里云| ALI["HTTP请求/下载/重试"]
ChooseProv --> |Mock| MK["FFmpeg生成占位音频"]
MM --> Merge["合并/时长/上传"]
ALI --> Merge
MK --> Merge
Merge --> AI["AI摘要/LRC歌词"]
AI --> Save["更新数据库/推送事件"]
Save --> End(["完成"])
```

**图表来源**
- [tts.service.ts:98-158](file://server/src/modules/tts/tts.service.ts#L98-L158)
- [tts.service.ts:163-190](file://server/src/modules/tts/tts.service.ts#L163-L190)
- [tts.service.ts:320-383](file://server/src/modules/tts/tts.service.ts#L320-L383)
- [tts.service.ts:428-446](file://server/src/modules/tts/tts.service.ts#L428-L446)
- [tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)

**章节来源**
- [tts.service.ts:24-89](file://server/src/modules/tts/tts.service.ts#L24-L89)
- [tts.service.ts:98-158](file://server/src/modules/tts/tts.service.ts#L98-L158)
- [tts.service.ts:163-190](file://server/src/modules/tts/tts.service.ts#L163-L190)
- [tts.service.ts:320-383](file://server/src/modules/tts/tts.service.ts#L320-L383)
- [tts.service.ts:428-446](file://server/src/modules/tts/tts.service.ts#L428-L446)
- [tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)

### 音频合并器（audio-merger.ts）
- 支持本地与远程URL合并，远程场景委托FFmpeg处理器。
- 本地合并：使用ffmpeg命令进行concat合并，MP3转码。
- 时长探测：本地使用ffprobe，远程委托FFmpeg处理器。

**章节来源**
- [audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)

### FFmpeg处理器（ffmpeg.processor.ts）
- 统一处理远程下载、合并、裁剪、音量调整、格式转换、时长探测。
- 支持OSS与本地路径，自动清理临时文件。
- 合并音频时自动上传至存储服务并返回URL。

**章节来源**
- [ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)

### 阿里云提供商（aliyun.provider.ts）
- HTTP模式：POST请求生成音频，支持指令控制（速度/音调），具备重试与限流处理。
- 下载失败时返回云端URL，由上层统一处理。

**章节来源**
- [aliyun.provider.ts:9-152](file://server/src/modules/tts/aliyun.provider.ts#L9-L152)

### MiniMax提供商（minimax.provider.ts）
- 异步长文本：创建任务→轮询→下载，tar格式提取MP3。
- 参数映射：速度、音量、音调转换为平台参数。
- 轮询策略：固定间隔与最大时长限制。

**章节来源**
- [minimax.provider.ts:42-280](file://server/src/modules/tts/minimax.provider.ts#L42-L280)

### Mock提供商（mock.provider.ts）
- 使用FFmpeg生成占位音频，便于测试与演示。
- 无法生成时写入最小MP3文件头作为后备。

**章节来源**
- [mock.provider.ts:11-61](file://server/src/modules/tts/mock.provider.ts#L11-L61)

### 阿里云实时提供商（aliyun-realtime.provider.ts）
- WebSocket流式合成，适合长文本。
- 支持语速与音调指令，自动分段与提交触发。

**章节来源**
- [aliyun-realtime.provider.ts:11-158](file://server/src/modules/tts/aliyun-realtime.provider.ts#L11-L158)

### AI摘要服务（ai-summary.service.ts）
- 标题：优先提取文本首行，否则调用AI生成或Mock降级。
- 摘要：支持真实AI与Mock降级，按句号截断。
- 标签：基于词频统计提取Top-N关键词。

**章节来源**
- [ai-summary.service.ts:7-169](file://server/src/modules/tts/ai-summary.service.ts#L7-L169)

### 配置与类型
- 配置中心：加载环境变量与模型配置，统一管理DashScope与MiniMax等厂商配置。
- 类型定义：音色参数、音频状态、用户与订单类型、分页等。

**章节来源**
- [index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [index.ts:40-124](file://server/src/types/index.ts#L40-L124)
- [models.json:1-186](file://server/src/config/models.json#L1-L186)
- [models.json:1-168](file://deploy-package/server/config/models.json#L1-L168)

## 依赖关系分析
- 控制器依赖服务层；服务层依赖提供商适配器、合并器、AI摘要、存储服务与数据库。
- 合并器与FFmpeg处理器耦合，前者负责策略选择，后者负责具体执行。
- 配置与模型文件提供统一的厂商与模型管理，避免硬编码。

```mermaid
classDiagram
class TTSController {
+voices()
+providers()
+generate()
+status()
+preview()
+downloadBatch()
}
class TTSService {
+generateAudio()
+getAudioStatus()
+generatePreview()
+getVoices()
}
class AliyunTtsProvider
class MiniMaxTtsProvider
class MockTtsProvider
class AliyunRealtimeTtsProvider
class AudioMerger {
+merge()
+getDuration()
}
class FFmpegProcessor {
+mergeAudio()
+convertFormat()
+getDuration()
}
class AISummaryService {
+generateTitle()
+generateSummary()
+extractTags()
}
class Config
class Types
class Prisma
TTSController --> TTSService
TTSService --> AliyunTtsProvider
TTSService --> MiniMaxTtsProvider
TTSService --> MockTtsProvider
TTSService --> AliyunRealtimeTtsProvider
TTSService --> AudioMerger
TTSService --> AISummaryService
AudioMerger --> FFmpegProcessor
TTSService --> Config
TTSService --> Types
TTSService --> Prisma
```

**图表来源**
- [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)
- [audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)
- [aliyun.provider.ts:9-152](file://server/src/modules/tts/aliyun.provider.ts#L9-L152)
- [minimax.provider.ts:42-280](file://server/src/modules/tts/minimax.provider.ts#L42-L280)
- [mock.provider.ts:11-61](file://server/src/modules/tts/mock.provider.ts#L11-L61)
- [aliyun-realtime.provider.ts:11-158](file://server/src/modules/tts/aliyun-realtime.provider.ts#L11-L158)
- [ai-summary.service.ts:7-169](file://server/src/modules/tts/ai-summary.service.ts#L7-L169)
- [index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [index.ts:40-124](file://server/src/types/index.ts#L40-L124)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)

**章节来源**
- [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)
- [audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)
- [aliyun.provider.ts:9-152](file://server/src/modules/tts/aliyun.provider.ts#L9-L152)
- [minimax.provider.ts:42-280](file://server/src/modules/tts/minimax.provider.ts#L42-L280)
- [mock.provider.ts:11-61](file://server/src/modules/tts/mock.provider.ts#L11-L61)
- [aliyun-realtime.provider.ts:11-158](file://server/src/modules/tts/aliyun-realtime.provider.ts#L11-L158)
- [ai-summary.service.ts:7-169](file://server/src/modules/tts/ai-summary.service.ts#L7-L169)
- [index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [index.ts:40-124](file://server/src/types/index.ts#L40-L124)
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)

## 性能考量
- 并发策略：MiniMax串行（异步轮询耗时长），其他提供商并行（并发度2），提升吞吐。
- 重试与指数退避：阿里云与MiniMax在限流/服务器错误时进行指数退避重试。
- 云端URL直传：优先下载后统一上传，减少跨域与网络抖动影响。
- 文本分段：按段落与句子拆分，避免超限；超长句子强制切片，保障稳定性。
- 时长与格式：合并后统一时长探测与格式转换，避免重复处理。
- 存储上传：通过统一存储服务上传，支持本地或OSS，降低耦合。

**章节来源**
- [tts.service.ts:348-383](file://server/src/modules/tts/tts.service.ts#L348-L383)
- [tts.service.ts:116-136](file://server/src/modules/tts/tts.service.ts#L116-L136)
- [aliyun.provider.ts:125-141](file://server/src/modules/tts/aliyun.provider.ts#L125-L141)
- [minimax.provider.ts:258-277](file://server/src/modules/tts/minimax.provider.ts#L258-L277)
- [audio-merger.ts:25-36](file://server/src/modules/tts/audio-merger.ts#L25-L36)
- [ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

## 故障排查指南
- 速率限制与配额：服务层识别“usage limit/rate limit/quota/exceeded”，优先切换提供商；若非额度错误则停止重试。
- 失败标记与僵尸任务：生成失败会在目录写入失败标记；空目录超过阈值判定为僵尸任务并回写数据库状态。
- 云端下载失败降级：MiniMax云端URL下载失败时回退到本地文件合并与上传。
- WebSocket实时模式：当前被强制禁用，如需启用需满足权限与配置要求。
- FFmpeg/网络异常：统一捕获并记录，必要时返回占位文件或抛出错误。

**章节来源**
- [tts.service.ts:518-542](file://server/src/modules/tts/tts.service.ts#L518-L542)
- [tts.service.ts:552-596](file://server/src/modules/tts/tts.service.ts#L552-L596)
- [tts.service.ts:394-427](file://server/src/modules/tts/tts.service.ts#L394-L427)
- [tts.service.ts:91-96](file://server/src/modules/tts/tts.service.ts#L91-L96)
- [ffmpeg.processor.ts:346-375](file://server/src/services/ffmpeg.processor.ts#L346-L375)

## 结论
该TTS语音合成服务通过多提供商适配、智能分段与并发策略、统一合并与上传、AI摘要与LRC歌词生成，实现了高可用、可扩展、易维护的音频生成流水线。结合配额控制与状态查询，满足生产环境的稳定性与可观测性需求。建议在生产环境中启用Mock降级与云端直传策略，并持续监控提供商可用性与成本指标。

## 附录

### API定义与调用示例
- 获取音色列表
  - 方法：GET
  - 路径：/tts/voices
  - 示例：[tts.controller.ts:12-21](file://server/src/modules/tts/tts.controller.ts#L12-L21)

- 获取可用提供商
  - 方法：GET
  - 路径：/tts/providers
  - 示例：[tts.controller.ts:23-32](file://server/src/modules/tts/tts.controller.ts#L23-L32)

- 异步生成音频
  - 方法：POST
  - 路径：/tts/generate
  - 请求体字段：text, voiceId, voiceParams(speed/pitch/volume), bookId, chapterTitle, ttsProvider(可选)
  - 示例：[tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)

- 查询生成状态
  - 方法：GET
  - 路径：/tts/status/:audioId
  - 示例：[tts.controller.ts:129-143](file://server/src/modules/tts/tts.controller.ts#L129-L143)

- 预览音色
  - 方法：POST
  - 路径：/tts/preview
  - 示例：[tts.controller.ts:145-180](file://server/src/modules/tts/tts.controller.ts#L145-L180)

- 批量下载
  - 方法：POST
  - 路径：/tts/download/batch
  - 示例：[tts.controller.ts:223-272](file://server/src/modules/tts/tts.controller.ts#L223-L272)

### 音色参数与配置
- 音色参数类型：speed(0.5-2.0), pitch(-500-500), volume(0-100)
  - 定义：[types/index.ts:40-44](file://server/src/types/index.ts#L40-L44)

- 阿里云配置：API Key、模型、音色、TTS模型列表、实时模式开关
  - 定义：[config/index.ts:83-93](file://server/src/config/index.ts#L83-L93)

- MiniMax配置：API Key、模型(speech-2.8-hd)
  - 定义：[config/index.ts:95-111](file://server/src/config/index.ts#L95-L111)，[models.json:68-74](file://server/src/config/models.json#L68-L74)

### 音频合并与格式转换
- 合并策略：本地文件concat，远程URL委托FFmpeg处理器；MP3转码，其他格式复制。
  - 实现：[audio-merger.ts:11-36](file://server/src/modules/tts/audio-merger.ts#L11-L36)，[ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

- 时长探测：本地ffprobe，远程下载后探测。
  - 实现：[audio-merger.ts:70-85](file://server/src/modules/tts/audio-merger.ts#L70-L85)，[ffmpeg.processor.ts:190-208](file://server/src/services/ffmpeg.processor.ts#L190-L208)

### AI摘要与歌词
- 标题/摘要/标签：支持真实AI与Mock降级。
  - 实现：[ai-summary.service.ts:22-164](file://server/src/modules/tts/ai-summary.service.ts#L22-L164)

- LRC歌词：按字数估算时长，生成时间轴。
  - 实现：[tts.service.ts:604-635](file://server/src/modules/tts/tts.service.ts#L604-L635)

### 数据模型与状态
- 音频状态：processing/completed/failed
  - 定义：[types/index.ts:46-46](file://server/src/types/index.ts#L46-L46)

- 数据库连接与Prisma客户端
  - 定义：[models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)