270 lines
8.8 KiB
Markdown
270 lines
8.8 KiB
Markdown
# 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/<日>/<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、采样参数、时长区间。
|
||
|
||
```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.json`(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.json` |
|
||
| 本机 Comfy 根 / QC Python / 音乐目录 | `config/local.json`(从 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_* 环境变量 > config/local.json > config/default.json > DEFAULTS
|
||
```
|
||
|
||
常用环境变量:`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_id>/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 行为。
|