vlog-auto-edit

AI Agent 自动剪辑旅行 Vlog

Author: nyx研究所 · GitHub · B站 @nyx研究所 · 小红书 @nyx研究所 · X @znyupup_music

把一堆手机拍的旅行素材，用AI自动剪成一个完整vlog。 最小依赖：ffmpeg + Python(whisper或FunASR+Pillow) + 视觉API。系统级只装ffmpeg，其余pip装。

触发条件

• 用户有一批旅行/日常视频素材，想自动剪成vlog
• 用户说"帮我剪个视频"、"自动剪辑"、"vlog剪辑"

前置要求

1. 系统工具

工具	用途	安装
ffmpeg	视频裁剪/编码/拼接/抽帧/音量检测	brew install ffmpeg (macOS) / apt install ffmpeg (Linux)
Python 3.9+	脚本胶水	macOS/Linux 系统自带

2. Python依赖（先检测，已有则跳过）

先检测系统是否已安装所需包，不要无脑创建 venv：

# 检测 whisper
python3 -c "import whisper; print('✅ whisper已安装:', whisper.__file__)"

# 检测 Pillow
python3 -c "from PIL import Image; print('✅ Pillow已安装')"

⚠ 重要：不要用 2>/dev/null 吃掉错误！要看到实际报错才能判断是真没装还是PATH问题。

⚠ macOS 注意： 检查系统已安装的包再决定是否需要 venv。如果系统 python3 已经能 import whisper 和 from PIL import Image，直接用就行，不要盲目创建 venv 导致找不到已有的包。

仅在检测不通过时才安装：

# 方案A: 直接装到用户环境（推荐）
pip install openai-whisper Pillow

# 方案B: 如果用户环境有冲突，再用 venv
python3 -m venv .venv && source .venv/bin/activate
pip install openai-whisper Pillow

⚠ 不要每个项目都新建 venv 重装一遍！whisper模型文件1.4GB，pip install也要几分钟。

⚠ ASR引擎二选一：Whisper 或 FunASR

本工作流支持两个ASR引擎，优先用 whisper，whisper 装不上就用 FunASR：

	Whisper (OpenAI)	FunASR (阿里达摩院)
安装	pip install openai-whisper	pip install funasr modelscope torchaudio
模型	medium (1.4GB, 从GitHub下载)	paraformer-zh (1.05GB, 从ModelScope下载)
附加模型	无	VAD模型 + 标点模型 (首次运行自动下载, 共~50MB)
中文效果	好	好（与whisper medium相当，细节略多）
速度	14s音频 ≈ 5-10s (CPU)	14s音频 ≈ 1.9s (CPU, RTF=0.132) ⚡
时间戳粒度	句级别 (每句话一个start/end)	字级别 (每个字一个时间戳)
模型下载源	GitHub (国内不稳定，容易失败)	ModelScope (国内极快，~15MB/s)
隐性依赖	torch	torch + torchaudio (⚠ 必须额外装)

检测已安装的ASR引擎：

python3 -c "import whisper; print('✅ whisper可用')" 2>/dev/null \
  || python3 -c "from funasr import AutoModel; print('✅ funasr可用')" 2>/dev/null \
  || echo "❌ 没有可用的ASR引擎，需要安装一个"

⚠ FunASR 安装注意事项：

• 必须装 torchaudio！pip install funasr modelscope 不会自动装 torchaudio，import 时会报 No module named 'torchaudio'
• 正确安装命令：pip install funasr modelscope torchaudio
• 首次运行会自动从 ModelScope 下载3个模型（ASR + VAD + 标点），总共约1.1GB，国内速度快
• 模型缓存在 ~/.cache/modelscope/hub/models/iic/ 目录下
• import 时会有 urllib3 的 SSL 警告（NotOpenSSLWarning），可忽略，不影响功能

标题卡方案自动选择：

ffmpeg -filters 2>&1 | grep drawtext
# 有drawtext → 直接用ffmpeg，不需要Pillow
# 没有 → 用Pillow生成透明PNG再overlay（macOS brew ffmpeg通常没编freetype）

可选（参考分析阶段用）：

which yt-dlp && echo "✅ yt-dlp已安装" || pip install yt-dlp
python3 -c "import scenedetect" 2>/dev/null && echo "✅ scenedetect已安装" || pip install scenedetect

3. 视觉理解模型（API）

需要一个能理解图像内容的视觉模型API，用于分析素材画面。

要求：

• 支持 OpenAI Chat Completions 格式（messages + image_url）
• 支持 base64 图片输入（本地素材抽帧后编码上传）
• 中文理解能力（需要描述画面内容、标注镜头类型等）

推荐模型：

模型	费用	说明
智谱 GLM-4.6V-Flash	免费	注册 https://open.bigmodel.cn 即用，中文理解好
GPT-4o	付费	效果最好
Qwen-VL	付费	阿里云，中文好

调用示例：

import base64, json, urllib.request

API_URL = 'YOUR_VISION_API_ENDPOINT'   # 替换为你的视觉模型端点
API_KEY='***'               # 替换为你的API Key
MODEL = 'YOUR_MODEL_NAME'             # 替换为你的模型名

with open('frame.jpg', 'rb') as f:
    img_b64 = base64.b64encode(f.read()).decode()

