From fa97f9d4b7b4f401560dcc3e642267e953a2a89e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 29 Oct 2026 07:41:09 +0000
Subject: [PATCH] docs(cli): list check's audio findings with severity, trigger
 and fix (#6730)

---
 docs/packages/cli.mdx                         | 20 +++++++++++++++++++
 skills-manifest.json                          |  2 +-
 .../references/lint-validate-inspect.md       |  9 +++++++++
 3 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index d09d55193a..1561221350 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -1294,6 +1294,26 @@ last 3 s (a held end card) or time when an element marked `data-hold` is on
 screen, and it stays quiet when `sweep_static` already reports the sweep or a
 whole-composition `keepsMoving` assertion sets its own limit.
 
+#### Audio findings
+
+The `audio` section checks the clips the render mixes. It runs even when lint
+stops the browser pass, and remote sources are not fetched.
+
+| Code                           | Severity | Triggers when                                                                                                | Fix                                                                                          |
+| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `audio_source_unreadable`      | error    | The file cannot be read as audio, so the render's mix fails and the render stops.                            | Point `src` at a file with an audio track, or re-export it.                                  |
+| `audio_source_rejected`        | error    | The file has no audio track, so render stops before it starts.                                               | Point `src` at a file with audio, or remove `data-has-audio="true"` from a `<video>`.        |
+| `audio_starts_past_source_end` | warning  | `data-media-start` is at or past the file's length, so the clip plays nothing.                               | Lower `data-media-start` below the file's length.                                            |
+| `audio_clip_silent`            | warning  | The file is silent for the whole part the clip plays.                                                        | Check the file has sound there, or move `data-media-start` to where it does.                 |
+| `audio_none`                   | info     | No clip plays audio and no unmuted `<video>` has an audio track.                                             | Nothing for a silent film; otherwise add the `<audio>`.                                      |
+| `audio_check_unavailable`      | info     | The audio check itself failed, and the message says why, so the clips were not checked.                      | Re-run; if it repeats, run `hyperframes doctor`.                                             |
+| `audio_src_not_found`          | error    | An `<audio src>` names a file that is not in the project, so the render is silent. Reported by `lint`.        | Add the file or fix the path.                                                                |
+
+Each file is probed once, with the same audio probe render uses. The check runs
+alongside the browser pass, up to four files at a time. A clip longer than 3 s
+is first sampled at three 1-second spots and decoded in full only if all three
+are silent.
+
 #### Mark intentional layout choices
 
 When the audit is wrong because the layout is deliberate, say so in the HTML and
diff --git a/skills-manifest.json b/skills-manifest.json
index 07f5269ca4..699936200e 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -10,7 +10,7 @@
       "files": 77
     },
     "hyperframes-cli": {
-      "hash": "64c80027b1239a9f",
+      "hash": "19cd51ab0ac43edc",
       "files": 13
     },
     "hyperframes-registry": {
diff --git a/skills/hyperframes-cli/references/lint-validate-inspect.md b/skills/hyperframes-cli/references/lint-validate-inspect.md
index 55cbaa89ee..a473b95c78 100644
--- a/skills/hyperframes-cli/references/lint-validate-inspect.md
+++ b/skills/hyperframes-cli/references/lint-validate-inspect.md
@@ -53,6 +53,15 @@ One command, one Chrome boot. `check` runs the linter first and skips the browse
   - `text_below_floor`: text under 2.6% of the frame's short side (28 px on 1080) held 0.5 s or more, one finding per file listing every element.
   - `first_frame_empty`: frame 0 paints nothing but the background (no text, image, video, canvas or svg), or an opaque element covers every other clip and the message names it; it is the thumbnail on social players.
   - `film_silent`: a film over 15 s with no unmuted `<audio>` or audible `<video>`.
+- **Audio**: the clips the render mixes, in the report's `audio` section. It runs even when lint stops the browser pass. Remote sources are not fetched.
+  - `audio_source_unreadable` (error): the file cannot be read as audio, so the render's mix fails and the render stops. Point `src` at a file with an audio track, or re-export it.
+  - `audio_source_rejected` (error): the file has no audio track, so render stops before it starts. Point `src` at a file with audio, or remove `data-has-audio="true"` from a `<video>`.
+  - `audio_starts_past_source_end` (warning): `data-media-start` is at or past the file's length, so the clip plays nothing. Lower `data-media-start` below the length.
+  - `audio_clip_silent` (warning): the file is silent for the whole part the clip plays. Check the file has sound there, or move `data-media-start` to where it does.
+  - `audio_none` (info): no clip plays audio and no unmuted `<video>` has an audio track. Fine for a silent film; otherwise add the `<audio>`.
+  - `audio_check_unavailable` (info): the audio check itself failed (the message says why), so the clips were not checked. Re-run; if it repeats, run `hyperframes doctor`.
+  - `audio_src_not_found` (error, from `lint`): an `<audio src>` names a file not in the project, so the render is silent. Add the file or fix the path.
+  - Cost: each file is probed once, with the same audio probe render uses. The check runs alongside the browser pass, up to four files at a time. A clip longer than 3 s is first sampled at three 1-second spots and decoded in full only if all three are silent.
 
 Every finding carries a selector, the element's `data-*` identity, the composition source file, a bbox, and the sample time: jump straight from the JSON to the HTML you must edit and re-run.