claude-video-edit

claude-video-edit — 视频编辑操作

预检

每次执行写入文件的操作之前：

1. 运行 bash scripts/preflight.sh "$INPUT" "$OUTPUT"
2. 如果失败，停止操作并向用户报告错误
3. 对于编码操作，运行 bash scripts/detect_gpu.sh 以选择编码器

操作

剪辑

无损剪辑（对齐关键帧、即时完成、不重新编码）：

ffmpeg -n -ss HH:MM:SS -i "$INPUT" -t DURATION -c copy "$OUTPUT"

注意：将 -ss 放在 -i 之前，以便快速定位。时长可用秒数或 HH:MM:SS 表示。

精确到帧的剪辑（重新编码，可精确到任意帧）：

ffmpeg -n -i "$INPUT" -ss HH:MM:SS -t DURATION -c:v libx264 -crf 20 -c:a aac "$OUTPUT"

注意：将 -ss 放在 -i 之后，以确保精确到帧。需要精确剪辑时使用。

移除开头／结尾的 N 秒：

• 移除开头 10s：-ss 10 -c copy
• 移除结尾 10s：使用 ffprobe 获取时长，然后剪辑到 duration - 10

拆分

在指定时间点拆分：

ffmpeg -n -i "$INPUT" -t 60 -c copy part1.mp4
ffmpeg -n -i "$INPUT" -ss 60 -c copy part2.mp4

拆分为等长片段：

ffmpeg -n -i "$INPUT" -f segment -segment_time 300 -c copy -reset_timestamps 1 "segment_%03d.mp4"

按场景边界拆分（有关 PySceneDetect，请加载 references/analyze.md）：

scenedetect -i "$INPUT" detect-adaptive -t 3.0 split-video

拼接

相同编码格式（不重新编码）：

printf "file '%s'\n" file1.mp4 file2.mp4 file3.mp4 > /tmp/concat_list.txt
ffmpeg -n -f concat -safe 0 -i /tmp/concat_list.txt -c copy "$OUTPUT"
rm /tmp/concat_list.txt

不同编码格式（重新编码）：

ffmpeg -n -i file1.mp4 -i file2.mp4 -filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1" "$OUTPUT"

变速

加速 2 倍（带音频音高校正）：

ffmpeg -n -i "$INPUT" -vf "setpts=0.5*PTS" -af "atempo=2.0" "$OUTPUT"

减速至 0.5 倍：

ffmpeg -n -i "$INPUT" -vf "setpts=2.0*PTS" -af "atempo=0.5" "$OUTPUT"

变速倍数：对于 atempo，有效范围为 0.5–100.0。大幅变速时可串联使用：atempo=2.0,atempo=2.0 = 4 倍速。

帧插值慢动作（AI 生成中间帧）：

ffmpeg -n -i "$INPUT" -vf "minterpolate=fps=60:mi_mode=mci:mc_mode=aobmc:vsbmc=1" "$OUTPUT"

警告：速度很慢（约为实时速度的 0.05 倍）。适用于较短的视频片段。

裁剪、缩放、旋转

裁剪（宽度:高度:x:y）：

ffmpeg -n -i "$INPUT" -vf "crop=640:480:100:50" "$OUTPUT"

缩放（保持宽高比，尺寸为偶数）：

ffmpeg -n -i "$INPUT" -vf "scale=1280:-2:flags=lanczos" "$OUTPUT"

缩放到精确尺寸并添加填充（信箱模式）：

ffmpeg -n -i "$INPUT" -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black" "$OUTPUT"

顺时针旋转 90°：-vf "transpose=1" 逆时针旋转 90°：-vf "transpose=2" 旋转 180°：-vf "transpose=1,transpose=1" 任意角度：-vf "rotate=PI/6:fillcolor=black" 翻转 水平：-vf "hflip" | 垂直：-vf "vflip"

叠加层和水印

