ffmpeg

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FFmpeg

CLI skill for local audio/video inspection and transformation via

ffmpeg

and

ffprobe

. Invoke as

/ffmpeg

Scope: Probe metadata, trim clips, transcode containers/codecs, concatenate segments, extract audio, capture thumbnails, and build GIF previews from files on disk. NOT for AI image or video generation (

draw-thing

), UI or layout design (

design

), networked downloads (

yt-dlp

), or broadcast/streaming pipelines.

一款基于

ffmpeg

和

ffprobe

的CLI工具，用于本地音视频文件的检查与转换。调用方式为

/ffmpeg

。

适用范围： 探测元数据、修剪片段、转码容器/编码格式、拼接视频段、提取音频、截取缩略图、从本地磁盘文件生成GIF预览。不支持AI图像/视频生成（

draw-thing

）、UI/布局设计（

design

）、网络下载（

yt-dlp

）或直播/流媒体工作流。

Canonical Vocabulary

标准术语定义

Term	Meaning	NOT
probe	Read-only ffprobe inspection	transcode
trim	Shorten by time range	crop UI mockup
transcode	Re-mux or re-encode to new container/codec	generate new imagery
concat	Join multiple inputs sequentially	merge git branches
extract-audio	Strip video, keep audio track	speech-to-text
thumbnail	Single still frame from video	design a poster layout
gif	Animated GIF preview from video clip	CSS animation
stream copy	`-c copy` without re-encode	always safe for all trims
recipe	Approved command template from `references/`	ad-hoc filter graph

术语	含义	排除场景
probe	只读式ffprobe探测	转码
trim	按时间范围缩短视频	裁剪UI原型
transcode	重新封装或重新编码为新容器/编码格式	生成新图像
concat	按顺序合并多个输入文件	合并Git分支
extract-audio	剥离视频，保留音轨	语音转文字
thumbnail	从视频中提取单帧静态画面	设计海报布局
gif	从视频片段生成动画GIF预览	CSS动画
stream copy	使用 `-c copy` 参数不重新编码	并非适用于所有修剪场景
recipe	来自 `references/` 目录的已批准命令模板	临时自定义滤镜图

Dispatch

命令调度

`$ARGUMENTS`	Mode	Action
`doctor` / `check` / `preflight`	Doctor	Run PATH doctor; stop if ffmpeg/ffprobe missing
`probe <path>` / `info <path>` / `metadata <path>`	Probe	Run probe helper; summarize streams and duration
`trim <path> <start> <end>` / `clip <path> ...`	Trim	Probe, pick copy vs re-encode recipe, new output path
`transcode <path>` / `convert <path> to mp4`	Transcode	Probe codecs; apply H.264/AAC or copy recipe
`concat <file1> <file2> [...]` / `join ...`	Concat	Verify probes; concat demuxer recipe + new output
`extract-audio <path>` / `audio <path>`	Extract audio	Probe audio stream; MP3/M4A/copy recipe
`thumbnail <path>` / `thumb <path> [timestamp]`	Thumbnail	Seek frame; write JPG/PNG to new path
`gif <path>` / `animate <path> [start] [duration]`	GIF	Palette GIF recipe with duration cap
Path to media + natural language edit intent	Auto	Classify trim/transcode/thumbnail/gif from intent
(empty)	Help	Show modes, critical rules, script commands, references

`$ARGUMENTS` 参数	模式	操作
`doctor` / `check` / `preflight`	环境检查	运行PATH检查；若ffmpeg/ffprobe缺失则终止操作
`probe <path>` / `info <path>` / `metadata <path>`	文件探测	运行探测工具；汇总流信息和时长
`trim <path> <start> <end>` / `clip <path> ...`	视频修剪	探测源文件，选择复制或重新编码方案，生成新输出路径
`transcode <path>` / `convert <path> to mp4`	格式转码	探测编码格式；应用H.264/AAC或直接复制方案
`concat <file1> <file2> [...]` / `join ...`	文件拼接	验证探测结果；使用拼接解复用器方案并生成新输出文件
`extract-audio <path>` / `audio <path>`	音频提取	探测音轨；应用MP3/M4A/直接复制方案
`thumbnail <path>` / `thumb <path> [timestamp]`	缩略图截取	定位帧位置；将JPG/PNG写入新路径
`gif <path>` / `animate <path> [start] [duration]`	GIF生成	使用调色板GIF方案，限制时长上限
媒体文件路径+自然语言编辑需求	自动识别	根据需求分类为修剪/转码/缩略图/GIF模式
(空参数)	帮助	显示模式说明、核心规则、脚本命令和参考文档

