Local Video Content Analyzer

Local Video Content Analyzer

Analyze LOCAL short-form video files and explain why they went viral, using both the video content and the engagement data the user provides.

The skill has no model, no adapter, no API key anywhere. The Python helper only does data preparation (file discovery, metadata normalization, metric computation, prompt assembly). The agent that runs this skill performs the actual video understanding and writes the final report.

Inputs

1. Video files (required, one of)

• --video / -v PATH - single local video file
• --video-dir / -V DIR - folder; supported extensions: mp4 mov mkv webm m4v

2. Engagement metadata (required - no data = no attribution)

Provide either a sidecar JSON next to each video (aweme_001.mp4 → aweme_001.json), or a unified --metadata FILE (CSV or JSON).

Canonical fields per video:

• Required: views, likes, author_followers
• Recommended: comments, saves, shares
• Optional: title, platform, publish_time, video_duration_sec, completion_rate, ctr, author, notes

Chinese / platform-native field names are accepted as aliases and normalized to the canonical names above. Common aliases:

Use canonical English keys in metadata (e.g. saves for bookmarks). Chinese aliases such as 收藏 are still accepted and normalized automatically. If a required metric is not visible on the platform, set it to null (JSON) or leave it blank (CSV). For example, Douyin may not expose views; use "views": null.

Behavior on missing fields:

• Any required field missing or null → that video is skipped with a reason
• Recommended/optional missing → marked unavailable in field_availability, the agent is instructed not to use it as evidence

Note: downloads (save-to-album) is NOT exposed by any consumer platform (Douyin, Xiaohongshu, Shipinhao, BiliBili). Do not put it in metadata. See REFERENCE.md for a full per-platform availability table.

3. Control flags (optional)

Usage

python3 .cursor/skills/local-video-content-analyzer/scripts/analyze_local_videos.py \
  --video-dir ./videos/ \
  --language zh

Output

The helper writes one file: viral-analysis-tasks.json (path from --output). It is a list, one entry per video, with:

• file, video_path (absolute path) — so the agent can open / watch the video
• metadata (normalized) and field_availability
• metrics (engagement rates, viral_score, viral_tier)
• language
• prompt — the full analysis prompt to apply to the video
• suggested_report_path — <video_dir>/<video_basename>-YYYYMMDDHHMMSS.md, using a single timestamp generated once per script run and shared across all videos in that run

Result: one run = exactly one .md per video, and the next independent ask gets a NEW timestamp → a new file, no overwrite of the previous one. Skipped videos (missing required metadata) get a task entry with a skipped reason and no suggested_report_path — they never produce a .md.

Agent workflow (REQUIRED)

This skill is a 2-step pipeline: helper prepares, agent analyzes & writes.

1. Run the helper above. Read viral-analysis-tasks.json.
2. For each task without a skipped field: a. Open / watch the video at video_path using your own multimodal capability. Do not call any external model SDK; do not require any API key. b. Treat the embedded prompt as the analysis spec, but produce a full natural-language report (in the requested language), not a bare JSON dump. Cover: data overview, hook, content structure, delivery style, CTA, primary/secondary viral drivers, replicable blueprint, anti-patterns, summary, and unavailable fields. c. Present that full report to the user in the chat reply. d. Write the EXACT SAME content to suggested_report_path. The file content and the chat reply must be identical — no summarize-down, no schema-flattening, no "abridged" file version.
3. For each task with a skipped field: tell the user the reason, do not write any .md.

Limitations (read before trusting results)

1. No video parsing inside the helper: no frame extraction, no ASR, no OCR. Video understanding is entirely the agent's job.
2. Subtitles are only implicit: not extracted as a separate transcript; short flashes may be missed.
3. No data → no attribution: required engagement fields are mandatory.
4. Unavailable fields are forbidden as evidence (downloads, completion_rate when missing, etc.).
5. Post-hoc attribution, not causal proof.

For platform-by-platform field availability, design rationale, and comparison with the remote-URL video-content-analyzer skill, see REFERENCE.md.