video-toolkit-litouge 0.1.4

批量压缩视频素材的 CLI 工具

🎬 Video Toolkit Litouge

一个用于批量压缩视频素材的 Python 工具，支持 .mov 转码、.mp4 压缩、智能分辨率控制、输出目录指定、GPU 加速、快速压缩模式、原始视频处理策略等功能。适用于素材库清理、自动化预处理、视频体积优化等场景。

---

🆕 更新日志（v0.1.4）

• ✅ 覆盖保护机制：自动检测 .mp4 → .mp4 压缩风险，原始文件将临时改名为 _pending_original_...，压缩完成后再恢复原名并处理，避免误覆盖
• ✅ 处理顺序优化：确保压缩完成后再执行原始文件处理策略（改名、移动等）
• ✅ 逻辑更稳健：无需用户干预即可安全处理同名文件，兼容所有 --handle-original 模式
• ✅ CLI 参数保持不变：无需修改命令行调用方式，兼容旧版本脚本和文档

---

🆕 更新日志（v0.1.1）

• ✅ 支持更多视频格式：新增 .avi, .mkv, .webm, .flv 等扩展名识别
• ✅ 可配置扩展名列表：通过 --ext 参数自定义要处理的视频类型
• ✅ 默认处理原始视频：压缩后自动将原始文件移动到 compressed/ 子目录（默认行为）
• ✅ 排除压缩目录：自动跳过 compressed/ 文件夹，避免重复处理或死循环
• ✅ 移除废弃参数：彻底删除 --prefix，压缩文件保留原始文件名
• ✅ 命令行入口修复：确保 video-toolkit-litouge 正确注册为可执行命令
• ✅ 发布流程优化：新增版本更新与构建清理指南，支持 Windows 与 Linux 用户

---

🚀 安装

确保你已安装 ffmpeg 并将其加入系统 PATH。

然后在项目根目录执行：

pip install .

或开发模式安装（推荐调试时使用）：

pip install -e .

---

🧪 使用示例

video-toolkit-litouge -d ./videos -s 100 -c 26 -r 1920x1080 -o ./output -f -g -w --handle-original rename

---

⚙️ 参数说明

参数	简写	说明
--directory	-d	要处理的根目录（必填）
--size	-s	文件大小阈值（单位 MB，默认 100）
--crf	-c	压缩质量（默认 26，范围 18–35）
--resolution	-r	目标分辨率（如 1920x1080，仅对高于此分辨率的视频生效）
--output-dir	-o	压缩文件输出目录（默认保存在源目录）
--verbose	-v	显示 ffmpeg 输出信息（调试用）
--fast	-f	使用快速压缩模式（preset=fast）
--gpu	-g	使用 GPU 编码（h264_nvenc）
--dry-run	-n	仅打印将处理的文件，不执行压缩
--overwrite	-w	强制覆盖已存在的压缩文件
--handle-original	无	压缩后如何处理原始文件：move_local（默认）、rename、none、move_to
--original-target	无	原始文件移动目标目录（仅在 move_to 模式下使用）

⚠️ --prefix 参数已废弃，压缩后文件将保留原始文件名。

---

📦 依赖

• ffmpeg（必须安装并加入系统 PATH）
• tqdm

安装依赖：

pip install tqdm

---

🧠 示例用途

• 批量压缩 .mov 素材为 .mp4
• 自动统一分辨率为 1920x1080
• 清理素材库中超过 100MB 的视频
• 使用 GPU 加速压缩过程
• 快速预览将要处理的文件（dry-run）
• 压缩后将原始视频移动到 compressed/ 子目录或指定目录

---

📁 项目结构建议

video_toolkit/
├── video_toolkit/
│   ├── __init__.py
│   ├── cli.py
│   ├── compressor.py
│   ├── utils.py
├── pyproject.toml
├── README.md
├── requirements.txt

---

🧼 后续规划

• ✅ 支持多线程并发处理
• ✅ 支持 YAML 配置文件
• ✅ 支持更多格式（如 .avi, .mkv）
• ✅ 支持压缩统计与日志输出

---