astrbot_plugin_matsuko_cover

适用于 AstrBot 的 AI 翻唱插件，支持 RVC、SVC-Fusion、SoulX-SVCVC 三种语音转换后端，以及网易云音乐、QQ 音乐、本地音频和 LLM 工具调用。

当前版本：v2.10.3

许可证：GNU AGPL-3.0

本项目基于 CCYellowStar2/astrbot_plugin_rvc_svc 扩展。

功能

功能	RVC	SVC-Fusion	SoulX-SVCVC
网易云 / QQ 音乐点歌	✅	✅	✅
本地音频翻唱	✅	✅	✅
LLM 智能点歌	✅	✅	✅
模型/音色列表和别名	✅	✅	✅
自动升降调	✅	✅	✅
推理进度发送到 QQ	✅	✅	✅
参数级结果缓存	由中间层提供	由中间层提供	✅
零样本参考音色	❌	❌	✅
固定/随机种子	❌	❌	✅

其他能力：

搜索、选歌、选模型、推理和发送结果的完整工作流。
QQ 音乐风控重试与可选第三方 VIP 播放地址 API。
RVC/SVC 的 F0、检索率、混响、延迟、人声/伴奏音量等参数。
MSST 模型列表、默认分离模型切换和分离质量参数。
翻唱任务查询、取消、批量翻唱、用户偏好和统计。
/查看翻唱缓存 [all|rvc|svc|svcvc] 查看各后端缓存占用；管理员可用 /清理翻唱缓存 [...] 安全清理。
取消任务会同步取消插件协程和 Gradio 推理任务，不再只隐藏任务状态。
QQ 语音发送失败时自动继续尝试发送音频文件。
默认关闭旧版 EQ/压缩/混响人声后处理，避免重复处理损伤音质；需要旧音色时可开启 vocal_postprocess。

架构

flowchart LR
    QQ[QQ / OneBot] --> AstrBot
    AstrBot --> Plugin[matsuko_cover]
    Plugin --> RVCAPI[RVC Gateway :3333]
    Plugin --> SVCAPI[SVC Gateway :9999]
    Plugin --> SVCVC[SVCVC-API-SVF :6767]
    RVCAPI --> RVC[RVC :2333]
    SVCAPI --> SVC[SVC-Fusion :7777]
    SVCVC --> SoulX[SoulX-Singer SVC :7861]

插件负责聊天交互、歌曲搜索/下载、参数选择和结果发送；中间层负责人声分离、缓存、后处理及调用实际推理引擎。

安装

将仓库克隆到 AstrBot 的插件目录：

cd AstrBot/data/plugins
git clone https://github.com/sdfsfsk/matsuko_cover.git astrbot_plugin_matsuko_cover
pip install -r astrbot_plugin_matsuko_cover/requirements.txt

随后重启 AstrBot，并在 WebUI 的插件配置中启用需要的后端。

依赖：

gradio_client
aiohttp
qqmusic-api-python

后端准备

中间层源码下载

旧版 README 中的百度网盘整合包不再作为主要下载入口，请直接使用以下公开项目：

项目	中间层端口	上游依赖	人声分离	适合场景
RVCSVC-API-amd	`3333` / `9999`	RVC `2333` / SVC-Fusion `7777`	UVR5 / HP5	环境较轻、兼容范围较广
RVCSVC-API-MSST	`3333` / `9999`	RVC `2333` / SVC-Fusion `7777`	BS-Roformer / MSST	更高分离质量、显存需求更高
SVCVC-API-SVF	`6767`	SoulX-Singer SVC `7861`	SoulX / 内置 MSST / 不分离	零样本参考音色转换

Caution

完整推理方案仅支持 Windows AMD 显卡（A 卡），NVIDIA、Intel GPU 和纯 CPU 环境不在支持范围内。 RVCSVC-API-amd 与 RVCSVC-API-MSST 使用相同的 3333/9999 端口，只需选择其中一个，不能同时启动；SVCVC-API-SVF 使用 6767 端口，可以与前两者之一同时运行，但还需要应用 AMD 补丁的 SoulX-Singer 上游。

