mcpField
F
ffmpeg-toolkit

ffmpeg-toolkit

github.com/jakenuts创意与媒体237 次安装15 周前更新
代码仓库

关于 ffmpeg-toolkit

ffmpeg-toolkit 是一份使用 FFmpeg 和 ffprobe 处理视频、音频与图像的参考技能，为需要常见媒体处理命令和导出设置的创作者与开发者提供示例。

主要功能

  1. 01转换媒体格式
  2. 02调整视频尺寸、裁剪与截取
  3. 03调整播放速度并压缩文件
  4. 04提取音频并添加淡入淡出
  5. 05叠加文字或图像并拼接片段
  6. 06检查媒体信息并批量处理

适用场景

  1. 01转换视频以便网页播放
  2. 02按目标大小或宽高比准备片段
  3. 03提取音频或生成缩略图
  4. 04批量编辑媒体文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jakenuts/agent-skills --skill ffmpeg-toolkit

安装后在 Claude Code 中输入/ffmpeg-toolkit确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

audio-processing.md
platform-export.md
reference.md
remotion.md
streaming-and-hwaccel.md

详细介绍

FFmpeg 工具包

转码

# Convert to MP4 (H.264 + AAC)
ffmpeg -i input.mov -c:v libx264 -preset medium -crf 23 \
       -c:a aac -b:a 128k output.mp4

# Convert to WebM (VP9 + Opus)
ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 \
       -c:a libopus -b:a 128k output.webm

调整尺寸

# Specific dimensions
ffmpeg -i input.mp4 -vf "scale=1920:1080" output.mp4

# Aspect-ratio preserve with padding (letterbox/pillarbox)
ffmpeg -i input.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" output.mp4

# Crop to fill (no black bars)
ffmpeg -i input.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080" output.mp4

# Scale to width, auto height
ffmpeg -i input.mp4 -vf "scale=1280:-2" output.mp4

# Scale to percentage (50%)
ffmpeg -i input.mp4 -vf "scale=iw/2:ih/2" output.mp4

修剪和剪切

# Cut from timestamp + duration (re-encode recommended for accuracy)
ffmpeg -i input.mp4 -ss 00:00:30 -t 00:00:15 -c:v libx264 -c:a aac output.mp4

# Cut from start to end timestamp
ffmpeg -i input.mp4 -ss 00:00:30 -to 00:00:45 -c:v libx264 -c:a aac output.mp4

# Stream copy (faster, but may lose frames at non-keyframe cut points)
ffmpeg -i input.mp4 -ss 00:00:30 -t 00:00:15 -c copy output.mp4

# Fast seek for large files (put -ss before -i)
ffmpeg -ss 00:10:00 -i large_video.mp4 -t 00:05:00 -c copy clip.mp4

注意： 建议在修剪时重新编码。流复制（-c copy）可能会在静默中丢弃视频，因为定位点可能与关键帧不对齐。

调整速度

# 2x speed (video and audio)
ffmpeg -i input.mp4 -filter_complex "[0:v]setpts=0.5*PTS[v];[0:a]atempo=2.0[a]" \
       -map "[v]" -map "[a]" output.mp4

# 0.5x speed (slow motion)
ffmpeg -i input.mp4 -filter_complex "[0:v]setpts=2.0*PTS[v];[0:a]atempo=0.5[a]" \
       -map "[v]" -map "[a]" output.mp4

# Video only (no audio)
ffmpeg -i input.mp4 -filter:v "setpts=0.5*PTS" -an output.mp4

# Extreme slow motion (0.25x) - chain atempo filters (each limited to 0.5-2.0)
ffmpeg -i input.mp4 -filter_complex "[0:v]setpts=4.0*PTS[v];[0:a]atempo=0.5,atempo=0.5[a]" \
       -map "[v]" -map "[a]" output.mp4

计算速度系数：

  • 将 X 秒调整为 Y 秒：speed = X / Y
  • setpts 乘数 = 1 / speed（例如，3 倍速 = setpts=0.333*PTS）
  • atempo 值 = speed（例如，3 倍速 = atempo=3.0）
  • 音频极端加速（>2 倍）：串联 atempo 滤镜，例如，4 倍速 = atempo=2.0,atempo=2.0

关于 Remotion playbackRate 与 FFmpeg 速度的选择，请参阅 remotion.md。

压缩

# Good quality, smaller file (CRF 23 is default, lower = better)
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k output.mp4

# Aggressive compression for web preview
ffmpeg -i input.mp4 -c:v libx264 -crf 28 -preset fast -c:a aac -b:a 96k output.mp4

# Target file size (e.g., ~10MB for 60s video = ~1.3Mbps)
ffmpeg -i input.mp4 -c:v libx264 -b:v 1300k -c:a aac -b:a 128k output.mp4

关于针对特定平台的文件大小目标，请参阅 platform-export.md。

提取和转换音频

# Extract to MP3
ffmpeg -i input.mp4 -vn -acodec libmp3lame -q:a 2 output.mp3

# Extract to AAC
ffmpeg -i input.mp4 -vn -acodec aac -b:a 192k output.m4a

# Extract to WAV (uncompressed)
ffmpeg -i input.mp4 -vn output.wav

# Extract audio from specific time range
ffmpeg -i video.mp4 -ss 00:01:00 -t 00:00:30 -vn audio.mp3

# M4A to MP3
ffmpeg -i input.m4a -codec:a libmp3lame -qscale:a 2 output.mp3

# Adjust volume
ffmpeg -i input.mp3 -filter:a "volume=1.5" output.mp3

