VoxWeave

在 Windows 本机完成离线媒体与实时麦克风 RVC 变声。

中文 · English · 日本語 | 文档 | 贡献 | 反馈

VoxWeave 是一套在 Windows 本机运行的 RVC 变声工作站。你可以交给它音频、歌曲、视频、目录或麦克风输入，在桌面端完成试听、离线转换、实时变声和批量处理，并从任务中心查看结果、失败原因与产物位置。

当前真机验收范围是 Windows 11、NVIDIA CUDA。源码保留 Linux 和 macOS 的运行边界，但这两个平台尚未完成真机验收。EXE 不内置大体积运行环境或声音模型；新用户可以在界面中按需下载经过哈希校验的运行组件和推荐模型。项目不提供虚拟声卡、模型训练或 GPT-SoVITS。

双击 VoxWeave.exe 后，程序会先发现现有 VoxWeave 数据、RVC 环境及 FFmpeg。找到已有环境就直接复用；否则自动选择空间充足的非系统盘创建 VoxWeave 数据目录。只有找不到合适磁盘时才要求手动选择。EXE 所在目录保存数据目录指针和运行组件检查结果；可能很大的运行组件、模型、缓存、日志和任务产物保存在数据目录。NVIDIA 完整首次安装要求至少 12 GiB 可用空间。

程序会自动检查检测到的运行环境。完整环境可直接使用；只缺 FFmpeg 时，“补全缺失组件”只补 FFmpeg；现有 RVC 自检不通过时，程序会弹窗说明安装内容、保存位置和空间要求，用户确认后才下载锁定版本的 Python 3.12、RVC 和 FFmpeg。模型库为空时，程序会自动扫描现有 RVC 的 assets\weights 和索引目录；仍然没有模型时，会弹窗询问是否下载“青年男声 + 学姐女声”两款入门音色。取消确认不会产生下载任务，其余中文音色仍可在模型库按需选择。

源码开发需要 Python 3.12 和 Git。运行数据必须放在源码目录之外；Python 环境、pip 缓存、临时文件、数据库、日志、下载和任务产物都会进入这个数据目录。

git clone https://github.com/CheshireMew/VoxWeave.git
cd VoxWeave
.\scripts\bootstrap.ps1 -DataRoot D:\Tools\VoxWeave

如果你已经有锁定兼容版本的 RVC 环境，可以在首次配置时一并声明：