公开仓库只包含源码和环境安装脚本，不包含已安装的 Python/ROCm 运行时、UVR5/MSST 权重、RVC/SVC/SoulX 模型、私人参考音色或歌曲缓存。请按照各项目 README 准备环境、上游引擎和分离模型；SVCVC 的内置 MSST 权重下载链接、SHA-256 和放置路径已写在 SVCVC-API-SVF README。

RVC

插件默认中间层：http://127.0.0.1:3333/
从 RVCSVC-API-amd 或 RVCSVC-API-MSST 选择一个中间层。
启动 RVC 上游和所选中间层。
使用 /刷新rvc模型 读取模型列表。

SVC-Fusion

插件默认中间层：http://127.0.0.1:9999/
从 RVCSVC-API-amd 或 RVCSVC-API-MSST 选择一个中间层。
启动 SVC-Fusion 上游和所选中间层。
兼容补丁参考：sdfsfsk/SVC-Fusion-fix
使用 /刷新svc模型 读取模型列表。

SoulX-SVCVC

SoulX-SVCVC 使用参考音频进行零样本音色转换，不需要训练 .pth 音色模型。

中间层：sdfsfsk/SVCVC-API-SVF
Windows AMD ROCm 补丁：sdfsfsk/SoulX-Singer-AMD-Patch
插件默认中间层：http://127.0.0.1:6767/
SoulX-Singer SVC 上游：http://127.0.0.1:7861/
目标歌曲分离：soulx（默认、由上游分离）、msst（中间层内置 BS-Roformer）或 none（直接交给 SoulX）。
msst 模式需要完整的 SVCVC-API-SVF/runtime-rocm/ 和模型权重；下载后无需依赖相邻的 RVCSVC-API-MSST 目录。

启动顺序：

启动 SoulX-Singer，选择 SVC voice conversion，等待 7861 就绪。
启动 SVCVC-API-SVF，等待 6767 就绪。
在插件配置中开启 enable_svcvc。
使用 /刷新svcvc音色。

若选择 msst 并开启“自动混回伴奏”，请使用带 soulx_svc_convert_external_acc_path 接口的 AMD 补丁版 SoulX-Singer；中间层会在分离前检查该接口，缺失时会立即提示而不浪费整首歌的分离时间。

参考音色放入 SVCVC-API-SVF 的 voice_profiles/。支持 WAV、FLAC、MP3、OGG、M4A 和 AAC；文件名默认作为音色 ID，也可添加同名 JSON：

{
  "profile_id": "my_voice",
  "display_name": "示例音色",
  "description": "干净、无伴奏的参考演唱",
  "prompt_vocal_sep": false
}

建议使用 5～30 秒、单人、无伴奏、低混响的干净音频。新增音色后需要重启或刷新中间层的 Gradio 音色选项，再执行插件刷新命令。

常用配置

配置	默认值	说明
`rvc_base_url`	`http://127.0.0.1:3333/`	RVC 中间层
`svc_base_url`	`http://127.0.0.1:9999/`	SVC-Fusion 中间层
`svcvc_base_url`	`http://127.0.0.1:6767/`	SoulX-SVCVC 中间层
`enable_rvc`	`true`	启用 RVC
`enable_svc`	`true`	启用 SVC-Fusion
`enable_svcvc`	`false`	启用 SoulX-SVCVC
`enable_qqmusic`	`true`	启用 QQ 音乐
`disable_netease`	`false`	禁用网易云点歌
`enable_progress_bar`	`true`	将后端进度发到聊天
`progress_update_interval`	`3`	进度消息最小间隔（秒）
`enable_send_file`	`false`	除 QQ 语音外再发送文件
`inference_timeout`	`300`	推理超时（秒）
`llm_force_mode`	`false`	禁用手动命令，只允许 LLM 工具

SoulX 在 AMD 上处理长歌曲时建议把 inference_timeout 和任务超时提高到 9000 秒。

SoulX 参数

配置	默认值	说明
`svcvc_prompt_vocal_sep`	`false`	是否分离参考音频
`svcvc_target_separation`	`soulx`	目标分离方式：`soulx` / `msst` / `none`
`svcvc_auto_shift`	`true`	自动匹配音域
`svcvc_auto_mix_acc`	`true`	自动混回伴奏
`svcvc_pitch_shift`	`0`	指定变调，范围 -36～36
`svcvc_n_step`	`32`	采样步数，越高通常越慢
`svcvc_cfg`	`1.0`	CFG 系数
`svcvc_seed`	`42`	固定种子（0–4294967295）
`svcvc_random_seed`	`false`	每次使用随机种子