payload = {
    'model': MODEL,
    'messages': [{'role': 'user', 'content': [
        {'type': 'image_url', 'image_url': {'url': f'data:image/jpeg;base64,{img_b64}'}},
        {'type': 'text', 'text': '简洁描述画面内容，标注：镜头类型(远/全/中/近/特写)、拍摄手法(固定/手持/移动)、画面氛围。格式：内容|类型|手法|氛围'}
    ]}],
    'max_tokens': 200
}

req = urllib.request.Request(API_URL, json.dumps(payload).encode(),
    {'Content-Type': 'application/json', 'Authorization': f'Bearer {API_KEY}'})
with urllib.request.urlopen(req, timeout=30) as resp:
    result = json.loads(resp.read())
    print(result['choices'][0]['message']['content'])

⚠ 视觉API调用注意事项：

• 输入格式：ffmpeg抽帧为JPEG → base64编码 → data:image/jpeg;base64,{b64} 放入 image_url
• 抽帧尺寸：不需要原始分辨率，缩到 720p 即可（节省上传带宽和token）
• 端点区分：有些平台视觉模型和文本模型端点不同，确认用对
• 限流：高峰时段容易被限流，加 retry + sleep

不需要的（踩过的坑）

• ❌ 剪映/CapCut — v10.4+ 项目文件加密，无法程序化操作
• ❌ moviepy — ffmpeg命令行已够用，多一层抽象反而不灵活
• ❌ capcut-cli (GitHub) — 基于明文JSON，对加密后的新版无效
• ❌ ImageMagick — Pillow已够用，不需要再装一个图像工具

工作流（7个阶段）

阶段1: 素材盘点

目标：了解你有什么素材。

