Module 4.2 — Onboarding, Lessons & Releases

🧭 Product onboarding

Explaining a new feature in ~90 seconds is HyperFrames’ most immediate use case. Instead of a static screenshot tour, you deliver a narrated MP4 that the user watches in the app itself—and can regenerate whenever the feature changes.

Why video instead of a carousel of screenshots?

Screenshots get outdated: with each release, the UI changes and the carousel falls behind. With HyperFrames, SCRIPT.md is the source of truth. You edit the script, run node build-index.mjs && npx hyperframes render and have a new video in minutes — no editor, no screen recorder.

Workflow for a feature onboarding

Write SCRIPT.md

6 scenes, ~100 s of narration in total. Describe the feature from the user's perspective, not the developer's.

Generate narration with Kokoro

Voice pf_dora --speed 0.98, measure duration with ffprobe, fill in AUDIO[] in the generator.

Compose scenes in build-index.mjs

Each scene = a UI state recreated in premium dark HTML. Use GSAP to animate entrances and highlights.

Render and distribute

npx hyperframes render --quality high --output renders/onboarding-v2.mp4 — uploads to the CDN or embeds directly in the app.

✓ Onboarding best practices

✓ 1–3 sentences of narration per scene (≤20 s)
✓ UI recreated in HTML, not a real screenshot
✓ Final CTA with a direct link to the feature
✓ 9:16 version for mobile onboarding

✗ Common errors

✗ Video over 5 minutes — viewers leave after 30 seconds
✗ Screenshots instead of HTML (gets outdated)
✗ Very fast narration — use --speed 0.98, not 1.2
✗ No silent version change: forgetting to rerender after an update

💡

Tip: semantic versioning in the file name

Name renders onboarding-v1.mp4, onboarding-v2.mp4. This way, the CDN doesn't cache the old video, and you keep a history for rollback.

Key concepts

⏱️

~90 s

ideal duration

🔄

Regenerable

with each release

📱

9:16 mobile

in-app onboarding

🎙️

pf_dora

local PT-BR voice

🎓 Micro-lessons and courses

Turning a concept into a short narrated lesson — with animated code, an SVG diagram, and synchronized captions — is what HyperFrames does best. Each lesson is a SCRIPT.md; a course is a folder of SCRIPTs.

Example prompt — asking Claude for a micro-lesson

# Paste into Claude Code (with the video-explicativo skill active)

Create an explainer video about

"JavaScript closures".

- 6 scenes, ~90 s of narration

- Show animated code in scene 3

- Final scene: CTA for the full course

- 16:9 + 9:16 format

Palette: standard premium dark

