simonmesmith/agent-skills/video-overview-generator

Video Overview Generator

Create document-grounded narrated videos from static generated images, voiceover, captions, and deterministic video assembly. Do not imply this skill generates motion-video footage. It creates an editable storyboard and renders a conventional video file from still images and audio.

Default Decisions

• Project folder: create all work in a new video-overview/ folder unless the user names another destination.
• Source ingestion: extract source text into source_map.json before writing a storyboard.
• Storyboard source of truth: use storyboard.json. Export storyboard.csv only for easier human editing.
• Image default: gpt-image-2, 2048x1152, medium, PNG, 16:9.
• Audio default: gpt-4o-mini-tts, voice alloy, MP3.
• Brand/icon default: start with #2563EB, then update agents/openai.yaml to match the final icon accent after sampling the generated PNG.
• Disclosure: include a brief note in user-facing deliverables when the audio is AI-generated.
• Cohesion default: define one project-level visual_direction and narration_direction before writing rows, then make every image prompt and spoken segment follow those directions.

Workflow

1. Set up project files

• Copy or reference the user's documents.
• Run scripts/ingest_sources.py <source paths...> --out video-overview/source_map.json.
• Read references/storyboard_schema.md before drafting or editing storyboard.json.

1. Create the storyboard

• Write a concise, source-grounded sequence of rows in storyboard.json.
• Add a project-level visual_direction describing palette, composition, rendering style, lighting, recurring motifs, and avoid-list.
• Add a project-level narration_direction describing tone, pacing, audience, voice continuity, and pronunciation notes if needed.
• Keep each narration_text under 4096 characters for the speech endpoint; prefer 20-80 spoken words per row.
• Write image prompts that describe a single strong 16:9 still image and explicitly inherit the same visual direction. Avoid precise in-image text unless the user explicitly needs it.
• Keep speech elements aligned: same voice, tone, cadence, audience, and vocabulary level unless the user asks for a format shift.
• Include source_refs for traceability.
• Run scripts/create_storyboard.py --validate storyboard.json --csv storyboard.csv.

1. Generate media

• Require OPENAI_API_KEY for live OpenAI API calls.
• Run scripts/generate_media.py storyboard.json --media-dir media.
• The script writes one image and one audio file per row and skips unchanged assets using hashes in manifest.json.
• Use --ids row_001,row_004 to regenerate selected rows.

1. Render the video

• Run scripts/render_video.py storyboard.json --media-dir media --out output/video-overview.mp4.
• The renderer uses actual audio durations, creates captions, and concatenates row clips.
• If only timing, captions, or transitions changed, rerender without regenerating API assets.

1. Iterate safely

• For narration edits, regenerate only affected audio rows.
• For image prompt edits, regenerate only affected image rows.
• For timing/caption edits, skip API calls and rerender.
• Preserve old assets unless the user explicitly wants cleanup.

Resource Map

• references/storyboard_schema.md: required storyboard fields, defaults, and edit rules.
• scripts/ingest_sources.py: extract text from TXT, Markdown, JSON, CSV, PDF via pdftotext, and DOCX via OOXML.
• scripts/create_storyboard.py: validate JSON, normalize defaults, export/import CSV.
• scripts/generate_media.py: call OpenAI image and speech endpoints row by row with caching.
• scripts/render_video.py: assemble still images, row audio, and captions into MP4 with ffmpeg.
• scripts/regen_item.py: patch one row from CLI flags and regenerate only needed assets.
• assets/icon_prompts.json: prompts used to generate this skill's icon family.
• assets/brand.json: provisional and sampled brand color metadata.

Quality Checks

• Validate storyboard.json before media generation.
• Confirm every row has an image, audio file, and measured audio duration before final render.
• Confirm images are 16:9 when rendered into the final video.
• Confirm the image sequence feels like one designed system, not five unrelated generations.
• Confirm narration sounds like one coherent host/script, not disconnected row snippets.
• Confirm final video duration roughly matches the sum of row audio durations.
• Report any missing external tools (ffmpeg, ffprobe, pdftotext) plainly.