195 lines
5.3 KiB
Markdown
195 lines
5.3 KiB
Markdown
# TTS项目开发规范
|
||
|
||
## 📁 项目结构规范
|
||
|
||
```
|
||
/root/tts/
|
||
├── 🎯 核心功能目录
|
||
│ ├── fish-speech/ # Fish Speech官方源码（核心TTS引擎）
|
||
│ ├── VoxCPM/ # VoxCPM官方源码（备用TTS引擎）
|
||
│ └── F5-TTS/ # F5-TTS官方源码（实验性引擎）
|
||
│
|
||
├── 🛠️ 开发脚本目录
|
||
│ └── scripts/
|
||
│ ├── generate/ # 音频生成脚本（核心功能）
|
||
│ └── tools/ # 辅助工具脚本
|
||
│
|
||
├── 📚 文档目录
|
||
│ └── docs/ # 项目文档
|
||
│
|
||
├── 🔊 音频目录
|
||
│ ├── audio/ # 分类音频文件
|
||
│ │ ├── reference/ # 参考音频
|
||
│ │ └── output/ # 生成音频
|
||
│ └── audio_files/ # 历史音频文件
|
||
│
|
||
└── 📦 素材目录
|
||
└── material/ # 训练素材和配置
|
||
```
|
||
|
||
## 🎯 核心脚本清单
|
||
|
||
### 必须保留的核心脚本（12个）
|
||
|
||
#### 🎵 音频生成脚本 (`scripts/generate/`)
|
||
1. **`fish_speech_cli.py`** - 主要CLI工具 ⭐⭐⭐
|
||
2. **`generate_final.py`** - 最终生成脚本 ⭐⭐⭐
|
||
3. **`real_fish_speech.py`** - 真实Fish Speech实现 ⭐⭐⭐
|
||
4. **`fish_speech_direct_cli.py`** - 直接CLI工具 ⭐⭐
|
||
5. **`create_30s_demo.py`** - 30秒音频演示 ⭐⭐
|
||
6. **`final_cli_demo.py`** - 最终CLI演示 ⭐⭐
|
||
7. **`generate_default_voice.py`** - 默认音色生成 ⭐⭐
|
||
8. **`generate_with_app.py`** - 应用接口生成 ⭐⭐
|
||
|
||
#### 🛠️ 工具脚本 (`scripts/tools/`)
|
||
9. **`final_summary.py`** - 最终总结工具 ⭐⭐⭐
|
||
10. **`check_audio.py`** - 音频检查工具 ⭐⭐
|
||
11. **`verify_env.py`** - 环境验证工具 ⭐⭐
|
||
|
||
#### 📚 文档文件 (`docs/`)
|
||
12. **`CLI_COMMANDS.md`** - CLI使用指南 ⭐⭐⭐
|
||
|
||
## 🚫 禁止保留的文件类型
|
||
|
||
### ❌ 立即删除的文件类别
|
||
1. **测试脚本** - 文件名包含 `test_`、`debug_`、`simple_`
|
||
2. **概念验证** - 文件名包含 `concept_`、`demo_`
|
||
3. **临时脚本** - 文件名包含 `temp_`、`tmp_`
|
||
4. **重复实现** - 功能相同的多个版本
|
||
5. **空文件** - 大小为0字节的文件
|
||
6. **过渡版本** - 标记为 `old_`、`backup_` 的文件
|
||
|
||
## 📋 开发流程规范
|
||
|
||
### 🔄 开发新功能时
|
||
1. **需求分析** → 在 `docs/` 创建需求文档
|
||
2. **设计阶段** → 确定脚本归属 (`generate/` 或 `tools/`)
|
||
3. **命名规范** → 使用清晰的描述性名称
|
||
4. **代码实现** → 遵循现有代码风格
|
||
5. **测试验证** → 使用临时脚本测试，完成后删除
|
||
6. **文档更新** → 更新相关使用文档
|
||
|
||
### 📝 脚本命名规范
|
||
```bash
|
||
# ✅ 正确命名
|
||
fish_speech_cli.py # 功能_工具类型.扩展名
|
||
generate_final.py # 功能_版本.扩展名
|
||
check_audio.py # 动作_对象.扩展名
|
||
|
||
# ❌ 错误命名
|
||
test_123.py # 无意义的数字
|
||
temp_script.py # 临时文件标识
|
||
demo_v1_old.py # 版本混乱
|
||
```
|
||
|
||
### 🏗️ 代码组织规范
|
||
|
||
#### 脚本结构模板
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""
|
||
[脚本功能描述]
|
||
|
||
Author: [作者]
|
||
Date: [日期]
|
||
Version: [版本号]
|
||
|
||
Usage:
|
||
python script_name.py [参数]
|
||
"""
|
||
|
||
import os
|
||
import sys
|
||
import argparse
|
||
from pathlib import Path
|
||
|
||
# 配置常量
|
||
PROJECT_ROOT = Path(__file__).parent.parent.parent
|
||
AUDIO_OUTPUT_DIR = PROJECT_ROOT / "audio" / "output"
|
||
|
||
def main():
|
||
"""主函数"""
|
||
pass
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
## 🔧 环境配置规范
|
||
|
||
### 📦 依赖管理
|
||
- **核心依赖**: Fish Speech、VoxCPM官方依赖
|
||
- **开发依赖**: pytest、black、flake8
|
||
- **环境隔离**: 使用虚拟环境
|
||
|
||
### 🌍 环境变量
|
||
```bash
|
||
TTS_PROJECT_ROOT=/root/tts
|
||
FISH_SPEECH_MODEL_PATH=/root/tts/fish-speech
|
||
DEFAULT_AUDIO_OUTPUT=/root/tts/audio/output
|
||
```
|
||
|
||
## 📊 质量控制规范
|
||
|
||
### ✅ 代码质量检查
|
||
1. **功能完整性** - 确保实现预期功能
|
||
2. **错误处理** - 包含异常处理机制
|
||
3. **日志记录** - 关键操作有日志输出
|
||
4. **参数验证** - 输入参数有效性检查
|
||
5. **资源清理** - 临时文件和资源释放
|
||
|
||
### 🧪 测试要求
|
||
1. **单元测试** - 核心函数功能测试
|
||
2. **集成测试** - 完整流程测试
|
||
3. **边界测试** - 极端情况处理
|
||
4. **性能测试** - 生成速度和质量评估
|
||
|
||
## 📈 版本管理规范
|
||
|
||
### 🏷️ 版本号规则
|
||
- **主版本号**: 重大功能变更 (1.x.x → 2.x.x)
|
||
- **次版本号**: 新功能添加 (1.0.x → 1.1.x)
|
||
- **修订号**: Bug修复 (1.0.0 → 1.0.1)
|
||
|
||
### 📝 更新日志格式
|
||
```markdown
|
||
## [1.2.0] - 2024-XX-XX
|
||
|
||
### 新增
|
||
- 新增批量生成功能
|
||
- 新增音频格式转换
|
||
|
||
### 修复
|
||
- 修复内存泄漏问题
|
||
- 修复参数解析错误
|
||
|
||
### 删除
|
||
- 移除废弃的旧版本CLI
|
||
```
|
||
|
||
## 🎯 项目目标
|
||
|
||
### 🏆 核心目标
|
||
1. **高质量TTS** - 提供清晰、自然的语音合成
|
||
2. **易用性** - 简单的命令行接口
|
||
3. **可扩展** - 支持多种TTS引擎
|
||
4. **高性能** - 快速生成，低资源占用
|
||
|
||
### 📋 发展路线
|
||
- **Phase 1**: 完善Fish Speech集成
|
||
- **Phase 2**: 添加Web界面
|
||
- **Phase 3**: 支持实时流式TTS
|
||
- **Phase 4**: 多语言支持
|
||
|
||
---
|
||
|
||
## 📞 联系和支持
|
||
|
||
- **技术问题**: 查看docs/目录相关文档
|
||
- **Bug报告**: 在项目Issues中提交
|
||
- **功能建议**: 在项目Discussions中讨论
|
||
|
||
---
|
||
|
||
*最后更新: 2024-12-25*
|
||
*版本: v1.0.0* |