# geekcast

**Repository Path**: soulnew/geekcast

## Basic Information

- **Project Name**: geekcast
- **Description**: AI 口播视频自动剪辑
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: http://ftmao.com/blog
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GeekCast Engine — 极客口播自动化剪辑工具

多模块视频生成平台，支持 AI 驱动的视频自动剪辑：上传素材 → 语音识别 → 词级精剪 → LLM 生成文案/配乐/字幕 → Remotion 渲染成片。

## 项目架构

前后端分离 + 轮询 Worker 架构，包含三个主要模块（Java 层已于 2026-10 下线，见 `geekCast-java/DEPRECATED.md`）：

| 模块 | 技术栈 | 职责 |
|------|--------|------|
| **geekCast-web** | Vue 3 + Vite + TypeScript + Pinia + Element Plus | 前端用户界面（项目管理、精剪工作台） |
| **geekCast-python** | Python 3.11 + **FastAPI**（`app/server/`）+ FunASR | 后端 API 服务 + 视频处理工作节点（ASR、FFmpeg、LLM、Remotion 渲染） |
| **geekCast-renderer** | Remotion 4 + React 18 | 视频渲染引擎（位于 `geekCast-python/geekCast-renderer`，由 Worker 子进程调用） |

```
geekCast-web (5173)  ──HTTP──▶  FastAPI (8080, geekCast-python/app/server)
                                        ▲
                              轮询/回调（/internal-api，X-Internal-Token 鉴权）
                                        │
                               Python Worker（含 Remotion 渲染子进程）
```

迁移契约与回归：`ai_work/design/java-to-fastapi-contracts.md`、`geekCast-python/scripts/contract_diff.py`。

## 目录结构

```
video7/
├── geekCast-web/          # 前端
├── geekCast-java/         # 后端 API（端口 8080）
├── geekCast-python/       # Python Worker（app/ 为主代码）
│   └── geekCast-renderer/ # Remotion 渲染器
├── sql/init.sql           # MySQL 8.0 建库建表脚本（库名 geekcast）
├── ai_work/               # 需求、设计、契约、复盘文档
├── chrome-kernel/         # 无头浏览器内核（渲染依赖）
└── start.bat              # Windows 一键启动脚本
```

## 环境要求

- Node.js ≥ 18
- Python 3.11（推荐使用 conda 环境 `geekCast`）
- MySQL 8.0（库名 `geekcast`，执行 `sql/init.sql` 初始化）
- FFmpeg

## 快速开始

### 1. 初始化数据库

```bash
mysql -u root -p < sql/init.sql
```

### 2. 启动后端（FastAPI，geekCast-python）

```bash
cd geekCast-python
pip install -r requirements.txt
python -m app.server.main   # uvicorn，端口 8080
```

可通过环境变量覆盖配置：`MYSQL_HOST` / `MYSQL_PORT` / `MYSQL_USER` / `MYSQL_PASS` 等（与历史 Java 配置同名）。

### 3. 启动 Python Worker

```bash
cd geekCast-python
pip install -r requirements.txt
python -m app.main
```

### 3.1 语音识别（ASR）模型下载与部署

默认使用 **FunASR** 引擎（中文准确率显著优于 Whisper base）：`paraformer-zh`（识别）+ `fsmn-vad`（静音切分）+ `ct-punc`（标点恢复），输出**字级时间戳**，供字幕渲染和精剪使用。

**下载模型**（约 2.2GB，从 ModelScope 下载，缓存在 `geekCast-python/models/funasr`）：

```bash
cd geekCast-python
python scripts/download_funasr_models.py
```

也可以不手动下载——首次转录时 FunASR 会自动下载到同一缓存目录，但首次运行会较慢，建议提前下载。

**运行环境**：

- **CPU**：开箱即用（conda 环境 `geekCast` 默认 CPU 版 torch），实测 RTF ≈ 0.2~0.35，1 分钟音频约 12~21 秒转完
- **GPU**：安装 CUDA 版 torch 后自动启用（代码内 `cuda:0 if torch.cuda.is_available() else "cpu"`），GTX 1060 6G 即可流畅运行

**相关环境变量**：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `STT_ENGINE` | `funasr` | 设为 `whisper` 可回退到 faster-whisper 引擎 |
| `FUNASR_MODEL_PATH` | `./models/funasr` | FunASR 模型缓存目录 |
| `WHISPER_MODEL_PATH` | `./models/large-v3` | （仅回退时）Whisper 模型路径 |

**回退到 Whisper**（可选）：设置 `STT_ENGINE=whisper`，并下载 whisper 模型：

```bash
python scripts/download_whisper_model.py --model base
```

### 4. 渲染器（geekCast-renderer）

渲染由 Python Worker 的 RenderExecutor 通过 `npx remotion render` 子进程完成，**无需单独启动渲染进程**。仅需构建一次（及调试预览）：

```bash
cd geekCast-python/geekCast-renderer
npm install
npm run build
npm run studio   # 可选：本地可视化预览
```

### 5. 启动前端

```bash
cd geekCast-web
npm install
npm run dev
```

### 一键启动（Windows）

```bash
start.bat
```

## 功能特性

- **多分辨率输出**：`1920x1080` / `2560x1440` / `3840x2160`（16:9 横屏），`1080x1920`（9:16 竖屏，适配抖音/快手/视频号）
- **词级精剪**：基于 ASR 字级时间戳（FunASR paraformer-zh）的删除/保留编辑，不拆分 segment，保持时间连续性
- **AI 驱动**：LLM 生成口播文案、B-roll 节奏优化、音效支持
- **Remotion 渲染**：React 组件化的视频合成管线

## 文档

- 需求文档：`ai_work/requirement/`
- 设计文档：`ai_work/design/`（含 v5 精剪工作台、竖屏支持、契约补充等）
- 功能设计模板：`ai_work/templates/feature_design_template.md`
- 问题复盘：`ai_work/memory/issue.md`

## 开发规范

- Java 后端：`ai_work/spec/techspec_java_backend_cn.md`
- 前端：`ai_work/spec/techspec_vue_frontend.md`
- Python：`ai_work/spec/python_code_rule.md`

新功能开发前请先阅读契约模板并确认跨层契约（null 处理、数据唯一性、force 重复调用语义等），详见根目录 `CLAUDE.md`。