analyze-video

Imported from JulesDups/claude-config-public (skills/analyze-video/SKILL.md). Install upstream with npx skills add JulesDups/claude-config-public --skill analyze-video. Copyright stays with the author.

name: analyze-video description: Download videos (YouTube/Vimeo/mp4), transcribe locally, extract frames, then dispatch parallel sub-agents to write one Markdown synthesis per video + aggregate recap. disable-model-invocation: true allowed-tools: Read, Write, Edit, TodoWrite, Glob, Grep, Agent, Monitor, Bash(yt-dlp *), Bash(ffmpeg *), Bash(ffprobe *), Bash(python *), Bash(trash *), Bash(powershell *), Bash(gio *), Bash(osascript *), Bash(code *), Bash(start *), Bash(open *), Bash(xdg-open *), Bash(nvidia-smi *), Bash(bash *), Bash(tail *) argument-hint: [url1 url2 ...] | [--file urls.txt] | [path/to/urls.txt]

Download one or many videos (YouTube, Vimeo, direct mp4, S3/CloudFront, etc.), transcribe locally on GPU when available, extract frames, then dispatch cheap parallel Haiku/Sonnet sub-agents to write one exhaustive Markdown synthesis per video. After all per-video syntheses land, a single reporter agent writes a cross-video aggregate synthesis. Only the synthesis files survive cleanup.

This skill is NOT:

• A translator — syntheses match each video's dominant language. No translation unless user asks.
• A summarizer — syntheses are exhaustive on visible UI, verbatim on on-screen text.
• A transcription service for audio-only — frame sampling mandatory; pure-audio URLs rejected.
• A live narrator — see Silence Policy below.
• A tool for private/login-gated URLs — yt-dlp will fail; mark URL skipped and move on.

Silence Policy (CRITICAL)

The orchestrator (main Claude) MUST emit ZERO user-facing text between Step 2 (env check pass) and the final report of Step 16. Tool calls are silent by design. Status updates, "now doing X", per-frame observations, post-cleanup confirmations — all forbidden. The user reads the final report and the synthesis files; nothing else.

Permitted user-facing output:

• One-line fatal error if Step 2 env check fails (single line, then stop).
• Final aggregate report at Step 16 (single Markdown block: table + reporter output path + cleanup status).

Sub-agents follow the same silence policy: they only emit their per-video summary at the very end of their work; their internal tool calls are not surfaced to the user.

If the user explicitly requests progress updates ("verbose mode", "narrate"), the orchestrator may emit one short caveman-style line per major phase transition (download done / transcribe done / synthesis done / cleanup done). Default = silent.

Usage

/analyze-video [url1] [url2] ...
/analyze-video --file path/to/urls.txt
/analyze-video path/to/urls.txt          # auto-detected if single arg ends in .txt

Examples:

/analyze-video https://www.youtube.com/watch?v=E6ncPDcIb2k
/analyze-video https://www.youtube.com/watch?v=aaa https://vimeo.com/bbb
/analyze-video C:/Users/jules/Desktop/videos_urls.txt
/analyze-video --file ./formation_urls.txt

A urls.txt file may contain one URL per line, with optional comment headers (lines starting with # or text-only lines without http). Blank lines and === separators are ignored. Optional ## Title lines preceding a URL are captured as the human title for that video.

If no URL is passed, stop and emit the expected usage on a single line.

Required environment

Instructions

1. Parse arguments — Tokenize $ARGUMENTS. Branches:

   • 0 tokens → stop, emit usage line.
   • 1 token ending in .txt OR starting with --file → file mode (read URL list).
   • All other tokens → URL mode (positional URLs).
   • In file mode, parse the file: keep lines starting with http/https, capture the immediately preceding non-empty non-URL line as the candidate human title. Strip leading numbering like 1. , 01). Build [(title, url), ...] queue.
   • Build the queue. If empty → stop with "no valid URL found" line.

2. Validate environment — Single batched check via Bash:

   • yt-dlp --version and ffmpeg -version — fatal if either missing.
   • python -c "import faster_whisper, ctranslate2; print(ctranslate2.get_cuda_device_count())" — record gpu_count. If import fails: set transcription_mode=skip and continue. If gpu_count >= 1: set transcription_mode=cuda. Else transcription_mode=cpu.
   • nvidia-smi --query-gpu=name,memory.total --format=csv,noheader — record GPU name (informational).
   • On fatal failure, emit single line FATAL: <missing tool> and stop.

