# webActiveGraphPlayer

**Repository Path**: CeasarSmj/web-active-graph-player

## Basic Information

- **Project Name**: webActiveGraphPlayer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网页端播客图谱播放器 (webActiveGraphPlayer)

将 Markdown 文案通过 LLM 转化为「动态图谱播放事件」，在网页画布上随 TTS 朗读逐句演化，并支持导出为 MP4 视频。

- 后端：Python 3.10+ / Flask / FFmpeg / edge-tts
- 前端：原生 HTML5 + CSS3 + JavaScript（Canvas 渲染、力导向布局）
- LLM：通过后端代理调用各厂商 API（DeepSeek、OpenAI、GLM、Moonshot、自定义）

## 目录结构

```
project_root/
├── backend/
│   ├── app.py                 # Flask 主应用（所有 API + 前端伺服）
│   ├── config.py              # 配置
│   ├── requirements.txt
│   ├── llm/
│   │   ├── mission_prompt.md  # LLM 系统提示词
│   │   ├── element_schema.json# 事件 JSON Schema（draft 2020-12）
│   │   ├── providers.json     # 厂商模板
│   │   ├── keys.json          # API Keys / 偏好（不纳入版本控制）
│   │   └── llm_client.py      # 调用 + 校验 + 重试 + 时间戳估算
│   ├── tasks/                 # 导出任务管理
│   ├── utils/                 # file_manager / tts / ffmpeg
│   └── tests/                 # 单元测试
├── frontend/
│   ├── index.html
│   ├── css/ js/ i18n/ assets/
├── data/                      # 运行时生成（由后端管理）
│   └── draft_sample/          # 内置示例项目
├── web_graph_player_env.yaml  # conda 环境
├── README.md
└── LICENSE
```

## 环境准备

需要系统已安装 **FFmpeg**（`ffmpeg`、`ffprobe` 在 PATH 中，或放到 `C:\ffmpeg\bin`）。

### 安装 FFmpeg

