Imported from zhangdszq/vk-skills (ffmpeg-usage/SKILL.md). Install upstream with npx skills add zhangdszq/vk-skills --skill ffmpeg-usage. Copyright stays with the author.

ffmpeg 使用指南

概述

本技能提供基于 ffmpeg 的全面音视频处理能力，包括经过实战验证的命令和工作流，适用于常见多媒体任务、平台特定优化，以及质量与文件大小管理的最佳实践。

版本： 1.0.0 要求： ffmpeg >= 4.0，ffprobe（可选但推荐）

当用户提及视频或音频处理任务、格式转换、社交媒体优化或多媒体编辑时，Claude 应使用本技能。

适用场景

当用户需要以下操作时使用本技能：

• 视频格式转换（MP4、WebM、MOV 等）
• 分辨率缩放或宽高比调整
• 从视频创建 GIF
• 音频提取或格式转换
• 视频编辑（裁剪、合并、变速、旋转）
• 字幕处理（硬字幕、软字幕、提取字幕）
• 视频压缩或优化
• 平台特定格式化（YouTube、Instagram、TikTok、Twitter）
• 缩略图或帧提取
• 批量处理音视频文件

前置条件

使用本技能前，请确保已安装 ffmpeg：

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows（使用 Chocolatey）
choco install ffmpeg

验证安装：

ffmpeg -version

支持的操作

1. 格式转换

在不同视频格式之间转换，并使用优化设置。

MP4 转 WebM：

ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm

MOV 转 MP4：

ffmpeg -i input.mov -c:v libx264 -c:a aac -strict experimental output.mp4

任意格式转 MP4（通用兼容）：

ffmpeg -i input.* -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k output.mp4

2. 分辨率调整

调整视频尺寸同时保持宽高比。

缩放到 720p：

ffmpeg -i input.mp4 -vf scale=-1:720 -c:a copy output_720p.mp4

缩放到 1080p：

ffmpeg -i input.mp4 -vf scale=-1:1080 -c:a copy output_1080p.mp4

缩放到指定宽度（高度自适应）：

ffmpeg -i input.mp4 -vf scale=1280:-1 -c:a copy output.mp4

带填充缩放（黑边填充/信箱模式）：

ffmpeg -i input.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" output.mp4

3. GIF 制作

从视频创建高质量 GIF，并优化文件大小。

基本 GIF（10 帧/秒）：

ffmpeg -i input.mp4 -vf "fps=10,scale=480:-1:flags=lanczos" output.gif

高质量 GIF（使用调色板）：

# 生成调色板
ffmpeg -i input.mp4 -vf "fps=10,scale=480:-1:flags=lanczos,palettegen" palette.png

# 使用调色板创建 GIF
ffmpeg -i input.mp4 -i palette.png -filter_complex "fps=10,scale=480:-1:flags=lanczos[x];[x][1:v]paletteuse" output.gif

从指定时间范围创建 GIF：

ffmpeg -ss 00:00:10 -t 5 -i input.mp4 -vf "fps=10,scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" output.gif

4. 音频操作

提取、转换和处理音频流。

提取音频为 MP3：

ffmpeg -i input.mp4 -vn -acodec libmp3lame -q:a 2 output.mp3

提取音频为 WAV：

ffmpeg -i input.mp4 -vn -acodec pcm_s16le -ar 44100 -ac 2 output.wav

转换音频格式：

ffmpeg -i input.wav -c:a aac -b:a 192k output.m4a

添加背景音乐：

ffmpeg -i video.mp4 -i music.mp3 -c:v copy -c:a aac -map 0:v:0 -map 1:a:0 -shortest output.mp4

混合音频（叠加）：

ffmpeg -i video.mp4 -i music.mp3 -filter_complex "[0:a][1:a]amix=inputs=2:duration=first" -c:v copy output.mp4

5. 视频编辑

裁剪、拼接和修改视频。

裁剪视频：

# 从第 10 秒到第 30 秒
ffmpeg -i input.mp4 -ss 00:00:10 -to 00:00:30 -c copy output.mp4

# 基于时长（从第 5 秒开始，截取 10 秒）
ffmpeg -i input.mp4 -ss 00:00:05 -t 10 -c copy output.mp4

拼接视频：

根据格式和兼容性选择方法：

方法一：Concat 协议（推荐——无需临时文件）

# 适用于 MPEG 格式：.ts、.mpg、.mpeg、.mp3、.aac 等
# 直接拼接，无需创建列表文件
ffmpeg -i "concat:file1.mp3|file2.mp3|file3.mp3" -c copy output.mp3
ffmpeg -i "concat:video1.ts|video2.ts|video3.ts" -c copy output.ts

