# VoiceLab **Repository Path**: jokerzcoder/voice-lab ## Basic Information - **Project Name**: VoiceLab - **Description**: voice-lab - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-24 - **Last Updated**: 2026-08-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # VoiceLab：车辆 HMI 语音测试应用 VoiceLab 是面向车辆语音控制与座舱 HMI 测试的本地 TTS 工具。它可以按年龄、性别、口音、情绪、语速和音色质感组合测试人群，生成可追踪的单条或批量 WAV。 v0.3.0 提供独立 Electron 桌面应用：解压即用，不需要外部浏览器、Python、Node.js 或完整 CUDA Toolkit。模型不随应用打包，由用户第一次在“模型中心”显式下载。 仓库：[Gitee / jokerzcoder/voice-lab](https://gitee.com/jokerzcoder/voice-lab) ## 文档入口 | 文档 | 用途 | | --- | --- | | [`QUICKSTART.md`](QUICKSTART.md) | 终端用户开箱使用 | | [`DISTRIBUTION.md`](DISTRIBUTION.md) | 网盘上传、SHA-256 和分发检查 | | [`RELEASE_NOTES_v0.3.0.md`](RELEASE_NOTES_v0.3.0.md) | Electron 绿色应用与模型中心变更 | | [`PROJECT_PROFILE.md`](PROJECT_PROFILE.md) | 知识库工具介绍 | 历史版本说明继续保留，新增版本不能覆盖或删除旧版本记录。 ## 应用能力 - Qwen3-TTS 预置音色 `custom_voice`； - Qwen3-TTS 自然语言音色设计 `voice_design`； - Qwen3-TTS 参考音频克隆 `voice_clone`； - 年龄 × 性别 × 情绪等人群矩阵，单批最多 100 条； - 串行生成队列，避免多个任务同时抢占显存； - 任务记录、参考素材、结构化可读文件名和 WAV 输出； - 应用内模型中心：进度、速度、ETA、当前文件、取消和完整性检查； - 独立 Electron 窗口和本地 FastAPI 后台； - REST API 与 OpenAPI 文档仍保留给研发和自动化测试使用。 声音克隆只能使用已取得明确授权的声音，合成数据应标记为 AI 生成。代码许可、模型权重许可和业务使用许可需要分别核对。 ## 绿色应用结构 Windows 包： ```text VoiceLab-v0.3.0-windows-x64/ ├─ VoiceLab.exe # Electron 应用入口 ├─ resources/ │ ├─ app.asar # Electron 主进程与 preload │ └─ backend/VoiceLab/ # PyInstaller 后台和 Torch 运行库 └─ VoiceLabData/ # 首次启动后创建 ├─ config/runtime.json ├─ models/ ├─ outputs/ ├─ assets/ ├─ cache/ └─ logs/ ``` Linux 包结构相同，入口为 `voicelab`，后台位于 `resources/backend/voicelab/`。 应用不创建系统服务、不要求安装器，也不把模型写入用户 C 盘的全局缓存。Electron、ModelScope、Hugging Face、模型、日志和输出统一放在程序同级 `VoiceLabData`。关闭应用后可以整体移动目录；完全移除时删除整个目录即可。 ## 终端用户启动 ### Windows 1. 校验 `VoiceLab-v0.3.0-windows-x64-portable.zip` 的 SHA-256。 2. 完整解压到有写权限的位置，不能在压缩软件预览窗口运行。 3. 双击根目录 `VoiceLab.exe`。 4. Electron 先显示启动页，后台就绪后进入主界面。 ### Linux ```bash sha256sum -c VoiceLab-v0.3.0-linux-x64-portable.tar.gz.sha256 tar -xzf VoiceLab-v0.3.0-linux-x64-portable.tar.gz cd VoiceLab-v0.3.0-linux-x64 chmod +x ./voicelab ./voicelab ``` Linux 需要 x86_64、glibc 2.31+ 和桌面图形环境。还需安装 GTK 3、NSS、ALSA、GBM、ATK、X11、OpenMP、libsndfile 和 SoX 等常见桌面/音频运行库；具体命令见 `QUICKSTART.md`。无桌面的服务器部署仍应使用项目的 FastAPI/Docker 入口，而不是 Electron。 ## 第一次下载模型 模型权重不包含在发布包内。应用启动后请求 `/api/v1/models` 获取三个模式的状态，但不会自动下载。 1. 点击单个“下载此模型”，或“依次下载全部”。 2. 后台先从 ModelScope 获取远端文件清单和总大小。 3. 下载阶段显示百分比、字节数、实时速度、剩余时间和当前文件。 4. 点击取消会结束独立下载进程；ModelScope 已有的未完成文件保留用于后续下载。 5. 下载结束后逐文件核对大小，全部通过才写入 `.voicelab-model.json` 并标记“已就绪”。 6. 对应模式未就绪时，生成按钮禁用，API 入队也会明确报错。 默认模型： | 模式 | ModelScope 模型 ID | | --- | --- | | 预置音色 | `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice` | | 音色设计 | `Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign` | | 音色克隆 | `Qwen/Qwen3-TTS-12Hz-0.6B-Base` | 完整下载建议至少预留 15 GB。默认来源固定为 ModelScope 国内线路；下载错误会直接暴露，不会静默换源。 ## NVIDIA CUDA 与 CPU 发布包默认配置： ```dotenv TTS_DEVICE=cuda:0 TTS_DTYPE=bfloat16 TTS_ATTENTION=sdpa ``` CUDA 模式需要 NVIDIA GPU 和兼容驱动，并应能正常执行 `nvidia-smi`。PyTorch 发布包包含 CUDA 用户态运行库，通常不要求另装完整 CUDA Toolkit。 无 NVIDIA GPU 的电脑仍能打开 Electron 界面。点击右上角“运行设置”，选择 CPU，再保存；后台会按以下值重启： ```dotenv TTS_DEVICE=cpu TTS_DTYPE=float32 TTS_ATTENTION=sdpa ``` 默认仍是 CUDA，程序不会根据错误自动降级到 CPU。CPU 推理尤其是 1.7B 模型会明显较慢。 ## 源码依赖 ### Python 后台 - Python `>=3.11,<3.13`； - FastAPI `>=0.116,<1`； - Uvicorn `>=0.35,<1`； - Qwen TTS `0.1.1`； - ModelScope `1.38.1`； - PyTorch / Torchaudio `2.11.0`； - PyInstaller `6.21.0`（构建发布包）； - Ruff、Pytest、HTTPX（开发验证）。 ### Electron 桌面端 - Electron `43.4.0`； - electron-builder `26.15.3`； - pnpm 锁定依赖并把 store 放在仓库所在 H 盘。 Electron 安全配置：渲染进程 `nodeIntegration: false`、`contextIsolation: true`、`sandbox: true`；只有 preload 暴露的运行设置、目录打开和后台重试 IPC 可以被页面调用。应用拒绝权限请求和非本地导航，本地后台只监听随机 `127.0.0.1` 端口。 ## Windows 源码开发 ### 1. Python 环境 ```powershell py -3.11 -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install ` torch==2.11.0+cu130 torchaudio==2.11.0+cu130 ` --index-url https://download.pytorch.org/whl/cu130 .\.venv\Scripts\python.exe -m pip install -e ".[qwen,dev]" .\.venv\Scripts\python.exe -m pip check Copy-Item .env.example .env ``` CPU 开发机应安装匹配的 CPU 版 Torch，并在 `.env` 同时设置 `cpu`、`float32`、`sdpa`。 ### 2. 仅启动后台/Web（开发调试） ```powershell .\.venv\Scripts\python.exe -m uvicorn voice_lab.main:app ` --host 127.0.0.1 --port 8000 --workers 1 ``` - Web： - OpenAPI： - 健康检查： ### 3. 启动 Electron 开发版 仓库在 H 盘时，`.npmrc` 会把 pnpm 数据留在 H 盘： ```powershell $pnpm = "C:\Users\ZYF\.cache\codex-runtimes\codex-primary-runtime\dependencies\bin\fallback\pnpm.cmd" & $pnpm --dir .\electron install & $pnpm --dir .\electron start ``` 开发态数据写入 `data/electron-dev`，不会与正式绿色包的 `VoiceLabData` 混用。 ## 环境配置 源码/Web 入口从 `.env` 读取；系统环境变量优先。Electron 正式包由桌面主进程传入绝对路径和运行设备，用户无需手改 `.env`。 | 变量 | 默认值 | 说明 | | --- | --- | --- | | `TTS_ENGINES` | `qwen3` | 启用引擎 | | `TTS_DATA_DIR` | `./data` | 任务、素材、输出根目录 | | `TTS_MODEL_DIR` | `./data/models` | 已完成模型目录 | | `TTS_DEVICE` | `cuda:0` | `cuda:0` 或 `cpu` | | `TTS_DTYPE` | `bfloat16` | CPU 必须使用 `float32` | | `TTS_ATTENTION` | `sdpa` | 默认注意力实现 | | `QWEN_MODEL_SOURCE` | `modelscope` | `modelscope` 或明确配置的 `huggingface` | | `MODELSCOPE_CACHE` | `./data/model-cache/modelscope` | ModelScope 临时/缓存目录 | | `HF_HOME` | `./data/model-cache/huggingface` | Hugging Face 缓存目录 | | `TTS_MAX_UPLOAD_MB` | `30` | 单个参考音频大小上限 | 模型 ID 可用 `QWEN_CUSTOM_MODEL`、`QWEN_DESIGN_MODEL`、`QWEN_CLONE_MODEL` 修改。修改模型 ID 后必须通过模型中心重新下载并校验对应目录。 ## 构建发布包 ### Windows Electron 绿色包 必须在 Windows x64 上执行： ```powershell .\packaging\build_electron_windows.ps1 ``` 脚本会： 1. 用 PyInstaller 重建 Python/Torch 后台； 2. 清除会覆盖系统 UCRT 的旧 app-local UCRT 文件，复制验证过的 VC++ x64 runtime； 3. 执行打包后 Torch/SciPy/Qwen3-TTS 诊断； 4. 安装锁定的 Electron 依赖； 5. 生成 `win-unpacked` 绿色目录； 6. 压缩并生成 SHA-256。 产物： - `dist/VoiceLab-v0.3.0-windows-x64-portable.zip` - `dist/VoiceLab-v0.3.0-windows-x64-portable.sha256` ### Linux Electron 绿色包 Windows 开发机需要可用的 Docker Desktop Linux engine： ```powershell docker version .\packaging\build_electron_linux.ps1 ``` 脚本先在 Linux 容器构建 Linux PyInstaller 后台，再用 Linux Electron runtime 组装目录。产物： - `dist/VoiceLab-v0.3.0-linux-x64-portable.tar.gz` - `dist/VoiceLab-v0.3.0-linux-x64-portable.tar.gz.sha256` PyInstaller 不是跨平台编译器，Linux 后台必须在 Linux 用户态构建。脚本也在 Linux 容器内完成 Electron 组装和最终归档，以保留 ELF 执行权限与动态库符号链接；不能在 Windows 目录中解包再重新打包。发布前仍建议在目标实体 Linux 桌面执行一条短音频测试。 ## 测试与验收 ```powershell .\.venv-test\Scripts\python.exe -m ruff check voice_lab tests .\.venv-test\Scripts\python.exe -m pytest -q ``` Electron JavaScript 语法： ```powershell $node = "C:\Users\ZYF\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe" & $node --check .\electron\main.js & $node --check .\electron\preload.js & $node --check .\voice_lab\static\app.js ``` 发布验收至少包括：启动/退出、CUDA 与 CPU 显式切换、模型清单、下载速度与 ETA、取消和再次下载、完整性校验、生成一条短音频、应用内完整播放、输出文件、后台无残留、另一台电脑 SHA-256 与启动测试。 ## 常见问题 ### `AssertionError: Torch not compiled with CUDA enabled` 有 NVIDIA GPU 时检查发布包、驱动和 `nvidia-smi`；源码环境应从 PyTorch 官方 CUDA 索引安装对应 wheel。无 NVIDIA GPU 时在应用“运行设置”明确选择 CPU。程序不会隐藏错误或自动降级。 ### `OSError: [WinError 1114]` / `c10.dll` 1. 核对 ZIP SHA-256； 2. 对 ZIP 解除锁定并解压到全新目录； 3. 不要单独移动 EXE 或删除 `resources/backend/.../_internal`； 4. 企业电脑让 IT 检查 AppLocker、WDAC、CodeIntegrity 和终端防护日志； 5. 查看 `VoiceLabData/logs/backend.log`。 ### 模型下载失败 确认 ModelScope 可访问、目录可写、空间足够。查看界面原始错误和 `VoiceLabData/logs/model-download.log`。应用不会静默改用 Hugging Face 或其他镜像。 ### 音频播放偶尔不完整 应用不会在任务轮询时重建已有 `