固定种子且其他参数一致时可以命中持久缓存；开启随机种子后，SVCVC-API-SVF 默认不会读取或写入持久缓存。

命令

模型和后端

命令	说明
`/刷新rvc模型`	刷新 RVC 模型
`/刷新svc模型`	刷新 SVC-Fusion 模型
`/刷新svcvc音色`	刷新 SoulX 参考音色
`/列出msst模型`	查看 MSST 分离模型
`/切换msst模型 <序号或名称>`	切换 MSST 分离模型
`/列出svcvc分离模型`	查看 SVCVC-API-SVF 内置的 MSST 分离模型及当前选择
`/切换svcvc分离模型 <序号或名称>`	切换并持久化 SVCVC-API-SVF 的 MSST 分离模型（管理员）
`/设置rvc后端链接 <URL>`	修改 RVC 中间层地址（管理员）
`/设置svc后端链接 <URL>`	修改 SVC 中间层地址（管理员）
`/设置svcvc后端链接 <URL>`	修改 SVCVC 中间层地址（管理员）

点歌

命令	说明
`/rvc <歌名> [升降调]`	RVC + 网易云点歌
`/svc <歌名> [升降调]`	SVC-Fusion + 网易云点歌
`/svcvc <歌名> [升降调]`	SoulX-SVCVC + 网易云点歌
`/qqrvc <歌名> [升降调]`	RVC + QQ 音乐
`/qqsvc <歌名> [升降调]`	SVC-Fusion + QQ 音乐
`/qqsvcvc <歌名> [升降调]`	SoulX-SVCVC + QQ 音乐
`/qq点歌 <关键词>`	只搜索 QQ 音乐
`/本地翻唱`	使用最近上传/缓存的本地音频

任务

命令	说明
`/查看翻唱任务`	查看当前任务状态
`/取消翻唱任务`	请求取消当前任务
`/我的翻唱统计`	查看个人翻唱统计

如果启用了 llm_force_mode，上述手动命令会被禁用，请直接通过自然语言要求机器人点歌。

LLM 工具

插件提供以下主要 Function Calling 工具：

search_music：搜索网易云或 QQ 音乐。
rvc_cover：使用 RVC 翻唱。
svc_cover：使用 SVC-Fusion 翻唱。
svcvc_cover：使用 SoulX 参考音色翻唱。
smart_cover：自动完成搜索、选歌、模型匹配和翻唱。
batch_cover：批量翻唱。
get_available_models：读取三种引擎的模型/音色列表。
cover_absolute_path_audio：处理本地绝对路径音频。
cover_local_audio：处理用户上传的音频。
get_task_status / cancel_cover_task：查询或取消任务。

示例：

用甘城喵音色从 QQ 音乐翻唱《起风了》
用 RVC 第 2 个模型翻唱《晴天》，升 2 调
列出现在可用的 SoulX 参考音色

进度、缓存和结果发送

支持接收 Gradio 的下载、人声分离、F0、逐段推理、混音和导出进度。
progress_update_interval 控制聊天提示频率，避免刷屏。
中间层返回 cache_hit 时，插件会提示缓存命中并直接发送结果。
默认先发送 QQ 语音；语音发送失败时无论 enable_send_file 是否开启都会继续发送音频文件，避免结果丢失。
QQ 音乐由插件先下载到本地，再提交给中间层；网易云歌曲可由对应中间层直接处理。

常见问题

无法连接后端

确认对应端口正在监听，并检查插件配置中的 URL。SVCVC 必须先启动 SoulX 7861，再启动中间层 6767。

新增 SVCVC 音色后转换提示“不在 choices 中”

请升级 SVCVC-API-SVF v1.2.0 或更高版本，再执行 /刷新svcvc音色。新版下拉框允许动态音色 ID，并提供 WebUI 刷新按钮，无需重启。

SoulX 推理完成但机器人没有收到文件

