# songforge 使用手册 本手册讲「怎么跑」。参数铁律、踩坑与版本史见上级目录 [`生歌规则.md`](../../生歌规则.md)(唯一规范)。 工作目录始终: ```powershell cd D:\CodeFiles\Thinking\ComfyUI-MiniMaxH3\user\default\workflows ``` 入口: ```powershell python songforge\songforge.py <命令> [选项] ``` 音频栈(librosa/torch 等)在 `C:\comfyui-venv\Scripts\python.exe`;主 CLI 用系统 Python,`qc` 会自动起子进程调用 venv。 --- ## 1. 标准流水线 ```text doctor → target → 写歌词 → check → gen → qc --baseline ``` | 步 | 命令 | 失败时 | |----|------|--------| | 体检 | `doctor` | 先起 ComfyUI;缺模型按提示补齐 | | 查字数 | `target --style pop --bpm 104 --dur 180` | 按打印区间写歌词 | | 校验 | `check --style … --title … --lyrics-file …` | **只改歌词**,不许改采样参数 | | 生成 | `gen …` | 看 `data/runs/<日>//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、采样参数、时长区间。 ```powershell 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。 ```powershell python songforge\songforge.py styles ``` ### 2.3 target 按 BPM、时长、密度档算出音节放行区间(硬校验同源公式)。 ```powershell 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。 ```powershell 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。 ```powershell 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 子进程执行。 ```powershell 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 ```powershell 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 坏了再跑。 ```powershell 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/` | | 外部 | 音频成品 | `/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 优先级 ```text 命令行 > 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 已锁定默认(勿随意改) ```json "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.log` JSONL。 字段示例:`ts`、`run_id`、`level`、`msg`,以及 `seed` / `prompt_id` / `title` 等。 ```powershell 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`(勿删) | 改规则/配置前先备份: ```powershell 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 行为。