Files
songforge/docs/使用手册.md
T

270 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.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 优先级
```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_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 行为。