selftest / selftest (push) Canceled after 0s
Stop naming filler syllables in tags (they conditioned the model); default prefer_lean_tags; hard-fail intro_filler in QC; add plugins/ hook bus as thin microkernel extension point. Co-authored-by: Cursor <cursoragent@cursor.com>
4.8 KiB
4.8 KiB
songforge
本地 ACE-Step 生歌 CLI:锁定模型与声线 LoRA、铁律前奏注入、歌词密度硬校验、QC 验收。
独立项目:clone 到任意目录,写好 config/local.toml 指向本机 ComfyUI,即可生成。
| 文档 | 给谁 | 何时读 |
|---|---|---|
AGENTS_MIN.md |
Agent 默认入口 | 先读这份(省 token) |
AGENTS.md |
Agent 全文 | dig 失败 / 改铁律时再读 |
docs/使用手册.md |
人类 | 命令与配置详解 |
config/local.toml.example |
所有人 | 第一次连本机 ComfyUI |
给 Agent:默认只读
AGENTS_MIN.md。缺local.toml、Comfy 没起、风格/歌名不清、想改模型或阈值时——先问用户。需改代码时先征求同意,建议 git 备份或新插件旁路,并问清是否 commit/push。音频探测/转码/截取用songforge media,不要读大源码。
一键体检
.\scripts\doctor_all.ps1
会:缺 .venv 则创建 → 缺 local.toml 则从 example 复制并提示编辑 → 跑 doctor → 打印下一步。
换目录也能用(推荐)
cd D:\CodeFiles\ProProjects
git clone https://git.nnrc.ren/swl/songforge.git
# 或:git clone https://github.com/lsuen/songforge.git
cd songforge
.\scripts\doctor_all.ps1
# 按提示编辑 config\local.toml 后,启动 ComfyUI,再跑一次 doctor_all
不必把本仓放进 ComfyUI 的 user/default/workflows。
需要的模型(ComfyUI 侧)
在 local.toml 的 comfy_root 下准备:
| 类型 | 文件名 | 目录 |
|---|---|---|
| Checkpoint | ace_step_1.5_turbo_swl_fused.safetensors |
models/checkpoints/ |
| LoRA | swl_voice_best_ep257.safetensors |
models/loras/ |
- 默认 LoRA 是作者定制声线;别人没有同文件时
doctor会 FAIL。 - 可换成自己的 LoRA,并改
config/default.toml的[model](声线会变;不要用禁用名单里的 YuE2/aio)。 - 缺文件时
doctor会打印人话排查步骤。
两个 Python 环境
| 环境 | 用途 |
|---|---|
本仓 .venv |
CLI:doctor / check / gen / catalog / prune |
qc_python |
QC 音频栈(可继续用 ComfyUI 的 venv) |
配置:TOML vs JSON
| 文件 | 作用 |
|---|---|
config/default.toml |
算法 / 相对路径(相对本仓根) |
config/local.toml |
本机 Comfy 根、服务地址、QC Python(勿提交) |
workflows/template.json |
workflow 图(JSON) |
config/baseline/*.json |
QC 基线数据 |
.secrets/ |
远程 token(勿提交) |
优先级:命令行 > SONGFORGE_* > local.toml > default.toml > DEFAULTS
流水线
.\.venv\Scripts\python.exe songforge.py target --style pop --bpm 104 --dur 180
.\.venv\Scripts\python.exe songforge.py check --style pop --title 灯还亮着 --lyrics-file input\lyrics\pop_灯还亮着.txt
.\.venv\Scripts\python.exe songforge.py gen --style pop --title 灯还亮着 --lyrics-file input\lyrics\pop_灯还亮着.txt
.\.venv\Scripts\python.exe songforge.py qc --run gen-<时间戳> --baseline
.\.venv\Scripts\python.exe songforge.py prune --days 7 # 清过期 tmp
.\.venv\Scripts\python.exe songforge.py prune --days 7 --dry-run
qc 必须带 --baseline。样例歌词见 input/lyrics/。Agent 规则见 AGENTS.md。
硬约束(摘要)
| 项 | 值 |
|---|---|
| 模型 | 见上表(0.5/0.5 LoRA) |
| 采样 | shift=5.5 / steps=28 / cfg=2.0 / temperature=0.68 |
| 时长 | 完整歌 150–200 秒 |
| 前奏 | 8 小节器乐 hook;CLI 自动注入 |
| 衬音 | 禁止开曲衬词;默认 prefer_lean_tags;tags 禁止点名 mm/ooh/嗯;QC 前奏窗 intro_filler 硬 FAIL |
| 插件 | plugins/ 微内核外挂;内核在 core/ + rules/ + cli/ |
音频库
qc / media 经 qc_python 使用:librosa、soundfile、torch、torchaudio、demucs、whisper。轻量 .venv 不装这些。
音频工具(Agent 优先用 CLI)
.\.venv\Scripts\python.exe songforge.py media info --file path.flac
.\.venv\Scripts\python.exe songforge.py media convert --file in.flac --to wav
.\.venv\Scripts\python.exe songforge.py media clip --file in.flac --start 12 --dur 8 --out out.wav
依赖 config/local.toml 的 qc_python(与 qc 同栈)。
远程(双 remote)
| 名 | URL | 用途 |
|---|---|---|
gitea |
https://git.nnrc.ren/swl/songforge | 常用推送 |
origin / GitHub |
https://github.com/lsuen/songforge | 公开镜像 |
git remote -v
git push gitea main
git push origin main # 或经 ghfast
Agent 推送前先问用户推哪个 remote;不要推 archive/*、.secrets、local.toml。
License
MIT — 见 LICENSE。