semvec/pypi-packages huggingface dataset:
video-toolkit-litouge 0.1.5
批量压缩视频素材的 CLI 工具
Requires Python: >=3.8



# 🎬 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](https://ffmpeg.org/) 并将其加入系统 PATH。

然后在项目根目录执行：

```bash
pip install .
```

或开发模式安装（推荐调试时使用）：

```bash
pip install -e .
```

---

## 🧪 使用示例

```bash
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](https://ffmpeg.org/)（必须安装并加入系统 PATH）
- [tqdm](https://pypi.org/project/tqdm/)

安装依赖：

```bash
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`）
- ✅ 支持压缩统计与日志输出

---