# AI Video LifePlan - 功能实现说明

本项目已完整实现以下6大核心功能模块:

## ✅ 已实现功能

### 1️⃣ Input Analysis - 输入分析 (PDF / 视频 / 音频)

**实现文件**: [`backend/extractor.py`](backend/extractor.py)

#### PDF 解析 (Gemini Pro)
- 使用 Google Gemini 2.0 Flash Exp 模型
- 自动提取结构化数据:
  - 客户基本信息 (姓名、年龄)
  - 财务数据 (资产、收入、支出)
  - 家庭结构
  - 人生事件规划
  - 财务目标

**使用示例**:
```python
from backend.extractor import PDFExtractor

extractor = PDFExtractor()
data = extractor.extract("path/to/lifeplan.pdf")
```

#### 视频/音频转录 (OpenAI Whisper)
- 使用 FFmpeg 提取音频
- OpenAI Whisper API 进行高精度日语转录
- 支持分段时间戳
- 自动提取关键词

**使用示例**:
```python
from backend.extractor import VideoExtractor

extractor = VideoExtractor()
result = extractor.extract("path/to/interview.mp4")
# 返回: transcription, segments, keywords
```

---

### 2️⃣ Scripting - 脚本生成

**实现文件**: [`backend/scripter.py`](backend/scripter.py)

- 使用 Gemini Pro 生成自然的日语口语脚本
- 基于 PDF 数据和视频转录
- 支持多种风格 (friendly, professional, casual)
- 自动分段并计算时长

**使用示例**:
```python
from backend.scripter import generate_script

script = generate_script(pdf_data, video_data, style="friendly")
```

---

### 3️⃣ Audio - TTS 音频生成

**实现文件**: [`backend/audio_generator.py`](backend/audio_generator.py)

- OpenAI TTS API (tts-1 模型)
- 多种语音选择 (alloy, echo, fable, onyx, nova, shimmer)
- 自动为每个脚本段落生成音频
- 输出到 `assets/1_processed/audio/`

**使用示例**:
```python
from backend.audio_generator import generate_audio_for_script

updated_script = generate_audio_for_script(script_data, voice="alloy")
```

---

### 4️⃣ Dynamic Visuals - 动态图表 (Remotion)

**实现文件**: 
- [`src/Composition.tsx`](src/Composition.tsx)
- [`src/DualChartView.tsx`](src/DualChartView.tsx)
- [`src/LifePlanChart.tsx`](src/LifePlanChart.tsx)

- 基于 Remotion 的程序化视频渲染
- 实时动态图表:
  - 资产消耗曲线
  - 现金流分析
  - 双图表联动显示
- 虚拟人角色同步说话
- 字幕自动同步

---

### 5️⃣ Stock Visuals - B-Roll 素材获取 (Pexels API)

**实现文件**: [`backend/media_fetcher.py`](backend/media_fetcher.py)

- 自动翻译日语关键词为英语 (使用 Gemini)
- Pexels API 搜索并下载 HD 视频
- 智能缓存机制 (避免重复下载)
- 支持本地文件路径引用

**功能特性**:
- 关键词翻译缓存
- 自动选择最佳质量 (≤1920p HD)
- 存储到 `assets/1_processed/broll/`

**使用示例**:
```python
from backend.media_fetcher import MediaFetcher

fetcher = MediaFetcher()
results = fetcher.fetch_broll(["家族", "老後", "貯蓄"], max_per_keyword=2)
```

---

### 6️⃣ Source Slicing - 视频切片 (可选功能)

**实现文件**: [`backend/video_slicer.py`](backend/video_slicer.py)

- 基于转录内容智能识别关键片段
- 使用 Gemini 分析重要性
- FFmpeg 快速切片 (stream copy, 无需重编码)
- 输出到 `assets/1_processed/video_clips/`

**使用示例**:
```python
from backend.video_slicer import extract_video_clips

clips = extract_video_clips(
    video_path="interview.mp4",
    transcription_data=video_data,
    max_clips=3
)
```

---

## 🚀 完整工作流

### 命令行使用

```bash
# 基础使用 - 仅 PDF
python main.py --pdf assets/0_input/report.pdf

# 带视频转录
python main.py --pdf report.pdf --video interview.mp4

# 启用视频切片功能
python main.py --pdf report.pdf --video interview.mp4 --extract-clips

# 仅生成数据,不渲染视频
python main.py --pdf report.pdf --dry-run
```

### 工作流步骤