# 批量获取素材信息
for f in footage/*.{MOV,mp4,MP4}; do
  echo "=== $f ==="
  ffprobe -v quiet -print_format json -show_format -show_streams "$f" \
    | python3 -c "import json,sys; d=json.load(sys.stdin); \
      s=d['streams'][0]; f=d['format']; \
      print(f\"  时长: {float(f['duration']):.1f}s\"); \
      print(f\"  分辨率: {s['width']}x{s['height']}\"); \
      print(f\"  编码: {s['codec_name']}\")"
done

输出一份素材清单：数量、总时长、分辨率分布、拍摄时间范围。

阶段2: 参考研究（可选但强烈建议）

目标：建立"好vlog长什么样"的认知。不做这步直接剪，效果会很差。

步骤：

1. 找2-3个同类型优质vlog（B站/YouTube）
2. yt-dlp 下载720p视频 + 音频
3. whisper 转录旁白（提取叙事结构）
4. scenedetect 检测镜头切换（统计节奏）
5. ffmpeg 抽关键帧 + 视觉API分析（理解画面构成）

已验证的规律：

• 镜头节奏: 平均3-4秒/镜头是黄金节奏
• 内容配比: 美食40-45% + 风景30% + 人物15% + 日常15%
• 镜头类型: 近景/中景为主(60-65%)，全景/远景穿插(35-40%)
• 叙事结构: 精彩片头 → 出发/到达 → 按地点串联 → 情感升华收尾
• 长短交替: 短镜头(<2s)做蒙太奇，长镜头(>8s)做叙事

剪辑教程要点：

1. 找侧重点，不要流水账
2. 三幕式结构: 25%悬念 + 50%发展 + 25%收尾
3. 精彩放片头
4. 情感占51%（Walter Murch六法则）

阶段3: 素材三维分析

目标：让AI理解每条素材的内容。每条素材做三维分析：

a) 音频分析 — ASR转录（Whisper 或 FunASR）

# 提取音频（16kHz单声道WAV，两个引擎通用的最佳输入格式）
ffmpeg -i footage/INPUT.MOV -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/audio.wav

方案1: Whisper转录（优先使用）

import whisper, json
model = whisper.load_model('medium')
result = model.transcribe('/tmp/audio.wav', language='zh')
segments = [{"start": s['start'], "end": s['end'], "text": s['text']} for s in result['segments']]
# 输出: [{"start": 0.5, "end": 2.3, "text": "我们现在在中央大街"}, ...]

方案2: FunASR转录（Whisper装不上时的替代）

import warnings
warnings.filterwarnings("ignore")
from funasr import AutoModel

model = AutoModel(
    model="paraformer-zh",      # Paraformer-large，中文ASR主模型(1.05GB)
    vad_model="fsmn-vad",       # 语音活动检测，自动切分静音段
    punc_model="ct-punc",       # 自动加标点
    log_level="ERROR",
    disable_update=True         # 跳过版本检查，加快启动
)

result = model.generate(input="/tmp/audio.wav")
text = result[0]["text"]        # 完整识别文本（已加标点）
timestamps = result[0].get("timestamp", [])  # 字级别时间戳 [[start_ms, end_ms], ...]

# ⚠ FunASR时间戳是字级别(毫秒)，需要聚合成句级别才能和whisper格式统一
# 聚合策略：按标点符号（。！？，）切分成句子
segments = []
if timestamps and text:
    puncs = set("。！？，,.!?")
    current_start = timestamps[0][0] / 1000.0
    current_text = ""
    chars = list(text)
    for i, (char, ts) in enumerate(zip(chars, timestamps)):
        current_text += char
        if char in puncs or i == len(chars) - 1:
            segments.append({
                "start": round(current_start, 1),
                "end": round(ts[1] / 1000.0, 1),
                "text": current_text.strip()
            })
            if i < len(chars) - 1:
                current_start = timestamps[i + 1][0] / 1000.0
            current_text = ""
# 输出格式与whisper一致: [{"start": 0.6, "end": 2.9, "text": "我们现在在中央大街的入口，"}, ...]

⚠ FunASR 输出差异注意：

• FunASR 返回的是完整文本 + 字级别时间戳，不像 whisper 直接给句级别 segments
• 上面的聚合代码把字级别时间戳按标点切分成句子，输出格式与 whisper 对齐
• 如果素材没有语音，FunASR 返回空文本 ""，timestamps 为空 []
• FunASR 速度比 whisper 快 3-5x（14s音频只需1.9s），批量处理时优势明显

b) 音量检测 — ffmpeg

ffmpeg -i footage/INPUT.MOV -af volumedetect -f null /dev/null 2>&1 | grep volume
# mean_volume: 平均音量(dB)  max_volume: 峰值音量(dB)
# mean < -40dB 基本无声  mean > -20dB 有明显声音/语音

c) 视觉分析 — ffmpeg抽帧 + 视觉理解模型

# 抽帧策略（按时长分段）
# ≤20s → 3帧(首/中/尾)
# 20-60s → 5帧
# >60s → 每15s一帧

# 抽首/中/尾三帧示例（缩到720p节省带宽）
ffmpeg -i footage/INPUT.MOV -vf "select=eq(n\,0),scale=1280:-1" -frames:v 1 -q:v 2 frame_start.jpg
ffmpeg -i footage/INPUT.MOV -vf "select=eq(n\,MIDDLE),scale=1280:-1" -frames:v 1 -q:v 2 frame_mid.jpg
ffmpeg -i footage/INPUT.MOV -vf "reverse,scale=1280:-1" -frames:v 1 -q:v 2 frame_end.jpg

d) 输出格式（每条素材一个JSON）

{
  "filename": "clip_001.MOV",
  "duration": 15.3,
  "resolution": "1920x1080",
  "visual": [
    {"time": "0:00", "description": "...", "shot_type": "近景", "camera": "手持", "mood": "温馨"}
  ],
  "audio": {
    "has_speech": true,
    "mean_volume_db": -20.5,
    "max_volume_db": -3.2,
    "transcript": [{"start": 0.5, "end": 2.3, "text": "..."}]
  }
}

阶段3.5: 素材精修预处理

目标：在给LLM之前，自动标注每条素材的"推荐有效区间"，让LLM专注叙事编排。

为什么需要这步： 原始手机素材普遍存在：开头录制口令、同一句话重复多遍、前1-2s举手机晃动、说完话后拖很长的无意义画面。如果把这些原始数据直接给LLM，LLM输出的plan还需要逐条修补。

预处理做四件事：

a) 录制口令检测

RECORDING_CUES = [
    "开始了", "好了开始", "开始录了", "好了 开始",
    "走了", "好了", "来了",  # 仅在前3s内出现时算口令
]

def detect_cues(transcript_segments, duration):
    """检测录制口令，返回skip zones"""
    skip_zones = []
    for seg in transcript_segments:
        text = seg['text'].strip()
        if seg['start'] < 3.0 and any(text.startswith(c) or text == c for c in RECORDING_CUES):
            skip_zones.append({
                'type': 'recording_cue',
                'range': [seg['start'], seg['end']],
                'text': text,
                'action': 'skip'
            })
        if seg['end'] > duration - 3.0 and text in ["好了", "走了", "好了 走"]:
            skip_zones.append({
                'type': 'recording_cue',
                'range': [seg['start'], seg['end']],
                'text': text,
                'action': 'skip'
            })
    return skip_zones

b) 音声の重複検出

from difflib import SequenceMatcher

def detect_repeats(segments, threshold=0.6):
    """检测重复语音，标记建议跳过的重复段"""
    repeats = []
    for i, a in enumerate(segments):
        for j, b in enumerate(segments):
            if j <= i: continue
            ratio = SequenceMatcher(None, a['text'], b['text']).ratio()
            if ratio >= threshold and len(a['text']) > 4:
                skip = a if len(a['text']) <= len(b['text']) else b
                repeats.append({
                    'type': 'repeat',
                    'range': [skip['start'], skip['end']],
                    'text': skip['text'],
                    'kept': b['text'] if skip == a else a['text'],
                    'action': 'suggest_skip'
                })
    return repeats

c) 冒頭の揺れ／末尾の引きずり検出

def detect_trim_points(segments, duration, mean_volume_db):
    """基于语音+音量推荐起止点"""
    suggested_start = 0.0
    suggested_end = duration

    if segments:
        first_speech = segments[0]['start']
        last_speech_end = segments[-1]['end']
        if first_speech > 2.0:
            suggested_start = max(0, first_speech - 0.5)
        if duration - last_speech_end > 3.0:
            suggested_end = last_speech_end + 1.5
    else:
        if duration > 5.0:
            suggested_start = 1.0

    return suggested_start, suggested_end

d) 映像のみの長さ制限

モード	映像のみの上限	音声の処理	重複の処理	冒頭の揺れ
strict	8-10s	すべて削除	1回だけ残す	1.5s削除
normal	12-15s	明確な掛け声を削除	明らかな重複を削除	1.0s削除
loose	20-25s	「始まった」だけ削除	大部分を残す	0.5s削除

e) 出力形式

前処理の結果を素材分析データに追加します。

━━━ clip_012.mp4 | 时长25.8s | 1920x1080 ━━━
  【画面】...
  【语音】...
  【精修建议】模式: normal
    原始区间: [0.0 - 25.8]
    推荐区间: [2.4 - 25.8]
    ⊘ [0.0-2.4] 跳过: 录制口令 "开始了"
    有效语音: [2.62-25.8]

⚠ 重要な原則：前処理は注釈と提案のみ行い、強制的なトリミングは行いません。最終決定権はLLMにあります。

フェーズ4：LLMによるナラティブ構成

目標：前処理済みの素材データをLLMに渡し、編集プランを生成します。

入力：素材分析＋精査の提案（推奨区間）＋参考調査の結論 出力：編集プランJSON（構造は以下のスキーマを参照）

edit_plan JSON Schema

{
  "title": "视频标题",
  "structure": [
    {
      "section": "段落名 — 副标题",
      "description": "本段落内容概述",
      "clips": [
        {
          "file": "素材文件名.mp4",
          "start": 0.0,
          "end": 12.0,
          "note": "画面内容简述",
          "subtitle": "保留的语音文字"
        }
      ]
    }
  ],
  "bgm_suggestion": "BGM风格建议（含genre/mood/instruments/tempo/bpm）",
  "editing_notes": "整体剪辑说明"
}

制約：

• 同じ素材を複数のclipに使用できます（時間区間は異なります）
• start/endで音声の途中を切らないでください（フェーズ4.5で検証します）
• 最初のsectionは「オープニング」のような導入部分を推奨します
• 最後のsectionは「エンディング」のような締めくくり部分を推奨します

詳細なプロンプトテンプレートは templates/edit_plan_prompt.md を参照してください。

フェーズ4+：ストーリーボードの可視化＋Dashboard（ブラウザプレビュー）

目標：LLMの出力した編集プランを、ユーザーが直感的にレビューできる、図や画像を含むWebページにします。

Dashboardには2つのパネルがあります：

1. 📋 素材一覧 — 素材のサムネイルグリッド＋長さ／音声／音量の注釈＋フィルター（すべて／使用済み／未使用／音声あり）＋クリックして詳細を表示
2. ✅ 完成動画の品質チェック — 完成動画から30秒ごとにフレームを抽出＋セクションの位置表示＋クリックして拡大

gen_dashboard.py スクリプトを使用します：

# 最小用法（只生成素材面板）
python3 scripts/gen_dashboard.py \
  --analysis clip_analysis.json \
  --plan edit_plan.json \
  --footage footage/ \
  --out output/

# 完整两面板（含成品QC帧）
python3 scripts/gen_dashboard.py \
  --analysis clip_analysis.json \
  --plan edit_plan.json \
  --footage footage/ \
  --video output/final.mp4 \
  --out output/

2種類の分析データ形式に対応しています（自動検出）：

• 標準形式 clip_analysis.json：{filename, duration, visual: [...], audio: {...}}
• コンパクト形式 clips_compact.json：{file, dur, visual: "string", speech: [...]}

ユーザーがストーリーボードを確認した後、レンダリングに進みます。

フェーズ4.5：音声の途中切れ検証

目標：LLMの出力したplanを自動検証し、音声を途中で切っていないことを確認します。

def validate_speech(plan_clips, speech_data):
    """检查每个clip的start/end是否截断了语音"""
    issues = []
    for clip in plan_clips:
        f = clip['file']
        cs, ce = clip['start'], clip['end']
        if f not in speech_data: continue
        for ss, se, txt in speech_data[f]:
            if ss < ce and se > cs:  # 语音与clip有交集
                if ss < cs - 0.3:    # 语音开始在clip之前
                    issues.append(f"截断开头: {f} clip从{cs}开始，但语音\"{txt}\"从{ss}开始")
                if se > ce + 0.5:    # 语音结束在clip之后
                    issues.append(f"截断结尾: {f} clip在{ce}结束，但语音\"{txt}\"到{se}结束")
    return issues

検証に失敗した場合：start/endを自動修正するため、LLMに戻って再構成する必要はありません。

自動修正ロジック

def fix_speech_cuts(plan, speech_data, margin=0.3):
    """
    自动修复语音截断问题。直接修改plan中的start/end。
    
    参数:
        plan: edit_plan dict (会被原地修改)
        speech_data: dict, {filename: [(start, end, text), ...]}
        margin: float, 语音边界容差(秒)
    
    返回:
        fixes: list of str, 修复日志
    """
    fixes = []
    
    for sec in plan["structure"]:
        for clip in sec["clips"]:
            f = clip["file"]
            cs = float(clip["start"])
            ce = float(clip["end"])
            
            if f not in speech_data:
                continue
            
            for ss, se, txt in speech_data[f]:
                if ss >= ce or se <= cs:
                    continue
                
                # 开头截断：clip.start > speech.start + margin
                if ss < cs - margin and se > cs:
                    old_start = cs
                    new_start = max(0, ss - 0.1)
                    clip["start"] = round(new_start, 1)
                    fixes.append(
                        f"  修复开头: {f} [{old_start}→{new_start}] "
                        f"语音\"{txt[:20]}\"从{ss}s开始"
                    )
                    cs = new_start
                
                # 结尾截断：clip.end < speech.end - margin
                if se > ce + margin and ss < ce:
                    old_end = ce
                    new_end = se + 0.2
                    clip["end"] = round(new_end, 1)
                    fixes.append(
                        f"  修复结尾: {f} [{old_end}→{new_end}] "
                        f"语音\"{txt[:20]}\"到{se}s结束"
                    )
                    ce = new_end
    
    return fixes


def validate_and_fix(plan, speech_data):
    """
    端到端校验+修复入口。
    
    用法:
        import json
        # 加载plan
        plan = json.load(open('edit_plan.json'))
        # 加载语音数据 (格式: {filename: [{start, end, text}, ...]})
        raw = json.load(open('clip_analysis.json'))
        speech_data = {}
        for clip_info in raw:
            fname = clip_info['filename']
            if clip_info['audio']['has_speech']:
                speech_data[fname] = [
                    (s['start'], s['end'], s['text'])
                    for s in clip_info['audio']['transcript']
                ]
        
        # 校验
        all_clips = [c for sec in plan['structure'] for c in sec['clips']]
        issues = validate_speech(all_clips, speech_data)
        print(f'发现 {len(issues)} 个截断问题')
        
        # 修复
        fixes = fix_speech_cuts(plan, speech_data)
        print(f'自动修复 {len(fixes)} 处')
        
        # 二次校验确认
        all_clips2 = [c for sec in plan['structure'] for c in sec['clips']]
        issues2 = validate_speech(all_clips2, speech_data)
        assert len(issues2) == 0, f'仍有 {len(issues2)} 个问题未修复!'
        print('✅ 二次校验通过')
        
        # 保存修复后的plan
        json.dump(plan, open('edit_plan_fixed.json', 'w', ensure_ascii=False), indent=2)
    """
    all_clips = [c for sec in plan['structure'] for c in sec['clips']]
    issues = validate_speech(all_clips, speech_data)
    fixes = fix_speech_cuts(plan, speech_data)
    return issues, fixes

修正戦略：

切断の種類	検出条件	修正方法
冒頭の切断	clip.start > speech.start + margin	clip.start → speech.start - 0.1s
末尾の切断	clip.end < speech.end - margin	clip.end → speech.end + 0.2s

境界の許容誤差（margin=0.3s）： Whisper/FunASRのタイムスタンプには±0.2-0.3sの誤差があります。修正後は必ず2回目の検証を実行してください。

フェーズ5：ffmpegによる自動実行

目標：編集プランをffmpegコマンドに変換して実行します。

レンダリング戦略：各クリップをトリミングしてから連結

# 单个片段裁剪+编码
ffmpeg -y -ss 00:00:02.400 -i footage/INPUT.mp4 -t 00:00:23.400 \
  -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,setsar=1" \
  -r 30 -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p \
  -c:a aac -b:a 128k -ar 44100 -ac 2 \
  -movflags +faststart segments/seg_001.mp4

# 拼接成品
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy -movflags +faststart output.mp4

速度変更

# 2倍速（视频+音频同步）
ffmpeg -i input.mp4 -filter:v "setpts=0.5*PTS" -filter:a "atempo=2.0" out.mp4

オープニングのハイライトモンタージュ

各セクションから視覚的に最もインパクトのあるショットを選び、素早く切り替えながら連結して動画の冒頭に配置します。

ショット選択の原則：

• 主要なセクションごとに印象的な映像を1つ選びます
• 各ショットは0.5-1秒、テンポよく切り替えます
• 全体で6-10ショット、合計時間は5-8秒です
• 縦向きの素材は除外します
• 音声は追加しません（-an）。最終的にBGMで覆います

import subprocess, os

highlights = [
    ('footage/clip_a.mp4',   1.5, 2.2),
    ('footage/clip_b.mp4',   2.0, 2.7),
    # ... 每个0.7秒左右
]

for i, (f, start, end) in enumerate(highlights, 1):
    dur = end - start
    cmd = f'ffmpeg -y -ss {start} -i "{f}" -t {dur} ' \
          f'-vf "scale=1920:1080:force_original_aspect_ratio=decrease,' \
          f'pad=1920:1080:(ow-iw)/2:(oh-ih)/2" ' \
          f'-c:v libx264 -preset ultrafast -crf 23 -pix_fmt yuv420p ' \
          f'-an highlights/hl_{i}.mp4'
    subprocess.run(cmd, shell=True)

# concat
with open('highlights/concat.txt', 'w') as f:
    for i in range(1, len(highlights)+1):
        f.write(f"file 'hl_{i}.mp4'\n")

subprocess.run('ffmpeg -y -f concat -safe 0 -i highlights/concat.txt '
               '-c copy highlights/montage.mp4', shell=True)

セクションタイトルの重ね合わせ

Pillowで透明なRGBAのPNGを生成し、ffmpeg overlayで動画に重ねます。黒背景のタイトルカードは使用しないでください。

from PIL import Image, ImageDraw, ImageFont, ImageFilter

W, H = 1920, 1080
title = "段落标题"

img = Image.new("RGBA", (W, H), (0, 0, 0, 0))
draw = ImageDraw.Draw(img)

# 字体：macOS用冬青黑体，Linux用Noto Sans CJK
# font = ImageFont.truetype("/System/Library/Fonts/Hiragino Sans GB.ttc", 60)  # macOS
# font = ImageFont.truetype("/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", 60)  # Linux
font = ImageFont.truetype("YOUR_FONT_PATH", 60)

bbox = draw.textbbox((0, 0), title, font=font)
tw, th = bbox[2] - bbox[0], bbox[3] - bbox[1]
x, y = (W - tw) // 2, (H - th) // 2

# 柔和阴影
shadow = Image.new("RGBA", (W, H), (0, 0, 0, 0))
sd = ImageDraw.Draw(shadow)
sd.text((x+2, y+2), title, fill=(0, 0, 0, 180), font=font)
shadow = shadow.filter(ImageFilter.GaussianBlur(radius=6))

img = Image.alpha_composite(img, shadow)
draw = ImageDraw.Draw(img)
draw.text((x, y), title, fill=(255, 255, 255, 240), font=font)
img.save("title_overlay.png")

動画に重ね合わせます：

# 标题显示前3秒
ffmpeg -y -i section.mp4 -i title.png \
  -filter_complex "overlay=0:0:enable='between(t,0,3)'" \
  -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p \
  -c:a aac -b:a 128k -movflags +faststart \
  section_titled.mp4

⚠ overlayに関する重要な落とし穴：

• ❌ shortest=1 は追加しないでください — PNGは1フレームしかないため、動画ストリームがすぐに切り詰められます
• ✅ overlay=0:0:enable='between(t,0,3)' を直接使うのが、最も簡単で確実です
• ✅ まず短いクリップ（5-8s）でoverlayの効果を確認してください

セクションの連結（推奨方式）

✅ 正しい方式：各セクションを個別にエンコード → concat copy

echo "file 'final_sec_01.mp4'" > concat.txt
echo "file 'final_sec_02.mp4'" >> concat.txt
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy -movflags +faststart output.mp4

❌ xfadeチェーンによる結合は使用しないでください： xfadeチェーンではフレーム数が累積的に失われ、後半がすべて真っ黒になります。

セクション間のトランジション：セクション内はハードカットで構いません。フェードが必要な場合は、xfadeよりも各セクションの冒頭と末尾にfadeを加えるほうが確実です。

BGMの生成とミキシング（任意）

BGMは手動で追加することも、AI音楽生成ツール（MiniMax music、Sunoなど）を使用することもできます。

a) AIによるBGM生成

スタイルの対応例（vlogでよく使われるもの）：

Vlogのスタイル	genre	mood	instruments	tempo
気軽な日常	indie pop	cheerful, carefree	ukulele, acoustic guitar	moderate
文芸的で癒やし系	folk, acoustic	warm, gentle	acoustic guitar, piano, strings	slow
グルメ・飲食店めぐり	jazz, bossa nova	cozy, playful	piano, upright bass	moderate
雪・冬	cinematic, ambient	serene, majestic	piano, celesta, strings	slow
熱帯・島	tropical house	sunny, relaxed	steel drums, marimba	upbeat
都市探訪	lo-fi hip hop	chill, urban	keys, vinyl crackle	moderate

b) 動画へのミキシング

# BGM 音量 10-15%（有语音的vlog要压低BGM）
ffmpeg -y -i video_no_bgm.mp4 -i bgm.m4a \
  -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]" \
  -map 0:v -map "[aout]" -c:v copy -c:a aac -b:a 192k \
  -movflags +faststart output/final.mp4

BGMの音量の目安：

• 音声／ナレーションが多い場合 → 8-12%
• 音声が少なく、風景映像が中心の場合 → 15-25%
• 風景映像のみのモンタージュの場合 → 30-40%

速度変更

ffmpeg -i input.mp4 -filter:v "setpts=0.5*PTS" -filter:a "atempo=2.0" out.mp4

注意点

1. 剪映は使用できません — v10.4以降は draft_info.json が暗号化されているため、時間を無駄にしないでください
2. ビジョン API のエンドポイントを区別してください — プラットフォームによっては、ビジョンモデルとテキストモデルでエンドポイントが異なります。正しいものを使っているか確認してください
3. Whisper モデルの選択 — base は中国語の精度が低く、large は遅すぎます。medium が最もコストパフォーマンスに優れています
4. 参考資料の調査を省略しないでください — 「良い Vlog の基準」を知らない AI は、単調な動画に編集してしまいます
5. ffmpeg のエンコード互換性 — 結合時は素材のエンコード形式を統一してください。まず各クリップを個別に同じ形式へエンコードしてから concat します
6. ビジョン API のレート制限 — ピーク時間帯は制限されやすいため、retry と sleep を追加してください
7. LLM の前に前処理を行ってください — 口癖／重複／手ブレの検出はステージ3.5で処理します
8. 前処理は提案であり、強制的なカットではありません — LLM が保持するかどうかを判断できます。口癖によっては物語上の価値がある場合もあります
9. 音声の途切れを必ず自動検証してください — LLM が出力した plan が音声の途中で切れている場合があります
10. Whisper の幻覚 — 音楽のみ／環境音のみの区間では、Whisper が文字を捏造することがあります。音量しきい値（-40dB）でフィルタリングしてください
11. 縦向きと横向きの混在 — 素材分析の段階で検出してください。縦向き（9:16）の映像が横向きの中に混ざると非常に違和感があるため、取り除くことをおすすめします
12. overlay に shortest=1 を付けないでください — PNG は1フレームしかないため、shortest=1 を付けると動画ストリームが途切れます
13. タイトルカードのスタイル — 動画の上に白文字＋柔らかな影を重ねます。黒背景のタイトルカードは使わないでください
14. ffmpeg の drawtext は使用できません — macOS の Homebrew 版 ffmpeg はデフォルトで freetype を有効にしてコンパイルされていないため、代わりに Pillow で PNG overlay を生成してください
15. HEVC の警告は無視できます — 「Error constructing the frame RPS」は HEVC のデコード警告であり、出力には影響しません
16. Non-monotonic DTS — concat での結合時によく見られるタイムスタンプ警告です。再生には影響しません
17. 無音の映像を長くしすぎないでください — 音声のない映像のみの区間が6秒を超えると長すぎます。5～8秒に短縮することをおすすめします
18. xfade の連鎖結合は信頼できません — xfade を連鎖させるとフレーム数が累積して失われ、後半がすべて黒くなります。代わりに concat を使ってください
19. まず短いクリップで検証してください — レンダリング方法を変更するたびに、まず5～8秒の短いクリップで効果を検証してください
20. レンダリング後は必ずフレーム数を検証してください — ffmpeg -i output.mp4 -f null - で実際のフレーム数を確認します
21. BGM の音量を上げすぎないでください — 音声がある区間では BGM を8～12％に抑え、試聴してから決めてください
22. 複数の BGM をつなぐ場合 — キーとテンポを近づけてください（bpm の差は20未満）
23. ミキシング後は必ず試聴してください — 素材によって元の音量に大きな差があります
24. 依存関係を繰り返しインストールしないでください — whisper／Pillow などは、まずインストール済みか確認してください。毎回新しい venv を作成しないでください
25. FunASR には torchaudio のインストールが必須です — pip install funasr modelscope だけでは不十分です。必ず pip install funasr modelscope torchaudio を実行してください。そうしないと、import 時に No module named 'torchaudio' が発生します
26. FunASR のタイムスタンプは文字単位です — whisper のように文単位の segments を直接返すのではなく、FunASR は各文字の [start_ms, end_ms] を返します。後続の音声途切れ検証（ステージ4.5）で使えるよう、句読点に基づいて文にまとめる必要があります
27. FunASR の幻覚は whisper より少なめです — 環境音のみ／音楽のみの場合、FunASR は通常空のテキストを返し、whisper のように内容を捏造しません。ただし、音量しきい値（-40dB）を使った再確認は必要です

エンコードと結合に関する注意点（動画チュートリアルの実践から追加）

28. ⚠️ atempo で速度を上げると、音声と動画の長さが一致しません — atempo の処理後、音声は動画より1区間あたり0.4～0.8秒短くなります。8区間では数秒の差が累積し、後半では映像と音声が完全にずれてしまいます。各区間の編集後、音声と動画の長さの差が必ず<0.05sであることをすぐに検証してください。それを超える場合は apad で補います：

# 验证
ffprobe -show_entries stream=duration -select_streams v -of csv=p=0 seg.mp4  # 视频时长
ffprobe -show_entries stream=duration -select_streams a -of csv=p=0 seg.mp4  # 音频时长
# 补齐
ffmpeg -y -i seg.mp4 -af "apad" -c:v copy -c:a aac -shortest seg_fixed.mp4

29. ⚠️ concat copy では音声のタイムスタンプが連続しません — 複数の区間を concat copy で結合すると、音声にプツプツとしたノイズが発生したり、剪映で映像と音声がずれたりします。正しい方法：音声を個別に wav として抽出し、apad で長さを補ってから concat filter で結合します。動画は個別に concat copy し、最後に結合します：

# 每段提取音频（apad补齐到视频时长）
ffmpeg -y -i seg.mp4 -vn -af "apad" -ar 48000 -ac 2 -c:a pcm_s16le -t {视频时长} seg.wav
# concat filter拼接音频（不是demuxer）
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
# 合并
ffmpeg -y -i video.mp4 -i audio.m4a -c:v copy -c:a copy output.mp4

30. 剪映と互換性のあるエンコード — 剪映に読み込んだときの映像と音声のずれを修正するには、-r 30 -vsync cfr（固定フレームレート）＋-x264-params "bframes=0"（B フレームなし）＋-ar 48000 -ac 2（音声形式を統一）を指定します

31. 画面録画のコンテンツでは crf 値を低くしてください — 画面録画は文字が多いため、crf 22 ではビットレートが足りず、ぼやけることがあります。画面録画には -crf 18 または -b:v 3M を使ってください。一般的な Vlog 素材なら crf 22 で問題ありません

32. 再エンコードを重ねると画質が累積して劣化します — 編集→結合→背景追加→進行状況バーの重ね合わせを行うたびに、画質が劣化します。できるだけ1つの filter チェーンで処理を完了し、エンコード回数を減らしてください

33. バックグラウンドの ffmpeg プロセスが残ることがあります — バックグラウンドタスクを kill すると、shell だけが終了して ffmpeg の子プロセスが残る場合があります。kill のたびに ps aux | grep ffmpeg で確認し、残っているプロセスには kill -9 PID を実行してください

34. 作業を始める前に、まず出力解像度を確認してください — 全工程で解像度を統一し、途中で変更しないでください。画面録画には1080p（文字が多く、解像度に敏感なため）、Vlog 素材には元の解像度または1080pを使ってください

35. ⚠️ 動画に overlay を重ねると、音声が上書き／消失することがあります — filter_complex overlay で進行状況バー／ウォーターマークなどの動画を重ねると、ffmpeg が元動画の音声ではなく overlay 元（無音）の音声を自動選択する場合があります。-map を使って音声ソースを明示的に指定してください：

# ❌ 不指定map，音频可能来自overlay源（静音）
ffmpeg -i main.mp4 -i overlay.mp4 -filter_complex "overlay=0:0" output.mp4

# ✅ 明确map：视频取filter输出，音频取原视频
ffmpeg -i main.mp4 -i overlay.mp4 \
  -filter_complex "[0:v][1:v]overlay=0:0[vout]" \
  -map "[vout]" -map 0:a \
  -c:v libx264 -c:a copy output.mp4

それでも解決しない場合（音声のコーデックの問題）は、手順を分けて処理するほうが確実です：

# Step1: 只处理视频（-an去掉音频）
ffmpeg -i main.mp4 -i overlay.mp4 -filter_complex "overlay" -map "[vout]" -an video_only.mp4
# Step2: 把原始音频合回来
ffmpeg -i video_only.mp4 -i main.mp4 -map 0:v -map 1:a -c:v copy -c:a copy final.mp4

36. ⚠️ -shortest は音声を途中で切ることがあります — 動画と音声の長さが完全に一致していない場合、-shortest によって最後の数秒の音声が失われます。代わりに -t {精確时长} を使うことを優先してください。または、音声と動画の長さを一致させたうえで -shortest を付けずに処理してください

エンドツーエンドの例

プロジェクトのファイル構成

my-vlog-project/
├── footage/                    # 原始素材（用户提供）
│   ├── clip_001.MOV
│   └── ...
│
├── analysis/                   # 阶段3输出
│   └── clip_analysis.json
│
├── edit_plan.json              # 阶段4输出
├── edit_plan_fixed.json        # 阶段4.5输出
│
├── output/
│   ├── dashboard.html          # Dashboard网页
│   ├── thumbnails/             # 素材缩略图
│   ├── qc_frames/              # 成品QC帧
│   ├── segments/               # 裁剪后的片段
│   ├── highlights/             # 片头高光蒙太奇
│   ├── titles/                 # 段落标题PNG
│   ├── sections/               # 带标题的段落视频
│   ├── bgm/                    # BGM文件
│   ├── video_no_bgm.mp4        # 无BGM的完整视频
│   └── final.mp4               # 🎬 成品视频
│
└── reference/                  # 阶段2输出（可选）

中間生成物の例

examples/ ディレクトリ内のサンプルファイルを参照してください。

実行フロー早見表

素材文件夹 footage/
     │
     ▼
 阶段1: 素材盘点 → ffprobe批量扫描 → 清单
     │
     ▼
 阶段2: 参考研究 → 下载优质vlog → 分析节奏（可选）
     │
     ▼
 阶段3: 素材三维分析 → whisper/FunASR+音量+视觉 → clip_analysis.json
     │
     ▼
 阶段3.5: 精修预处理 → 口令/重复/晃动/纯画面标注
     │
     ▼
 阶段4: LLM叙事编排 → edit_plan.json
     │
     ▼
 阶段4+: Dashboard可视化 → 浏览器预览确认
     │
     ▼
 阶段4.5: 语音截断校验 → 自动修复
     │
     ▼
 阶段5: ffmpeg渲染 → 裁剪→标题→拼接→BGM → final.mp4 🎬

検証

• 素材の棚卸しが完了し、一覧を生成した
• 参考資料の調査が完了し、傾向を抽出した
• 素材の三次元分析が完了した（映像＋音声＋音量）
• 素材の仕上げ前処理が完了した
• LLM の編集プランを生成した
• 音声の途切れの検証に合格した
• 各クリップの音声と動画の長さの差が<0.05s
• ffmpeg の実行に成功し、完成動画を出力した
• 完成動画の音声が完全である（-shortest で切られていない）
• 動画の後半に移動して、映像と音声の同期を確認した
• 完成動画の品質を人手で確認した

---

Author： nyx研究所 · GitHub · B站 · 小紅書 @nyx研究所 License： MIT