Back to Details

video-analysis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Video Analysis

视频分析

Follow shared release-shell rules in:
  • postplus-shared
    release-shell rules
Use this skill for video-level analysis after metadata research has already narrowed a candidate set.
Follow shared routing and guidance rules in:
  • postplus-shared
    research preferences
This skill is usually downstream of platform research, not the default first step for broad TikTok discovery.
遵循以下共享的release-shell规则：
  • postplus-shared
    release-shell规则
本技能用于在元数据研究已筛选出候选视频集后的视频级分析。
遵循以下共享的路由与指导规则：
  • postplus-shared
    研究偏好
本技能通常用于平台研究的下游环节，并非广泛发现TikTok内容的默认第一步。

Use For

适用场景

  • upload local video files to the official Gemini Files API
  • run Gemini 3.1 Pro Preview on video inputs
  • use a stable TikTok/Reels analysis prompt
  • request structured JSON output
  • keep analysis linked to source metadata such as TikTok URL, video id, or dataset row
  • 将本地视频文件上传至官方Gemini Files API
  • 基于视频输入运行Gemini 3.1 Pro Preview
  • 使用稳定的TikTok/Reels分析提示词
  • 请求生成结构化JSON输出
  • 将分析结果与源元数据（如TikTok URL、视频ID或数据集行）关联

Trigger Signals

触发信号

Use this skill when the user asks for things like:
  • why a video works
  • hook or structure breakdown
  • spoken-line or CTA analysis
  • shot-level decomposition
  • visual execution analysis
  • adaptation or recreation guidance based on actual videos
Do not use this skill as a substitute for broad TikTok trend discovery when no shortlist exists yet.
当用户提出以下需求时使用本技能：
  • 分析某视频为何成功
  • 钩子（hook）或结构拆解
  • 台词或行动号召（CTA）分析
  • 镜头级分解
  • 视觉呈现分析
  • 基于实际视频的改编或复刻指导
当尚未形成候选视频列表时，请勿将本技能用作广泛TikTok趋势发现的替代方案。

Core Resources

核心资源

  • Official source library: 
    references/core-sources.md
  • TikTok analysis prompt: 
    references/tiktok-video-analysis-prompt.md
  • JSON schema: 
    references/tiktok-video-analysis-schema.json
  • Downloader: 
    ../../00-core/shared-runtime/scripts/download_videos_from_manifest_with_ytdlp.mjs
  • Batch runner: 
    scripts/run_video_analysis_batch.mjs
  • Manifest builder: 
    scripts/build_manifest_from_master_table.mjs
  • Backfill helper: 
    scripts/backfill_master_table_with_script.mjs
  • 官方源库：
    references/core-sources.md
  • TikTok分析提示词：
    references/tiktok-video-analysis-prompt.md
  • JSON schema：
    references/tiktok-video-analysis-schema.json
  • 下载工具：
    ../../00-core/shared-runtime/scripts/download_videos_from_manifest_with_ytdlp.mjs
  • 批量运行器：
    scripts/run_video_analysis_batch.mjs
  • 清单构建工具：
    scripts/build_manifest_from_master_table.mjs
  • 回填助手：
    scripts/backfill_master_table_with_script.mjs

Workflow

工作流程

For this workspace, use this skill after:
  1. metadata research identifies high-value videos
  2. the actual video files are available locally
If the local video files are missing, do not stop at metadata. Recover the source video first, then run analysis.
For this workspace, a practical recovery path is:
  1. try to locate previously downloaded local videos
  2. if missing, proactively install the local downloader dependency first when needed
  3. if still missing, download from the TikTok web URL with 
    yt-dlp
  4. save files under a stable workspace path
  5. only then call the Gemini analysis scripts
Do not start with full-market video analysis. First shortlist, then analyze.
If the user request is broad or ambiguous, ask one short question before running:
  • "你是想先找出值得看的爆款样本，还是已经有视频要我直接拆 hook、结构和镜头？"
