video-batch-trim 0.1.0

视频批量裁剪命令行工具 - 使用 ffmpeg 批量删除视频开头指定秒数

VBT - 视频批量裁剪工具

一个类似 kubectl/docker 风格的 Python 命令行工具，用于批量裁剪视频开头的指定秒数。

功能特性

• 🎬 批量处理视频文件，递归扫描子文件夹
• ⚡ 使用 ffmpeg 的流复制模式，处理速度快
• 📊 实时进度显示
• 📝 完善的日志记录（控制台 + 文件）
• 🎨 彩色控制台输出
• ⚙️ 灵活的 YAML 配置文件
• 🔄 自动处理文件名冲突

支持的视频格式

工具支持以下常见视频格式（由 ffmpeg 实际处理能力决定）：

常见格式

• .mp4, .avi, .mkv, .mov, .flv, .wmv, .m4v, .ts

MPEG 系列

• .mpg, .mpeg, .m2v, .vob, .m2ts

移动设备格式

• .3gp, .3g2, .f4v

Web 格式

• .webm, .ogv, .ogg

其他格式

• .rm, .rmvb, .asf, .wtv, .mts, .mxf, .divx, .xvid, .vro, .dat, .amv, .drc, .gifv, .svi, .viv, .nsv

注意：实际支持的格式取决于系统中安装的 ffmpeg 版本及其编译配置。如果遇到不支持的格式，ffmpeg 会报错，详情可查看日志文件。

安装

使用 uv（推荐）

# 克隆或进入项目目录
cd video_batch_trim

# 使用 uv 安装依赖
uv sync

# 或者安装为可编辑模式
uv pip install -e .

使用 pip

pip install -e .

配置

在项目根目录或运行目录创建 config.yaml 文件：

input_dir: "./input"           # 输入视频文件夹
output_dir: "./output"         # 输出文件夹
ffmpeg_path: "ffmpeg"          # ffmpeg 可执行文件路径
trim_seconds: 5                # 删除开头的秒数

使用方法

基本用法

# 显示帮助
vbt --help

# 执行视频裁剪
vbt trim

# 查看 trim 命令帮助
vbt trim --help

工作流程

1. 创建配置文件 config.yaml
2. 将要处理的视频放入 input_dir 指定的文件夹（支持子文件夹）
3. 运行 vbt trim
4. 处理后的视频将保存到 output_dir，文件名保持不变
5. 如有文件名冲突，会自动添加 5 位随机数字

日志

• 控制台输出：显示 INFO 级别以上的彩色日志
• 文件日志：保存在 logs/vbt_*.log，包含详细的 DEBUG 信息
• 日志文件自动轮转（10MB）并保留 7 天

查看日志：

# 实时查看日志
tail -f logs/vbt_*.log

# 查看所有日志
cat logs/vbt_*.log

技术栈

• 包管理: uv - 极速 Python 包管理器
• CLI 框架: Click - 优雅的命令行工具
• 配置解析: PyYAML - YAML 解析器
• 进度显示: tqdm - 美观的进度条
• 日志框架: loguru - 现代化日志库
• 视频处理: ffmpeg - 强大的多媒体处理工具

示例

配置示例

input_dir: "/Users/username/Videos/raw"
output_dir: "/Users/username/Videos/trimmed"
ffmpeg_path: "/usr/local/bin/ffmpeg"
trim_seconds: 3.5

执行示例

$ vbt trim
2026-01-15 10:30:15 | INFO     | 正在加载配置文件: config.yaml
2026-01-15 10:30:15 | INFO     | 开始扫描视频文件...
2026-01-15 10:30:15 | INFO     | 找到 15 个视频文件
2026-01-15 10:30:15 | INFO     | 开始处理视频...
Processing: 100%|██████████| 15/15 [02:30<00:00,  0.10s/it]
2026-01-15 10:32:45 | SUCCESS  | 处理完成！成功: 15, 失败: 0

项目结构

video_batch_trim/
├── vbt/
│   ├── __init__.py
│   ├── cli.py              # CLI 入口
│   ├── commands/
│   │   ├── __init__.py
│   │   └── trim.py         # trim 子命令
│   ├── config.py           # 配置管理
│   ├── logger.py           # 日志配置
│   └── utils.py            # 工具函数
├── config.yaml             # 配置文件
├── pyproject.toml          # 项目配置
├── .python-version         # Python 版本
└── README.md               # 本文档

开发

# 安装开发依赖
uv sync --dev

# 运行测试（如果有）
pytest

# 格式化代码
black vbt/

# 类型检查
mypy vbt/

许可证

MIT License

注意事项

1. 确保系统已安装 ffmpeg
2. 处理大量视频时建议先小范围测试
3. 日志文件会自动清理，但可手动删除 logs/ 目录
4. 使用 -c copy 模式，某些视频可能因编码问题无法精确裁剪关键帧