.\scripts\bootstrap.ps1 `
  -DataRoot D:\Tools\VoxWeave `
  -RvcRoot E:\path\to\Retrieval-based-Voice-Conversion-WebUI `
  -RvcPython E:\path\to\Retrieval-based-Voice-Conversion-WebUI\.venv\Scripts\python.exe `
  -Ffmpeg D:\path\to\ffmpeg.exe `
  -Ffprobe D:\path\to\ffprobe.exe

requirements.lock 是 Windows/Python 3.12 的已验收依赖集合，首次配置和 CI 使用同一约束文件。源码目录只保留一个被 Git 忽略的 .voxweave.local.json 数据目录指针。

直接双击仓库根目录的 VoxWeave.vbs，即可无控制台窗口启动。需要查看启动错误时，在 PowerShell 中运行：

.\scripts\run.ps1

VoxWeave.bat 只负责把旧快捷方式转交给 VoxWeave.vbs，随后立即退出。源码更新后，先用 .\scripts\voxweave.ps1 service stop 正常关闭旧服务，再重新启动桌面端。

先启动桌面端，让本机服务可用；然后在新的 PowerShell 窗口提交安装任务：

.\scripts\voxweave.ps1 --json execute runtime.install --arguments '{}'

安装任务把锁定的 Python、RVC 源码、FFmpeg 和必需推理资源放入数据目录，只安装 VoxWeave 实际使用的推理、实时音频、模型检查和语音分析依赖，不安装 RVC 网页界面、训练面板、Gradio 或 TensorBoard。默认不会下载许可证无法确认的人声分离权重；WeSpeaker ONNX 权重按 CC-BY-4.0 安装。完整边界见 第三方说明。

1. 在“模型库”下载推荐模型、扫描本机目录，或添加你有权使用的 .pth 和可选 .index。
2. 打开“转换工作台”，选择输入文件、输出位置和目标模型。
3. 先生成试听，确认音高、F0、索引率等参数，再开始完整转换。
4. 在“任务中心”查看进度；完成后可播放或打开最终产物。

桌面端会记住它是否亲自启动了本机服务。关闭窗口时，只停止由这个窗口启动的服务并释放 GPU；从 CLI 或其它工具独立启动的服务不会被误关。设置页也提供“停止服务、释放 GPU 并退出”的明确操作。

VoxWeave 默认不覆盖已有输出。提交任务时会固化输入文件、模型和索引身份，执行前后再次验证；结果清单记录最终文件及 SHA-256，避免重试时悄悄换用已经变化的素材或模型。

转换工作台接受 WAV、FLAC、MP3、MP4 和 MKV。语音模式可以先分析说话人，只转换选中的说话人；转换工程会保存波形、分段边界、逐段启用状态、音色与参数，并提供拆分、合并、撤销、重做和历史版本恢复。一个工程可把不同片段分配给不同模型，实际渲染时按模型分组复用加载结果。歌曲模式可以在用户自行准备分离模型后处理人声并混回伴奏；最多四组参数可以生成同步 A/B 试听，模型库还可以对 2–8 个音色生成同源同参对比。

预设可以复制、更新、归档、恢复、导入和导出。模型库可维护封面、自定义名称、标签、收藏、备注和试听样本，并显示使用次数、最近使用时间、重复权重和完整性检查结果。成品处理链包含去混响、降噪、低切、低频/清晰度均衡、压缩、齿音控制、目标响度、限幅与首尾静音处理。长音频会在低能量位置分块，但只加载一次 RVC 模型。视频输出复制原视频流和原音轨，再新增命名后的变声音轨；最终发布前会完成媒体解码、清单和哈希检查。每次成品都会进入带父子关系的结果版本记录，可查看参数与输出差异、做 A/B 播放，并用当时的输入和模型修订精确重跑。

在“设置与诊断”中选择 Windows 音频接口、麦克风和播放设备，再到“实时变声”选择模型与参数。输入和输出必须属于同一个音频接口；连续模式建议使用耳机，避免播放声音被麦克风再次收录。

实时页提供 0.25、0.5 和 1.0 秒三档延迟预算。麦克风校准会实测噪声底、信噪比、音高范围和设备稳定度，再推荐噪声门、VAD 阈值、音高、索引率和延迟档位；路由测试会实际打开指定入出设备完成一次闭环探测，而不只检查设备名称。Silero VAD 和用户设置的麦克风启动阈值共同决定何时进入推理；测试模式会先录入并转换整句话，在停顿后播放，适合在开始连续监听前检查效果。场景按设备名称保存模型、路由、参数、录音开关和快捷键，设备编号在重启后变化也会重新匹配。

连续会话中可以即时切换原声旁路、静音、录音和按键说话，不需要重启模型；悬浮迷你面板与系统托盘在主窗口隐藏时仍可完成这些控制。默认全局快捷键为 Ctrl+Alt+F9/F10/F11/F12，依次控制开始/停止、旁路、静音和按住说话。录音写入数据目录的 artifacts/realtime，分别生成麦克风干声和最终湿声 WAV，同时保存包含文件哈希、模型修订和运行指标的录音清单；停止后可把干声和当时的模型参数直接提升为离线转换工程。路由助手会识别 VB-CABLE 与 Voicemeeter。

实时会话和离线任务共用 GPU：已有离线任务运行时不能启动实时会话；实时会话开始后，新任务会保持排队，并在会话停止后继续。预热会暂停离线任务，因此不会在后台自动发生；用户可以明确点击“准备模型”，也可以直接开始实时会话并等待预热完成。离开实时页且没有活动会话时会释放驻留工作进程和 GPU 显存。

批量规则把输入目录、输出目录、多组模型/预设变体和监控状态保存到数据库。每个变体可单独设置扩展名与包含/排除 glob，同一个输入可以一次生成多个模型结果；多变体即使命名模板没有写 {variant} 也会得到不同目标路径。规则可以编辑、归档和恢复，归档不会删除规则、任务或文件。运行前可以预检文件数、输出数、体积、目标路径和冲突；命名模板支持 {stem}、{source_ext}、{variant}、{model}、{preset}、{hash}，还能选择是否保留目录结构、输出格式以及跳过、版本化或覆盖策略。新文件写入稳定后才会进入队列；输出目录会从输入枚举中排除，内容 SHA-256 用于去重。单个失败项可以更换模型、预设和输出路径后单独重试，不必重跑整批。

任务可以取消、重试并在任务中心统一查看。设置页会分别统计结果、中间产物、失败运行、模型、缓存与组件占用；归档后的任务可以校验后恢复。迁移数据目录时，程序会先生成带摘要的计划，退出服务后复制并逐文件核对，切换数据目录指针再重启，旧目录保留为回退来源。VoxWeave 不会自动删除中间产物。更新页只读取项目的 GitHub Release，Windows ZIP 必须带有发布者 SHA-256 摘要才允许下载；新版本并排安装，激活后必须在期限内报告健康，否则启动器自动回到上一版本。

桌面端、CLI 和自动化工具都是同一个本机服务的客户端。调用前先读取正在运行的服务实际声明的操作与 schema，不要在脚本里硬编码一份旧合同：

.\scripts\voxweave.ps1 --json describe
.\scripts\voxweave.ps1 --json models
.\scripts\voxweave.ps1 --json execute runtime.inspect --arguments '{}'

所有请求使用 voxweave-control v1。会修改状态的操作和长任务都需要全局唯一的 request_id；网络中断后使用同一 ID、操作、参数和调用者重发，会得到第一次调用的结果而不会重复执行。长任务立即返回 task_id，随后用 task get 查询，或连接发现文件声明的已认证本机 WebSocket：

.\scripts\voxweave.ps1 --json execute conversion.run --arguments '{
  "input":"D:\\media\\source.wav",
  "output":"D:\\media\\source-converted.wav",
  "model":"MODEL_ID_FROM_MODELS",
  "pitch":9,
  "f0":"rmvpe",
  "content_mode":"clean",
  "overwrite":false
}'

.\scripts\voxweave.ps1 --json task get TASK_ID

服务只监听 127.0.0.1 的随机端口。发现文件包含 PID、协议版本和临时令牌；客户端会先验证进程和握手，不沿用陈旧文件。完整请求、任务和 WebSocket 合同见 协议说明。

外部 Agent 也可以直接启动 stdio MCP 服务，不需要在 VoxWeave 内增加聊天界面或模型运行时：

python -m voxweave.mcp_server

MCP 服务会从正在运行的本机服务读取最新 describe 合同，把每个公开操作动态暴露为 voxweave_<操作名> 工具；长任务仍返回持久化 task_id，Agent 随后调用 voxweave_task_get 检查结果。客户端配置与调用约束见 外部 Agent 与 MCP。

• SQLite 是工程与修订、结果版本、模型、预设、任务、批量规则、实时会话与场景、事件、产物及归档记录的唯一状态真源。
• 结构化 JSON 日志位于数据目录的 logs，单文件 10 MB，最多保留 5 个轮转文件。
• 诊断导出包含运行时、模型、任务、实时会话、存储统计和日志清单，不嵌入模型或媒体内容。
• 外部模型按原路径登记；VoxWeave 计算权重和索引哈希，不复制、改名或上传模型。
• URL 模型必须提供来源、最终大小和 SHA-256；上游没有明确许可证时会显示“授权未说明”，不会冒充已授权模型。

声音模型可能模仿真实人物或角色。使用者必须取得声音主体、模型作者和素材权利人的必要许可，并遵守适用法律与平台规则。详见 模型来源与授权政策。

QML 桌面端、CLI 和第三方工具只通过认证的回环 API 进入后台服务，不直接扫描模型、修改任务库或调用 RVC。离线任务由一个串行工作线程处理，实时会话使用独立常驻进程；两者通过同一个 GPU 调度边界协调。

进一步阅读：

• 架构与数据边界
• 协议说明
• 外部 Agent 与 MCP
• Windows 0.1 实机验收记录
• 公开 schema
• 变更记录

先按快速开始创建源码环境，再运行当前 Windows 验收入口：

D:\Tools\VoxWeave\.venv\Scripts\python.exe -m ruff check .
D:\Tools\VoxWeave\.venv\Scripts\python.exe -m pytest

真实 CUDA 链脚本会经正在运行的服务完成模型解析、任务提交、RVC 推理和最终媒体解码：

D:\Tools\VoxWeave\.venv\Scripts\python.exe scripts\verify_real_user_chain.py `
  --input D:\media\voice.wav `
  --model MODEL_ID_FROM_MODELS `
  --output-root D:\Tools\VoxWeave\validation\run

