Initial commit for TTS project
This commit is contained in:
Ben
195
docs/PROJECT_DEVELOPMENT_RULES.md
Normal file
195
docs/PROJECT_DEVELOPMENT_RULES.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user