# ffmpeg_tools

**Repository Path**: giaog/ffmpeg_tools

## Basic Information

- **Project Name**: ffmpeg_tools
- **Description**: 基于ffmpeg实现的视频处理工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FFmpeg 工具箱

一个与 go2rtc 完全隔离的本地 FFmpeg 媒体处理工具箱。项目围绕“本机处理、少依赖、可视化操作”组织，当前包含命令行、桌面 UI、uTools 插件和本地网页四种入口。

视频分辨率转换的默认目标尺寸为 `2960x1666`。

## 功能状态

| 入口 | 位置 | 当前能力 |
| --- | --- | --- |
| 命令行 | `video_resizer.py` | 视频分辨率转换；核心命令构造覆盖更多媒体操作 |
| 桌面 UI | `desktop-ui/` | 视频分辨率转换、进度显示、取消任务 |
| uTools 插件 | `utools-plugin/` | 分辨率转换、格式转换、视频压缩、视频裁剪、音频提取、视频合并、截图/缩略图、水印、自动裁剪、音频替换/背景音乐、HLS 导出 |
| 本地网页 | `local-web/` | 与 uTools 插件同等的工具箱能力，HLS 与批量缩略图以 ZIP 下载 |

已支持的视频操作：

- 分辨率转换：等比补边、等比裁剪或拉伸到精确尺寸。
- 格式转换：支持 `mp4`、`mov`、`mkv`、`webm`，优先无损封装，失败后自动转码。
- 视频压缩：支持 H.264、H.265、VP9，支持复制原音频或转码音频。
- 视频裁剪：支持时间截取和画面区域裁切。
- 提取音频：支持 MP3、AAC、M4A、WAV、FLAC、码率、采样率和声道设置。
- 视频合并：支持多视频顺序合并，优先 concat copy，失败后自动转码。
- 视频截图 / 缩略图：支持单张截图，批量缩略图以 ZIP 交付。
- 加水印：支持文字水印和图片水印，可调位置、边距、透明度等参数。
- 去黑边 / 自动裁剪：使用 FFmpeg cropdetect 检测黑边并自动裁切。
- 音频替换或添加背景音乐：支持替换原音轨或混音背景音乐。
- HLS 切片导出：输出单清晰度 VOD HLS，网页端和 uTools 端均打包 ZIP。

Tkinter 桌面 UI 暂未扩展这些新能力，仍保持原有分辨率转换工作流。

## 环境要求

- Python 3.8 或更高版本。
- FFmpeg。建议同时安装 `ffprobe`；没有 `ffprobe` 时会回退到 `ffmpeg` 读取媒体信息。
- Tkinter。大多数 macOS/Windows Python 已自带，Linux 可能需要安装 `python3-tk`。
- uTools 插件版需要 uTools 开发者工具。

常见安装方式：

```bash
# macOS
brew install ffmpeg

# Windows
winget install Gyan.FFmpeg
```

如果 FFmpeg 不在 `PATH` 中，可以在命令行、桌面 UI、网页服务或 uTools 插件里显式指定完整路径。

## 快速开始

先运行测试确认基础逻辑可用：

```bash
python3 -m unittest -v
```

### 命令行转换分辨率

```bash
python3 video_resizer.py input.mp4 output.mp4
```

指定目标尺寸：

```bash
python3 video_resizer.py input.mp4 output.mp4 --size 1920x1080
```

工具也接受 `2960×1666` 和 `2960*1666` 这两种尺寸写法。宽和高必须为偶数，以兼容 H.264 / `yuv420p` 编码。

### 桌面 UI

```bash
python3 desktop-ui/video_resizer_gui.py
```

桌面 UI 支持选择输入/输出文件、自动识别源分辨率和时长、选择目标尺寸预设、实时进度条、预计剩余时间、取消转码和打开输出目录。详细说明见 `desktop-ui/README.md`。

### 本地网页

```bash
python3 local-web/server.py
```

默认监听 `0.0.0.0:8765`。本机打开：

```text
http://127.0.0.1:8765/
```

局域网其他设备可以使用运行服务电脑的 IP 访问。详细说明见 `local-web/README.md`。

### uTools 插件

在 uTools 开发者工具中选择：

```text
utools-plugin/plugin.json
```

插件提供关键字入口和视频文件匹配入口，并通过 uTools MCP 暴露 `video_probe`、`video_convert`、`video_resize` 三个 AI Agent 工具。详细说明见 `utools-plugin/README.md`。

## 分辨率适配模式

| 模式 | 参数 | 说明 |
| --- | --- | --- |
| 等比补边 | `--mode fit` | 默认模式，保持宽高比，空余区域补黑边，输出尺寸严格等于目标尺寸 |
| 等比裁剪 | `--mode fill` | 保持宽高比并居中裁剪，不留黑边 |
| 拉伸 | `--mode stretch` | 直接拉伸到目标尺寸，可能导致画面变形 |

示例：

```bash
python3 video_resizer.py input.mp4 output.mp4 --size 2960x1666 --mode fill
```

## 常用命令参数

输出文件已存在时，命令行默认拒绝覆盖。确认需要覆盖时添加：

```bash
python3 video_resizer.py input.mp4 output.mp4 --overwrite
```

查看检测结果和即将执行的 FFmpeg 命令，但不实际转码：

```bash
python3 video_resizer.py input.mp4 output.mp4 --dry-run
```

指定 FFmpeg：

```bash
python3 video_resizer.py input.mp4 output.mp4 --ffmpeg /完整路径/ffmpeg
```

默认编码参数为 H.264 (`libx264`)、`CRF 20`、`medium` preset、`yuv420p`，音频流保持复制。可以用 `--encoder`、`--crf` 和 `--preset` 调整。

查看全部参数：

```bash
python3 video_resizer.py --help
```

## FFmpeg 自动查找

项目会优先使用用户显式指定的路径，然后查找 `PATH` 和常见安装目录。

macOS 常见目录：

- `/opt/homebrew/opt/ffmpeg/bin`
- `/opt/homebrew/bin`
- `/usr/local/opt/ffmpeg/bin`
- `/usr/local/bin`
- `/opt/local/bin`

Windows 常见目录：

- Scoop shims 和 `scoop/apps/ffmpeg/current/bin`
- WinGet Links 和 WinGet Packages
- Chocolatey `bin`
- 用户目录下的 `tools`、`ffmpeg/bin`
- `Program Files/ffmpeg/bin`
- `C:\ffmpeg\bin`

## 项目结构

```text
.
├── video_resizer.py          # 核心 FFmpeg 命令构建与命令行入口
├── test_video_resizer.py     # 单元测试
├── desktop-ui/               # Tkinter 桌面 UI
├── local-web/                # 本地网页版本
└── utools-plugin/            # uTools 插件版本
```

## 排查建议

- 提示找不到 FFmpeg：先运行 `ffmpeg -version`，或在界面/命令里指定完整路径。
- 提示找不到视频流：确认输入文件能被 FFmpeg 读取。
- 输出文件已存在：改名输出，或开启覆盖。
- Web 端远程访问失败：确认服务启动日志中的监听地址、端口和防火墙设置。
- Web 端上传大文件失败：使用 `--max-upload-mb` 调整单个上传文件上限。