# 文本转音频

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

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

## 引言
本技术文档围绕“文本转音频”（TTS）能力进行系统化梳理，覆盖异步音频生成流程、队列与状态管理、智能分段算法、音频拼接、质量控制、错误处理与重试、以及 API 使用与最佳实践。文档面向开发者与产品/运营人员，既提供代码级细节，也给出概念性说明与可视化图示。

## 项目结构
TTS 功能位于后端服务的 TTS 模块，主要由控制器、服务层、提供者（Provider）、合并器与 FFmpeg 处理器组成，并通过配置中心与类型定义支撑运行时行为。

```mermaid
graph TB
subgraph "应用入口"
APP["app.ts<br/>注册路由/中间件/静态资源"]
end
subgraph "TTS 模块"
CTRL["tts.controller.ts<br/>REST 控制器"]
SVC["tts.service.ts<br/>业务服务"]
MERGE["audio-merger.ts<br/>本地合并/时长"]
FPROC["ffmpeg.processor.ts<br/>远程下载/合并/时长"]
SUMM["ai-summary.service.ts<br/>标题/摘要/标签"]
end
subgraph "TTS 提供者"
ALI["aliyun.provider.ts<br/>HTTP 合成"]
REAL["aliyun-realtime.provider.ts<br/>WebSocket 实时"]
MINI["minimax.provider.ts<br/>异步长文本"]
MOCK["mock.provider.ts<br/>模拟/占位"]
end
subgraph "配置与类型"
CFG["config/index.ts<br/>DashScope/模型/上传"]
TYPES["types/index.ts<br/>VoiceParams/AudioStatus"]
end
APP --> CTRL --> SVC
SVC --> ALI
SVC --> REAL
SVC --> MINI
SVC --> MOCK
SVC --> MERGE
MERGE --> FPROC
SVC --> SUMM
SVC --> CFG
SVC --> TYPES
```