```
1. 📄 PDF 解析 (Gemini Pro)
   ↓
2. 🎥 视频转录 (Whisper) [可选]
   ↓
3. ✍️  脚本生成 (Gemini Pro)
   ↓
4. 🎙️  音频生成 (OpenAI TTS)
   ↓
5. 🎬 B-Roll 获取 (Pexels API)
   ↓
6. ✂️  视频切片 [可选]
   ↓
7. 📊 数据整合 (render_props.json)
   ↓
8. 🎞️  视频渲染 (Remotion)
```

---

## 🔑 API 配置

需要在 `.env` 文件中配置以下 API Keys:

```env
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
PEXELS_API_KEY=your_pexels_api_key
```

---

## 📦 依赖安装

### Python 依赖
```bash
pip install -r requirements.txt
```

主要包含:
- `google-genai` - Gemini AI SDK (新版)
- `openai` - OpenAI API (Whisper + TTS)
- `requests` - HTTP 请求 (Pexels API)
- `ffmpeg-python` - 视频处理
- `python-dotenv` - 环境变量管理

### 系统依赖
- **FFmpeg**: 必须安装并在 PATH 中
  - Windows: `choco install ffmpeg` 或从官网下载
  - Mac: `brew install ffmpeg`
  - Linux: `apt install ffmpeg`

### Node.js 依赖
```bash
npm install
```

---

## 📁 目录结构

```
assets/
├── 0_input/              # 输入文件 (PDF, 视频)
├── 1_processed/          # 中间处理文件
│   ├── audio/           # 生成的音频
│   ├── broll/           # 下载的 B-Roll 视频
│   ├── video_clips/     # 提取的视频片段
│   ├── render_props.json
│   └── translation_cache.json
└── 2_output/            # 最终视频输出
```

---

## 🔍 调试与验证

### 检查 PDF 提取结果
```python
from backend.extractor import PDFExtractor
extractor = PDFExtractor()
data = extractor.extract("path/to/pdf")
print(json.dumps(data, ensure_ascii=False, indent=2))
```

### 检查视频转录
```python
from backend.extractor import VideoExtractor
extractor = VideoExtractor()
result = extractor.extract("path/to/video.mp4")
print(f"Duration: {result['duration']}s")
print(f"Segments: {len(result['segments'])}")
```

### 检查 B-Roll 下载
```python
from backend.media_fetcher import MediaFetcher
fetcher = MediaFetcher()
results = fetcher.fetch_broll(["家族", "老後"])
for keyword, videos in results.items():
    print(f"{keyword}: {len(videos)} videos")
```

---

## ⚠️ 注意事项

1. **API 配额**: 
   - Gemini Pro 和 OpenAI API 有使用限制
   - Pexels API 免费版每小时 200 请求

2. **文件大小**:
   - 视频文件建议不超过 500MB
   - PDF 建议不超过 20 页

3. **处理时间**:
   - PDF 解析: ~10-30秒
   - 视频转录: ~视频时长的 1/3
   - B-Roll 下载: ~2-5分钟 (取决于网络)
   - 视频渲染: ~1-3分钟

4. **语言支持**:
   - 主要支持日语
   - B-Roll 关键词会自动翻译为英语

---

## 🐛 常见问题

### Q: FFmpeg not found
A: 确保 FFmpeg 已安装并在系统 PATH 中
```bash
ffmpeg -version  # 检查是否安装
```

### Q: Gemini API 错误
A: 检查 API key 是否正确,是否有配额

### Q: Whisper 转录失败
A: 确认视频文件有音频轨道,格式支持

### Q: B-Roll 下载慢
A: Pexels API 有速率限制,会自动等待

---

## 📄 相关文档

- [项目总览 README](PROJECT_README.md)
- [Remotion 配置](remotion.config.ts)
- [字幕提取调查](backend/SUBTITLE_INVESTIGATION_README.md)

---

## 📝 更新日志

**v1.0.0** (2026-01-16)
- ✅ 完整实现 6 大核心功能
- ✅ PDF 语义分析 (Gemini)
- ✅ 视频/音频转录 (Whisper)
- ✅ 脚本生成 (Gemini)
- ✅ TTS 音频生成 (OpenAI)
- ✅ B-Roll 素材获取 (Pexels)
- ✅ 视频切片 (FFmpeg + Gemini)
- ✅ 动态图表渲染 (Remotion)

---

**构建者**: Qoder AI Assistant  
**最后更新**: 2026-01-16