图像水印（右下角，边距 10px）：

ffmpeg -n -i "$INPUT" -i logo.png -filter_complex "overlay=W-w-10:H-h-10" "$OUTPUT"

画中画（在角落显示小尺寸视频）：

ffmpeg -n -i "$INPUT" -i pip.mp4 -filter_complex "[1:v]scale=320:180[pip];[0:v][pip]overlay=10:10" "$OUTPUT"

文本叠加层：

ffmpeg -n -i "$INPUT" -vf "drawtext=text='My Title':fontsize=48:fontcolor=white:x=(w-tw)/2:y=50:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf:box=1:[email protected]:boxborderw=8" "$OUTPUT"

定时显示文本（在 5s 到 15s 之间显示）：

-vf "drawtext=text='Hello':enable='between(t,5,15)':fontsize=36:fontcolor=white:x=10:y=10"

绿幕（色度键）

ffmpeg -n -i greenscreen.mp4 -i background.mp4 -filter_complex \
  "[0:v]chromakey=0x00FF00:0.1:0.2[fg];[1:v][fg]overlay" "$OUTPUT"

调整颜色十六进制值、相似度（0.1）和混合度（0.2），以获得最佳效果。

视频稳定

使用 vidstab 的两遍处理流程：

# Pass 1: Analyze motion
ffmpeg -i "$INPUT" -vf vidstabdetect=shakiness=5:accuracy=15:result=/tmp/transforms.trf -f null -

# Pass 2: Apply stabilization + sharpening
ffmpeg -n -i "$INPUT" -vf "vidstabtransform=smoothing=10:input=/tmp/transforms.trf,unsharp=5:5:0.8:5:5:0.3" "$OUTPUT"

rm /tmp/transforms.trf

shakiness 的范围为 1-10（源视频的抖动程度），smoothing 表示平滑度（值越大，摄像机画面越平稳，但可能裁掉边缘）。

转场

两个视频片段之间交叉淡化（有 44 种以上转场类型可用）：

ffmpeg -n -i first.mp4 -i second.mp4 -filter_complex \
  "xfade=transition=fade:duration=2:offset=5" "$OUTPUT"

可用的 xfade 转场：fade、dissolve、wipeleft、wiperight、wipeup、wipedown、slideleft、slideright、slideup、slidedown、circlecrop、rectcrop、distance、fadeblack、fadewhite、radial、smoothleft、smoothright、smoothup、smoothdown、circleopen、circleclose、vertopen、vertclose、horzopen、horzclose、diagtl、diagtr、diagbl、diagbr、hlslice、hrslice、vuslice、vdslice、pixelize、squeezeh、squeezev、zoomin、fadegrays、wipetl、wipetr、wipebl、wipebr、coverleft、coverright、coverup、coverdown、revealleft、revealright、revealup、revealdown。

淡入／淡出：

# Fade in first 2 seconds
ffmpeg -n -i "$INPUT" -vf "fade=t=in:st=0:d=2" -af "afade=t=in:st=0:d=2" "$OUTPUT"

# Fade out last 2 seconds (get duration first with ffprobe)
ffmpeg -n -i "$INPUT" -vf "fade=t=out:st=OFFSET:d=2" -af "afade=t=out:st=OFFSET:d=2" "$OUTPUT"

色彩校正

完整滤镜目录请加载 references/filters.md。快速参考：

• 亮度／对比度：-vf "eq=brightness=0.06:contrast=1.2:saturation=1.3"
• 色调曲线预设：-vf "curves=preset=lighter"（也包括 darker、increase_contrast、vintage 等）
• 色彩平衡：-vf "colorbalance=rs=0.3:gs=-0.1:bs=0.0"
• 3D LUT：-vf "lut3d=file=my_lut.cube"
• 灰度：-vf "colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3"
• 模糊：-vf "gblur=sigma=10"
• 锐化：-vf "unsharp=5:5:1.0:5:5:0.0"
• 降噪：-vf "hqdn3d=4:3:6:4.5"（快速）或 -vf "nlmeans=s=3.5:p=7:r=15"（质量最佳）

