video-edit

视频编辑工具包

目标

完整的视频制作流程：删除静音、自动生成字幕、竖屏裁剪、剪辑 YouTube 视频、压缩和添加 3D 转场。

脚本（共 7 个）

脚本	用途
jump_cut_vad_singlepass.py	使用神经 VAD（Silero）删除静音
auto_captions.py	生成并烧录样式化字幕（Whisper + FFmpeg）
vertical_crop.py	使用人脸追踪自动将 16:9 裁剪为 9:16
youtube_clip.py	下载 YouTube 视频并使用 AI 按章节剪辑
compress_video.py	使用平台预设压缩视频，以适配社交媒体
simple_video_edit.py	完整流程：删除静音、转录、添加元数据并上传
insert_3d_transition.py	插入 3D 旋转预告片

---

快速入门方案

方案 1：完整社交媒体流程

# 1. Remove silences
python3 ./scripts/jump_cut_vad_singlepass.py input.mp4 .tmp/edited.mp4

# 2. Add captions
python3 ./scripts/auto_captions.py .tmp/edited.mp4 .tmp/captioned.mp4 --word-level --max-words 2

# 3. Crop to vertical for Shorts/Reels
python3 ./scripts/vertical_crop.py .tmp/captioned.mp4 .tmp/vertical.mp4

# 4. Compress for platform
python3 ./scripts/compress_video.py .tmp/vertical.mp4 output.mp4 --preset instagram-reel

方案 2：YouTube → Shorts 流程

# 1. Download + auto-clip YouTube video
python3 ./scripts/youtube_clip.py "https://youtube.com/watch?v=..." --auto-clip --output-dir clips/

# 2. Add captions to best clip
python3 ./scripts/auto_captions.py clips/chapters/01_intro.mp4 .tmp/captioned.mp4 --word-level

# 3. Crop to vertical
python3 ./scripts/vertical_crop.py .tmp/captioned.mp4 .tmp/vertical.mp4

# 4. Compress for YouTube Shorts
python3 ./scripts/compress_video.py .tmp/vertical.mp4 short.mp4 --preset youtube-shorts

方案 3：快速编辑并上传

# All-in-one: silence removal + transcription + metadata + Auphonic upload
python3 ./scripts/simple_video_edit.py --video input.mp4 --title "My Video"

---

脚本 1：VAD 静音移除

文件： ./scripts/jump_cut_vad_singlepass.py

工作原理

1. 将音频提取为 WAV（16kHz 单声道）
2. 运行 Silero VAD 检测语音片段
3. 合并间隔较短的片段，并添加留白
4. 使用 FFmpeg trim+concat 一次性拼接片段
5. 使用 hevc_videotoolbox 进行硬件编码（H.265，17Mbps，30fps）

CLI 参数

参数	默认值	说明
--min-silence	0.5	要剪掉的最短静音时长（秒）
--min-speech	0.25	保留的最短语音时长（秒）
--padding	100	语音周围的留白（毫秒）
--merge-gap	0.3	合并间隔小于此值的片段（秒）
--keep-start	true	始终从 0:00 开始

用法

python3 ./scripts/jump_cut_vad_singlepass.py input.mp4 output.mp4
python3 ./scripts/jump_cut_vad_singlepass.py input.mp4 output.mp4 --min-silence 1.0 --padding 200

处理时间

处理一段 49 分钟的 4K 视频约需 8 分钟

---

脚本 2：自动生成字幕

文件： ./scripts/auto_captions.py

工作原理

1. 使用 faster-whisper 转录视频（词级时间戳）
2. 生成 SRT 字幕（片段级或词级）
3. 使用 FFmpeg 将样式化字幕烧录到视频中

CLI 参数

参数	默认值	说明
--model	base	Whisper 模型：tiny、base、small、medium、large-v3
--language	auto	指定语言（en、es、hi 等）
--word-level	false	简短有力的字幕（每次显示 1-3 个词）
--max-words	3	词级模式下每条字幕的最大词数
--font-size	22	字幕字体大小（竖屏视频会自动缩放）
--font-color	white	文字颜色：white、yellow、cyan、green、red、orange、pink
--outline-color	black	描边颜色
--position	bottom	字幕位置：bottom、top、middle
--srt-only	false	仅生成 SRT，不烧录字幕
--srt-path	auto	自定义 SRT 输出路径
--bold	true	加粗文字

用法

# Basic captions
python3 ./scripts/auto_captions.py input.mp4 output.mp4

# Word-level (CapCut/Submagic style)
python3 ./scripts/auto_captions.py input.mp4 output.mp4 --word-level --max-words 2

