mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(studio): the copied render command carries no composition text a shell can run The Variables panel's "Copy render command" put every variable value inline, quoted for POSIX shells only. A shared project's author chooses those values, so in PowerShell, cmd.exe (including npx.cmd's re-parse) or fish a default such as `x'; calc.exe; '` ran as commands when the command was pasted. The command is now fixed text: `npx hyperframes render -c <composition> --variables-file .hyperframes/render-variables.json`. Copying it saves the previewed values to that file through a new PUT /projects/:id/render-variables route, which refuses a link standing in for .hyperframes and replaces, rather than writes through, a link at the file itself. A composition path that is not one plain word in every shell (letters, digits, `_ . / -`) gets no command. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(scripts): the comment checker skips a template nested in a substitution stripLiterals ended a template literal at the first backtick, including one that opens a nested template inside `${...}`. On a line such as `'${value.replace(/'/g, `'\\''`)}'` that left a backtick unmatched, so scanCLike read the rest of the file as one template and counted none of its comments. The ratchet then measured VariablesPanel.tsx on main at 1 comment line instead of 31 and failed any change that removed that line. A `${...}` is now scanned as code: strings, regexes and templates inside it are skipped, and its closing brace returns to the outer template. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(studio-server): read the replaced render-variables record through one no-follow descriptor The link test checked the record with lstat and then read it by path, two lookups CodeQL reports as a file-system race. Opening it once with O_NOFOLLOW fails if a link is still there and reads the file that open checked. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
153 lines
7.2 KiB
Plaintext
153 lines
7.2 KiB
Plaintext
---
|
|
title: "Captions, assets and variables"
|
|
description: "In the browser editor: import and reuse media, add Catalog visuals, restyle caption words, and turn values into variables for templates."
|
|
sidebarTitle: "Captions, assets and variables"
|
|
---
|
|
|
|
Use **Assets** for media files. Use **Catalog** for reusable visual scenes and components.
|
|
|
|
<div className="not-prose my-7 max-w-2xl overflow-hidden rounded-xl border border-zinc-200 bg-zinc-950 dark:border-zinc-800">
|
|
<video
|
|
className="aspect-video w-full object-cover"
|
|
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-assets-catalog-loop-v1.mp4#t=0.1"
|
|
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-assets-catalog-loop-v1.jpg"
|
|
autoPlay
|
|
muted
|
|
loop
|
|
playsInline
|
|
preload="metadata"
|
|
/>
|
|
<div className="px-3 py-2 text-sm text-zinc-600 dark:text-zinc-400">
|
|
Import project media, then add a compatible Catalog scene at the playhead.
|
|
</div>
|
|
</div>
|
|
|
|
## Import an asset
|
|
|
|
1. Open **Assets**.
|
|
2. Choose **Import media**, or drop files into the panel.
|
|
3. Preview it before adding it to the project.
|
|
4. Drag it to the timeline or use it from the relevant inspector control.
|
|
|
|
Keep clear filenames. `product-dashboard-dark.png` is easier to reuse than `Screenshot 42.png`.
|
|
|
|
## Reuse project assets
|
|
|
|
**This project** contains the files available to the open project. **All projects** is a read-only
|
|
index of the global `~/.media` cache, where resolved media can be found again across projects. It is
|
|
not a file manager, so files cannot be deleted or replaced from that view.
|
|
|
|
If a large video is still preparing a preview or proxy, wait for that process before judging playback performance.
|
|
|
|
## Add a Catalog item
|
|
|
|
Open **Catalog**, search or pick a category (**Captions**, **Code Animations**, **VFX**, **Transitions**, **Effects**)
|
|
and preview what you need. Choose **Add** where it's offered to place it at the playhead, or **Ask agent** to copy a
|
|
ready request for your agent, which adapts the item to your composition. Then swap the sample content for yours and
|
|
match the project's timing and look.
|
|
|
|
Browse the full [Catalog](/catalog) when you want to compare categories and individual examples.
|
|
|
|
<Tip>
|
|
Reusable does not mean finished. Remove sample content and decorative motion that does not support
|
|
your story.
|
|
</Tip>
|
|
|
|
## Edit captions
|
|
|
|
When a composition has captions, the editor switches to caption editing: click a word on the frame, or find it in the
|
|
caption track under the preview.
|
|
|
|
<Frame caption="A selected word connects the canvas, caption rail, and the controls that the browser editor currently saves.">
|
|
<img
|
|
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio-captions-panel-v1.jpg"
|
|
alt="HyperFrames browser editor with one caption word selected, word blocks in the caption rail, and position and transform controls"
|
|
/>
|
|
</Frame>
|
|
|
|
### What you can change here
|
|
|
|
Select a word (Shift-click for more), then drag, resize or rotate it on the frame. Arrow keys nudge it by 1 pixel,
|
|
Shift + arrow by 10. Color, opacity, font size, weight and family are in the panel. These edits are saved for you, in
|
|
`caption-overrides.json`, a moment after you make them.
|
|
|
|
### What to ask the agent for
|
|
|
|
Wording, timing, how words are grouped into lines and the caption style itself live in the caption source, not in
|
|
the editor. Ask your agent ("break the captions into two-word groups", "fix the spelling of HeyGen") or change the
|
|
source.
|
|
|
|
Then watch once with sound and once muted: names and numbers right, nothing covering a face or a button, and the last
|
|
caption clearing cleanly. For reusable styles, browse [caption components](/catalog/components/caption-highlight).
|
|
|
|
## Use variables
|
|
|
|
Variables let one project produce many versions without rebuilding its layout or animation.
|
|
|
|
<Frame caption="The current Variables panel previews values beside the real composition.">
|
|
<img
|
|
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio-variables-panel-v1.jpg"
|
|
alt="HyperFrames browser editor showing a composition beside the Variables panel with Title, Subtitle, and Background inputs"
|
|
/>
|
|
</Frame>
|
|
|
|
### Create one reusable input
|
|
|
|
The quickest path starts from the canvas:
|
|
|
|
1. Select the element.
|
|
2. Open **Variables** in the right panel.
|
|
3. Bind the text, media source, text color, background, or font property.
|
|
4. Create a new variable or choose a compatible existing one.
|
|
|
|
Before binding to an existing variable, the browser editor shows its saved default, using the font name or image URL for object values.
|
|
|
|
For a value that is not tied to the selected element, click **Add variable**. The browser editor supports string, number, color, boolean, enum, font, and image variables. Number variables can include minimum, maximum, and step values; enums can define their allowed options.
|
|
|
|
Name the input by meaning—`customerName`, `headline`, or `brandColor`—rather than by its position in the design.
|
|
|
|
### Preview without changing the template
|
|
|
|
Change a value in the Variables panel to preview that version immediately. The preview is an override: it does not replace the saved default.
|
|
|
|
The panel tells you whether you are previewing defaults or custom values. Use **Reset** to clear all preview overrides. When a scalar preview should become the new default, use **Set default**.
|
|
|
|
Use **Edit** to change a variable's label, description, or saved default. For font and image objects, **Default** edits the font name or image URL. Saving keeps the font source, image alt text and fit, and any other stored metadata, including when you change only the label or description.
|
|
|
|
<Note>
|
|
Variables from other compositions are listed separately. You can edit their declarations, but
|
|
their values are not live-previewed in the active composition.
|
|
</Note>
|
|
|
|
### Hand the project off
|
|
|
|
At the bottom of the panel, **Use this template** can copy either:
|
|
|
|
- the effective values as JSON;
|
|
- a ready-to-run `npx hyperframes render -c <composition> --variables-file .hyperframes/render-variables.json` command.
|
|
|
|
Copying the command also saves the values you are previewing to `.hyperframes/render-variables.json`, so run it from the project folder. The values travel in that file rather than in the command, so no value can be read as shell syntax in bash, zsh, fish, PowerShell or Command Prompt. If the composition's file name has characters other than letters, digits, `_`, `.`, `/` and `-`, the browser editor offers only the JSON; rename the file to get the command.
|
|
|
|
This keeps the values you just reviewed attached to the render request instead of asking the next person to reconstruct them.
|
|
|
|
### Test the fallback
|
|
|
|
A useful template survives realistic variation. Before handing it off, test:
|
|
|
|
- long and short names or headlines;
|
|
- image aspect ratios;
|
|
- color contrast;
|
|
- number formatting;
|
|
- missing optional values.
|
|
|
|
For the schema, HTML bindings, and batch-render examples, read [Variables](/concepts/variables).
|
|
|
|
## Related topics
|
|
|
|
- [Work with media](/guides/video-components)
|
|
- [Browse the Catalog](/catalog)
|
|
- [Add captions to a video](/guides/captions-and-recuts)
|
|
- [Voice, sound and captions](/guides/voice-and-audio)
|
|
- [Understand the variables contract](/concepts/variables)
|
|
- [Render variable-driven versions](/guides/rendering#batch-and-cloud-work)
|