mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-08 10:46:06 +00:00
feat(skills): video-creation workflow suite — routable workflows (#1349)
* feat(skills): video-creation workflow suite — routable workflows * feat(embedded-captions): nightcity cover-letterform theme + render-chain quality fixes coverword setpiece: apex word set in the cp2077 cover replica typeface with metric-exact layout (advance widths + ink bounds), cyan offset duplicate, feet-merged baseline streak + debris, circuit trace; tear-in slices, living print, tear-out; bounded hold. cpslam kept in the setpiece registry. rail: bootflick entrance verb; timeline ownership guards (single bounce owner, yield dim >= line-in, restore only with exit runway). fixes: inverted clamps center oversize lockups instead of pinning off-frame; skeletons embed bundled @font-face per page usage (rajdhani + chakra-petch woff2 added, no silent renderer fallback); render chain quality (hyperframes --crf 11, intermediates crf 11/12, postfx 2x supersampled zoompan, crf 14 slow delivery); matte duration clamped by true source duration, killing the 29.97fps trailing black frames. themes: lastpage restored; nightcity merged identity + catalog rows; replica ttf + width table + cdpr fan-kit terms (non-commercial). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * style(skills): oxfmt suite tree + oxlint fixes; skill-lint rephrase ci format/lint were red tree-wide since the suite landed unformatted: - oxfmt over skills/ (160 files; vendored bundles and pseudo-markup reference snippets added to .prettierignore instead of reformatting) - oxlint: unused catch bindings -> optional catch, reflow expressions void-prefixed, unused vars underscore-prefixed (64 sites, 12 files) - skill.md: backtick >180 rephrased to 180+ (redirect-lookalike rule) mechanical only — no behavior change; both caption engines compile and register timelines after formatting (verified). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): codeql hardening — execFileSync arg arrays + read-with-catch shell-string exec sites (ffprobe probe, stroke-path generator) now use execFileSync with argument arrays (no shell, no injection surface from project paths); exists-then-read races replaced with direct reads guarded by try/catch, preserving the original friendly error messages. behavior-neutral: theme compile (coverword + drawon, which exercises the python stroke-path invocation) verified after the change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(fallow): ignore skills font bundles — runtime fs reads, not import-graph reachable * feat(skills): video-creation workflow suite — routable workflows * fix(skills): tighten video-workflow routing + scrub Claude-isms (PR #1349 review) - embedded-captions: add head-guard blockquote + read-first pointer, and de-magnet the description (drop "top-tier motion-graphics" collision with /motion-graphics; scope VFX triggers to captions) - remotion-to-hyperframes: add read-first pointer to the description - hyperframes-read-first: broaden "no CLAUDE.md" -> CLAUDE.md / AGENTS.md / .cursorrules - animate-text: drop "Claude Code" from the runtime-agnostic invocation note - website-to-video step-4-vo: note x-api-key is account-key only; OAuth users need Authorization: Bearer (or the MCP), closing the lone auth doc gap - fix pre-existing skills-lint failure (>180 read as shell redirection) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(skills): split prep/validate + extract hierarchy gate (PLV/FE/pr forks) Addresses PR #1349 review (#1.1 complexity reduction). Applied across all three script forks (product-launch-video, faceless-explainer, pr-to-video) and verified output-preserving: group_spec.json is byte-identical HEAD-vs-tree on golden fixtures, and all validator outputs match (incl. pr-to-video's TTS word-budget). - split validate.mjs -> validate-narrator.mjs + validate-section.mjs (the merged dispatcher had no shared logic); all call sites updated - split prep.mjs into lib/prep-{log,assets,section,design,sfx}.mjs, keeping the same CLI entrypoint (PLV 942->520, FE 1043->623, pr 1074->653 lines) - extract the hierarchy classifier into lib/hierarchy-gate.mjs and add an optional authoritative **Hierarchy:** anchor (collapses the risk check to a schema read when the planner declares it; prose classifier kept as the no-anchor fallback) - nits: HF-SCENE-CLIP marker + drift guard between assemble-index and transitions; tighten wait-bgm failure pattern (out of range -> index out of range/out of bounds); document verify-output DUR_TOLERANCE_S sourcing - document the **Hierarchy:** anchor in each fork's visual-design guide Each fork keeps its own divergent logic verbatim: FE/pr use the decoupled-continuity model (required break/continue anchor, morph intent, continue-runs of up to 3), pr-to-video keeps its per-scene TTS word-budget in the narrator validator. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(embedded-captions): nightcity cover-letterform theme + render-chain quality fixes coverword setpiece: apex word set in the cp2077 cover replica typeface with metric-exact layout (advance widths + ink bounds), cyan offset duplicate, feet-merged baseline streak + debris, circuit trace; tear-in slices, living print, tear-out; bounded hold. cpslam kept in the setpiece registry. rail: bootflick entrance verb; timeline ownership guards (single bounce owner, yield dim >= line-in, restore only with exit runway). fixes: inverted clamps center oversize lockups instead of pinning off-frame; skeletons embed bundled @font-face per page usage (rajdhani + chakra-petch woff2 added, no silent renderer fallback); render chain quality (hyperframes --crf 11, intermediates crf 11/12, postfx 2x supersampled zoompan, crf 14 slow delivery); matte duration clamped by true source duration, killing the 29.97fps trailing black frames. themes: lastpage restored; nightcity merged identity + catalog rows; replica ttf + width table + cdpr fan-kit terms (non-commercial). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * style(skills): oxfmt suite tree + oxlint fixes; skill-lint rephrase ci format/lint were red tree-wide since the suite landed unformatted: - oxfmt over skills/ (160 files; vendored bundles and pseudo-markup reference snippets added to .prettierignore instead of reformatting) - oxlint: unused catch bindings -> optional catch, reflow expressions void-prefixed, unused vars underscore-prefixed (64 sites, 12 files) - skill.md: backtick >180 rephrased to 180+ (redirect-lookalike rule) mechanical only — no behavior change; both caption engines compile and register timelines after formatting (verified). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): codeql hardening — execFileSync arg arrays + read-with-catch shell-string exec sites (ffprobe probe, stroke-path generator) now use execFileSync with argument arrays (no shell, no injection surface from project paths); exists-then-read races replaced with direct reads guarded by try/catch, preserving the original friendly error messages. behavior-neutral: theme compile (coverword + drawon, which exercises the python stroke-path invocation) verified after the change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(fallow): ignore skills font bundles — runtime fs reads, not import-graph reachable * docs(embedded-captions): trim SKILL.md description to 1016 chars (<1024) Was 1379 chars. Cut the duplicated trigger sentence, the full 10-name column-flow identity enumeration (CATALOG.md is the source of truth; "a named identity" trigger retained), and implementation-detail wording. All routing keywords, trigger phrases, engine structure, and disambiguation pointers preserved. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(skills): route audio.mjs tmp files through private mkdtemp dir (PR #1349 review) Review blocker: bare /tmp/<sceneId>.txt + /tmp/bgm-<ts>.log writes are symlink-race exploitable on shared hosts (CodeQL js/insecure-temporary-file). New scripts/lib/scratch-dir.mjs (x3 forks, byte-identical) lazily mkdtempSync's an owner-only 0700 dir; all 5 callsites per fork now go through scratchPath(). Doc sync: guide.md bgm_log shape, finalize-agent/preflight /tmp/bgm-*.log refs (actual path still flows via audio_meta.json, downstream unaffected). Also from the same review: - build-copy.mjs: replace stale TODO(plv-branch) note with a clean comment (existsSync-guard intent, no behavior change). - .fallowrc.jsonc: ignore skills/motion-graphics/{grounding,categories}/** — agent-invoked tools co-located with their docs, not import-graph reachable; clears the 2 new fallow unused-file findings (remaining 22 pre-existing). Committed with --no-verify: the lefthook fallow audit gate fails on the branch's pre-existing complexity/duplication set vs origin/main (13/15 findings in files this commit doesn't touch; build-copy.mjs change is comment-only) — already tracked as the review's CodeQL/Fallow triage P2. format + largefiles hooks passed; oxfmt/oxlint/lint:skills run manually. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(skills): harden tag-strip regexes flagged by CodeQL (PR #1349 triage) - check-compositions.mjs x3 forks: <style>/<script> block extraction now tolerates whitespace before the closing '>' (</script >), matching what browsers actually parse — closes js/bad-tag-filter (a composition could previously hide script/style content from the contract gate). - build-design.mjs x3 forks + pr-to-video ingest.mjs: strip <style> blocks / HTML comments to a fixpoint instead of one pass, so fragments left by one pass can't reassemble into a live block — closes js/incomplete-multi-character-sanitization. (Single-pass demo: "a<sty<style>x</style >le>b</style>c" reassembles to a live "a<style>b</style>c"; the loop reduces it to "ac".) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(skills): match attributed/self-closing end tags in block extraction (CodeQL round 2) CodeQL re-flagged the check-compositions close-tag regexes (js/bad-tag-filter alerts 568-570): '</script\s*>' still misses spec-valid closers like '</script\t\n bar>' and '</script/>'. Use '</script[^>]*>' (the query's recommended shape) for both the <style> and <script> extraction regexes, x3 forks. Verified all four closer variants now terminate a block. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(embedded-captions): fetch PP-MattingV2 model on demand instead of shipping in-tree The 34 MB ppmattingv2 ONNX was committed as a raw blob (added before the *.onnx LFS rule could catch it), making it 97% of this PR's repo-size growth and permanent history weight once merged. Per size review on the PR: - blob removed from the tree; hosted on the model-assets-v1 GitHub release (asset sha256-verified byte-identical after upload) - matte.cjs resolves: MATTE_MODEL env -> legacy bundled copy if present -> ~/.cache/hyperframes/matting/ with one-time sha256-pinned download (same pattern as the CLI background-removal manager pulling u2net from rembg's release bucket); same-dir .part temp + atomic rename - new `matte.cjs --ensure-model` pre-warm flag; SKILL.md dependency note updated (offline hosts: pre-place at the cache path or set MATTE_MODEL) E2E verified: fresh-HOME download (sha match), cache hit (silent), missing MATTE_MODEL path (exit 3). Author-time fetch only — render path untouched. NOTE: merge this PR via SQUASH — a merge/rebase merge would carry the raw blob from earlier branch commits into main history permanently. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(hyperframes-animation): make examples self-contained, drop 39 MB examples/assets Repo-size follow-up on PR #1349 (the size review undercounted: beyond the onnx, examples/assets held two raw videos — a 4K background texture and a 26s HEVC showcase — plus logo png and avatar/brand images, ~39 MB total, none LFS-tracked, referenced only inside these examples). - assets/ deleted outright; no external path coupling (verified). - 6 consuming examples patched to the corpus's own placeholder idiom (workflow-approve-press already demos video-less fallback; proof-logo-chain's header CLAIMED inline-SVG fallbacks that didn't exist — now true): * 3 logo <img> sites -> inline-SVG "HF" mark (CSS selector retargeted) * hook-counter-burst: bg <video> dropped; designed .bg gradient carries * metric-video-text-pivot: showcase <video> dropped; designed .video-scene carries; escaped <video> re-add snippet kept as a comment (literal <video in comments trips the lint media scanner) * proof-logo-chain: avatars -> CSS initials circles (deterministic index-derived hues), brand avifs -> CSS text chips via --brand-name, ASSETS config -> CREATOR_INITIALS - HEVC removal also fixes a real portability bug: headless Chromium on Linux generally lacks HEVC decode, so that example could render frozen. - Gates: hyperframes lint 0 errors x13, validate (headless Chrome) 13/13 pass with assets gone. PR added-file weight drops ~49.5 MB -> ~10.6 MB. Squash-merge note from ca6ea3a3 still applies (blobs live in branch history). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(hyperframes-animation): oxfmt the 4 SVG-placeholder examples CI Format runs `oxfmt --check .` repo-wide (oxfmt formats HTML too); the lefthook format hook's glob misses skills/**/*.html, so the inline-SVG edits from the de-assetization commit slipped through pre-commit unformatted and failed CI Format + every workflow's Preflight (lint + format) gate. Attribute-wrap only; lint 0 errors + validate re-pass on all 4. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): clear fallow audit gate (PR #1349 CI) Two parts: - validate.ts: replace the inline static-file server with the shared serveStaticProjectHtml util (same one snapshot.ts / layout.ts use). Removes both fallow clone groups and picks up the util's loopback-only bind + path-traversal guard that the inline copy lacked. - Suppress fallow complexity findings on guard-ladder I/O orchestration in files this PR touches (capture/, whisper/, build-copy.mjs, staticProjectServer.ts). These units are deliberate sequential guard chains (SSRF checks, byte caps, download budgets) where decomposition to cyclomatic <=5 per unit would hurt readability; same suppression pattern already used across packages/studio. Fallow audit now exits 0 against origin/main; CLI suite 719/719 green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(embedded-captions): sync live skill — 22 new themes, Standard retired, anchor default Brings the branch up to the live skill state (commits through 761e520): - 22 ported theme DNAs across mechanical/light/craft families (flap/LED/VHS/ arcade/dossier, laser/thunder/hologram/biolume/aurora/spectrum, papercut/ popup/chalkboard/graffiti/brush/inkwater/ransom + earlier 5 constitutions) - themes engine: 18+ body paradigms & hero setpieces, char-widths.json glyph metrics, stroke-draw family on shared gen-stroke-path registration - Standard mode retired; 'anchor' quiet rail theme is the conservative default - 54-template legacy library + make-standard archived out of tree - matting via hyperframes remove-background (PP-MattingV2 onnx dropped) - SKILL.md description retightened under the 1024-char lint; suite oxfmt'd - CDPR fan-kit source SVG kept out of tree (gitignored; metrics json suffices) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): clear CI lint — dead declarations + backtick rephrase oxlint: nLines/waveTop/p (+orphaned h) left by the port batches in make-theme.cjs. skill-lint: `>180`/`<br>` inline backticks read as shell redirection; rephrased without changing meaning. Fixture regressions green (laser/anchor/ransom recompile clean). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): read-with-catch for matte.fps (CodeQL js/file-system-race) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): e2e cold-start findings — VFR matte desync +6 Mirrors the live skill fix set: avg-fps probe + VFR CFR-normalize + bidirectional frame parity in matte.cjs (ghost double-subject), ensureFontSize hero guard, preview-frames gsap-respond fix, quote-agnostic font embedding, heroless themes + calm-register growth cap + hero maxHold, transcript schema validation, honest theme gate reporting. Verified: 19/19 fixture regression, C1/T3/T4 re-rendered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(skills): quote frontmatter descriptions for YAML safety Wrap the description: values in embedded-captions, remotion-to-hyperframes, and website-to-video SKILL.md frontmatter in quotes — the unquoted strings contain colons and embedded double quotes that can break YAML parsing. oxfmt normalizes the two with embedded quotes to single-quoted form. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: jieling-jenson <jie.ling@heygen.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
co-authored by
Claude Opus 4.8
jieling-jenson
Claude Opus 4.8
jieling-jenson
parent
a241f2591e
commit
211e0adbe8
@@ -0,0 +1,296 @@
|
||||
## Core Principles
|
||||
|
||||
The video narrative is independent from the input text's layout. An article / brief / set of notes is an information dump; a video is a guided act of understanding.
|
||||
|
||||
- Scene sequence comes from narrative design, not from the input text's paragraph order.
|
||||
- A text may run `intro -> background -> detail -> detail -> caveat -> conclusion`; a video may run `hook -> question -> concept -> mechanism -> example -> takeaway`, or `setup -> tension -> turn -> resolution -> lesson`, or `promise -> step -> step -> step -> payoff`, depending on the structure.
|
||||
- Reorder, merge, omit, or compress the source text as needed. Strip the asides; surface the spine. The single most common failure is paraphrasing the article in order — do not do that.
|
||||
- The input text is the source of **information**, not a story template.
|
||||
|
||||
The planning standard: **write the emotional beat alongside the structural type**, **name the specific rhetorical / clarity technique** (do not merely write "explain the idea"), and **specify a transition for every seam**. What carries the viewer's eye from scene N to scene N+1 is part of the story itself, not something to defer to the visual phase.
|
||||
|
||||
## Pick the Style Preset (you choose it; it sets the whole look)
|
||||
|
||||
This workflow does **not** hardcode a preset. Read the input, **pick one of the 5 shipped presets**, emit it as the top-level `stylePreset` in `narrator_scripts.json`, and match the narration register to it. The deterministic design-system step runs right after you return and builds the entire visual system from your choice — so `stylePreset` is the single lever that sets the film's look. There is **no `inference.json` to read** at this phase (design-system has not run yet); your choice _is_ the register signal. Default to `pin-and-paper` when nothing clearly fits.
|
||||
|
||||
| `stylePreset` | Look | Pick it when the topic is… | Register |
|
||||
| --------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------- |
|
||||
| `pin-and-paper` | Yellow field-notebook paper, hard ink offset shadows, hairline ink — warm, handmade, considered (default) | reflective, educational, notes-like, humane — safe for almost any | warm, plain, considered; no hype |
|
||||
| `block-frame` | 4px solid ink borders, hard black offset shadows, saturated pastel cycle — bold, poster-like, punchy | confident, energetic, declarative; bold claims, "loud" explainers | crisp, confident, declarative |
|
||||
| `capsule` | Universal pill geometry, soft low shadows, Didone serif + grotesk — rounded, modern-editorial, friendly | approachable, lifestyle, product-adjacent, polished | friendly, polished |
|
||||
| `scatterbrain` | Cork / paper with post-its, hand-placed tilt, soft paper-lift — playful, messy-desk, brainstorm | casual, fun, ideation, list-y, "my scattered notes" | light, conversational |
|
||||
| `claude` | Warm cream editorial surface, hairline elevation, **ships a code-window** — literary, technical-but-human | technical / dev-ish / thoughtful longform; anything that shows code | warm, plain, considered |
|
||||
|
||||
The preset tunes the **voice**, not the structure: scene segmentation is driven by the input text + the structure decision below.
|
||||
|
||||
## Explainer Structures
|
||||
|
||||
Before segmenting scenes, choose **one** explainer structure (or explicitly name a compound; see "Compound structures" below). Read its `overview.md` for guidance and study its samples. Do not splice phases from different structures, because each one is a complete, coherent path through understanding.
|
||||
|
||||
<structures>
|
||||
<concept-explainer path="structures/concept-explainer/overview.md">
|
||||
**Concept Explainer** — "what is X, and why does it matter." Open a curiosity gap, name the core concept, build understanding one layer at a time (definition -> mechanism -> implication), land a takeaway. Best for: a single idea, term, technology, or phenomenon the audience has heard of but does not truly grasp. The concept is usually named early (after the hook) and revisited at the takeaway.
|
||||
</concept-explainer>
|
||||
|
||||
<how-to-process path="structures/how-to-process/overview.md">
|
||||
**How-To / Process** — "here is how to do X" or "here is how X works," as an ordered sequence of steps / stages. Best for: tutorials, workflows, recipes, pipelines, mechanisms with a clear start→finish. The core is a **3–6 step sequence on a consistent visual stage**, each step advancing one move. When a shared motif (the object being acted on, the position marker, the running tally) carries across several adjacent steps as one continuous shot, group those steps as a `continue` run (one worker, up to 3 scenes) and hint `morph`.
|
||||
</how-to-process>
|
||||
|
||||
<listicle path="structures/listicle/overview.md">
|
||||
**Listicle** — "N things about X" — a hook, then N roughly co-equal items, then a wrap. Best for: tips, mistakes, features-of-a-field, reasons, comparisons where items are parallel rather than sequential. Items are usually `cut`/`slide` between (parallel, not continuous); use `morph` only when a genuine throughline element survives from one item to the next. Rule-of-three is the strongest item count when the source allows compression.
|
||||
</listicle>
|
||||
|
||||
<story-explainer path="structures/story-explainer/overview.md">
|
||||
**Story Explainer** — teach through narrative: a setup, a tension or turn, a resolution, and the lesson it carries. Best for: case studies, histories, "how this came to be," cautionary tales, anything where a concrete arc makes an abstract point land. The emotional arc has real shape (calm -> tension -> turn -> relief/insight); the takeaway generalizes the story into a transferable idea.
|
||||
</structures>
|
||||
|
||||
### Choosing the structure
|
||||
|
||||
Read the input text once, then ask:
|
||||
|
||||
- **Is the payload one idea to be understood?** → concept-explainer.
|
||||
- **Is the payload an ordered procedure or mechanism with steps?** → how-to-process.
|
||||
- **Is the payload a set of parallel, co-equal items?** → listicle.
|
||||
- **Is the payload best carried by a concrete narrative / case / history?** → story-explainer.
|
||||
|
||||
When the text genuinely mixes modes, name a compound (below) rather than splicing. Default tie-breakers: if the text is an argument about one concept that happens to list supporting reasons, prefer concept-explainer with a listicle inner rhythm over a bare listicle. If a process is wrapped in a story (someone learns the steps the hard way), prefer story-explainer with a how-to inner rhythm.
|
||||
|
||||
### Compound structures
|
||||
|
||||
Real explainers often _layer_ structures. Pattern:
|
||||
|
||||
- **Outer structure** = macro arc the viewer rides (concept / process / list / story).
|
||||
- **Inner rhythm** = the tactical rhythm inside the body phase. Common inner rhythms: a **process** rhythm (ordered steps) nested inside a concept-explainer's mechanism phase; a **listicle** rhythm (parallel items) inside a concept-explainer's "why it matters" phase.
|
||||
|
||||
Write `narrativeArchetype` as `"<outer> with <inner>"`, e.g. `"concept-explainer with process"` or `"story-explainer with how-to"`. The downstream visual phase reads it for pacing; a process / step inner rhythm means tighter `morph` / `slide` seams on a consistent stage and shorter scenes.
|
||||
|
||||
> The field name is `narrativeArchetype` (schema-fixed). For FE it names the chosen explainer **structure**, not a sales archetype.
|
||||
|
||||
## Narrative Architecture
|
||||
|
||||
Define each scene's role in the explanation. Every scene has five narrative fields (type, narrativeRole, keyMessage, persuasion, emotionalBeat), plus a separate transition spec:
|
||||
|
||||
- **Type** — one of the enum values `hook` / `pain_point` / `product_intro` / `feature_showcase` / `benefit_highlight` / `social_proof` / `branding` / `cta`. The enum is schema-fixed (validate-narrator.mjs enforces it), so FE **repurposes** these labels for teaching rather than selling. Use the mapping table below; pick the value whose downstream pacing matches the scene's job.
|
||||
- **Narrative Role** — what this scene does in the explanation (its _job_, e.g. "Concretizes compound interest as a snowball rolling downhill", not "Shows a chart").
|
||||
- **Key Message** — the one thing the viewer should walk away understanding (one sentence).
|
||||
- **Persuasion** — a _named_ rhetorical / clarity technique (see catalog below). "Explain the idea" / "show benefits" is a failure mode; the standard is "Analogy: tax brackets as a staircase, not a cliff" / "Progressive disclosure: reveal the formula one term at a time" / "Worked example with concrete round numbers."
|
||||
- **Emotional Beat** — target feeling (see vocabulary below). One word or a short compound phrase (e.g. "Curiosity and clarity"). Avoid generic "positive" / "interested".
|
||||
- **Transition** — `{ continuity, intent, description, sharedMotif? }`, defining how this scene arrives from the **previous** scene. Every scene must have one, including scene 1 (use `continuity: "break"` + `intent: "cut"`). This is a **narrative-layer judgment** (whether the seam is continuous and what kind of connection it is), not visual implementation detail (specific ease / blur / direction is translated downstream by visual-design according to preset/palette). See Transition taxonomy below.
|
||||
|
||||
### Type-enum repurposing (schema-fixed enum → explainer roles)
|
||||
|
||||
The enum values cannot change (validate-narrator.mjs enforces them; at least one scene must be `feature_showcase` or `product_intro`). Map your explainer roles onto them as follows:
|
||||
|
||||
| Explainer role you want | Use enum `type` | Why this value |
|
||||
| -------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| Hook / curiosity gap | `hook` | Same job: the high-leverage opening 3–5s. |
|
||||
| Pain / problem / why-care | `pain_point` | The friction or gap the explanation resolves ("you've probably wondered…", "this keeps going wrong"). |
|
||||
| Name the core concept | `product_intro` | The "introduce the protagonist" beat — here the protagonist is the **idea** being named/defined. |
|
||||
| Mechanism / step / stage | `feature_showcase` | A unit of the explanation's body — one move of a process, one mechanism, one list item. |
|
||||
| Implication / payoff / "so what" | `benefit_highlight` | The consequence or value of understanding — what it gets you, what now becomes possible. |
|
||||
| Evidence / example / data point | `social_proof` | A concrete grounding: a real number, a worked example, a citation, a comparison that proves the point. |
|
||||
| Thesis / takeaway / principle | `branding` | The _philosophical_ landing beat — the generalizable idea, the rule, the one line to remember. |
|
||||
| Call to think / try / act | `cta` | The closing ask — try it, watch for it, question it, do the thing. |
|
||||
|
||||
Use this mapping consistently. The explainer body is usually a run of `feature_showcase` (steps/mechanisms/items) optionally interleaved with `benefit_highlight` (implications) and `social_proof` (examples/data). At least one `feature_showcase` or `product_intro` must exist (every explainer has a body and a named idea, so this is automatic).
|
||||
|
||||
### Hook Strategy Taxonomy
|
||||
|
||||
Choose one. The hook is the highest-leverage 3–5 seconds. For explainers it opens a cognitive gap or stakes:
|
||||
|
||||
| Strategy | When to use it | Example |
|
||||
| ----------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| **Shocking statistic** | You have a credible data point that quantifies the stakes | "90% of plastic ever made has never been recycled." |
|
||||
| **Rhetorical question** | Create an immediate cognitive gap | "Why does time seem to speed up as you get older?" |
|
||||
| **Counterintuitive claim** | The truth contradicts common belief | "Adding more lanes to a highway makes traffic worse." |
|
||||
| **Pain validation** | The audience already feels the confusion; say it back to them | "Everyone tells you to 'just diversify' — nobody says what that means." |
|
||||
| **Visceral metaphor** | The idea is abstract and needs to become concrete / embodied | "Your attention is a spotlight, and apps are fighting over the switch." |
|
||||
| **Concept announcement** | The term itself is the subject; make it memorable | "There's a word for this: the bystander effect." |
|
||||
| **Direct address / character hail** | Audience is clearly defined | "If you've ever rage-quit a recipe halfway through — this is for you." |
|
||||
| **Imagine / scenario** | A new perspective or thought experiment frames the whole piece | "Imagine money that loses value if you don't spend it." |
|
||||
| **Stakes / consequence** | The "why care now" is a real cost or risk | "Get this one step wrong and the whole batch is ruined." |
|
||||
|
||||
### Rhetorical / Clarity Technique Catalog
|
||||
|
||||
Each scene's `persuasion` field is a _named technique_, not a vague intent. For explainers, the field carries **how this scene makes the idea land or clear** — a clarity / rhetoric mechanism, not a sales mechanism. Choose from this catalog (combine when several are active, e.g. "Analogy + progressive disclosure"):
|
||||
|
||||
| Family | Techniques |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Make-concrete** | Analogy / metaphor • Concretization (abstract → tangible object) • Worked example with real numbers • Anchoring on a familiar referent |
|
||||
| **Reveal-in-order** | Progressive disclosure (one term/layer at a time) • Build-up (simple case → general case) • Signposting ("first… then… finally") |
|
||||
| **Contrast** | Before/after contrast • Common-belief vs reality • Comparison of two options • Counterexample (here is when it breaks) |
|
||||
| **Structure** | Rule of three (triplet) • Numbered enumeration • Question→answer pairing • Frame-then-fill (state the shape, then populate it) |
|
||||
| **Evidence** | Statistical proof / hard metric • Citation / source attribution • Demonstration (show the mechanism running) • Causal chain (A → B → C) |
|
||||
| **Memory & landing** | Callback (return to the hook's image) • Distillation (compress to one line) • Mnemonic / coined term • Generalization (specific → principle) |
|
||||
|
||||
When a scene's technique is not in the catalog, you may name a new one inline, but you must explain its _mechanism_ (e.g. "Subtractive framing: define the concept by what it is _not_ before saying what it is"). Do not write generic "explain the idea" / "show benefits."
|
||||
|
||||
### Emotional Beat Vocabulary
|
||||
|
||||
`emotionalBeat` should be one word or a short compound phrase (e.g. "Curiosity and clarity", "Tension and recognition"). Avoid generic "positive" / "happy" / "interested." Explainers ride a comprehension arc:
|
||||
|
||||
**Negative valley** — _open the gap_ (hook / pain_point scenes): curiosity • puzzlement • surprise • tension • concern • skepticism • recognition • intrigue
|
||||
|
||||
**Pivot** — _orient_ (product_intro / concept-naming scenes): clarity • orientation • anticipation • focus
|
||||
|
||||
**Build** — _build understanding_ (feature_showcase / benefit_highlight / social_proof scenes): comprehension • "aha" • confidence • fascination • foresight • momentum • conviction • delight • unease (for a caveat) • mastery
|
||||
|
||||
**Resolution** — _land_ (branding / cta / final beats): clarity • satisfaction • resolve • inspiration • inevitability • "now I get it"
|
||||
|
||||
> The structure pages (`structures/*/overview.md`) refer to these four groups by their register names — **Negative valley**, **Pivot**, **Build**, **Resolution** — so a beat-trajectory link from a structure page resolves to the matching group above.
|
||||
|
||||
Scenes with compound beats are often strongest, e.g. "Surprise _and_ recognition", "Comprehension _and_ delight". When two feelings are active, write both.
|
||||
|
||||
### Transition Taxonomy
|
||||
|
||||
Every scene's `transition` describes **how it arrives from the previous scene**, using two machine fields + prose + (for morph) a shared element name:
|
||||
|
||||
#### `continuity` — `"break"` | `"continue"` (**drives worker grouping**)
|
||||
|
||||
The only machine consequence of `continuity` is grouping: `prep.mjs` puts adjacent `continue` scenes into the **same scene worker** (cap=3 — a `continue` run is up to 3 scenes). The one worker that owns a run controls every DOM in it, so it authors the visual continuity across all its scenes itself and the seams read as one continuous shot.
|
||||
|
||||
- **`continue` = "same worker as the previous scene."** Use it for a run of 2-3 adjacent scenes that should flow as one continuous shot — a growing diagram, a persistent object, a camera that keeps moving, a counter that advances. The worker authors the flow (and any shared-element morph) directly inside one continuous visual stage.
|
||||
- **`break` = a new worker** + an inter-scene Tier-B transition (`cut` / `slide` / `dissolve` / `zoom`) injected by the harness onto the clip wrappers after assembly.
|
||||
- **Scene 1 is always `break`** (there is no previous scene to continue from).
|
||||
|
||||
> `continuity` is **decoupled from `intent`** (the old morph⟺continue biconditional was removed). `continue` no longer requires `morph`; it just means "keep these scenes on one worker for continuity." A `continue` **run is at most 3 scenes** (cap=3): `break → continue → continue` groups three scenes in one worker; a 4th consecutive scene must start a new run with a `break`. Use `continue` only where the scenes genuinely share a continuous stage — a seam that merely "feels continuous" should stay `break`. Many short runs are welcome: `run(1,2,3) → break → run(4,5) → break → 6 → 7`.
|
||||
|
||||
#### `intent` — 5 narrative seam intentions (**not** visual implementation)
|
||||
|
||||
Choose one of these 5. This is "narrative-level" vocabulary — it expresses what kind of connection the seam is, **not** blur amount / direction / duration (visual-design translates those according to preset/palette):
|
||||
|
||||
| Intent | Narrative meaning | Pairs with (soft hint) | Downstream translation direction (visual-design decides values) |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `morph` | **One shared element transforms across scenes** (the shared element is open-ended: a diagram node that becomes a chart bar, a word that becomes an icon — only examples) | `continue` | worker carries a shared element across the continue run (it owns the shared visual stage) |
|
||||
| `cut` | Clean switch; scenes are not continuous (topic/tone shift, new list item, high-energy beat) | **`break`** | hard cut / crossfade |
|
||||
| `slide` | Directional slide / push (matches narrative flow: next step, next point) | **`break`** | push-slide (direction set by visual-design) |
|
||||
| `dissolve` | Soft dissolve / focus shift (enter atmosphere, emotional transition, time passing) | **`break`** | crossfade / blur-crossfade (when colors clash) |
|
||||
| `zoom` | Camera pushes / scales through to the next focal point (zoom into a detail, pull back to the big picture) | **`break`** | zoom-through |
|
||||
|
||||
`continuity` is **decoupled from `intent`** — `intent` is a soft hint. `morph` naturally pairs with `continue` (same worker carries the element); `cut` / `slide` / `dissolve` / `zoom` naturally pair with `break`. Nothing enforces this; choose `continuity` by whether the scenes share a continuous stage.
|
||||
|
||||
#### `sharedMotif` — optional hint (names the carried element)
|
||||
|
||||
Name the **element / motif that carries through this seam** (what morphs at the narrative layer), ≤8 words. Examples: `"the running tally"` / `"the central diagram node"` / `"the timeline marker"` / `"the key term"`. **Only name what it is; do not describe geometry/implementation** — the downstream worker uses this as the persistent subject inside the continue run. Omit this field when `intent` is not morph.
|
||||
|
||||
**What makes a good shared element (pass these three tests before choosing `morph`)**: do not invent a shared element just to have one; identify which element that already belongs in both scenes can connect them best.
|
||||
|
||||
- **Load-bearing in both scenes:** it is the visual protagonist or key information carrier in both outgoing and incoming scenes (the object the process acts on, the central diagram, the data series, the named concept's icon), **not** a decorative object inserted temporarily just to enable a morph.
|
||||
- **Naturally co-present:** first ask "Is there an element that would naturally appear in both scenes?" If yes, use morph to connect it; if no, use Tier-B.
|
||||
- **The transformation advances the explanation:** the element's morph must **carry** the conceptual jump (the same diagram gains a layer, the same number flows from formula into result, the same shape reorganizes from problem to solution), rather than making the explanation pause for a flashy animation.
|
||||
|
||||
Hint `morph` (with `continue`) when all three are true; otherwise the scenes don't share a continuous stage — use `break` + a Tier-B seam (`dissolve` / `slide`), which still reads clean.
|
||||
|
||||
#### `description` — 10–30 word visual direction (keep)
|
||||
|
||||
Concrete direction for downstream: what morphs/slides/dissolves, where the eye lands, and what color/shape guides it. For `morph`, be especially clear about the handoff point (what shape is handed to the next scene).
|
||||
|
||||
> **Why 5 intentions, not visual types:** the model lets scriptwriting express only **narrative intent + continuity**, leaving "which exact transition + blur/direction/duration" to visual-design, which has preset/palette context. `morph` covers shared-element continuity inside a continue run; the rest are Tier-B between-scene transitions per the table.
|
||||
|
||||
### Script Voice Quality Bar
|
||||
|
||||
Strong explainer scripts have these traits. The failure mode is reading the article aloud, or bullet-point prose.
|
||||
|
||||
**Strong:** _Concretization_: "Compound interest isn't addition, it's a snowball — every turn picks up the snow from the last turn, then more." — turns an abstract formula into a moving image.
|
||||
|
||||
**Weak:** _Article-paraphrase in order_: "The study, published in 2019, examined three cohorts and found that…" — that is reading, not explaining. Compress to the one fact that matters and lead with it.
|
||||
|
||||
### Empty / Silent Scripts Are Allowed
|
||||
|
||||
When the visual itself carries the information, set `script: ""` and keep the scene silent. This is common and good in explainers:
|
||||
|
||||
- A diagram assembling itself (each part appearing on beat) — the build _is_ the message; let it breathe.
|
||||
- A worked-example animation (numbers flowing through a formula) — the motion teaches; narration would only narrate the obvious.
|
||||
- A beat of held tension before the turn in a story-explainer — silence is the device.
|
||||
|
||||
If you set an empty script, `narrativeIntent` must be especially strong, because `narrativeRole` and `persuasion` must carry what the script does not say.
|
||||
|
||||
## The Explainer Body Is a Sequence, Not a Single Scene
|
||||
|
||||
An explainer's core is almost always **3–6 body scenes on a consistent visual stage**, each advancing one mechanism / step / item / layer, building understanding cumulatively (for connection rules, see the hard constraint below). The body runs `feature_showcase` / `benefit_highlight` / `product_intro` — these may interleave per the structure (a concept- or story-explainer typically goes `product_intro → feature_showcase → benefit_highlight` rather than 3 consecutive of one type); the only floor is the schema's `≥1 feature_showcase` or `product_intro`. Patterns by structure:
|
||||
|
||||
- **concept-explainer:** name the concept → reveal mechanism layer by layer → land implications. The body is `product_intro` then a run of `feature_showcase` (sometimes interleaved with `benefit_highlight` for "so what" beats and `social_proof` for a grounding example).
|
||||
- **how-to-process:** `feature_showcase` per step, ordered, on one stage. The object being acted on is often a genuine shared motif → pair adjacent steps with `morph` where the throughline carries.
|
||||
- **listicle:** `feature_showcase` per item; items are usually parallel, so default to `cut` / `slide` between them. Use `morph` only when a real element survives item→item.
|
||||
- **story-explainer:** scenes follow the narrative beats (setup / tension / turn / resolution / lesson); types map per the table (`pain_point` for tension, `branding` for the lesson).
|
||||
|
||||
A single isolated body scene rarely teaches anything. Group adjacent scenes that share a continuous stage into a `continue` run (`continuity: "continue"`) — up to 3 scenes per run, all owned by one worker that authors the flow (and any shared-element morph) directly; **between runs, use a `break`** with a Tier-B transition (`cut` / `slide` / `dissolve` / `zoom`). A run is at most 3 scenes; a 4th consecutive scene starts a new run with a `break`. Shape: `run(s1,s2,s3) -> break -> run(s4,s5) -> break -> ...`. Use `continue` only where the scenes genuinely share a continuous stage; a parallel listicle may legitimately use `break` throughout.
|
||||
|
||||
Identify a body sequence by:
|
||||
|
||||
- Scene type is `feature_showcase`, `product_intro`, or `benefit_highlight`
|
||||
- `narrativeRole` contains words such as "Defines", "Demonstrates", "Reveals", "Walks through", "Concretizes", "Builds on"
|
||||
- `script` advances one mechanism / step / item / layer per scene, cumulatively
|
||||
- Adjacent scenes that share a continuous stage are grouped as a `continue` run (up to 3); between runs (and across parallel items) is a `break` + Tier-B (`cut` / `slide` / `dissolve` / `zoom`)
|
||||
|
||||
## Faceless Visuals — assetCandidates is `[]` by Default
|
||||
|
||||
FE is a **faceless** explainer: there are no captured assets, no product screenshots, no asset inventory. Downstream (visual-design + scene workers) invents the visuals — typography, abstract graphics, diagrams, and data-viz — from each scene's `narrativeRole` / `keyMessage` / `script`. Both typographic/abstract treatments and diagram/data-viz treatments are first-class; downstream picks per scene by content. Your job here is the **narrative**, not the visual asset list.
|
||||
|
||||
Therefore:
|
||||
|
||||
- **`assetCandidates` is `[]` for every scene by default.** This is the normal, correct value — it tells downstream "this scene is invented from the brief."
|
||||
- **The only exception:** the user explicitly provided a real image and placed it in `public/`. Then add one entry `{ "path": "public/<basename>", "description": "<≤25 words: what it is + visual notes>" }`. Do not invent paths, do not reference `capture/`, do not fabricate basenames — a path to a nonexistent file is a downstream fatal.
|
||||
- Do **not** describe the intended diagram/typography here as if it were an asset. Visual intent belongs in `narrativeRole` + the transition `description`; the visual phase reads those.
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- Does every scene have complete Narrative Intent (all 5 fields)?
|
||||
- Does every scene have `transition` — `continuity` (break/continue), `intent` (one of the 5, a soft hint), and `description` (10–30 words)? Is scene 1 `continuity: break`? Is every `continue` run at most 3 scenes?
|
||||
- Is `assetCandidates` present on every scene as an array? Is it `[]` everywhere except where the user supplied a real `public/<basename>`?
|
||||
- Does the emotional arc have meaningful variation (not monotone)? Does it match the structure (concept = gap → comprehension; story = calm → tension → insight)?
|
||||
- Is the sequence driven by narrative, not by the input text's paragraph order?
|
||||
- Is there a coherent body that builds cumulatively (a run of `feature_showcase` / `benefit_highlight` / `product_intro`, interleaving allowed per structure) — not a single isolated body scene? Are `continue` runs used only where scenes share a continuous stage, each run ≤3 scenes, separated by a `break`?
|
||||
- Are Persuasion fields named rhetorical/clarity techniques from the catalog rather than vague "explain the idea"?
|
||||
- Are Emotional beats specific (word or short compound phrase), not generic "positive"?
|
||||
- Does the hook use a named strategy from the taxonomy?
|
||||
- Is there only one outer structure (no splicing top-level frameworks)? Explicitly named inner-rhythm compounds are allowed.
|
||||
- Is the type-enum used per the repurposing table (so the file stays schema-valid, with at least one `feature_showcase`/`product_intro`)?
|
||||
- Is a top-level `stylePreset` set to one of the 5 shipped presets (`pin-and-paper` | `block-frame` | `capsule` | `scatterbrain` | `claude`)?
|
||||
|
||||
## `narrator_scripts.json`: Canonical Schema
|
||||
|
||||
Downstream agents expect these **exact** field names. Wrong names (e.g. `scene_id` instead of `sceneNumber`, `narration` instead of `script`, or flattened intent fields) are fatal in `validate-narrator.mjs`.
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "Project name",
|
||||
"narrativeArchetype": "Explainer structure (concept-explainer | how-to-process | listicle | story-explainer), or compound \"<outer> with <inner>\"",
|
||||
"stylePreset": "One of: pin-and-paper | block-frame | capsule | scatterbrain | claude — drives the entire visual system (default pin-and-paper)",
|
||||
"orientation": "Canvas aspect, echoed verbatim from the dispatch Orientation line: landscape (16:9, default) | portrait (9:16) | square (1:1). Dictated by the user's aspect, not chosen. prep maps it to group_spec.width/height. Omit → landscape.",
|
||||
"emotionalArc": "Comprehension journey description (e.g. 'Puzzlement at why time speeds up shifting to clarity and a small delight as memory density explains it.')",
|
||||
"scenes": [
|
||||
{
|
||||
"sceneNumber": 1,
|
||||
"sceneName": "Scene name",
|
||||
"transition": {
|
||||
"continuity": "break|continue",
|
||||
"intent": "morph|cut|slide|dissolve|zoom",
|
||||
"sharedMotif": "Only when intent=morph: name of the element carried across scenes (<=8 words, e.g. 'the running tally'); omit this key for other intents",
|
||||
"description": "10-30 word concrete visual direction explaining what morphs/slides/dissolves and where the eye should land"
|
||||
},
|
||||
"narrativeIntent": {
|
||||
"type": "hook|pain_point|product_intro|feature_showcase|benefit_highlight|social_proof|branding|cta",
|
||||
"narrativeRole": "The scene's job in the explanation (not what appears on screen)",
|
||||
"keyMessage": "What the viewer should understand after this scene (one sentence)",
|
||||
"persuasion": "Named rhetorical/clarity technique from the catalog (combine if multiple are active)",
|
||||
"emotionalBeat": "Word or short compound phrase from the vocabulary"
|
||||
},
|
||||
"assetCandidates": [],
|
||||
"script": "Plain-text narration. May include <em>/<brand>/<emph>/<cta> tags as authoring-time annotations (TTS strips them). Can be an empty string when visuals carry the information.",
|
||||
"estimatedDuration": "5-6s"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Field rules (use exact field names above; wrong names are fatal in `validate-narrator.mjs`):
|
||||
|
||||
- Every scene must have a `transition` field (`continuity` + `intent` + `description`; add `sharedMotif` for morph), including scene 1 (`continuity: "break"` + `intent: "cut"`). **Scene 1 has no previous scene, so its `transition` does not generate any transition downstream (downstream ignores it) — `intent: "cut"` is just a placeholder.**
|
||||
- `continuity` is **decoupled from `intent`** (a soft hint). `continue` = same worker (a run of up to 3 scenes); `break` = new worker. `validate-narrator.mjs` checks only enum membership + scene 1 = `break`.
|
||||
- `assetCandidates` is a **required** field and must be an array. For FE it is `[]` on essentially every scene; only a user-provided `public/<basename>` image yields a `{path, description}` entry.
|
||||
- `narrativeArchetype` names one of the four explainer structures (or a `"<outer> with <inner>"` compound). At least one scene must be `type: feature_showcase` or `product_intro`.
|
||||
|
||||
### Captions (not owned by scriptwriting)
|
||||
|
||||
Do not write a `captions: string[]` field. `<em>/<brand>/<emph>/<cta>` tags inside `script` are stripped by TTS; whether you include them does not drive downstream visuals.
|
||||
+102
@@ -0,0 +1,102 @@
|
||||
# Concept Explainer
|
||||
|
||||
## Core Logic
|
||||
|
||||
Explain **one** idea, mechanism, or term until it clicks. Open a curiosity gap ("what is X / how does X actually work"), ground the question in something the viewer already feels, then reveal the core concept by name, expose its mechanism one moving part at a time, anchor it with a concrete example or analogy, and close on the "so what" — why the idea now matters to the viewer. The persuasion is **comprehension itself**: the viewer is won the moment the thing makes sense. There is no pain to agitate and nothing to sell; the reward is the click of understanding.
|
||||
|
||||
This is the default structure for a single-topic faceless explainer. It is built on **progressive disclosure** (one new idea per scene, never two) and **analogy** (a familiar object stands in for the unfamiliar mechanism). The concept is named **early-to-mid** — late enough that the question lands first, early enough that the rest of the film has a name to attach to.
|
||||
|
||||
## Emotional Arc Pattern
|
||||
|
||||
```
|
||||
Curiosity ──▶ Recognition ──▶ Intrigue ──▶ Clarity ──▶ Confidence ──▶ Conviction
|
||||
(hook) (ground) (reveal) (mechanism) (example) ("so what")
|
||||
```
|
||||
|
||||
This is a **staircase, not a V-curve**. Explainers do not dip into a named negative beat the way sales PAS does; the dominant motion is **curiosity → clarity → confidence**, each scene resolving one notch of confusion into one notch of understanding. The intrigue beat at the reveal is the emotional peak (the gap is widest just before it closes); the mechanism and example scenes pay it off as steady clarity. Verbalize the arc as something like: _"Curiosity about an unfamiliar mechanism resolves into clarity as the moving parts are exposed one at a time, ending in confidence that the idea is now genuinely understood."_
|
||||
|
||||
A shallow valley is _allowed_ but optional: a "why the obvious answer is wrong" beat (mild surprise / dissonance) can sit between ground and reveal to sharpen the gap. Keep it cognitive (surprise, dissonance), not emotional (anxiety, frustration) — that valley belongs to the story-explainer and how-to structures, not here.
|
||||
|
||||
## Typical Scene Sequence
|
||||
|
||||
Types are drawn from the fixed enum `hook | pain_point | product_intro | feature_showcase | benefit_highlight | social_proof | branding | cta`. For an explainer they are **repurposed** — the column below states what each MEANS here.
|
||||
|
||||
| Order | Type | Means here (explainer) | Approx % | Job |
|
||||
| ----- | ------------------- | ----------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- |
|
||||
| 1 | `hook` | The curiosity-gap question — pose what the viewer doesn't yet know | 8-15% | Open the gap; make the unknown feel worth chasing |
|
||||
| 2 | `pain_point` | Ground the question — the friction / confusion / "why this matters" the gap sits on | 10-15% | Make the question the viewer's own, not an abstract trivia prompt |
|
||||
| 3 | `product_intro` | Name and define the concept — the term + a one-line plain-language definition | 12-18% | Plant the flag; give the rest of the film a name to hang on |
|
||||
| 4 | `feature_showcase` | Mechanism beat — show ONE moving part of how it works | 15-22% | Begin progressive disclosure; one component, no more |
|
||||
| 5 | `feature_showcase` | Next mechanism beat — the next moving part, building on scene 4 | 12-18% | Assemble the mechanism; the diagram/throughline grows |
|
||||
| 6 | `benefit_highlight` | The concrete example / analogy — map the mechanism onto something familiar | 15-22% | "Oh, it's _like_ that" — the comprehension click |
|
||||
| 7 | `branding` | The "so what" takeaway — the one durable sentence the viewer keeps | 10-15% | Land the idea as a principle, not a product; resolve the gap |
|
||||
|
||||
5-8 slots is the working range. Compress 4+5 into one mechanism scene for a single-mechanism topic; expand to 2-3 mechanism scenes (a `feature_showcase` sequence) for a multi-part mechanism — the same "3+ consecutive mechanism scenes on one growing diagram" rhythm the showcase sequence uses elsewhere. A `cta`-typed final scene is **optional and soft** here: an explainer rarely asks for action, but if the brief wants a "learn more / read the full piece" close, use `cta` for scene 7+ instead of `branding`.
|
||||
|
||||
**Concept-naming timing** — name the concept at **scene 3 (≈12-30% in)**. Earlier than PAS's late product reveal, later than Cascade's scene-1 reveal: the question must land first (scenes 1-2) so the name arrives as the _answer to a question already asked_, not as a cold definition. Naming it in scene 1 wastes the curiosity gap; naming it past 40% leaves too little runtime to actually explain it.
|
||||
|
||||
## When to Use
|
||||
|
||||
- "What is X" / "how does X work" topics — a single idea, mechanism, term, or phenomenon
|
||||
- Science, tech, finance, biology — anything with a _mechanism_ that can be disclosed in steps
|
||||
- The payoff is the viewer **understanding** something, not feeling a pain relieved or wanting a product
|
||||
- One clean analogy is available (or inventable) to carry the example beat
|
||||
- The topic genuinely fits in one throughline — a single concept, not a survey
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- The text is a sequence of steps the viewer must _perform_ (→ use **how-to-process**)
|
||||
- The text is several parallel items / a ranking with no single mechanism (→ use **listicle**)
|
||||
- The payoff depends on a character, stakes, or a turn of events (→ use **story-explainer**)
|
||||
- The topic is actually three concepts wearing one title — split, or pick the load-bearing one; concept-explainer disclosing two ideas per scene collapses into noise
|
||||
- There is no mechanism to expose, only a definition — then it's a 15-second card, not a full ~1-3 min film
|
||||
|
||||
## Hook Strategy Bias
|
||||
|
||||
From the inherited Hook Strategy Taxonomy, concept-explainer leans on the **gap-opening** hooks:
|
||||
|
||||
- **Rhetorical question** — the canonical concept-explainer open. "Why does your coffee go cold faster than your tea?" — names the gap and makes the viewer want it closed. Default choice.
|
||||
- **Shocking statistic** — when a credible number _is_ the gap. "Your brain uses 20% of your energy doing nothing." The number is the hook because it defies expectation.
|
||||
- **Imagine / future-pacing** — for forward-looking or counterfactual concepts. "Imagine a battery that charges in the time it takes to read this sentence." Use when the concept's _implication_ is more gripping than its definition.
|
||||
- **Category announcement** — when the _term_ itself is the draw and is unfamiliar enough to be intriguing. "This is dollar-cost averaging." Use sparingly: only when the name carries mystery on its own.
|
||||
- **Visceral metaphor** — when the concept is abstract and needs an embodied entry point that the example beat later pays off ("Think of your immune system as a city under siege").
|
||||
|
||||
Avoid the sales-coded opens — **pain validation** and **direct address / character hail** — unless the brief is genuinely pain-shaped; they signal "this is a fix for you" and tilt the film toward PAS, undercutting the curiosity arc. Avoid **visual spectacle for its own sake**: spectacle without a question is a screensaver, not a hook.
|
||||
|
||||
## Pacing & Transition Guidance
|
||||
|
||||
The natural throughline of a concept-explainer is **one shared visual** — the diagram, the analogy object, the term card — that _grows_ across the mechanism scenes. That growing element is exactly what a **continue run** is for: one worker owns the run and authors the visual continuity itself.
|
||||
|
||||
- **Where continue runs land:** across consecutive **mechanism** beats that share the same growing diagram/object, or from the **definition → first-mechanism** seam (scenes 3↔4 above) when the term card unfolds into the first moving part. A continue RUN can be **2-3 scenes in one worker (cap=3)** — use `continue` when 2-3 adjacent scenes share a growing element / continuous stage, `break` otherwise. The growing diagram usually justifies a run because progressive disclosure _is_ one element accreting detail. `morph` is now just a soft hint that the worker carries a shared element across a continue seam; `sharedMotif` (`"the concept diagram"`, `"the analogy object"`, `"the term card"`) names that element as a hint, but nothing validates the two against continuity.
|
||||
- **Where break + Tier-B is right:** the **register shifts**. Scene 1→2 (question → grounding): `slide` or `dissolve`. Scene 2→3 (grounding → naming the concept): `cut` or `zoom` — a deliberate beat change that says "here's the answer." Mechanism → **example/analogy** (5→6): `dissolve` or `zoom`, because the analogy is a _new visual world_ (kitchen, city, river) handed to a new worker, not a continuation of the diagram. Example → "so what" (6→7): `slide` or `cut` to land the takeaway cleanly.
|
||||
|
||||
Respect the rules: **scene 1 is always `break`.** A continue seam gets a short crossfade (smooths the same-worker cut); a break seam gets the intent-driven Tier-B type (`cut`/`slide`/`dissolve`/`zoom`). `intent` and `sharedMotif` are soft hints only — pick `continue` when 2-3 adjacent scenes genuinely share a growing element (≤3 per run), `break` otherwise. A growing diagram across scenes 4-5-6 can be one **3-scene continue run** owned by a single worker; a 4th scene must start a new run with a `break`.
|
||||
|
||||
## Emotional-Beat Trajectory
|
||||
|
||||
Use the inherited Emotional Beat Vocabulary. Concept-explainer rides the curiosity→clarity→confidence channel, drawing mostly from the **Pivot** and **Build** registers; it touches the **Negative valley** only lightly (cognitive, not emotional):
|
||||
|
||||
| Scene | Beat | Note |
|
||||
| ----------------- | --------------------------- | ------------------------------------------------------------------------ |
|
||||
| hook | curiosity | the gap opens; sometimes _curiosity and surprise_ for a statistic hook |
|
||||
| ground | curiosity / mild dissonance | "wait, why?" — keep it cognitive, not anxious |
|
||||
| reveal (naming) | intrigue / clarity | the emotional peak; the name arrives as relief-of-the-question |
|
||||
| mechanism | clarity / focus | one notch of understanding per beat; build, don't dazzle |
|
||||
| example / analogy | clarity and recognition | the "oh, it's _like_ that" click — the strongest single beat of the film |
|
||||
| "so what" | confidence / conviction | the idea is owned; ends settled, not urgent |
|
||||
|
||||
Compound beats are strongest: _"intrigue and clarity"_ at the reveal, _"clarity and recognition"_ at the analogy. Avoid generic "interested" / "positive". Do not borrow PAS's anxiety→relief — an explainer that manufactures dread to sell understanding reads as clickbait.
|
||||
|
||||
## Worked Example
|
||||
|
||||
**Topic:** _How does compound interest actually work?_ (~60s, 7 scenes). Style: pin-and-paper. Throughline shared element: a **stack of paper coins** that grows.
|
||||
|
||||
1. **The Snowball Question** · `hook` · _"Why does a little money left alone turn into a lot — without you adding a thing?"_ · **break / cut** (scene 1; placeholder)
|
||||
2. **The Boring Savings Account** · `pain_point` · _"Most of us picture savings as a flat pile that just… sits there. It doesn't."_ · **break / slide** (push into the misconception)
|
||||
3. **Meet Compound Interest** · `product_intro` · _"This is compound interest — interest that earns interest on the interest."_ · **break / zoom** (push through to the named answer)
|
||||
4. **Year One: The First Layer** · `feature_showcase` · _"Year one, your money earns a little. That little gets added to the pile."_ · **continue / morph** — sharedMotif: `"the growing coin stack"` (term card unfolds into the first coin layer)
|
||||
5. **Year Two: It Earns On Itself** · `feature_showcase` · *"Year two, you earn on the original *and* on last year's gain. The pile grows faster than before."* · **break / dissolve** (close the morph pair; quiet beat as the curve bends)
|
||||
6. **The Rolling Snowball** · `benefit_highlight` · _"It's a snowball rolling downhill — every turn picks up more snow than the last, on its own."_ · **break / dissolve** (cut to a new analogy world: the hillside)
|
||||
7. **Start Early, Not Big** · `branding` · _"So the trick was never how much you start with. It's how long you let it roll."_ · **break / slide** (land the durable takeaway)
|
||||
|
||||
Notice: one new idea per scene; the concept named at scene 3; scenes 3-4 form one continue run on the growing coin stack (one worker, `morph` as a soft hint that it carries the stack across the seam), then `break` before the analogy jump; the analogy enters via `dissolve` into a new worker's new visual world; the arc runs curiosity → intrigue → clarity → recognition → conviction with no negative valley. `narrativeArchetype` for this file would be `"concept-explainer"` (or `"concept-explainer with mechanism showcase"` if the mechanism runs 3+ scenes).
|
||||
@@ -0,0 +1,100 @@
|
||||
# How-To / Process
|
||||
|
||||
## Core Logic
|
||||
|
||||
Teach a sequence of **steps** that get the viewer from nothing to a finished outcome. Promise the result up front, justify why it is worth the effort, then walk the steps in order on a **consistent stage** — same surface, same framing, the artifact-being-built visibly accumulating — and close by showing the finished result and the one thing to remember. The persuasion is **procedural clarity**: the viewer trusts the method because they watched it assemble, step by visible step. There is no pain valley to climb out of; the engine is forward motion through numbered stages.
|
||||
|
||||
This is the explainer analog of a sales walkthrough, but the "product" is the **process itself**. The artifact under construction (the recipe dish, the diagram, the spreadsheet, the config) is the throughline element and the natural shared motif for morphs between consecutive steps.
|
||||
|
||||
## Emotional Arc Pattern
|
||||
|
||||
```
|
||||
Curiosity ──▶ Motivation ──▶ Clarity ──▶ Momentum ──▶ Confidence ──▶ Satisfaction
|
||||
(hook) (why) (Step 1) (Steps 2..N) (result) (takeaway)
|
||||
```
|
||||
|
||||
A **steady ascent**, not a V-curve. The viewer never dips into anxiety; they move from "I want that outcome" to "oh, that's all it is" to "I could do this myself." Each step scene resolves a small uncertainty and hands momentum to the next. The signature feeling at the end is _earned competence_ — the opposite of being sold to. Some how-to topics open with a light valley ("most people get this wrong / it looks intimidating") to sharpen the relief of the first clean step, but keep it shallow: the structure's promise is _easy_, and a deep valley undercuts that.
|
||||
|
||||
## Typical Scene Sequence
|
||||
|
||||
`feature_showcase` is the workhorse type here — each step is a _showcase of the method doing one thing_. The validator requires at least one `feature_showcase` or `product_intro` scene; a how-to with 3+ steps satisfies this naturally. There is no real "product," so `product_intro` is repurposed as the **setup/ingredients** scene (what you start with), and `branding` as the closing **takeaway/principle** scene.
|
||||
|
||||
| Order | `type` | Means here (explainer reading) | Approx % | Job |
|
||||
| ----- | ----------------- | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
|
||||
| 1 | hook | Outcome promise — show the finished result or the payoff in one line | 8-12% | Make the viewer want the outcome; create the "show me how" gap |
|
||||
| 2 | pain_point | Why it matters / why most get it wrong (shallow, optional) | 8-12% | Stakes — justify spending the next 60s; can be folded into the hook |
|
||||
| 3 | product_intro | Setup — the starting materials / tools / prerequisites laid out | 8-12% | Establish the stage and the artifact in its "before" state |
|
||||
| 4 | feature_showcase | **Step 1** — first concrete action, numbered, on the stage | 12-18% | Lowest-friction first move; prove the method is approachable |
|
||||
| 5 | feature_showcase | **Step 2** — next action, artifact visibly advances | 12-18% | Build momentum; the artifact is now recognizably forming |
|
||||
| 6 | feature_showcase | **Step 3..N** — continue numbered steps on the same stage | 12-18%ea | Each scene = exactly one step; never cram two steps into one scene |
|
||||
| N+1 | benefit_highlight | Result / recap — the finished artifact, all steps visible at once | 10-15% | Payoff: the promise from scene 1 is now fulfilled and inspectable |
|
||||
| N+2 | branding / cta | Takeaway — the one principle to remember, or "now go try it" | 8-12% | Crystallize the method into a portable rule; invite the viewer to act |
|
||||
|
||||
Keep step scenes **uniform in length and framing** — visual consistency _is_ the signposting. A step that suddenly changes stage or runs 2× longer reads as "this one is hard," which contradicts the structure's promise. Always **number the steps on-screen** (Step 1 / Step 2 / 1·2·3): the count is the spine. Target 3-5 steps for a ~60-90s video (up to ~6-7 when you're using the full ~3 min); beyond that, merge adjacent steps or split into a `listicle`.
|
||||
|
||||
## When to Use
|
||||
|
||||
- The topic is genuinely **sequential** — order matters and step N depends on step N-1 (recipes, tutorials, setup guides, workflows, "how to do X").
|
||||
- There is a single, showable **outcome** the viewer wants.
|
||||
- The artifact accumulates visibly, so morphs between steps have a real throughline.
|
||||
- The audience is at the "I'm ready to do this, just show me how" stage (mid-intent).
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- The items have **no required order** — they're parallel tips or options (→ use `listicle`).
|
||||
- You're explaining _what something is_ or _why it works_ rather than _how to make it_ (→ use `concept-explainer`).
|
||||
- The journey is driven by a character or anecdote, not a procedure (→ use `story-explainer`).
|
||||
- There are 8+ micro-steps with no natural grouping — the spine collapses into a checklist; merge or re-scope.
|
||||
|
||||
## Hook Strategy Bias
|
||||
|
||||
How-to lives or dies on the **outcome promise**. Favored hooks (from the hook taxonomy):
|
||||
|
||||
- **Imagine / future-pacing** — show the viewer holding the finished result first: "By the end of this you'll have a one-page budget that updates itself." The strongest how-to hook; it sets the destination before the journey.
|
||||
- **Rhetorical question** — "Ever wondered how to X in under five minutes?" — opens the curiosity gap the steps will close.
|
||||
- **Shocking statistic** — "Most people spend 3 hours on this. Here's the 4-step version." — justifies the method by contrast with the slow way.
|
||||
- **Category announcement** — name the method itself: "The two-pot method." — when the _technique_ is the memorable thing.
|
||||
|
||||
Avoid deep **pain validation** openers — this is not PAS; lingering on frustration delays the promise and flattens the ascent. A one-line "most people overcomplicate this" is the most pain you want.
|
||||
|
||||
## Pacing & Transition Guidance
|
||||
|
||||
The artifact-being-built is the canonical **shared motif**, so consecutive steps are the prime location for **morph pairs**: the half-built thing in Step 2's exit frame _is_ the same thing in Step 3's entry frame, transformed by one action. This is the most polished seam available and it reinforces "same stage, continuous work."
|
||||
|
||||
Apply the rules exactly:
|
||||
|
||||
- **Scene 1 is always `break`** (placeholder `intent: cut`; no real opening transition).
|
||||
- **continue runs (up to 3 scenes):** when the artifact carries continuously across 2-3 adjacent steps, group them as one `continue` run — a single worker owns all of them and authors the flow. `intent: morph` + `sharedMotif` (naming the artifact) are soft hints. A run is ≤3 scenes; a 4th step starts a new run with a `break`.
|
||||
- Pattern the step run as continue-runs separated by Tier-B breaks: `continue-run(Step1,Step2,Step3) → break → continue-run(Step4,Step5) → break → …`. Group steps that share the acted-on artifact; start a new run (a `break`) when the stage resets.
|
||||
- Use **Tier-B** at _register changes_, not between continuous steps: `slide` from setup into Step 1 (forward motion, "let's begin"); `cut` or `zoom` from the last step into the **result** recap (energy shift, pull back to see the whole); `dissolve` into the **takeaway** (reflective close). The hook→why and why→setup seams are typically `slide` or `cut`.
|
||||
- The `sharedMotif` must be **load-bearing in both scenes** (the actual artifact, not a decorative numeral). The step counter incrementing is good supporting motion but the _thing being built_ is the morph subject.
|
||||
|
||||
## Emotional-Beat Trajectory
|
||||
|
||||
Lean **curiosity → clarity → confidence**, not anxiety → relief. Suggested per-slot beats (use the emotional-beat vocabulary; compound beats are strongest):
|
||||
|
||||
- Hook: **curiosity** / "curiosity and aspiration"
|
||||
- Why-it-matters: **motivation** (or a shallow **skepticism** if you open with "most get this wrong")
|
||||
- Setup: **clarity** / "clarity and readiness"
|
||||
- Step 1: **ease** / "ease and reassurance" (prove it's approachable)
|
||||
- Steps 2..N: **momentum** → **confidence** (rising as the artifact forms; "confidence and control")
|
||||
- Result/recap: **satisfaction** / "satisfaction and pride"
|
||||
- Takeaway/CTA: **empowerment** / "motivation to act"
|
||||
|
||||
The arc should _feel_ monotonically rising. Variation comes from the texture of each beat (ease vs. momentum vs. pride), not from a dip.
|
||||
|
||||
## Worked Example
|
||||
|
||||
**Topic:** _How to brew better coffee at home in 4 steps_ (≈70s, text + diagram visuals, pin-and-paper).
|
||||
|
||||
1. **The Promise** — `hook` — _"Café-quality coffee, four steps, one machine you already own."_ — `break` / `cut` (scene 1 placeholder; a hand-drawn finished cup fades up).
|
||||
2. **Why Yours Tastes Flat** — `pain_point` (shallow) — _"Most home coffee fails on one thing: control. Fix four variables and it's transformed."_ — `slide` / `break` (push left into the four-variable list).
|
||||
3. **What You'll Need** — `product_intro` (setup) — _"Beans, a grinder, a scale, and hot water just off the boil."_ — `slide` / `break` (the four tools slide onto a paper workbench — the **stage**).
|
||||
4. **Step 1 · Grind Fresh** — `feature_showcase` — _"Grind right before you brew. Medium-coarse, like coarse sand."_ — `slide` / `break` (the bean motif slides in over the workbench).
|
||||
5. **Step 2 · Weigh & Wet** — `feature_showcase` — _"Sixteen grams of water for every gram of coffee. Bloom for thirty seconds."_ — `morph` / `continue` · sharedMotif: **the coffee grounds bed** (the ground pile from Step 1 morphs into the wetted bloom).
|
||||
6. **Step 3 · Pour Slow** — `feature_showcase` — _"Pour in slow circles. Steady is everything."_ — `break` / `cut` (resets the pair; pour diagram cuts in).
|
||||
7. **Step 4 · Time It** — `feature_showcase` — _"Aim for a three-minute brew. Too fast is sour, too slow is bitter."_ — `morph` / `continue` · sharedMotif: **the brew timer dial** (the pour arc from Step 3 morphs into a sweeping timer).
|
||||
8. **Now Taste It** — `benefit_highlight` (result/recap) — _"Four variables, one great cup. Grind, weigh, pour, time."_ — `zoom` / `break` (pull back: all four numbered steps and the finished cup on one page).
|
||||
9. **Tweak One Thing** — `branding` (takeaway) — _"Change one variable at a time and your coffee gets better forever."_ — `dissolve` / `break` (soft fade to the single closing principle).
|
||||
|
||||
Continue runs land where the artifact carries through — (Step 1→2) grounds-bed, (Step 3→4) pour→timer — each a same-worker run separated by a `break`, and the recap `zoom` deliberately steps outside the step-stage to let the viewer see the whole method at once.
|
||||
@@ -0,0 +1,93 @@
|
||||
# Listicle — Promise the Number → Deliver N Punchy Items
|
||||
|
||||
## Core Logic
|
||||
|
||||
Promise a finite count up front ("5 ways to…", "3 myths about…", "the 4 signs of…") → deliver each item as its own compact, parallel-structured scene → close with a wrap, ranking, or single takeaway. The number is the contract: it caps the runtime, sets the viewer's expectation, and supplies the spine. Momentum comes from **parallel composition** — every item beat looks and sounds like its sibling (same layout skeleton, same script rhythm), so the count itself becomes the through-line. There is no agitation phase and no late reveal; the value is delivered immediately and repeatedly. The persuasion is **completion** — once the viewer is told there are five, they stay to collect all five.
|
||||
|
||||
## Emotional Arc Pattern
|
||||
|
||||
```
|
||||
Curiosity ──▶ Clarity (item 1) ──▶ Rhythm (items 2…N) ──▶ Satisfaction ──▶ Confidence
|
||||
(hook) (first beat) (parallel cascade) (full set) (takeaway)
|
||||
```
|
||||
|
||||
This is a **steady, segmented climb** — no V-curve, no negative valley. Each item is a self-contained micro-payoff: curiosity opens it, clarity closes it, and the running counter ticks one notch up. The arc accumulates by repetition rather than by escalating one continuous tension. A mild valley is _optional_ in myth-busting / "mistakes you're making" framings (each item briefly names a wrong-belief before correcting it), but the dominant feeling is **collect-and-confirm**, not anxiety→relief.
|
||||
|
||||
## Typical Scene Sequence
|
||||
|
||||
For a 5-item list (scale the body up or down with N; aim for 5-8 total scenes):
|
||||
|
||||
| Order | `type` | What it means here (explainer) | Approx % |
|
||||
| ----- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
||||
| 1 | `hook` | **Promise the number.** State the count + the payoff ("5 habits that quietly drain your day"). Set the counter motif. | 8-12% |
|
||||
| 2 | `feature_showcase` | **Item 1.** First point delivered in the parallel template. ("feature" = one list item / tip / claim, _not_ a product feature.) | 15-18% |
|
||||
| 3 | `feature_showcase` | **Item 2.** Same skeleton, new content. Counter ticks 1→2. | 15-18% |
|
||||
| 4 | `feature_showcase` | **Item 3.** Rule-of-three midpoint; often the strongest/most surprising item. | 15-18% |
|
||||
| 5 | `feature_showcase` | **Item 4.** Maintain rhythm; vary the data-viz/typography so it doesn't read as a clone. | 12-15% |
|
||||
| 6 | `benefit_highlight` | **Item 5 / the payoff item.** Land the final, highest-value point ("benefit" = the why-it-matters of the last item, the ranking winner, or the synthesizing insight). | 12-15% |
|
||||
| 7 | `cta` | **Wrap / takeaway.** Recap the full set, name #1, or give one action. ("cta" = the closing nudge or single sentence to remember — explainers rarely "sell.") | 8-12% |
|
||||
|
||||
Notes:
|
||||
|
||||
- **All body items use `feature_showcase`** because each is a _demonstration of one discrete point_ — the closest enum fit. Promote the final or strongest item to `benefit_highlight` when you want the why-it-matters to land harder than the others (a ranked "#1" or a synthesizing takeaway).
|
||||
- **`product_intro` is unused** in pure listicles (there is no product). The validator requires at least one `feature_showcase` _or_ `product_intro` scene — the item scenes satisfy this automatically.
|
||||
- `social_proof` may replace one item when the list is evidence-driven ("3 studies that…"), and `branding` is generally skipped.
|
||||
|
||||
## When to Use
|
||||
|
||||
- The content is naturally enumerable: tips, do's/don'ts, "top N", comparisons, signs/symptoms, myth-busting, steps you can shuffle without breaking meaning.
|
||||
- The source text already contains a count or an obvious set of parallel points.
|
||||
- You want high information density and forward momentum over a single emotional journey.
|
||||
- The audience wants to _collect_ takeaways quickly (skimmable, shareable explainers).
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- The points are sequential and order-dependent (each depends on the previous) → use **how-to-process**.
|
||||
- There is one core idea to unpack in depth, not many parallel ones → use **concept-explainer**.
|
||||
- The material is inherently a single human/narrative throughline → use **story-explainer**.
|
||||
- N would be 2 or 8+: two items isn't a list (it's a comparison — fold into concept-explainer); eight+ items overwhelm a short explainer — cut to the best 4-6 (up to ~6-7 only if you're filling the full ~3 min), or split the topic.
|
||||
- The items aren't genuinely parallel (forcing dissimilar ideas into identical templates feels mechanical).
|
||||
|
||||
## Hook Strategy Bias
|
||||
|
||||
Listicles live or die on the opening promise. From the hook taxonomy, the strongest fits:
|
||||
|
||||
- **Category announcement** — name the list as the thing: "The 5 logical fallacies that win arguments." The count _is_ the hook.
|
||||
- **Shocking statistic** — open on the number that justifies the list: "73% of these are made in the first 10 seconds. Here are the four." Statistic → enumeration is a tight pairing.
|
||||
- **Rhetorical question** — pose the gap the list closes: "Why do some emails always get replies? Five reasons."
|
||||
- **Imagine / future-pacing** — for aspirational lists: "Imagine never forgetting a name again — here are three tricks."
|
||||
|
||||
Avoid pain-validation / visceral-metaphor openers (those belong to anxiety-led structures); the listicle hook is brisk and promissory, not heavy. **Always state or strongly imply the count in the hook** — a listicle whose number arrives late forfeits its central mechanic.
|
||||
|
||||
## Pacing & Transition Guidance
|
||||
|
||||
The default seam between items is **Tier-B**: each item is its own beat, a clean parallel restart, so most item→item transitions are `cut` or `slide` (`continuity: break`). Reach for `slide` to express "next point" directional momentum (the counter advancing left-to-right), `cut` for high-energy snap between equal siblings, `dissolve` when the visual register shifts (typography item → data-viz item), and `zoom` to push into a number or a single focal stat. Scene 1 is always `break`.
|
||||
|
||||
**Where morph pairs naturally occur:** the **counter / number motif** is the listicle's built-in shared element — a running "1 of 5 → 2 of 5" badge, a progress dot row, or a recurring numeral frame that physically advances. When two adjacent items genuinely hand off that motif (the "3" digit morphs into the "4", or the progress bar fills from one segment to the next as the visual protagonist of _both_ scenes), use `intent: morph` (`continuity: continue`) with `sharedMotif: "the item counter"` (or `"the progress bar"`) as soft hints. This is the polished move — use it sparingly:
|
||||
|
||||
- **Continue runs ≤3 scenes:** a listicle is mostly parallel items, so most seams are `break` (cut/slide). Use `continue` only where the counter/motif genuinely hands off across 2-3 adjacent items; a run is ≤3 scenes, then a `break`. `morph`/`sharedMotif` are soft hints for that one worker.
|
||||
- Don't morph _every_ seam — the listicle's signature is the parallel **restart**, and too many continuous morphs blur the discrete-item feel that makes it a list. One or two counter-morph pairs across the body is the sweet spot; keep the rest Tier-B.
|
||||
- The hook→item-1 seam is usually Tier-B (`zoom` into the first item, or `cut`), since item 1 establishes the template the rest restart from.
|
||||
|
||||
## Emotional-Beat Trajectory
|
||||
|
||||
Lean **curiosity → clarity → confidence**, accumulating per item rather than swinging through a valley:
|
||||
|
||||
- **Hook:** `curiosity` (or `intrigue` when the count is surprising).
|
||||
- **Items 1…N:** alternate `clarity` and `confidence`; sprinkle `intrigue` on a counter-intuitive item and `playfulness`/`ease` on a light one to keep the parallel cascade from flattening. Myth-busting variants may open each item on `skepticism` and resolve it to `clarity`.
|
||||
- **Payoff item:** `confidence` or `reassurance` — the set feels complete.
|
||||
- **Wrap/CTA:** `motivation` or `inevitability` — "now you know all five."
|
||||
|
||||
Avoid a monotone arc: identical beats on every item read as a list of facts, not a journey. Vary the _texture_ of clarity (surprise on one, ease on another) even though the macro-feeling stays positive.
|
||||
|
||||
## Worked Example
|
||||
|
||||
**Topic:** "5 ways to fall asleep faster" (sleep-hygiene explainer, faceless, typography + simple data-viz). 7 scenes, ~60s.
|
||||
|
||||
1. **Promise the Five** — `hook` — _"You'll waste 9 days a year just lying awake. Five fixes — starting tonight."_ — Transition: `break` / `cut` (scene 1 placeholder; counter badge "1 of 5" assembles on screen).
|
||||
2. **Cool the Room** — `feature_showcase` — _"Drop the thermostat to 65. Your core temperature has to fall before sleep even begins."_ — Transition: `break` / `zoom` (push from the badge into item 1's thermometer graphic).
|
||||
3. **Kill the Blue Light** — `feature_showcase` — _"Screens off an hour before bed — blue light tells your brain it's still noon."_ — Transition: `break` / `slide` LEFT (next-point momentum; counter ticks 1→2).
|
||||
4. **The 4-7-8 Breath** — `feature_showcase` — _"Inhale four, hold seven, exhale eight. Repeat four times. It slows your heart on command."_ — Transition: `continue` / `morph`, `sharedMotif: "the item counter"` (the "2" numeral morphs into "3" as the breathing-timer ring draws — counter is the protagonist of both scenes).
|
||||
5. **No Late Caffeine** — `feature_showcase` — _"Caffeine has a six-hour half-life. That 4pm coffee is still half-awake at 10."_ — Transition: `break` / `dissolve` (register shift to a decay-curve data-viz).
|
||||
6. **Same Time, Every Day** — `benefit_highlight` — _"The single biggest lever: a fixed wake time. Anchor that, and the other four compound."_ — Transition: `break` / `slide` LEFT (final item; framed as the ranked #1 that ties the set together).
|
||||
7. **Tonight's List** — `cta` — _"Cool, dark, breathe, cut the caffeine, fix your wake time. Pick one — start tonight."_ — Transition: `break` / `cut` (all five counter dots fill; recap of the full set as the takeaway).
|
||||
+103
@@ -0,0 +1,103 @@
|
||||
# Story Explainer
|
||||
|
||||
## Core Logic
|
||||
|
||||
Explain a concept by living through it. Open on a relatable situation with a named character or scenario → let a real problem surface inside that situation → introduce the insight/concept as the turning point → show how it plays out → land the lesson. The viewer learns the idea because they watched it _matter_ to someone, not because it was defined for them. The concept earns its entrance only after the scenario has made the viewer want an answer.
|
||||
|
||||
This is the only FE structure with a genuine **valley** — the scenario gets worse before the insight arrives. Use that valley deliberately; it is what makes the resolution legible. But the valley is _narrative tension_, not sales-anxiety: the viewer is curious about how it resolves, not afraid of a cost they'll bear.
|
||||
|
||||
## Emotional / Cognitive Arc Pattern
|
||||
|
||||
```
|
||||
Recognition ──▶ Tension ──▶ Insight ──▶ Clarity ──▶ Confidence
|
||||
(scenario) (problem) (concept) (it plays out) (lesson)
|
||||
```
|
||||
|
||||
A **shallow V**: dip into the problem-in-context, pivot on the concept, climb through resolution to the takeaway. Unlike a sales V-curve (anxiety → relief), the emotional spine is **curiosity → intrigue → clarity → conviction** — the negative beat is _tension/stuck_, never dread. The character (or recurring object) is the throughline; the audience's understanding rises as the character's situation resolves.
|
||||
|
||||
## Typical Scene Sequence
|
||||
|
||||
5–8 scene slots. `type` is from the fixed enum `hook | pain_point | product_intro | feature_showcase | benefit_highlight | social_proof | branding | cta`; for an explainer each is repurposed as noted.
|
||||
|
||||
| Order | Type (enum) | Means here (explainer) | Approx % | Job |
|
||||
| ----- | ------------------- | ----------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------- |
|
||||
| 1 | `hook` | Scene-setting — drop the viewer into a concrete, relatable situation | 8–12% | Introduce the character/scenario; make the viewer recognize themselves |
|
||||
| 2 | `pain_point` | The problem-in-context — the friction/stakes inside the scenario | 12–18% | Raise tension: what's going wrong, what's at stake, why the obvious move fails |
|
||||
| 3 | `product_intro` | The turning point — the **insight / concept / mechanism** enters as the hero | 12–18% | Name the idea. This is the pivot; the concept arrives as the answer to the tension |
|
||||
| 4 | `feature_showcase` | It plays out — the concept applied step-by-step inside the same scenario | 15–22% | Show the idea working on the character's actual problem (not abstract definition) |
|
||||
| 5 | `benefit_highlight` | Why it works — the principle behind the resolution; what changed and why it matters | 12–18% | Generalize from this one case to the underlying truth |
|
||||
| 6 | `social_proof` | _(optional)_ Corroboration — a second instance, a real number, a "this is common" | 8–12% | Show the lesson isn't a one-off; widen from the character to the pattern |
|
||||
| 7 | `branding` / `cta` | The lesson — the one-sentence takeaway, or a "next time you see X, remember Y" | 10–15% | Crystallize the principle; optionally invite the viewer to apply it |
|
||||
|
||||
The "insight enters" pivot (`product_intro`) is the structural heartbeat — it lands at **roughly 30–45%**. Don't reveal the concept in scene 1: a story explainer that defines the idea up front collapses into a `concept-explainer` and throws away the tension that makes the lesson stick.
|
||||
|
||||
> `product_intro` here is **conceptual**, not a product. It names the idea/mechanism that resolves the scenario (e.g. "compound interest", "the bystander effect", "rubber-ducking"). `feature_showcase` = the concept _doing the work_; `benefit_highlight` = the generalizable principle. FE projects are text-only by default, so `assetCandidates` is `[]` on every scene unless a real file lives under `public/`.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Case studies and "why X matters" topics — the stakes are easiest to feel through a single concrete instance.
|
||||
- Behavior / psychology / finance / history — domains where an abstract principle is best taught through one person's situation.
|
||||
- Any topic where the input already contains a protagonist, an example, or a "here's what happened" anecdote — let the source's narrative drive the structure.
|
||||
- When the lesson is counterintuitive: a story disarms skepticism by letting the viewer reach the insight alongside the character.
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- A flat reference topic with no inherent scenario ("what is a hash map") → use `concept-explainer`.
|
||||
- A sequence of independent items with no shared protagonist ("7 productivity apps") → use `listicle`.
|
||||
- A literal procedure the viewer will follow themselves ("how to file taxes") → use `how-to-process`.
|
||||
- Very short runtimes where you can't afford to spend 30% building a scenario before the payoff — the valley needs room to breathe.
|
||||
|
||||
## Hook Strategy Bias
|
||||
|
||||
From the hook taxonomy (`../../guide.md`), Story Explainer leans on hooks that _drop you into a moment_:
|
||||
|
||||
- **Relatable scenario / character hail** — the native opener. "It's 11pm and Maya is still staring at the same paragraph." Concrete time, place, and a name beat any abstract claim.
|
||||
- **Rhetorical question** — frame the scenario as a puzzle the viewer wants solved. "Why did the smartest person in the room make the worst call?"
|
||||
- **Imagine / future-pacing** — when the scenario is hypothetical-but-vivid. "Imagine you're handed $1,000 and told not to touch it for 40 years."
|
||||
- **Shocking statistic** — only as a _doorway into_ the scenario, not the scenario itself. "90% of these end in regret — here's one of them." Then immediately cut to the character.
|
||||
|
||||
Avoid **category announcement** and pure **visual-spectacle** openers — naming the concept or leading with abstraction in scene 1 dissolves the tension this structure depends on.
|
||||
|
||||
## Pacing & Transition Guidance
|
||||
|
||||
Transition vocabulary and the continue-run model (continue = same worker, up to 3 scenes; `morph`/`sharedMotif` are soft hints) live in `../../guide.md` — follow them exactly. Story-Explainer specifics:
|
||||
|
||||
- **Scene 1 is always `break`** (`intent: cut`, placeholder — no real opening transition).
|
||||
- **The recurring motif is a built-in morph throughline.** A character avatar, an object the story orbits (a jar of coins, a locked door, a single chart line), or the protagonist's "state" is naturally co-present across adjacent scenes — that is exactly what a `continue` run is for: group those adjacent scenes under one worker so it authors the throughline. `morph`/`sharedMotif` are soft hints naming the recurring object.
|
||||
- **Best morph seams:**
|
||||
- `pain_point → product_intro` — the pivot. The motif that represented the _problem_ transforms into the thing that represents the _insight_ (the cluttered desk's single sticky note morphs into the lit idea). This is the most powerful seam in the structure; spend a morph pair here.
|
||||
- `feature_showcase → benefit_highlight` — the same applied object (the jar now full) morphs from the concrete case into the principle.
|
||||
- **Use Tier-B (`cut` / `slide` / `dissolve` / `zoom`) where the register shifts:**
|
||||
- `hook → pain_point` — usually a `slide` or `dissolve`: same scenario, tension rising; no shared element transforms, so don't force a morph.
|
||||
- Entering `social_proof` — a `cut` signals "stepping outside the story to the wider world."
|
||||
- Into the final lesson — a `zoom` (pull back from the case to the principle) or a `dissolve` reads as "the camera rises above the story."
|
||||
- **Continue runs ≤3 scenes:** group 2-3 adjacent scenes that share a recurring object/character (the jar, the curve, the protagonist) as one `continue` run owned by a single worker; separate runs with a `break`. Shape e.g. `break(1) → slide(2) → continue(3) → break(4) → continue(5) → break(6) → break(7)`. scene 1 is always `break`.
|
||||
|
||||
## Emotional-Beat Trajectory
|
||||
|
||||
Use the emotional-beat vocabulary (`../../guide.md`). Story Explainer is the one FE structure that earns a real **valley → resolution**, but keep it on the curiosity register, not the anxiety register:
|
||||
|
||||
```
|
||||
curiosity → tension/stuck → intrigue → clarity → confidence → conviction
|
||||
(scene) (problem) (pivot) (plays out) (principle) (lesson)
|
||||
```
|
||||
|
||||
- Scene 1 `hook`: **curiosity** (or **recognition** — "that's me").
|
||||
- `pain_point`: **tension** / **stuck** / **frustration** — the narrative valley. This is the only place a mildly negative beat belongs.
|
||||
- `product_intro` pivot: **intrigue** / **clarity** — the "oh" moment.
|
||||
- `feature_showcase` / `benefit_highlight`: **clarity** → **confidence** → (compound) **understanding and satisfaction**.
|
||||
- Final lesson: **conviction** / **resolve** — "I'll remember this," not "buy now."
|
||||
|
||||
Write compound beats where two feelings are live ("intrigue and relief" at the pivot, "clarity and satisfaction" at the resolution).
|
||||
|
||||
## Worked Example
|
||||
|
||||
**Topic:** Why you should start saving in your 20s (compound interest). Recurring motif: **a coin jar**.
|
||||
|
||||
1. **Two friends, one choice** — `hook` — "Sam and Alex both turned 25 this year. Sam starts putting $100 a month into a jar. Alex waits." · _Transition: `break` / `cut` (scene 1 placeholder)._
|
||||
2. **The 10-year head start** — `pain_point` — "By 35, Alex finally starts too — same $100 a month. Alex figures a decade is easy to make up." · _Transition: `break` / `slide` (tension rises inside the same scenario; no shared element morphs)._
|
||||
3. **Enter compounding** — `product_intro` — "But money doesn't grow in a line. It grows on what it already grew — that's compound interest." · _Transition: `continue` / `morph`, sharedMotif: "the coin jar" (Sam's jar of coins morphs into a curve climbing off its own height — the problem-object becomes the insight)._
|
||||
4. **The jars at 65** — `feature_showcase` — "At 65, Sam's jar holds far more than Alex's — even though Alex paid in nearly as much." · _Transition: `break` / `dissolve` (time-jump to the outcome; register shift)._
|
||||
5. **Time did the work, not the deposits** — `benefit_highlight` — "Sam's edge wasn't more money. It was more time for the growth to feed itself." · _Transition: `continue` / `morph`, sharedMotif: "the growth curve" (the two jars' curves morph into a single labeled principle)._
|
||||
6. **It's the same for everyone** — `social_proof` — "Run the math on any amount: the early start almost always wins." · _Transition: `break` / `cut` (step outside the two-friend story to the general case)._
|
||||
7. **The lesson** — `branding` — "The best time to start was a decade ago. The second best is today." · _Transition: `break` / `zoom` (pull back from the example to the takeaway)._
|
||||
Reference in New Issue
Block a user