Video Analysis
Follow shared release-shell rules in:
Use this skill for video-level analysis after metadata research has already narrowed a candidate set.
Follow shared routing and guidance rules in:
This skill is usually downstream of platform research, not the default first step for broad TikTok discovery.
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
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.
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
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
- 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.
Environment
Do not store secrets in this repo.
In the product shell:
- follow release-shell rules
- if is missing, install with the host package manager
already present on the machine before continuing
- if is missing, run
python3 -m pip install --user yt-dlp
- rerun direct checks such as and
python3 -c "import yt_dlp"
- 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
Default Model
Do not use
; it has been shut down.
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
}
]
}
Batch Guidance
When scaling to many videos:
- keep provider calls concurrent but bounded
- start with concurrency 2-4
- prefer 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
Fallback Strategy
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
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.
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
Always Keep
Never treat video analysis as isolated output. Always keep these fields:
That makes it possible to join Gemini output back to TikTok metadata later.