Skip to content

Commit 12030b0

Browse files
authored
docs(prompting): the Prompt Guide as six topic pages (#6378)
* docs(prompting): the Prompt Guide as six topic pages * docs(prompting): call the skill the way each agent does The overview told every own-agent user to start with /hyperframes; Codex uses $hyperframes, and other agents have their own way. The line now names both and keeps the caveat the old page had.
1 parent 8d773fc commit 12030b0

36 files changed

Lines changed: 2045 additions & 3067 deletions

‎docs/docs.json‎

Lines changed: 90 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -90,67 +90,19 @@
9090
"group": "Prompt Guide",
9191
"pages": [
9292
"prompting/overview",
93+
"prompting/motion",
94+
"prompting/media-and-audio",
95+
"prompting/captions-catalog",
96+
"prompting/color-grading",
97+
"prompting/design-systems",
9398
{
94-
"group": "Level 2 — Control",
99+
"group": "More prompt topics",
95100
"pages": [
96-
"prompting/anatomy",
97-
"prompting/specification-dial",
98-
"prompting/vocabulary",
99-
"prompting/visual-specs",
100-
"prompting/examples"
101-
]
102-
},
103-
{
104-
"group": "Level 3 — Life",
105-
"pages": [
106-
"prompting/motion",
107-
"prompting/transitions"
108-
]
109-
},
110-
{
111-
"group": "Level 4 — Substance",
112-
"pages": [
113-
"prompting/code-blocks",
114-
"prompting/data-and-maps",
115-
"prompting/overlays-and-lower-thirds",
116-
"prompting/captions-catalog",
117-
"prompting/generated-artwork",
118-
"prompting/color-grading",
119-
"prompting/vfx-and-liquid-glass",
120-
"prompting/runtimes-and-3d"
121-
]
122-
},
123-
{
124-
"group": "Level 5 — Voice and sound",
125-
"pages": [
126-
"prompting/media-and-audio",
127-
"prompting/audio-effects"
128-
]
129-
},
130-
{
131-
"group": "Level 6 — Scale",
132-
"pages": [
133-
"prompting/design-systems",
134-
"prompting/variables-and-templating",
135-
"prompting/storyboards",
101+
"prompting/examples",
136102
"prompting/editing-existing-videos",
137-
"prompting/iterating",
138103
"prompting/recreating-references",
139-
"prompting/rendering-and-output",
140-
"prompting/remotion-migration"
141-
]
142-
},
143-
{
144-
"group": "Level 7 — Capstone",
145-
"pages": [
146104
"prompting/capstone"
147105
]
148-
},
149-
{
150-
"group": "Appendix",
151-
"pages": [
152-
"prompting/rules-and-anti-patterns"
153-
]
154106
}
155107
]
156108
},
@@ -164,9 +116,11 @@
164116
"guides/captions-and-recuts",
165117
"guides/motion-graphics",
166118
"guides/music-to-video",
119+
"prompting/data-and-maps",
167120
"guides/slideshow",
168121
"guides/general-video",
169-
"guides/hyperframes-vs-remotion"
122+
"guides/hyperframes-vs-remotion",
123+
"prompting/remotion-migration"
170124
]
171125
},
172126
{
@@ -1313,6 +1267,86 @@
13131267
"source": "/guides/color-grading",
13141268
"destination": "/guides/media-effects#fix-and-grade-the-color",
13151269
"permanent": true
1270+
},
1271+
{
1272+
"source": "/prompting/rendering-and-output",
1273+
"destination": "/guides/rendering#ask-the-agent-for-the-right-output",
1274+
"permanent": true
1275+
},
1276+
{
1277+
"source": "/prompting/specification-dial",
1278+
"destination": "/prompting/overview#how-much-to-specify",
1279+
"permanent": true
1280+
},
1281+
{
1282+
"source": "/prompting/code-blocks",
1283+
"destination": "/prompting/captions-catalog#code-on-screen",
1284+
"permanent": true
1285+
},
1286+
{
1287+
"source": "/prompting/runtimes-and-3d",
1288+
"destination": "/prompting/color-grading#3d-and-other-animation-runtimes",
1289+
"permanent": true
1290+
},
1291+
{
1292+
"source": "/prompting/visual-specs",
1293+
"destination": "/prompting/color-grading#high-fidelity-looks",
1294+
"permanent": true
1295+
},
1296+
{
1297+
"source": "/prompting/variables-and-templating",
1298+
"destination": "/prompting/design-systems#templates-and-variables",
1299+
"permanent": true
1300+
},
1301+
{
1302+
"source": "/prompting/rules-and-anti-patterns",
1303+
"destination": "/prompting/overview#rules-and-common-mistakes",
1304+
"permanent": true
1305+
},
1306+
{
1307+
"source": "/prompting/generated-artwork",
1308+
"destination": "/prompting/color-grading#generated-artwork",
1309+
"permanent": true
1310+
},
1311+
{
1312+
"source": "/prompting/iterating",
1313+
"destination": "/prompting/overview#iterate-toward-the-look",
1314+
"permanent": true
1315+
},
1316+
{
1317+
"source": "/prompting/transitions",
1318+
"destination": "/prompting/motion#between-scenes-transitions",
1319+
"permanent": true
1320+
},
1321+
{
1322+
"source": "/prompting/audio-effects",
1323+
"destination": "/prompting/media-and-audio#mix-it",
1324+
"permanent": true
1325+
},
1326+
{
1327+
"source": "/prompting/storyboards",
1328+
"destination": "/prompting/design-systems#storyboards",
1329+
"permanent": true
1330+
},
1331+
{
1332+
"source": "/prompting/vocabulary",
1333+
"destination": "/prompting/motion#words-for-how-motion-feels",
1334+
"permanent": true
1335+
},
1336+
{
1337+
"source": "/prompting/vfx-and-liquid-glass",
1338+
"destination": "/prompting/color-grading#vfx-and-liquid-glass",
1339+
"permanent": true
1340+
},
1341+
{
1342+
"source": "/prompting/anatomy",
1343+
"destination": "/prompting/overview#the-shape-of-a-strong-prompt",
1344+
"permanent": true
1345+
},
1346+
{
1347+
"source": "/prompting/overlays-and-lower-thirds",
1348+
"destination": "/prompting/captions-catalog#overlays-and-lower-thirds",
1349+
"permanent": true
13161350
}
13171351
],
13181352
"integrations": {

‎docs/guides/faceless-explainer.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ explainer from pasted text:
9393

9494
Note the `~`. When you supply a script, the runtime follows the spoken words. So
9595
ask for *about* a minute, not exactly one. See the
96-
[anatomy](/prompting/anatomy) for the rest of the skeleton.
96+
[anatomy](/prompting/overview#the-shape-of-a-strong-prompt) for the rest of the skeleton.
9797

9898
### Say these when they matter
9999

‎docs/guides/motion-graphics.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ The canonical shape: routed, spec'd, beat-timestamped, copy quoted, technique pi
7373

7474
**Registry blocks vs freeform.** Naming a block (`apple-money-count`, `x-post`, `data-chart`, `code-typing`, `us-map` / `world-map`) makes the agent compose reuse-first: install the block, customize in place, hand-author only the gaps. Omit the block and it hand-builds from your description — fine for one-off looks, more drift on the details you didn't pin. Name blocks exactly as they appear in the [catalog](/catalog/blocks/data-chart).
7575

76-
**Easing and motion feel.** The words you use for *how* motion feels — "snappy", "bouncy", "settles with overshoot" — map to specific eases. Spend them; they're cheap precision. See [Vocabulary](/prompting/vocabulary) for the adjective-to-ease table and [Premium motion](/prompting/motion) for the grammar that keeps a piece from reading cheap (nothing fully stops, action overlaps, the camera acts).
76+
**Easing and motion feel.** The words you use for *how* motion feels — "snappy", "bouncy", "settles with overshoot" — map to specific eases. Spend them; they're cheap precision. See [Vocabulary](/prompting/motion#words-for-how-motion-feels) for the adjective-to-ease table and [Premium motion](/prompting/motion) for the grammar that keeps a piece from reading cheap (nothing fully stops, action overlaps, the camera acts).
7777

7878
### Variants
7979

@@ -109,7 +109,7 @@ Each reuses a registry block, so the agent composes rather than hand-building fr
109109
- **Instead:** `an 8-second kinetic-type piece of one headline` — or promote it to a multi-scene video.
110110

111111
<Tip>
112-
For the six-part skeleton and the per-beat content formula these prompts share, see [Prompt anatomy](/prompting/anatomy); for the full set of run-verified examples, [Verified examples](/prompting/examples).
112+
For the six-part skeleton and the per-beat content formula these prompts share, see [Prompt anatomy](/prompting/overview#the-shape-of-a-strong-prompt); for the full set of run-verified examples, [Verified examples](/prompting/examples).
113113
</Tip>
114114

115115

‎docs/guides/music-to-video.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Every timing decision here is delegated to the track's own analysis — you desc
9696
**Wrong deliverable for the output.** Photos set to music that you'll export and post is a video; a thing you click through live is a presentation. Picking by the word "slideshow" alone builds the wrong deliverable.
9797

9898
<Tip>
99-
The music prompts here are unnarrated; ask for a voice-over if you want one. For the six-part skeleton these prompts share, see [Prompt anatomy](/prompting/anatomy); for adjectives that map to eases and transitions, [Vocabulary](/prompting/vocabulary).
99+
The music prompts here are unnarrated; ask for a voice-over if you want one. For the six-part skeleton these prompts share, see [Prompt anatomy](/prompting/overview#the-shape-of-a-strong-prompt); for adjectives that map to eases and transitions, [Vocabulary](/prompting/motion#words-for-how-motion-feels).
100100
</Tip>
101101

102102
A clause from a longer film prompt that makes the cuts follow the real beats, ready to lift:

‎docs/guides/product-launch-video.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Set the ones you care about and leave the rest to the agent.
6868
| **Length & destination** | "~45 seconds", "9:16 for TikTok" | Sweet spot is 30-90s; destination sets the aspect (16:9 embed · 1:1 feed · 9:16 Shorts) |
6969

7070
<Tip>
71-
Duration and destination are the two cheapest, highest-leverage things to state. Everything else the agent will choose well if you stay quiet — see [the specification dial](/prompting/specification-dial) for how much to delegate.
71+
Duration and destination are the two cheapest, highest-leverage things to state. Everything else the agent will choose well if you stay quiet — see [the specification dial](/prompting/overview#how-much-to-specify) for how much to delegate.
7272
</Tip>
7373

7474
### Variants

‎docs/guides/rendering.mdx‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,117 @@ ffmpeg -i out.mp4 -map_metadata -1 -c copy clean.mp4
222222
C2PA.
223223
</Note>
224224

225+
## Ask the agent for the right output
226+
227+
The flags above are what the agent sets for you. Say what you need in the request and it picks them. The defaults (MP4, 1920×1080, 30fps, `looks` quality) are deliberately good, so most of the skill is knowing when *not* to ask for more.
228+
229+
### Quality tier
230+
231+
Say the tier by name and the agent selects the matching encode preset — you don't specify CRF or encoder speed:
232+
233+
| Say this | Tier | Best for |
234+
| --- | --- | --- |
235+
| "draft" / "quick render" | `draft` | Fast iteration while you're still judging the cut |
236+
| nothing | `looks` (default, CRF 16) | Finished work: visually lossless at 1080p |
237+
| "final" / "high quality" | `delivery` | Masters you hand off |
238+
239+
The tiers trade encode time for fidelity. `looks` (the default) is already visually lossless at 1080p, so reserve `delivery` for the master you'll actually hand off, and use `draft` freely while iterating.
240+
241+
- **Avoid:** `render everything at high quality`
242+
- **Instead:** `draft renders while we iterate, then one high-quality final` — you spend the slow encode once, on the cut you've already approved
243+
244+
### Format
245+
246+
MP4 is the default and the right answer for almost everything — it plays everywhere. Ask for a different container only when the delivery target needs one:
247+
248+
> Render this as a transparent WebM overlay.
249+
250+
> Export a MOV I can drop into Premiere with the background knocked out.
251+
252+
Transparency has a container hierarchy, and the tradeoffs are real:
253+
254+
| Ask for | You get | Watch out for |
255+
| --- | --- | --- |
256+
| "transparent MOV" | ProRes 4444 with alpha | The editor-grade choice (Premiere, Final Cut, Resolve, After Effects). Files are large — expected for an editing intermediate. |
257+
| "transparent WebM" | VP9 with alpha | Small, but **only browsers decode the alpha** — every video editor renders the transparent areas black. Browser playback only. |
258+
| "PNG sequence" | Lossless RGBA frames | For compositing in After Effects / Nuke / Fusion. Largest of all. |
259+
260+
Transparency also only *means something* on a design that has empty space to see through. A lower third, a subscribe card, or a logo sting is mostly empty canvas — transparency lets it composite over other footage. A full-frame scene (edge-to-edge background, full-bleed video, a title card with its own backdrop) has nothing to be transparent; the request produces a file that looks identical to the opaque one but is larger and plays in fewer places.
261+
262+
- **Avoid:** `render my full-screen product promo as a transparent WebM`
263+
- **Instead:** `render the promo as MP4; export just the lower-third overlay as transparent WebM` — transparency belongs to the layer meant to sit *over* other footage, not the finished full-frame film
264+
265+
<DocsVideo
266+
title="Overlay spotify preview"
267+
src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/overlay-spotify-preview.mp4#t=0.1"
268+
portrait
269+
loop
270+
/>
271+
*A transparent VP9 WebM overlay previewed over a checkerboard. To verify alpha from the CLI: VP9 stores it out-of-band, so look for ALPHA_MODE=1 in ffprobe (a pix_fmt-only check false-negatives) or extract it with ffmpeg alphaextract.*
272+
273+
274+
<Note>
275+
A transparent render also depends on the composition leaving `html` / `body` backgrounds unset — the transparency comes through only where nothing is painted. The skills handle this; see the [Rendering guide](/guides/rendering#transparent-video) if you're hand-authoring an overlay.
276+
</Note>
277+
278+
### Resolution and framerate
279+
280+
1920×1080 at 30fps is the default. Both cost real time when you raise them, and both are frequently asked for out of habit rather than need.
281+
282+
**4K** is a render-time flag — the composition stays at its authored size and Chrome supersamples it to 3840×2160. That buys crisp text, SVG, and CSS at any scale, but it does *nothing* for content already locked to a pixel grid: a 1080p `<video>`, a fixed-size `<canvas>`, or a sub-4K image gain no detail from it. And it isn't free — a 4K render is roughly **4× slower per frame** and produces a **3–5× larger file**. Ask for it when the delivery surface genuinely needs it (a 4K display, a client spec), not reflexively.
283+
284+
> Render this at 4K for the trade-show display.
285+
286+
**Framerate** follows the same logic: 60fps doubles the frames the engine captures and encodes. It's worth it for fast motion graphics destined for a high-refresh screen; it's wasted on a talking-head clip or a slow title sequence.
287+
288+
- **Avoid:** `render in 4K 60fps` for a clip headed to Instagram — the platform will transcode it down anyway, and you paid the slow render for nothing
289+
- **Instead:** say nothing for social; name `4K` (or `60fps`) only when the target actually resolves it
290+
291+
<Warning>
292+
A few 4K constraints will stop a render before it starts (all grounded in the [4K guide](/guides/4k-rendering#constraints)): the target orientation must match the composition's aspect ratio, the scale must be a whole number (1080p → 4K is exactly 2×), and **4K cannot be combined with HDR** in one pass. If you need both, render HDR at composition resolution and upscale separately.
293+
</Warning>
294+
295+
### HDR
296+
297+
HDR output is **HDR10 MP4** (H.265 10-bit, BT.2020) and it is *source-driven* — the render only goes HDR when your composition actually references HDR media (video tagged BT.2020 with PQ or HLG transfer, or a 16-bit PNG). Text, gradients, and GSAP animation are not HDR sources; a composition made entirely of them has nothing to render in HDR.
298+
299+
> This composition has an HDR drone clip — render it as HDR10.
300+
301+
By default HDR is auto-detected, so with a real HDR source in the project you often need to say nothing. Force it explicitly only to override the probe:
302+
303+
- "force HDR" → forces the HDR path even without a detected HDR source
304+
- "force SDR" → forces standard range even when HDR sources are present
305+
306+
HDR is **MP4 only** (a transparent MOV/WebM request falls back to SDR) and it is **not available on Lambda** (distributed rendering is SDR-only). See the [HDR guide](/guides/hdr) for source requirements and verification.
307+
308+
### Where the render runs
309+
310+
Local rendering is the default and the right choice for the whole iteration loop. Reach for cloud rendering only when a single machine is the bottleneck:
311+
312+
> Render this on Lambda.
313+
314+
That routes to HyperFrames' AWS Lambda path, which fans the render across many parallel workers. It's the right call for renders that are **too long or too large for one host** — multi-minute videos, 4K masters, or large parallel batches — and it needs AWS credentials configured first. For dev-loop iteration, stay on local `render`; the round-trip is faster than any cloud dispatch. Lambda is SDR-only (no HDR) and bills by compute time; the [AWS Lambda guide](/deploy/aws-lambda) covers setup, cost shape, and the conservative concurrency default.
315+
316+
- **Avoid:** `set up Lambda so I can preview edits faster` — cloud dispatch adds latency to a fast local loop
317+
- **Instead:** `render the final 3-minute 4K cut on Lambda` — the workload that actually justifies fanning out
318+
319+
Lambda is not the only remote target. **HeyGen-hosted cloud rendering** ([guide](/deploy/cloud)) takes the infrastructure off your hands entirely — no AWS account to configure — and **Google Cloud Run** ([guide](/deploy/gcp-cloud-run)) is the option when your stack already lives on GCP. Name the one you want ("render this on Cloud Run"); the routing is explicit, never inferred.
320+
321+
### Preview before you commit the slow render
322+
323+
The cheapest way to avoid a wasted `high`/4K/HDR render is to judge the frame first. The habit the skills follow:
324+
325+
1. Keep `preview` running and scrub the timeline — same runtime as the render, so what you see is what you get.
326+
2. Iterate with `draft` renders when you need a real file to check.
327+
3. Only when the cut is locked, ask for the final tier / resolution / format.
328+
329+
- **Avoid:** `render the final 4K HDR master` on a cut you haven't watched end to end
330+
- **Instead:** `draft render so I can check timing` → approve → `now the 4K final`
331+
332+
<Tip>
333+
Rendering is user-gated by design — the agent pauses at preview and renders only when you approve. Use that pause to lock the cut before you pay for the expensive export.
334+
</Tip>
335+
225336
## If rendering fails
226337

227338
Run:

0 commit comments

Comments
 (0)