3. Provision the pipeline script — Use ~/.claude/skills/analyze-video/scripts/process_video.py (absolute path). The file ships with the skill; do not write inline. If missing, abort with FATAL: skill scripts/process_video.py missing — reinstall skill. The script:

   • Args: <url> <video_id> <scratch_dir> [fps_div].
   • Steps: yt-dlp download → ffprobe duration → fps_div auto-bump for >20min → ffmpeg audio (16k mono pcm_s16le) → ffmpeg frames (fps=1/{div}, scale=800:-1) → faster-whisper transcription (large-v3 float16 CUDA, fallback base int8 CPU; language=auto with bias to user-default).
   • Writes: video.mp4, audio.wav, frames/frame_NNN.jpg, transcript.srt, meta.json.
   • Exits 0 on success.

4. Provision the batch driver — Write a per-run bash driver <perm-root>/.batch-<run-id>.sh that loops the queue sequentially and invokes process_video.py per URL. Logs to <perm-root>/.batch-<run-id>.log. Each loop iteration emits === START chNN === and === END chNN === markers (used by the Monitor watch). The Python invocation must end with || true so a non-zero exit from the script does not abort the entire batch loop.

5. Per-video naming — For each (title, url) in the queue:

   • video_id = chNN (zero-padded index from queue order). Used for scratch dir name.
   • slug = slugify(title) → lowercase ASCII, non-alnum → -, collapse repeats, trim 60 chars. If batch from file with a common course name in headings, prefix slug with {course-slug}-NN- for natural sort.
   • synthesis_filename = {YYYY-MM-DD}-{slug}.md (single video) or {YYYY-MM-DD}-{course-slug}-{NN}-{slug}.md (batch from file).
   • If a file with the same name exists today, append -2, -3 before .md.

6. Set up locations — Permanent root: /c/Users/jules/Documents/pro/hegoatek/creation contenu/syntheses videos. mkdir -p it. Per-video scratch: <perm-root>/.work-{video-id}/. Quote every path (it contains spaces).

7. Launch the batch driver in background — Bash run_in_background: true invoking bash <batch-driver>.sh. Capture the background task ID.

8. Arm a Monitor watch — Monitor with tail -F <batch-log> | grep -E --line-buffered "===|FAILED|BATCH DONE|TRANSCRIBING|Error|Traceback". Coverage rule: include progress + failure signatures. Use timeout_ms ≈ 120000 + 900000 * N (2 min base + 15 min/URL — accounts for GPU transcription of long videos).

9. Wait silently — While the batch runs, do not narrate. The Monitor surfaces START/END/FAILED events automatically. Do NOT poll, do NOT sleep, do NOT issue intermediate report lines.

10. On FAILED chNN events — Inspect the scratch dir AFTER END chNN. If meta.json + transcript.srt exist, treat as false positive (Windows exit-code quirk) and log internally as OK. Only mark as real failure if scratch dir is missing artifacts.

11. On BATCH DONE — Probe each scratch dir for meta.json. Build the per-video manifest:

    [{video_id, title, url, scratch, frames, duration_sec, srt_size, status: ok|incomplete}, ...]
    

    incomplete videos are skipped from synthesis dispatch and recorded as skipped in the final report.

12. Dispatch parallel synthesis sub-agents — Decide cohort size based on video count N:

    • N == 1: 1 sub-agent (Haiku) for the synthesis. Orchestrator does NOT write the synthesis itself — to keep the main context clean.
    • 2 ≤ N ≤ 5: 1 sub-agent per video (Haiku each).
    • 6 ≤ N ≤ 12: 2–3 sub-agents, each handling a contiguous chunk (ceil(N / 3) videos per agent). Default model: Haiku. Use Sonnet only for chunks where average video duration > 25 min (denser content benefits from stronger reasoning).
    • N > 12: 4 sub-agents (Haiku), chunks of ≈ N/4. Hard cap.
    • Send all sub-agent calls in a single message with multiple Agent tool uses so they run concurrently.
    • Each sub-agent prompt MUST be self-contained (see "Sub-agent prompt template" below). Sub-agents are general-purpose. Override model per agent via the model parameter (haiku default, sonnet for dense content).