Auto-Detection Heuristic

自动识别规则

Install/tooling doubt → Doctor.
"metadata", "codec", "duration", "how long", "what format" → Probe.
"cut", "clip", "from ... to ...", time range → Trim.
"mp4", "webm", "h264", "aac", "smaller", "compress" → Transcode.
"join", "merge clips", "append videos" → Concat.
"mp3", "wav", "m4a", "strip video", "audio only" → Extract audio.
"poster frame", "screenshot", "still", "thumbnail" → Thumbnail.
"gif", "animated preview" → GIF.
Generative image/video language → refuse; redirect to
```
draw-thing
```
.
UI/page/layout design → refuse; redirect to
```
design
```
.
Ambiguous → ask which mode and state copy vs re-encode tradeoff.

安装/工具疑问 → 环境检查
包含"metadata"、"codec"、"duration"、"时长"、"格式" → 文件探测
包含"cut"、"clip"、"从...到..."、时间范围 → 视频修剪
包含"mp4"、"webm"、"h264"、"aac"、"缩小"、"压缩" → 格式转码
包含"join"、"合并片段"、"追加视频" → 文件拼接
包含"mp3"、"wav"、"m4a"、"剥离视频"、"仅保留音频" → 音频提取
包含"海报帧"、"截图"、"静态画面"、"缩略图" → 缩略图截取
包含"gif"、"动画预览" → GIF生成
生成式图像/视频相关描述 → 拒绝请求；引导至
```
draw-thing
```
UI/页面/布局设计相关描述 → 拒绝请求；引导至
```
design
```
需求模糊 → 询问用户选择模式，并说明复制与重新编码的权衡

Critical Rules

核心规则

Probe before mutate — run
```
probe_media.py
```
on every source file before trim, transcode, concat, extract-audio, thumbnail, or gif. Use probe fields to choose maps, codecs, and duration bounds. See
```
references/probe-fields.md
```
.
Never overwrite in-place (default) — always write to a new output path. In-place replace requires explicit user approval plus backup/temp-file replace. See
```
references/safety.md
```
.
Recipe-only mutations — build ffmpeg commands only from
```
references/recipes-trim-transcode.md
```
and
```
references/recipes-thumbnail-gif.md
```
. No improvised filter chains or destructive batch jobs without approval.

先探测再修改 — 在执行修剪、转码、拼接、音频提取、缩略图截取或GIF生成前，必须对每个源文件运行
```
probe_media.py
```
。使用探测字段选择映射、编码格式和时长范围。详见
```
references/probe-fields.md
```
。
默认禁止原地覆盖 — 始终写入新输出路径。原地替换需用户明确批准，并执行备份/临时文件替换流程。详见
```
references/safety.md
```
。
仅使用预设方案修改 — 仅从
```
references/recipes-trim-transcode.md
```
和
```
references/recipes-thumbnail-gif.md
```
构建ffmpeg命令。未经批准不得使用临时滤镜链或破坏性批量任务。

Prerequisite Protocol

前置检查流程

Run before any mutation:

bash

uv run python scripts/doctor.py --format json

Stop when JSON

ok

is false. Install guidance:

bash

brew install ffmpeg

For each input file:

bash

uv run python scripts/probe_media.py /absolute/path/to/input.mp4

Parse

summary.duration_seconds

summary.stream_counts

, and codec fields before selecting a recipe.

执行任何修改操作前需运行：

bash

uv run python scripts/doctor.py --format json

若JSON返回

ok

为

false

则终止操作。安装指引：

bash

brew install ffmpeg

对每个输入文件执行：

bash

uv run python scripts/probe_media.py /absolute/path/to/input.mp4

在选择方案前解析

summary.duration_seconds

、

summary.stream_counts

和编码格式字段。

Mode Protocols

各模式执行流程

Doctor

环境检查

Run

uv run python scripts/doctor.py --format json

Report
```
checks
```
statuses and remediation for any
```
fail
```
.
Do not run ffmpeg mutations when
```
ffmpeg-binary
```
or
```
ffprobe-binary
```
fails.

运行

uv run python scripts/doctor.py --format json

报告
```
checks
```
状态，并为任何
```
fail
```
项提供修复方案
若
```
ffmpeg-binary
```
或
```
ffprobe-binary
```
检查失败，不得执行ffmpeg修改操作

