---

项目简介

XB-SVCB 是一个 Windows 本地优先的 AI 翻唱与音频创作工具。它以 Vue 3 作为界面，以 Python 作为业务核心，并将不同 AI 框架放在独立环境和 Worker 进程中运行。

项目目前支持 So-VITS-SVC、RVC、SeedVC 和 DDSP-SVC 四种歌声转换框架，同时提供 UVR / PyMSS 人声分离、AI 歌声增强、高音保护、在线曲库、模型站、实时系统音频变声和 Audio Editor Lite 音频编辑器。

主要功能

• 一键完成「人声分离 → 去混响 → F0 分析 → 歌声转换 → 增强 → 混音」。
• 统一管理 So-VITS-SVC、RVC、SeedVC、DDSP-SVC 模型，并按模型框架选择推理参数。
• 按模型音域自动进行高音保护，对掉音或错误音高区域局部降调重试并恢复原调。
• 通过歌词或静音检测切分歌曲，在可视化时间轴中分配模型，支持多人混唱和一句多模型合唱。
• 使用 Audio Editor Lite 进行多轨编辑、剪切、淡化、声道分配、效果处理和 WAV / MP3 / FLAC 导出。
• 支持 TXT / LRC 歌词导入、角色管理和独唱、对唱、和声等时间轴模板。
• 通过 WASAPI 回环或 VB-CABLE 对播放器音频进行实时人声转换，伴奏保持原样。
• 通过 ModelScope 搜索、上传和下载模型，支持后台传输、断点续传和模型清单校验。
• 支持网易云、QQ 音乐、酷我音乐的搜索、试听、下载和歌词获取。
• 支持 GPU / CPU 切换：NVIDIA 使用 CUDA，Windows AMD 优先使用 ROCm 10，也可选择独立 DirectML 包；无兼容 GPU 时使用 CPU。
• 提供可选 FastAPI 服务，供外部程序创建任务、查询进度、管理模型和下载成品。
• 支持插件中心、自定义插件页面、Python 插件 Worker 和 C++ JUCE VST3 Host。

快速开始

使用安装包

普通用户建议直接使用 GitHub Releases 安装：

1. 按硬件选择 CPU、ROCm 10、DirectML、CUDA126 或 CUDA128 安装包，并下载该包的 EXE 和全部同名前缀 BIN 文件。
2. 运行 EXE，选择应用安装目录和用户数据目录。
3. 选择或手动指定 64 位 CPython 3.12.x，勾选「安装后立即搭建运行环境」。
4. 通过桌面或开始菜单中的 XB-SVCB 启动应用。

安装包内已包含前端、FFmpeg、模型框架源码、关键底模和对应硬件栈的离线 Python 依赖。NVIDIA 40 系及以下选择 CUDA126，RTX 50 系选择 CUDA128；两种 CUDA 包默认创建两层共享运行时。Windows AMD 首选 ROCm 10，也可按需选择 DirectML；无兼容 GPU 时选择 CPU。DirectML 包不提供 PyMSS 加速，DDSP 自动模式使用 CPU。

从源码安装

源码运行需要 Windows、64 位 CPython 3.12.x、Node.js 20.19+ 或 22.12+。在项目根目录明确选择硬件栈：

Python 3.12 依赖迁移、ROCm 10 官方源和模型兼容范围见 迁移说明。AMD 默认使用官方 whl-next 源及 device-all 套件，已验证 Windows cp312 wheel 与 PyMSS 的依赖解析；安装成功仍须通过 HIP/GPU 运算校验。

setup_env.bat --cu128
setup_env.bat --cu126
setup_env.bat --rocm10
setup_env.bat --directml
setup_env.bat --cpu

CUDA126/CUDA128 调用 install/install_shared.py，分别创建 runtimes/core- 与 runtimes/svc- 两层共享环境；CPU、ROCm 10 和 DirectML 走 install/install.py。ROCm 10 的 SVC/RVC/Vocal 共用 runtimes/svc-rocm10，其余组件仍隔离；CPU/DirectML 使用隔离布局。

常用的单组件安装命令：

setup_env.bat --only uvr seedvc ddsp
setup_env.bat --only svc rvc vocal
setup_env.bat --only models

CUDA core 的 UVR、SeedVC、DDSP 是原子组，修复时应一起选择。共享布局、固定配方、旧安装回退和清理边界见 共享运行时与兼容布局。

安装器部署大体积只读底模时优先尝试硬链接，跨卷时回退为复制；已有同尺寸权重只有 SHA-256 一致才会去重。硬链接共享内容，训练或修改权重前须另存副本。此机制不负责删除旧环境。

启动应用

生产模式会加载已构建的 web/dist：

run.bat

也可以直接运行：

app\.venv\Scripts\python.exe app\main.py

开发模式需要两个终端。第一个终端启动前端：

cd web
npm install
npm run dev

第二个终端启动 Python 后端：

app\.venv\Scripts\python.exe app\main.py --dev

开发模式默认连接 http://localhost:5173，也可以通过 XB_DEV_URL 指定前端地址。完整环境说明见源码安装与启动。

基本使用流程

1. 在「模型管理」中导入或下载声音模型。
2. 在创建页选择歌曲、人声分离方式、目标模型和设备。
3. 单模型翻唱直接提交任务；多人翻唱先导入歌词或使用静音检测生成时间轴。
4. 在时间轴上调整片段边界，为片段分配一个或多个模型。
5. 等待推理、增强和混音完成，在作品库试听或导出成品。
6. 需要进一步处理时，将作品送入 Audio Editor Lite，进行局部重推理、效果处理或多轨编辑。

系统音频实时模式只支持一个 RVC 或 SeedVC 模型。它会采集播放器输出的混合音频，用 UVR 提取人声，再将转换后的人声与原伴奏重新混音并输出。

系统架构

XB-SVCB 的核心原则是：桌面 UI 和 FastAPI 共用同一套 Python 业务核心，重型模型与音频工具通过隔离 Worker 执行。

flowchart LR
    USER[桌面用户] --> UI[Vue 3 + pywebview]
    CLIENT[外部客户端] --> HTTP[FastAPI]
    UI --> BRIDGE[Bridge API]
    HTTP --> FACADE[Api Facade]
    BRIDGE --> FACADE
    FACADE --> APP[Application Services]
    APP --> QUEUE[推理队列]
    QUEUE --> ROUTER[EngineRegistry]
    ROUTER --> SVC[So-VITS-SVC Worker]
    ROUTER --> RVC[RVC Worker]
    ROUTER --> SEED[SeedVC Worker]
    ROUTER --> DDSP[DDSP-SVC Worker]
    APP --> UVR[UVR Worker]
    APP --> VOCAL[Vocal Enhancement Worker]
    APP --> FFMPEG[FFmpeg]
    APP <--> DATA[.xb_svcb 用户数据]
    SVC -.-> ASSETS[随包模型资产]
    RVC -.-> ASSETS
    SEED -.-> ASSETS
    DDSP -.-> ASSETS
    UVR -.-> ASSETS

上图中各连接的含义：

主程序环境只负责桌面壳、API 和业务编排，不会把所有模型权重加载到同一个 Python 进程。模型 Worker 通过 runtime.json 路由到实际解释器：CUDA126/CUDA128 使用 runtimes/core- 与 runtimes/svc-；ROCm 10 的 SVC/RVC/Vocal 使用 runtimes/svc-rocm10，其余组件和 CPU/DirectML 采用隔离环境。详细的 Python 后端、启动链路和模型加载时机见：

• 系统架构说明
• 启动与模型推理链路
• 系统架构图（含连接解释）
• 启动与推理时序图

FastAPI 外部接入

FastAPI 默认关闭，不会在应用启动时自动监听端口。打开软件中的「资料库 → API 接入」，配置监听地址、端口和 API Key 后手动启动服务。

服务支持：

• 模型列表、导入和管理；
• 单模型、多模型和批量推理；
• 大音频流式上传；
• 任务进度、历史记录和预设；
• 作品查询与成品下载；
• Audio Editor Lite 的工程、音轨、片段、分离、局部重推理和渲染接口。

API 文档、鉴权方式和 Python / PowerShell 示例见 FastAPI 接入文档。桌面 UI 和 HTTP 创建的任务共享同一个业务核心和任务队列。

插件系统

插件由 PluginService 负责安装、启停、配置和生命周期管理。插件前端运行在受限 iframe 中，通过 Client SDK 和宿主 Bridge 使用能力；Python 或混合插件的动作在独立 Worker 中执行。

插件可以包含：

• Vue / HTML / JavaScript 前端页面；
• Python Worker 和动作；
• TypeScript / Python SDK；
• 清单、权限、配置和资源文件。

开发入口：

• 插件开发总览
• 插件开发完整指南
• 插件清单规范

目录结构

xb-svcb/
├─ app/                         Python 后端、业务服务、引擎适配和测试
│  ├─ api/                      pywebview Bridge 与 FastAPI
│  ├─ application/              用例和业务编排
│  ├─ domain/                   任务、模型、工程等领域对象
│  └─ infrastructure/           Worker、FFmpeg、仓储和引擎实现
├─ web/                         Vue 3 + Vite 前端
├─ engines/                     So-VITS-SVC、SeedVC、DDSP-SVC 等引擎源码
├─ assets/                      随包模型、工具和离线 wheelhouse
├─ install/                     环境搭建和模型部署脚本
├─ installer/                   PyInstaller / Inno Setup 安装器
├─ native/                      JUCE VST3 Host 工程
├─ plugin-sdk/                  插件 SDK
├─ docs/                        使用、架构、API、插件和发布文档
├─ run.bat / run.ps1            源码启动入口
└─ setup_env.bat                运行环境搭建入口

数据目录与配置

默认用户数据目录是 .xb_svcb，与程序文件分离，主要包含：