If the user appears to want a broader TikTok research outcome, proactively mention that 
skills/20-research/tiktok-research
can first build the shortlist this skill should analyze.
在本工作区中，需在完成以下步骤后使用本技能：
  1. 元数据研究确定高价值视频
  2. 本地已获取实际视频文件
若本地缺少视频文件，请勿仅停留在元数据层面。先恢复源视频，再进行分析。
在本工作区中，可行的恢复路径如下：
  1. 尝试查找之前已下载的本地视频
  2. 若缺失，需先主动安装本地下载器依赖
  3. 若仍未找到，使用
    yt-dlp
    从TikTok网页URL下载视频
  4. 将文件保存至稳定的工作区路径
  5. 之后再调用Gemini分析脚本
请勿直接开始全市场视频分析。先筛选候选列表，再进行分析。
若用户请求宽泛或模糊，在运行前先提出一个简短问题：
  • "你是想先找出值得看的爆款样本，还是已经有视频要我直接拆 hook、结构和镜头？"
若用户需要更广泛的TikTok研究成果，请主动告知
skills/20-research/tiktok-research
可先构建本技能所需分析的候选视频列表。

Environment

环境要求

Do not store secrets in this repo.
In the product shell:
  • follow 
    postplus-shared
    release-shell rules
  • if 
    python3
    is missing, install 
    python3
    with the host package manager already present on the machine before continuing
  • if 
    yt_dlp
    is missing, run 
    python3 -m pip install --user yt-dlp
    before continuing
  • rerun direct checks such as 
    python3 --version
    and 
    python3 -c "import yt_dlp"
    after installation
  • if the required Gemini capability is missing, or local dependency installation/verification fails, or the script returns a stable network/proxy/DNS error, stop immediately and report that failure
请勿在本仓库中存储密钥。
在产品shell中：
  • 遵循
    postplus-shared
    release-shell规则
  • 若缺少
    python3
    ，使用机器上已有的主机包管理器安装
    python3
    后再继续
  • 若缺少
    yt_dlp
    ，先运行
    python3 -m pip install --user yt-dlp
    再继续
  • 安装后重新运行直接检查，如
    python3 --version
    和
    python3 -c "import yt_dlp"
  • 若所需的Gemini功能缺失，或本地依赖安装/验证失败，或脚本返回稳定的网络/代理/DNS错误，请立即停止并报告该故障

Default Model

默认模型

  • gemini-3.1-pro-preview
Do not use 
gemini-3-pro-preview
; it has been shut down.
  • gemini-3.1-pro-preview
请勿使用
gemini-3-pro-preview
；该模型已停用。

First Run

首次运行

Use a single local video and keep the first request simple:
bash
node skills/40-creative/video-analysis/scripts/run_video_analysis_batch.mjs \
  --download-report <work-folder>/.postplus/download-report.json \
  --output-dir <work-folder>/.postplus/video-analysis-results \
  --concurrency 1 \
  --model gemini-3.1-pro-preview
The download report should contain at least:
json
{
  "results": [
    {
      "sourceId": "demo-1",
      "sourceUrl": "https://www.tiktok.com/@demo/video/1",
      "filePath": "/abs/path/to/video.mp4",
      "success": true
    }
  ]
}
使用单个本地视频，首次请求保持简单：
bash
node skills/40-creative/video-analysis/scripts/run_video_analysis_batch.mjs \
  --download-report <work-folder>/.postplus/download-report.json \
  --output-dir <work-folder>/.postplus/video-analysis-results \
  --concurrency 1 \
  --model gemini-3.1-pro-preview
下载报告应至少包含：
json
{
  "results": [
    {
      "sourceId": "demo-1",
      "sourceUrl": "https://www.tiktok.com/@demo/video/1",
      "filePath": "/abs/path/to/video.mp4",
      "success": true
    }
  ]
}

Batch Guidance

批量处理指导

