media-processing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Media Processing

媒体处理

Tools and workflows for working with images, audio, and video in a repeatable, scriptable way using standard CLI tools (FFmpeg, ImageMagick) and Python helpers.

借助标准CLI工具（FFmpeg、ImageMagick）和Python辅助脚本，以可重复、可脚本化的方式处理图片、音频和视频的工具与工作流。

When to Use

适用场景

Working with image batches (thumbnails, resizing, format conversion)
Converting media between formats (video ↔ audio ↔ image)
Optimizing video size while maintaining acceptable quality
Preparing assets for web, mobile, or archival use
Designing or refining CLI workflows around FFmpeg/ImageMagick

处理图片批量任务（缩略图生成、尺寸调整、格式转换）
媒体格式互转（视频 ↔ 音频 ↔ 图片）
在保证可接受画质的前提下优化视频体积
为网页、移动设备或归档用途准备媒体资源
围绕FFmpeg/ImageMagick设计或优化CLI工作流

Key Principles

核心原则

CLI-first workflows: Prefer command-line tools (FFmpeg, ImageMagick) and scripts that can be automated in CI or local tooling.
Deterministic scripts: Scripts should be safe to run repeatedly with predictable output paths and options.
Non-destructive defaults: Default to writing outputs to new files/directories rather than overwriting originals.
Cross-platform friendly: Keep examples and scripts usable on Linux, macOS, and Windows where possible.
Agent-agnostic: Guidance should work with any coding agent (Cursor, Claude, Copilot, etc.), not one specific environment.

CLI优先工作流：优先使用命令行工具（FFmpeg、ImageMagick）和可在CI或本地工具中自动化的脚本。
确定性脚本：脚本可安全重复运行，输出路径和参数可预测。
非破坏性默认设置：默认将输出写入新文件/目录，而非覆盖原始文件。
跨平台友好：尽可能让示例和脚本在Linux、macOS和Windows系统上均可使用。
Agent无关性：相关指导适用于任何编码Agent（Cursor、Claude、Copilot等），不局限于特定环境。

Capabilities

功能特性

Image workflows
- Batch resize and thumbnail generation
- Aspect-ratio–aware resizing (fit, fill, cover, exact)
- Optional watermarking
- Format conversion (e.g., PNG → WebP, JPEG)
Media conversion
- Detects media type (video, audio, image) from extension
- Uses FFmpeg for video/audio, ImageMagick for images
- Quality presets for
```
web
```
  ,
```
archive
```
  , and
```
mobile
```
  use cases
- Batch conversion with dry-run and verbose modes
Video optimization
- Resolution and frame-rate adjustments
- Single-pass (CRF) or two-pass encoding
- Audio bitrate tuning
- Basic before/after comparison (size, bitrate, resolution, FPS)

图片工作流
- 批量调整尺寸和生成缩略图
- 支持宽高比自适应调整（适配、填充、覆盖、精确尺寸）
- 可选添加水印
- 格式转换（例如：PNG → WebP、JPEG）
媒体格式转换
- 通过文件扩展名检测媒体类型（视频、音频、图片）
- 视频/音频使用FFmpeg处理，图片使用ImageMagick处理
- 针对
```
web
```
  、
```
archive
```
  和
```
mobile
```
  场景提供画质预设
- 支持批量转换，包含试运行（dry-run）和详细日志模式
视频优化
- 分辨率和帧率调整
- 单遍（CRF）或两遍编码
- 音频比特率调优
- 基础的优化前后对比（体积、比特率、分辨率、帧率）

Scripts

脚本说明

Scripts live in

scripts/

and are intended to be run directly from a shell:

```
batch_resize.py
```
- Batch image resizing with multiple strategies (
```
fit
```
  ,
```
fill
```
  ,
```
cover
```
  ,
```
exact
```
  ,
```
thumbnail
```
  )
- Optional watermark overlay
- Supports parallel processing and dry-run mode
```
media_convert.py
```
- Unified conversion tool for video, audio, and images
- Automatically picks FFmpeg or ImageMagick
- Uses quality presets (
```
web
```
  ,
```
archive
```
  ,
```
mobile
```
  )
- Supports batch conversion and format changes (e.g.,
```
.mov
```
  →
```
.mp4
```
  ,
```
.wav
```
  →
```
.mp3
```
  )