# Yellow captions at top
python3 ./scripts/auto_captions.py input.mp4 output.mp4 --font-color yellow --position top

# SRT only (no burn)
python3 ./scripts/auto_captions.py input.mp4 --srt-only

# High accuracy
python3 ./scripts/auto_captions.py input.mp4 output.mp4 --model large-v3

依赖项

pip install faster-whisper

---

脚本 3：竖屏裁剪

文件： ./scripts/vertical_crop.py

工作原理

1. 对视频全程进行抽帧
2. 使用 OpenCV Haar 级联检测人脸
3. 平滑人脸位置，避免抖动
4. 将 16:9 裁剪为 9:16，并以说话者为中心
5. 对于移动主体：将视频切分为 2 秒片段，并逐段追踪

CLI 参数

参数	默认值	说明
--ratio	9:16	目标宽高比（例如 9:16、4:5、1:1）
--position	auto	裁剪位置：auto（人脸追踪）、left、center、right
--smoothing	30	平滑窗口的帧数
--sample-interval	5	每隔 N 帧抽样进行检测

用法

# Auto face-tracking crop
python3 ./scripts/vertical_crop.py input.mp4 output.mp4

# Square crop (Instagram post)
python3 ./scripts/vertical_crop.py input.mp4 output.mp4 --ratio 1:1

# 4:5 crop (Instagram feed)
python3 ./scripts/vertical_crop.py input.mp4 output.mp4 --ratio 4:5

# Center crop (no tracking)
python3 ./scripts/vertical_crop.py input.mp4 output.mp4 --position center

依赖项

pip install opencv-python numpy

---

脚本 4：YouTube 剪辑

文件： ./scripts/youtube_clip.py

工作原理

1. 通过 yt-dlp 下载视频（最高 4K）
2. 如果有 YouTube 章节信息，则提取章节
3. 如果没有，则使用 AI 生成章节（Whisper + Claude）
4. 将视频剪辑为单独的章节文件

CLI 参数

参数	默认值	描述
--download-only	false	仅下载，不剪辑
--max-quality	1080	最高画质：480、720、1080、1440、2160
--audio-only	false	仅下载音频（MP3）
--start	none	手动设置片段起始时间（秒）
--end	none	手动设置片段结束时间（秒）
--auto-clip	false	AI 驱动的章节检测与剪辑
--use-yt-chapters	true	如果有 YouTube 章节，则使用
--max-clips	none	限制片段数量
--whisper-model	base	用于转录的 Whisper 模型
--reencode	false	重新编码片段（精确剪切）
--output-dir	.tmp/clips	输出目录

用法

# Download only
python3 ./scripts/youtube_clip.py "https://youtube.com/watch?v=..." --download-only

# Auto-clip into chapters
python3 ./scripts/youtube_clip.py "https://youtube.com/watch?v=..." --auto-clip

# Extract specific range
python3 ./scripts/youtube_clip.py "https://youtube.com/watch?v=..." --start 60 --end 180 -o clip.mp4

# Download audio only
python3 ./scripts/youtube_clip.py "https://youtube.com/watch?v=..." --audio-only

# Top 3 clips only
python3 ./scripts/youtube_clip.py "https://youtube.com/watch?v=..." --auto-clip --max-clips 3

依赖项

pip install yt-dlp faster-whisper anthropic

---

脚本 5：视频压缩器

文件： ./scripts/compress_video.py

平台预设

预设	分辨率	CRF	最长时长	最大大小	备注
youtube	1080p	18	none	none	高画质
youtube-shorts	1080x1920	20	60s	none	竖屏
instagram-reel	1080x1920	23	90s	none	竖屏
instagram-post	1080x1080	23	60s	none	方形／竖屏
tiktok	1080x1920	23	180s	none	竖屏
twitter	1080p	23	140s	512MB	自动码率
linkedin	1080p	23	600s	200MB	自动码率
telegram	720p	28	none	50MB	用于机器人
whatsapp	720p	28	120s	16MB	高强度压缩
small	480p	30	none	none	快速分享

CLI 参数

参数	默认值	描述
--preset	none	平台预设（见上表）
--resolution	1080	最大高度（像素）
--crf	23	画质（0=无损，51=最差）
--audio-bitrate	128k	音频码率
--target-size	none	目标文件大小（MB）
--max-duration	none	最长时长（秒）
--list-presets	false	显示所有预设

用法

# Platform preset
python3 ./scripts/compress_video.py input.mp4 output.mp4 --preset instagram-reel
python3 ./scripts/compress_video.py input.mp4 output.mp4 --preset whatsapp

