magic-book

magic-book 的第一阶段目标，是先把“绘本讲解老师”能力独立做出来：

1. 输入一个人的多段讲话音频。
2. 生成并保存一个“讲解老师”。
3. 给定文本，生成讲解音频。

当前仓库提供的是一个适合持续 AI Coding 的后端骨架：

• FastAPI API 层，方便以后接前端和管理后台。
• “讲解老师”领域模型独立，避免业务逻辑散在接口里。
• 语音供应商可插拔，后续可切换 OpenAI、ElevenLabs、XTTS 或自研服务。
• CLAUDE.md 约束未来 AI Coding 的协作方式。
• SPEC.md 记录路线图、状态和每个小需求的完成进度。

目录结构

src/magic_book/
  api/              # FastAPI 路由与接口模型
  domain/           # 领域模型
  providers/        # 语音供应商抽象与实现
  repositories/     # 元数据持久化
  services/         # 应用服务
  storage/          # 文件存储
tests/              # 基础单测

运行准备

当前环境还没有安装依赖，后续建议先补齐：

1. fastapi / uvicorn
2. ffmpeg
3. 一个真实语音供应商
   • 云端：OpenAI 自定义语音或 ElevenLabs
   • 本地：XTTS v2

当前 API 草案

• GET /health
• GET /api/v1/teachers
• GET /api/v1/teachers/{teacher_id}
• POST /api/v1/teachers
• POST /api/v1/teachers/{teacher_id}/synthesize

本地校验

当前代码可以先用标准库完成基础自检：

python3 -m unittest discover -s tests
python3 -m compileall src tests

下一步建议

1. 实现真实供应商适配器，优先接入一个能保存 voice asset 的方案。
2. 增加音频预处理流水线，包括响度、采样率、静音裁剪。
3. 引入任务队列，把“创建老师”和“生成语音”改成异步作业。
4. 再接绘本、章节、讲解脚本和后台管理界面。