Research Skills (Phase 0)

Phase 0 of the video pipeline. Before writing a single line of script, you research what the best videos in your category look like, download them, and reverse-engineer them into structured storyboards your agent can learn from.

iopho-video-director calls these in sequence automatically. You can also use each standalone by jumping directly to a skill.

Phase 0 sequence:

iopho-product-context → iopho-searching-videos → iopho-getting-videos → iopho-analyzing-videos

---

iopho-product-context

Generate context.md — the foundation file every other skill reads.

/iopho-product-context ./exp/my-project
/iopho-product-context ./exp/my-project --quick           # 5 core questions only
/iopho-product-context ./exp/my-project --from-file README.md

Modes

Interactive (default) — Asks 12 structured questions in order. Accepts any language (EN/ZH/mixed):

Core (always):

1. Product name, URL, one-sentence description
2. Primary audience + their pain point
3. Top 3 differentiators from competitors
4. Video type (demo/explainer/launch/teaser), duration, target platforms
5. Brand rules — colors, fonts, tone, design system files

Deep-dive (skipped with --quick): 6. Competitors — list 2–5 with strengths/weaknesses 7. Founder visibility — public / anonymous / team-only 8. Hero feature — the ONE thing the video must show 9. What to avoid — off-limits messaging or visuals 10. Reference videos — URLs → fed to iopho-searching-videos 11. Languages — VO and subtitle languages 12. Call to action — what viewers should do after watching

--from-file — Scans project directory for existing docs, pre-fills answers:

README.md, package.json, **/brand.ts, **/*DesignPrompts*, context.md

Then asks user to confirm or correct each pre-filled field.

Update mode — If context.md already exists, ask “what needs updating?” and only modify mentioned fields.

Output: context.md with product, audience, brand, video brief, and competitor sections. All other skills read this file.

---

iopho-searching-videos

Search for videos across 19+ platforms without downloading anything.

Prerequisites:

pip install yt-dlp                    # Required
pip install duckduckgo-search         # Optional — cross-platform web search

/iopho-searching-videos <query> [--platform youtube|bilibili|all] [--limit N] [--json]

Examples:

/iopho-searching-videos "SaaS product demo under 30s"
/iopho-searching-videos "产品介绍" --platform bilibili --limit 10
/iopho-searching-videos "startup pitch deck" --platform all --limit 8

Platform support:

Platform	Notes
YouTube	ytsearch — native, fast
YouTube by date	ytsearchdate — most recent first
Bilibili	BiliBiliSearch — Chinese queries work best
SoundCloud, Niconico, Dailymotion	Native yt-dlp extractors
Cross-platform web	DuckDuckGo — requires duckduckgo-search

Duration/view filters (agent applies automatically):

--match-filter "duration<30"           # under 30 seconds
--match-filter "view_count>10000"      # popular only
--match-filter "duration<60 & view_count>1000"

Returns: title, duration, view count, upload date, URL — without downloading.

---

iopho-getting-videos

Download video, audio, subtitles, thumbnails, and metadata from 1800+ platforms.

Prerequisites:

pip install yt-dlp                    # Required
brew install ffmpeg                   # Required — for merging/conversion
pip install youtube-transcript-api   # Optional — fast YouTube transcripts
dotnet tool install -g BBDown         # Optional — Bilibili specialist

/iopho-getting-videos <url> [--mode video|audio|transcript|metadata|all] [--quality best|720p|480p] [--output DIR]

Modes:

Mode	What you get
video	Best quality MP4
audio	Audio only (MP3/M4A)
transcript	Subtitles/captions as timestamped text
metadata	JSON: title, duration, tags, channel, upload date
all	Video + audio + subtitles + metadata + thumbnail

Examples:

/iopho-getting-videos https://youtube.com/watch?v=abc --mode transcript
/iopho-getting-videos https://bilibili.com/video/BVxxx --mode all --output ./research/downloads/
/iopho-getting-videos https://youtube.com/watch?v=abc --mode audio

Platform routing (auto-selected):

Platform	Primary tool	Fallback
YouTube	yt-dlp	yt-dlp + cookies
Bilibili	yt-dlp	BBDown (for complex/multi-part)
Chinese platforms (Youku, iQiyi)	yt-dlp	lux
Everything else	yt-dlp (1800+ extractors)	you-get

Tip

--mode all is the best input for iopho-analyzing-videos. The .info.json produced by --mode all is auto-detected by the analysis skill for source URL and title metadata.

---

iopho-analyzing-videos

Reverse-engineer a video into a .storyboard.md file — the “source code” of the video.

Prerequisites:

pip install google-generativeai       # Required
brew install ffmpeg                   # Required — keyframe extraction
export GEMINI_API_KEY=your-key        # Required — free key at aistudio.google.com/apikey

/iopho-analyzing-videos <video_path> [output_path] [--no-frames] [--model gemini-2.0-flash]

Examples:

/iopho-analyzing-videos ./research/downloads/competitor.mp4
/iopho-analyzing-videos ./video.mp4 ./research/storyboards/output.storyboard.md
/iopho-analyzing-videos ./video.mp4 --no-frames        # faster, no keyframe images
/iopho-analyzing-videos ./video.mp4 --model gemini-2.5-flash

What it produces

output.storyboard.md    ← YAML frontmatter + scene-by-scene markdown
frames/
  scene-001.jpg         ← Keyframe at midpoint of scene 1
  scene-002.jpg         ← ...

Each scene in the storyboard includes:

• Visual — shot type, camera movement, subject, on-screen text, graphics
• Audio — exact voiceover transcript, music/SFX description
• Analysis — narrative purpose, viewer psychology, sales element, transition

Pipeline stages

Stage 1 — Upload:  video file → Gemini File API (up to ~1GB)
Stage 2 — Analyze: Gemini Flash processes video natively (no pre-extraction needed)
Stage 3 — Frames:  ffmpeg screenshots at scene midpoints
Stage 4 — Output:  .storyboard.md + frames/ directory

Cost estimates (Gemini 2.0 Flash)

Video length	Approx. cost
< 30s	~$0.001
1–5 min	~$0.01
5–15 min	~$0.03
15–60 min	~$0.06–0.15

Full research pipeline

/iopho-searching-videos "SaaS product demo under 30s" --limit 5
/iopho-getting-videos https://youtube.com/watch?v=BEST_MATCH --mode all --output research/downloads/
/iopho-analyzing-videos research/downloads/video.mp4 research/storyboards/reference.storyboard.md

Three commands → structured blueprint of any reference video, ready for Phase 1 storyboard writing.