remotion-mashup-video

name	remotion-mashup-video
description	用 Remotion（React + TypeScript）代码化生成短视频：零碎片段混剪（fade 渐变转场 + 字幕关键词聚焦标记）、16:9/9:16 双尺寸、双语字幕、30 秒讲解视频，支持 yt-dlp 嗅探下载 YouTube 素材（tv_android 破解 403）+ VLM 视频理解自动标重点的完整闭环。 触发词：混剪视频、渐变转场、聚焦标记、讲解视频、Remotion 视频、双语字幕、 VLM 自动标重点、YouTube 下载、嗅探下载、视频理解。
agent_created	true
version	1.1.0

Remotion 混剪/讲解视频生成

基于 Remotion 4（React + TypeScript 写视频）的代码驱动视频生成工作流。 核心信条：视频不是堆特效，是信息传达的效率——数据驱动、改数据即改片。

何时使用

• 用户要「把零碎视频片段混剪成一条视频，带转场」
• 用户要「讲解视频 / 30 秒科普 / 产品介绍短视频」
• 用户要「渐变转场 / 关键词聚焦标记 / 双语字幕」
• 用户要「VLM 自动识别视频内容并标记重点」
• 用户要「嗅探下载 YouTube/B站 素材做科普混剪」（skillhub/clawhub universal-video-downloader 方案的落地替代）
• 平台：B站/YouTube 16:9 横屏（1920×1080）或 抖音 9:16 竖屏（1080×1920）

环境准备（Windows 注意）

# 工程依赖（关键：--legacy-peer-deps 绕过 React19 ERESOLVE）
cd remotion-videos
export npm_config_cache="$PWD/.npm-cache"   # 绕过系统 AppData EACCES 权限坑
npm install --legacy-peer-deps --no-audit --no-fund
npm install lucide-react --legacy-peer-deps --no-audit --no-fund   # 讲解视频图标库

# 渲染（无需系统 ffmpeg，用 ffmpeg-static；用项目内 cache 规避权限）
export npm_config_cache="$PWD/.npm-cache"
./node_modules/.bin/remotion render <composition-id> out/xxx.mp4 --concurrency=2

渲染环境修坑（必做一次）

Remotion 首次渲染要下载 Chrome Headless Shell。若因 safe-delete 钩子/版本校验失败， 在 remotion.config.ts 钉死已下载二进制，跳过下载：

import { Config } from "@remotion/cli/config";
Config.setVideoImageFormat("jpeg");
Config.setOverwriteOutput(true);
Config.setBrowserExecutable(
  "C:/.../remotion-videos/node_modules/.remotion/chrome-headless-shell/win64/chrome-headless-shell-win64/chrome-headless-shell.exe"
);

• fade 必须是子路径导入：import { fade } from "@remotion/transitions/fade";（主入口没有！）
• 验证：./node_modules/.bin/tsc --noEmit -p tsconfig.json

核心组件结构（可复用模板）

src/compositions/mashup/           # 混剪（零碎视频 → 渐变转场 + 聚焦）
  types.ts       # Clip {id,src,placeholderColor,durationInFrames,captions[],fit} / Caption {text,translation?,start,end} / FocusConfig {keywords[],label?}
  data.ts        # 编辑区：clips[] / focusConfig / TRANSITION_FRAMES；横屏用 landscapeClips
  ClipScene.tsx  # 单片段：视频/占位 + 双语字幕（原文白+翻译金）+ 聚焦逻辑（s=height/1080 自适应）
  FocusMarker.tsx# 暗角 radial-gradient + 右上角「重点：关键词」标签（中央光圈已按用户要求移除）
  MashupVideo.tsx# TransitionSeries 串联 + fade() 渐变转场（props 传 clips/focusConfig）
src/compositions/explain/          # 30 秒讲解（场景制）
  data.ts        # scenes[]（kicker/title/subtitle/accent/icon/focusKeyword）+ 画布/帧率/场景时长
  ExplainScene.tsx # 渐变背景 + lucide 图标 + 大字标题 + 副标题 + 右上角重点标签
  ExplainVideo.tsx # 场景间 fade 转场
  IconMap.tsx    # icon 类型 → lucide-react 组件映射
src/Root.tsx     # 注册 composition（竖屏/横屏/横屏VLM/30s讲解）

关键实现细节：

• 渐变转场：TransitionSeries + <TransitionSeries.Transition presentation={fade()} timing={linearTiming({durationInFrames})} />
• 关键词聚焦：字幕文本（含 translation）命中 focusConfig.keywords → focusProgress 平滑进出 → 暗角 + 画面放大 1.06x + 右上角「重点：关键词」标签
• 尺寸自适应：组件内 const s = height/1080，所有字号/尺寸乘 s，竖屏横屏共用一套组件

数据驱动（改数据即改片）