**图表来源**
- [app.ts:99-130](file://server/src/app.ts#L99-L130)
- [tts.controller.ts:10-13](file://server/src/modules/tts/tts.controller.ts#L10-L13)
- [tts.service.ts:1-20](file://server/src/modules/tts/tts.service.ts#L1-L20)
- [audio-merger.ts:9-36](file://server/src/modules/tts/audio-merger.ts#L9-L36)
- [ffmpeg.processor.ts:24-122](file://server/src/services/ffmpeg.processor.ts#L24-L122)
- [aliyun.provider.ts:9-19](file://server/src/modules/tts/aliyun.provider.ts#L9-L19)
- [aliyun-realtime.provider.ts:11-21](file://server/src/modules/tts/aliyun-realtime.provider.ts#L11-L21)
- [minimax.provider.ts:42-51](file://server/src/modules/tts/minimax.provider.ts#L42-L51)
- [mock.provider.ts:11-17](file://server/src/modules/tts/mock.provider.ts#L11-L17)
- [index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [index.ts:40-46](file://server/src/types/index.ts#L40-L46)

**章节来源**
- [app.ts:99-130](file://server/src/app.ts#L99-L130)
- [tts.controller.ts:10-13](file://server/src/modules/tts/tts.controller.ts#L10-L13)
- [tts.service.ts:1-20](file://server/src/modules/tts/tts.service.ts#L1-L20)
- [index.ts:69-117](file://server/src/config/index.ts#L69-L117)

## 核心组件
- 控制器（tts.controller.ts）：负责参数校验、配额检查、调用服务层并返回统一响应格式。
- 服务层（tts.service.ts）：实现异步生成、文本分段、Provider 选择与回退、并发合成、合并与上传、状态更新、回调与 WebSocket 通知。
- 提供者（Provider）：封装不同 TTS 供应商的调用细节，含重试与错误分类。
- 合并器（audio-merger.ts）：本地文件合并与时长探测；远程场景委托 FFmpeg 处理器。
- FFmpeg 处理器（ffmpeg.processor.ts）：统一处理远程 URL 的下载、合并、格式转换、裁剪、音量调节与上传。
- 配置与类型（config/index.ts、types/index.ts）：提供 DashScope/MiniMax 等配置、模型列表、上传目录、音质参数等。
- AI 摘要（ai-summary.service.ts）：生成标题、摘要与标签，提升内容可发现性。

**章节来源**
- [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-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [ffmpeg.processor.ts:69-208](file://server/src/services/ffmpeg.processor.ts#L69-L208)
- [index.ts:83-93](file://server/src/config/index.ts#L83-L93)
- [index.ts:40-46](file://server/src/types/index.ts#L40-L46)
- [ai-summary.service.ts:7-169](file://server/src/modules/tts/ai-summary.service.ts#L7-L169)

## 架构总览
TTS 采用“控制器-服务-提供者-存储”的分层设计，结合 Provider 工厂与优先级回退策略，确保在多供应商环境下具备高可用与弹性。异步生成流程通过文件系统状态与 WebSocket 事件实现进度通知，同时通过配额与订阅服务保障资源使用合规。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "tts.controller.ts"
participant S as "tts.service.ts"
participant P as "Provider(阿里云/MiniMax/模拟)"
participant M as "AudioMerger/FFmpeg"
participant ST as "存储服务"
participant WS as "WebSocket"
C->>R : POST /api/tts/generate
R->>R : 校验参数/配额检查
R->>S : generateAudio(userId,text,voice,voiceParams,...)
S->>S : 选择Provider/分段/并发合成
S->>P : synthesize(分段xN)
P-->>S : 本地文件/云端URL
S->>M : 合并/时长探测
M-->>S : 合成文件/URL
S->>ST : 上传/返回最终URL
ST-->>S : 最终URL
S->>WS : 推送完成事件
S-->>R : 返回{audioId,audioUrl}
R-->>C : 统一响应
```

**图表来源**
- [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-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

## 详细组件分析

### 异步音频生成流程与状态跟踪
- 入口：控制器接收请求，进行参数与配额校验后调用服务层异步生成。
- 服务层：
  - 生成唯一音频 ID，创建记录（processing），并进入异步处理。
  - 选择 Provider（优先级：MiniMax → 阿里云 → 模拟），按类型决定分段策略与并发度。
  - 并行合成各段音频，聚合本地文件与云端 URL。
  - 合并为最终 MP3，计算时长与大小，上传至存储服务。
  - 生成标题/摘要/标签，写入书籍章节（如存在），更新记录状态为 completed。
  - 回调 onComplete（如有），推送 WebSocket 完成事件。
- 状态查询：基于文件系统与失败标记判断（not_found/processing/completed/failed）。

```mermaid
flowchart TD
Start(["开始"]) --> Validate["参数与配额校验"]
Validate --> CreateRec["创建处理记录(processing)"]
CreateRec --> SelectProv["选择Provider(优先级)"]
SelectProv --> DecideSplit{"是否分段?"}
DecideSplit --> |是| Split["智能分段(段落/句子/强制切分)"]
DecideSplit --> |否| NoSplit["整段直传(如MiniMax)"]
Split --> Concurrency["并发合成(1/2)"]
NoSplit --> Concurrency
Concurrency --> Merge["合并/时长/上传"]
Merge --> AI["AI生成标题/摘要/标签"]
AI --> Save["写入书籍章节/更新记录"]
Save --> Callback["回调/推送事件"]
Callback --> End(["结束"])
```

**图表来源**
- [tts.controller.ts:87-120](file://server/src/modules/tts/tts.controller.ts#L87-L120)
- [tts.service.ts:285-542](file://server/src/modules/tts/tts.service.ts#L285-L542)

**章节来源**
- [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)
- [tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)

### 智能分段处理算法
- 分段策略：
  - 按段落（按换行）合并，超过阈值（550 字）再按句子切分。
  - 句子仍超限则强制按字符块切分。
  - 最终安全检查：超过阈值的段落截断，避免越界。
- 适用范围：HTTP Provider（阿里云）；MiniMax 异步长文本不进行分段。
- 设计动机：兼顾供应商字符上限与自然语义边界，保证合成质量与稳定性。

```mermaid
flowchart TD
A["输入文本"] --> Clean["清理/去回车"]
Clean --> Para["按段落拆分"]
Para --> CheckLen{"当前段<=550?"}
CheckLen --> |是| Acc["累加到当前段"]
CheckLen --> |否| OverPara["段超限"]
OverPara --> Sent["按句号/感叹号等切分"]
Sent --> SentCheck{"句<=550?"}
SentCheck --> |是| Acc
SentCheck --> |否| Force["强制按字符块切分"]
Force --> Acc
Acc --> NextPara["下一个段落"]
NextPara --> Done["汇总为若干段(≤550)"]
```

**图表来源**
- [tts.service.ts:98-158](file://server/src/modules/tts/tts.service.ts#L98-L158)

**章节来源**
- [tts.service.ts:98-158](file://server/src/modules/tts/tts.service.ts#L98-L158)

### 音频生成与拼接
- 合成阶段：Provider 返回本地文件路径或云端 URL。
- 合并阶段：
  - 本地：使用 FFmpeg concat 合并，MP3 转码为 192k。
  - 远程：委托 FFmpeg 处理器下载、合并、上传，统一返回最终 URL。
- 时长探测：本地使用 ffprobe；远程通过 FFmpeg 处理器探测。
- 上传：统一经存储服务处理（本地/oss 可切换）。

```mermaid
classDiagram
class AudioMerger {
+merge(inputFiles,outputPath) Promise~string~
+getDuration(filePath) Promise~number~
-mergeLocalFiles(inputFiles,outputPath) Promise~string~
}
class FFmpegProcessor {
+mergeAudio(urls,format) Promise~string~
+getDuration(url) Promise~number~
+convertFormat(url,format,bitrate) Promise~string~
+trimAudio(url,start,duration) Promise~string~
+adjustVolume(url,volume) Promise~string~
-downloadFile(url) Promise~string~
}
AudioMerger --> FFmpegProcessor : "远程场景委托"
```

**图表来源**
- [audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [ffmpeg.processor.ts:69-208](file://server/src/services/ffmpeg.processor.ts#L69-L208)

**章节来源**
- [audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [ffmpeg.processor.ts:69-208](file://server/src/services/ffmpeg.processor.ts#L69-L208)

### Provider 与质量控制
- 阿里云（HTTP）：支持 instruct 模型的指令控制（速度/音调），带指数退避重试与速率限制处理。
- 阿里云（实时 WebSocket）：长文本流式合成，支持会话配置与音频流拼接。
- MiniMax：异步长文本任务，轮询状态，tar 包内提取 MP3，音频采样率 32kHz、码率 128kbps、单声道 MP3。
- 模拟 Provider：FFmpeg 生成占位音频，便于开发调试。

```mermaid
classDiagram
class AliyunTtsProvider {
+synthesize(text,voice,params,output,retries,model?) Promise~string~
}
class AliyunRealtimeTtsProvider {
+synthesize(text,voice,params,output) Promise~string~
}
class MiniMaxTtsProvider {
+synthesize(text,voice,params,output,retries,_) Promise~string~
}
class MockTtsProvider {
+synthesize(text,voice,params,output) Promise~string~
}
```

**图表来源**
- [aliyun.provider.ts:9-152](file://server/src/modules/tts/aliyun.provider.ts#L9-L152)
- [aliyun-realtime.provider.ts:11-158](file://server/src/modules/tts/aliyun-realtime.provider.ts#L11-L158)
- [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.provider.ts:21-150](file://server/src/modules/tts/aliyun.provider.ts#L21-L150)
- [aliyun-realtime.provider.ts:23-156](file://server/src/modules/tts/aliyun-realtime.provider.ts#L23-L156)
- [minimax.provider.ts:53-278](file://server/src/modules/tts/minimax.provider.ts#L53-L278)
- [mock.provider.ts:12-60](file://server/src/modules/tts/mock.provider.ts#L12-L60)

### 错误处理与重试机制
- 速率限制/服务器错误：指数退避重试（2^attempt × 1000 ms），最多 N 次。
- Provider 回退：若为额度受限错误，切换下一个 Provider；否则直接抛错。
- 文件系统状态：失败标记文件、空目录僵尸任务检测、超时失败回写数据库。
- WebSocket 通知：生成成功/失败均推送事件，前端可订阅。

```mermaid
flowchart TD
Call["调用Provider"] --> Resp{"响应状态"}
Resp --> |200+有效| OK["成功返回"]
Resp --> |429/配额| Rate["速率限制/配额超限"]
Resp --> |5xx/网络| Retry["指数退避重试"]
Resp --> |其他| Fail["抛错/回退"]
Rate --> NextProv["切换下一Provider"]
Retry --> Call
NextProv --> Call
Fail --> End["结束"]
OK --> End
```

**图表来源**
- [tts.service.ts:518-542](file://server/src/modules/tts/tts.service.ts#L518-L542)
- [aliyun.provider.ts:125-145](file://server/src/modules/tts/aliyun.provider.ts#L125-L145)
- [minimax.provider.ts:258-278](file://server/src/modules/tts/minimax.provider.ts#L258-L278)

**章节来源**
- [tts.service.ts:518-542](file://server/src/modules/tts/tts.service.ts#L518-L542)
- [tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)
- [aliyun.provider.ts:125-145](file://server/src/modules/tts/aliyun.provider.ts#L125-L145)
- [minimax.provider.ts:258-278](file://server/src/modules/tts/minimax.provider.ts#L258-L278)

### API 使用示例与最佳实践
- 获取音色列表与可用供应商
  - GET /api/tts/voices
  - GET /api/tts/providers
- 生成音频（异步）
  - POST /api/tts/generate
  - 请求体包含 text、voiceId、voiceParams（speed/pitch/volume）、可选 bookId/chapterTitle/ttsProvider
  - 响应返回 audioId（立即可用），最终 URL 通过回调/WebSocket/状态接口获取
- 预览音色
  - POST /api/tts/preview
- 下载音频
  - GET /api/tts/download/:audioId
  - 批量下载：POST /api/tts/download/batch

最佳实践
- 参数校验：必填字段与数值范围（速度 0.5-2.0、音调 -500~500、音量 0-100）。
- 并发与配额：合理设置并发度（MiniMax 1，其他 2），关注订阅配额与字数限制。
- Provider 选择：优先 MiniMax（长文本），否则阿里云 HTTP；无密钥回退模拟。
- 状态查询：使用 /api/tts/status/:audioId 或 WebSocket 事件。
- 质量控制：MP3 192k、采样率 32kHz（MiniMax），必要时通过 FFmpeg 转换。

**章节来源**
- [API.md:95-158](file://docs/API.md#L95-L158)
- [tts.controller.ts:12-180](file://server/src/modules/tts/tts.controller.ts#L12-L180)
- [tts.controller.ts:182-272](file://server/src/modules/tts/tts.controller.ts#L182-L272)
- [index.ts:40-46](file://server/src/types/index.ts#L40-L46)
- [minimax.provider.ts:72-77](file://server/src/modules/tts/minimax.provider.ts#L72-L77)

## 依赖关系分析
- 控制器依赖服务层与中间件（鉴权、限流、错误处理、性能监控、安全防护）。
- 服务层依赖 Provider、合并器、AI 摘要、存储服务、WebSocket 服务、数据库。
- Provider 依赖配置中心（DashScope/MiniMax）与网络库。
- 合并器与 FFmpeg 处理器依赖系统命令（ffmpeg/ffprobe）与存储服务。

```mermaid
graph LR
CTRL["tts.controller.ts"] --> SVC["tts.service.ts"]
SVC --> ALI["aliyun.provider.ts"]
SVC --> REAL["aliyun-realtime.provider.ts"]
SVC --> MINI["minimax.provider.ts"]
SVC --> MOCK["mock.provider.ts"]
SVC --> MERGE["audio-merger.ts"]
MERGE --> FPROC["ffmpeg.processor.ts"]
SVC --> SUMM["ai-summary.service.ts"]
SVC --> CFG["config/index.ts"]
CTRL --> TYPES["types/index.ts"]
```

**图表来源**
- [tts.controller.ts:1-10](file://server/src/modules/tts/tts.controller.ts#L1-L10)
- [tts.service.ts:1-14](file://server/src/modules/tts/tts.service.ts#L1-L14)
- [audio-merger.ts:1-7](file://server/src/modules/tts/audio-merger.ts#L1-L7)
- [ffmpeg.processor.ts:1-12](file://server/src/services/ffmpeg.processor.ts#L1-L12)
- [index.ts:1-11](file://server/src/config/index.ts#L1-L11)
- [index.ts:1-12](file://server/src/types/index.ts#L1-L12)

**章节来源**
- [tts.controller.ts:1-10](file://server/src/modules/tts/tts.controller.ts#L1-L10)
- [tts.service.ts:1-14](file://server/src/modules/tts/tts.service.ts#L1-L14)
- [audio-merger.ts:1-7](file://server/src/modules/tts/audio-merger.ts#L1-L7)
- [ffmpeg.processor.ts:1-12](file://server/src/services/ffmpeg.processor.ts#L1-L12)
- [index.ts:1-11](file://server/src/config/index.ts#L1-L11)
- [index.ts:1-12](file://server/src/types/index.ts#L1-L12)

## 性能考量
- 并发策略：MiniMax 异步轮询耗时较长，采用并发=1；HTTP Provider 并发=2，提升吞吐。
- 分段阈值：550 字安全余量，平衡字符上限与语义完整性。
- 合并优化：本地合并直接复制流（非 MP3）或转码（MP3），远程场景统一通过 FFmpeg 处理器。
- 存储上传：统一经存储服务，支持本地/oss 切换，减少耦合。
- 时长与大小：合并后即时统计，避免重复探测。

[本节为通用性能讨论，不直接分析具体文件]

## 故障排查指南
常见问题与定位步骤
- 生成失败：检查 Provider 日志与错误类型（速率限制/配额/网络），确认回退链路是否生效。
- 文件缺失：确认上传目录存在、权限正确；检查失败标记文件与僵尸任务检测逻辑。
- 时长/大小异常：确认合并与探测流程是否执行；远程场景检查 FFmpeg 处理器下载与探测。
- WebSocket 未推送：确认初始化与事件推送逻辑；检查回调是否被正确 await。
- 配额不足：核对订阅状态与字数消耗；必要时提示升级会员等级。

**章节来源**
- [tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)
- [tts.service.ts:272-279](file://server/src/modules/tts/tts.service.ts#L272-L279)
- [ffmpeg.processor.ts:190-208](file://server/src/services/ffmpeg.processor.ts#L190-L208)

## 结论
该 TTS 方案通过“控制器-服务-Provider-存储”的清晰分层，结合智能分段、并发合成、统一合并与上传、AI 摘要与状态跟踪，实现了高可用、可扩展、可维护的文本转音频能力。配合订阅配额与错误回退机制，可在多供应商环境下稳定运行，并为后续扩展（队列、批处理、更多 Provider）奠定基础。

## 附录
- 关键配置项
  - DashScope API Key、模型、音色、TTS 模型列表、是否启用实时模式
  - 上传目录、最大文件大小
- 关键类型
  - VoiceParams：speed/pitch/volume
  - AudioStatus：processing/completed/failed
- 常用接口
  - GET /api/tts/voices
  - GET /api/tts/providers
  - POST /api/tts/generate
  - GET /api/tts/status/:audioId
  - POST /api/tts/preview
  - GET /api/tts/download/:audioId
  - POST /api/tts/download/batch

**章节来源**
- [index.ts:83-93](file://server/src/config/index.ts#L83-L93)
- [index.ts:113-117](file://server/src/config/index.ts#L113-L117)
- [index.ts:40-46](file://server/src/types/index.ts#L40-L46)
- [API.md:95-158](file://docs/API.md#L95-L158)