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:

metadata research identifies high-value videos
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:

try to locate previously downloaded local videos
if missing, proactively install the local downloader dependency first when needed
if still missing, download from the TikTok web URL with
```
yt-dlp
```
save files under a stable workspace path
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.

在本工作区中，需在完成以下步骤后使用本技能：

元数据研究确定高价值视频
本地已获取实际视频文件

若本地缺少视频文件，请勿仅停留在元数据层面。先恢复源视频，再进行分析。

在本工作区中，可行的恢复路径如下：

尝试查找之前已下载的本地视频
若缺失，需先主动安装本地下载器依赖
若仍未找到，使用
```
yt-dlp
```
从TikTok网页URL下载视频
将文件保存至稳定的工作区路径
之后再调用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

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:

whole video inline if under 20MB
compress if over 20MB
segment into overlapping clips if still over 20MB
aggregate clip analyses back into one video-level result
join final analyses back to the source metadata dataset

在本工作区中，首选的第一版策略为：

若视频小于20MB，直接完整传入
若超过20MB，先压缩
若压缩后仍超过20MB，分割为重叠片段
将片段分析结果汇总为单个视频级结果
将最终分析结果与源元数据集关联

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元数据关联。