video_probe/VIDEO_PROBE_RUST_QUICKSTART.md

# video_probe (Rust) - 快速参考指南

## 📋 项目概述

**目标**: 将 Python 版本的 `video_probe.py` 重写为高性能 Rust 版本

**核心功能**: 使用 ffprobe 提取视频元数据并保存为 JSON

**仓库**: `video_probe` (独立的 Gitea 仓库)

---

## 🚀 快速开始

### 1. 初始化项目

```bash
# 运行初始化脚本
chmod +x init_video_probe_rust.sh
./init_video_probe_rust.sh
```

### 2. 实现核心功能

参考 `VIDEO_PROBE_RUST_DEVELOPMENT.md` 文档，按以下顺序实现：

1. **src/error.rs** - 错误类型定义
2. **src/metadata.rs** - 数据结构定义
3. **src/probe.rs** - ffprobe 执行逻辑
4. **src/parser.rs** - JSON 解析逻辑
5. **src/output.rs** - 输出格式化
6. **src/main.rs** - 命令行入口

### 3. 测试

```bash
cd video_probe
cargo test
cargo run -- video.mp4
```

---

## 📦 依赖清单

### 核心依赖 (必需)

| 依赖 | 版本 | 用途 |
|------|------|------|
| `serde` | 1.0 | 序列化/反序列化 |
| `serde_json` | 1.0 | JSON 处理 |
| `chrono` | 0.4 | 时间处理 |
| `anyhow` | 1.0 | 错误处理 |
| `thiserror` | 1.0 | 自定义错误 |
| `clap` | 4.0 | 命令行解析 |

### 增强依赖 (可选)

| 依赖 | 版本 | 用途 |
|------|------|------|
| `indicatif` | 0.17 | 进度条 |
| `rayon` | 1.8 | 并行处理 |
| `walkdir` | 2.4 | 目录遍历 |

---

## 📁 项目结构

```
video_probe/
├── Cargo.toml              # 项目配置
├── src/
│   ├── main.rs            # 入口点
│   ├── lib.rs             # 库接口
│   ├── probe.rs           # ffprobe 执行
│   ├── parser.rs          # JSON 解析
│   ├── metadata.rs        # 数据结构
│   ├── output.rs          # 输出格式化
│   └── error.rs           # 错误类型
├── tests/
│   └── integration_test.rs # 集成测试
└── docs/
    ├── USAGE.md           # 使用文档
    └── DEVELOPMENT.md     # 开发文档
```

---

## 🔧 核心实现要点

### 1. ffprobe 调用

```rust
Command::new("ffprobe")
    .args(&[
        "-v", "quiet",
        "-print_format", "json",
        "-show_format",
        "-show_streams",
        video_path
    ])
    .output()?
```

### 2. JSON 解析

```rust
#[derive(Deserialize)]
struct FfprobeOutput {
    format: Option<Value>,
    streams: Option<Vec<Value>>,
}
```

### 3. 元数据结构

```rust
struct VideoMetadata {
    video_path: String,
    probed_at: DateTime<Utc>,
    format: FormatInfo,
    video_stream: Option<VideoStream>,
    audio_streams: Vec<AudioStream>,
    subtitle_streams: Vec<SubtitleStream>,
    other_streams: Vec<OtherStream>,
}
```

### 4. 命令行参数

```rust
#[derive(Parser)]
struct Args {
    video_path: String,
    #[arg(short, long)]
    output: Option<String>,
    #[arg(short, long)]
    verbose: bool,
}
```

---

## 📊 开发时间表

| 阶段 | 任务 | 时间 |
|------|------|------|
| 1 | 项目初始化 | 0.5 天 |
| 2 | 数据结构 | 1 天 |
| 3 | ffprobe 执行 | 1 天 |
| 4 | JSON 解析 | 1 天 |
| 5 | 输出格式化 | 0.5 天 |
| 6 | 命令行界面 | 0.5 天 |
| 7 | 测试 | 1 天 |
| 8 | 文档 | 0.5 天 |
| **总计** | | **6 天** |

---

## ✅ 功能对照表

| 功能 | Python 版本 | Rust 版本 | 状态 |
|------|-------------|-----------|------|
| ffprobe 调用 | ✅ | 待实现 | 🔨 |
| JSON 解析 | ✅ | 待实现 | 🔨 |
| 格式信息提取 | ✅ | 待实现 | 🔨 |
| 视频流提取 | ✅ | 待实现 | 🔨 |
| 音频流提取 | ✅ | 待实现 | 🔨 |
| 字幕流提取 | ✅ | 待实现 | 🔨 |
| JSON 输出 | ✅ | 待实现 | 🔨 |
| 命令行参数 | ✅ | 待实现 | 🔨 |
| 友好输出 | ✅ | 待实现 | 🔨 |

---

## 🎯 性能对比预期

| 指标 | Python | Rust | 提升 |
|------|--------|------|------|
| 启动时间 | ~50ms | ~1ms | 50x |
| 内存使用 | ~30MB | ~5MB | 6x |
| CPU 效率 | 中 | 高 | 2-3x |
| 二进制大小 | N/A | ~2MB | - |
| 部署复杂度 | 高 | 低 | ✅ |

---

## 🔗 有用链接

- [Rust 官方文档](https://doc.rust-lang.org/)
- [serde 文档](https://serde.rs/)
- [clap 文档](https://docs.rs/clap/)
- [FFprobe 文档](https://ffmpeg.org/ffprobe.html)
- [anyhow 文档](https://docs.rs/anyhow/)

---

## 📝 开发清单

### 必须完成
- [ ] 实现 ffprobe 调用
- [ ] 实现 JSON 解析
- [ ] 实现元数据提取
- [ ] 实现 JSON 输出
- [ ] 实现命令行参数
- [ ] 编写单元测试
- [ ] 编写集成测试
- [ ] 编写 README
- [ ] 添加错误处理
- [ ] 添加日志输出

### 可选增强
- [ ] 批量处理
- [ ] 并行处理
- [ ] 进度条
- [ ] 递归扫描
- [ ] 多种输出格式
- [ ] 配置文件支持

---

## 🚨 注意事项

1. **ffprobe 依赖**: 系统必须安装 FFmpeg
2. **跨平台**: 测试 Linux/macOS/Windows
3. **错误处理**: 文件不存在、ffprobe 失败等
4. **性能优化**: 避免不必要的内存分配
5. **测试覆盖**: 至少 80% 代码覆盖率

---

## 📞 支持

如有问题，请：
1. 查看 `VIDEO_PROBE_RUST_DEVELOPMENT.md`
2. 查看 Rust 官方文档
3. 提交 Issue 到 Gitea 仓库