Probe

文件探测

Require a readable local file path.

Run

uv run python scripts/probe_media.py <path>

Summarize: container, duration, video/audio codecs, resolution, stream counts.
Load
```
references/probe-fields.md
```
when interpreting rotation, multi-track audio, or subtitle streams.

要求提供可读取的本地文件路径

运行

uv run python scripts/probe_media.py <path>

汇总信息：容器格式、时长、视频/音频编码、分辨率、流数量
解读旋转角度、多轨音频或字幕流时，加载
```
references/probe-fields.md
```

Trim

视频修剪

Probe source; validate
```
start
```
/
```
end
```
against
```
duration_seconds
```
.
Prefer stream copy when keyframe alignment is acceptable; otherwise use re-encode trim recipe.
Output to
```
basename.trim.ext
```
or user-provided new path.
Load
```
references/recipes-trim-transcode.md
```
.

探测源文件；验证
```
start
```
/
```
end
```
是否在
```
duration_seconds
```
范围内
若关键帧对齐可接受，优先使用流复制；否则使用重新编码修剪方案
输出至
```
basename.trim.ext
```
或用户指定的新路径
加载
```
references/recipes-trim-transcode.md
```

Transcode

格式转码

Probe source; decide copy vs H.264/AAC re-encode.
Map explicit streams when multiple tracks exist.
Include
```
-movflags +faststart
```
for MP4 web delivery unless user forbids.
Load
```
references/recipes-trim-transcode.md
```
.

探测源文件；决定使用直接复制还是H.264/AAC重新编码
存在多轨时明确映射流
除非用户禁止，否则MP4格式需添加
```
-movflags +faststart
```
参数以适配网页分发
加载
```
references/recipes-trim-transcode.md
```

Concat

文件拼接

Probe every segment; confirm compatible codecs/resolution for copy concat.
Build concat list file with absolute paths; never concat unrelated codecs with copy without warning.
Output to a new
```
*.concat.mp4
```
path.
Load
```
references/recipes-trim-transcode.md
```
.

探测所有片段；确认编码/分辨率兼容以使用直接复制拼接
使用绝对路径构建拼接列表文件；未警告情况下不得直接复制拼接不兼容编码的文件
输出至新的
```
*.concat.mp4
```
路径
加载
```
references/recipes-trim-transcode.md
```

Extract audio

音频提取

Probe source; fail gracefully when
```
stream_counts.audio
```
is zero.
Choose MP3, M4A, or copy recipe based on target format.
Write
```
basename.audio.ext
```
as a new file.
Load
```
references/recipes-trim-transcode.md
```
.

探测源文件；若
```
stream_counts.audio
```
为0则优雅终止
根据目标格式选择MP3、M4A或直接复制方案
将文件写入
```
basename.audio.ext
```
新文件
加载
```
references/recipes-trim-transcode.md
```

Thumbnail

缩略图截取

Probe source; require at least one video stream.
Pick timestamp (user value, or 10% duration clamped 1–10s).
Write JPG/PNG under
```
OUTPUT/
```
or sibling path — never overwrite source.
Load
```
references/recipes-thumbnail-gif.md
```
.

探测源文件；要求至少包含一条视频流
选择时间戳（用户指定值，或时长的10%，限制在1-10秒之间）
将JPG/PNG写入
```
OUTPUT/
```
目录或同级路径 — 不得覆盖源文件
加载
```
references/recipes-thumbnail-gif.md
```

GIF

GIF生成

Probe source; cap duration (default max 5s unless user expands).
Use two-pass palette recipe for quality; single-pass only for quick previews.
Write
```
clip.gif
```
and optional
```
palette.png
```
as new files.
Load
```
references/recipes-thumbnail-gif.md
```
.

探测源文件；限制时长（默认最大5秒，用户可扩展）
使用双-pass调色板方案保证质量；仅快速预览时使用单-pass
将
```
clip.gif
```
和可选的
```
palette.png
```
写入新文件
加载
```
references/recipes-thumbnail-gif.md
```

Help (empty)

帮助 (空参数)

Show dispatch table, critical rules, doctor/probe commands, reference index, and the gallery below.

显示调度表、核心规则、环境检查/文件探测命令、参考文档索引及下方示例库

Gallery (Empty Arguments)

示例库（空参数时展示）

Present common local media tasks when

$ARGUMENTS

is empty:


