Skip to content

About

把小说 txt 变成一本多人演播的有声书:LLM 剧本化切分(旁白/台词/说话人/情绪)→ 多角色音色锁定 → Fish Audio 合成(片段级增量缓存)→ ffmpeg 拼接成品 m4a;Vue 3 + FastAPI 可视化工作台,可选登录鉴权。

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

StoryForge · 有声书工坊

把一部小说 txt,变成一本多人演播的有声书

LLM 剧本化切分 · 多角色音色锁定 · 增量合成缓存 · 可视化工作台

Python FastAPI Vue Tests Ruff License


这是什么

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/>试听 · 编辑 · 增量重生成"]
Loading

断点续传:每章、每片段的处理状态都落库。中途停止/崩溃后重跑,已完成的片段直接复用,只补没做完的部分。


快速开始

1. 安装

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

需要 Python 3.10+。ffmpeg 无需单独安装——通过 imageio-ffmpeg 自带。

2. 配置两个 Key

复制 .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 免费额度)

3. 启动

.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

Web 工作台

页面 能做什么
项目库 拖拽上传 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 把它们变成可量化、可见的:

  1. 覆盖率校验:解析后把剧本拼接结果与原文做归一化比对(忽略空白/引号,剔除"设计内会被剥离"的纯引导语),得到有效覆盖率;
  2. 自动补写:低于 min_coverage(默认 0.97,实测正常章节 98.7%~100%)时,把真正遗漏的原文片段喂回模型重试一次,取更好的那版;
  3. 告警可见:覆盖率不足、说话人未识别、LLM 输出非法 JSON 降级——都会写入 chapters.parse_warn,在章节列表显示 ⚠、剧本页顶部显示原因;
  4. 提示词规则:明确要求"引号前的动作必须单独成段,不得与引语一起丢弃""台词里的称呼是被称呼者,不是说话人""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   表格版

配置

环境变量(.env)

变量 默认 说明
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

About

把小说 txt 变成一本多人演播的有声书:LLM 剧本化切分(旁白/台词/说话人/情绪)→ 多角色音色锁定 → Fish Audio 合成(片段级增量缓存)→ ffmpeg 拼接成品 m4a;Vue 3 + FastAPI 可视化工作台,可选登录鉴权。

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages