interactive-explainer

Use when the user wants educational explainers with a host plus in-story characters, history or science shorts, or witness and expert dialogue—not wall-to-wall narration alone.

Educational explainer (narrator + character interaction)

Not wall-to-wall narration. Alternate host / narrator VO (p-video + TTS) with people in the story speaking (p-video-avatar + voice_script) — historians, scientists, witnesses, animated guides, etc.

Canonical scene patterns: educational-explainer-scenes.md
Motion (dynamic, physics-safe): educational-explainer-motion.md
Narrator triple spec: scene-anchor-triple.md

See p-video, p-video-avatar, p-image, p-image-edit, gemini-3.1-flash-tts.

For narrator-only explainers, use multi-scene-ai-video instead.

Staged generation: staged-generation-gate.md — approve plan → stills → narration TTS → video clips → assembly + bed. Default runner phase is stills.

Quick reference

Resource	Path
Positive prompts / blocked phrases	interactive-explainer-prompts.md
Scene patterns & stand-alone test	interactive-explainer-scenes.md
Motion (OPEN/MID/CLOSE)	interactive-explainer-motion.md
Feedback discipline	requesting-generation-feedback
Runner	run_from_plan.py · --phase stills|tts|video|assemble · --approve-stills · --approve-clips
Plan template	explainer-plan.template.json

Subject flavors (pick one style_bible)

Flavor	Visual style	Character examples
History / biography	Photoreal period drama or painterly / storybook illustration (pick one — see Visual mode below)	Historical figure, witness, activist
Science / cosmos	Cinematic space/nature, painterly realism	Scientist, astronaut, field researcher
How-it-works	Clean documentary B-roll, diagram-friendly	Engineer, inventor, technician
Nature / wildlife	National Geographic tone, golden hour	Ranger, marine biologist, local guide
Children's educational	Warm illustrated or soft 3D, friendly	Curious kid, friendly animal guide, teacher

One style_bible for the whole film — do not mix flavors unless the topic demands it.

Defaults (720p / 24 fps)

Every plan should set:

json

"defaults": {
  "resolution": "720p",
  "fps": 24,
  "aspect_ratio": "16:9"
}

• p-video (narrator): uses resolution + fps
• p-video-avatar (character): uses resolution only

Template: explainer-plan.template.json

Motion (dynamic, physics-safe)

Every scene needs visible motion — but not physics-heavy action. See educational-explainer-motion.md.

Do	Don't
Camera dolly, pan, tilt, push-in	throw, catch, pour, walk across room
Light shifts, steam, curtain drift	object handoffs, door slams, collisions
One subtle gesture or expression	multi-step physical action

Write video_prompt as OPEN: → MID: (attention hook) → CLOSE: (settle on end still). Keep camera moves slow and deliberate (use 1080p / 48 fps only when the user asks for final delivery).

Intake: ask before generating

Topic	Questions
Topic	What should the viewer learn? Key facts or story beats?
Audience	Kids, general public, enthusiast? Sets tone and vocabulary
Flavor	History? Science? Nature? How-it-works? Illustrated?
Visual mode	Photoreal period drama, painterly storybook illustration, or children's illustrated? (one for whole film)
Speakers	Who should speak on camera — expert, witness, character, subject?
Interaction mix	Target ≥ 35% character beats — who speaks, in what order?
Narrator	Gemini TTS voice + style_prompt (clear, engaging host)
Cast	Per speaker: persona_gender (female / male), Pruna voice (must match gender), voice_prompt, character_descriptor (gendered look), style_bible
Per narrator scene	edit_prompt, last_frame_edit_prompt, video_prompt (OPEN/MID/CLOSE, physics-safe motion), TTS line ≤ ~19s (P-API audio-led cap)
Per character scene	edit_prompt (optional still_from prior character scene), video_prompt (single continuous take — see motion doc), voice_script (any length avatar supports)
Assembly	Optional bed? Crossfades?

Draft the full scene table as a dialogue arc before any API calls. Confirm with user (Phase 0 — plan). Do not call generative APIs until the user replies approve plan / go.

Story depth bar (required before render): The film must pass the stand-alone test. If the story is a biography, pick one through-line — not a life survey.

Feedback gates (required)