# 支持格式：TS、MPEG-1、MPEG-2、MP3、AAC
# 不支持：MP4、MOV、MKV（请使用方法二）

方法二：Concat 分离器（适用于 MP4、MOV、MKV）

# 使用进程替换避免临时文件
ffmpeg -f concat -safe 0 -i <(printf "file '%s'\n" video1.mp4 video2.mp4 video3.mp4) -c copy output.mp4

# 如果 shell 不支持进程替换：
printf "file '%s'\n" video1.mp4 video2.mp4 video3.mp4 > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4
rm list.txt

方法三：Concat 滤镜（可接受重新编码时使用）

# 当视频编码/分辨率不同时使用
ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 \
  -filter_complex "[0:v][0:a][1:v][1:a][2:v][2:a]concat=n=3:v=1:a=1[v][a]" \
  -map "[v]" -map "[a]" output.mp4

格式选择指南：

• .mp3、.aac、.ts、.mpg、.mpeg → 使用 concat 协议（方法一）
• .mp4、.mov、.mkv → 使用 concat 分离器（方法二）
• 不同编码/分辨率 → 使用 concat 滤镜（方法三）

加速/减速：

# 2 倍速
ffmpeg -i input.mp4 -filter:v "setpts=0.5*PTS" -an output.mp4

# 0.5 倍速（慢动作）
ffmpeg -i input.mp4 -filter:v "setpts=2.0*PTS" output.mp4

旋转视频：

# 顺时针旋转 90 度
ffmpeg -i input.mp4 -vf "transpose=1" output.mp4

# 旋转 180 度
ffmpeg -i input.mp4 -vf "transpose=2,transpose=2" output.mp4

6. 字幕处理

添加、提取或烧录字幕。

烧录字幕到视频（硬字幕）：

ffmpeg -i input.mp4 -vf subtitles=subtitles.srt output.mp4

添加软字幕：

ffmpeg -i input.mp4 -i subtitles.srt -c copy -c:s mov_text output.mp4

提取字幕：

ffmpeg -i input.mp4 -map 0:s:0 subtitles.srt

7. 缩略图提取

从视频中提取帧作为图片。

在指定时间提取单帧：

ffmpeg -i input.mp4 -ss 00:00:05 -vframes 1 thumbnail.jpg

提取多张缩略图：

# 每 10 秒提取一帧
ffmpeg -i input.mp4 -vf fps=1/10 thumb%04d.jpg

# 提取前 10 帧
ffmpeg -i input.mp4 -vframes 10 frame%04d.png

8. 压缩与优化

在保持质量的同时减小文件大小。

视频压缩（均衡模式）：

ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k output.mp4

高压缩（更小文件）：

ffmpeg -i input.mp4 -c:v libx264 -crf 28 -preset veryslow -c:a aac -b:a 96k output.mp4

Web 优化压缩：

ffmpeg -i input.mp4 -c:v libx264 -preset medium -crf 23 -movflags +faststart -c:a aac -b:a 128k output.mp4

平台特定预设

YouTube 优化

ffmpeg -i input.mp4 \
  -c:v libx264 -preset slow -crf 18 \
  -c:a aac -b:a 192k \
  -pix_fmt yuv420p \
  -movflags +faststart \
  youtube.mp4

Instagram 快拍（9:16）

ffmpeg -i input.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -preset medium -crf 23 \
  -c:a aac -b:a 128k \
  -t 15 \
  instagram_story.mp4

Twitter/X（16:9，最长 2 分 20 秒）

ffmpeg -i input.mp4 \
  -vf scale=1280:720 \
  -c:v libx264 -preset medium -crf 23 \
  -c:a aac -b:a 128k \
  -t 140 \
  twitter.mp4

TikTok（9:16）

ffmpeg -i input.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -preset medium -crf 23 \
  -c:a aac -b:a 128k \
  -t 60 \
  tiktok.mp4

常见用例

屏幕录制优化

# 减小屏幕录制文件大小
ffmpeg -i screen_recording.mov \
  -c:v libx264 -preset medium -crf 23 \
  -vf "scale=1920:-1" \
  -c:a aac -b:a 128k \
  optimized.mp4

批量转换

# 将所有 MOV 文件转换为 MP4
for i in *.mov; do
  ffmpeg -i "$i" -c:v libx264 -crf 23 -c:a aac "${i%.mov}.mp4"
done

从图片创建视频

# 从图片序列创建
ffmpeg -framerate 30 -pattern_type glob -i '*.jpg' \
  -c:v libx264 -pix_fmt yuv420p \
  output.mp4

# 单张图片转视频（5 秒）
ffmpeg -loop 1 -i image.jpg -c:v libx264 -t 5 -pix_fmt yuv420p output.mp4

最佳实践

