---
name: generate-video
description: "Generate short-form video clips via a 5-stage human-in-the-loop pipeline: concept, keyframes, video generation, and delivery."
argument-hint: "[--post <id>] [--script-only] [--thumbnail]"
effort: high
user-invocable: true
---

# /socialforge:generate-video — Video Production Kit

Generate video production assets through a 5-stage human-in-the-loop pipeline. Each stage requires user approval before advancing.

## Context efficiency

Asset-heavy skill. **Grep before Read** the asset catalog (`${CLAUDE_PLUGIN_DATA}/<brand>/assets/index.json`) — never list the asset directory. Reference generated images / videos by path, not by loading metadata. Brand profile loads once per session.

## Prerequisites

- Credentials must be configured via `/socialforge:setup`:
  - **Vertex AI** (Gemini Imagen) — used for first-frame and last-frame keyframe generation
  - **WaveSpeed API** — used for image-to-video generation via Kling v3.0 Pro
- Brand profile must be active (`/socialforge:switch-brand` if needed)
- Calendar must be parsed (`/socialforge:parse-calendar`) with video posts identified

## The 5-Stage Pipeline

### Stage 1: Video Concept (no API call)

Claude generates **2-3 video concept ideas** based on the post brief, brand voice, and platform requirements. Each concept includes:
- Working title and hook
- Visual narrative arc (opening, middle, close)
- Suggested duration and pacing
- Tone and style direction

The user picks one concept (or requests refinements) before proceeding.

### Stage 2: First Frame Generation (Vertex AI / Gemini Imagen)

Generate **2 first-frame options** based on the chosen concept. These set the opening visual and establish the look and feel.

- Images are shown **inline** in the terminal for immediate review
- User selects one or requests a regeneration with adjusted direction

### Stage 3: Last Frame Generation (Vertex AI / Gemini Imagen)

Generate **2 last-frame options** that complete the visual narrative arc, matching the approved first frame.

- Images are shown **inline** in the terminal for immediate review
- User selects one or requests a regeneration with adjusted direction

### Stage 4: Video Generation (WaveSpeed / Kling v3.0 Pro)

Using the approved first and last frames, generate **2 video versions** via WaveSpeed's Kling v3.0 Pro image-to-video endpoint (3-15 seconds).

- A **video gallery is opened in the browser** for side-by-side comparison
- User selects the final version or requests a regeneration

### Stage 5: Post-Process, Save & Deliver

After the user picks the final video, post-processing runs before saving:
- **Logo watermark** is automatically added to the video via video_postprocess.py
- **Subtitles:** User is asked whether to burn subtitles into the video (optional). SRT was already generated from the script and is saved separately regardless.
- **Background music:** If the video has no audio (sound=False in Kling config), user is asked whether to add background music (optional).
- **Platform resize:** Video is automatically resized for each target platform (letterbox/pillarbox with black padding, no stretching)

Save all final assets to `{post_folder}/` -- keyframes in `keyframes/`, video versions in `versions/`, platform-resized final videos in `final/`:
- **Video files** (.mp4) — post-processed and resized per platform
- **Script** — timestamped narration/dialogue
- **Storyboard** — shot-by-shot visual breakdown with keyframe references
- **SRT subtitle file** (.srt) — for captioned playback

## Output Per Video Post

| Asset | Format | Always Generated |
|-------|--------|-----------------|
| Script | Markdown | Yes |
| Storyboard | Markdown + keyframe images | Yes |
| Thumbnail | PNG/WebP (via compose-creative) | Yes |
| First frame | PNG | Yes (Stage 2) |
| Last frame | PNG | Yes (Stage 3) |
| AI Video Clip | MP4 via WaveSpeed / Kling v3.0 Pro (image-to-video, 3-15 seconds) | If pipeline completed |
| SRT subtitles | .srt | If video generated |

## Video Types

| Type | Duration | AI Generation | Production Notes |
|------|----------|--------------|-----------------|
| hero_video | 30-90s | Partial — AI generates 3-15s hero clip; full version needs filming | Script + storyboard + AI teaser clip |
| mini_case_study | 30-60s | Yes — AI animation from keyframes | Full pipeline supported |
| short_reel | 15-30s | Yes — ideal for AI generation | Full pipeline supported |
| story | 15s | Yes — image-to-video animation | Full pipeline supported |
| talking_head | 30-120s | No — needs filming | Script + storyboard only (use `--script-only`) |

## Rules

- Every stage requires explicit user approval before advancing
- `--script-only` skips Stages 2-4 and generates script + storyboard only
- `--thumbnail` generates a video thumbnail via compose-creative (independent of the pipeline)
- AI video clips are never auto-saved; user must confirm the final selection
- Thumbnails use the same creative mode system as static images
- All assets save to `{post_folder}/` -- keyframes in `keyframes/`, video versions in `versions/`, final video in `final/`

## Timeout & Fallback

- AI video generation (Stage 4): **300-second timeout** (Kling v3.0 Pro can take several minutes for high-quality output)
- Keyframe generation (Stages 2-3): 60-second timeout per image
- If video generation fails or times out, deliver script + storyboard + keyframes as fallback