analyze-footage

分析素材 — AI 视频理解

你正在使用 TwelveLabs MCP 帮助用户了解现有视频文件。这能让你的 Agent 拥有“眼睛”，看清视频素材中的内容。

加载 remotion-production 技能，以使用 video-analysis 规则。

工作流

1. 识别视频文件

询问用户要分析哪些视频文件，或查找这些文件：

# Check common locations
ls public/footage/ public/raw/ public/video/ public/ 2>/dev/null | grep -E '\.(mp4|mov|avi|mkv|webm)$'

如果没有找到文件，请询问用户素材存放在哪里。

2. 上传到 TwelveLabs

为每个视频文件上传一个素材（分析无需索引）：

create-asset:
  file: [absolute path, e.g. /path/to/project/public/footage/source-video.mp4]

保留返回的素材 ID。如果下一次调用提示素材尚未就绪，请等待几秒后重试。

3. 分析内容

场景拆解 — 带时间戳的场景映射，如 video-analysis 规则所示：

async-analyse-video:
  assetId: [asset ID]
  modelName: "pegasus1.5"
  analysisMode: "time_based_metadata"
  segmentDefinitions: [one "shots" definition with fields: description, shot_type, people, on_screen_text, usable]

每隔 5-10 秒轮询一次 get-analyse-task，直到状态为 ready，然后解析 result.data（一个以片段定义 id 为键的 JSON 字符串）。最长支持 2 小时的视频。

对于直接提问（“哪些镜头展示了产品？”、“选出适合制作 30s 宣传片的片段”），使用 sync-analyse-video（传入 assetId、modelName: "pegasus1.5"、prompt 和 jsonSchema，以便将起止时间作为数字返回）。同步分析最多支持 1 小时的视频。

始终传入 modelName: "pegasus1.5"：服务的默认模型已从 API 中移除。

按以下格式呈现：

📹 Video Analysis: [filename]

Scenes:
  0:00 - 0:15  │ Logo animation, dark background
  0:15 - 0:45  │ Speaker at podium, introducing topic, conference setting
  0:45 - 1:20  │ Product demo on laptop screen, close-up
  1:20 - 1:45  │ Audience reaction, medium shot, clapping
  1:45 - 2:00  │ Call to action slide, company branding

Key Elements (from the segment fields):
  - People: 1 speaker, audience (~30 people)
  - Shot types: wide, medium, close-up, screen capture
  - Text on screen: company logo, product name
  - Setting: conference room, professional lighting

保存结果（例如保存到 analysis/[filename].json）后，使用 delete-asset（传入 assetId）清理素材。素材会占用账户存储空间。

4. 定向搜索（用户有具体需求时）

对于单个文件，直接调用 sync-analyse-video（可选用 startTime/endTime 截取片段）。若要在视频库中查找某些时刻，先为视频库创建一次索引，再进行搜索：

start-video-indexing-task:
  folderFilePath: [absolute path to the footage folder]   (or videoFilePath for one file)
→ poll get-indexed-asset until ready
search:
  query: "the part where the product is demonstrated"

search 会返回带有起止时间和缩略图的排序片段，但不会描述这些片段。若要了解更多，请分析搜索结果。

5. 推荐片段

根据分析结果，为用户的视频推荐最佳片段：

🎬 Recommended Clips for a 30-second promo:

1. Opening (0:00-0:05)
   → Use 0:45-0:50 of source — product demo close-up, high energy
   
2. Main content (0:05-0:20)  
   → Use 0:50-1:05 of source — full demo walkthrough
   
3. Social proof (0:20-0:25)
   → Use 1:20-1:25 of source — audience clapping
   
4. CTA (0:25-0:30)
   → Use 1:45-1:50 of source — branded slide

6. 展示在 Remotion 中的用法

对于每个推荐片段，展示 Remotion 代码。源片段范围会转换为 <Video>（来自 @remotion/media）上的 trimBefore（起始时间戳）和 durationInFrames（片段时长）。按照官方 remotion-markup 技能（video-editing.md）所示，使用 TransitionSeries 或 Track 将片段剪辑在一起；skills/remotion-production/rules/video-analysis.md 中提供了完整示例。

import { Video } from "@remotion/media";
import { staticFile, useVideoConfig } from "remotion";

const { fps } = useVideoConfig();

// Opening (0:00-0:05) ← source 0:45-0:50
<Video
  name="Opening"
  src={staticFile("footage/source-video.mp4")}
  trimBefore={45 * fps}
  durationInFrames={5 * fps}
  objectFit="cover"
  style={{ width: "100%", height: "100%" }}
/>

将 TwelveLabs 的小数时间戳四舍五入到整帧：Math.round(45.6 * fps)。

提示

• 确保视频文件位于 public/（理想情况下为 public/footage/），这样 Remotion 才能使用相对于 public/ 的路径，通过 staticFile() 访问文件；将同一文件的绝对路径传给 create-asset
• 限制：同步分析最多 1 小时，异步分析最多 2 小时，直接上传最多 4 GB
• 仅在使用 search 时创建索引；同一个索引可用于多次搜索，而素材针对单次分析（使用后删除）
• 其他信息请参阅官方文档：https://docs.twelvelabs.io（以及 llms.txt）
• 将分析过的素材与 Pexels 的库存片段结合，以补足内容