/ffmpeg doctor
/ffmpeg probe ~/Movies/clip.mp4
/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15
/ffmpeg transcode ~/Movies/clip.mov
/ffmpeg concat part1.mp4 part2.mp4
/ffmpeg extract-audio ~/Movies/clip.mp4
/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03
/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4

#	Task	Example
1	Preflight tooling	`/ffmpeg doctor`
2	Inspect metadata	`/ffmpeg probe ~/Movies/clip.mp4`
3	Trim a clip	`/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15`
4	Transcode container	`/ffmpeg transcode ~/Movies/clip.mov`
5	Join segments	`/ffmpeg concat part1.mp4 part2.mp4`
6	Extract audio	`/ffmpeg extract-audio ~/Movies/clip.mp4`
7	Poster frame	`/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03`
8	GIF preview	`/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4`

Pick a number, a mode from the dispatch table, or paste a file path and describe the edit.

当

$ARGUMENTS

为空时，展示常见本地媒体任务：


/ffmpeg doctor
/ffmpeg probe ~/Movies/clip.mp4
/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15
/ffmpeg transcode ~/Movies/clip.mov
/ffmpeg concat part1.mp4 part2.mp4
/ffmpeg extract-audio ~/Movies/clip.mp4
/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03
/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4

序号	任务	示例
1	工具预检查	`/ffmpeg doctor`
2	查看元数据	`/ffmpeg probe ~/Movies/clip.mp4`
3	修剪视频片段	`/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15`
4	转码容器格式	`/ffmpeg transcode ~/Movies/clip.mov`
5	合并视频段	`/ffmpeg concat part1.mp4 part2.mp4`
6	提取音频	`/ffmpeg extract-audio ~/Movies/clip.mp4`
7	截取海报帧	`/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03`
8	生成GIF预览	`/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4`

选择序号、调度表中的模式，或粘贴文件路径并描述编辑需求。

Skill Awareness

技能适用范围

Signal	Redirect
"generate an image", "txt2img", "AI video", local Draw Things	`draw-thing`
"design a landing page", "Figma", "React layout"	`design`
"download from YouTube/URL"	`yt-dlp`
Live streaming, RTMP, OBS wiring	out of scope — suggest streaming docs

需求信号	引导至
"生成图像"、"txt2img"、"AI视频"、本地Draw Things	`draw-thing`
"设计落地页"、"Figma"、"React布局"	`design`
"从YouTube/URL下载"	`yt-dlp`
直播、RTMP、OBS配置	超出范围 — 建议查看流媒体文档

Reference Files

参考文件

File	Load when
`references/safety.md`	Any mutation; in-place overwrite questions
`references/probe-fields.md`	Interpreting probe JSON
`references/recipes-trim-transcode.md`	trim, transcode, concat, extract-audio
`references/recipes-thumbnail-gif.md`	thumbnail, gif

文件	加载场景
`references/safety.md`	任何修改操作；原地覆盖相关问题
`references/probe-fields.md`	解读探测JSON结果
`references/recipes-trim-transcode.md`	修剪、转码、拼接、音频提取
`references/recipes-thumbnail-gif.md`	缩略图截取、GIF生成

Scripts

脚本工具

Script	Purpose
`scripts/doctor.py`	Verify ffmpeg/ffprobe on PATH ( `--format json` )
`scripts/probe_media.py`	ffprobe wrapper with summary ( `--raw` for full payload)
`scripts/check.py`	Validate SKILL.md, evals, package dry-run, audit

Validation:

bash

uv run python scripts/check.py

脚本	用途
`scripts/doctor.py`	验证PATH中的ffmpeg/ffprobe（ `--format json` 参数）
`scripts/probe_media.py`	ffprobe包装工具，生成汇总信息（ `--raw` 参数获取完整数据）
`scripts/check.py`	验证SKILL.md、评估、包预运行、审计

验证命令：

bash

uv run python scripts/check.py

Reporting Template

结果报告模板

After any mutation, report:

Doctor status (if run this session)
Probe summary (duration, codecs, streams)
Recipe name (copy vs re-encode)
Exact ffmpeg command(s) executed
Output path(s) and size change
Caveats (keyframe trim, missing audio, GIF duration cap)

执行任何修改操作后，需报告：

本次会话的环境检查状态
文件探测汇总（时长、编码格式、流信息）
使用的方案名称（复制或重新编码）
执行的完整ffmpeg命令
输出路径及文件大小变化
注意事项（关键帧修剪、缺失音频、GIF时长限制）