贡献前请阅读 CONTRIBUTING.md。当前项目只验收 Windows。正式发布物是免安装的 Windows x64 ZIP；日常贡献流程不生成发布包。

维护者只能从干净提交构建正式发布物，输出目录必须位于仓库和系统盘之外：

.\scripts\build-exe.ps1 `
  -Python D:\Tools\VoxWeave\.venv\Scripts\python.exe `
  -OutputRoot D:\Tools\VoxWeave\release-builds

同一版本和提交只允许保留一个构建目录。命令会生成 ZIP、SHA-256、文件清单和发布摘要，并把 ZIP 解压到独立目录逐文件复验和离屏启动；版本、提交、组件许可证、运行 DLL、QML 启动或文件哈希有任何不一致都会失败。完整约束见 Windows 发布流程。

图表由 GitHub Actions 定期生成，并发布到独立的 star-history 分支。

VoxWeave 源码使用 AGPL-3.0-or-later，完整许可说明见 LICENSING.md。Windows ZIP 会带上运行桌面应用所需的 CPython、PySide6/Qt 和 Python 依赖，但不带 RVC、托管 RVC Python 环境、FFmpeg、推理权重或声音模型。每个 ZIP 都包含完整许可证目录、Qt/PySide 源码与替换说明及逐文件哈希清单。完整来源、锁定版本和再分发边界见 第三方说明。