Files
songforge/README.md
T
swlandCursor b1afe68f3c
selftest / selftest (push) Canceled after 0s
Fix opening filler via lean tags and intro QC gate.
Stop naming filler syllables in tags (they conditioned the model); default prefer_lean_tags; hard-fail intro_filler in QC; add plugins/ hook bus as thin microkernel extension point.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-10 12:49:25 +08:00

126 lines
4.8 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 验收。
**独立项目**:clone 到任意目录,写好 `config/local.toml` 指向本机 ComfyUI,即可生成。
| 文档 | 给谁 | 何时读 |
|------|------|--------|
| **[`AGENTS_MIN.md`](AGENTS_MIN.md)** | **Agent 默认入口** | **先读这份(省 token)** |
| [`AGENTS.md`](AGENTS.md) | Agent 全文 | dig 失败 / 改铁律时再读 |
| [`docs/使用手册.md`](docs/使用手册.md) | 人类 | 命令与配置详解 |
| [`config/local.toml.example`](config/local.toml.example) | 所有人 | 第一次连本机 ComfyUI |
> 给 Agent:默认只读 `AGENTS_MIN.md`。缺 `local.toml`、Comfy 没起、风格/歌名不清、想改模型或阈值时——**先问用户**。需改代码时先征求同意,建议 git 备份或新插件旁路,并问清是否 commit/push。音频探测/转码/截取用 `songforge media`,不要读大源码。
## 一键体检
```powershell
.\scripts\doctor_all.ps1
```
会:缺 `.venv` 则创建 → 缺 `local.toml` 则从 example 复制并提示编辑 → 跑 `doctor` → 打印下一步。
## 换目录也能用(推荐)
```powershell
cd D:\CodeFiles\ProProjects
git clone https://git.nnrc.ren/swl/songforge.git
# 或:git clone https://github.com/lsuen/songforge.git
cd songforge
.\scripts\doctor_all.ps1
# 按提示编辑 config\local.toml 后,启动 ComfyUI,再跑一次 doctor_all
```
不必把本仓放进 ComfyUI 的 `user/default/workflows`。
## 需要的模型(ComfyUI 侧)
在 `local.toml` 的 `comfy_root` 下准备:
| 类型 | 文件名 | 目录 |
|------|--------|------|
| Checkpoint | `ace_step_1.5_turbo_swl_fused.safetensors` | `models/checkpoints/` |
| LoRA | `swl_voice_best_ep257.safetensors` | `models/loras/` |
- 默认 LoRA 是**作者定制声线**;别人没有同文件时 `doctor` 会 FAIL。
- 可换成自己的 LoRA,并改 `config/default.toml` 的 `[model]`(声线会变;不要用禁用名单里的 YuE2/aio)。
- 缺文件时 `doctor` 会打印人话排查步骤。
## 两个 Python 环境
| 环境 | 用途 |
|------|------|
| **本仓 `.venv`** | CLI:`doctor` / `check` / `gen` / `catalog` / `prune` |
| **`qc_python`** | QC 音频栈(可继续用 ComfyUI 的 venv) |
## 配置:TOML vs JSON
| 文件 | 作用 |
|------|------|
| `config/default.toml` | 算法 / 相对路径(相对**本仓根**) |
| `config/local.toml` | 本机 Comfy 根、服务地址、QC Python(**勿提交**) |
| `workflows/template.json` | workflow 图(JSON) |
| `config/baseline/*.json` | QC 基线数据 |
| `.secrets/` | 远程 token(**勿提交**) |
优先级:`命令行 > SONGFORGE_* > local.toml > default.toml > DEFAULTS`
## 流水线
```powershell
.\.venv\Scripts\python.exe songforge.py target --style pop --bpm 104 --dur 180
.\.venv\Scripts\python.exe songforge.py check --style pop --title 灯还亮着 --lyrics-file input\lyrics\pop_灯还亮着.txt
.\.venv\Scripts\python.exe songforge.py gen --style pop --title 灯还亮着 --lyrics-file input\lyrics\pop_灯还亮着.txt
.\.venv\Scripts\python.exe songforge.py qc --run gen-<时间戳> --baseline
.\.venv\Scripts\python.exe songforge.py prune --days 7 # 清过期 tmp
.\.venv\Scripts\python.exe songforge.py prune --days 7 --dry-run
```
`qc` 必须带 `--baseline`。样例歌词见 `input/lyrics/`。Agent 规则见 [`AGENTS.md`](AGENTS.md)。
## 硬约束(摘要)
| 项 | 值 |
|----|-----|
| 模型 | 见上表(0.5/0.5 LoRA) |
| 采样 | shift=5.5 / steps=28 / cfg=2.0 / temperature=0.68 |
| 时长 | 完整歌 150–200 秒 |
| 前奏 | 8 小节器乐 hook;CLI 自动注入 |
| 衬音 | 禁止开曲衬词;默认 `prefer_lean_tags`;tags **禁止点名** mm/ooh/嗯;QC 前奏窗 `intro_filler` 硬 FAIL |
| 插件 | [`plugins/`](plugins/) 微内核外挂;内核在 `core/` + `rules/` + `cli/` |
### 音频库
`qc` / `media` 经 `qc_python` 使用:**librosa、soundfile、torch、torchaudio、demucs、whisper**。轻量 `.venv` 不装这些。
## 音频工具(Agent 优先用 CLI)
```powershell
.\.venv\Scripts\python.exe songforge.py media info --file path.flac
.\.venv\Scripts\python.exe songforge.py media convert --file in.flac --to wav
.\.venv\Scripts\python.exe songforge.py media clip --file in.flac --start 12 --dur 8 --out out.wav
```
依赖 `config/local.toml` 的 `qc_python`(与 qc 同栈)。
## 远程(双 remote)
| 名 | URL | 用途 |
|----|-----|------|
| `gitea` | https://git.nnrc.ren/swl/songforge | 常用推送 |
| `origin` / GitHub | https://github.com/lsuen/songforge | 公开镜像 |
```powershell
git remote -v
git push gitea main
git push origin main # 或经 ghfast
```
Agent 推送前先问用户推哪个 remote;**不要**推 `archive/*`、`.secrets`、`local.toml`。
## License
MIT — 见 [LICENSE](LICENSE)。