StoryForge 是一条从纯文本到成品音频的流水线,专为中文网文/小说设计:
- 你丢进去一个
小说.txt,它按「第X章」自动切章; - LLM 把每一章转成朗读剧本:谁在说话、哪句是旁白、什么情绪;
- 每个角色从音色池里挑一个声音,选定即锁定,跨章节/跨重启都不变;
- Fish Audio 逐段合成,内容哈希缓存保证只重跑有改动的片段;
- ffmpeg 按剧本顺序拼接、插入停顿,输出可直接发布/试听的
.m4a; - 以上全部可以在 Web 工作台里可视化操作、逐句试听、行内改台词。
设计取向:过程可见、失败不静默。解析覆盖率、说话人未识别、音频错误都会显式暴露在界面上,而不是悄悄生成一段听着不对劲的音频。
| 🎭 多角色演播 | 旁白 / 台词分离,33 类音色按【男主】【男配】【反派】【老年】等档位分级,LLM 按角色身份自动选角 |
| 🔒 音色锁定 | 角色首次注册时选定的音色写库锁定,重跑、重启、换机器都不会变(主角尤其重要) |
| ♻️ 增量合成 | 片段缓存键 = 文本 + 情绪 + 音色 + 语速 + 音量 + 音调 + TTS 模型;改一句只重合成一句 |
| 📊 解析质量校验 | 解析后自动比对"剧本 vs 原文"覆盖率,低于阈值把遗漏片段喂回模型补写一次;仍不足则标⚠告警 |
| ✂️ 剧本清洗 | 拆混合段、拆超长段、合并碎旁白、剥离"他淡淡道:"引导语、去重同一句台词 |
| 🎚️ 细粒度调节 | 全局语速/音量/音调 + 每个角色单独微调,改完立即生效(按角色试听) |
| 🖥️ 完整工作台 | 项目库 → 章节工作台 → 剧本页 → 人物音色 → 设置;任务中心、全局播放器、深浅主题、键盘快捷键 |
| 🔐 可选登录 | 公网部署可开鉴权:会话 Cookie + 同 IP 连续失败锁定 |
| 🧪 可测试 | 84 项 pytest(全部跑在临时目录,不碰真实数据)+ ruff 静态检查 |
flowchart LR
A["小说 txt"] --> B["章节切分<br/>正则识别 第X章"]
B --> C["Pass 0 · 角色预识别<br/>列角色 + 从音色池选角"]
C --> D["逐章 LLM 剧本化<br/>旁白/台词 · 说话人 · 情绪"]
D --> E["清洗与校验<br/>拆段·合并·去引导语·覆盖率"]
E --> F["Fish Audio 合成<br/>内容哈希缓存命中即跳过"]
F --> G["ffmpeg 拼接<br/>停顿 + AAC m4a"]
G --> H["Web 工作台<br/>试听 · 编辑 · 增量重生成"]
断点续传:每章、每片段的处理状态都落库。中途停止/崩溃后重跑,已完成的片段直接复用,只补没做完的部分。
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt需要 Python 3.10+。
ffmpeg无需单独安装——通过imageio-ffmpeg自带。
复制 .env.example 为 .env 并填入(等号后不要加引号):
# .env
LLM_API_KEY=你的百炼key # https://dashscope.aliyuncs.com (qwen3.7-flash 免费额度)
FISH_API_KEY=你的fish key # https://fish.audio (s2.1-pro-free 免费额度).venv/bin/python app.py # 打开 http://127.0.0.1:8300前端源码在 web/(Vue 3 + Vite)。首次克隆需要构建一次,app.py 直接托管 web/dist:
cd web && npm install && npm run build开发模式(热更新,/api、/audio 自动代理到 8300):
cd web && npm run dev # http://localhost:5173| 页面 | 能做什么 |
|---|---|
| 项目库 | 拖拽上传 txt(自动识别 UTF-8/GBK/UTF-16 编码)、重命名、删除、查看每本书进度 |
| 章节工作台 | 搜索标题、按切分/音频状态筛选、批量起止章任务、每章一键开始/继续、实时批次进度、失败章节⚠提示 |
| 剧本页 | 逐片段查看/编辑台词、角色、情绪;单击试听单句、连播全章;快捷键 J/K 翻句、空格 播放、E 编辑、? 看帮助 |
| 人物音色 | 33 类音色库试听对比、给角色换音色(换完只重合成该角色的片段) |
| 设置 | 并发数、片段字数、停顿、模型、默认音色与语速/音量/音调、不注册音色的角色名 |
| 任务中心 | 右下角悬浮,多本书并行任务的实时进度,可单独停止 |
| 播放器 | 全局单例,切页不中断;支持进度拖动、上下句 |
其它细节:浅色/深色/跟随系统三态主题、解析告警横幅、确认弹窗、toast 通知、移动端自适应。
# 最小链路验证(不落库,输出到 output/audio/_cli/)
.venv/bin/python run_chapter.py 小说.txt 0
# 数据库版 CLI(与 Web 共用同一张表)
.venv/bin/python forge.py import 小说.txt # 导入并切章
.venv/bin/python forge.py run 4 1 5 # 解析+合成第 1~5 章(断点续传)
.venv/bin/python forge.py status 4 # 每章进度 + 角色音色
.venv/bin/python forge.py chars 4 # 角色表LLM 把小说转剧本时,最常见的两类错误是漏字(尤其"动作 + 说话动词 + 引语"整段被吞)和认不出说话人。StoryForge 把它们变成可量化、可见的:
- 覆盖率校验:解析后把剧本拼接结果与原文做归一化比对(忽略空白/引号,剔除"设计内会被剥离"的纯引导语),得到有效覆盖率;
- 自动补写:低于
min_coverage(默认0.97,实测正常章节 98.7%~100%)时,把真正遗漏的原文片段喂回模型重试一次,取更好的那版; - 告警可见:覆盖率不足、说话人未识别、LLM 输出非法 JSON 降级——都会写入
chapters.parse_warn,在章节列表显示 ⚠、剧本页顶部显示原因; - 提示词规则:明确要求"引号前的动作必须单独成段,不得与引语一起丢弃""台词里的称呼是被称呼者,不是说话人""speaker 用到的名字必须同时出现在 new_characters 里"。
超长章节、模型输出被截断(finish_reason=length)会明确报错,而不是重试六次后静默退化成整章旁白。
33 类音色,key 是代码/数据库引用的锁定契约(永不改名),label 会喂给 LLM 选角,note 只在界面显示(样音杂音/音量等缺陷,不污染 LLM 判断):
| 档位 | 例子 |
|---|---|
| 【旁白】 | narrator_male 沉稳大气播音腔 |
| 【男主】/【男主·少年】/【男主·文弱型】/【男主/男配】 | male_lead_serious、male_weak、male_gentle_young … |
| 【男配】/【男配·长辈】/【男配·市井】/【龙套】 | male_brother、male_middle、male_middle_accent、male_youth … |
| 【反派】/【上位者】 | male_villain、male_emperor … |
| 【老年】/【女童】/【女主】/【女配】 | male_elder_3、female_child_1、female_lead_gentle … |
- 兜底映射:男主 →
male_lead_serious,男配 →male_gentle_young,龙套 →male_young_support;女主/女配同理。 - 音色类别可带建议语速(如
male_brother样音偏慢 → 自动 1.15 倍速),角色微调可覆盖。 - 旁白音色不会被分配给角色(避免角色和旁白同声)。
调整描述时用试听反馈表:
.venv/bin/python tools/voice_pool_sheet.py
# → output/voices/voice_review.html 浏览器打开:逐条试听 + 填反馈 + 一键导出 JSON
# → output/voices/voice_review.csv 表格版| 变量 | 默认 | 说明 |
|---|---|---|
LLM_API_KEY |
— | 必填,剧本解析用 |
FISH_API_KEY |
— | 必填,语音合成用 |
LLM_BASE_URL |
https://dashscope.aliyuncs.com/compatible-mode/v1 |
OpenAI 兼容接口地址 |
LLM_MODEL |
qwen3.7-flash |
解析模型 |
FISH_TTS_MODEL |
s2.1-pro-free |
合成模型 |
TTS_CONCURRENCY |
5 |
同时合成的片段数 |
NARRATOR_VOICE_ID |
空 | 覆盖默认旁白音色 |
LOG_LEVEL |
INFO |
日志级别 |
AUTH_USER / AUTH_PASSWORD |
空 | 同时配置即启用登录鉴权 |
AUTH_SECRET |
空 | 会话签名密钥;不配则每次重启需重新登录 |
| 分组 | 设置项 |
|---|---|
| 并发与切分 | llm_concurrency、tts_concurrency、segment_max_chars |
| 拼接与停顿 | narrator_silence_ms、paragraph_silence_ms |
| 模型 | llm_model、fish_tts_model |
| 默认音色参数 | default_voice_category、default_speed、default_volume、default_pitch |
| 质量 | min_coverage(低于此覆盖率告警并补写一次) |
| 其他 | excluded_characters(不注册音色的角色名,空格分隔) |
每个角色还能在「项目设置」里单独调语速/音量/音调,留空即跟随全局。
storyforge.db SQLite(WAL):novels / chapters / characters
/ segments / settings / character_tuning / novel_meta
uploads/ 上传的小说源文件(同名不覆盖)
output/
├── audio/{novel_id}/
│ ├── chapter_NNN.m4a 章节成品
│ └── segments/ch_NNN/
│ ├── seg_XXXXXX.mp3 片段音频
│ └── seg_XXXXXX.hash 缓存键(内容哈希)
└── voices/ 音色样音 + 试听表
音频按项目隔离(output/audio/{id}/),不同书的同序号章节不会互相覆盖。设置页的「清理残留音频」可回收已删除项目的目录与不再被引用的孤儿片段。
本机执行(需 SSH 可达、rsync 可用):
SERVER=你的服务器IP ./deploy/push.sh # 同步代码 + web/dist + 音色样音,重启服务
SERVER=你的服务器IP ./deploy/push.sh --data # 首次部署:额外同步 uploads/output/数据库push.sh 会同步代码(含 output/voices 音色样音,几 MB)→ 调用 setup_server.sh 建 venv、装依赖、写 systemd 服务、配置 Caddy 反代,然后重启服务。
- 服务器要求:Debian/Ubuntu、Python 3.10+,磁盘按音频量预留(40G 起步)。
- 服务器无需 Node:前端在本机
npm run build后随代码同步。 - 日志:
ssh 服务器 "journalctl -u storyforge -f"。 - 绑域名:把服务器
/etc/caddy/Caddyfile里的:80换成域名,Caddy 自动签 HTTPS。 ⚠️ 服务必须单进程运行(任务状态、TTS 信号量、登录失败计数都在进程内存里);app.py已固定workers=1。
setup_server.sh会重写 Caddyfile;如果你手工改过(例如绑了域名),推送后需要重新贴回。
.venv/bin/pip install -r requirements-dev.txt # pytest + ruff
.venv/bin/python -m pytest tests/ -q # 84 项,全部离线,不调用任何外部 API
.venv/bin/ruff check . # 静态检查测试通过 conftest.py 把 config.BASE_DIR 指向临时目录并重置数据库连接,不会碰真实的 storyforge.db / output/ / uploads/。覆盖范围包括:剧本清洗正则、覆盖率算法、缓存键口径、音色池契约(33 个 id 锁定)、事务回滚、上传安全、参数边界、鉴权签名与锁定。
解析很慢 / LLM 限流
免费档建议把 llm_concurrency 设为 1(默认),解析本身是逐章串行的,渲染会与解析并行一章。合成并发受 tts_concurrency 控制,片段按批并发。
某个角色说话人没认出来,被旁白念了
这是刻意的降级(role_id=unknown → 用旁白音色),并在章节上留 ⚠ 告警。到剧本页点该片段编辑,把角色改成正确的人即可,重生成时只重合成这一句。
改了设置/换音色后,需要全部重新生成吗?
不需要。缓存键包含文本、情绪、音色、语速、音量、音调、模型;只有真正受影响的片段会重新合成,其余命中缓存。换角色音色只会把该角色出现的片段标记为待生成。
超长章节报错 "输出被截断"
模型单次输出装不下整章剧本。目前会明确报错(不再静默降级);临时办法是到剧本页手动分段,或等分块解析功能上线。
服务器上 API 全部 401
服务器 .env 配了 AUTH_USER/AUTH_PASSWORD 就会保护 /api 与 /audio,浏览器打开首页登录即可。会话密钥现在真正使用 AUTH_SECRET,所以升级到新版本后需要重新登录一次。
├── app.py FastAPI 入口 + SPA 托管
├── api.py JSON API(唯一后端契约)
├── auth.py 可选登录鉴权(签名会话 + IP 锁定)
├── jobs.py 后台任务:每本书一个运行槽、并发窗口、停止/收尾
├── config.py .env 加载 + 静态配置
├── core/
│ ├── ingest.py txt 编码识别 + 章节切分
│ ├── analyzer.py LLM 提示词、剧本模型、清洗与覆盖率校验
│ ├── pipeline.py 角色注册、逐章解析、TTS 渲染、拼接调度
│ ├── tts.py Fish Audio 封装(缓存键、重试、本地后处理)
│ ├── stitch.py ffmpeg 拼接(停顿 + AAC)
│ ├── db.py SQLite 持久层(事务、聚合统计、迁移)
│ ├── settings.py 运行时设置 + 角色微调
│ ├── voices.py 音色池(档位描述 + 样音映射)
│ ├── paths.py 音频路径(按项目隔离)
│ └── log.py 日志配置
├── web/ Vue 3 + Vite 前端
├── tools/voice_pool_sheet.py 音色试听/反馈表生成
├── tests/ pytest(84 项)
├── deploy/ push.sh + setup_server.sh
└── REVIEW.md 一次全量代码审查报告(含修复记录与实测数据)
MIT © 2026 EstimateFaster