联系表／缩略图网格

ffmpeg -n -i "$INPUT" -vf "select=not(mod(n\,100)),scale=320:180,tile=4x4" -frames:v 1 contact_sheet.png

提取单帧

ffmpeg -n -ss 00:01:30 -i "$INPUT" -frames:v 1 -q:v 2 thumbnail.jpg

隐私模糊处理（人脸／区域遮挡）

模糊整个面部区域（静态坐标——使用 ffprobe 或 MediaPipe 查找人脸边界框）：

ffmpeg -n -i "$INPUT" -vf "delogo=x=200:y=100:w=150:h=150" "$OUTPUT"

模糊方框区域（控制更灵活）：

ffmpeg -n -i "$INPUT" -filter_complex \
  "[0:v]crop=150:150:200:100,boxblur=10[blur];[0:v][blur]overlay=200:100" "$OUTPUT"

按时间范围模糊（仅在 5s 至 15s 之间模糊）：

ffmpeg -n -i "$INPUT" -filter_complex \
  "[0:v]split[main][copy];[copy]crop=150:150:200:100,boxblur=10[blur];[main][blur]overlay=200:100:enable='between(t,5,15)'" "$OUTPUT"

模糊整个画面（用于 B-roll 背景）：

ffmpeg -n -i "$INPUT" -vf "boxblur=20:5" "$OUTPUT"

如需使用 AI 进行人脸检测并跨帧跟踪模糊处理，请使用 python3 scripts/face_tracker.py 和 MediaPipe BlazeFace（使用 CPU，无需 VRAM）。face_tracker 会输出每帧的边界框， 可用于确定叠加模糊效果的坐标。

LUT 色彩分级

应用 .cube LUT 文件：

ffmpeg -n -i "$INPUT" -vf "lut3d=file=my_grade.cube" "$OUTPUT"

应用并控制强度（在原始画面和调色后画面之间混合）：

ffmpeg -n -i "$INPUT" -filter_complex \
  "[0:v]split[a][b];[b]lut3d=file=my_grade.cube[graded];[a][graded]blend=all_mode=normal:all_opacity=0.7" "$OUTPUT"

常见 LUT 来源：从 lutify.me、filtergrade.com 等网站下载 .cube 文件，或 在 DaVinci Resolve 中创建自定义 LUT。将 LUT 文件放在项目目录旁，或使用绝对路径。

支持的格式：.cube（最常见）、.3dl、.dat、.m3d

运动跟踪文字叠加

跟随某个位置的静态文字（手动关键帧）：

ffmpeg -n -i "$INPUT" -vf "drawtext=text='Label':fontsize=24:fontcolor=white:\
x='if(lt(t,5),100+t*20,200)':y='if(lt(t,5),50+t*10,100)':\
fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf:\
box=1:[email protected]:boxborderw=4" "$OUTPUT"

使用表达式控制移动的文字（平滑正弦波）：

ffmpeg -n -i "$INPUT" -vf "drawtext=text='Moving Text':fontsize=36:fontcolor=white:\
x='w/2-tw/2+50*sin(t*2)':y='h/2-th/2+30*cos(t*2)':\
fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf" "$OUTPUT"

如需进行复杂跟踪（在视频中跟随人脸或物体），请将 scripts/face_tracker.py 输出的边界框与逐帧 drawtext 坐标结合使用。从跟踪器导出人脸中心点， 然后生成带有逐帧 x/y 表达式的 drawtext 滤镜。

输出命名约定

如果用户未指定输出名称，则根据输入文件生成：

• video.mp4 → video_trimmed.mp4、video_stabilized.mp4、video_2x.mp4 等。
• 批量处理时：video_001.mp4、video_002.mp4 等。