From 8dba394d4dd52678cd49b68a3ec8fd8a921a1d6d Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Tue, 4 Aug 2026 12:05:32 -0700 Subject: [PATCH] docs: make the ten hardest-reading prompting pages readable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Measured across all 136 hand-written pages, the twelve hardest to read were all in prompting/. These ten were untouched — 29% to 40% of their sentences ran over 28 words, against a site median under 15%. media-and-audio 39.7% -> 6.2% 15 semicolons -> 6 visual-specs 37.1% -> 19.0% 11 -> 9 weekly-updates 39.1% -> 0.0% runtimes-and-3d 34.1% -> 17.5% design-systems 34.0% -> 4.3% recreating-references 33.3% -> 7.3% 16 -> 1 storyboards 31.9% -> 5.4% variables-and-templating 30.3% -> 7.3% generated-artwork 29.4% -> 9.1% explainers 29.1% -> 3.3% 12 -> 1 Word counts barely move — 1752 to 1748, 1633 to 1617 — which is the point. The facts and worked examples all survived; the sentences carrying them got shorter. weekly-updates is an archive, so no date, version or fact changed there at all. One anchor came back: capstone#the-full-prompt-verbatim, which these pages link to and which an earlier commit had already moved to #the-prompt-word-for-word. Repointed. Branch total: 0 broken pages, 0 broken anchors. --- docs/prompting/design-systems.mdx | 71 +++++--- docs/prompting/explainers.mdx | 89 +++++++--- docs/prompting/generated-artwork.mdx | 52 ++++-- docs/prompting/media-and-audio.mdx | 176 ++++++++++++++++---- docs/prompting/recreating-references.mdx | 92 ++++++++-- docs/prompting/runtimes-and-3d.mdx | 124 +++++++++----- docs/prompting/storyboards.mdx | 66 +++++--- docs/prompting/variables-and-templating.mdx | 140 +++++++++++++--- docs/prompting/visual-specs.mdx | 80 +++++++-- docs/weekly-updates.mdx | 160 +++++++++--------- 10 files changed, 768 insertions(+), 282 deletions(-) diff --git a/docs/prompting/design-systems.mdx b/docs/prompting/design-systems.mdx index 8a566c3d7..6168dd730 100644 --- a/docs/prompting/design-systems.mdx +++ b/docs/prompting/design-systems.mdx @@ -5,74 +5,103 @@ description: "Point the agent at a source of brand truth — a design spec, a si import { DocsVideo } from "/snippets/docs-video.jsx"; -Everything so far was one scene at a time. This level is about videos as systems — design that persists across scenes, edits that don't regress, output that ships. It starts with the most systemic thing a video has: its brand. +Everything so far was one scene at a time. This level is about videos as systems. Design that persists across scenes. Edits that don't regress. Output that ships. It starts with the most systemic thing a video has: its brand. -"Make it on-brand" is the single vaguest thing you can ask. The agent has no way to know what your brand *is*, so it invents one. The fix is always the same: give it a **source of brand truth** — a design spec, a live site, or a Figma file — and name it in the prompt. Everything on this page is a way to do that. +"Make it on-brand" is the vaguest thing you can ask. The agent has no way to know what your brand *is*, so it invents one. + +The fix never changes. Give the agent a **source of brand truth**, and name it in the prompt. That source is a design spec, a live site, or a Figma file. Every section below is one way to do it. ## Point at a spec, don't describe a vibe -HyperFrames projects can carry a design spec — `frame.md` — whose frontmatter tokens are the machine-readable brand: exact hex values, font families, weight relationships, and the brand's Do's and Don'ts. When one exists, name it: +A HyperFrames project can carry a design spec: `frame.md`. Its frontmatter holds the machine-readable brand — exact hex values, font families, weight relationships. The prose below the frontmatter carries intent and the brand's Do's and Don'ts. + +When a spec exists, name it: > Use the palette and type from `frame.md`. Build a 15-second feature announcement. - ❌ `make it feel on-brand and premium` - ✅ `pull colors and fonts from frame.md; premium means generous spacing and one restrained accent` -The engine rationale: `on-brand` is a mood the agent guesses at. A spec's frontmatter is normative — the agent quotes the hex and font family verbatim instead of approximating, and reads the prose sections for intent. If your brand lives somewhere else (a PDF brand guide, a screenshot, pasted hex codes), attach it — attachments and pasted tokens are read more reliably than a described impression. +Why this works: `on-brand` is a mood the agent has to guess at. A spec's frontmatter is normative. The agent quotes your hex and font family verbatim instead of approximating, then reads the prose for intent. + +If your brand lives somewhere else, attach it. A PDF brand guide, a screenshot, or pasted hex codes all read more reliably than a described impression. ## Brand is truth for color and type — not for layout -A design spec tells the agent what the brand *looks like*; it does **not** dictate how to compose a video frame. Say what's sacred and let the agent stage the rest: +A design spec says what the brand *looks like*. It does **not** say how to compose a video frame. Name what's sacred and let the agent stage the rest: > Colors and fonts are locked to the brand — keep the exact hexes and the display/body pairing. Layout, spacing, and motion are yours to compose for video. -The engine rationale: web-scale brand values don't survive video. A `1px` border with a `0.06`-opacity shadow is invisible after H.264 compression; a web body size vanishes on a 1080p frame. The brand color, background choice (if the brand is a light canvas, keep it light), fonts, and weight relationships are strict — but type sizes, decorative opacity, and border weight get scaled up for the medium. Over-specifying layout from a web design system fights this; pin the palette and typography, delegate the frame. +Why this works: web-scale brand values don't survive video. A `1px` border with a `0.06`-opacity shadow is invisible after H.264 compression. A web body size vanishes on a 1080p frame. + +So treat the spec in two halves: + +- **Strict** — brand colors, fonts, weight relationships, and the background choice. If the brand is a light canvas, keep it light. +- **Scaled up for the medium** — type sizes, decorative opacity, border weight. + +Over-specifying layout from a web design system fights this. Pin the palette and typography. Delegate the frame. ## Use the site's own palette and fonts -When there's no spec but there is a brand out there, point at it and let the agent extract: +When there's no spec but the brand is out there, point at it and let the agent extract: > Match this site's look — pull its palette and fonts — and make a 20-second launch clip: `https://…` -For a well-known brand, naming it is often enough for the agent to research the palette and typography. One caveat worth stating: a single-page-app homepage often returns a near-empty shell, so if the palette comes back thin, point the agent at a blog, press, or docs page instead. This is the same brand-truth move — the *site* is the source instead of a file. +For a well-known brand, naming it is often enough. The agent researches the palette and typography itself. + +One caveat is worth stating. A single-page-app homepage often returns a near-empty shell. If the palette comes back thin, point the agent at a blog, press, or docs page instead. + +This is the same brand-truth move. The *site* is the source instead of a file. ## Bringing in a Figma frame, brand, or logo -If the brand lives in Figma, ask for it directly — the agent imports it rather than eyeballing a screenshot: +If the brand lives in Figma, ask for it directly. The agent imports it rather than eyeballing a screenshot: > Bring in the brand tokens from this Figma file, then build the intro: `https://figma.com/…` > Import this Figma frame as the opening scene and this logo as an SVG: `` -The [Figma import](/guides/figma) path freezes each import as a local asset with recorded provenance (so renders stay deterministic) and imports brand variables as composition brand tokens. Two things worth knowing when you phrase the ask: +[Figma import](/guides/figma) freezes each import as a local file with recorded provenance. Renders never call Figma, so they stay deterministic. Brand variables come in as composition brand tokens. -- **Import tokens before components.** Say "brand tokens first, then the components" — that's what lets imported component colors link to your brand variables instead of baking in duplicate hexes. -- **Storyboard frames are states, not slides.** If you point at a strip of scene frames, ask the agent to *reconstruct the motion between them* — a frame showing an element at four positions is one element animating, not four stills to flip through. +Two things are worth knowing when you phrase the ask: + +- **Import tokens before components.** Say "brand tokens first, then the components." That's what lets imported component colors link to your brand variables instead of baking in duplicate hexes. +- **Storyboard frames are states, not slides.** If you point at a strip of scene frames, ask the agent to *reconstruct the motion between them*. A frame showing an element at four positions is one element animating, not four stills to flip through. ## Keeping a multi-video series consistent -For a series — a launch set, a weekly clip, a per-region cut — consistency comes from a **shared source of truth**, not from re-describing the brand each time: +A series is a launch set, a weekly clip, or a per-region cut. Consistency comes from a **shared source of truth**, not from re-describing the brand each time: > All four videos share `frame.md` for palette and type. Only the headline and the stat change per video. -The parts that stay constant come from the one authoring spec (or one set of imported Figma tokens), and the parts that vary become [variables](/prompting/variables-and-templating). When `frame.md` changes, rerun the workflow steps that generate or assemble the affected compositions so the authored HTML picks up the new brand value. For existing compositions that must re-skin at render time, declare the shared brand tokens as composition variables and bind them through CSS custom properties. This is where design systems and templating meet: the brand is shared, the content is parameterized. +The constant parts come from that one authoring spec, or from one set of imported Figma tokens. The parts that vary become [variables](/prompting/variables-and-templating). + +When `frame.md` changes, rerun the workflow steps that generate or assemble the affected compositions. That's how the authored HTML picks up the new brand value. + +Some compositions already exist and have to re-skin at render time. Declare the shared brand tokens as composition variables instead. Every scalar variable is applied as a `--{id}` CSS custom property on the composition root, so `var(--id)` in your CSS follows the override. + +This is where design systems and templating meet. The brand is shared. The content is parameterized. ## Supplying brand assets by path -Logos, fonts, textures, and product shots are inputs — hand the agent the path, don't ask it to draw them: +Logos, fonts, textures, and product shots are inputs. Hand the agent the path — don't ask it to draw them: > Logo at `assets/logo.svg`, brand font files in `assets/fonts/`, product shot at `assets/hero.png`. Use them; don't invent placeholders. -Prefer an SVG logo (scalable, animatable) over a raster one. State the paths explicitly so the agent wires the real assets instead of generating stand-ins — and so the render is deterministic, with every asset present locally before it starts. +Prefer an SVG logo over a raster one. It scales and it animates. + +State the paths explicitly. That way the agent wires up the real assets instead of generating stand-ins. It also keeps the render deterministic, because every asset is present locally before the render starts. ## Supply inputs a workflow accepts — don't fight its preset -The creation workflows (`/product-launch-video`, `/faceless-explainer`, and the rest) each come with a designed look. The productive move is to feed that look your brand inputs, not to override its composition after the fact: +Each creation workflow comes with a designed look — `/product-launch-video`, `/faceless-explainer`, and the rest. Feed that look your brand inputs. Don't override its composition after the fact. - ❌ `run /product-launch-video, then restyle every scene to my colors afterward` - ✅ `run /product-launch-video with my palette, fonts, and logo as inputs up front` -The engine rationale: a workflow's preset is a coherent, tested system — colors, spacing, motion, and component treatments that hang together. Supplying brand inputs at the start lets it apply your palette and type *within* that system. Restyling scene-by-scene afterward pulls threads out of a design that was balanced as a whole, and you spend more effort fighting the preset than you'd have spent handing it a spec. +Why this works: a workflow's preset is a coherent, tested system. Its colors, spacing, motion, and component treatments hang together. Supply your brand inputs at the start and it applies your palette and type *within* that system. + +Restyling scene by scene afterward pulls threads out of a design that was balanced as a whole. You spend more effort fighting the preset than handing it a spec would have cost. ## Related @@ -92,10 +121,10 @@ The engine rationale: a workflow's preset is a coherent, tested system — color -**Capstone thread** — the entire [Level 7 film](/prompting/capstone) obeys a supplied `frame.md` — the real HyperFrames brand. The closing lockup is where the system shows most: ABC Solar Display for the display type and the mint→cyan CTA gradient in its single sanctioned appearance (cut from the film, below). +**Capstone thread** — the entire [Level 7 film](/prompting/capstone) obeys a supplied `frame.md`: the real HyperFrames brand. The closing lockup is where the system shows most. ABC Solar Display carries the display type, and the mint→cyan CTA gradient makes its single sanctioned appearance (cut from the film, below). -This is the clause in the [full capstone prompt](/prompting/capstone#the-prompt-word-for-word) that buys the piece — prompt language you can lift for your own video: +This is the clause in the [full capstone prompt](/prompting/capstone#the-prompt-word-for-word) that buys the piece. It's prompt language you can lift for your own video: > **Design system: the provided `frame.md` is the single source of brand truth — read it first and obey it exactly.** It is the real HyperFrames brand (by HeyGen), dark-first: flat near-black ground […] **mint `#3CE6AC` used sparingly as the single accent — mint means go / primary / active**. The mint→cyan gradient (`#3CE6AC → #00E3FF`) appears in exactly one place in the whole film: the final CTA lockup. @@ -104,6 +133,6 @@ This is the clause in the [full capstone prompt](/prompting/capstone#the-prompt- src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/capstone-region-render.mp4#t=0.1" loop /> -*That clause paying off, rendered — the closing lockup, where the brand file's display face and its one sanctioned gradient finally appear together.* +*That clause paying off, rendered. The closing lockup is where the brand file's display face and its one sanctioned gradient finally appear together.* *Next: [Variables and templating](/prompting/variables-and-templating) — turn the brand tokens that repeat across a series into named slots you fill per render.* diff --git a/docs/prompting/explainers.mdx b/docs/prompting/explainers.mdx index 1863f12bc..778bba830 100644 --- a/docs/prompting/explainers.mdx +++ b/docs/prompting/explainers.mdx @@ -5,49 +5,74 @@ description: "What to say to turn an article, notes, or a topic into a faceless import { DocsVideo } from "/snippets/docs-video.jsx"; -The last ride pointed a workflow at a website. This one drops the site entirely — arbitrary text is the whole input, and every visual downstream is invented rather than captured. +The last page pointed a workflow at a website. This one drops the site. Your +text is the whole input. Every visual is invented, not captured. ## Your first win -One prompt to [`/faceless-explainer`](/prompting/overview), with your text pasted in, is enough for a finished explainer — no site, no footage, no design decisions required yet. +Paste your text into one prompt to [`/faceless-explainer`](/prompting/overview). +That is enough for a finished explainer. No site, no footage, no design +decisions yet. -Verified, from the [examples](/prompting/examples) page — a ~60-second vertical explainer from pasted text: +Verified, from the [examples](/prompting/examples) page — a ~60-second vertical +explainer from pasted text: > /faceless-explainer Turn this into a ~60-second 1080x1920 vertical explainer: [paste your text]. One idea per scene, big typography, diagrams over stock footage, brand color #FF5533 on off-black. Male TTS voice, calm. Embedded captions, keywords highlighted in the brand color. *Rendered from the prompt above, unedited.* -Note the `~` — with a supplied script the runtime follows the spoken words, so ask for *about* a minute, not exactly one. See the [anatomy](/prompting/anatomy) for the rest of the skeleton. +Note the `~`. When you supply a script, the runtime follows the spoken words. So +ask for *about* a minute, not exactly one. See the +[anatomy](/prompting/anatomy) for the rest of the skeleton. ## What this makes -A faceless explainer: arbitrary text — an article, notes, a topic, a brief — becomes a narrated video where every visual is invented per scene (typography, abstract graphics, diagrams, data-viz). The [`/faceless-explainer`](/prompting/overview) workflow picks a design system, reshapes your text into a teaching story, generates its own TTS narration, and builds it frame by frame. +A faceless explainer. Your text becomes a narrated video — an article, notes, a +topic, a brief. Every visual is invented per scene: typography, abstract +graphics, diagrams, data-viz. -**Faceless means there's nothing to capture.** No site, no footage, no asset inventory — the visuals are designed downstream. If you have a product to sell use [`/product-launch-video`](/prompting/product-launch); if you have a real site to show use [`/product-launch-video`](/prompting/product-launch) with a tour brief; a GitHub PR goes to [`/pr-to-video`](/prompting/code-and-prs). Unsure → start at `/hyperframes`. +The [`/faceless-explainer`](/prompting/overview) workflow does four things. It +picks a design system. It reshapes your text into a teaching story. It generates +its own TTS narration. Then it builds the video frame by frame. + +**Faceless means there is nothing to capture.** No site, no footage, no asset +inventory. The visuals are designed downstream. + +Pick a different workflow when you do have something to show: + +- A product to sell → [`/product-launch-video`](/prompting/product-launch) +- A real site to show → [`/product-launch-video`](/prompting/product-launch) + with a tour brief +- A GitHub PR → [`/pr-to-video`](/prompting/code-and-prs) +- Unsure → start at `/hyperframes` ## The knobs that matter -What you can already steer from the prompt, before you've learned any technique. +You can steer all of these from the prompt, before you have learned any +technique. | Knob | What to say | Why it matters | | --- | --- | --- | -| **Verbatim vs summarized** | "use my wording verbatim" or "restructure it freely" | The workflow asks once. Verbatim keeps your voice but locks the word count; summarized lets it cut and reorder for pace | -| **Duration** | "~60 seconds", never "60 seconds" | With a script the narration sets the real length; a hard number forces the agent to trim or pad the words | -| **Scene density** | "one idea per scene" | A faceless scene has one invented focal to animate; two ideas in a scene leave nothing to build the motion around, and it reads as a text dump | -| **Angle** | "concept" / "how-to" / "listicle" / "narrative" | The angle decides the story shape — the workflow reshapes your text into it rather than reading paragraphs in order | -| **Caption style** | "embedded captions, keywords highlighted in the accent color" | Captions are burned in; naming the highlight color ties them to the palette instead of a default pill | -| **Palette** | "brand color #FF5533 on off-black" | With no site to borrow from, the preset supplies a full palette; a named accent + ground personalizes it | -| **Voice** | "male TTS voice, calm" / "warm female voice" | Gender and tone are prompt words; the provider is a workflow decision | +| **Verbatim vs summarized** | "use my wording verbatim" or "restructure it freely" | The workflow asks once. Verbatim keeps your voice but locks the word count. Summarized lets it cut and reorder for pace. | +| **Duration** | "~60 seconds", never "60 seconds" | With a script, the narration sets the real length. A hard number forces the agent to trim or pad the words. | +| **Scene density** | "one idea per scene" | A faceless scene has one invented focal to animate. Two ideas leave nothing to build the motion around. It reads as a text dump. | +| **Angle** | "concept" / "how-to" / "listicle" / "story" | The angle decides the story shape. The workflow reshapes your text into it instead of reading your paragraphs in order. | +| **Caption style** | "embedded captions, keywords highlighted in the accent color" | Captions are burned in. Naming the highlight color ties them to your palette instead of a default pill. | +| **Palette** | "brand color #FF5533 on off-black" | There is no site to borrow from, so the preset supplies a full palette. A named accent and ground personalize it. | +| **Voice** | "male TTS voice, calm" / "warm female voice" | Gender and tone are prompt words. The provider is a workflow decision. | - The single biggest quality lever here is scene density. "One idea per scene" turns a dense paragraph into a paced sequence — the workflow reorders and compresses your text to hit it, which is exactly what makes an explainer teach instead of recite. + Scene density is the single biggest quality lever here. "One idea per scene" + turns a dense paragraph into a paced sequence. The workflow reorders and + compresses your text to hit it. That is what makes an explainer teach instead + of recite. ## Variants @@ -56,7 +81,8 @@ What you can already steer from the prompt, before you've learned any technique. > /faceless-explainer Make a ~30-second 1920x1080 explainer on how HTTPS keeps a request private, for a non-technical audience — the takeaway: your data is sealed before it leaves the browser. Concept angle: one idea per scene, big geometric type, a simple lock-and-key diagram as the centerpiece (swap the metaphor with the topic). Near-black ink on off-white with a deep-blue accent. Female TTS voice, warm and clear. Embedded captions, key terms highlighted in the accent color. - Shorter runtime, landscape for YouTube / embed. Fewer scenes means the topic has to compress — naming the takeaway tells the workflow what to keep. + Shorter runtime, landscape for YouTube or an embed. Fewer scenes means the + topic has to compress. Naming the takeaway tells the workflow what to keep. > /faceless-explainer Make a ~45-second 1080x1920 listicle: "5 habits of fast-shipping teams". Listicle angle — one habit per scene, each with a big number and a one-line label, escalating energy toward #1. Off-black with a lime accent. Male TTS voice, upbeat. Embedded captions, the habit label highlighted each scene. - The listicle angle gives each item its own scene with a consistent number-and-label shape, so the structure reads as a countdown rather than a wall of points. + The listicle angle gives each item its own scene. Every scene reuses the same + number-and-label shape. The result reads as a countdown, not a wall of + points. > /faceless-explainer Make a ~60-second 1920x1080 how-to on setting up a CI pipeline, for developers. How-to angle: one step per scene, each built around a simple node-and-arrow diagram that draws on as the narration explains it. Charcoal with a teal accent. Calm male TTS voice. Embedded captions, the step name highlighted. - A how-to leans on diagrams as the load-bearing visual. Describe the diagram *shape* per step ("node-and-arrow", "a pipeline that fills left to right") and let the workflow invent the specifics. + A how-to leans on diagrams as the load-bearing visual. Describe the diagram + *shape* per step — "node-and-arrow", or "a pipeline that fills left to + right". Let the workflow invent the specifics. ## Common failure modes -**"60 seconds" instead of "~60 seconds".** Same rule as [ride 1](/prompting/product-launch#common-failure-modes), and it bites harder here because the script is the whole video — a supplied script's spoken duration isn't knowable until the TTS renders. +**"60 seconds" instead of "~60 seconds".** Same rule as on the +[product launch page](/prompting/product-launch#common-failure-modes). It bites +harder here, because the script is the whole video. You cannot know a supplied +script's spoken duration until the TTS renders. + - ❌ `a 60-second explainer from this text: ...` - ✅ `a ~60-second explainer from this text: ...` -**Cramming ideas into a scene.** Every faceless visual is invented around a single focal; overload the scene and there's no clear thing to animate. +**Cramming ideas into a scene.** Every faceless visual is invented around a +single focal. Overload the scene and there is no clear thing to animate. + - ❌ `explain all five caching layers in one scene` - ✅ `one idea per scene — one caching layer at a time` -**Asking it to capture or pull real imagery.** There is no capture step; a faceless explainer invents its visuals. +**Asking it to capture or pull real imagery.** There is no capture step. A +faceless explainer invents its visuals. + - ❌ `pull screenshots from the site and explain the feature` -- ✅ that's a site or product video — use [`/product-launch-video`](/prompting/product-launch) +- ✅ that's a site or product video — use + [`/product-launch-video`](/prompting/product-launch) + +**Leaving the look unspecified when you care.** There is no brand to read, so +the preset picks the palette. If you have colors, name them. -**Leaving the look unspecified when you care.** With no brand to read, the preset picks the palette; if you have colors, name them. - ❌ `make it look on-brand` - ✅ `brand color #FF5533 on off-black` diff --git a/docs/prompting/generated-artwork.mdx b/docs/prompting/generated-artwork.mdx index 2473ce9fa..e87a2d94c 100644 --- a/docs/prompting/generated-artwork.mdx +++ b/docs/prompting/generated-artwork.mdx @@ -1,25 +1,51 @@ --- title: When to generate artwork -description: "Code-drawn wins for UI, type, geometry, and 3D; illustration-led hero art comes from an image model, animated as layers." +description: "Code-drawn wins for UI, type, geometry, and 3D. Illustration-led hero art comes from an image model, animated as layers." --- import { DocsVideo } from "/snippets/docs-video.jsx"; -Your Level 1 music slideshow cut real photos to the beat — there was real art to work with. This chapter is for the opposite case: a hero character, a painterly scene, sculptural objects that don't exist as a photo or a footage capture yet. +Your Level 1 music slideshow cut real photos to the beat. There was real art to +work with. This chapter is for the opposite case: a hero character, a painterly +scene, or sculptural objects that do not exist yet as a photo or a capture. -Code-drawn HTML/CSS/SVG excels where the medium is native: UI mockups, typography, geometric shapes, charts, pixel art, and 3D via Three.js. For **illustration-led** hero art — characters, painterly scenes, sculptural objects — hand-drawn SVG tops out at clipart quality no matter how well you prompt. The fix is a hybrid: +## What code draws well — and what it doesn't + +Code-drawn HTML, CSS, and SVG excel where the medium is native. That means UI +mockups, typography, geometric shapes, charts, pixel art, and 3D via Three.js. + +**Illustration-led** hero art is the exception. Characters, painterly scenes, +and sculptural objects are what hand-drawn SVG is worst at. It tops out at +clipart quality no matter how well you prompt. + +## The hybrid: generate the art, animate it in code + +Ask for the still art from an image model, then move it with code: > Generate the hero artwork as an image (via the media-use skill's image generation), then animate it with code. Anything that must move independently — eyelids, light beams, drawing lines — stays a code layer on top of the static art. -Three rules that make this work: +The generated image is one flat layer. Everything that has to move on its own +stays a code layer above it. -1. **Generate on a solid contrasting background** (magenta works) so the subject keys out cleanly. A light subject on a light background gets silently eaten. -2. **Key flat vector-style art with a chroma key** (`ffmpeg colorkey`), not AI background removal — `remove-background`'s matting model is tuned for photographic and human subjects and reads flat art unreliably, sometimes keeping the background instead of the subject. Reserve `remove-background` for photographs. -3. **Put a restraint clause in the generation prompt** ("minimal, lots of negative space") — image models fill the frame by default, and a busy generated texture reads as cheap as bad vector art. +## Three rules that make this work + +1. **Generate on a solid contrasting background.** Magenta works well. It lets + the subject key out cleanly. A light subject on a light background gets + silently eaten. +2. **Key flat vector-style art with a chroma key** (`ffmpeg colorkey`), not AI + background removal. `remove-background` runs a human-segmentation matting + model, so it is tuned for photographs and people. It reads flat art + unreliably, and sometimes keeps the background instead of the subject. Save + `remove-background` for photographs. +3. **Put a restraint clause in the generation prompt** — "minimal, lots of + negative space". Image models fill the frame by default. A busy generated + texture reads as cheap as bad vector art. ## The difference, side by side -The same brief — four people arm in arm, warm gradient sweaters, flat-illustration style — built both ways. Same animation beats, same craft layer (lighting, atmosphere, grade); the only variable is where the figures came from. +The same brief built both ways: four people arm in arm, warm gradient sweaters, +flat-illustration style. Same animation beats, same craft layer of lighting, +atmosphere, and grade. The only variable is where the figures came from. -*Generated illustration animated as layers — real anatomy and editorial shading; the animated line still passes behind the figures because the artwork was keyed to transparency.* +*Generated illustration animated as layers — real anatomy and editorial shading. The animated line still passes behind the figures, because the artwork was keyed to transparency.* -**Capstone thread** — the [Level 7 film](/prompting/capstone)'s Surface region rides on generated artwork: a palette-neutral mural duotoned live by CSS from the composition's two variables, so even the raster re-skins on a `--variables` render (cut from the film, below). +**Capstone thread** — the [Level 7 film](/prompting/capstone)'s Surface region +rides on generated artwork. The mural is generated palette-neutral, then +duotoned live by CSS from the composition's two variables. So even the raster +re-skins on a `--variables` render. That region is cut from the film below. -This is the clause in the [full capstone prompt](/prompting/capstone#the-prompt-word-for-word) that buys the piece — prompt language you can lift for your own video: +This is the clause in the [full capstone prompt](/prompting/capstone#the-prompt-word-for-word) +that buys the piece — prompt language you can lift for your own video: > […] over a **generated-artwork backdrop** — a flat abstract mural evoking motion trails, generated **palette-neutral (grayscale) and duotoned live by CSS** from the two variables so it re-skins with everything else. **The mural is a full-frame, screen-fixed backdrop: it never moves on screen — the widening iris circle alone reveals it already in place at full frame […] and it exits by fading out.** diff --git a/docs/prompting/media-and-audio.mdx b/docs/prompting/media-and-audio.mdx index a100a4af4..0b2b7b118 100644 --- a/docs/prompting/media-and-audio.mdx +++ b/docs/prompting/media-and-audio.mdx @@ -1,28 +1,50 @@ --- title: Media and audio -description: "Ask for the voiceover, music, sound, captions, cutouts, and assets a composition needs — with the precise, unambiguous phrasing the media pipeline acts on." +description: "Ask for the voiceover, music, sound, captions, cutouts, and assets a composition needs, in phrasing the media pipeline acts on." --- import { DocsVideo } from "/snippets/docs-video.jsx"; -By now your video moves and reads right; this level gives it a voice. HyperFrames owns media *playback*; a sibling media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say. +Your video moves and reads right. This level gives it a voice. + +HyperFrames owns media *playback*. A sibling media pipeline resolves everything +else: voice, music, sound effects, images, icons, logos, captions, and +background removal. You describe what the composition needs. The agent resolves +each need to a frozen local file. + +Precision is the whole craft here. Vague asks come back wrong. "Add some music" +and "no sound" are the two that bite most often, because the pipeline does +exactly what the words say. ## Voiceover (TTS) -Text-to-speech runs locally through Kokoro — no API key needed — with a HeyGen TTS upsell behind it. Describe the content and the agent picks a fitting voice, or name the voice, tone, and speed directly: +The agent picks a voice engine in a fixed order. HeyGen Starfish goes first if +your HeyGen account is configured. ElevenLabs is next if that key is set. +Otherwise the local Kokoro model runs, and it needs no API key. + +Describe the content and let the agent pick a fitting voice. Or name the voice, +tone, and speed yourself: > Generate narration for this script with a professional female voice. > Add TTS voiceover, British male voice, at 1.1× speed. -The [Vocabulary](/prompting/vocabulary#text-to-speech-voices) table maps content types to Kokoro voices (for example `af_heart` / `af_nova` for a product demo, `am_adam` / `bf_emma` for a tutorial, `af_sky` / `am_michael` for marketing). Name one directly if you already know it; otherwise describe the read and let the agent choose. +The [Vocabulary](/prompting/vocabulary#text-to-speech-voices) table maps content +types to Kokoro voices. `af_heart` and `af_nova` suit a product demo. `am_adam` +and `bf_emma` suit a tutorial. `af_sky` and `am_michael` suit marketing. Name a +voice directly if you already know it. Otherwise describe the read and let the +agent choose. - ❌ `add a voice` - ✅ `warm, unhurried female narration of the quoted script` — tone and pace are what actually change the delivery ## Background music -Music resolves from a large catalog by mood, and it should almost always sit *under* the narration, not compete with it. Give the mood **and** a loudness target — the pipeline can duck and normalize to a level, so an explicit target lands a mix instead of a guess: +Music resolves from a large catalog by mood. It should almost always sit *under* +the narration rather than compete with it. + +Give the mood **and** a loudness target. The pipeline can duck and normalize to +a level, so an explicit target lands a mix instead of a guess. > Add subtle electronic BGM, kept under −18 dB so it stays beneath the voiceover. @@ -32,12 +54,15 @@ Music resolves from a large catalog by mood, and it should almost always sit *un - ✅ `subtle background music, ducked ~12 dB under the voice` — a mix instruction the pipeline can execute - A stated loudness target ("under −18 dB," "ducked under the voice") is the difference between music that supports the piece and music that buries it. When there's narration, always say the bed goes under it. + A stated loudness target ("under −18 dB," "ducked under the voice") is the + difference between music that supports the piece and music that buries it. + When there's narration, always say the bed goes under it. ## Sound effects -SFX resolve from a small bundled library plus the catalog. Cue them to specific moments — a transition, a stamp-in, an impact — rather than sprinkling them: +SFX resolve from a bundled 19-file library plus the catalog. Cue them to +specific moments — a transition, a stamp-in, an impact. Don't sprinkle them. > Add a whoosh on each of the three scene transitions. @@ -45,56 +70,114 @@ SFX resolve from a small bundled library plus the catalog. Cue them to specific ## Pace reveals to the narration -Once a video has a voice, the voice is the clock — the next instruction that matters is telling the agent that on-screen elements land **on their spoken cues** — the stat appears as the narrator says it, not at some independent time the builder eyeballed. Without this, narration and visuals drift into two parallel tracks that happen to share a file: +Once a video has a voice, the voice is the clock. Say that on-screen elements +land **on their spoken cues**. The stat appears as the narrator says it, not at +some independent time the builder eyeballed. Skip this and narration and visuals +drift into two parallel tracks that happen to share a file. > VO-paced reveals: each scene's elements land on their spoken cues; secondary elements keep resolving while the narrator is mid-thought; the scene is complete just as the narration moves on. -The capstone film applies exactly this rule to every region — its Direction block reads: +The capstone film applies exactly this rule to every region. Its Direction block +reads: > VO-paced reveals: each region's elements land on their spoken cues as the camera arrives; secondary elements keep resolving while the camera is present; the region is complete just as the camera accelerates away. -Two practical notes: the agent gets word timings for free (the narration is transcribed with per-word timestamps, the same machinery behind [captions](#captions-and-transcription)), so "on its spoken cue" is a real, executable instruction — and the inverse rule matters just as much: the narration never waits for the visuals. Pace the camera and reveals to the voice, not the voice to the animation. +Two practical notes. + +The agent gets word timings for free. Narration is transcribed with per-word +timestamps — the same machinery behind +[captions](#captions-and-transcription). So "on its spoken cue" is a real, +executable instruction. + +The inverse rule matters just as much. The narration never waits for the +visuals. Pace the camera and the reveals to the voice, not the voice to the +animation. ## Captions and transcription -Captions come from word-level timestamps. When you generate a voiceover, the timing comes with it; for existing footage, transcription produces the timing (Parakeet by default, with a whisper.cpp fallback). Scaffolding a project from a source video can generate captions from its audio directly. +Captions come from word-level timestamps. Generate a voiceover and the timing +comes with it. For existing footage, transcription produces the timing: Parakeet +runs when it's installed, and whisper handles it otherwise. Scaffolding a +project from a source video can generate captions from its audio directly. > Transcribe the narration and add karaoke-style captions synced to it. > Generate captions from `assets/interview.mp4` and style them hype, scale-pop. -Caption *look* is its own vocabulary (tone, size, per-word emphasis) — see [Captions catalog](/prompting/captions-catalog) for the styles. This page is about producing the timed text; that page is about styling it. +Caption *look* is its own vocabulary — tone, size, per-word emphasis. See the +[Captions catalog](/prompting/captions-catalog) for the styles. This page is +about producing the timed text. That page is about styling it. ## Background removal (transparent cutouts) -The `remove-background` command mattes a subject out of a video or image locally and hands you a transparent WebM you can drop into any scene as a `