推荐使用 [BtbN/FFmpeg-Builds](https://github.com/BtbN/FFmpeg-Builds/releases) 提供的预编译版本（含 ffmpeg 与 ffprobe）。

**Windows**：
1. 打开 [Releases 页面](https://github.com/BtbN/FFmpeg-Builds/releases)，下载最新版 `ffmpeg-master-latest-win64-gpl.zip`（gpl 版即可）。
2. 解压到任意目录，例如 `C:\ffmpeg\`，使其结构为 `C:\ffmpeg\bin\ffmpeg.exe` 与 `C:\ffmpeg\bin\ffprobe.exe`。
3. 将 `C:\ffmpeg\bin` 加入系统 `PATH`（推荐）；或保持在该目录，本项目也会自动从 `C:\ffmpeg\bin` 查找。
4. 验证：新开终端执行 `ffmpeg -version` 与 `ffprobe -version`，能打印版本号即成功。

**macOS**（任选其一）：
```bash
brew install ffmpeg          # Homebrew，自带 ffprobe
```

**Linux**（任选其一）：
```bash
# Debian / Ubuntu
sudo apt update && sudo apt install -y ffmpeg
# 或从 BtbN 下载 linux64 构建解压后加入 PATH
```

> 提示：导出 MP4 需要 `ffmpeg` 合成音视频；TTS 时长测量优先用 `ffprobe`，若仅有 `ffmpeg` 也可自动回退（建议两者都装）。

```bash
# 创建 conda 环境
conda env create -f web_graph_player_env.yaml
conda activate web_graph_player

# （可选）Playwright 浏览器，用于备选导出方案 B
# playwright install chromium
```

> 若不使用 conda，也可直接 `pip install -r backend/requirements.txt`。

## 运行

```bash
conda activate web_graph_player
cd backend
python app.py
```

默认监听 `http://0.0.0.0:5000`，浏览器打开即可。可用环境变量覆盖：
`WGP_HOST`、`WGP_PORT`、`WGP_DEBUG`。

前端构建产物直接由 Flask 伺服（`/` → `frontend/index.html`），也可用 Nginx 单独托管 `frontend/` 并反向代理 `/api` 到 Flask。

### 无依赖 EXE 版本

Release 页面提供打包好的 `.zip`，解压即可运行，**无需 Python 环境**。

```
webGraphPlayer/
├── webGraphPlayer.exe  ← 双击启动
├── start_ND.bat        ← 或点此启动
├── data/               ← 运行时数据（包含示例项目）
├── frontend/           ← 内嵌在 exe 中（静态资源已打包）
└── llm/                ← LLM 提示词/Schema（已打包）
```

构建 EXE：
```bash
cd backend_release
pack.bat             # 一键打包（需 conda 环境 web_graph_player）
```

> 无论源代码运行还是 EXE 运行，均需系统安装 **FFmpeg**（用于音频合成与格式转换）。

## 使用流程

1. **配置 LLM**：点击右上角 ⚙ 设置，选择供应商 / 模型，填写 API Key（Key 仅存服务端，前端脱敏显示 `***`）；提供「验证」功能一键测试连通性。
2. **新建 / 粘贴文案**：在文本对照区粘贴 Markdown，点「保存」。
3. **解析**：点「解析」，后端调用 LLM 生成事件 JSON（含 JSON/Schema 校验 + 错误反馈重试），自动载入主显示区。解析后自动与原文案进行**句子对齐**，确保文本对照区内容完整准确。
4. **播放**：底部控件播放/暂停、倍速、进度条；文本对照区逐句高亮并滚动，点击句子可跳转；双击画布元素可跳转到其创建时刻。
5. **导出 MP4**：点「导出」，后端依次生成 TTS 音频 → 修正时间戳 → 前端录制画面（MediaRecorder）上传 → FFmpeg 合成 MP4 → 下载。支持可选字幕烧录。

### 核心特性
- **智能解析**：自适应细粒度（自动/词汇/事件）+ 自定义 Prompt，灵活控制图谱密度
- **图谱渲染**：无穷大画布、力导向布局、节点/边/列表容器、视口裁剪、夜间模式
- **有向边**：实心三角箭头，端点裁剪到节点边界，方向明确
- **列表容器**：纵向堆叠组合节点，紧密排列，整体受力布局
- **空操作**：过渡/抒情/重复句用 `noop`，仅朗读不改图
- **文本校对**：解析后自动匹配原文修正句子，不漏句子
- **人工配音**：可选对每句录音（🎤），导出时优先使用已录音频，未录制句才用 TTS
- **字幕**：设置中可开启字幕，导出时自动生成 SRT 并烧录到视频
- **布局调参**：阻尼、归零阈值、聚焦边距等可在设置中调节

## JSON 播放文件格式

每条记录：`[时间戳(秒), 句子文本, 事件类型, 事件数据, 焦点ID列表]`

- 事件类型：`create_node` / `edit_node` / `delete_node` / `create_edge` / `edit_edge` / `delete_edge` / `create_list`
- 初始时间戳由匀速阅读估算；导出时由 TTS 实测时长修正。
- 元素字段严格受 [element_schema.json](backend/llm/element_schema.json) 约束（JSON Schema draft 2020-12，按事件类型条件校验）。

### 节点样式
- 文字节点：颜色、粗体/斜体/下划线/删除线；边框颜色、宽度（细/中/粗）、线型（实线/虚线/双线/无）、形状（方形/椭圆/平行四边形/菱形）。
- 图像节点：`src` 为相对 `images/` 的路径，长边等比缩放；加载失败显示红色「图像加载失败」占位。

## API 接口

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/drafts` | GET | 缓存项目列表 |
| `/api/draft/new` | POST | 新建草稿 |
| `/api/draft/<id>` | GET | 获取 Markdown |
| `/api/draft/<id>/save` | POST | 保存 Markdown |
| `/api/draft/<id>/parse` | POST | LLM 解析，返回事件 |
| `/api/draft/<id>/json` | GET/POST | 读取/保存播放 JSON |
| `/api/draft/<id>/export` | POST | 发起 MP4 导出，返回 task_id |
| `/api/task/<task_id>` | GET | 查询导出进度 |
| `/api/task/<task_id>/upload_webm` | POST | 前端上传录制画面 |
| `/api/download/<draft_id>` | GET | 下载 MP4 |
| `/api/settings` | GET/POST | 读取/更新配置 |
| `/api/cache/clear` | POST | 清空所有 data/ |
| `/api/upload_image/<draft_id>` | POST | 上传图片 |
| `/api/voices` | GET | 可用 TTS 音色 |
| `/api/health` | GET | 健康检查（ffmpeg 可用性等） |

## 测试

```bash
cd backend
python -m unittest discover tests
```

覆盖：Schema 校验、JSON 提取、时间戳估算、TTS 分段、文件管理、图片路径净化。

## 导出方案

- **方案 A（默认）**：前端用 `canvas.captureStream` + `MediaRecorder` 录制无声 WebM 上传，后端 FFmpeg 合成音频转 MP4。
- **方案 B（备选）**：后端 Playwright 无头浏览器录制（`tasks/export_worker.py` 可扩展实现）。

## i18n

界面与提示词支持中文 / 英文，通过设置切换（`frontend/i18n/zh.json`、`en.json`）。

## 安全说明

- API Key 仅存于服务端 `backend/llm/keys.json`（建议加入 `.gitignore`），前端 API 只返回脱敏的 `***`。
- 上传文件名经净化，防止路径穿越。