13. Sub-agent contract — Each sub-agent: a. For each assigned chapter: read meta.json, read transcript.srt fully, read frames/ in batches of 5–6 via Read tool (vision auto-render), cross-reference timestamps, write the synthesis Markdown at the canonical output path, run code "<absolute path>", then trash "<scratch dir>" (max 2 attempts, fall back to PowerShell Recycle Bin verb on Windows). b. Report back ONLY a per-chapter Markdown table (chapter, filename, frames, size in KB, cleanup status). No prose.

14. Wait for all synthesis sub-agents — They run in background. The orchestrator receives one notification per agent on completion. Do NOT narrate while waiting. Do NOT spawn new work.

15. Dispatch reporter agent — After all synthesis agents complete:

    • Skip if N == 1.
    • Otherwise: dispatch ONE Sonnet sub-agent to read every per-video synthesis file (titled {YYYY-MM-DD}-*.md matching this run's prefix) and produce one aggregate cross-video synthesis at <perm-root>/{YYYY-MM-DD}-{course-slug}-00-RECAP.md. Sections (adapt to detected language):
      • # Récapitulatif global — {course title}
      • ## Vue d'ensemble — 5–10 lignes denses sur l'arc narratif global.
      • ## Carte des chapitres — table (n°, titre, durée, 1-ligne résumé, 2 takeaways).
      • ## Concepts récurrents — concepts qui apparaissent dans 2+ chapitres, avec liste des chapitres source.
      • ## Stack et outils mentionnés (agrégé) — dédupliqué.
      • ## Pricing / chiffres clés (agrégé).
      • ## URLs et liens (agrégé).
      • ## Hooks et formules transversales.
      • ## Plan d'action recommandé — 7–15 actions priorisées synthétisées des takeaways individuels.
      • ## Génération — date, nombre de chapitres, modèle whisper, nombre total de frames.
    • Reporter then opens the recap in VS Code.

16. Final report (orchestrator, single Markdown block) — After reporter completes, emit one message containing:

    • Brief one-line header: Processed N URLs.
    • One table: | Chapter | URL host/path | Filename | Frames | Size (KB) | Status |.
    • If reporter ran: Recap: <path to RECAP md>.
    • If any video failed: Failed: chNN — <one-line reason> rows.
    • If any cleanup failed: Cleanup-failed: <path> lines.
    • Nothing else. No prose, no congratulations.

Cohort sizing reference

Token-cost rationale: Opus is forbidden for sub-agents in this skill. Haiku reads vision frames at a fraction of the cost. Reporter uses Sonnet because cross-chapter synthesis benefits from stronger reasoning.

Sub-agent prompt template (self-contained)

Each Agent call uses subagent_type=general-purpose and a model override (haiku or sonnet). The prompt must include:

1. The hard rule that this is silent mode — no narration, only final per-chapter table at end.
2. The chapter assignment table: | chNN | original title | absolute scratch dir path |.
3. The exact synthesis output path pattern.
4. The slug-to-NN mapping.
5. The synthesis sections in the target language (French by default, autodetect if non-FR videos).
6. The cleanup contract (trash first, PowerShell Recycle Bin verb fallback, hard cap 2 attempts, never rm -rf).
7. The final per-chapter report table format.

Standard French sections (the default for the canonical destination):

• # {Titre original} — {Course title} (Chapitre {N}/{Total})
• ## Métadonnées (URL source, formation, chapitre, durée, langue, date)
• ## Résumé express (3–5 lignes denses)
• ## Plan détaillé / Structure narrative (timestamps [mm:ss] + écran + discours)
• ## Concepts clés (numérotée, verbatim quand définition explicite)
• ## Listes, tableaux et données affichés (verbatim) (recopié mot pour mot)
• ## Hooks, formules et phrases marquantes (citations entre « »)
• ## Pricing, chiffres et dates mentionnés
• ## Outils, plateformes et stack technique observés
• ## URLs, liens et mentions
• ## Identité visuelle
• ## Takeaways actionnables (impératif, numérotée)
• ## Génération (frames, modèle whisper, langue, date)

For non-French videos, the sub-agent translates the section headings to the dominant language but keeps quoted content verbatim in the original language.

Output Layout

Canonical root: /c/Users/jules/Documents/pro/hegoatek/creation contenu/syntheses videos/

syntheses videos/
  2026-05-01-formation-affiliation-00-RECAP.md             <- kept (reporter output)
  2026-05-01-formation-affiliation-01-introduction.md      <- kept
  2026-05-01-formation-affiliation-02-trouver-niches.md    <- kept
  ...
  .work-ch01/                                              <- deleted at cleanup
    video.mp4
    audio.wav
    transcript.srt
    meta.json
    frames/frame_001.jpg ...
  .batch-<run-id>.sh                                       <- deleted at end
  .batch-<run-id>.log                                      <- deleted at end

Per-video synthesis + final RECAP survive. Everything else trashed.

Cleanup Policy

Per-video (sub-agent responsibility):

Per-run (orchestrator responsibility, Step 16 prelude):

Restrictions

• NEVER cd into the scratch directory. All Bash commands targeting scratch use absolute paths. cd leaves a handle that blocks trash on Windows.
• NEVER spawn long-running or background processes on scratch files (no tail -f, no watchers on scratch). Monitor watches the batch LOG only.
• NEVER open a scratch file in an editor before synthesis is written.
• Before any cleanup, confirm no Bash invocation is still running against scratch paths.
• Never use rm -rf or any destructive unix command. Always trash.
• Never skip cleanup. Only .md deliverables survive.
• Never write a synthesis outside the canonical destination. The path is fixed.
• Never upload videos / transcripts to third-party services. Process locally.
• Do not write a synthesis in a language different from the video unless the user explicitly requests translation.
• Process URLs sequentially in the batch driver. Do not parallelize downloads — disk IO contention corrupts frame numbering.
• Sub-agent synthesis writing IS parallel (see cohort sizing) — they read disk, not network.
• Opus is FORBIDDEN as a sub-agent model in this skill. Haiku for synthesis, Sonnet for reporter.
• The orchestrator (main Claude) MUST NOT write synthesis content itself when N ≥ 1 — always dispatch. This keeps main context clean and uses cheaper tokens.

Examples

Single URL (silent → 1 sub-agent → final table):

/analyze-video https://www.youtube.com/watch?v=E6ncPDcIb2k

Output (only thing printed):

Processed 1 URL.

| Chapter | URL                              | Filename                                                       | Frames | Size  | Status |
|---|---|---|---:|---:|---|
| ch01 | youtube.com/watch?v=E6ncPDcIb2k | 2026-04-16-contentpreneur-club-meilleure-formation.md          | 105    | 15.8KB | OK |

Batch from file (silent → 3 parallel Haiku sub-agents → 1 Sonnet reporter → final table + recap path):

/analyze-video C:/Users/jules/Desktop/videos_urls.txt

Output:

Processed 11 URLs.

| Chapter | URL                                       | Filename                                                          | Frames | Size  | Status |
|---|---|---|---:|---:|---|
| ch01 | cloudfront.net/.../1.Introduction.mp4    | 2026-05-01-formation-affiliation-01-introduction.md               | 200    | 18.2KB | OK |
| ch02 | cloudfront.net/.../2.Trouverdesniches... | 2026-05-01-formation-affiliation-02-trouver-niches.md             | 164    | 16.0KB | OK |
| ...   | ...                                       | ...                                                                | ...    | ...    | OK |

Recap: /c/Users/jules/Documents/pro/hegoatek/creation contenu/syntheses videos/2026-05-01-formation-affiliation-00-RECAP.md

Verbose mode (opt-in)

If user adds --verbose (or says "narrate", "verbose"), the orchestrator MAY emit one caveman-style line per phase:

• env OK gpu=RTX4080
• batch start N=11
• batch done — 11 OK / 0 fail
• synth dispatch — 3 agents (haiku)
• synth done — 11 files
• recap done

Caveman style only — no full sentences. Tool calls still silent.

Related Skills

• /graphify — Build a knowledge graph from generated syntheses.

Failure modes