# Target file size
python3 ./scripts/compress_video.py input.mp4 output.mp4 --target-size 25

# Custom
python3 ./scripts/compress_video.py input.mp4 output.mp4 --resolution 720 --crf 28

# List all presets
python3 ./scripts/compress_video.py input.mp4 output.mp4 --list-presets

---

脚本 6：简单视频编辑（完整流程）

文件： ./scripts/simple_video_edit.py

工作原理

1. 使用 FFmpeg 检测静音并剪切
2. 音频标准化（loudnorm）
3. 使用 Whisper 转录
4. Claude 生成 YouTube 元数据（摘要和章节）
5. 上传至 Auphonic → YouTube（私密草稿）

CLI 参数

参数	默认值	描述
--video	required	输入视频路径
--title	required	YouTube 标题
--thumbnail	none	缩略图路径
--no-upload	false	跳过 Auphonic 上传
--no-normalize	false	跳过音频标准化
--upload-only	false	跳过编辑，仅上传
--silence-threshold	-35	静音阈值（dB）
--silence-duration	3.0	最短静音时长（秒）

用法

# Full pipeline
python3 ./scripts/simple_video_edit.py --video input.mp4 --title "My Video"

# Local only
python3 ./scripts/simple_video_edit.py --video input.mp4 --title "Test" --no-upload

依赖项

pip install anthropic faster-whisper requests python-dotenv
# Requires: ANTHROPIC_API_KEY, AUPHONIC_API_KEY in .env

---

脚本 7：3D 旋转预告片

文件： ./scripts/insert_3d_transition.py

工作原理

1. 从视频后段提取帧（默认：从 60s 开始）
2. 通过 Remotion 创建 3D 旋转“转轴”动画
3. 分割视频：片头 → 转场 → 主要内容
4. 重新编码并拼接，同时保留音频

CLI 参数

参数	默认值	描述
--insert-at	3	插入预告片的位置（秒）
--duration	5	预告片时长（秒）
--teaser-start	60	内容采样起始位置（秒）
--bg-color	#2d3436	背景颜色（十六进制）
--bg-image	none	背景图片路径

最终时间线

[0-3s intro] [3-8s swivel teaser @ 100x] [8s onwards: edited content]
Audio: Original audio plays continuously

依赖项

pip install torch  # For Silero VAD (jump_cut script)
brew install ffmpeg node  # macOS
cd video_effects && npm install  # For Remotion 3D rendering

---

所有依赖项（仅需安装一次）

# Core (required for all scripts)
brew install ffmpeg

# Silence removal
pip install torch

# Auto-captions + YouTube clip
pip install faster-whisper

# Vertical crop
pip install opencv-python numpy

# YouTube download
pip install yt-dlp

# AI features (chapters, metadata)
pip install anthropic

# Full pipeline (simple_video_edit)
pip install requests python-dotenv

# 3D transitions
brew install node
cd scripts/video_effects && npm install

---

故障排查

问题	解决方案
剪辑衔接显得突兀	在 jump_cut 中使用 --padding 200
剪切过多	在 jump_cut 中使用 --min-silence 1.0
字幕太小	在 auto_captions 中使用 --font-size 32
检测到竖屏视频	字体会自动缩放 1.3 倍
无法在 QuickTime 中播放	确保使用 hvc1 编解码器标记
未检测到人脸	在 vertical_crop 中尝试 --position center
YouTube 下载失败	更新 yt-dlp：pip install -U yt-dlp
文件过大	使用 --preset whatsapp 或 --target-size 25
硬件编码器失败	自动回退到软件编码（libx264）

技术详情

• macOS：硬件编码（hevc_videotoolbox / h264_videotoolbox）
• 回退方案：使用 CRF 的 libx264/libx265
• 音频：AAC 128-192kbps
• 使用 hvc1 编解码器标记以兼容 QuickTime
• 所有脚本均支持通过 --help 查看完整参数列表

---

架构

输入

名称	类型	必填	描述
input_video	file_path	是	输入视频文件路径
recipe	string	否	流水线配方：full-social、youtube-shorts、quick-edit
preset	string	否	压缩预设：youtube、instagram-reel、tiktok、whatsapp 等

输出

名称	类型	描述
output_video	file_path	处理后的视频文件路径

凭据

名称	来源
ANTHROPIC_API_KEY	.env（用于 AI 章节）
AUPHONIC_API_KEY	.env（用于上传）

可组合使用

与此工具搭配效果良好的技能：pan-3d-transition、recreate-thumbnails

费用

本地免费（FFmpeg + Silero VAD）