```
video_optimize.py
```
- Focused on video size/quality trade-offs
- Resolution caps, FPS reduction, CRF tuning, optional two-pass encoding
- Optional comparison summary between original and optimized outputs

See

scripts/requirements.txt

for environment expectations (Python 3.10+, FFmpeg, ImageMagick) and system installation hints.

脚本存放在

scripts/

目录下，可直接在Shell中运行：

```
batch_resize.py
```
- 支持多种策略的批量图片尺寸调整（
```
fit
```
  、
```
fill
```
  、
```
cover
```
  、
```
exact
```
  、
```
thumbnail
```
  ）
- 可选添加水印叠加层
- 支持并行处理和试运行模式
```
media_convert.py
```
- 视频、音频、图片的统一转换工具
- 自动选择FFmpeg或ImageMagick进行处理
- 使用
```
web
```
  、
```
archive
```
  、
```
mobile
```
  画质预设
- 支持批量转换和格式变更（例如：
```
.mov
```
  →
```
.mp4
```
  、
```
.wav
```
  →
```
.mp3
```
  ）
```
video_optimize.py
```
- 专注于视频体积与画质的平衡优化
- 支持分辨率上限设置、帧率降低、CRF调优、可选两遍编码
- 可选生成原始视频与优化后视频的对比摘要

环境依赖可查看

scripts/requirements.txt

（要求Python 3.10+、FFmpeg、ImageMagick），其中包含系统安装提示。

Usage Guidelines

使用指南

Check dependencies first
- Ensure
```
ffmpeg
```
  and
```
ffprobe
```
  are installed and on
```
PATH
```
  for video/audio tasks.
- Ensure
```
magick
```
  (ImageMagick) is installed and on
```
PATH
```
  for image tasks.
Prefer dry-runs when exploring
- Use
```
--dry-run
```
  and/or
```
--verbose
```
  flags on scripts to inspect generated commands before running them.
Keep originals
- Point outputs to a separate directory on first runs (e.g.,
```
--output ./out/
```
  ) to avoid accidental overwrites.
Document workflows
- When you find good command lines or script invocations, promote them into project scripts (e.g.,
```
just
```
  ,
```
npm scripts
```
  , or CI jobs) so they’re repeatable.

先检查依赖
- 确保
```
ffmpeg
```
  和
```
ffprobe
```
  已安装并添加到
```
PATH
```
  中，用于处理视频/音频任务。
- 确保
```
magick
```
  （ImageMagick）已安装并添加到
```
PATH
```
  中，用于处理图片任务。
探索时优先使用试运行模式
- 在脚本中使用
```
--dry-run
```
  和/或
```
--verbose
```
  参数，在实际运行前查看生成的命令。
保留原始文件
- 首次运行时将输出指向单独目录（例如：
```
--output ./out/
```
  ），避免意外覆盖原始文件。
记录工作流
- 当找到合适的命令行或脚本调用方式时，将其整合到项目脚本中（例如：
```
just
```
  、
```
npm scripts
```
  或CI任务），确保工作流可重复执行。

References

参考资料

For deeper tool-specific notes (placeholders for now, extend as needed), see:

```
references/ffmpeg-encoding.md
```
– FFmpeg encoding patterns and flags
```
references/ffmpeg-filters.md
```
– Common filter graphs (scale, crop, audio filters)
```
references/ffmpeg-streaming.md
```
– Streaming-friendly settings and HLS/DASH tips
```
references/format-compatibility.md
```
– Container/codec compatibility notes (web, mobile, desktop)
```
references/imagemagick-batch.md
```
– Batch image processing patterns with ImageMagick
```
references/imagemagick-editing.md
```
– Image editing operations (crop, resize, composite, text, etc.)

如需更深入的工具专属说明（目前为占位符，可按需扩展），请查看：

```
references/ffmpeg-encoding.md
```
– FFmpeg编码模式与参数
```
references/ffmpeg-filters.md
```
– 常用滤镜图（缩放、裁剪、音频滤镜）
```
references/ffmpeg-streaming.md
```
– 流媒体友好设置及HLS/DASH技巧
```
references/format-compatibility.md
```
– 容器/编解码器兼容性说明（网页、移动设备、桌面端）
```
references/imagemagick-batch.md
```
– ImageMagick批量图片处理模式
```
references/imagemagick-editing.md
```
– 图片编辑操作（裁剪、缩放、合成、文字添加等）