Skip to content
Back to search

vlog-auto-edit

SkillWorks with Claude CodeGitHub

AI Agent自动剪辑旅行Vlog的完整工作流。从原始素材到成品视频,系统级只需ffmpeg,其余在Python venv内完成。by nyx研究所 (GitHub @znyupup · B站/小红书 @nyx研究所)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/znyupup--ai-video-editing-skill/badge.svg)](/listings/znyupup--ai-video-editing-skill)

HTML

<a href="/listings/znyupup--ai-video-editing-skill"><img src="/api/listings/znyupup--ai-video-editing-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 952 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: vlog-auto-edit
  3. description: AI Agent自动剪辑旅行Vlog的完整工作流。从原始素材到成品视频,系统级只需ffmpeg,其余在Python venv内完成。by nyx研究所 (GitHub @znyupup · B站/小红书 @nyx研究所)
  4. version: 1.1.0
  5. tags: [video-editing, vlog, ffmpeg, whisper, funasr, automation]
  6. author: nyx研究所 (https://github.com/znyupup)
  7. status: stable
  8. ---
  9. # AI Agent 自动剪辑旅行 Vlog
  10. **Author:** nyx研究所 · [GitHub](https://github.com/znyupup) · [B站 @nyx研究所](https://space.bilibili.com/4330525) · 小红书 @nyx研究所 · [X @znyupup_music](https://x.com/znyupup_music)
  11. > 把一堆手机拍的旅行素材,用AI自动剪成一个完整vlog。
  12. > 最小依赖:ffmpeg + Python(whisper或FunASR+Pillow) + 视觉API。系统级只装ffmpeg,其余pip装。
  13. ## 触发条件
  14. - 用户有一批旅行/日常视频素材,想自动剪成vlog
  15. - 用户说"帮我剪个视频"、"自动剪辑"、"vlog剪辑"
  16. ## 前置要求
  17. ### 1. 系统工具
  18. | 工具 | 用途 | 安装 |
  19. |------|------|------|
  20. | ffmpeg | 视频裁剪/编码/拼接/抽帧/音量检测 | `brew install ffmpeg` (macOS) / `apt install ffmpeg` (Linux) |
  21. | Python 3.9+ | 脚本胶水 | macOS/Linux 系统自带 |
  22. ### 2. Python依赖(先检测,已有则跳过)
  23. **先检测系统是否已安装所需包,不要无脑创建 venv:**
  24. ```bash
  25. # 检测 whisper
  26. python3 -c "import whisper; print('✅ whisper已安装:', whisper.__file__)"
  27. # 检测 Pillow
  28. python3 -c "from PIL import Image; print('✅ Pillow已安装')"
  29. ```
  30. **⚠ 重要:不要用 `2>/dev/null` 吃掉错误!要看到实际报错才能判断是真没装还是PATH问题。**
  31. **⚠ macOS 注意:** 检查系统已安装的包再决定是否需要 venv。如果系统 python3 已经能 `import whisper` 和 `from PIL import Image`,直接用就行,不要盲目创建 venv 导致找不到已有的包。
  32. **仅在检测不通过时才安装:**
  33. ```bash
  34. # 方案A: 直接装到用户环境(推荐)
  35. pip install openai-whisper Pillow
  36. # 方案B: 如果用户环境有冲突,再用 venv
  37. python3 -m venv .venv && source .venv/bin/activate
  38. pip install openai-whisper Pillow
  39. ```
  40. **⚠ 不要每个项目都新建 venv 重装一遍!whisper模型文件1.4GB,pip install也要几分钟。**
  41. **⚠ ASR引擎二选一:Whisper 或 FunASR**
  42. 本工作流支持两个ASR引擎,优先用 whisper,whisper 装不上就用 FunASR:
  43. | | Whisper (OpenAI) | FunASR (阿里达摩院) |
  44. |---|---|---|
  45. | 安装 | `pip install openai-whisper` | `pip install funasr modelscope torchaudio` |
  46. | 模型 | medium (1.4GB, 从GitHub下载) | paraformer-zh (1.05GB, 从ModelScope下载) |
  47. | 附加模型 | 无 | VAD模型 + 标点模型 (首次运行自动下载, 共~50MB) |
  48. | 中文效果 | 好 | 好(与whisper medium相当,细节略多) |
  49. | 速度 | 14s音频 ≈ 5-10s (CPU) | 14s音频 ≈ 1.9s (CPU, RTF=0.132) ⚡ |
  50. | 时间戳粒度 | 句级别 (每句话一个start/end) | 字级别 (每个字一个时间戳) |
  51. | 模型下载源 | GitHub (国内不稳定,容易失败) | ModelScope (国内极快,~15MB/s) |
  52. | 隐性依赖 | torch | torch + torchaudio (⚠ 必须额外装) |
  53. **检测已安装的ASR引擎:**
  54. ```bash
  55. python3 -c "import whisper; print('✅ whisper可用')" 2>/dev/null \
  56. || python3 -c "from funasr import AutoModel; print('✅ funasr可用')" 2>/dev/null \
  57. || echo "❌ 没有可用的ASR引擎,需要安装一个"
  58. ```
  59. **⚠ FunASR 安装注意事项:**
  60. - 必须装 torchaudio!`pip install funasr modelscope` 不会自动装 torchaudio,import 时会报 `No module named 'torchaudio'`
  61. - 正确安装命令:`pip install funasr modelscope torchaudio`
  62. - 首次运行会自动从 ModelScope 下载3个模型(ASR + VAD + 标点),总共约1.1GB,国内速度快
  63. - 模型缓存在 `~/.cache/modelscope/hub/models/iic/` 目录下
  64. - import 时会有 urllib3 的 SSL 警告(NotOpenSSLWarning),可忽略,不影响功能
  65. **标题卡方案自动选择:**
  66. ```bash
  67. ffmpeg -filters 2>&1 | grep drawtext
  68. # 有drawtext → 直接用ffmpeg,不需要Pillow
  69. # 没有 → 用Pillow生成透明PNG再overlay(macOS brew ffmpeg通常没编freetype)
  70. ```
  71. **可选(参考分析阶段用):**
  72. ```bash
  73. which yt-dlp && echo "✅ yt-dlp已安装" || pip install yt-dlp
  74. python3 -c "import scenedetect" 2>/dev/null && echo "✅ scenedetect已安装" || pip install scenedetect
  75. ```
  76. ### 3. 视觉理解模型(API)
  77. 需要一个能理解图像内容的视觉模型API,用于分析素材画面。
  78. **要求:**
  79. - 支持 OpenAI Chat Completions 格式(messages + image_url)
  80. - 支持 base64 图片输入(本地素材抽帧后编码上传)
  81. - 中文理解能力(需要描述画面内容、标注镜头类型等)
  82. **推荐模型:**
  83. | 模型 | 费用 | 说明 |
  84. |------|------|------|
  85. | 智谱 GLM-4.6V-Flash | 免费 | 注册 https://open.bigmodel.cn 即用,中文理解好 |
  86. | GPT-4o | 付费 | 效果最好 |
  87. | Qwen-VL | 付费 | 阿里云,中文好 |
  88. **调用示例:**
  89. ```python
  90. import base64, json, urllib.request
  91. API_URL = 'YOUR_VISION_API_ENDPOINT' # 替换为你的视觉模型端点
  92. API_KEY='***' # 替换为你的API Key
  93. MODEL = 'YOUR_MODEL_NAME' # 替换为你的模型名
  94. with open('frame.jpg', 'rb') as f:
  95. img_b64 = base64.b64encode(f.read()).decode()
  96. payload = {
  97. 'model': MODEL,
  98. 'messages': [{'role': 'user', 'content': [
  99. {'type': 'image_url', 'image_url': {'url': f'data:image/jpeg;base64,{img_b64}'}},
  100. {'type': 'text', 'text': '简洁描述画面内容,标注:镜头类型(远/全/中/近/特写)、拍摄手法(固定/手持/移动)、画面氛围。格式:内容|类型|手法|氛围'}
  101. ]}],
  102. 'max_tokens': 200
  103. }
  104. req = urllib.request.Request(API_URL, json.dumps(payload).encode(),
  105. {'Content-Type': 'application/json', 'Authorization': f'Bearer {API_KEY}'})
  106. with urllib.request.urlopen(req, timeout=30) as resp:
  107. result = json.loads(resp.read())
  108. print(result['choices'][0]['message']['content'])
  109. ```
  110. **⚠ 视觉API调用注意事项:**
  111. - 输入格式:ffmpeg抽帧为JPEG → base64编码 → `data:image/jpeg;base64,{b64}` 放入 image_url
  112. - 抽帧尺寸:不需要原始分辨率,缩到 720p 即可(节省上传带宽和token)
  113. - 端点区分:有些平台视觉模型和文本模型端点不同,确认用对
  114. - 限流:高峰时段容易被限流,加 retry + sleep
  115. ### 不需要的(踩过的坑)
  116. - ❌ 剪映/CapCut — v10.4+ 项目文件加密,无法程序化操作
  117. - ❌ moviepy — ffmpeg命令行已够用,多一层抽象反而不灵活
  118. - ❌ capcut-cli (GitHub) — 基于明文JSON,对加密后的新版无效
  119. - ❌ ImageMagick — Pillow已够用,不需要再装一个图像工具
  120. ## 工作流(7个阶段)
  121. ### 阶段1: 素材盘点
  122. 目标:了解你有什么素材。
  123. ```bash
  124. # 批量获取素材信息
  125. for f in footage/*.{MOV,mp4,MP4}; do
  126. echo "=== $f ==="
  127. ffprobe -v quiet -print_format json -show_format -show_streams "$f" \
  128. | python3 -c "import json,sys; d=json.load(sys.stdin); \
  129. s=d['streams'][0]; f=d['format']; \
  130. print(f\" 时长: {float(f['duration']):.1f}s\"); \
  131. print(f\" 分辨率: {s['width']}x{s['height']}\"); \
  132. print(f\" 编码: {s['codec_name']}\")"
  133. done
  134. ```
  135. 输出一份素材清单:数量、总时长、分辨率分布、拍摄时间范围。
  136. ### 阶段2: 参考研究(可选但强烈建议)
  137. 目标:建立"好vlog长什么样"的认知。不做这步直接剪,效果会很差。
  138. **步骤:**
  139. 1. 找2-3个同类型优质vlog(B站/YouTube)
  140. 2. `yt-dlp` 下载720p视频 + 音频
  141. 3. `whisper` 转录旁白(提取叙事结构)
  142. 4. `scenedetect` 检测镜头切换(统计节奏)
  143. 5. `ffmpeg` 抽关键帧 + 视觉API分析(理解画面构成)
  144. **已验证的规律:**
  145. - 镜头节奏: 平均3-4秒/镜头是黄金节奏
  146. - 内容配比: 美食40-45% + 风景30% + 人物15% + 日常15%
  147. - 镜头类型: 近景/中景为主(60-65%),全景/远景穿插(35-40%)
  148. - 叙事结构: 精彩片头 → 出发/到达 → 按地点串联 → 情感升华收尾
  149. - 长短交替: 短镜头(<2s)做蒙太奇,长镜头(>8s)做叙事
  150. **剪辑教程要点:**
  151. 1. 找侧重点,不要流水账
  152. 2. 三幕式结构: 25%悬念 + 50%发展 + 25%收尾
  153. 3. 精彩放片头
  154. 4. 情感占51%(Walter Murch六法则)
  155. ### 阶段3: 素材三维分析
  156. 目标:让AI理解每条素材的内容。每条素材做三维分析:
  157. **a) 音频分析 — ASR转录(Whisper 或 FunASR)**
  158. ```bash
  159. # 提取音频(16kHz单声道WAV,两个引擎通用的最佳输入格式)
  160. ffmpeg -i footage/INPUT.MOV -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/audio.wav
  161. ```
  162. **方案1: Whisper转录(优先使用)**
  163. ```python
  164. import whisper, json
  165. model = whisper.load_model('medium')
  166. result = model.transcribe('/tmp/audio.wav', language='zh')
  167. segments = [{"start": s['start'], "end": s['end'], "text": s['text']} for s in result['segments']]
  168. # 输出: [{"start": 0.5, "end": 2.3, "text": "我们现在在中央大街"}, ...]
  169. ```
  170. **方案2: FunASR转录(Whisper装不上时的替代)**
  171. ```python
  172. import warnings
  173. warnings.filterwarnings("ignore")
  174. from funasr import AutoModel
  175. model = AutoModel(
  176. model="paraformer-zh", # Paraformer-large,中文ASR主模型(1.05GB)
  177. vad_model="fsmn-vad", # 语音活动检测,自动切分静音段
  178. punc_model="ct-punc", # 自动加标点
  179. log_level="ERROR",
  180. disable_update=True # 跳过版本检查,加快启动
  181. )
  182. result = model.generate(input="/tmp/audio.wav")
  183. text = result[0]["text"] # 完整识别文本(已加标点)
  184. timestamps = result[0].get("timestamp", []) # 字级别时间戳 [[start_ms, end_ms], ...]
  185. # ⚠ FunASR时间戳是字级别(毫秒),需要聚合成句级别才能和whisper格式统一
  186. # 聚合策略:按标点符号(。!?,)切分成句子
  187. segments = []
  188. if timestamps and text:
  189. puncs = set("。!?,,.!?")
  190. current_start = timestamps[0][0] / 1000.0
  191. current_text = ""
  192. chars = list(text)
  193. for i, (char, ts) in enumerate(zip(chars, timestamps)):
  194. current_text += char
  195. if char in puncs or i == len(chars) - 1:
  196. segments.append({
  197. "start": round(current_start, 1),
  198. "end": round(ts[1] / 1000.0, 1),
  199. "text": current_text.strip()
  200. })
  201. if i < len(chars) - 1:
  202. current_start = timestamps[i + 1][0] / 1000.0
  203. current_text = ""
  204. # 输出格式与whisper一致: [{"start": 0.6, "end": 2.9, "text": "我们现在在中央大街的入口,"}, ...]
  205. ```
  206. **⚠ FunASR 输出差异注意:**
  207. - FunASR 返回的是完整文本 + 字级别时间戳,不像 whisper 直接给句级别 segments
  208. - 上面的聚合代码把字级别时间戳按标点切分成句子,输出格式与 whisper 对齐
  209. - 如果素材没有语音,FunASR 返回空文本 `""`,timestamps 为空 `[]`
  210. - FunASR 速度比 whisper 快 3-5x(14s音频只需1.9s),批量处理时优势明显
  211. **b) 音量检测 — ffmpeg**
  212. ```bash
  213. ffmpeg -i footage/INPUT.MOV -af volumedetect -f null /dev/null 2>&1 | grep volume
  214. # mean_volume: 平均音量(dB) max_volume: 峰值音量(dB)
  215. # mean < -40dB 基本无声 mean > -20dB 有明显声音/语音
  216. ```
  217. **c) 视觉分析 — ffmpeg抽帧 + 视觉理解模型**
  218. ```bash
  219. # 抽帧策略(按时长分段)
  220. # ≤20s → 3帧(首/中/尾)
  221. # 20-60s → 5帧
  222. # >60s → 每15s一帧
  223. # 抽首/中/尾三帧示例(缩到720p节省带宽)
  224. ffmpeg -i footage/INPUT.MOV -vf "select=eq(n\,0),scale=1280:-1" -frames:v 1 -q:v 2 frame_start.jpg
  225. ffmpeg -i footage/INPUT.MOV -vf "select=eq(n\,MIDDLE),scale=1280:-1" -frames:v 1 -q:v 2 frame_mid.jpg
  226. ffmpeg -i footage/INPUT.MOV -vf "reverse,scale=1280:-1" -frames:v 1 -q:v 2 frame_end.jpg
  227. ```
  228. **d) 输出格式**(每条素材一个JSON)
  229. ```json
  230. {
  231. "filename": "clip_001.MOV",
  232. "duration": 15.3,
  233. "resolution": "1920x1080",
  234. "visual": [
  235. {"time": "0:00", "description": "...", "shot_type": "近景", "camera": "手持", "mood": "温馨"}
  236. ],
  237. "audio": {
  238. "has_speech": true,
  239. "mean_volume_db": -20.5,
  240. "max_volume_db": -3.2,
  241. "transcript": [{"start": 0.5, "end": 2.3, "text": "..."}]
  242. }
  243. }
  244. ```
  245. ### 阶段3.5: 素材精修预处理
  246. 目标:在给LLM之前,自动标注每条素材的"推荐有效区间",让LLM专注叙事编排。
  247. **为什么需要这步:**
  248. 原始手机素材普遍存在:开头录制口令、同一句话重复多遍、前1-2s举手机晃动、说完话后拖很长的无意义画面。如果把这些原始数据直接给LLM,LLM输出的plan还需要逐条修补。
  249. **预处理做四件事:**
  250. #### a) 录制口令检测
  251. ```python
  252. RECORDING_CUES = [
  253. "开始了", "好了开始", "开始录了", "好了 开始",
  254. "走了", "好了", "来了", # 仅在前3s内出现时算口令
  255. ]
  256. def detect_cues(transcript_segments, duration):
  257. """检测录制口令,返回skip zones"""
  258. skip_zones = []
  259. for seg in transcript_segments:
  260. text = seg['text'].strip()
  261. if seg['start'] < 3.0 and any(text.startswith(c) or text == c for c in RECORDING_CUES):
  262. skip_zones.append({
  263. 'type': 'recording_cue',
  264. 'range': [seg['start'], seg['end']],
  265. 'text': text,
  266. 'action': 'skip'
  267. })
  268. if seg['end'] > duration - 3.0 and text in ["好了", "走了", "好了 走"]:
  269. skip_zones.append({
  270. 'type': 'recording_cue',
  271. 'range': [seg['start'], seg['end']],
  272. 'text': text,
  273. 'action': 'skip'
  274. })
  275. return skip_zones
  276. ```
  277. #### b) 重复语音检测
  278. ```python
  279. from difflib import SequenceMatcher
  280. def detect_repeats(segments, threshold=0.6):
  281. """检测重复语音,标记建议跳过的重复段"""
  282. repeats = []
  283. for i, a in enumerate(segments):
  284. for j, b in enumerate(segments):
  285. if j <= i: continue
  286. ratio = SequenceMatcher(None, a['text'], b['text']).ratio()
  287. if ratio >= threshold and len(a['text']) > 4:
  288. skip = a if len(a['text']) <= len(b['text']) else b
  289. repeats.append({
  290. 'type': 'repeat',
  291. 'range': [skip['start'], skip['end']],
  292. 'text': skip['text'],
  293. 'kept': b['text'] if skip == a else a['text'],
  294. 'action': 'suggest_skip'
  295. })
  296. return repeats
  297. ```
  298. #### c) 起手晃动 / 结尾拖拽检测
  299. ```python
  300. def detect_trim_points(segments, duration, mean_volume_db):
  301. """基于语音+音量推荐起止点"""
  302. suggested_start = 0.0
  303. suggested_end = duration
  304. if segments:
  305. first_speech = segments[0]['start']
  306. last_speech_end = segments[-1]['end']
  307. if first_speech > 2.0:
  308. suggested_start = max(0, first_speech - 0.5)
  309. if duration - last_speech_end > 3.0:
  310. suggested_end = last_speech_end + 1.5
  311. else:
  312. if duration > 5.0:
  313. suggested_start = 1.0
  314. return suggested_start, suggested_end
  315. ```
  316. #### d) 纯画面时长限制
  317. | 模式 | 纯画面上限 | 口令处理 | 重复处理 | 起手晃动 |
  318. |----------|-----------|---------|---------------|---------|
  319. | strict | 8-10s | 全部去除 | 只留1遍 | 去1.5s |
  320. | normal | 12-15s | 去除明确口令 | 去明显重复 | 去1.0s |
  321. | loose | 20-25s | 仅去"开始了" | 保留大部分 | 去0.5s |
  322. #### e) 输出格式
  323. 预处理结果追加到素材分析数据里:
  324. ```
  325. ━━━ clip_012.mp4 | 时长25.8s | 1920x1080 ━━━
  326. 【画面】...
  327. 【语音】...
  328. 【精修建议】模式: normal
  329. 原始区间: [0.0 - 25.8]
  330. 推荐区间: [2.4 - 25.8]
  331. ⊘ [0.0-2.4] 跳过: 录制口令 "开始了"
  332. 有效语音: [2.62-25.8]
  333. ```
  334. **⚠ 重要原则:预处理只做标注和建议,不做硬裁剪。LLM保留最终决定权。**
  335. ### 阶段4: LLM叙事编排
  336. 目标:把预处理后的素材数据交给LLM,生成剪辑方案。
  337. 输入:素材分析 + 精修建议(推荐区间) + 参考研究结论
  338. 输出:剪辑方案JSON(结构见下方schema)
  339. #### edit_plan JSON Schema
  340. ```json
  341. {
  342. "title": "视频标题",
  343. "structure": [
  344. {
  345. "section": "段落名 — 副标题",
  346. "description": "本段落内容概述",
  347. "clips": [
  348. {
  349. "file": "素材文件名.mp4",
  350. "start": 0.0,
  351. "end": 12.0,
  352. "note": "画面内容简述",
  353. "subtitle": "保留的语音文字"
  354. }
  355. ]
  356. }
  357. ],
  358. "bgm_suggestion": "BGM风格建议(含genre/mood/instruments/tempo/bpm)",
  359. "editing_notes": "整体剪辑说明"
  360. }
  361. ```
  362. **约束:**
  363. - 同一素材可出现在多个clip中(不同时间区间)
  364. - start/end 不能截断语音中间(阶段4.5会校验)
  365. - 第一个section建议是"开篇"类引入段落
  366. - 最后一个section建议是"收尾"类段落
  367. 详细prompt模板见 `templates/edit_plan_prompt.md`。
  368. ### 阶段4+ : 分镜可视化 + Dashboard(浏览器预览)
  369. 目标:把LLM输出的剪辑方案做成图文并茂的网页,方便用户直观Review。
  370. **Dashboard 包含两个面板:**
  371. 1. **📋 素材总览** — 素材缩略图网格 + 时长/语音/音量标注 + 筛选(全部/已用/未用/含语音) + 点击查看详情
  372. 2. **✅ 成品质量检查** — 成品视频定时抽帧(每30秒) + 段落定位 + 点击放大
  373. **使用 `gen_dashboard.py` 脚本:**
  374. ```bash
  375. # 最小用法(只生成素材面板)
  376. python3 scripts/gen_dashboard.py \
  377. --analysis clip_analysis.json \
  378. --plan edit_plan.json \
  379. --footage footage/ \
  380. --out output/
  381. # 完整两面板(含成品QC帧)
  382. python3 scripts/gen_dashboard.py \
  383. --analysis clip_analysis.json \
  384. --plan edit_plan.json \
  385. --footage footage/ \
  386. --video output/final.mp4 \
  387. --out output/
  388. ```
  389. **支持两种分析数据格式(自动检测):**
  390. - 标准格式 `clip_analysis.json`: `{filename, duration, visual: [...], audio: {...}}`
  391. - 紧凑格式 `clips_compact.json`: `{file, dur, visual: "string", speech: [...]}`
  392. 用户确认分镜方案后,再进入渲染阶段。
  393. ### 阶段4.5: 语音截断校验
  394. 目标:自动校验LLM输出的plan,确保没有把任何语音从中间截断。
  395. ```python
  396. def validate_speech(plan_clips, speech_data):
  397. """检查每个clip的start/end是否截断了语音"""
  398. issues = []
  399. for clip in plan_clips:
  400. f = clip['file']
  401. cs, ce = clip['start'], clip['end']
  402. if f not in speech_data: continue
  403. for ss, se, txt in speech_data[f]:
  404. if ss < ce and se > cs: # 语音与clip有交集
  405. if ss < cs - 0.3: # 语音开始在clip之前
  406. issues.append(f"截断开头: {f} clip从{cs}开始,但语音\"{txt}\"从{ss}开始")
  407. if se > ce + 0.5: # 语音结束在clip之后
  408. issues.append(f"截断结尾: {f} clip在{ce}结束,但语音\"{txt}\"到{se}结束")
  409. return issues
  410. ```
  411. **校验不通过时:自动修复start/end,不需要回LLM重新编排。**
  412. #### 自动修复逻辑
  413. ```python
  414. def fix_speech_cuts(plan, speech_data, margin=0.3):
  415. """
  416. 自动修复语音截断问题。直接修改plan中的start/end。
  417. 参数:
  418. plan: edit_plan dict (会被原地修改)
  419. speech_data: dict, {filename: [(start, end, text), ...]}
  420. margin: float, 语音边界容差(秒)
  421. 返回:
  422. fixes: list of str, 修复日志
  423. """
  424. fixes = []
  425. for sec in plan["structure"]:
  426. for clip in sec["clips"]:
  427. f = clip["file"]
  428. cs = float(clip["start"])
  429. ce = float(clip["end"])
  430. if f not in speech_data:
  431. continue
  432. for ss, se, txt in speech_data[f]:
  433. if ss >= ce or se <= cs:
  434. continue
  435. # 开头截断:clip.start > speech.start + margin
  436. if ss < cs - margin and se > cs:
  437. old_start = cs
  438. new_start = max(0, ss - 0.1)
  439. clip["start"] = round(new_start, 1)
  440. fixes.append(
  441. f" 修复开头: {f} [{old_start}→{new_start}] "
  442. f"语音\"{txt[:20]}\"从{ss}s开始"
  443. )
  444. cs = new_start
  445. # 结尾截断:clip.end < speech.end - margin
  446. if se > ce + margin and ss < ce:
  447. old_end = ce
  448. new_end = se + 0.2
  449. clip["end"] = round(new_end, 1)
  450. fixes.append(
  451. f" 修复结尾: {f} [{old_end}→{new_end}] "
  452. f"语音\"{txt[:20]}\"到{se}s结束"
  453. )
  454. ce = new_end
  455. return fixes
  456. def validate_and_fix(plan, speech_data):
  457. """
  458. 端到端校验+修复入口。
  459. 用法:
  460. import json
  461. # 加载plan
  462. plan = json.load(open('edit_plan.json'))
  463. # 加载语音数据 (格式: {filename: [{start, end, text}, ...]})
  464. raw = json.load(open('clip_analysis.json'))
  465. speech_data = {}
  466. for clip_info in raw:
  467. fname = clip_info['filename']
  468. if clip_info['audio']['has_speech']:
  469. speech_data[fname] = [
  470. (s['start'], s['end'], s['text'])
  471. for s in clip_info['audio']['transcript']
  472. ]
  473. # 校验
  474. all_clips = [c for sec in plan['structure'] for c in sec['clips']]
  475. issues = validate_speech(all_clips, speech_data)
  476. print(f'发现 {len(issues)} 个截断问题')
  477. # 修复
  478. fixes = fix_speech_cuts(plan, speech_data)
  479. print(f'自动修复 {len(fixes)} 处')
  480. # 二次校验确认
  481. all_clips2 = [c for sec in plan['structure'] for c in sec['clips']]
  482. issues2 = validate_speech(all_clips2, speech_data)
  483. assert len(issues2) == 0, f'仍有 {len(issues2)} 个问题未修复!'
  484. print('✅ 二次校验通过')
  485. # 保存修复后的plan
  486. json.dump(plan, open('edit_plan_fixed.json', 'w', ensure_ascii=False), indent=2)
  487. """
  488. all_clips = [c for sec in plan['structure'] for c in sec['clips']]
  489. issues = validate_speech(all_clips, speech_data)
  490. fixes = fix_speech_cuts(plan, speech_data)
  491. return issues, fixes
  492. ```
  493. **修复策略:**
  494. | 截断类型 | 检测条件 | 修复方式 |
  495. |----------|---------|---------|
  496. | 开头截断 | clip.start > speech.start + margin | clip.start → speech.start - 0.1s |
  497. | 结尾截断 | clip.end < speech.end - margin | clip.end → speech.end + 0.2s |
  498. **边界容差 (margin=0.3s):** Whisper/FunASR 时间戳有±0.2-0.3s误差。修复后必须跑二次校验。
  499. ### 阶段5: ffmpeg自动执行
  500. 目标:把剪辑方案转成ffmpeg命令并执行。
  501. #### 渲染策略:逐片段裁剪 → 拼接
  502. ```bash
  503. # 单个片段裁剪+编码
  504. ffmpeg -y -ss 00:00:02.400 -i footage/INPUT.mp4 -t 00:00:23.400 \
  505. -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,setsar=1" \
  506. -r 30 -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p \
  507. -c:a aac -b:a 128k -ar 44100 -ac 2 \
  508. -movflags +faststart segments/seg_001.mp4
  509. # 拼接成品
  510. ffmpeg -y -f concat -safe 0 -i concat.txt -c copy -movflags +faststart output.mp4
  511. ```
  512. #### 变速
  513. ```bash
  514. # 2倍速(视频+音频同步)
  515. ffmpeg -i input.mp4 -filter:v "setpts=0.5*PTS" -filter:a "atempo=2.0" out.mp4
  516. ```
  517. #### 片头高光蒙太奇
  518. 从各段落选最有视觉冲击力的镜头,快切拼接放在视频最前面。
  519. **选片原则:**
  520. - 每个主要段落选1个精彩画面
  521. - 每个镜头0.5-1秒,快切节奏
  522. - 总共6-10个镜头,总时长5-8秒
  523. - 排除竖屏素材
  524. - 不加音频(-an),最终由BGM覆盖
  525. ```python
  526. import subprocess, os
  527. highlights = [
  528. ('footage/clip_a.mp4', 1.5, 2.2),
  529. ('footage/clip_b.mp4', 2.0, 2.7),
  530. # ... 每个0.7秒左右
  531. ]
  532. for i, (f, start, end) in enumerate(highlights, 1):
  533. dur = end - start
  534. cmd = f'ffmpeg -y -ss {start} -i "{f}" -t {dur} ' \
  535. f'-vf "scale=1920:1080:force_original_aspect_ratio=decrease,' \
  536. f'pad=1920:1080:(ow-iw)/2:(oh-ih)/2" ' \
  537. f'-c:v libx264 -preset ultrafast -crf 23 -pix_fmt yuv420p ' \
  538. f'-an highlights/hl_{i}.mp4'
  539. subprocess.run(cmd, shell=True)
  540. # concat
  541. with open('highlights/concat.txt', 'w') as f:
  542. for i in range(1, len(highlights)+1):
  543. f.write(f"file 'hl_{i}.mp4'\n")
  544. subprocess.run('ffmpeg -y -f concat -safe 0 -i highlights/concat.txt '
  545. '-c copy highlights/montage.mp4', shell=True)
  546. ```
  547. #### 段落标题叠加
  548. 用 Pillow 生成透明RGBA的PNG,ffmpeg overlay到视频画面上。**不要用黑底标题卡**。
  549. ```python
  550. from PIL import Image, ImageDraw, ImageFont, ImageFilter
  551. W, H = 1920, 1080
  552. title = "段落标题"
  553. img = Image.new("RGBA", (W, H), (0, 0, 0, 0))
  554. draw = ImageDraw.Draw(img)
  555. # 字体:macOS用冬青黑体,Linux用Noto Sans CJK
  556. # font = ImageFont.truetype("/System/Library/Fonts/Hiragino Sans GB.ttc", 60) # macOS
  557. # font = ImageFont.truetype("/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", 60) # Linux
  558. font = ImageFont.truetype("YOUR_FONT_PATH", 60)
  559. bbox = draw.textbbox((0, 0), title, font=font)
  560. tw, th = bbox[2] - bbox[0], bbox[3] - bbox[1]
  561. x, y = (W - tw) // 2, (H - th) // 2
  562. # 柔和阴影
  563. shadow = Image.new("RGBA", (W, H), (0, 0, 0, 0))
  564. sd = ImageDraw.Draw(shadow)
  565. sd.text((x+2, y+2), title, fill=(0, 0, 0, 180), font=font)
  566. shadow = shadow.filter(ImageFilter.GaussianBlur(radius=6))
  567. img = Image.alpha_composite(img, shadow)
  568. draw = ImageDraw.Draw(img)
  569. draw.text((x, y), title, fill=(255, 255, 255, 240), font=font)
  570. img.save("title_overlay.png")
  571. ```
  572. **overlay到视频上:**
  573. ```bash
  574. # 标题显示前3秒
  575. ffmpeg -y -i section.mp4 -i title.png \
  576. -filter_complex "overlay=0:0:enable='between(t,0,3)'" \
  577. -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p \
  578. -c:a aac -b:a 128k -movflags +faststart \
  579. section_titled.mp4
  580. ```
  581. **⚠ overlay关键Pitfall:**
  582. - ❌ 不要加 `shortest=1` — PNG只有1帧,会导致视频流立刻截断
  583. - ✅ 直接用 `overlay=0:0:enable='between(t,0,3)'` 最简单可靠
  584. - ✅ 先用短片段(5-8s)验证overlay效果
  585. #### 段落拼接(推荐方案)
  586. **✅ 正确方案:逐段编码 → concat copy**
  587. ```bash
  588. echo "file 'final_sec_01.mp4'" > concat.txt
  589. echo "file 'final_sec_02.mp4'" >> concat.txt
  590. ffmpeg -y -f concat -safe 0 -i concat.txt -c copy -movflags +faststart output.mp4
  591. ```
  592. **❌ 不要用xfade链式合并:** 链式xfade会导致帧数累积丢失,后半段全黑。
  593. **段落间过渡**:段落内硬切即可。如需渐变,每段首尾加fade比xfade更可靠。
  594. #### BGM生成与混音(可选)
  595. BGM 可以手动添加,也可以用 AI 音乐生成工具(如 MiniMax music、Suno 等)。
  596. ##### a) AI 生成 BGM
  597. **风格映射参考(vlog常用):**
  598. | Vlog 风格 | genre | mood | instruments | tempo |
  599. |-----------|-------|------|-------------|-------|
  600. | 轻松日常 | indie pop | cheerful, carefree | ukulele, acoustic guitar | moderate |
  601. | 文艺治愈 | folk, acoustic | warm, gentle | acoustic guitar, piano, strings | slow |
  602. | 美食探店 | jazz, bossa nova | cozy, playful | piano, upright bass | moderate |
  603. | 冰雪/冬季 | cinematic, ambient | serene, majestic | piano, celesta, strings | slow |
  604. | 热带/海岛 | tropical house | sunny, relaxed | steel drums, marimba | upbeat |
  605. | 城市探索 | lo-fi hip hop | chill, urban | keys, vinyl crackle | moderate |
  606. ##### b) 混合到视频
  607. ```bash
  608. # BGM 音量 10-15%(有语音的vlog要压低BGM)
  609. ffmpeg -y -i video_no_bgm.mp4 -i bgm.m4a \
  610. -filter_complex "[0:a]volume=1.0[orig];[1:a]volume=0.12[bgm];[orig][bgm]amix=inputs=2:duration=first:dropout_transition=2[aout]" \
  611. -map 0:v -map "[aout]" -c:v copy -c:a aac -b:a 192k \
  612. -movflags +faststart output/final.mp4
  613. ```
  614. **BGM 音量建议:**
  615. - 有大量语音/旁白 → 8-12%
  616. - 语音较少,空镜为主 → 15-25%
  617. - 纯空镜蒙太奇段落 → 30-40%
  618. #### 变速
  619. ```bash
  620. ffmpeg -i input.mp4 -filter:v "setpts=0.5*PTS" -filter:a "atempo=2.0" out.mp4
  621. ```
  622. ## Pitfalls
  623. 1. **剪映不可用** — v10.4+ 对 draft_info.json 加密,不要浪费时间
  624. 2. **视觉API端点要区分** — 有些平台视觉模型和文本模型端点不同,确认用对
  625. 3. **Whisper模型选择** — base中文太差,large太慢,medium是性价比最优
  626. 4. **不要跳过参考研究** — 没有"好vlog标准"的AI会剪出流水账
  627. 5. **ffmpeg编码兼容** — 拼接时注意素材编码一致性,先逐片段统一编码再concat
  628. 6. **视觉API限流** — 高峰时段容易限流,加retry和sleep
  629. 7. **预处理在LLM之前做** — 口令/重复/晃动检测在阶段3.5处理
  630. 8. **预处理是建议不是硬裁剪** — LLM保留覆盖权,某些口令可能有叙事价值
  631. 9. **语音截断必须自动校验** — LLM输出的plan可能在语音中间切断
  632. 10. **Whisper幻觉** — 纯音乐/环境音段落whisper会编造文字,需用音量阈值(-40dB)过滤
  633. 11. **竖屏混横屏** — 素材分析阶段就要检测,竖屏(9:16)混在横屏里很突兀,建议去掉
  634. 12. **overlay不要加shortest=1** — PNG只有1帧,shortest=1会让视频流截断
  635. 13. **标题卡风格** — 白字+柔和阴影叠在视频画面上,**不要黑底标题卡**
  636. 14. **ffmpeg drawtext不可用** — macOS Homebrew ffmpeg默认没编译freetype,用Pillow生成PNG overlay代替
  637. 15. **HEVC警告可忽略** — "Error constructing the frame RPS" 是HEVC解码警告,不影响输出
  638. 16. **Non-monotonic DTS** — concat拼接时常见的时间戳警告,播放不受影响
  639. 17. **空镜不宜过长** — 无语音的纯画面>6s偏长,建议压缩到5-8s
  640. 18. **xfade链式合并不可靠** — 链式xfade会导致帧数累积丢失,后半段全黑,用concat代替
  641. 19. **先用短片段验证** — 每次改渲染方案都先用5-8秒短片段验证效果
  642. 20. **渲染完必须验证帧数** — `ffmpeg -i output.mp4 -f null -` 检查实际frame数
  643. 21. **BGM别太大声** — 有语音段BGM控制在8-12%,先试听再定
  644. 22. **多段BGM衔接** — 保持相近的key和tempo(bpm差值<20)
  645. 23. **混音后必须试听** — 不同素材原始音量差异大
  646. 24. **不要重复安装依赖** — whisper/Pillow等先检测再装,不要每次都新建venv
  647. 25. **FunASR必须装torchaudio** — `pip install funasr modelscope` 不够,必须 `pip install funasr modelscope torchaudio`,否则 import 报 `No module named 'torchaudio'`
  648. 26. **FunASR时间戳是字级别** — 不像whisper直接给句级别segments,FunASR返回每个字的[start_ms, end_ms],需要按标点聚合成句子才能喂给后续的语音截断校验(阶段4.5)
  649. 27. **FunASR幻觉比whisper轻** — 纯环境音/音乐时FunASR通常返回空文本,不像whisper会编造内容。但仍需用音量阈值(-40dB)做二次确认
  650. ### 编码与拼接类(视频教程实战新增)
  651. 28. **⚠️ atempo加速后音视频时长不一致** — atempo处理后音频比视频短0.4-0.8秒/段。8段累积差好几秒,后半段音画完全对不上。**每段剪辑后必须立即验证音视频时长差<0.05s**,超过则用apad补齐:
  652. ```bash
  653. # 验证
  654. ffprobe -show_entries stream=duration -select_streams v -of csv=p=0 seg.mp4 # 视频时长
  655. ffprobe -show_entries stream=duration -select_streams a -of csv=p=0 seg.mp4 # 音频时长
  656. # 补齐
  657. ffmpeg -y -i seg.mp4 -af "apad" -c:v copy -c:a aac -shortest seg_fixed.mp4
  658. ```
  659. 29. **⚠️ concat copy音频时间戳不连续** — 多段concat copy后音频咔咔响/剪映音画偏移。**正确方案:音频单独提取wav+apad补齐+concat filter拼接,视频单独concat copy,最后合并**:
  660. ```bash
  661. # 每段提取音频(apad补齐到视频时长)
  662. ffmpeg -y -i seg.mp4 -vn -af "apad" -ar 48000 -ac 2 -c:a pcm_s16le -t {视频时长} seg.wav
  663. # concat filter拼接音频(不是demuxer)
  664. ffmpeg -y -i a.wav -i b.wav -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[aout]" -map "[aout]" -c:a aac audio.m4a
  665. # 合并
  666. ffmpeg -y -i video.mp4 -i audio.m4a -c:v copy -c:a copy output.mp4
  667. ```
  668. 30. **剪映兼容编码** — 导入剪映音画不同步的修复:`-r 30 -vsync cfr`(固定帧率) + `-x264-params "bframes=0"`(无B帧) + `-ar 48000 -ac 2`(统一音频)
  669. 31. **crf值对录屏类内容要低** — 录屏文字密集,crf 22码率不够会糊。录屏用`-crf 18`或`-b:v 3M`。一般vlog素材crf 22即可
  670. 32. **多次重编码画质累积损失** — 剪辑→拼接→加背景→叠进度条,每次编码都损失画质。**尽量一次filter链搞定**,减少编码次数
  671. 33. **后台ffmpeg进程泄漏** — kill后台任务时可能只杀shell不杀ffmpeg子进程。每次kill后`ps aux | grep ffmpeg`确认,残留用`kill -9 PID`
  672. 34. **开工前第一件事确认输出分辨率** — 全流程统一分辨率不要中途改。录屏类用1080p(文字密集对分辨率敏感),vlog素材用原始分辨率或1080p
  673. 35. **⚠️ overlay视频时音频被覆盖/丢失** — 用filter_complex overlay叠加进度条/水印等视频时,ffmpeg可能自动选取overlay源(静音)的音频而不是原视频的音频。**必须用`-map`明确指定音频来源**:
  674. ```bash
  675. # ❌ 不指定map,音频可能来自overlay源(静音)
  676. ffmpeg -i main.mp4 -i overlay.mp4 -filter_complex "overlay=0:0" output.mp4
  677. # ✅ 明确map:视频取filter输出,音频取原视频
  678. ffmpeg -i main.mp4 -i overlay.mp4 \
  679. -filter_complex "[0:v][1:v]overlay=0:0[vout]" \
  680. -map "[vout]" -map 0:a \
  681. -c:v libx264 -c:a copy output.mp4
  682. ```
  683. 如果还不行(音频编解码问题),**分步做更可靠**:
  684. ```bash
  685. # Step1: 只处理视频(-an去掉音频)
  686. ffmpeg -i main.mp4 -i overlay.mp4 -filter_complex "overlay" -map "[vout]" -an video_only.mp4
  687. # Step2: 把原始音频合回来
  688. ffmpeg -i video_only.mp4 -i main.mp4 -map 0:v -map 1:a -c:v copy -c:a copy final.mp4
  689. ```
  690. 36. **⚠️ -shortest会截断音频** — 视频和音频时长不完全一致时,`-shortest`会丢掉最后几秒的音频。**优先用`-t {精确时长}`替代**,或者确保音视频等长后不加-shortest
  691. ## 端到端示例
  692. ### 项目文件结构
  693. ```
  694. my-vlog-project/
  695. ├── footage/ # 原始素材(用户提供)
  696. │ ├── clip_001.MOV
  697. │ └── ...
  698. │
  699. ├── analysis/ # 阶段3输出
  700. │ └── clip_analysis.json
  701. │
  702. ├── edit_plan.json # 阶段4输出
  703. ├── edit_plan_fixed.json # 阶段4.5输出
  704. │
  705. ├── output/
  706. │ ├── dashboard.html # Dashboard网页
  707. │ ├── thumbnails/ # 素材缩略图
  708. │ ├── qc_frames/ # 成品QC帧
  709. │ ├── segments/ # 裁剪后的片段
  710. │ ├── highlights/ # 片头高光蒙太奇
  711. │ ├── titles/ # 段落标题PNG
  712. │ ├── sections/ # 带标题的段落视频
  713. │ ├── bgm/ # BGM文件
  714. │ ├── video_no_bgm.mp4 # 无BGM的完整视频
  715. │ └── final.mp4 # 🎬 成品视频
  716. │
  717. └── reference/ # 阶段2输出(可选)
  718. ```
  719. ### 中间产物示例
  720. 见 `examples/` 目录下的示例文件。
  721. ### 执行流程速查
  722. ```
  723. 素材文件夹 footage/
  724. │
  725. ▼
  726. 阶段1: 素材盘点 → ffprobe批量扫描 → 清单
  727. │
  728. ▼
  729. 阶段2: 参考研究 → 下载优质vlog → 分析节奏(可选)
  730. │
  731. ▼
  732. 阶段3: 素材三维分析 → whisper/FunASR+音量+视觉 → clip_analysis.json
  733. │
  734. ▼
  735. 阶段3.5: 精修预处理 → 口令/重复/晃动/纯画面标注
  736. │
  737. ▼
  738. 阶段4: LLM叙事编排 → edit_plan.json
  739. │
  740. ▼
  741. 阶段4+: Dashboard可视化 → 浏览器预览确认
  742. │
  743. ▼
  744. 阶段4.5: 语音截断校验 → 自动修复
  745. │
  746. ▼
  747. 阶段5: ffmpeg渲染 → 裁剪→标题→拼接→BGM → final.mp4 🎬
  748. ```
  749. ## 验证
  750. - [ ] 素材盘点完成,生成清单
  751. - [ ] 参考研究完成,提取规律
  752. - [ ] 素材三维分析完成(视觉+音频+音量)
  753. - [ ] 素材精修预处理完成
  754. - [ ] LLM剪辑方案生成
  755. - [ ] 语音截断校验通过
  756. - [ ] **每段片段音视频时长差<0.05s**
  757. - [ ] ffmpeg执行成功,输出成品视频
  758. - [ ] **成品音频完整(不被-shortest截断)**
  759. - [ ] **拖到视频后半段检查音画同步**
  760. - [ ] 成品视频质量人工确认
  761. ---
  762. **Author:** nyx研究所 · [GitHub](https://github.com/znyupup) · [B站](https://space.bilibili.com/4330525) · 小红书 @nyx研究所
  763. **License:** MIT
README.md · README · 238 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🎬 Vlog Auto Edit — AI Agent 自动剪辑旅行 Vlog
  2. > 把一堆手机拍的旅行素材,用 AI Agent 自动剪成一个完整 Vlog。
  3. > 你只需要提供素材文件夹,剩下的交给 Agent。
  4. **Vibe Editing** — 不用学剪辑软件,不用自己挑选素材,不用纠结叙事结构。
  5. 告诉 AI 你想要什么风格,它帮你从头到尾搞定。
  6. 🧑‍💻 by **nyx研究所** — [GitHub](https://github.com/znyupup) · [B站](https://space.bilibili.com/4330525) · [小红书](https://www.xiaohongshu.com/) @nyx研究所 · [X / Twitter](https://x.com/znyupup_music)
  7. ## ✨ 这是什么
  8. 这是一份给 AI Agent(Claude Code / Hermes / OpenClaw / GPT 等)使用的 **Skill 文件**,定义了从原始素材到成品视频的完整自动剪辑工作流。
  9. 它不是一个传统的软件程序——而是一份**指导 AI Agent 工作的知识文件**,包含:
  10. - 完整的工作流程定义
  11. - 每个步骤的具体命令和代码
  12. - 24 条实战踩坑经验
  13. - 可视化预览工具
  14. - 模板和示例数据
  15. ## 🎯 解决什么问题
  16. 你去旅行拍了 80 个视频片段,回来之后:
  17. - ❌ 打开剪映/PR,面对几十G素材不知从何下手
  18. - ❌ 花了3小时挑选素材,又花3小时调整顺序
  19. - ❌ 最后剪出来的要么是流水账,要么节奏奇怪
  20. - ❌ 或者就这么一直放着,永远不会去剪
  21. 用了这个 Skill:
  22. - ✅ 把素材文件夹丢给 AI Agent
  23. - ✅ Agent 自动理解每条素材(画面、语音、音量)
  24. - ✅ Agent 像专业剪辑师一样编排叙事结构
  25. - ✅ 你在浏览器里预览确认
  26. - ✅ Agent 自动渲染、加标题、配BGM,输出成品
  27. ## 🛠️ 最小依赖
  28. 系统级只需要装两样东西:
  29. | 工具 | 用途 | 安装 |
  30. |------|------|------|
  31. | **ffmpeg** | 视频裁剪/编码/拼接/抽帧/混音 | `brew install ffmpeg` / `apt install ffmpeg` |
  32. | **Python 3.9+** | 脚本胶水 | macOS/Linux 自带 |
  33. Python 依赖(Agent 会自动检测和安装):
  34. - `openai-whisper` — 语音转录
  35. - `Pillow` — 标题图片生成
  36. 还需要一个**视觉理解 API**(用来看懂画面内容):
  37. | 模型 | 费用 | 说明 |
  38. |------|------|------|
  39. | 智谱 GLM-4.6V-Flash | 免费 | 注册 [open.bigmodel.cn](https://open.bigmodel.cn) 即用,中文好 |
  40. | GPT-4o | 付费 | 效果最好 |
  41. | Qwen-VL | 付费 | 阿里云,中文好 |
  42. **不需要:** 剪映 / CapCut / Premiere / moviepy / ImageMagick
  43. ## 📋 只有 4 步
  44. ```
  45. ┌──────────────────────────────────────────────────────────┐
  46. │ │
  47. │ 素材文件夹 ❶ 分析 自动,不用管 │
  48. │ footage/ ──────────▶ Agent 理解每条素材的画面、 │
  49. │ 语音、音量,标记问题片段 │
  50. │ │
  51. │ ❷ 编排 自动,不用管 │
  52. │ Agent 像剪辑师一样规划 │
  53. │ 叙事结构和镜头节奏 │
  54. │ │
  55. │ ❸ 预览 ◀── 你看一眼 │
  56. │ 浏览器打开 Dashboard │
  57. │ 确认方案,或提修改意见 │
  58. │ │
  59. │ ❹ 出片 自动,不用管 │
  60. │ 裁剪 → 加标题 → 拼接 → BGM │
  61. │ │ │
  62. │ ▼ │
  63. │ 🎬 final.mp4 │
  64. │ │
  65. └──────────────────────────────────────────────────────────┘
  66. ```
  67. **你唯一需要做的就是第 ❸ 步——看一眼方案,说"可以"。** 其他全是 Agent 自动完成。
  68. ### ❶ 分析 — Agent 理解你的素材
  69. Agent 会自动对每条素材做三件事:
  70. - **听** — Whisper 转录语音内容
  71. - **看** — 抽帧 + 视觉 API 理解画面(内容、镜头类型、氛围)
  72. - **量** — 检测音量,区分有语音 / 静音 / 环境音
  73. 然后自动做预处理:去掉开头的"好了开始录了"、重复说了三遍的同一句话、举手机的晃动、说完话后的拖拽。
  74. ### ❷ 编排 — Agent 像剪辑师一样规划
  75. 基于素材分析结果,Agent 会:
  76. - 用**三幕式结构**编排叙事(开篇引入 → 主体发展 → 情感收尾)
  77. - 控制**镜头节奏**(平均 3-4 秒/镜头,长短交替)
  78. - 自动选最精彩的镜头做**片头蒙太奇**
  79. - 校验语音边界,**确保不会把话切在中间**
  80. - 建议 BGM 风格
  81. ### ❸ 预览 — 你在浏览器里确认
  82. Agent 生成一个交互式 Dashboard 网页:
  83. - **素材总览** — 缩略图网格,标注已用/未用/含语音,点击看详情
  84. - **分镜预览** — 每个镜头的关键帧 + 时间线 + 段落结构
  85. 你看完说"可以",或者说"第三段换个素材"——Agent 调整后再给你看。
  86. ### ❹ 出片 — Agent 自动渲染
  87. - 统一编码(h264, 1080p, 30fps)
  88. - 段落标题叠加(白字柔和阴影,不是黑底标题卡)
  89. - 片段拼接成完整视频
  90. - BGM 混音(有语音段自动压低 BGM)
  91. - 输出 `final.mp4` 🎬
  92. ## 🚀 怎么用
  93. ### 快速开始
  94. 复制下面的指令发给你的 AI Agent,它会自动完成安装和配置:
  95. ```
  96. 请从 https://github.com/znyupup/ai-video-editing-skill 克隆仓库,
  97. 阅读 SKILL.md 学习完整工作流,然后帮我把 footage/ 目录下的素材剪成一个旅行vlog。
  98. ```
  99. > 💡 一般情况下 Agent 能自行完成 ffmpeg 检测、Python 依赖安装、视觉 API 配置等所有前置步骤。你只需要准备好素材文件夹和一个视觉模型的 API Key。
  100. ### 方式一:配合 AI Agent 使用(推荐)
  101. 1. 把 `SKILL.md` 加载到你的 AI Agent
  102. 2. 告诉 Agent:`帮我把 footage/ 目录下的素材剪成一个旅行vlog`
  103. 3. 等着看 Dashboard,确认方案,收片
  104. 支持的 Agent 平台:
  105. - [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) — `git clone` 后 `/read SKILL.md` 加载
  106. - [OpenClaw](https://github.com/nicepkg/openclaw) — 导入到 Skill 库
  107. - 其他支持自定义指令/知识库的 Agent 均可使用
  108. ### 方式二:作为参考手册
  109. 即使不用 AI Agent,SKILL.md 本身也是一份详细的 ffmpeg + Whisper + 视觉 API 视频剪辑手册,可以手动按步骤执行。
  110. ## 📁 项目结构
  111. ```
  112. vlog-auto-edit/
  113. ├── SKILL.md # 🧠 核心:完整工作流定义(给 AI Agent 读的)
  114. ├── README.md # 📖 项目介绍(给人类读的)
  115. ├── LICENSE # MIT
  116. │
  117. ├── scripts/
  118. │ ├── gen_dashboard.py # 📊 Dashboard 生成器
  119. │ └── gen_storyboard.py # 🎬 分镜预览生成器
  120. │
  121. ├── templates/
  122. │ └── edit_plan_prompt.md # 📝 LLM 叙事编排 prompt 模板
  123. │
  124. └── examples/
  125. ├── clip_analysis.json # 示例:素材分析数据
  126. ├── edit_plan.json # 示例:剪辑方案
  127. └── project_structure.md # 示例:项目文件结构说明
  128. ```
  129. ## 🧠 进阶用法
  130. ### 参考研究
  131. 在分析素材之前,可以让 Agent 先研究 2-3 个同类型优质 vlog(B站/YouTube),提取镜头节奏和叙事结构作为参考。这一步可选,但能显著提升成品质量。
  132. ### 调整剪辑风格
  133. 编辑 `templates/edit_plan_prompt.md` 中的参数:
  134. - 镜头节奏(平均秒数/镜头)
  135. - 内容配比(美食/风景/人物比例)
  136. - 叙事结构(三幕式比例)
  137. - 目标时长
  138. ### 调整预处理严格度
  139. Agent 在分析阶段支持三种预处理模式:
  140. - `strict` — 激进裁剪,最短成品
  141. - `normal` — 均衡模式(默认)
  142. - `loose` — 保守裁剪,保留更多内容
  143. ### 自定义视觉模型
  144. 支持任何兼容 OpenAI Chat Completions 格式的视觉模型,替换 SKILL.md 中的 API 配置即可。
  145. ## ⚠️ 已知限制
  146. - 目前针对 **旅行 Vlog** 优化,其他类型视频需调整 prompt 模板
  147. - 需要视觉理解 API(推荐智谱免费模型)
  148. - Whisper 转录在 CPU 上较慢(12分钟音频约3分钟)
  149. - BGM 自动生成需要额外的音乐 API(可选,也可以手动加 BGM)
  150. - macOS 的 Homebrew ffmpeg 通常没有 drawtext filter,Skill 中已用 Pillow 方案替代
  151. ## ⚠️ 踩坑合集
  152. SKILL.md 中记录了 24 条实战踩坑经验,这里列几个关键的:
  153. 1. **剪映 v10.4+ 项目文件加密** — 不要尝试程序化操作剪映
  154. 2. **xfade 链式合并会丢帧** — 用 concat 代替
  155. 3. **overlay 不要加 shortest=1** — PNG 只有1帧,会截断整个视频
  156. 4. **Whisper 会幻觉** — 纯环境音会编造文字,需用音量阈值过滤
  157. 5. **先短片段验证** — 每次改渲染方案先用 5-8 秒片段试
  158. 6. **预处理是建议不是硬裁剪** — LLM 可能觉得某个"口令"很有趣要保留
  159. 完整列表见 [SKILL.md](./SKILL.md) 的 Pitfalls 章节。
  160. ## 🤝 贡献
  161. 欢迎提 Issue 和 PR!特别欢迎:
  162. - 更多类型视频的 prompt 模板(美食探店、城市漫步、户外运动...)
  163. - 新的视觉模型适配
  164. - Dashboard 功能增强
  165. - 其他 Agent 平台的适配指南
  166. ## 👤 作者
  167. **nyx研究所** — [GitHub](https://github.com/znyupup) · [B站 @nyx研究所](https://space.bilibili.com/4330525) · 小红书 @nyx研究所 · [X / Twitter](https://x.com/znyupup_music)
  168. ## 📄 License
  169. MIT — 随便用,标注来源就行。
  170. ## 致谢
  171. - [ffmpeg](https://ffmpeg.org/) — 视频处理的瑞士军刀
  172. - [OpenAI Whisper](https://github.com/openai/whisper) — 语音转录
  173. - [智谱AI](https://open.bigmodel.cn/) — 免费视觉理解模型

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.