VideoDB Skill 是 Everything Claude Code 插件体系中专为视频和音频场景设计的多功能能力组件。它支持本地、URL、RTSP/直播流和桌面录制的多源视频摄取，自动构建视觉/语义/时间索引，实现秒级内容搜索、自动剪辑、字幕与配音生成、时间线编辑、实时流事件监控与告警。开发者无需手写 ffmpeg 等本地脚本，即可一站式完成多媒体 ingest、分析、编辑与自动化流转，极大提升 AI 辅助编程效率与产品力。

Everything Claude Code VideoDB Skill：视频摄取、索引搜索、时间线编辑与实时流 AI 分析

在 AI 编程助手的实际项目中，如何让 Claude Code 等 Agent 具备“看懂视频、理解内容、自动编辑、实时监控”的能力？VideoDB Skill 正是为此而生。它将视频/音频的摄取、索引、搜索、编辑、实时流分析等环节全流程打通，极大简化了开发者在多媒体自动化场景下的操作复杂度。本文将结合实际项目场景，详细讲解 VideoDB Skill 的激活时机、使用流程、典型输出、常见 Agent 配合与最佳实践。

1. VideoDB Skill 能解决什么问题？

传统做法的痛点：

• 需要手动用 ffmpeg、moviepy 等本地工具处理视频，脚本复杂且难以自动化；
• 视频内容搜索、自动剪辑、字幕/配音生成等需多工具集成，流程割裂，难以与 AI Agent 流畅协作；
• 实时流（如 RTSP 监控、桌面录屏）事件检测、自动告警实现门槛高，难以和业务流无缝集成；
• 视频时间线编辑、素材拼接、AI 生成内容等需手动操作，自动化程度低。

有了 VideoDB Skill 后：

• 支持本地文件、URL、YouTube、RTSP 流、桌面录屏等多源摄取，自动转码、标准化格式；
• 自动构建视觉、语音、关键词等多维索引，支持按内容/场景/字幕秒级搜索并自动生成剪辑片段；
• 一行代码即可生成/翻译/烧录字幕、添加文字/图片/品牌/配音/音乐等时间线编辑操作；
• 支持实时流与桌面会话的 AI 事件检测与自动告警，输出可追溯的证据流和摘要；
• 所有操作均为云端 API/SDK 调用，无需本地安装 ffmpeg，支持异步、回调和批量自动化。

2. 典型触发场景与激活条件

VideoDB Skill 会在如下场景自动激活或建议使用：

• 用户请求摄取/分析/编辑视频或音频（本地文件、URL、YouTube、直播流、桌面录屏等）；
• 需要搜索视频内容、提取特定片段、生成证据流或自动剪辑；
• 需要生成/翻译/烧录字幕，或添加配音、背景音乐、品牌、文字/图片覆盖等时间线编辑操作；
• 需要监控 RTSP/桌面流，并对视觉/语音事件进行实时告警和摘要；
• 需要批量处理视频格式、分辨率、码率、平台适配等转码任务；
• 需要AI 生成图片、音频、视频等多模态内容，并自动插入时间线。

3. VideoDB Skill 使用流程 Step by Step

步骤 1：环境准备与 SDK 安装

1. 安装 Python SDK（推荐用虚拟环境）：

   pip install "videodb[capture]" python-dotenv

   如 Linux 下 [capture] 安装失败，可降级为：

   pip install videodb python-dotenv

2. 配置 API Key（两种方式，选一）：

   • 终端导出：export VIDEO_DB_API_KEY=你的key
   • 项目 .env 文件：VIDEO_DB_API_KEY=你的key

   免费 API Key 可在 console.videodb.io 申请

3. 加载环境变量并建立连接（在项目根目录）：

   from dotenv import load_dotenv
   load_dotenv(".env")
   
   import videodb
   conn = videodb.connect()
   coll = conn.get_collection()

步骤 2：摄取视频/音频（本地、URL、YouTube、直播流）

• 本地文件上传

  video = coll.upload(file_path="/path/to/video.mp4")

• URL 上传

  video = coll.upload(url="https://example.com/video.mp4")

• YouTube 视频

  video = coll.upload(url="https://www.youtube.com/watch?v=xxxx")

• RTSP/直播流接入

  video = coll.upload(url="rtsp://your-stream-url")

步骤 3：视频内容索引与搜索

• 自动索引语音内容、生成字幕

  video.index_spoken_words(force=True)
  text = video.get_transcript_text()
  stream_url = video.add_subtitle()

• 关键词搜索并获取时间戳和证据片段

  try:
      results = video.search("产品演示")
      shots = results.get_shots()
      stream_url = results.compile()  # 生成可播放片段
  except InvalidRequestError as e:
      if "No results found" in str(e):
          shots = []

