Viva Video
Produce a deterministic, code-rendered product launch or concept-explainer film from a source document — the document is read and understood first, then every frame is drawn by code (no video-generation model), with exact data and real code on screen, Chinese narration (through a speech provider the user supplies, or whatever the agent can do on its own) whose product-name pronunciation is measured rather than guessed, brand-derived gradient typography, and machine-checked layout density, reading order, motion continuity, diagrams and colour. Every frame carries one idea, the reveal order follows the measured F-shaped reading path, and abstract mechanisms are explained as step-by-step derivations that leave a trace. Use for 产品宣发片, 版本发布视频, 概念/机制/原理讲解视频, developer-tool release films, or whenever a video must carry accurate numbers, real code and correct product names. Do not use for cinematic brand films built from generated footage, video trimming, or talking-head editing.
Difference from cinematic-product-video: That skill uses SeedDance to generate cinematic footage, oriented towards branding. This one uses no generated footage at all, everything is code-rendered, oriented towards information. The two skills are independent; do not mix them.
Deliverable is the final film, not a storyboard. When only asked to change specs or prompts, stop at file revision and validation; do not initiate paid generation or full rendering.
First Thing: Read and Understand the Document. Fail This, Everything Else is Wrong
The primary reason a film is unclear is not the rendering; it's that the document wasn't fully understood before layout began. The
comprehensionsection infilm-rules.yamlis blocking;compose_spec.pywill reject it.
Produce Three Artifacts
| File | Content | Purpose |
|---|---|---|
UNDERSTANDING.md | What it is, whose problem it solves, mechanism causality chain, key numbers and their measurement conditions, three questions the audience should be able to answer after watching, what the document does NOT claim, mark unknown points as unknown | Prevents the film from being wrong or overreaching |
CLAIMS.md | One claim per line: claim / source in the document / mechanism / benefit / constraints / visual evidence / risk wording | Every sentence in the film must be traceable back to this table |
CONCEPT_MAP.md | Document section → claim → mechanism & benefit → visual subject & action → forbidden misinterpretations → evidence required for judgment | Translate "what to say" into "what to draw" |
Simultaneously fill the conclusions into content.yaml under content.understanding, compose_spec.py will validate it.
Close the Document and Answer These Five Questions
If you can't answer them, go back and re-read. Do not proceed with questions in mind.
- What problem does this thing solve, how did users do it before, what was the pain point?
- Explain the mechanism as a causal chain with no skipped steps.
- Which number best proves the conclusion, under what conditions was it measured, would it still hold under different conditions?
- What is the most likely misconception the audience will have, and how should the visuals prevent it?
- Which sentences in the document are marketing speak and cannot be presented as facts?
Reorganize After Understanding, Don't Just Copy the Table of Contents
Order by: Problem → Cost of Old Approach → New Mechanism → Evidence → Applicability Boundary → Next Steps. Each scene covers only one conclusion; state the conclusion first, then the mechanism, then the evidence. When a term appears for the first time, explain it in one sentence.
Forbidden: Replacing specific numbers from the document with phrases like "dramatically improved", "comprehensively upgraded", "significantly optimized"; making up numbers not in the document; presenting a roadmap as delivered; rewriting example code into a prettier but non-functional version; guessing the meaning of a chapter based on its title when you haven't understood it.
compose_spec.py will scan for these clichés and report errors.
Checkpoint
Before writing content.yaml, present UNDERSTANDING.md, the chapter outline, one conclusion per chapter, and the intended visual prototype for each chapter to the user for review. Do not proceed to the visual layer if the factual layer has not been approved. Reworking at this step is cheapest; reworking a finished film is most expensive.
Methodology Source: The transition decision table, focus triad, energy skeleton, three-meter test, and Chinese typography sections are borrowed from huashu-design (Uncle Flower). What was borrowed, what was reviewed but not borrowed, and why, is recorded in
references/borrowed-from-huashu-design.md.
Three-Layer Structure, Only the Middle Layer Changes Each Time
| Layer | File | When Making a Film |
|---|---|---|
| Rules Layer | references/film-rules.yaml | Do not modify. What must be done: understand the document, one thing per frame, narration corresponds one-to-one with information units, highlight what is being narrated, zero raw cuts, minimum density, rendering invariants R01–R30, acceptance gates Q01–Q38, measurement methods and thresholds |
| Theme Pack | themes/<name>/theme.yaml | Only modify when changing look and feel. How it looks: color palette derivation, font sizes, coordinates, card and navigation styling, easing curves, transition choices, focus ink amount, BPM and instrumentation for music |
| Product Content | Your content.yaml | Only write this. Understanding, facts, chapters, claims, metrics, brand assets, pronunciation table, each chapter's delivery method and information units |
| Synthesis Product | video-spec.resolved.yaml | Do not edit by hand, generated by scripts |
The boundary between the rules layer and the theme pack is just one: Changing the look and feel should not be able to change "the narration must align with the visuals."
The criteria stay in the rules layer; the look and feel is delegated to the theme pack; theme_contract writes both as machine-checkable checklists.
If the pack is missing keys, goes out of bounds, or tries to modify criteria, validate_spec.py will reject it on the spot.
The default pack is daylight (near-white background + white cards + brand color triple-stop gradient), the default look and feel of the skill.
How to write a new pack is in themes/README.md.
SKILL=~/.agents/skills/viva-video
cp $SKILL/templates/content.example.yaml ./content.yaml
# First read and understand the document, fill in understanding; then fill in remaining TODOs
python3 $SKILL/scripts/compose_spec.py ./content.yaml -o ./video-spec.resolved.yaml # Add --theme <pack-name> to change look and feel
python3 $SKILL/scripts/validate_spec.py ./video-spec.resolved.yaml --self-test
examples/content.viva-video.yaml is a filled example (viva-video 1.0's own release film, 7 chapters).
Voice and Video Models: Use What the User Provides, If None, Only Use Your Own Capabilities
The skill does not come with any voice or video model addresses or keys.
- If the user specifies how to call their own TTS, ASR, or video model (commands, API documentation, existing scripts all count): Package it into a command written in
providers.json, thentts.mjs,pron_calibrate.mjs,asr_check.mjs --backend commandwill all use it. Keys should only remain in environment variables or the user's own configuration, not written into project files, logs, or messages. - If the user does not specify: Only use the capabilities the agent already has. If there are existing voice tools in the environment, use them; if not, produce a film with subtitles only and no voice-over, and mark pronunciation checks as
not_tested. Do not guess or search for any service's address or key.
Format, lookup order, and fallback tables are in references/providers.md.
First Three Things When Changing Products, Order Cannot Be Reversed
1. Determine Pronunciation
Chinese TTS reads Rspack as a single English word, with the middle 's' being swallowed — tests showed it transcribes back as Spac.
The fix is to make the TTS read it letter by letter, not to transcribe the name into Chinese characters. Format: RS + space + rest of the English word.
| Display | Input to TTS | Output |
|---|---|---|
| Rspack | RS pack | R-S-pack |
| Rsbuild | RS build | R-S-build |
| Rstest | RS test | R-S-test |
| Rsdoctor | RS doctor | R-S-doctor |
Tested on 2026-11-04 (a specific Chinese female voice, speed 1.24, transcribed back with local faster-whisper after synthesis):
| Input | Transcription Back | Verdict |
|---|---|---|
Rspack | Spac | Fail, 's' lost |
RS pack | RSPAC | Adopted, total length for four names 7.78s |
R S pack | RS Pack | Usable, slightly longer |
R 斯 pack | OSPAC | Fail, the Chinese character "斯" distorts the preceding 'R' |
R-S-pack | RS Pack | Fail, hyphens introduce pauses, sentence 1.5s longer |
而斯派克 | 而斯派克 | Fail, fully sinicized, the English word disappears |
Units must be expanded: Test showed 915.8 ms was read as "915.8 meters." Write it as "915.8 毫秒" (milliseconds).
pronounce.py does this automatically (only replaces units following numbers).
Letter abbreviations (SSR / BFF / SWC / CLI), decimals, percentages, version numbers like 3.0 — all tested to be pronounced correctly, do not over-adapt them.
python3 scripts/pronounce.py --self-test # 8 tests
python3 scripts/pronounce.py "分析耗时从 915.8 ms 降到 51.6 ms。"
node scripts/pron_calibrate.mjs --terms terms.json # Test and choose format when changing product or voice
node scripts/asr_check.mjs --spec video-spec.resolved.yaml --voice voice/
When changing voices, speeds, or introducing new proper nouns, always run pron_calibrate.mjs first; don't copy the conclusions above. Different voices read letters differently.
Do not mark pronunciation as passed without a regression test; passing ASR does not mean it sounds natural; mark untested as not_tested.
2. Determine Theme Color and Gradient
python3 scripts/theme_resolve.py --svg brand/logo.svg --out qa/theme-resolution.json
python3 scripts/theme_resolve.py --hex '#F93920'
Follow design.theme.resolution_order: user specified → brand SVG → official website CSS variables → document decorative color → fallback.
Convert the obtained raw color to OKLCH, clamp lightness to 0.45–0.62 and chroma to 0.12–0.22, preserving the original hue. When it exceeds sRGB, map by lowering chroma, not by clipping channels individually — clipping changes the hue, negating the normalization.
The gradient triple-stop colors move in the same direction along the hue circle, towards the magenta anchor (H=350°), with a span clamped to 55°–86°, secondary at 40%. Bidirectional movement causes the gradient to reverse direction midway, looking like a bug. Feeding the reference film's own primary color reproduces its #376CFF → #8E33F2 → E3429B.
Two ramps: Use the fully saturated one for titles, use a lighter grade for large numbers ≥96px (L +0.13, C −0.06) — large area high saturation would overpower the title.
Contrast grading: Body text ink level 4.5, brand-colored large text 3.0, primary values ≥96px 2.3 (reference film measured 2.37–2.86; tighter would dull the entire gradient).
Red, green, and orange are semantic colors and do not participate in the derivation. Forbidden to use error red as a normal container border or decoration.
3. Choose a Visual Archetype and Explanation Mode for Each Chapter
Visual Archetype: Choose from the eight in scene_language.archetypes: dependency graph, code with relationships, request-response, discover-then-request, before-after metrics, capability matrix, state machine, layered architecture. Consecutive chapters must not repeat.
Explanation Mode (explanation_mode): Choose from explanation_modes.vocabulary, determines whether and how this page animates. First determine the type of information, then consult the selection table (see the "How to Explain Abstract Information" section below).
Information Units: Write 3–5 short labels per chapter. This serves as both the minimum density baseline and the upper limit of "too much content on one frame."
All three will be validated by compose_spec.py.
Layout: Is it Full or Sparse?
Titles are Always a Two-Part Structure: "Lead, Conclusion"
The lead uses plain ink, the conclusion part uses a full gradient. The boundary can only fall on punctuation, and the conclusion part must occupy 35%–70%.
简洁、线性，｜每一步单独读也成立
声明一次， ｜运行时检查与说明书自动就绪
同机实测， ｜跑得更多、更快、更省
In content.yaml, write it as headline_lead + headline_emphasis. compose_spec.py validates the ratio and boundary.
Note that this is different from title (chapter name): chapter names appear on chapter pages and navigation; headlines are the main titles on content pages.
Gradient budget: At most 1 title + 1 primary value + 2 keywords per page. Exceeding this means it's no longer a signal for emphasis. Gradients are forbidden on text <32px (tested to show band-like discontinuities), must not be combined with strokes, shadows, glow effects, or animation.
Pre-allocate Slots First, Fill in Key Content Later
In the first frame of a scene, draw all slots — container borders, slot headers (chip + title + separator), content skeletons. After that, only change content and opacity; the bounding boxes remain fixed. Key content (values, code, labels) waits until the narration mentions it.
This single rule solves three problems simultaneously: The layout looks filled from the first frame, so the audience never sees an empty page "waiting for content to grow in"; no reflow jitter occurs during population; the first thing seen is the structure of the page, so the viewer knows how many things will be discussed.
The skeleton must include a title or placeholder structure, not a pure white rounded rectangle.
Slot headers must not wait together with the content. A bug tested on 2026-11-05: feature and stage slot types had their titles attached to the content's reveal event, resulting in the two cards at the bottom of the page being pure white rectangles at the start. The header belongs to the container, the content belongs to the beat.
This rule has a pixel-level judgment (R18's measured half): At the scene's opening frame (the moment the transition finishes), the maximum blank rectangle in the content area must be ≤ 0.26. Testing only the hold frame won't reveal this — at the hold frame, the page is obviously full; it cannot see the half-empty state during the first eight seconds.
Don't dim empty slots. See the "Focus" section below: Dimming empty slots to the out-of-focus level makes the page immediately read as "not yet grown in," which is exactly the problem pre-allocated slots are supposed to solve. Tests showed that after raising the opacity of empty slots from 0.38 to 0.80, the maximum blank rectangle in the opening frame across seven scenes dropped from 0.29–0.62 to 0.058–0.199.
Content Without Borders Must Be Contained
User feedback: "Things feel very scattered when there are no cards." The rules have been tightened to:
- Every information unit in the content area must belong to a container or a labeled group.
- Only three types of content are allowed to be borderless: a list of key points immediately below a container, a single concluding sentence at the bottom of a page, and the kicker and title at the top.
- Borderless key points must share the left edge and width with an adjacent container, be at most 7 columns wide, at most 4 items, and be formatted as "circle number + bold short title + colon + body text" all starting on the same line.
- All borderless text blocks on the same page can only have a single left boundary.
- If borderless content exceeds 40% of the content area, it must be placed into a container.
Forbidden: Three or four paragraphs of text each centered with whitespace between them; using empty lines to "fill up" space; more than one type of left boundary on a page.
Minimum Density (Content Area [120, 280, 1680, 610])
| Metric | Lower Limit | Measurement Method |
|---|---|---|
| Container occupancy | ≥ 0.55 | Scene object bounding boxes |
| Vertical span | ≥ 0.72 | Scene object bounding boxes |
| Horizontal span | ≥ 0.86 | Scene object bounding boxes |
| Maximum blank rectangle | ≤ 0.14 | Scene object bounding boxes |
| Maximum blank band | ≤ 150 design px | Scene object bounding boxes |
| Independent information units | ≥ 3 | Scene object list |
| Maximum blank rectangle on stable frames | ≤ 0.20 | Stable frame edge map |
The last one is pixel-level. Chapter pages, covers, and endings are exempt. Do not use "non-background pixel ratio": This visual system uses white cards on a near-white background, so card fill would become the modal color, inverting the metric (tested: reference film 0.144, the version judged aesthetically poor 0.419, direction completely wrong). Edge maps are unaffected.
When content is insufficient, supplement according to density.escalation. Step 0 is to first check if slots weren't pre-allocated or content wasn't placed into containers — most "emptiness" is this, not a lack of content.
Forbidden to leave whitespace directly. Forbidden to enlarge font size to fill space. Forbidden to use particles, glows, or geometric blocks to masquerade as information units.
Window Shells: Judge by Information Density, Not Preference
Use when: Content naturally belongs to a specific interface (file, configuration, terminal, editor, dashboard, report); there are ≤3 information units, making them look sparse and needing a boundary to contain them; or to express the subordinate relationship of "filename + content."
Do not use when: A more accurate representation exists and can fill the content area; the previous two shots have already consecutively used window shells; the content is an abstract mechanism rather than a concrete interface.
When used, fill it: content fill rate must be ≥ 78%. Window titles must use real filenames, not "Example" or "Demo." Window scenes must be ≤ 50% of the entire film, with no more than three consecutive shots of the same composition.
Relationship Diagrams and Flowcharts
At least 4 nodes and 3 edges. Nodes must have a title plus a one-line description. Every directed edge must have an action label and an arrow, with both ends anchored to the boundary points of the real object IDs; endpoints not landing on an object are defects. Must be paired with an explanation panel occupying 30%–42% of the content area width: choose from pseudo-code, config snippets, state tables, message samples, metric bars, or step sequences. Pseudo-code should be 5–12 lines, with each line corresponding to a node or edge in the diagram, and synchronously highlighted during rendering.
Metrics Pages
In addition to the primary value, at least 2 supporting items: before/after comparison charts, composition breakdown, test condition block, a second metric of the same mechanism, the real configuration that produced the metric, or a baseline definition. Charts must share a baseline, mark scales and values. Different units (qps vs ms) must be on separate charts or axes. Order: First show the original value and test conditions → transition to the new value → settle on the improvement margin → hold steady. Numbers must be monospaced, units fixed, and emphasize only once.
Chinese Typography: Western Rules Can't Be Copied Directly
| Rule | Why | |
|---|---|---|
| Line height | Display 1.15, Title 1.35, Body 1.65 | Chinese characters are full-grid squares with no inherent gaps like the ascenders/descenders of Western lowercase; insufficient line spacing makes them blur together. Chinese lines are generally about 0.2 higher than Western text. |
| Letter spacing | Display ( >60px) −0.02em, Title 0, Body 0 | Chinese character spacing is naturally even. Adding positive letter spacing to titles makes them loose; negative spacing on display text causes strokes to collide. Only all-caps Western small labels need 0.08–0.15em. |
| Line length | 22–38 characters per line, optimal 28–32 | Chinese has high density; the same width carries more information than Western text. Too long a line causes the reader to lose their place when wrapping. |
| Font stack | Western font first, Chinese font last | Character-by-character matching: Western fonts do not contain CJK code points; Chinese characters naturally fall through to the Chinese font. Doing it in reverse causes all Western characters to be rendered by the ugly Western glyphs embedded in Chinese fonts. |
| Emphasis | Change font weight or add background color | Chinese has no italic; synthesized italics by browsers/renderers distort Chinese characters. Similarly, synthetic bolding is forbidden. |
| Quotes | Use corner brackets 「」『』 | Curly quotes in Chinese fonts are full-width placeholders but Western shapes, appearing visually floating. |
| Numbers | Use Western font with tabular-nums | Otherwise, '1' and '8' are not the same width, causing data columns to jitter left and right. |
Monospaced fonts must be verified for CJK glyphs. JetBrains Mono does not contain CJK glyphs, so Chinese comments in code windows become tofu blocks.
The mono font family must explicitly include a Chinese fallback.
Three-Meter Test
Pause at any frame; the largest word on the screen must be readable from three meters away; shrink a keyframe to mobile screen size and it must still be legible. The audience pays less attention to each frame in a video than in a static image, font sizes can only be larger, never smaller. This rule forms an upper and lower bound with the minimum density rule: minimum density prevents emptiness, the three-meter test prevents "shrinking font size to fit everything in."
One Frame, One Thing Only
User feedback: Content, effects, and narration must all convey information clearly; do not be vague; don't put too much content in one frame. Every rule in this section can be judged by
motion_audit.py; it's not an aesthetic suggestion.
Information Budget: Upper and Lower Limits
| Value | Description | |
|---|---|---|
| Minimum information units | 3 | Below this, the page is empty |
| Maximum information units | 5 | Above this, the 2-second freeze-frame test will fail |
| Total text in content area | ≤ 120 count units | Count Chinese characters by character, English by word |
| New information entering per beat | 1 location | A group of staggered elements counts as one location |
Count by the outermost container or labeled group; sub-items within a group are not counted separately. In the reference film at 01:32, by this metric, the page has 3 units (configuration code window + cloud device card group + process bar); even though the card group has 5 cards, it still counts as 1 unit.
If it exceeds the limit, do not shrink the font size to fit. Try in order: split into two scenes → merge similar items into a titled group → move details into the explanation panel.
Reading Path is F-Shaped and Measurable
Eye-tracking studies show viewing focus in the content area is concentrated in three regions: a top horizontal bar (kicker and title), a second horizontal bar (first row of main content), and a left vertical column (the shared left boundary). Applied to this film:
- Starting point: The first revealed information unit of a scene must have its center of gravity in the upper left of the content area (normalized x ≤ 0.50, y ≤ 0.45).
- Order: The vertical center of gravity of the reveal sequence must be monotonically non-decreasing, with at most one upward jump allowed.
- Vertical bar: Borderless text blocks share a single left boundary (R14), containers align to the left column grid (R13).
- Preceding information: The first two words of titles, slot headers, and point titles must carry information. Titles starting with "About," "Our," "Better," "How to" will be flagged directly by
compose_spec.py.
Test results (within content_box, at 12fps, center of gravity change 1.5 seconds after each cut):
| Start x | Start y | Percentage of cuts spreading downward | |
|---|---|---|---|
| Reference film | 0.393 ± 0.121 | 0.336 ± 0.126 | 67% |
| Previous version judged aesthetically poor | 0.660 ± 0.175 | 0.498 ± 0.152 | 48% |
The reference film starts from the upper left and spreads downward; the poor version started from the center-right and spread outward — this is a direct cause of "looking scattered", irrespective of density.
The Visual and Narration Must Be About the Same Thing
Each information unit must specify which narration sentence it corresponds to, with its reveal time falling within [sentence start −0.4, sentence end +0.8] seconds. If you can't write the corresponding sentence, it means this unit isn't talked about in the narration and should be deleted or the narration should be supplemented.
Text on the screen is for conclusion phrases, proper nouns, values, and labels — not a verbatim copy of the narration — listening and reading the same thing simultaneously competes for attention. Subtitles are a separate track and are not counted in the text budget.
Narration Also: One Thing Per Sentence
- One sentence, one fact. Write two sentences for two facts; don't connect them with "also" or "and." Single sentence ≤ 32 count units.
- The first sentence of each scene is the conclusion; the mechanism and evidence come after.
- Don't use "it" or "this" consecutively; if separated by one sentence, repeat the name.
- When a term first appears, explain it within that sentence; don't leave it for the next sentence.
- When stating a number, the same or immediately following sentence must include its measurement conditions.
- Forbidden: Keyword-list reading ("faster, stronger, more stable"), marketing parallelism, three proper nouns in one sentence, reading aloud content that is already clearly written on the screen.
Copy every sentence of the narration into CLAIMS.md for mapping. Any sentence that cannot be mapped should either be deleted or supplemented with a sourced conclusion.
2-Second Freeze-Frame Test
Take a hold frame of a scene, cover the narration and subtitles, ask someone unfamiliar with the product to state the page's conclusion and that key number. If they can't, the page isn't clear. Record passed / failed / not_tested per scene; if not done, mark not_tested.
How to Allocate Time: First Allocate Hold Budget, Then Arrange Motion Effects
In a multi-shot film, duration is not evenly distributed. The four-part skeleton has fixed proportions:
| Segment | Proportion | Energy | Content | Hard Metric |
|---|---|---|---|---|
| Opening | 8–12% | Low | Brand reveal + one sentence stating what the whole film is about | Wordmark must hold ≥1 second after settling; frame 0 is the complete cover |
| Credibility | 10–16% | Low-to-mid, slowest of the film | First chapter, highest quality segment | — |
| Climb | 52–64% | Alternating mid-high and low | One capability per shot | Insert a chapter page every 1–2 content shots to lower energy |
| Closing | 10–16% | Peak of the film | Recap + key number + call to action | No fade-out; hold until the last frame after reading |
Order: ① List capabilities to count the number of shots → ② First, allocate the inviolable still time (wordmark hold, reading pause, chapter page full hold 1.1s, ending hold 2s) → ③ Remaining time is for motion effects → ④ Choose transitions for each seam, transition duration is deducted from the budgets of the two adjacent shots, not added to the film length.
No two consecutive high-energy shots. Chapter pages are "breathing title cards" meant to lower energy — they have low density, generous whitespace, and 2–6 characters. Don't make them into yet another information shot; that defeats their purpose.
Template Decoration Blacklist
These are not "ugly" per se, but "obviously a template." Delete them if they appear:
An all-caps English small label above every title · Dotted-connected word strings like "A · B · C" · Arrow decorations on the tail of buttons or labels · Coloring only a single word differently in a title · Numbering items 01/02/03 when they are not part of a sequence · Emoji icons unrelated to the mechanism · Left-strip colored rounded cards · Glowing particles, data streams, holographic HUD, neon · Dark background with neon glows pretending to be technology.
The criterion is "Did it grow out of the content?", not "Does it look like a template?" Numbering is legitimate when the items truly are a sequence (chapters, derivation steps); gradients are legitimate when derived from the brand color.
Seams: Zero Raw Cuts Through the Entire Film
User feedback (2026-11-05): "The transition between each chapter and the next must be very natural, not just directly displayed which looks very rigid." Universally acclaimed release films have zero raw cuts. When a "cut" effect is desired, use a designed cut.
Every scene seam must declare a transition, with its duration half deducted from each adjacent shot's budget — transitions are not added to the film's length; they are borrowed from the two shots. The window is [boundary − duration/2, boundary + duration/2], during which both scenes are on screen simultaneously.
| Adjacent Shots | Transition | Duration | Method |
|---|---|---|---|
| Cover → Chapter page | Cross dissolve | 0.62s | Cover fades out and gradually blurs, while the chapter number simultaneously resolves from blur |
| Content → Chapter page | Cross dissolve | 0.58s | While the previous page fades out, the number resolves from blur, both events in the same window |
| Chapter page → Content | Prism sweep | 0.92s | Number enlarges and blurs → rainbow sweeping light band (diagonal) → next page takes shape behind the light band, key content still hidden |
| Content → Ending | Cross dissolve | 0.62s | Same as above |
| Content → Content (same chapter, new shot) | Defocus relay | 0.50s | Only change blur, no horizontal displacement |
Prism sweep: A thin veil of surface_tint covers the entire screen (peak 0.62), a 1420-wide light band sweeps at a 17° angle, with stop colors main color 0.34 → secondary accent color 0.30 → accent 0.26. Flash to white, full-screen wipe, page turn, and rotation are prohibited.
Seams should attach to narration gaps (move on pause): Only advance, never delay, with a maximum of 0.8 seconds. The audience's cost of shifting their gaze during an auditory gap is lowest.
Judgment (R27): Sample the seam window at 12fps, calculate the full-screen per-frame change amount; The change in a single frame must be ≤ 0.55 of the total window change. A raw cut concentrates over 90% of the change into one frame. Measured across seven seams in this version: 0.155–0.35.
The cover must be Frame 0. Media players use t=0 as the poster frame; if Frame 0 is blank, the cover might as well not exist. Therefore, the cover does not rely on elements entering to create motion — all elements are present from the start, and motion comes from three things that don't change bounding boxes: a stationary concentric circle, two sweep lights, and the label for the direction the narration is talking about lights up. The judgment is that the edge coverage of the content area at Frame 0 ≥ 0.90 times that of the cover's hold frame. Even decorative elements must be in place at Frame 0 — tests showed that when the circle was made with a 0→1 fade-in, this ratio was only 0.673.
Focus: What is Narrated is Bright, but What Has Been Narrated Must Still Be Readable
User feedback (Round 2): "When talking about one piece of content, gray out the others to highlight the one being discussed." User feedback (Round 3): "It was grayed out immediately after finishing; I hadn't finished reading it." "Don't make it too blurry, just dim it, but I need to see the content." "If what was just talked about is related to what's coming next, don't dim it yet for a while."
Four States: Only Reduce Ink Amount, Not Clarity
| State | Ink Amount | Blur | Card | When |
|---|---|---|---|---|
| active | 1.0 | 0 | Shadowed, main color border | The narration is currently talking about it. It's recognized by "floating up," not by others being blurred out |
| read | 0.70 | 0 | No shadow, normal border | Has been talked about. Ink level visually approximates #5A6070, contrast is still 6:1, readable from three meters away |
| waiting | 0.88 | 0 | Normal | Not yet its turn. Only slightly lowered; the page must still read as full |
| settled | 1.0 | 0 | Normal | Narration for this page is over; the entire page returns to fully opaque |
No blur. This conflicts with huashu-design's "defocus triad must include blur," but here it's resolved based on the needs of an informational film: blur's purpose is to make an element cease competing for attention, but in informational films, the audience still needs to look back at it. Blur is reserved for only two places: transitions between scenes, and the entry/exit of chapter page numbers.
When to Start Dimming
Sentence Start Sentence End +1.0s +0.8s
|--------------|------------|------------|
active ============================>
dimming [===gradient===] read
- A unit must not start dimming before its own narration sentence finishes (R30's declaration half).
- After the narration finishes, allow 1.0 second for the audience to finish reading, then use 0.8 seconds to dim gradually.
- The old method was "switch focus right when the next sentence starts." The audience was still reading the previous block, but the visual had already taken it away.
Interrelated Blocks Light Up and Dim Together
A config and its applicable boundary, a value and its measurement condition — such paired content declares the same focus_group: when any member of the group is being narrated, the entire group stays active; after the last member in the group finishes + 1.0 seconds, the entire group dims together.
Judgment (R28)
Take a frame at the moment a unit defocuses and the same frame from the hold state, and compare the average gradient magnitude within the same unit's bounding box. The defocused state must be ≤ 0.85 of the hold state.
Using average gradient instead of thresholded edge count: when only contrast is reduced without adding blur, a threshold either passes everything or nothing, decoupling the measurement from the manipulation. Average gradient varies linearly with contrast; at ink level 0.70, it will measure around 0.70.
Reveal: Supporting Content is There from the Start, Only Key Items Wait for the Narration
User feedback (Round 3): "The middle box has no content, the bottom box has no content but still has its style; it looks strange at first glance." "Actually, it's okay to show unimportant content first. Important content can be typewriter-revealed during the explanation." "Usually, you just need a typewriter effect to print the content. If it's already printed and a line is mentioned again later, just highlight its background."
This narrows the Round 2 rule of "keep key content for when the narration mentions it" — it doesn't overturn it: What waits is only the one key item per unit, not the entire card.
What Must Be Drawn from the Start
Cards, chips, titles, separators, row labels, secondary rows, structure. Only one key item per unit waits for the narration — that number, that code, that set of labels.
Use Only One Type of Motion Effect per Row
| Timing | What to Use | Do Not Stack |
|---|---|---|
| First appearance | Typewriter, left to right, character by character, 0.4–1.0 seconds | Do not add scan lights, background color bands, or left accent strips |
| Subsequent mentions | Background highlight #FFF4D6 + 3px left accent strip, 0.42 seconds | — |
Highlight is the language for "re-mention." If the first appearance also uses highlight, this language is lost, and the audience can't distinguish what's new.
The previous version gave every row a single scan light, to meet the "proportion of frames with change ≥ 0.45" metric — but the user's own words were "there are too many motion effects on the text." Stacking decorative effects to meet a motion metric is now judged as a direct fail.
When is a Skeleton Screen Allowed?
When content genuinely needs to be revealed later, AND the skeleton itself is designed, it is allowed, but must satisfy: have a title and structure (not a pure white rounded rectangle); placeholder bars of varying lengths (looking like an outline of real content); the skeleton does not exceed 60% of the card height; and no two cards' skeletons look exactly identical.
Narration and Visuals Must Be About the Same Thing; This is the Bottom Line
User feedback (Round 3): "Must, MUST ensure narration and visuals and motion are consistent!!! This is the bottom line."
The failure of the second version was that the declaration itself was flawed: R22 only checked whether the reveal time falls within the claimed sentence's time window, it never checked whether that sentence was actually talking about this unit. So the 2.8x card was attached to "another metric dropped from 12.6s to 4.0s" — that sentence was talking about the second row of another card — the time window of course matched, and all gates were green.
R29: One-to-One Correspondence, and Text Matches
- Each information unit declares exactly one narration sentence.
- Two units must not share the same sentence, unless they are in the same stagger group and enter together in the same beat.
- Every sentence of narration in a scene must be declared by some unit; no orphan sentences allowed.
- The text of that sentence must contain a keyword from that unit: card title, row label, value, label text, or filename. Therefore, each information unit in
content.yamlmust have akeywordsfield.
R30: Visual Follows Narration
- Declaration layer:
dim_t >= end_time_of_that_unit's_sentence + 1.0 seconds. - Measurement layer: During the playback of each sentence, its corresponding unit's bounding box must have a visible change (typewriter text appearing, highlight appearing, value loading, etc.).