(bg #0D1321, accent #FFC300)

Recommended structure for a micro-lesson

Scene 1 — Hook

Everyday question or problem. ≤15 sec.

Scenes 2–5 — Concept

Progressive explanation with code or a diagram. ~60 seconds total.

Scene 6 — CTA

Link to the full lesson or next video. ≤10 s.

💡

CAPTIONS[] increase retention by up to 40%

The array CAPTIONS[] no build-index.mjs defines captions synchronized with the audio. For micro-lessons, fill in every scene — viewers watching without sound (LinkedIn feed, phone on silent) can still absorb the content.

📊 Actual micro-lesson metrics (~90 s format)

Completion rate

~65–80% for videos ≤2 min vs. ~30% for videos ≥10 min.

Production cost

R$ 0,00 per video — local TTS, local rendering, no subscription.

Update time

Edit SCRIPT.md + render again: ~5 minutes of human work.

Key concepts

📝

SCRIPT.md

source of truth

💬

CAPTIONS[]

synchronized caption

🎬

6 scenes

default structure

📐

16:9 + 9:16

two formats

📣 Launch / video changelog

Announcing a release with a narrated video instead of a text post increases engagement—especially on LinkedIn and the product’s Discord channel. HyperFrames produces the changelog video in the same CI pipeline that publishes the release.

⚠️

The textual changelog trap

Release note posts are ignored by 80%+ of users. Videos of 60–90 s with narration and animation of the new feature have 3–5× higher open rates on channels like Discord, Slack, and product email.

Example script — changelog scene

# assets/txt/s1.txt — scene 1 narration from the changelog

Version 2.3 is live.

Three improvements you'll notice

from the very first use.

# Generate the WAV:

npx kokoro-tts assets/txt/s1.txt \

--voice pf_dora --speed 0.98 \

--output assets/audio/s1.wav

# Measure duration:

ffprobe -v error -show_entries format=duration \

-of default=noprint_wrappers=1:nokey=1 \

assets/audio/s1.wav

# → e.g.: 5.82 (seconds) — put it in AUDIO[0]

✓ Effective video changelog

✓ Focus on 3 changes, not all 47 in the release
✓ Show the animated “before” and “after”
✓ 9:16 version for product Stories/Reels
✓ Automate in CI: npx hyperframes render in the release pipeline

✗ What to avoid

✗ Listing fixed bugs — the user doesn’t care
✗ Over 2 minutes long — attention drops
✗ Narrate internal company jargon ("service layer refactor")
✗ Forget the CTA: "update now at inema.club/app"

Key concepts

📣

Narrated changelog

video > text

🤖

CI/CD

render in the pipeline

🔢

Max. 3 features

focus increases impact

🧑‍🤝‍🧑 Explain a technical concept to the team

Align internal understanding without a meeting. A 90-second video explains an architectural decision, a new coding standard, or a deploy process—and stays available for asynchronous reference in Notion, Confluence, or a Slack channel.

Async beats meetings for technical understanding

Alignment meetings have a high attention cost and low retention. A narrated 90 s video, with an animated diagram and real code, can be paused, rewound, and watched when the developer is focused — not when they’ve been called into a meeting.

Asynchronous video vs. alignment meeting

Aspect	HyperFrames video	Synchronous meeting
Team time cost	90 s per person	30–60 min × N devs
Availability	Async, 24/7	Depends on schedule
Content retention	Can pause/review	Depends on notes
Update	Re-run the build	New meeting

💡

Inline SVG diagrams are ideal for technical concepts

Use the function sceneN() of the build-index.mjs to inject futuristic SVG with animated arrows (GSAP gsap.from() + stagger) showing the system flow. Much clearer than a text slide.

Key concepts

🔀

Asynchronous

without blocking the schedule

📐

Animated SVG

visual architecture

📎

Notion/Confluence

permanent embed

🔄

Rerunnable

updates without a meeting

📄 Video documentation that doesn’t go out of date

The biggest complaint about video documentation is that it becomes outdated within weeks. With HyperFrames, the video is a build artifact—when the content changes, just edit SCRIPT.md and run the build again. No video editor needed.

Video documentation update cycle

APIs change — docs become outdated

Renamed endpoint, new parameter, changed behavior. The old video is out of date.

Edit SCRIPT.md e assets/txt/sN.txt

Adjust the narration lines and HTML for the affected scene. ~5 min of work.

Re-run narration only for changed scenes

npx kokoro-tts assets/txt/s3.txt --voice pf_dora --speed 0.98 --output assets/audio/s3.wav

Rebuild and render

node build-index.mjs && npx hyperframes lint && npx hyperframes render --quality high --output renders/docs-api-v3.mp4

✓

Updated video published

From zero to a new MP4: ~10 min. No need to open a video editor or record your screen again.

🗂️ Recommended project structure for video docs

docs-api/

SCRIPT.md # script

build-index.mjs # generator

design.md # brand house style

assets/

txt/s1.txt … s6.txt

audio/s1.wav … s6.wav

fonts/*.woff2 + fonts.css

renders/

docs-api-v1.mp4

docs-api-v2.mp4

docs-api-v3.mp4 # ← current

Key concepts

🏗️

Build artifact

MP4 = CI output

✏️

~5 min to edit

to update

📌

Versioned

render history

🔒

Local-first

no cloud, no cost

🎨 Adapt the house style to the client's brand

HyperFrames has a default premium dark palette (#0D1321 bg, #FFC300 accent). But the design.md is the only file you need to swap to adapt the entire look to a different brand — while keeping the whole pipeline intact.

What changes when you switch the design.md

Changes with design.md:

✓ Background color (bg)
✓ Accent color (buttons, borders, highlights)
✓ Fonts (headings, body, monospace)
✓ Final CTA color and text
✓ Company logo/icon in the opening scene

Doesn’t change (the pipeline stays the same):

— Scene structure (SCRIPT.md)
— TTS (pf_dora, Kokoro local)
— Render (headless Chrome + FFmpeg)
— npx hyperframes lint/render commands

Example design.md for a fictional "FinovaTech" brand

# design.md — FinovaTech (replace with the client's brand version)

bg: "#0A0F1E" # dark navy

panel: "#111827" # panel

border: "#1E3A5F" # subtle border

text: "#E2F0FF" # main text

accent: "#00C2FF" # FinovaTech blue

code: "#7FDBFF" # code/monospace

font_title: "Plus Jakarta Sans"

font_body: "Inter"

font_code: "Fira Code"

cta_text: "Open your account at finovatech.com"

cta_url: "https://finovatech.com/abrir"

✓ Effective brand adaptation

✓ Always use a dark background (premium dark — don't give in to the "white background")
✓ Accent with contrast ≥4.5:1 against the background
✓ Title font with a weight of 700 or 800
✓ Test with npx hyperframes inspect --samples 16 before delivering

✗ Customization pitfalls

✗ White background — antialiased fonts look pixelated in the render
✗ Accent that's too light (e.g., #FFFF00) — obscures the text
✗ Change the LEAD/TAIL/FADE without testing (LEAD=0.5 TAIL=0.9 FADE=0.45 are the validated values)
✗ Use a font unavailable on Google Fonts — it breaks the fetch-fonts.mjs

💡

LEAD, TAIL, and FADE: scene timings

The values LEAD=0.5 (silence before narration), TAIL=0.9 (pause after narration) and FADE=0.45 (fade duration between scenes) were calibrated for the voice pf_dora --speed 0.98. If you change the voice or speed, recalibrate these values.

Key concepts

🎨

design.md

only file to swap

⏱️

LEAD/TAIL/FADE

0.5 / 0.9 / 0.45

🔤

Google Fonts

fetch-fonts.mjs

🌑

Dark premium

always a dark background

📋 Module 4.2 summary

What you learned

✓ Product onboarding: narrated video in ~90 s, regenerable with every release
✓ Micro-lessons: 6-scene structure with CAPTIONS[] for accessibility
✓ Video changelog: max. 3 features, product-style narration
✓ Asynchronous technical alignment: animated SVG replaces a 30-minute meeting
✓ Video docs: MP4 is a build artifact, update it in ~10 min
✓ Brand adaptation: only design.md changes—the entire pipeline stays the same

Values and commands to remember

→ pf_dora --speed 0.98 — default PT-BR voice
→ LEAD=0.5 / TAIL=0.9 / FADE=0.45 — validated timings
→ npx hyperframes lint before every render
→ npx hyperframes inspect --samples 16 to check the layout
→ bg #0D1321 / accent #FFC300 — standard premium dark palette
→ --quality high for the final render (not a draft)

Next module:

4.3

🧰 Prompt library

Collection of ready-made prompts for the most common use cases — onboarding, micro-lessons, changelogs, and more.

← Back to Learning Path 4 Next Module: 4.3 Prompt Library →