请使用带 /soulx_svc_convert_path 接口的 AMD 补丁和最新版 SVCVC-API-SVF；该接口避免在同一台机器上通过 Gradio 重复下载大型 WAV。

QQ 音乐无法获取播放地址

普通歌曲优先使用 QQ 音乐接口。VIP/付费歌曲可选配置 third_party_api_key；默认值为空，仓库不包含任何 API 密钥。频繁触发风控时可调整重试设置。

SoulX 无法命中缓存

检查 svcvc_random_seed 是否关闭。歌曲内容、参考音色、种子、采样步数、CFG、升降调或模型资产变化都会生成新的缓存键。

更新日志

v2.10.3

修复 LLBot upload_group_file 已上传二进制、但群文件动态发布返回 code=-1002 时被误判为完全失败的问题。
上传异常后会查询群文件列表核对文件名、大小和时间；确认文件已存在时停止重复上传，并尝试获取群文件直链作为兜底提示。

v2.10.2

针对 LLBot 的 upload_group_file 临时性 code=-1002 / 请重试：语音发送后延迟上传，并按退避间隔重试三次。
最后一次重试自动使用纯 ASCII 文件名，排除协议端文件名编码兼容问题；日志会记录每次回执，全部失败时在 QQ 明确提示。

v2.10.1

SVCVC-API-SVF 的 MSST 子进程百分比可经 Gradio 进度事件实时输出到 QQ，并继续受 progress_update_interval 节流控制。
QQ 群聊启用“同时发送文件”时优先调用 OneBot upload_group_file，避免普通 File 消息被协议端静默忽略；失败时仍回退原文件消息。

v2.10.0

新增 /列出svcvc分离模型 与管理员 /切换svcvc分离模型，直接管理 SVCVC-API-SVF 内置 MSST 模型。
模型切换由中间层写回 config.json，重启后继续生效，分离缓存按模型指纹自动隔离。
SVCVC 的 MSST 自动混伴奏任务会在分离前检查 SoulX 外部伴奏接口，旧 7861 未加载补丁时立即提示，避免完成分离后才失败。

v2.8.0

新增 /查看翻唱缓存 与管理员 /清理翻唱缓存，统一管理 RVC、SVC 和 SoulX-SVCVC 缓存。
取消翻唱任务时同步取消实际异步任务与 Gradio Job，并拦截同一会话重复提交。
修复本地文件消息分支不可达、QQ 下载临时文件碰撞、下载流无前置大小限制和临时客户端泄漏。
Gradio 客户端初始化、提交和关闭移出事件循环，减少机器人消息处理卡顿。
新增 vocal_postprocess；默认保留后端原始人声，按需启用旧版 EQ/压缩/空间效果。
语音发送失败时始终回退发送音频文件。

v2.7.1

新增 SoulX-SVCVC 第三推理引擎和参考音色管理。
新增 /svcvc、/qqsvcvc、svcvc_cover 及三引擎智能路由。
新增固定/随机种子、SoulX 分离、自动变调、伴奏混合、采样步数和 CFG 配置。
将 SoulX 的预处理、F0 和逐段推理进度发送到 QQ。
支持中间层缓存标记，并在随机任务中避免误用持久缓存。
QQ 语音发送失败时继续尝试文件发送。
新增 MSST 模型列出、切换和后端调试信息。

v2.5.7

新增伴奏同步升降调开关。
补充 QQ 音乐依赖。
支持参数级中间层结果缓存。

更早版本记录可通过 Git 历史和 GitHub Releases 查看。

安全与版权

不要把私人音色、歌曲、生成结果、Cookie 或 API Key 提交到公开仓库。
使用者应确保对参考音频、歌曲和生成内容拥有相应授权，并遵守所在地区法律及平台规则。
本插件和相关模型可能产生模仿特定人物的声音，请勿用于冒充、欺骗、骚扰或其他侵权行为。

许可证

本仓库使用 GNU Affero General Public License v3.0。第三方项目、模型、音乐和 API 分别受其自身许可证及服务条款约束。

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
_conf_schema.json		_conf_schema.json
api.py		api.py
logo.png		logo.png
main.py		main.py
metadata.yaml		metadata.yaml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation