# SoundMagic 声魔法

Local audio tools for AI agents: speech, voice cloning, music, sound effects and audio editing through MCP. Models load on demand and GPU workers shut down after inactivity. Built and tested on Windows with an 8 GB NVIDIA GPU.

面向 Windows + NVIDIA GPU 的本地声音插件，已在 RTX 4060 Laptop 上验证。大模型通过 MCP 提交规范 JSON 任务；模型按需加载、单卡串行处理，结束后保温，空闲 300 秒自动结束推理进程和调度进程。

当前设备实测：RTX 4060 Laptop，8188 MiB 显存，约 32GB 系统内存。模型与虚拟环境位于本项目，输出保存在 `outputs/<job_id>/`。推理默认离线，下载和升级单独执行。

## 工作方式

```mermaid
flowchart LR
    A[你的自然语言要求] --> B[大模型 + 插件技能]
    B --> C[MCP / 版本化 JSON]
    C --> D[SQLite 持久任务队列]
    D --> E[按需启动调度进程]
    E --> F[单个 GPU 工作进程]
    F --> G[音频 + 参数 + 耗时 + 哈希]
    F --> H{空闲 5 分钟?}
    H -->|有新任务| F
    H -->|是| I[结束进程 释放显存和内存]
```

MCP 接入层随调用方运行，保持轻量，不导入 PyTorch。未收到任务时不启动调度器和 GPU 工作进程；关闭调用方后接入层也退出。纯 CLI 调用完全退出后可以没有任何 SoundMagic 常驻进程。状态查询不延长保温时间。不同大模型客户端共用一条队列，GPU 同时只执行一个任务。

## 模型选择

| 能力 | 引擎 | 本机运行方式 |
| --- | --- | --- |
| 中文及多语种 TTS | Qwen3-TTS 0.6B CustomVoice | BF16、SDPA、批量 1，速度优先 |
| 情绪控制与高质量 TTS | Qwen3-TTS 1.7B CustomVoice | 按任务切换，质量优先 |
| 用参考音色说新文本 | Qwen3-TTS 0.6B / 1.7B Base | 3–30 秒干净参考录音，最好附准确转录 |
| 根据描述设计新音色 | Qwen3-TTS 1.7B VoiceDesign | 指令描述声音特征 |
| 音效、短器乐 | TangoFlux | BF16，25 步，最长 30 秒 |
| 优先音效引擎（需单独授权与安装） | Stable Audio 3 Small SFX | FP16、8 步、分段解码；未安装时使用 TangoFlux |
| 歌词歌曲生成 | ACE-Step 1.5 Turbo | 批量 1，8 步，CPU/DiT 内存卸载；外部大模型提供描述与歌词 |
| 人声/伴奏分离 | HTDemucs | GPU，6 秒窗口 |
| 歌声或说话换音色 | Seed-VC | 两种独立模型配置，歌声保留基频；参考音色无需先训练 |
| 剪辑、混音、响度、变速、重采样 | FFmpeg | CPU 执行，省去加载大模型 |

选择依据与候选比较见 [docs/model-selection.md](docs/model-selection.md)。`available` 代表文件与运行环境已配置；`validation` 才标明实际生成验证状态。以 `soundmagic capabilities` 和 [docs/validation.md](docs/validation.md) 为准。

## 调用

```powershell
.\.bridge\Scripts\python.exe -m soundmagic.cli capabilities
.\.bridge\Scripts\python.exe -m soundmagic.cli submit examples\tts.json
.\.bridge\Scripts\python.exe -m soundmagic.cli wait <job_id> --seconds 30
.\.bridge\Scripts\python.exe -m soundmagic.cli status <job_id>
.\.bridge\Scripts\python.exe -m soundmagic.cli cancel <job_id>
.\.bridge\Scripts\python.exe -m soundmagic.cli release
```

提交示例：

```json
{
  "schema_version": 1,
  "operation": "tts",
  "mode": "preset",
  "quality": "fast",
  "text": "你好，欢迎来到我的声音工作室。",
  "language": "Chinese",
  "speaker": "Vivian"
}
```

MCP 工具：`soundmagic_capabilities`、`soundmagic_submit`、`soundmagic_status`、`soundmagic_wait`、`soundmagic_cancel`、`soundmagic_release`。任务返回 `queued/running/succeeded/failed/cancelled`。`submit` 的成功只表示已入队，需等待 `succeeded` 才有音频结果。`wait` 最长 50 秒，可重复调用。

克隆你的声音：把清晰录音放入 `inputs/my-voice.wav`，调整 `examples/clone.json` 中录音实际转录。示例所需素材及路径说明见 [examples/README.md](examples/README.md)。歌曲换声由大模型依次调用 `separate → convert_voice → mix`，用上一步返回的绝对文件路径作为下一步输入。

输入限于 `inputs`、`outputs` 或明确配置的文件目录，不接受网络 URL。通过 `config.local.json` 扩展 `input_roots` 或调整 `idle_timeout_seconds`。输出路径由插件分配，原音频不被覆盖。内部请求不开放任意命令执行。

## 安装与接入

本项目的安装环境：`.bridge` 为 MCP/维护，`.venv` 为 Qwen，`.envs/audio` 为 TangoFlux/Seed-VC/Demucs，`.envs/ace` 为 ACE-Step，`.envs/stable` 为 Stable Audio。不同模型的 Transformers 版本冲突通过独立环境解决。

