# voice-over-editing-tool

**Repository Path**: jamer/voice-over-editing-tool

## Basic Information

- **Project Name**: voice-over-editing-tool
- **Description**: AI 口播视频剪辑工具，自动识别语音、标记无效内容（静音、语气词、重复）、可视化编辑并快速导出。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 口播视频剪辑工具

智能口播视频剪辑工具 —— 自动识别语音、标记无效内容（静音、语气词、重复）、可视化编辑并快速导出。

## 功能

- **语音识别** — 基于 faster-whisper，自动将口播语音转为带词级时间戳的文字
- **智能标记** — 自动检测静音段、填充词（嗯、啊、呃等）、重复语句，一键删除
- **波形联动** — 波形图与视频播放器双向同步，点击波形/字幕可定位视频
- **片段标记** — 支持勾选/拖拽删除片段，实时跳过已删片段预览剪辑效果
- **字幕嵌入** — 支持 ASS 字幕嵌入导出，根据语音停顿自动分句，竖屏适配
- **无损剪辑** — 基于 FFmpeg concat 协议，不重新编码，保留原始画质
- **GPU 加速** — 支持 NVIDIA NVENC 硬件编码加速导出

## 技术栈

| 层 | 技术 |
|---|---|
| 桌面壳 | Electron |
| 前端 | React 19 + TypeScript + Vite + Tailwind CSS + Zustand |
| 后端 | Python 3.12 + FastAPI + SQLAlchemy + SQLite |
| ASR | faster-whisper |
| 音视频 | FFmpeg, librosa, Wavesurfer.js |

## 快速开始

### 方式一：Docker 部署（推荐）

```bash
docker compose up -d --build
```

启动后访问 `http://localhost`，后端 API 在 `http://localhost:9800`。

### 方式二：本地开发

#### 前置条件

- Python 3.10+
- Node.js 18+
- FFmpeg 6+（含 libass 支持）

### 后端

```bash
cd backend
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
# 安装 faster-whisper（需单独安装）
pip install faster-whisper librosa numpy

python main.py
```

默认启动在 `http://127.0.0.1:9800`

### 前端

```bash
cd frontend
npm install
npm run dev
```

默认启动在 `http://localhost:5173`，自动代理 `/api` 到后端。

### 桌面应用

```bash
cd frontend
npm run electron:dev
```

## 项目结构

```
voice-over-editing-tool/
├── backend/                      # Python FastAPI
│   ├── main.py                   # 应用入口
│   ├── requirements.txt          # Python 依赖
│   ├── api/v1/                   # REST API 路由
│   │   ├── tasks.py              # 任务 CRUD + 导出
│   │   ├── ws.py                 # WebSocket 进度推送
│   │   └── __init__.py           # 健康检查
│   ├── asr/                      # 语音识别
│   │   ├── engine.py             # 抽象引擎
│   │   └── faster_whisper_impl.py
│   ├── marker/                   # 智能标记
│   │   ├── silence_detector.py   # 静音检测
│   │   ├── filler_detector.py    # 语气词检测
│   │   └── repetition_detector.py# 重复检测
│   ├── clipper/                  # 视频剪辑
│   │   └── ffmpeg_clipper.py     # FFmpeg concat + 字幕
│   ├── database/                 # SQLite ORM
│   │   ├── models.py             # 5 张表
│   │   └── connection.py
│   ├── task/queue.py             # 异步任务队列
│   ├── schemas/                  # Pydantic 模型
│   ├── utils/                    # 工具函数
│   └── tests/                    # 后端测试
├── frontend/                     # React + Vite
│   ├── src/
│   │   ├── App.tsx               # 路由
│   │   ├── main.tsx              # 入口
│   │   ├── store/                # Zustand 状态管理
│   │   ├── api/                  # Axios API 客户端
│   │   ├── hooks/                # WebSocket hook
│   │   ├── pages/                # 5 个页面
│   │   │   ├── UploadPage.tsx
│   │   │   ├── HistoryPage.tsx
│   │   │   ├── EditPage.tsx
│   │   │   ├── ExportPage.tsx
│   │   │   └── SettingsPage.tsx
│   │   └── components/           # UI 组件
│   │       ├── VideoPlayer.tsx
│   │       ├── WaveformViewer.tsx
│   │       ├── SubtitlePanel.tsx
│   │       ├── Layout.tsx
│   │       └── Toast.tsx
│   ├── electron/                 # Electron 主进程
│   └── package.json
└── docs/                         # 开发文档与计划
```

## 任务流程

```
上传视频 → 提取音频 → 语音识别 → 智能标记 → 编辑 → 导出
```

状态机：`pending` → `extracting_audio` → `asr_processing` → `marking` → `ready` → `exporting` → `completed` / `failed`

## API 概览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/v1/tasks` | 上传视频 |
| GET | `/api/v1/tasks` | 任务列表 |
| GET | `/api/v1/tasks/{id}` | 任务详情 |
| DELETE | `/api/v1/tasks/{id}` | 删除任务 |
| POST | `/api/v1/tasks/{id}/export` | 导出剪辑 |
| GET | `/api/v1/tasks/{id}/video` | 获取原视频 |
| GET | `/api/v1/tasks/{id}/audio` | 获取音频 |
| WS | `/api/v1/ws/tasks/{id}` | 进度推送 |
| GET | `/api/v1/health` | 健康检查 |

## 测试

```bash
# 后端
cd backend && python -m pytest -v

# 前端
cd frontend && npm test
```

## 构建

```bash
cd frontend
npm run build           # Web 构建
npm run electron:build  # 桌面安装包
```

## 许可证

MIT