explainer-video

# Explainer Video

Use this workflow to turn information into a clear finished video. The information is the product: topic, script, logic, data, product mechanism, or voiceover. Visuals support understanding. Explainer Video owns the section plan, narration mode, timing order, assembly, and QA; `create-motion-graphics` is the helper workflow for direct Motion Graphic authoring and placement.

## Workflow

1. Read the project state, prompt, attached files, assets, transcript, and timeline.
2. Identify the working labels:
   - `explainer_start`: `topic_only`, `script_or_outline`, `voiceover_or_transcript`, `product_or_data`, `reference_assets`, or `direct_mg_animation_brief`.
   - `source_structure`: `free_topic`, `script_sections`, `timestamped_sections`, `slides_or_pages`, `existing_voiceover`, `uploaded_assets`, `product_or_data`, or `mixed`.
   - `narration_mode`: `generated_tts`, `existing_voiceover`, `transcript_only`, or `none`.
   - `visual_mode`: `motion_graphics`, `stock_or_uploaded_footage`, `generated_video_or_images`, or `mixed`.
3. Respect source structure. If the user provides structured material such as timestamps, numbered sections, slides/pages, scene labels, chapters, bullet outline, product points, transcript ranges, or voiceover sections, use that as the default planning scaffold. Merge, split, reorder, or relabel only when there is a clear production reason; explain the change and get user acceptance before treating it as the plan.
4. Ask only for missing details that change the result: topic or script, target length, audience, platform/aspect ratio, language/voice, visual mode, tone, brand/style constraints, and whether to plan first or create directly.
5. If more than one detail is missing, load `widget-forms` and ask in one `<widget>`. Use text fields for topic/script/context and single-choice fields for duration, platform, language/voice, and visual mode.
6. Complete the preflight before writing visual treatments. The plan must have values for:
   - `source_structure`
   - `narration_mode`
   - `visual_mode`
   - `animation_reference`: `read` or `not_needed`
   - `visual_direction_source`: active Design Style, chosen preset, concrete user style/reference, accepted role anchor, explicit proceed-without-alignment, or `not_needed`
   - `voice_selection`: confirmed concrete preset, audition needed, or `not_needed`
   - `timing_source`: actual voiceover/transcript ranges, generated TTS duration, user timestamps, planned duration, or `not_needed`
7. Animation Reference Gate. If any section may use motion graphics, animation, animated diagrams, data animation, mechanism visualization, abstract concept visualization, or MG overlays, read [references/explainer-animation.md](references/explainer-animation.md) before writing those visual treatments. If the visual plan uses only stock footage, uploaded footage, generated live-action/video clips, or still images, mark `animation_reference: not_needed` and continue without loading it.
8. Motion Graphic Direction Gate. If any section will generate MG/animation, load `create-motion-graphics` before asking the user to choose visual style. Use it to read the existing project visual language, align or confirm the Design Style, and directly author and place the Motion Graphic. Explainer Video still owns narration mode, section order, timing, assembly, and QA. Before final MG authoring, confirm visual direction through one of: active Design Style, catalog Design Style preset chosen from visual cards, concrete user style/reference, accepted role anchor, or explicit proceed-without-alignment. Treat broad hints such as "clean", "modern", "technical", "cinematic", or "tech style" as filters for preset selection, not as enough to generate final MGs. Do not invent text-only style choices before checking presets; assistant-written style options are fallback alignment, not a catalog preset.
9. Build a compact explainer plan only after the relevant gates above are complete:
   - viewer promise or thesis
   - preserved or proposed sections
   - narration source and timing source
   - narration-to-visual map per section: narration text or time range, visual goal, visual treatment, source assets, and sync risk
   - assumptions and claims that need grounding
   - first visible result to create before batching
10. For `topic_only`, write a short outline before drafting or generating. For `script_or_outline`, preserve the user's claims and meaning while tightening structure. For `product_or_data`, explain the mechanism or value without inventing unsupported claims. For `direct_mg_animation_brief`, do not force a broad explainer outline; inspect the provided script, assets, references, transcript, or style target, then create the requested MG section, intro, diagram, or overlay inside the same gates.
11. Voice Gate. For `generated_tts`, load `voice` before recommending voices, choosing a preset, or submitting TTS. If the user has not confirmed a concrete voice preset, follow `voice` to read the curated voice list and show an audition widget first. Do not infer a `voiceId` from the content topic, language, gender, or broad style words.
12. Create or align narration only when needed. For `generated_tts`, draft or tighten section-level narration lines first; estimate whether they fit target timing before submission, rewrite obvious mismatches, generate/place TTS by section only after the Voice Gate is complete, then read actual audio duration before any matching narration-backed MG/animation generation. Do not submit TTS and its matching MG in the same parallel batch. For `existing_voiceover`, do not regenerate narration; transcribe or read the audio and split it into section time ranges before generating matching visuals. For `transcript_only`, confirm whether the transcript should become TTS, captions, or only structure if ambiguous. For `none`, skip narration sync and plan visuals from the information structure and output rhythm.
13. Produce visual