需要 Windows、[Git](https://git-scm.com/)、[uv](https://docs.astral.sh/uv/) 和网络；脚本使用 Python 3.12，可由 uv 下载。GPU 推理需要兼容 CUDA 12.6 的 NVIDIA 驱动。验证设备为 8 GB 显存、32 GB RAM；完整模型约 40 GiB，另需环境、缓存和输出空间。

首次安装完整环境与无需额外账号授权的模型：

```powershell
git clone https://github.com/JasondeWest/SoundMagic.git
cd SoundMagic
powershell -File scripts/setup-all.ps1 -DownloadModels
.\.bridge\Scripts\python.exe -m soundmagic.cli capabilities
```

仅体验 MCP、队列及 FFmpeg 编辑，可运行 `powershell -File scripts/setup.ps1`，暂不下载 GPU 模型。语音最小安装可用 `powershell -File scripts/setup.ps1 -TTS`，再按下方命令下载 Qwen 模型。已有可用环境无需重复运行安装脚本。

`requirements/*.lock.txt` 固定五套环境依赖，`sources.lock.json` 固定四个上游源码提交；CUDA 轮子固定 SHA256。完整安装脚本当前使用清华 PyPI 镜像，部分 PyTorch 轮子使用南京大学镜像。不要把这些环境合并。脚本会保留并拒绝覆盖已修改或版本不同的上游源码；全新机器恢复脚本尚未在第二台设备重跑。

Stable Audio 是可选引擎。需要它时，运行 `powershell -File scripts/login-huggingface.ps1`，在官方模型页面自行完成账号与条款授权，再运行以下命令。授权与模型文件不会随本仓库分发；登录凭据由 Hugging Face CLI 保存在本项目忽略的缓存目录。

```powershell
.\.bridge\Scripts\python.exe scripts\install_stable.py sfx --stage-only
.\.bridge\Scripts\python.exe scripts\activate_staged.py stable-sfx
```

下载模型：

```powershell
.\.bridge\Scripts\python.exe scripts\install_model.py qwen-0.6b-preset
.\.bridge\Scripts\python.exe scripts\install_model.py qwen-0.6b-clone
.\.bridge\Scripts\python.exe scripts\install_audio_models.py ace-step --stage-only
.\.bridge\Scripts\python.exe scripts\activate_staged.py ace-step
```

项目中的插件清单和技能在 `plugins/soundmagic`。安装脚本会调用 `scripts/configure_plugin.py`，按当前绝对路径生成插件 `.mcp.json` 和项目根目录 `codex-mcp.toml`。这两份机器配置不纳入 Git，移动项目后需重新生成，并更新客户端配置或已安装的插件副本。

Codex 的 MCP 配置片段见生成的 `codex-mcp.toml`。使用个人插件时，以生成配置后的 `plugins/soundmagic` 为插件源。通用 MCP 客户端启动 `.bridge/Scripts/python.exe -m soundmagic.mcp_server`，并设置 `SOUNDMAGIC_ROOT` 为本项目绝对路径及 `PYTHONPATH` 为本项目 `src` 目录。仓库本身不会自动在客户端中安装插件。

## 更新与故障恢复

模型下载解析并固定上游提交版本。Qwen 下载记录逐文件 SHA256；高级模型固定仓库提交，Demucs 校验官方哈希。`--stage-only` 先暂存；结束现有任务并执行 `release`，确认 `status` 为 stopped，再激活。旧模型文件保留，注册表历史在 `models/history`，可用 `scripts/rollback_models.py <snapshot.json>` 恢复。

代码更新在独立目录或版本控制分支完成，先跑测试与短音频实测，再更新插件缓存版本。运行环境依赖由 lock 文件恢复；注册表回滚仅回滚模型选择，不自动回滚 Python 依赖。

断电/崩溃后，下次启动把被中断的 running 任务标为 failed，保留排队任务。重试失败任务应使用新 ID；不确定提交是否成功时用相同 `idempotency_key` 查询/重提。同一 ID 不能用于不同内容。超时和取消会结束整个工作进程；Windows Job Object 也会在调度器异常退出时清理工作进程及其子进程。

默认单任务超时 30 分钟、队列上限 32。日志在 `runtime/daemon.log` 与 `runtime/worker.log`；任务请求记录在本机 SQLite 中，可能包含文本、歌词和参考音频路径。

## 验证

```powershell
.\.bridge\Scripts\python.exe -m pytest -q
.\.bridge\Scripts\python.exe scripts\smoke_mcp.py
.\.bridge\Scripts\python.exe scripts\benchmark.py examples\tts.json --warm
```

测试覆盖真实 FFmpeg 输出、进程唤醒、复用、闲置退出、并发排队、幂等提交、失败恢复和路径约束。GPU 实测单独记录，不用单元测试结果冒充模型质量或速度结果。相同随机种子保留生成条件，但不同 CUDA 操作/版本不保证逐字节一致。

## 开源与贡献

SoundMagic 自有代码采用 [MIT License](LICENSE)。第三方源码、依赖、模型权重和音频素材仍按各自许可使用，详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。本仓库不包含模型、虚拟环境、账号凭据、个人录音、生成音频或任务数据库。

欢迎提交 Issue 和 Pull Request。修改后请运行上述工程测试；涉及模型后端时，附上具体模型版本、设备、参数和实际生成验证结果。报告问题前请去除日志中的私人文本、歌词、音频路径和账号信息。