/generate-video

name: generate-video
description: "Generate short-form video clips via a 5-stage human-in-the-loop pipeline: concept, first frame, last frame, 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}/socialforge/brands/<brand>/asset-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** (Nano Banana Pro / Gemini 3 Pro Image, resolved via `latest-image-google`) — 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 / Nano Banana Pro)

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 / Nano Banana Pro)

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 recommended (Instagram Reels and YouTube Shorts accept up to 3 min) | Yes — ideal for AI generation | Full pipeline supported | | story | up to 60s per frame (Instagram Stories) | 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