Files
songforge/README.md
T

97 lines
3.4 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
本地 ACE-Step 生歌 CLI:锁定模型与声线 LoRA、铁律前奏注入、歌词密度硬校验、QC 验收。
自己用爽是第一目标;代码按 MIT 开源,方便别人在 ComfyUI + ACE-Step 上复用同一套流水线。
| 文档 | 给谁 |
|------|------|
| [`AGENTS.md`](AGENTS.md) | Agent / 自动化(做歌时重读) |
| [`docs/使用手册.md`](docs/使用手册.md) | 人类操作 |
## 两个 Python 环境(别混)
| 环境 | 用途 | 怎么来 |
|------|------|--------|
| **项目 `.venv`** | CLI:`doctor` / `target` / `check` / `gen` / `catalog` | `scripts\setup_venv.ps1` |
| **`qc_python`** | QC 音频栈(librosa / torch / demucs) | `config/local.toml` 指向 ComfyUI venv,或自建重环境 |
```powershell
# 1) 建 CLI 环境(推荐 Python 3.13 / ≥3.11)
cd path\to\songforge
.\scripts\setup_venv.ps1
# 2) 本机路径
copy config\local.toml.example config\local.toml
# 编辑 comfy_root / qc_python / music_dir
# 3) 工作目录:包的父目录(文件夹名必须是 songforge)
cd ..
.\songforge\.venv\Scripts\python.exe songforge\songforge.py doctor
```
嵌套在 ComfyUI 时父目录就是 `user\default\workflows`。
## 配置:TOML vs JSON
| 文件 | 格式 | 作用 |
|------|------|------|
| `config/default.toml` | **TOML** | 算法 / 采样 / 相对路径(可提交) |
| `config/local.toml` | **TOML** | 本机绝对路径(gitignore) |
| `config/styles.json` `lexicon.json` | JSON | 风格字典 / 禁词(数据) |
| `config/baseline/*.json` | JSON | QC 基线数值 |
| `workflows/*.json` 与 Comfy 模板 | JSON | **只有** workflow 图用 JSON |
优先级:`命令行 > SONGFORGE_* > local.toml > default.toml > DEFAULTS`
(仍可读旧的 `local.json` / `default.json`,同名时 TOML 覆盖。)
## 30 秒流水线
```powershell
python songforge\songforge.py doctor
python songforge\songforge.py target --style pop --bpm 104 --dur 180
python songforge\songforge.py check --style pop --title 歌名 --lyrics-file songforge\input\lyrics\歌名.txt
python songforge\songforge.py gen --style pop --title 歌名 --lyrics-file songforge\input\lyrics\歌名.txt
python songforge\songforge.py qc --run gen-<时间戳> --baseline
python songforge\songforge.py catalog --limit 20
```
`qc` 必须带 `--baseline`。
## 硬约束(摘要)
| 项 | 值 |
|----|-----|
| 模型 | `ace_step_1.5_turbo_swl_fused` + `swl_voice_best_ep257`(0.5/0.5) |
| 采样 | shift=5.5 / steps=28 / cfg=2.0 / temperature=0.68 |
| 时长 | 完整歌 150–200 秒 |
| 前奏 | 8 小节器乐 hook;CLI 自动注入 |
## 目录(项目 vs 数据)
```
songforge/ # Git 仓根 = 包根
config/default.toml # 算法配置
config/local.toml # 本机(勿提交)
config/baseline/ # QC 基线
cli/ core/ rules/ ...
data/runs/YYYY-MM-DD/ # gen 产物
data/tmp/YYYY-MM-DD/ # doctor/check
index/catalog.jsonl
workflows/template.json # 包内备用模板
.venv/ # CLI 专用(勿提交)
.secrets/ # 本地 token(勿提交)
```
音频成品仍在 ComfyUI `output/MyMusic/`(可用 `music_dir` 覆盖)。
## Git
- `main`:项目资产
- `archive/full-snapshot`:本地过程数据备份,**不要 push**
- `.secrets/`、`config/local.toml`、`.venv/`、`data/**` 均已 ignore
## License
MIT — 见 [LICENSE](LICENSE)。