# easy-ffmpeg

**Repository Path**: dreadice/easy-ffmpeg

## Basic Information

- **Project Name**: easy-ffmpeg
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyFFmpeg

一键式 FFmpeg 调用工具箱，让视频处理变得简单。

## 简介

EasyFFmpeg 是一个基于 Electron + TypeScript 的桌面应用，将 FFmpeg 的强大能力封装为可视化操作。无需记忆复杂的命令行参数，选择视频、配置参数、一键执行。

## 已实现的工具

### 🎬 场景帧提取

自动检测视频中的场景切换，为每个场景提取指定帧。

- 使用 FFmpeg `scdet` 滤镜进行场景探测
- 可配置场景检测阈值、提取帧索引、输出质量
- 自动检测视频帧率、硬件加速支持
- 输出目录以时间戳命名，不覆盖历史结果
- 支持中途停止
- 提取结果实时预览，点击可放大查看

## 计划中的工具

- [ ] 视频转码（格式转换、编码器选择、码率控制）
- [ ] 视频裁剪（时间区间裁剪）
- [ ] 视频拼接（多段合并）
- [ ] 音频提取
- [ ] 字幕处理
- [ ] GIF 生成
- [ ] 视频信息查看
- [ ] 批量处理

## 系统要求

- Node.js 20+
- FFmpeg 4.3+（推荐 7.0+）
- Windows / macOS

## 安装

```bash
# 克隆项目
git clone <repo-url>
cd easy-ffmpeg

# 设置国内镜像（可选，加速 Electron 下载）
npm config set registry https://registry.npmmirror.com/

# 安装依赖
npm install
```

### 安装 FFmpeg

- **Windows**：[下载](https://ffmpeg.org/download.html) 后将 bin 目录添加到系统 PATH
- **macOS**：`brew install ffmpeg`

## 使用

```bash
# 构建并启动
npm start
```

### 操作流程

1. 点击「选择视频文件」
2. 选择要执行的工具（如「提取场景第五帧」）
3. 在弹出的参数面板中调整参数
4. 点击「执行」
5. 处理过程中可点击「停止」取消
6. 结果实时显示在右侧预览区，点击图片可放大查看

### 场景帧提取参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| 场景检测阈值 | 0-100，值越小检测越灵敏 | 15 |
| 最大场景数 | 0 = 不限制 | 0 |
| 输出质量 | 1 = 最高，31 = 最低 | 2 |
| 提取第几帧 | 每个场景提取第 N 帧 | 5 |
| 使用硬件加速 | 自动检测并启用 | 开 |

### 输出

- 输出目录：视频文件所在目录下，以时间戳命名（如 `scene_20260409_143527`）
- 文件命名：`scene_1_frame_5.jpg`、`scene_2_frame_5.jpg` ...
- 每次执行生成新目录，不覆盖历史结果

## 项目结构

```
src/
├── main/
│   └── main.ts           # Electron 主进程
├── renderer/
│   ├── index.html         # 界面
│   └── index.js           # 渲染逻辑
├── config/
│   └── operations.ts      # 工具配置（扩展新工具在此添加）
├── utils/
│   └── ffmpeg.ts          # FFmpeg 核心调用
└── preload.ts             # 预加载脚本
```

### 添加新工具

在 `src/config/operations.ts` 中添加一个新的操作配置即可：

```typescript
{
  id: 'your-tool-id',
  name: '工具名称',
  description: '工具描述',
  params: [
    { name: 'param1', label: '参数1', type: 'number', default: 10, min: 0, max: 100 }
  ],
  execute: async (videoPath, outputDir, params, onProgress, onFrameExtracted) => {
    // 调用 ffmpeg.ts 中的函数
  }
}
```

## 技术栈

- **Electron 41** — 桌面应用框架
- **TypeScript 5.8** — 类型安全
- **FFmpeg** — 视频处理引擎
- **Node.js child_process** — FFmpeg 进程管理

## 常见问题

**FFmpeg 未找到**：确保 FFmpeg 已安装并添加到系统 PATH。

**提取的图片是黑屏**：在参数中关闭硬件加速重试。

**场景检测不准确**：降低场景检测阈值（如从 15 调到 5）可检测更多场景。

**npm install 卡在 Electron 下载**：项目根目录已配置 `.npmrc` 使用国内镜像，如仍失败可手动设置环境变量：

```powershell
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm install
```

## License

ISC