• 场景级语义搜索（如“白板写字”）

  scene_index_id = video.index_scenes(
      extraction_type=SceneExtractionType.shot_based,
      prompt="描述该场景的视觉内容"
  )
  results = video.search(
      query="白板写字",
      search_type=SearchType.semantic,
      index_type=IndexType.scene,
      scene_index_id=scene_index_id,
      score_threshold=0.3
  )
  shots = results.get_shots()

步骤 4：时间线编辑与自动化生成

• 添加片段、文字覆盖、字幕、配音、音乐等

  from videodb.timeline import Timeline
  from videodb.asset import VideoAsset, TextAsset, TextStyle
  
  timeline = Timeline(conn)
  timeline.add_inline(VideoAsset(asset_id=video.id, start=10, end=30))
  timeline.add_overlay(0, TextAsset(text="结束语", duration=3, style=TextStyle(fontsize=36)))
  stream_url = timeline.generate_stream()

• 转码与分辨率/比例调整

  from videodb import TranscodeMode, VideoConfig, AudioConfig
  
  job_id = conn.transcode(
      source="https://example.com/video.mp4",
      mode=TranscodeMode.economy,
      video_config=VideoConfig(resolution=720, quality=23, aspect_ratio="16:9"),
      audio_config=AudioConfig(mute=False),
  )

• 智能重构比例（如竖屏/方形/自定义）

  reframed = video.reframe(start=0, end=60, target="vertical")

步骤 5：实时流/桌面会话监控与事件告警

• 桌面录屏与事件监听（macOS 支持）
  1. 启动事件监听器：

     STATE_DIR="$HOME/.local/state/videodb"
     VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" &

  2. 录制桌面会话并监听 WebSocket 事件，事件数据写入 $STATE_DIR/videodb_events.jsonl。
  3. 解析事件数据，提取实时字幕、视觉事件等：

     import json, os
     from pathlib import Path
     
     events_dir = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".local" / "state" / "videodb"))
     events_file = events_dir / "videodb_events.jsonl"
     events = []
     if events_file.exists():
         with events_file.open(encoding="utf-8") as handle:
             for line in handle:
                 try:
                     events.append(json.loads(line))
                 except json.JSONDecodeError:
                     continue
     transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]

步骤 6：AI 多模态生成与自动化

• 生成图片/音频/视频等素材并插入时间线

  image = coll.generate_image(
      prompt="夕阳下的群山",
      aspect_ratio="16:9",
  )

4. 输出示例

• 摄取结果：返回可在线播放的流链接（HLS）、视频 ID、索引状态
• 搜索结果：返回包含时间戳、片段、证据流 URL 的结构化数据
• 时间线编辑：生成带字幕/音乐/品牌/配音的成品视频流
• 实时流监控：输出事件/告警结构体、桌面会话摘要、证据链接

5. 常见配套 Agent 与 Skill 协作

• 与 Doc Updater Agent 协作：自动生成/更新视频相关文档、README、演示链接
• 与 GAN Generator Agent、GAN Evaluator Agent 协作：多 Agent 协同生成、评测视频内容
• 与 Video Editing Skill 协同：复杂剪辑、配音、字幕、AI 生成内容的流水线自动化
• 与 Autonomous Agent Harness Skill 配合：实现全流程无人值守的视频 ingest→分析→编辑→分发闭环

6. 常见问题与注意事项

• API Key 安全：始终让用户自行设置 VIDEO_DB_API_KEY，不要自动读取或写入密钥。
• 错误处理：如索引/搜索/转码失败，需捕获异常并根据错误类型给出友好提示（如已索引、无结果、权限/配额等）。
• 本地 vs 云端：优先用 VideoDB 云端操作（摄取、转码、字幕、配音、剪辑等），仅在官方文档明确不支持的极端场景下再用 ffmpeg 等本地工具。
• 时间线参数校验：插入片段/素材时，务必校验时间戳合法性（start >= 0，start < end，end <= 视频总长）。
• 大文件/长视频异步处理：如重构比例、全片转码等耗时操作，建议用 callback_url 异步回调，避免阻塞。

---

FAQ

Q: VideoDB Skill 支持哪些视频来源？ A: 支持本地文件、公网 URL、YouTube、RTSP/直播流、桌面录屏（macOS）。

Q: 如何在 AI 自动化流程中实现视频内容搜索和自动剪辑？ A: 通过 video.index_spoken_words()、video.search() 等接口，自动构建索引并按关键词/场景搜索，返回可播放片段和证据流。

Q: 视频编辑和字幕/配音生成是否需要本地安装 ffmpeg？ A: 不需要，所有剪辑、字幕、配音、转码等操作均由 VideoDB 云端 API 完成，无需本地 ffmpeg。

---