Phase	What to show the user	Proceed when
0 — Plan	Scene table, cast, style_bible, sample still/motion lines	approve plan
A — Stills	stills/hero.png, scene start/end PNGs	approve stills
A2 — TTS	audio/narration_*.mp3 — listen for pace and length	Lines OK → phase video
B — Video	clips/*.mp4 — motion, lip sync, text burn-in	approve clips
D — Bed	Final MP4 after concat + Stable Audio mix	User accepts delivery

Ask when art direction is unclear (visual mode, cast continuity, narrator vs character mix, bed yes/no) — see staged-generation-gate.md.

Scene table (template)

#	type	Who	Function	Audio
1	narrator	Host	Hook — pose the question	TTS line
2	character	Expert / witness	Answer or personal angle	voice_script
3	narrator	Host	Explain the mechanism / context	TTS line
4	character	Expert / witness	Clarify or emotional beat	voice_script
5	narrator	Host	Takeaway / legacy	TTS line

Scene types

type	Model	Stills	Audio
narrator	p-video	start + end via p-image-edit	TTS → upload → input.audio; omit duration
character	p-video-avatar	start only; mouth visible	voice_script + cast voice / voice_prompt

Default if omitted: narrator (backward compatible with older all-VO plans).

Workflow

Phase	Action
0	p-image hero (+ optional _cast_* anchor stills from anchor_still_prompt)
1	Parallel p-image-edit start stills (all scenes)
2	Parallel end stills (narrator only)
A2	Parallel Gemini TTS (narrator only, ≤ ~19s per line)
B	Parallel p-video triples + p-video-avatar (avatar may exceed 20s)
C/D	Concat ± stable-audio-2.5 bed

Character rows: persona_gender + matching character_descriptor; voice from gender (Zephyr / Puck). Use still_from or _cast_* when hero is B-roll/objects. Avatar text suppression: positive stills + default avatar_negative_prompt token list — interactive-explainer-prompts.md.

Assembly: optional crossfades via assembly.hard_cut_crossfade_seconds; still_from_end for bookend narrator rows. Re-run --assemble-only to fix concat without regen video.

Scripting rules

Dialogue arc, stand-alone test, causal chain, visual–audio alignment, visual modes, and three-beat ending: interactive-explainer-scenes.md.

Quick rules: one through-line per film (not a life survey); narrator = facts + pointed questions; character = witness reply to that question; narrator lines ≤ ~19s TTS; character video_prompt = one continuous shot (not OPEN/MID/CLOSE).

Common mistakes

Anti-patterns:

• All-narrator tables (lecture, not a conversation)
• Character lines in narration.scene_lines (wrong voice pipeline)
• Gemini TTS voice names on p-video-avatar (use Pruna voices)
• Missing lips in frame on character stills; facing camera in character still prompts (use video_prompt for on-camera delivery)
• Missing persona_gender on cast / voice not matching generated avatar gender
• Negative or avoidance prompts — no …, avoid …, not … in stills, style_bible, or video_prompt; use explicit positive props and surfaces instead
• Still-prompt blocked substrings — see interactive-explainer-prompts.md
• Biographical life-survey cramming vs single through-line
• Motivational character lines instead of witness detail
• Narrator rows that combine two visual chapters in one still
• Static video_prompt (OPEN: hold. CLOSE: hold.) — always add a MID motion beat
• Physics-trap motion (throwing, pouring, walking, prop handoffs) — see educational-explainer-motion.md
• 720p / 24 fps unless user explicitly requests draft quality
• Missing causal chain — climax without prerequisite beats (mechanism, local standoff, deadline)
• Visual–audio mismatch — character interior while narration describes harbor, ships, or courts
• Visual mode mismatch — photoreal still lines under a storybook style_bible, or painterly / illustration lines under a photoreal style_bible
• Thin ending — single consequence sentence; no punishment → collective response → next war/reform step
• No narrator wrap — film ends on character witness or aftermath only; viewer never gets recap / hook payoff

Portable runner

Default --phase stills. Phased commands: workflow-feedback-gates.md Interactive explainer.

Flags: --phase stills|tts|video|assemble|all · --approve-stills · --approve-clips · --assemble-only · --only SCENE_ID · --regen-stills · --regen-tts · --regen-clips

Requires PRUNA_API_KEY; optional bed needs REPLICATE_API_TOKEN.

Related

• Prompt tables: interactive-explainer-prompts.md
• Feedback: requesting-generation-feedback
• Narrator-only: multi-scene-ai-video
• Visual transitions (no VO): scene-transition-video
• Hub: pruna-generative-pipeline (Recipe R)
• Example prompts: examples/workflows/verticals/interactive-explainer/example-prompt.md
• Example plans (local workspace): output/verticals/interactive-explainer/<project-slug>/plan.json — see output/README.md