mediashrink

命令行工具：转码、压缩 视频、音频、图片和 PDF，支持单个文件、批量文件和整个文件夹。

安装

需要 Python ≥ 3.12；处理视频 / 音频还需要 ffmpeg（含 ffprobe）在 PATH 中。

brew install ffmpeg              # macOS；Linux 用 apt install ffmpeg 等

uv tool install mediashrink      # 推荐（需要 uv）：独立环境，命令全局可用
# 或
pipx install mediashrink
# 或
pip install mediashrink

升级：uv tool upgrade mediashrink（或 pipx upgrade mediashrink / pip install -U mediashrink）。

从源码运行：克隆仓库后 uv sync，再用 uv run mediashrink ...。

快速上手

# 图片 → WebP（整个文件夹）
mediashrink image ~/素材 -f webp -o ~/素材/webp

# 视频 → WebM（整个文件夹，按画质压缩）
mediashrink video ~/素材 -f webm -o ~/素材/webm

# 视频 → WebM，每个文件控制在 10MB 以内（适合网页加载）
mediashrink video ~/素材 -f webm -t 10M -o ~/素材/webm

连子目录一起处理加 -r；查看某个子命令的全部参数用 mediashrink <子命令> --help。

输入与输出（所有子命令通用）

• 处理文件夹时会自动跳过：隐藏文件、之前生成的 *.min.*、-o 输出目录里的文件，所以同一条命令反复运行是安全的。
• 任何情况下都不会覆盖原文件。
• 每个文件处理完会打印 原大小 → 新大小 (比例)；有文件失败时退出码为 1，其余文件不受影响。

图片：image

mediashrink image ~/素材 -f webp -q 75 --max-size 1920 -o ~/素材/webp

视频：video

mediashrink video in.mov -f webm                          # webm 自动用 vp9
mediashrink video in.mov -f webm --crf 36 --max-height 1080
mediashrink video in.mov -f webm -t 10M                   # 控制在 10MB 以内
mediashrink video in.mp4 -c h265 -o out.mp4               # mp4 默认 h265

两种压缩模式（二选一）

-t / --target-size 的工作方式：

1. 用 ffprobe 读取时长，按 目标大小 × 8 ÷ 时长 算出总码率（预留约 4% 给封装开销），再分给视频和音频；音频占比超过约 15% 时自动降低音频码率。
2. 码率撑不起原分辨率时，按 2160 / 1440 / 1080 / 720 / 540 / 480 / 360 / 240 逐档降低分辨率，避免糊成马赛克；--max-height 作为上限，手机竖屏视频会正确识别方向。
3. vp9 / h264 两遍编码，码率分配更准；结果仍超标时自动降低码率重压，最多 3 次。
4. 目标在该时长下不可能达到时（例如 1 小时压到 10MB），直接报错并给出最少需要的大小。
5. 单位必须写（500K、10M、1.5G），按十进制计算：10M = 10,000,000 字节，在 macOS 访达里也显示不超过 10 MB。

10MB 大约能放多长的视频（1080p30 源、默认 128k 音频时的规划结果）：

参数

输出 mp4 / mov 时会加 +faststart（边下边播）；h265 会打 hvc1 标签，苹果设备可直接播放。

编码选择与速度

文件多、文件长又不需要兼容老设备时，推荐：

mediashrink video ~/素材 -c av1 -f webm -t 10M -o ~/素材/webm

其他子命令

mediashrink audio song.wav -f mp3 -b 192k        # 音频：mp3 / m4a / aac / opus / ogg / flac；--sample-rate、--mono
mediashrink pdf scan.pdf -q 60 --max-image-size 1600   # PDF：重新压缩内嵌图片和数据流
mediashrink auto ~/素材 -o ~/素材/out            # 按文件类型自动选择，全部用默认参数
mediashrink info video.mp4                       # 查看媒体信息（ffprobe JSON）

• pdf：把内嵌的 RGB / 灰度图片重新编码为 JPEG（只有确实变小才替换），带透明蒙版的图片保持不动；不依赖 Ghostscript，纯文字 / 矢量 PDF 效果有限。
• auto：视频 → mp4（h265），wav / wma / flac → m4a，其他音频保持格式；bmp / tif / gif 等 → jpg；PDF → pdf。只支持 -o、-y、-r。

常见问题

开发

uv sync
uv run pytest
uv run ruff check . && uv run ruff format .

发布新版本

1. 修改 pyproject.toml 里的 version（如 0.2.0），合并到 master。
2. 二选一：
   • 在 GitHub 上新建 Release，tag 写 v0.2.0（必须和 version 一致），点 Publish；
   • 或在 Actions 页面对 Publish to PyPI 点 Run workflow（分支选 master），发布后会自动创建 v0.2.0 tag 和 Release。
3. GitHub Actions（.github/workflows/publish.yml）会跑测试、构建，并通过 PyPI Trusted Publishing 自动上传，无需 API token。

许可证

MIT：可以自由使用、修改和分发，保留版权声明即可。