9.6 KiB
songforge 使用手册
本手册讲「怎么跑」。
| 文档 | 用途 |
|---|---|
../AGENTS.md |
Agent 必读:流水线、铁律、遇事先问 |
../README.md |
clone / 安装 / 远程 |
../config/default.toml |
算法默认(本仓为准) |
若仍嵌套 ComfyUI:生歌规则.md |
踩坑长文;与 default.toml 冲突时以 TOML + AGENTS 为准 |
推荐:clone 到任意目录后在仓根执行(先配 config/local.toml):
cd D:\CodeFiles\ProProjects\songforge
.\.venv\Scripts\python.exe songforge.py <命令> [选项]
仍嵌套在 ComfyUI 时:
cd D:\CodeFiles\Thinking\ComfyUI-MiniMaxH3\user\default\workflows
python songforge\songforge.py <命令> [选项]
local.toml 填 engine.server + paths.comfy_root 即可连本机 ComfyUI。QC 用 paths.qc_python(常为 ComfyUI venv)。
给 Agent / 自动化
- 先读
AGENTS.md,再跑命令。 - 没有
local.toml、Comfy 没起、风格/歌名/歌词来源不清 → 先问用户,不要猜路径或改铁律。 - 交付以
qc --baselinePASS 为准;不要把style_fam说成「风格已验证」。
1. 标准流水线
doctor → target → 写歌词 → check → gen → qc --baseline
| 步 | 命令 | 失败时 |
|---|---|---|
| 体检 | doctor |
先起 ComfyUI;缺模型按提示补齐 |
| 查字数 | target --style pop --bpm 104 --dur 180 |
按打印区间写歌词 |
| 校验 | check --style … --title … --lyrics-file … |
只改歌词,不许改采样参数 |
| 生成 | gen … |
看 data/runs/<日>/<id>/run.log;服务挂了再 doctor |
| 验收 | qc --run gen-… --baseline |
FAIL 修歌/重跑,不放宽阈值 |
| 索引 | catalog / catalog --rebuild |
查歌名/风格/BPM/QC 结论 |
qc 报告里的 style_fam / style_conf 是弱参考,不会单独导致 FAIL。对外不要把 PASS 说成「风格已验证」——当前风格物理保证主要是实测 BPM 对齐。
2. 命令详解
2.1 doctor
检查:服务可达、GPU、锁定 checkpoint/LoRA、采样参数、时长区间。
python songforge\songforge.py doctor
python songforge\songforge.py doctor --server http://127.0.0.1:8188
2.2 styles
列出 config/styles.json 里可用的 --style 键及默认 bpm/key/duration。
python songforge\songforge.py styles
2.3 target
按 BPM、时长、密度档算出音节放行区间(硬校验同源公式)。
python songforge\songforge.py target --style pop --bpm 104 --dur 180
python songforge\songforge.py target --bpm 92 --dur 165 --profile sparse
常用:--style / --bpm / --dur / --profile(sparse = 人声点缀档)。
2.4 check
纯本地:铁律词条、前奏注入结果、词典、密度窗口。不连 ComfyUI。
python songforge\songforge.py check --style pop --title 夜班 --lyrics-file songforge\_archive\lyrics_corpus\某歌.txt
与 gen 共用同一套 assemble + do_validate,check 过再 gen,避免白跑。
2.5 gen
组装 tags/歌词(自动注入 8 小节器乐前奏与铁律)→ 写 workflow → 提交 ComfyUI → 写 manifest。
python songforge\songforge.py gen `
--style pop --title 夜班 `
--lyrics-file path\to\lyrics.txt `
--seeds 1
| 参数 | 说明 |
|---|---|
--style |
风格键,必填 |
--title |
歌名,必填 |
--lyrics-file / --lyrics |
二选一 |
--bpm --key --dur |
覆盖风格默认 |
--instruments --mood |
覆盖风格描述 |
--seeds |
多 seed 选优(默认 1) |
--seed |
起始 seed |
--dry-run |
只写 workflow / payload_preview,不提交 |
--language |
zh / ja / en |
--instrumental |
纯器乐(密度闸门不适用) |
--chill-vocal |
低音吟唱路径 |
--lean-tags |
精简 tags 路径 |
--profile sparse |
稀疏密度档 |
--log-level / --quiet |
日志 |
产出目录:songforge\data\runs\YYYY-MM-DD\gen-YYYYMMDD-HHMMSS-mmm\
| 文件 | 内容 |
|---|---|
run.log |
JSONL 结构化日志 |
lyrics.txt |
最终歌词(含注入前奏) |
tags.txt |
最终 tags(含铁律) |
wf_*.json |
提交用 UI workflow |
manifest.json |
seed / prompt_id / 输出路径 / intro_bars 等 |
payload_preview.json |
仅 --dry-run |
qc.json |
qc --run 后写入 |
音频在 ComfyUI:output\MyMusic\(可用 local.json 的 music_dir 覆盖)。
2.6 qc
验收。测量在 tools/qc_worker.py,由 venv Python 子进程执行。
python songforge\songforge.py qc --run gen-20261009-120000-123 --baseline
python songforge\songforge.py qc --run songforge\data\runs\2026-10-09\gen-20261009-120000-123 --baseline
python songforge\songforge.py qc --file D:\path\to\song.flac --dur 165 --baseline
| 参数 | 说明 |
|---|---|
--run |
run_id,或 data/runs/... 路径(两者都行) |
--file |
直接验单个 flac |
--baseline |
交付必带:与 8 首已认可老歌对照声线 |
--baseline-only / --save-baseline |
校准/固化软阈值(维护用) |
本机路径:config/local.json 的 qc_python / comfy_root;或环境变量 SONGFORGE_QC_PYTHON、SONGFORGE_COMFY_ROOT。
2.7 runs / show / catalog
python songforge\songforge.py runs
python songforge\songforge.py catalog --day 2026-10-09
python songforge\songforge.py catalog --rebuild
python songforge\songforge.py show gen-20261009-120000-123
2.8 selftest
不连 ComfyUI 生成,跑配置优先级、模型锁定、铁律、密度、回归等。怀疑 CLI 坏了再跑。
python songforge\songforge.py selftest
3. 配置与目录
3.0 目录(项目 vs 数据)
| 级别 | 用途 | 默认(相对 workflows) |
|---|---|---|
| 项目 | 新歌词 | songforge/input/lyrics/ |
| 项目 | QC/风格基线 | songforge/config/baseline/ |
| 本机 | 绝对路径覆盖 | songforge/config/local.toml(gitignore) |
| 数据 | gen 产物 | songforge/data/runs/YYYY-MM-DD/ |
| 数据 | 临时日志 | songforge/data/tmp/YYYY-MM-DD/ |
| 数据 | 全局索引 | songforge/index/catalog.jsonl |
| 数据 | QC 缓存 | songforge/cache/qc/ |
| 外部 | 音频成品 | <ComfyUI>/output/MyMusic/ |
Agent 远程做歌请读 songforge/AGENTS.md。
3.1 该改哪里
| 想改 | 文件 |
|---|---|
| 模型 / 采样 / 时长区间 / 相对路径 | config/default.toml |
| 本机 Comfy 根 / QC Python / 音乐目录 | config/local.toml(从 example 复制) |
| 风格 bpm/key/乐器/情绪 | config/styles.json |
| 禁词 | config/lexicon.json |
| QC 软阈值 | config/baseline/qc_baseline.json(工具校准,勿手拍) |
| workflow 节点拓扑 | 配置里的模板名(在 workflows 根下) |
不要为改参数去改 data/runs/ 里某次生成的 JSON——下次 gen 会按模板+配置重写。
3.2 优先级
命令行 > SONGFORGE_* 环境变量 > local.toml > default.toml > DEFAULTS
算法配置用 TOML;Comfy workflow 图仍是 JSON。常用环境变量:SONGFORGE_SERVER、SONGFORGE_COMFY_ROOT、SONGFORGE_QC_PYTHON、SONGFORGE_MUSIC_DIR、SONGFORGE_SHIFT、SONGFORGE_RUNS。
3.3 已锁定默认(勿随意改)
"model.checkpoint": "ace_step_1.5_turbo_swl_fused.safetensors",
"model.lora": "swl_voice_best_ep257.safetensors",
"sampler": { "shift": 5.5, "steps": 28, "cfg": 2.0 },
"encode.temperature": 0.68,
"song.duration_range": [150, 200]
denied_checkpoints 含 aio / yue2;doctor 会拦。
4. 歌词怎么写
- 先
target拿音节区间,正文填进区间(偏稀 → 模型用拖腔填空)。 - 不要手写
[intro]/ Instrumental 前奏 / tags——assemble会注入。 - 段落用
[verse][chorus]等结构标记即可。 check不过 → 改字数或结构,不要动 shift/steps。
密度档:
- 默认:人声填满(中文说唱/流行)
--profile sparse:音乐主导、人声点缀(勿用默认档硬套)
5. 日志
log/logger.py:控制台一行可读 + runs/<run_id>/run.log JSONL。
字段示例:ts、run_id、level、msg,以及 seed / prompt_id / title 等。
python songforge\songforge.py gen ... --log-level debug
python songforge\songforge.py gen ... --quiet
排错优先打开对应 run.log 和 manifest.json,不要只看控制台最后一行。
6. 失败速查
| 现象 | 处理 |
|---|---|
| doctor 服务不可达 | 启动 ComfyUI(8188) |
| check 密度不匹配 | 改歌词到 target 区间 |
| gen KeyError / 提交失败 | 用 CLI,勿手转 API;跑 selftest |
| 改了参数没生效 | 是否改了 workflow JSON?应改 config/*.json |
| qc 声线 FAIL 且 voice_nn=null | 漏了 --baseline |
| 开头仍是人声 | 看规范第 0 章;重 gen,勿放宽 QC |
| CLI 本身崩溃 | --dry-run 拿 workflow 到手跑;或 fallback 旧 remake_v5.py(勿删) |
改规则/配置前先备份:
python songforge\tools\backup.py --note "说明" --from-root D:\CodeFiles\Thinking\ComfyUI-MiniMaxH3 AGENTS.md 生歌规则.md
7. 与规范文档的分工
| 文档 | 职责 |
|---|---|
生歌规则.md |
铁律、模型、采样、密度公式、踩坑、版本 |
README.md |
项目入口、30 秒上手 |
docs/使用手册.md |
命令、目录、配置操作、流水线 |
行为冲突时以 生歌规则.md + config/default.json 为准;手册只描述当前 CLI 行为。