• models：用户导入和下载的声音模型；
• works：作品、伴奏、人声和导出文件；
• editor_projects：音频编辑工程；
• uploads、cache、logs、settings：API 上传、缓存、日志和设置；
• plugins、plugin-data、theme/media：插件数据和主题媒体。

数据目录可以在软件内迁移，也可以通过 XB_DATA_DIR 指定。安装包升级通常不会覆盖该目录。

常用环境变量：

测试与开发

后端测试（项目根目录）：

uv run --project app --with pytest --with scipy==1.13.1 pytest app/tests -q -rs

运行时、安装器、离线打包和真实推理的分组与前置条件见 测试说明。

前端检查和测试：

cd web
npm run type-check
npm run test:unit -- --run
npm run build

修改 Python 后端时，建议从 app/api/bridge.py、app/application/ 开始，再阅读 app/infrastructure/ 中的引擎和 Worker。发布校验与安装包构建命令见开发与发布和安装器说明。

常见问题

生产模式提示找不到前端

生产模式要求 web/dist/index.html 存在。进入 web 执行 npm install 和 npm run build，或者使用 --dev 连接 Vite。

AI 环境搭建失败

确认 Python 已加入 PATH，并按组件重新执行 install/install.py --only COMPONENT。网络不稳定时可设置镜像：

set XB_HF_MIRROR=https://hf-mirror.com
set XB_PYPI_MIRROR=https://pypi.tuna.tsinghua.edu.cn/simple
set XB_GH_MIRROR=https://ghfast.top

推理提示缺少 pkg_resources

SVC 环境可能缺少兼容版本的 setuptools。RTX 50 系 cu128 安装可执行：

uv pip install --python <安装目录>\runtimes\svc-cu128\Scripts\python.exe "setuptools<81" wheel

分离或推理速度很慢

确认安装器选择的设备与本机硬件一致。NVIDIA 40 系及以下使用共享 cu126，RTX 50 系使用共享 cu128，AMD Radeon 优先使用 ROCm 10，也可选择 DirectML；没有兼容 GPU 时使用 CPU。

任务失败如何排查

在作品库中打开失败任务的日志，先查看 run.log 和对应 Worker 的输出。启动链路、环境路径和常见错误见源码安装与启动。

Roadmap

当前版本：v0.0.32

已完成的核心方向：

• So-VITS-SVC、RVC、SeedVC、DDSP-SVC 多框架推理；
• 多模型时间轴混唱和基础合唱；
• Audio Editor Lite 音频编辑工程；
• ModelScope 模型站；
• FastAPI 外部接入；
• NVIDIA CUDA、AMD ROCm 10、DirectML 和 CPU 路径；
• 插件中心与 Python / 前端插件运行时。

后续重点：

• 自动歌词识别和更完善的自动时间轴；
• 模型元数据标准化、兼容性检查和自动识别；
• 工程导入导出与自动保存；
• 更多歌声转换框架；
• 作品分类、视频导出和歌词视频能力；
• Intel GPU、CPU 性能和多 GPU 调度优化。

完整版本历史见 docs/release-notes/，当前版本说明见 v0.0.32 更新说明。

进一步阅读

• 文档总目录
• 源码安装与启动
• 系统架构
• 启动与推理链路
• FastAPI 接入
• 开发与发布
• 插件开发

---

🙏 致谢

• 🧁 模型来源 —— 目前软件内可用 / 演示的绝大部分声音模型，均由「白菜工厂1145号员工」提供。在此特别致谢 🙏，正是这些模型让本工具能开箱即用地体验完整翻唱流程。
• 📌 模型版权归原作者所有，请在其授权范围内使用；如有侵权或需要下架，请联系作者处理。
• 🛠️ 同时感谢上游开源项目：so-vits-svc、rvc-python / RVC、Seed-VC、DDSP-SVC、Ultimate Vocal Remover、DeepFilterNet、Pedalboard、ModelScope 魔搭社区 等。
• 🚀 后续会把更多模型逐一上传到「模型站」，方便在软件内直接搜索下载。

---

📄 许可

本项目自身代码采用 GNU General Public License v3.0 only（GPL-3.0-only）。Copyright © 2026 SDIJF1521。

⚠️ 本项目依赖/附带的第三方组件各自遵循其原始协议，使用与再分发时请遵守：

• so-vits-svc 4.1（svc-develop-team/so-vits-svc）：源码随安装分卷携带，遵循上游 AGPL-3.0。
• DDSP-SVC 6.3（yxlllc/DDSP-SVC）：源码随安装分卷携带，遵循上游 MIT License。
• 底模：ContentVec、NSF-HiFiGAN、RMVPE、FCPE 等各有其许可。
• UVR 模型：5_HP-Karaoke-UVR、UVR-DeEcho-DeReverb 等遵循 Ultimate Vocal Remover 项目相应许可。

GPL-3.0-only 仅覆盖本仓库自有代码，不改变上述第三方组件、模型和资源的原始授权条款。