• 混剪：编辑 data.ts 的 clips[]（src 填 staticFile("assets/xxx.mp4") 或远程 URL）与 focusConfig.keywords
• 讲解：编辑 scenes[] 的文案/配色/图标
• 关键词命中即触发聚焦标记，无需改组件

YouTube 嗅探下载（yt-dlp，含 403 破解）

素材准备：先搜索主题最新/综合评分最好的视频 → 嗅探下载 1080p 片段 → 截取/合并 → VLM 理解。

# 依赖
$VENV/Scripts/python.exe -m pip install yt-dlp

# ① 下载（关键：--extractor-args "youtube:player_client=tv_android" 破解 HTTP 403）
#    -4 强制 IPv4；限 1080p 视频流 + 音频流并合并为 mp4
python -m yt_dlp --extractor-args "youtube:player_client=tv_android" -4 \
  -f "bv*[height<=1080]+ba/b[height<=1080]" --merge-output-format mp4 \
  -o "work/yt_downloads/%(id)s.%(ext)s" "URL"

# ② 截取 10-20s 片段（科普混剪通常取主题核心段落）
ffmpeg -y -ss 12 -t 20 -i work/yt_downloads/XXXX.mp4 \
  -c:v libx264 -c:a aac -movflags +faststart work/clips/clip1.mp4

403 破解排障顺序（本机验证）：直连 403 → --cookies-from-browser chrome（无 Chrome）→ edge（cookie 库被占用）→ web_safari（无格式）→ tv_android 成功。不同机器 cookie 情况不同，按此顺序逐个尝试。

合规守卫（脚本内置）：仅允许 CC/授权/自有内容，--cc-licensed / --i-own-this 二选一， 未声明直接拒绝。科普二次创作/引用必须附完整出处（B站发布文案带来源链接）。

VLM 自动标重点（aiping Qwen3-VL）

pipeline/（Python）实现「视频理解 → 自动生成聚焦数据」闭环：

# 依赖：装到托管 venv（Windows 用 Scripts\python.exe）
python -m venv C:/Users/<user>/.workbuddy/binaries/python/envs/default
$VENV/Scripts/python.exe -m pip install openai yt-dlp faster-whisper bilibili-api

# ① 视频理解（key 走环境变量，不写文件）
AIPING_API_KEY=xxx python pipeline.py understand video.mp4 --json
# ② keypoints → Remotion data.ts 片段
python pipeline.py gen-data video.mp4.keypoints.json
# ③ 追加进 data.ts → remotion render

• 抽帧：ffmpeg -i in.mp4 -vf fps=N/dur out_%03d.jpg（无需 ffprobe）
• VLM 调用：OpenAI 兼容接口，帧 base64 内联 image_url，流式聚合 reasoning_content+content
• 已知坑：VLM 常把 JSON 包在 json 围栏里 → gen-data 解析失败。模板脚本的 `_load` 已加正则剥离 `^(json)?\s*/\s*```$`，若自写脚本必须处理
• VLM keypoints 偏「画面描述」→ 生成字幕时融合视频真实主题人工精修（例：大模型科普 → 预测下一个词/Token/注意力/应用）
• 合规守卫：YouTube 下载仅限 CC/授权/自有内容（--cc-licensed / --i-own-this），未声明直接拒绝

30 秒真实视频混剪模板（llmClips）

把 3 个真实科普视频各截 10s 片段 + 手写双语字幕 + 关键词聚焦，拼成 30s 科普混剪：

// data.ts —— 结构示例（src 指向 public/llm/ 下的本地片段）
export const llmClips: Clip[] = [
  { id: "clip-1", src: staticFile("llm/LPZh9BOjkQs.mp4"),
    durationInFrames: 300, // 10s @30fps
    captions: [
      { text: "LLMs predict the next token", translation: "大模型预测下一个词",
        start: 0, end: 300 },
    ] },
  // ...共 3 个片段，每个 10s，总长 30s
];
export const focusConfigLLM: FocusConfig = {
  keywords: ["LLM", "token", "attention", "大模型", "Token", "注意力", "预测", "推理"],
  label: "重点",
};

• 片段时长 10s × 3 = 30s，TransitionSeries 转场帧重叠约 0.5s，总时长 31s 左右
• 渲染：remotion render mashup-llm-30s out/llm-30s.mp4（composition 在 Root.tsx 注册， defaultProps={{ clips: llmClips, focusConfig: focusConfigLLM }}）
• 发布 B站文案必须带出处：标题 + 简介列 3 个来源视频链接 + 授权/引用声明

交付

• 渲染产物：remotion-videos/out/*.mp4，复制到工作区根 产物/ 便于用户查看
• 用 present_files 展示 mp4 + 概览文档

边界

• 复杂转场/特效/混音建议专业软件（剪映/PR/达芬奇）；Remotion 擅长数据驱动+程序化生成
• 音乐/素材版权必须合规；B站自动上传有平台风控，先人工核对
• 渲染耗时：视频越长越慢，交付前告知用户预估时间