裁剪

# Arbitrary crop (width:height:x:y)
ffmpeg -i input.mp4 -vf "crop=640:480:100:50" output.mp4

# Center crop to 16:9
ffmpeg -i input.mp4 -vf "crop=ih*16/9:ih" output.mp4

拼接

# Create file list
echo "file 'clip1.mp4'" > list.txt
echo "file 'clip2.mp4'" >> list.txt
echo "file 'clip3.mp4'" >> list.txt

# Concatenate (same codec/resolution)
ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4

# Concatenate with re-encoding (different sources)
ffmpeg -f concat -safe 0 -i list.txt -c:v libx264 -c:a aac output.mp4

淡入淡出

# Video fade in first 1s, fade out last 1s (adjust st= for your duration)
ffmpeg -i input.mp4 -vf "fade=t=in:st=0:d=1,fade=t=out:st=9:d=1" -c:a copy output.mp4

# Audio fade
ffmpeg -i input.mp4 -af "afade=t=in:st=0:d=1,afade=t=out:st=9:d=1" -c:v copy output.mp4

叠加和合成

# Watermark (bottom-right corner)
ffmpeg -i video.mp4 -i watermark.png \
       -filter_complex "overlay=W-w-10:H-h-10" output.mp4

# Text overlay
ffmpeg -i input.mp4 -vf "drawtext=text='Hello World':fontsize=24:fontcolor=white:x=10:y=10" output.mp4

# Picture-in-Picture
ffmpeg -i main.mp4 -i overlay.mp4 \
       -filter_complex "[1:v]scale=320:-1[pip];[0:v][pip]overlay=W-w-10:H-h-10" output.mp4

# Side by side
ffmpeg -i left.mp4 -i right.mp4 \
       -filter_complex "[0:v]scale=640:-1[l];[1:v]scale=640:-1[r];[l][r]hstack" output.mp4

缩略图和屏幕截图

# Single screenshot at timestamp
ffmpeg -i video.mp4 -ss 00:00:10 -vframes 1 thumbnail.jpg

# Best quality thumbnail
ffmpeg -i video.mp4 -ss 00:00:10 -vframes 1 -q:v 2 thumbnail.jpg

# Generate thumbnails every N seconds
ffmpeg -i video.mp4 -vf "fps=1/10" thumbnails_%03d.jpg

# Thumbnail sprite sheet
ffmpeg -i video.mp4 -vf "fps=1/5,scale=160:-1,tile=5x5" sprite.jpg

# GIF from video (simple)
ffmpeg -i input.mp4 -vf "fps=10,scale=480:-1" output.gif

# GIF from video (palette for better quality + smaller size)
ffmpeg -i input.mp4 -vf "fps=10,scale=480:-1,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" output.gif

探测（ffprobe）

# Full JSON info
ffprobe -v quiet -print_format json -show_format -show_streams input.mp4

# Duration in seconds
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 input.mp4

# Resolution
ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 input.mp4

# Codec name
ffprobe -v error -select_streams v:0 -show_entries stream=codec_name -of default=noprint_wrappers=1:nokey=1 input.mp4

# Frame count
ffprobe -v error -select_streams v:0 -count_frames -show_entries stream=nb_read_frames -of csv=p=0 input.mp4

批量处理

# Convert all MP4s to WebM
for f in *.mp4; do
    ffmpeg -i "$f" -c:v libvpx-vp9 -crf 30 -c:a libopus "${f%.mp4}.webm"
done

# Resize all images in directory
for f in *.jpg; do
    ffmpeg -i "$f" -vf "scale=1280:-1" "resized_$f"
done

# Extract audio from multiple videos
for f in *.mp4; do
    ffmpeg -i "$f" -vn -c:a mp3 -b:a 192k "${f%.mp4}.mp3"
done

常见错误

错误原因解决方法
"height not divisible by 2"尺寸为奇数添加 -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2"
视频无法在浏览器中播放缺少 Web 标志使用 -movflags faststart -pix_fmt yuv420p -c:v libx264
调整速度后音频不同步滤镜不匹配使用同时包含 setpts 和 atempo 的 filter_complex
文件过大压缩率低提高 CRF（23->28）或降低分辨率
"No such file"输入路径错误检查路径，路径中有空格时使用引号
"Invalid data"输入文件已损坏重新下载或重新录制源文件
"encoder not found"缺少编解码器安装包含完整编解码器的 FFmpeg
输出为 0 字节静默失败检查完整的 ffmpeg 输出（-v error）

质量指南

用途CRF预设备注
存档/母版18slow质量最佳，文件较大
生产20-22medium平衡性好
Web/预览23-25fast文件较小
草稿/快速处理28+veryfast编码速度快

预设范围（越快 = 文件越大，编码越快）： ultrafast > superfast > veryfast > faster > fast > medium > slow > slower > veryslow

参考资料

  • reference.md - 编解码器、滤镜和格式查询表（视频/音频滤镜、编解码器、CRF 范围、容器、输入/输出选项）
  • audio-processing.md - 高级音频处理：归一化、降噪、频率滤镜、合并音轨
  • streaming-and-hwaccel.md - HLS/DASH 流媒体和硬件加速（NVENC、VideoToolbox、QuickSync）
  • remotion.md - Remotion 集成：素材准备、速度选择、<OffthreadVideo> 说明
  • platform-export.md - 社交媒体导出优化（YouTube、Twitter/X、LinkedIn、Instagram、TikTok、Web 嵌入）

评论

支持 Markdown