When scaling to many videos:
  • keep provider calls concurrent but bounded
  • start with concurrency 2-4
  • prefer 
    inline
    for short TikTok clips under 20MB when the network path to Files API is unreliable
  • persist one JSON result per source video
  • include source ids and source URLs in every result
  • retry upload and generate calls with bounded backoff
  • separate upload failures from model failures
当扩展至大量视频时：
  • 保持并发调用但限制并发数
  • 初始并发数设为2-4
  • 当Files API的网络路径不稳定时，对于20MB以下的短TikTok视频，优先使用
    inline
    方式
  • 为每个源视频保存一个JSON结果
  • 在每个结果中包含源ID和源URL
  • 对上传和生成调用进行有限退避重试
  • 区分上传失败与模型失败

Fallback Strategy

Fallback策略

For this workspace, the preferred first-version strategy is:
  1. whole video inline if under 20MB
  2. compress if over 20MB
  3. segment into overlapping clips if still over 20MB
  4. aggregate clip analyses back into one video-level result
  5. join final analyses back to the source metadata dataset
在本工作区中，首选的第一版策略为：
  1. 若视频小于20MB，直接完整传入
  2. 若超过20MB，先压缩
  3. 若压缩后仍超过20MB，分割为重叠片段
  4. 将片段分析结果汇总为单个视频级结果
  5. 将最终分析结果与源元数据集关联

Keep These Assets

保留资产

Do not treat downloaded videos as disposable temp files if they were expensive to source.
When a benchmark set matters, keep:
  • the local video file
  • the analysis JSON
  • the manifest or URL list that can restore the file later
If you only keep the metadata table, you may lose the ability to reproduce shot-level analysis later.
若视频获取成本较高，请勿将下载的视频视为一次性临时文件。
当基准视频集重要时，请保留：
  • 本地视频文件
  • 分析JSON文件
  • 可用于后续恢复文件的清单或URL列表
若仅保留元数据表，您可能会失去后续重现镜头级分析的能力。

Shot-Level Backfill

镜头级回填

If shot-level fields were generated by Gemini but not preserved in the master table, backfill them instead of creating duplicate records.
Use:
bash
node skills/40-creative/video-analysis/scripts/backfill_master_table_with_script.mjs \
  --master "reports/video-master-table.csv" \
  --analysis-dir /path/to/analysis-dir
This updates matching source ids in the existing master table and preserves the single-table workflow.
Batch example:
bash
node skills/40-creative/video-analysis/scripts/run_video_analysis_batch.mjs \
  --download-report /path/to/download-report.json \
  --output-dir <work-folder>/.postplus/video-results \
  --concurrency 2 \
  --model gemini-3.1-pro-preview
若Gemini生成了镜头级字段但未保存至主表，请进行回填而非创建重复记录。
使用以下命令：
bash
node skills/40-creative/video-analysis/scripts/backfill_master_table_with_script.mjs \
  --master "reports/video-master-table.csv" \
  --analysis-dir /path/to/analysis-dir
此命令会更新现有主表中匹配的源ID，并保留单表工作流程。
批量示例：
bash
node skills/40-creative/video-analysis/scripts/run_video_analysis_batch.mjs \
  --download-report /path/to/download-report.json \
  --output-dir <work-folder>/.postplus/video-results \
  --concurrency 2 \
  --model gemini-3.1-pro-preview

Always Keep

需始终保留的字段

Never treat video analysis as isolated output. Always keep these fields:
  • sourceId
  • sourceUrl
  • sourceMetadataPath
    or dataset path
  • videoFilePath
  • model
  • promptVersion
That makes it possible to join Gemini output back to TikTok metadata later.
切勿将视频分析视为孤立输出。请始终保留以下字段：
  • sourceId
  • sourceUrl
  • sourceMetadataPath
    或数据集路径
  • videoFilePath
  • model
  • promptVersion
这使得后续可将Gemini输出与TikTok元数据关联。