Files
songforge/docs/使用手册.md
T
swlandCursor 6d79ab93a2
selftest / selftest (push) Canceled after 0s
Add align/recheck/compare, plugins, and refresh Agent docs.
Wire deliver_report/listen_pack/retry hooks; gen --auto-retry and intro light check; make AGENTS_MIN the up-to-date agent entry with full command map.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-10 13:03:44 +08:00

10 KiB
Raw Blame History

songforge 使用手册

本手册讲「怎么跑」。

文档 用途
../AGENTS_MIN.md Agent 默认入口(省 token)
../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 / 自动化

  1. 进仓先读 AGENTS_MIN.md(含 align/recheck/compare/插件);不够再读 AGENTS.md。
  2. 没有 local.toml、Comfy 没起、风格/歌名/歌词来源不清 → 先问用户。
  3. 需改代码:先征求同意;优先 plugins/;问清 commit/push/remote。
  4. 交付:qc --baseline PASS;看 report.md / listen/;开曲衬词硬门;style_fam 弱参考。
  5. 音频用 media / recheck / qc(qc_python:librosa/demucs/whisper…)。
  6. 默认 prefer_lean_tags;密度不够用 align;开曲 FAIL 用 gen --auto-retry。

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 结论
清理 prune --days 7 删过期 data/tmp,不动 runs/音频
一键体检 .\scripts\doctor_all.ps1 venv + local.toml + doctor

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. 歌词怎么写

  1. 先 target 拿音节区间,正文填进区间(偏稀 → 模型用拖腔填空)。
  2. 不要手写 [intro] / Instrumental 前奏 / tags——assemble 会注入。
  3. 段落用 [verse] [chorus] 等结构标记即可。
  4. 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 行为。