1. 始终先检查输入文件：

   ffmpeg -i input.mp4
   # 或使用 ffprobe 获取详细信息
   ffprobe -v quiet -print_format json -show_format -show_streams input.mp4

2. 尽可能使用 -c copy 避免重新编码：

   ffmpeg -i input.mp4 -ss 00:01:00 -t 30 -c copy output.mp4

3. 处理前用 -t 参数预览效果：

   # 先测试前 10 秒
   ffmpeg -i input.mp4 -t 10 [其他参数] test.mp4

4. 使用合适的 CRF 值：

   • 18 = 视觉无损
   • 23 = 高质量（默认值）
   • 28 = 可接受质量，文件更小
   • 范围：0（无损）到 51（最差质量）

5. 为 Web 视频添加 -movflags +faststart：

   • 启用渐进式播放
   • 将元数据移至文件开头

错误处理

使用本技能时，请始终：

1. 验证输入文件存在且可读
2. 处理前检查 ffmpeg 是否已安装
3. 验证输出路径可写
4. 使用适当的提示信息优雅处理错误
5. 处理大文件时显示进度

Claude 使用指南

当用户请求音视频处理时：

1. 识别任务类型
2. 从本技能中选择合适的命令
3. 验证前置条件（ffmpeg 已安装、输入文件存在）
4. 执行前说明命令的作用
5. 执行命令并进行错误处理
6. 验证输出是否成功创建
7. 提供优化建议（如适用）

对于复杂工作流，应分步骤执行并逐一说明。

视频拼接注意事项： 尽可能使用 printf 配合进程替换来避免临时文件（参见拼接部分的方法二）。仅在必要时使用临时 list.txt 文件。

示例

用户："把这个 MOV 文件转成 MP4" 响应： 使用 H.264 编码的 MOV 转 MP4 命令

用户："从这个视频做一个 GIF，从第 10 秒开始只要 5 秒" 响应： 使用带时间范围的 GIF 创建命令

用户："我需要把这个 4K 视频缩小到 1080p 用于网页" 响应： 结合分辨率缩放和 Web 优化预设

用户："提取音频为 MP3" 响应： 使用 MP3 编码的音频提取命令

参考资料

• FFmpeg 官方文档：https://ffmpeg.org/documentation.html
• FFmpeg Wiki：https://trac.ffmpeg.org/wiki
• 支持的编解码器：https://ffmpeg.org/ffmpeg-codecs.html
• 滤镜文档：https://ffmpeg.org/ffmpeg-filters.html

文案提取和转录功能，当涉及到转录和文案提取功能的时候，参考下面文档：

Voice Model API (本地语音转录)

应用启动后自动在 http://127.0.0.1:18923 开启本地 HTTP 接口，供 Claude Skill 等外部调用方使用。

接口列表

1. 查询模型状态

GET /v1/audio/models/status

响应示例：

{
  "installed": true,
  "modelDir": "/Users/xxx/.newmax/models/sensevoice-small",
  "modelSize": 239549735
}

{
  "installed": false,
  "modelDir": "/Users/xxx/.newmax/models/sensevoice-small",
  "missingFiles": ["model.int8.onnx", "tokens.txt"]
}

2. 音频转录

POST /v1/audio/transcriptions
Content-Type: application/json

请求参数：

请求示例：

{
  "audioPath": "/Users/xxx/Downloads/interview.mp3",
  "language": "zh"
}

成功响应（200）：

{
  "success": true,
  "text": "第一段转录文字\n第二段转录文字\n第三段转录文字"
}

失败响应（400/500）：

{
  "success": false,
  "error": "模型未安装，请先下载模型"
}

使用说明

• 端口固定为 18923，仅监听 127.0.0.1（本机访问）
• 支持格式：WAV / MP3 / FLAC / M4A / OGG / AAC（非 WAV 格式需系统安装 ffmpeg）
• 长音频自动按 30 秒分段转录，结果以换行符拼接
• 模型需在设置 → 语音模型中先下载（约 239 MB），否则转录接口会返回未安装错误
• 使用 SenseVoice Small 模型，支持中英日韩粤等 50+ 语种

curl 快速测试

# 检查模型是否已安装
curl http://127.0.0.1:18923/v1/audio/models/status

# 转录音频文件
curl -X POST http://127.0.0.1:18923/v1/audio/transcriptions \
  -H 'Content-Type: application/json' \
  -d '{"audioPath": "/path/to/audio.mp3"}'

在 Claude Skill 中调用

# 在 skill 脚本中调用转录 API
result=$(curl -s -X POST http://127.0.0.1:18923/v1/audio/transcriptions \
  -H 'Content-Type: application/json' \
  -d "{\"audioPath\": \"$AUDIO_FILE\"}")

echo "$result" | jq -r '.text'