# smart-podcast

**Repository Path**: fighting010/smart-podcast

## Basic Information

- **Project Name**: smart-podcast
- **Description**: smart-podcast
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎙️ Smart Podcast Platform

一个端到端的智能播客制作平台（参考京东技术《全栈 AI Agent 从 0 到 1》的设计理念）：
**发一个话题或粘贴一段素材，AI 自动完成脚本创作 → 音色设计 → 语音合成 → 拼接 → BGM 选择 → 专业混音 → 成品入库，全程无需人工干预。**

## 快速开始

```bash
cd /Users/ajian/repo/smart-podcast
./start.sh          # 首次运行自动创建 venv 并安装依赖
# 访问 http://127.0.0.1:8300
```

## 功能总览

| 页面 | 说明 |
|---|---|
| **创作 Agent** | 流式对话入口（SSE + AG-UI 风格事件）：打字机文本、可折叠工具调用卡片、内嵌音频播放器、快捷话题、拖拽 .txt 素材、麦克风语音输入（Web Speech API） |
| **播客库** | 成品列表：封面卡片、内嵌播放、完整脚本查看、删除 |
| **资源库** | 系统音色试听/保存、BGM 管理与上传（文件名即场景描述，参与语义匹配） |
| **设置** | 可视化配置：对话模型（本地模板 / OpenAI 兼容 API）、语音参数（语速/间隔/淡 化/BGM 增益） |

## 架构设计（对应原文的关键设计）

```
用户发消息 ──POST /api/chat──▶ FastAPI (SSE) ──▶ Agent 工作线程
                                                  │  事件队列（AG-UI 风格事件）
前端 fetch 流式解析 ◀──data: {...}\n\n────────────┘
```

### 1. 单 Agent 多工具（9 个单一职责工具）

| 工具 | 职责 |
|---|---|
| `script_generate` | 脚本创作（LLM 或本地模板） |
| `voice_design` | 人设 → 音色匹配（性别/气质/语速） |
| `tts_synthesize` | 逐段合成 WAV |
| `concatenate_audio` | 交叉淡入淡出拼接（默认 200ms crossfade + 500ms 间隔） |
| `select_background_music` | 基于文件名的场景语义匹配 |
| `mix_audio_with_bgm` | 专业混音：BGM 前 3s 原音量 → 20 步渐变 → 背景段 -26dB → 结尾淡出 |
| `save_podcast` | 临时 → 永久入库（WAV + afconvert 压缩 M4A） |
| `save_voice` | 音色临时样本 → 永久音色库 |
| `list_voices` | 音色库查询 |

### 2. 「临时-永久」双层存储

```
storage/
├── temp/       # 工具中间产物（默认 10 分钟自动清理，后台线程）
├── audios/     # 用户确认保存的音色样本
├── bgm/        # 背景音乐（含程序化合成的 4 首风格曲目）
├── podcasts/   # 播客成品（wav + m4a）
├── voice_index.json      # 音色索引（原子写 + 文件锁）
└── podcast_index.json    # 播客索引
```

### 3. 零云依赖的离线引擎

- **TTS**：macOS 内置 `say`（11+ 中文音色，双主持播客开箱即用）
  ⚠️ 必须使用带语言后缀的完整音色名（如 `Eddy (中文（中国大陆）)`），短名会静默降级
- **BGM**：首次启动程序化合成 4 种风格（明快钢琴/温暖弦乐/科技电子/舒缓大提琴）
- **脚本**：本地模板兜底，保证无任何 API Key 也能跑通全链路
- **DSP**：纯标准库 `wave` + `array` 实现拼接/混音/归一化；`afconvert` 压缩 M4A

### 4. LLM 可插拔（工厂模式）

设置页配置 OpenAI 兼容接口（DashScope / DeepSeek / OpenAI 均可）后：
- 脚本创作由 LLM 生成（更自然、能消化长素材）
- 普通对话走 LLM 流式聊天
- 任何失败自动降级本地模板，链路永不中断

配置优先级：`config.json`（可视化配置页）> 环境变量（`SP_LLM_MODE` 等）> 默认值

## 技术栈

FastAPI + Uvicorn（SSE 流式）· 原生 JS SPA（深空蓝紫主题）· macOS say/afconvert · Python 标准库 DSP

## 与原文实现的差异

| 原文 | 本实现 |
|---|---|
| Vue 3 + shadcn-vue 前端 | 原生 JS SPA（FastAPI 单服务托管，一条命令启动） |
| LangChain/LangGraph Agent | 自研轻量 Agent 编排（线程 + 事件队列，逻辑等价、零框架锁定） |
| DashScope Qwen-TTS/ASR | macOS say（离线）；ASR 暂未接入，素材通过文本粘贴/拖拽输入 |
| pydub + FFmpeg | 标准库 DSP + afconvert（可选 ffmpeg） |