From c49fea2e0c4caaa7c4329493cdd5112581addc06 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Wed, 5 Aug 2026 10:45:32 -0700
Subject: [PATCH] docs: complete the media-start layer map + fix the third page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per Rames: add the engine audio mixer (audioMixer.ts:350 -> ffmpeg -ss) to the
media-start-only readers — it's the live path that makes a lone data-playback-start
a shipped output bug (trimmed picture over untrimmed audio). 'Set one' isn't enough;
give the element-kind rule: <video>/<audio> use data-media-start, nested composition
uses data-playback-start (Studio writes it; it's the child-timeline offset). Also fix
editing-existing-videos.mdx, which offered both names as interchangeable for front
trim of a clip — the exact kind where they aren't.
---
 docs/prompting/editing-existing-videos.mdx | 2 +-
 docs/reference/html-schema.mdx             | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/prompting/editing-existing-videos.mdx b/docs/prompting/editing-existing-videos.mdx
index 37d23c19d..42cde5150 100644
--- a/docs/prompting/editing-existing-videos.mdx
+++ b/docs/prompting/editing-existing-videos.mdx
@@ -18,7 +18,7 @@ Every timeline verb resolves to a `data-*` attribute or an inline style. This is
 | "start scene 2 later / earlier" | Move | `data-start` |
 | "put the captions on top of the video" | Restack | `data-track-index` + inline `z-index` |
 | "end the logo sooner" | Trim (right) | `data-duration` |
-| "skip the first second of the clip" | Trim (front, media only) | `data-media-start` / `data-playback-start` |
+| "skip the first second of the clip" | Trim (front, media only) | `data-media-start` |
 | "make scene 2 two seconds long" | Retime | `data-duration` (and the GSAP timeline length) |
 | "the audio bed is too loud" | Level | `data-volume` |
 
diff --git a/docs/reference/html-schema.mdx b/docs/reference/html-schema.mdx
index c9c6495a4..05e88af7b 100644
--- a/docs/reference/html-schema.mdx
+++ b/docs/reference/html-schema.mdx
@@ -122,7 +122,7 @@ Audio has no visual lifecycle.
 
 | Attribute | Applies to | Meaning |
 | --- | --- | --- |
-| `data-media-start` / `data-playback-start` | Video, audio, nested composition | Offset into the source file, used by trim and split. The two names are read by different layers, and not all of them agree. **Read only `data-media-start`:** the timing compiler, the HTML parser, the producer's audio extraction, and `hyperframes validate`. **Read `data-playback-start` first, falling back to `data-media-start`:** the runtime player, Studio, and `hyperframes snapshot` — and Studio also writes `data-playback-start` for nested compositions and any element authored with it. Set **one** value; authoring both is what makes these two groups diverge. |
+| `data-media-start` / `data-playback-start` | Video, audio, nested composition | Offset into the source file, used by trim and split. Two groups of readers disagree, so the right name depends on the element. **Read only `data-media-start`:** the timing compiler, the HTML parser, `hyperframes validate`, and the engine's audio mixer (which feeds ffmpeg `-ss`). **Read `data-playback-start` first, falling back to `data-media-start`:** the runtime player, Studio (which also writes it), and `hyperframes snapshot`. Because the audio mixer reads only `data-media-start`, a `<video>` authored with just `data-playback-start` renders a trimmed picture over untrimmed audio. So set the name by kind: **`<video>` / `<audio>` → `data-media-start`**; **nested composition → `data-playback-start`** (Studio writes it, and it is the [child-timeline offset](/concepts/compositions)). |
 | `data-playback-rate` | Video, audio, nested composition | Playback multiplier from `0.1` to `5` |
 | `data-volume` | Video and audio | Static volume from `0` to `1` |
 | `data-has-audio="true"` | Video | Declares that the video contributes audio |