# 视频解说项目

**Repository Path**: software_project_backup/video-commentary-project

## Basic Information

- **Project Name**: 视频解说项目
- **Description**: 视频解说工具
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIVPET - AI 视频自动切片工具

基于 Tauri + React + TypeScript 构建的本地视频自动切片工具。

## 版本说明

**当前版本**: v0.1.0

> ⚠️ 此版本 UI 尚未优化，界面较为简陋，但核心免费功能已全部实现。

## 功能特性

- 🎬 视频剪辑与时间轴编辑
- 🎙️ 音频提取与语音转文本（Whisper 本地识别）
- 🔊 TTS 文生音频集成
- 🎨 亮色/暗色主题切换
- 📁 项目记录管理与自动保存
- 🏷️ 视频片段标签管理
- 🎥 视频合成与导出

## 使用指南

### 完整工作流程

1. **新建记录** - 创建一个新的项目记录
2. **打开视频文件** - 选择需要处理的视频
3. **分解关键帧图** - 点击"分解关键帧图"按钮，等待分解完成
4. **复制关键帧图** - 点击"关键帧图信息" → "复制关键帧图到..."，将关键帧图文件夹放到工作目录
5. **打开工作目录** - 用 VSCode、Trae 等 AI 编程工具打开刚才的关键帧图文件夹
6. **整理剪辑提示词** - 点击"整理剪辑提示词"按钮
7. **AI 分析** - 将剪辑提示词复制给 AI 编程工具（如 VSCode 的 ChatGPT、Trae 等免费/付费 AI）
8. **自动剪辑** - 将 AI 反馈的剪辑片段数组复制到"自动剪辑"弹窗中
9. **检查调整** - 自动剪辑完成后，检查画布中的视频片段，可自行调整
10. **配置音频** - 配置 TTS 文生音频接口，或使用"必剪"等工具手动生成音频后导入
11. **合成视频** - 点击"合成视频"按钮
12. **发布** - 将合成后的视频发布到目标平台

### 推荐工具

| 用途 | 推荐工具 |
|------|---------|
| AI 编程助手 | VSCode + ChatGPT 插件、Trae |
| 手动音频生成 | 必剪（免费） |
| 视频发布 | 抖音、B站、小红书等 |

## 项目初始化

### 1. 安装依赖

```bash
pnpm install
```

### 2. Whisper 语音识别配置（可选）

如需使用音频转文本功能，需要配置 Whisper CLI 和模型文件。

#### 2.1 下载 Whisper CLI

从 [whisper.cpp releases](https://github.com/ggerganov/whisper.cpp/releases) 下载对应平台的可执行文件：

- Windows: `whisper-cli.exe`
- macOS/Linux: `whisper-cli`

将可执行文件放在以下位置之一：
- 应用可执行文件所在目录
- `resources/whisper-cli/` 目录
- 或设置环境变量 `WHISPER_PATH` 指向可执行文件路径

#### 2.2 下载 Whisper 模型

下载模型文件（`.bin` 格式）并放在 `whisper-cli` 同目录下：

| 模型名称 | 文件名 | 大小 | 说明 |
|---------|--------|------|------|
| tiny | ggml-tiny.bin | ~75MB | 最快，准确率较低 |
| base | ggml-base.bin | ~142MB | 较快，准确率一般 |
| small | ggml-small.bin | ~466MB | 平衡速度与准确率 |
| medium | ggml-medium.bin | ~1.5GB | ⚠️ 不推荐，可能存在问题 |
| large | ggml-large.bin | ~2.9GB | 准确率高，速度较慢 |
| large-v3 | ggml-large-v3.bin | ~2.9GB | 最新大模型，推荐使用 |

**推荐配置**：
- 日常使用：`small` 或 `base`
- 高准确率需求：`large-v3`
- 快速预览：`tiny`

**模型下载地址**：
- [Hugging Face - whisper.cpp](https://huggingface.co/ggerganov/whisper.cpp/tree/main)
- [GitHub Releases](https://github.com/ggerganov/whisper.cpp/releases)

### 3. TTS 试听音频配置（可选）

如需在 TTS 音色选择时播放试听音频，需要配置试听音频文件。

#### 3.1 音频文件放置

将试听音频文件（MP3 格式）放入 `resources/tts_samples/` 目录，**文件名必须与音色名称完全一致**。

示例：
```
resources/tts_samples/
├── 云舟(男声).mp3
├── 萧天(男声).mp3
├── Vivi(女声).mp3
├── 可爱女孩.mp3
└── ...
```

#### 3.2 自动下载试听音频（需要 API 配置）

如果配置了 Coze 平台的 TTS API，可以使用脚本自动下载试听音频：

```bash
cd resources/tts_samples

# 1. 复制配置文件模板
cp config.example.json config.json

# 2. 编辑 config.json，填入 API URL 和 Token
# （从 Coze Coding 平台的 "backend_视频合成工作流" 项目获取）

# 3. 运行下载脚本
node download_samples.cjs
```

## 开发运行

```bash
# 开发模式
pnpm tauri:dev

# 构建生产版本
pnpm tauri:build
```

## 主题切换

应用支持亮色和暗色主题：
- 默认跟随系统主题
- 点击顶部居中的太阳/月亮图标切换
- 用户选择会自动保存

## 目录结构

```
aivpet/
├── src/                    # React 前端源码
│   ├── App.tsx             # 主应用组件
│   ├── App.css             # 样式文件
│   ├── theme.css           # 主题 CSS 变量
│   ├── ThemeContext.tsx    # 主题状态管理
│   └── ThemeToggle.tsx     # 主题切换组件
├── src-tauri/              # Tauri 后端源码
│   └── src/
│       └── lib.rs          # Rust 核心逻辑
├── resources/              # 资源文件
│   ├── bin/                # 可执行文件
│   │   └── ffmpeg.exe      # FFmpeg
│   └── tts_samples/        # TTS 试听音频
│       ├── README.md       # 详细说明
│       └── *.mp3           # 音频文件
└── Docs/                   # 文档
```

## 技术栈

- **前端**: React 19 + TypeScript + Vite
- **后端**: Tauri 2.x + Rust
- **音视频处理**: FFmpeg
- **语音识别**: Whisper.cpp

## Recommended IDE Setup

- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)

## 相关文档

- [Whisper 集成说明](./WHISPER_INTEGRATION.md)
- [GPU 模式选择设计](./Docs/GPU_MODE_SELECTION_DESIGN.md)
- [视频合成过渡效果](./Docs/VIDEO_COMPOSE_TRANSITION.md)