From acc4ba6790f10a3919bd5f2a732606ee49231554 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Tue, 10 Nov 2026 19:32:55 -0500
Subject: [PATCH 1/2] docs(variables): say what can be a variable, including a
 video or sound per account

---
 docs/concepts/variables.mdx | 71 ++++++++++++++++++++++++++++++-------
 1 file changed, 59 insertions(+), 12 deletions(-)

diff --git a/docs/concepts/variables.mdx b/docs/concepts/variables.mdx
index bc058cff21f..d6e7e451f61 100644
--- a/docs/concepts/variables.mdx
+++ b/docs/concepts/variables.mdx
@@ -60,20 +60,23 @@ Variables live on the composition declaration:
 ></html>
 ```
 
-Supported declared types are:
+## What can be a variable
 
-| Type      | Good for                               |
-| --------- | -------------------------------------- |
-| `string`  | Text or a media path                   |
-| `number`  | Counts, positions, sizes, or strengths |
-| `color`   | Approved color choices                 |
-| `boolean` | On or off                              |
-| `enum`    | One value from an approved list        |
-| `font`    | A font-family choice                   |
-| `image`   | An image path or image value           |
+A variable has one of seven kinds. The kind sets the control the browser editor
+shows and what a render accepts for it.
 
-The type lets the browser editor show the right control and lets rendering catch invalid
-values.
+| Kind      | What it holds                                  | Example                          |
+| --------- | ---------------------------------------------- | -------------------------------- |
+| `string`  | Text, or a link to a file                      | A customer name, a video link    |
+| `number`  | A count, position, size, or strength           | Seats on a plan, a speed         |
+| `color`   | One approved color                             | A brand accent                   |
+| `boolean` | On or off                                      | Show the badge                   |
+| `enum`    | One value from a list you approved             | `light` or `dark`                |
+| `font`    | A font family                                  | The headline typeface            |
+| `image`   | A link to a picture                            | A customer logo                  |
+
+Video and sound have no kind of their own. Declare the link as a `string`, then
+bind it to a `<video>` or `<audio>` element (next section).
 
 ### Say what a slot means, not where it sits
 
@@ -137,6 +140,50 @@ const { featured = false } = window.__hyperframes.getVariables();
 document.querySelector(".badge").hidden = !featured;
 ```
 
+## Swap in a video or a sound
+
+Bind a link to a media element with `data-var-src`. Keep a `src` on the element
+as the placeholder:
+
+```html compositions/welcome.html
+<html
+  data-composition-variables='[
+  {"id":"welcomeClip","type":"string","label":"Welcome clip","default":"assets/placeholder.mp4"}
+]'
+>
+  <video
+    data-var-src="welcomeClip"
+    src="assets/placeholder.mp4"
+    data-start="0"
+    data-track-index="0"
+    playsinline
+  ></video>
+</html>
+```
+
+Render the same saved project once per account by passing each account's clip:
+
+```bash
+npx hyperframes render \
+  --variables '{"welcomeClip":"https://example.com/clips/northstar.mp4"}' \
+  --output northstar.mp4
+```
+
+The film takes the length and the sound of the clip you pass, not the
+placeholder's. A 3 second placeholder swapped for a 5 second clip renders 5
+seconds, and that clip's sound is mixed once.
+
+Limits:
+
+- `data-var-src` works on `<video>`, `<audio>`, `<img>`, and `<source>`. On any
+  other element it is ignored.
+- The link must be a relative path or an `http`, `https`, or `blob` URL. Any
+  other value, including a `data:` video, is dropped and the placeholder
+  renders instead, with a warning.
+- A clip inside a nested composition that receives its own `data-variable-values`
+  is resolved by the browser during the render, not before it.
+- The root composition's length follows the clips it plays. It is not a variable.
+
 ## Give each nested composition different values
 
 A parent can reuse the same composition several times:

From 8fd91d50641177637a08d1dce2d9cd8f45b0a2b2 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Tue, 10 Nov 2026 19:37:51 -0500
Subject: [PATCH 2/2] docs(variables): render the per-account example from
 index.html and keep the outline

---
 docs/concepts/variables.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/concepts/variables.mdx b/docs/concepts/variables.mdx
index d6e7e451f61..81e3ffb9233 100644
--- a/docs/concepts/variables.mdx
+++ b/docs/concepts/variables.mdx
@@ -60,7 +60,7 @@ Variables live on the composition declaration:
 ></html>
 ```
 
-## What can be a variable
+### What can be a variable
 
 A variable has one of seven kinds. The kind sets the control the browser editor
 shows and what a render accepts for it.
@@ -76,7 +76,7 @@ shows and what a render accepts for it.
 | `image`   | A link to a picture                            | A customer logo                  |
 
 Video and sound have no kind of their own. Declare the link as a `string`, then
-bind it to a `<video>` or `<audio>` element (next section).
+bind it to a `<video>` or `<audio>` element, as in [Swap in a video or a sound](#swap-in-a-video-or-a-sound).
 
 ### Say what a slot means, not where it sits
 
@@ -145,7 +145,7 @@ document.querySelector(".badge").hidden = !featured;
 Bind a link to a media element with `data-var-src`. Keep a `src` on the element
 as the placeholder:
 
-```html compositions/welcome.html
+```html index.html
 <html
   data-composition-variables='[
   {"id":"welcomeClip","type":"string","label":"Welcome clip","default":"assets/placeholder.mp4"}
@@ -177,7 +177,7 @@ Limits:
 
 - `data-var-src` works on `<video>`, `<audio>`, `<img>`, and `<source>`. On any
   other element it is ignored.
-- The link must be a relative path or an `http`, `https`, or `blob` URL. Any
+- The link must be a path or an `http`, `https`, or `blob` URL. Any
   other value, including a `data:` video, is dropped and the placeholder
   renders instead, with a warning.
 - A clip inside a nested composition that receives its own `data-variable-values`