From 0eca7b1e0aef831bbab1265395f942378468afc0 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 22 Aug 2026 05:49:35 -0700
Subject: [PATCH] docs(audio): document the audio effects system (#3420)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(audio): document the audio effects system

The effects feature had no documentation at all — the only mentions anywhere in
docs/ were changelog entries. This adds the three pages the color-grading feature
already has, one per audience, and closes a gap in the existing audio guide.

- prompting/audio-effects — a new Level 5 chapter on asking for a mix in
  symptoms rather than in filters, with the voiceover carve as the headline, the
  level-before-depth check, groups, and the three requests that have no honest
  answer (de-essing, noise removal, tone matching).
- studio/audio-effects — the rack, presets by symptom, the carve module, groups,
  the deliberately asymmetric mute/solo, automation lanes, and troubleshooting.
- reference/audio-effects — the contract: all four attributes, every effect and
  parameter range, why some parameters cannot be automated, the 19 presets, the
  five jobs and five one-knob profiles, carve semantics, the group model, the
  render bus, preview/render parity, and the three lint rules.

Also points the existing "duck music under important speech" advice in
guides/voice-and-audio at the carve, which does that properly and was never
named there.

Facts verified against source rather than the shipped skill prose: the panel
section is "Audio FX" (the neighbouring "Effects" section is visual effects, and
an earlier draft of this page named the wrong one), MAX_AUTOMATION_POINTS is 512,
fromPreset carries a preset id rather than a boolean, the leveller targets the
track's own 80th percentile, group mute reaches the render while solo never
leaves Studio, and the CLI carve currently writes clip ids.

No screenshots in this pass, and no placeholders for them either — the pages
carry concrete markup and tables instead. Screenshots of the rack, the carve
module, and a group row would each earn their place later.

mint validate and mint broken-links both pass.

* docs(audio): give audio its own Studio group, split by task

Review feedback: the audio page did not belong in Studio / Edit. That group is
already one task per page — canvas, timeline, animation, captions — and a single
page covering the rack, the carve, groups, and automation lanes was four tasks
bundled together and dropped in beside them.

Studio now has an Audio group holding four task pages:

- Effects and presets — the rack, presets by symptom, adding single effects in a
  working order, the one-knob controls, Even Out Levels
- Voiceover carve — its own page, because it is the feature people come for
- Groups, mute, and solo — including why mute reaches the export and solo cannot
- Automation lanes — drawing envelopes, the shape menu, and which parameters
  cannot move at all

Not a new top-level tab: the tabs here are audience-scoped (Guides, Studio,
Catalog, Developers), so a feature tab would be the only one of its kind and
would strand the prompting chapter out of its Level 5 sequence and the reference
page out of Developers.

Repointed the deep link in guides/voice-and-audio at the carve's own page.

Lane interactions verified in source before documenting: the right-click menu
offers Ramp up, Ramp down, Swell, Dip, and Simplify (which needs three points).
Deliberately not documented: "clicking a lane label reveals it in the rack",
which is not on main.

mint validate and mint broken-links both pass.

* docs(audio): fix the four review blockers

All four verified in source before fixing; the review was right on every count.

**The registry was incomplete.** `pitchshift` ships at `audioFx.ts:509-535`
(`semitones` −12–12, `mix` 0–1, worklet-backed so neither automatable) and was
missing entirely — sixteen effects, not fifteen. It also joins the worklet list,
so five effects expose no automatable parameters rather than four.

**Three presets were missing.** `chipmunk`, `giant`, and `monster` ship at
`audioFxPresets.ts:336-357`, all built on `pitchshift`. Twenty-two presets, and
Character holds ten. Fixed in both the reference table and the Studio list.

**The copyable markup contradicted the warning above it.** The page said
`carve.mjs` only finds double-quoted attributes and then gave three
single-quoted examples — copying the chain example would make a later carve miss
the existing chain and overwrite it. All three are now double-quoted with
`&quot;`, each followed by its unescaped reading so it stays legible.

**The attribute table over-claimed.** `data-audio-group` is a plain id, not JSON,
and is ignored on `<video>`; the other three also live on `<hf-audio-group>` for
a group. The table now carries shape and valid host per attribute.

**The automation contract was wrong on two axes.** A clip lane's `t` is
clip-relative but a GROUP lane's is composition time, because a group has no
`data-start` (`webAudioTransport.ts:337-342`, `audioMixer.ts:1311-1344`) — both
pages now split the two clocks. And `volume` is not 0–1: the ceiling is
`MAX_AUDIO_GAIN`, +12 dB or about 3.981 (`audioGain.ts:8-9`), so a boosting lane
is valid and documented.

**Current-main drift.** #3416 is merged, so the CLI now records the voices'
shared group when it is safe and falls back to clip ids when that group contains
the bed or a music/SFX member. Documented, including why neither refusal shows
up on the run that writes it, and rebased onto main.

mint validate and mint broken-links both pass.

* docs(audio): name the real add-menu family, and finish propagating pitchshift

Second review round. All three findings were my own incomplete propagation — I
corrected the reference for `pitchshift` last round and left the reader-facing
pages behind it.

**The add-menu family is `Time`, not `Space`.** `propertyPanelFxAddMenu.tsx:22-28`
labels the four groups Filters / Dynamics / Non-linear / Time, and the time group
holds pitchshift, delay, chorus, phaser, and reverb. The Studio page sent readers
looking for a group that does not exist. It is now a table naming the family and
its contents, and the reference's "Time — space and width" heading is retitled,
since that description stopped covering the family the moment pitch shift joined
it.

Also from the same file: the menu offers the named jobs in place of a bare
`peaking`, because picking `peaking` is picking a machine and leaving the real
decision — which range — for afterwards. Worth saying on the task page.

**Pitch shift was missing from both no-automation lists** that a reader actually
follows — `studio/audio-automation` and, unflagged but the same defect, the
prompting chapter. Five worklet effects in all four places now. Called out
explicitly on the Studio page, because a rising pitch is exactly the thing
someone reaches for a lane to do, and the lane will not report that it cannot.

**Narrowed the group-metadata sentence.** "The other three are JSON, and on a
group they live on `<hf-audio-group>`" swept in `data-fx-carve`, contradicting the
table directly above it. Only `data-fx-chain` and `data-automation` are group
metadata.

mint validate and mint broken-links both pass.
---
 docs/docs.json                     |  15 +-
 docs/guides/voice-and-audio.mdx    |   5 +-
 docs/prompting/audio-effects.mdx   | 177 +++++++++++
 docs/prompting/media-and-audio.mdx |   4 +-
 docs/reference/audio-effects.mdx   | 472 +++++++++++++++++++++++++++++
 docs/studio/audio-automation.mdx   | 119 ++++++++
 docs/studio/audio-effects.mdx      | 168 ++++++++++
 docs/studio/audio-groups.mdx       | 105 +++++++
 docs/studio/voiceover-carve.mdx    | 124 ++++++++
 9 files changed, 1184 insertions(+), 5 deletions(-)
 create mode 100644 docs/prompting/audio-effects.mdx
 create mode 100644 docs/reference/audio-effects.mdx
 create mode 100644 docs/studio/audio-automation.mdx
 create mode 100644 docs/studio/audio-effects.mdx
 create mode 100644 docs/studio/audio-groups.mdx
 create mode 100644 docs/studio/voiceover-carve.mdx

diff --git a/docs/docs.json b/docs/docs.json
index 9d6e64aee..91a3048fd 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -126,7 +126,8 @@
               {
                 "group": "Level 5 — Voice and sound",
                 "pages": [
-                  "prompting/media-and-audio"
+                  "prompting/media-and-audio",
+                  "prompting/audio-effects"
                 ]
               },
               {
@@ -215,6 +216,15 @@
               "studio/captions"
             ]
           },
+          {
+            "group": "Audio",
+            "pages": [
+              "studio/audio-effects",
+              "studio/voiceover-carve",
+              "studio/audio-groups",
+              "studio/audio-automation"
+            ]
+          },
           {
             "group": "Build and reuse",
             "pages": [
@@ -812,7 +822,8 @@
             "group": "Composition reference",
             "pages": [
               "reference/html-schema",
-              "reference/color-grading"
+              "reference/color-grading",
+              "reference/audio-effects"
             ]
           },
           {
diff --git a/docs/guides/voice-and-audio.mdx b/docs/guides/voice-and-audio.mdx
index 3fca39fc1..848aec3b6 100644
--- a/docs/guides/voice-and-audio.mdx
+++ b/docs/guides/voice-and-audio.mdx
@@ -99,7 +99,10 @@ graphic overlays, and an actual change to the spoken edit.
 
 - Keep voice clear above music.
 - Duck music under important speech instead of reducing the whole track
-  equally.
+  equally. A [voiceover carve](/studio/voiceover-carve)
+  does this properly: it takes only the bands the voice occupies out of the
+  music, so the bed keeps its low end and its top instead of going limp for the
+  whole voiceover.
 - Use sound effects for meaningful events, not every movement.
 - Avoid cutting words, breaths, or reverb tails accidentally at scene
   boundaries.
diff --git a/docs/prompting/audio-effects.mdx b/docs/prompting/audio-effects.mdx
new file mode 100644
index 000000000..a95af7cff
--- /dev/null
+++ b/docs/prompting/audio-effects.mdx
@@ -0,0 +1,177 @@
+---
+title: Audio effects and mixing
+description: "Ask for a mix in symptoms rather than in filters — make music step out of the way of narration, clean a voice, and know which requests have no honest answer."
+---
+
+The last chapter gave your video a voice. This one makes the voice and everything
+around it *listenable*.
+
+Audio work is where prompts go wrong in a specific way: it is tempting to name
+the machine. "Add a high-pass at 80 Hz with a Q of 0.7" is a real instruction, and
+it is worse than the request that produced it, because it commits you to a fix
+before anyone has established the problem. The mix is stored as effects on each
+track — filters, dynamics, character, space, and envelopes that move any of them
+over time — and the agent reaches into that toolbox for you. Your job is to
+describe the symptom accurately.
+
+## Say what it sounds like, not what to add
+
+Every effect in the rack exists to answer a complaint. Name the complaint.
+
+```text
+The narration sounds muffled, like it's behind cardboard. Fix it.
+```
+
+```text
+The voice sounds amateur — clean it up but don't make it sound processed.
+```
+
+```text
+There's a hum under the interview audio the whole way through.
+```
+
+Each of those lands on a specific, small change: a cut at 250 Hz, the
+`voice-clean` chain, a high-pass under the voice. You do not have to know which —
+and if you name the wrong mechanism, you get the wrong mechanism applied
+confidently.
+
+This matters more than it does for picture work, because **you can hear a mix and
+the agent cannot**. A prompt describing a sound is evidence. A prompt naming a
+filter is a guess wearing evidence's clothes.
+
+## The one request worth learning by name
+
+Music under narration is the single most common audio problem, and the reflex fix
+is wrong.
+
+Ducking the whole music track works and costs the music all of its presence for
+the entire voiceover — it goes limp for as long as anyone is talking. The voice
+does not need the whole spectrum, though. It needs the few bands it actually
+occupies. Taking only those out of the music is called a **carve**, and it keeps
+the low end and the top, so the bed is still music while the voice stays
+intelligible.
+
+Ask for it in those terms:
+
+```text
+Put the music under the narration properly — carve it so the voice stays clear
+without the track going limp.
+```
+
+```text
+The music is fighting the voiceover. Make room for the voice in the music
+rather than just turning the music down.
+```
+
+Two things are worth knowing so you can judge the result:
+
+- **It follows the speech.** Silence leaves the music alone; a loud passage pushes
+  it to full depth. It is not a fixed dip held through every pause.
+- **It lives on the music**, and names the voices it makes room for. If someone
+  tells you they carved the voice track, that is a bug rather than a taste
+  decision.
+
+If it comes back and the music sounds *hollow* rather than simply quieter, say so
+in exactly that word — it means the depth is too high, and it is the one failure
+mode with an obvious sound:
+
+```text
+Too far — the music sounds notched now. Back it off.
+```
+
+## Ask for levels before asking for more depth
+
+A carve cannot fix music that is simply louder than the voice. When narration is
+buried, the useful instruction is about **level**, not about spectrum:
+
+```text
+Check the actual loudness of the voiceover against the music before touching
+the carve — the voice may just be quieter than the bed.
+```
+
+Machine-generated speech commonly arrives far below a mastered music track. That
+gap is arithmetic, not taste, and no amount of carving closes it. Asking for the
+measurement first turns one round of guessing into a number.
+
+## Group the things that belong together
+
+Five narration clips want one set of effects, one fader, and one mute — not five
+copies that drift apart as you edit. Say so:
+
+```text
+Group all the narration clips as one voiceover group, then carve the music
+against that group.
+```
+
+That phrasing is worth the extra clause. A carve pointed at individual clips has
+to list every one of them, and it stays right only until you add another — the
+sixth clip plays outside the carve's awareness and the music silently fails to
+duck under it. A carve pointed at a *group* picks up whatever is in the group at
+the time it runs.
+
+Use groups for sound effects too, when there are more than a couple. One place to
+turn all of them down is worth more than precise individual levels you will never
+revisit.
+
+## Ask for movement when a static setting will not do
+
+Anything that should change over the video's length is an envelope, and you ask
+for it by describing the shape in time:
+
+```text
+Fade the music out over the last three seconds.
+```
+
+```text
+Bring the ambience up while the wide shot is on screen, then pull it back
+under the interview.
+```
+
+One caveat worth carrying: a few effects cannot move over time at all — the
+compressor, limiter, gate, bitcrush, and pitch shift are configured whole rather
+than knob-by-knob. If you ask for a compressor that tightens as a scene builds, the
+honest answer is a level stage moving in front of it instead. An agent that
+quietly writes an envelope on one of those has written something inert, so if a
+requested change does nothing audible, that is the first thing to suspect.
+
+## Three requests with no honest answer
+
+Naming a gap is more useful than accepting the nearest preset and calling it the
+thing.
+
+**De-essing.** Sharp `s` sounds need a detector faster than anything in the
+toolbox. The nearest fix is a narrow cut in the 5–9 kHz range, swept to find
+where that particular voice spits. It is always on, so it costs a little air on
+every word. That trade is usually worth it — but ask for it knowing it is a
+trade:
+
+```text
+The s sounds are spitting. I know there's no real de-esser — put a narrow cut
+where this voice actually sibilates and tell me what it cost.
+```
+
+**Noise removal.** A gate closes the gaps between phrases; the hiss *underneath*
+the words is untouched by anything available. A source with audible hiss needs a
+better source, and an agent telling you so is being accurate rather than lazy.
+
+**Matching one voice to another.** There is no match-curve tool. Two takes can be
+brought closer by hand with an EQ, which is predictable in a way a derived curve
+would not be — but it is hand work, and worth asking for as such.
+
+## Describe the whole mix once, at the end
+
+Individual fixes accumulate into something nobody has judged as a whole. One
+closing instruction is worth more than three more adjustments:
+
+```text
+Render an audio-only pass and check the mix end to end: voice clear through
+the loudest musical moment, effects where the action is, nothing surprising
+at the open, and the music finishing on purpose rather than at the file edge.
+```
+
+Audio problems are easier to notice when the picture is not competing for
+attention. Listening once without watching catches things twenty prompt rounds
+will not.
+
+*Next: [Design systems and brand](/prompting/design-systems) — pointing the agent
+at a source of brand truth instead of describing a vibe.*
diff --git a/docs/prompting/media-and-audio.mdx b/docs/prompting/media-and-audio.mdx
index 0b2b7b118..027a43bf7 100644
--- a/docs/prompting/media-and-audio.mdx
+++ b/docs/prompting/media-and-audio.mdx
@@ -243,8 +243,8 @@ prompt language you can lift for your own video:
 />
 *That clause, rendered — the region cut from the finished film.*
 
-*Next: [Design systems and brand](/prompting/design-systems) — pointing the
-agent at a source of brand truth instead of describing a vibe.*
+*Next: [Audio effects and mixing](/prompting/audio-effects) — making the voice,
+music, and effects you just placed sit together.*
 
 ## Related topics
 
diff --git a/docs/reference/audio-effects.mdx b/docs/reference/audio-effects.mdx
new file mode 100644
index 000000000..df00a9c5f
--- /dev/null
+++ b/docs/reference/audio-effects.mdx
@@ -0,0 +1,472 @@
+---
+title: "Audio effects implementation"
+sidebarTitle: "Audio effects"
+description: "The four audio attributes, every effect and parameter, automation targets, the voiceover carve, audio groups, and how preview and render stay identical."
+---
+
+Use this reference when Studio controls are not enough: you need to write a mix
+into HTML, know a parameter's exact range, automate a knob, or understand why
+something behaves differently in the render than in preview. For everyday use
+start with [Mix audio and apply effects](/studio/audio-effects), and for what to
+ask an agent for, [Audio effects and mixing](/prompting/audio-effects).
+
+A composition carries its whole mix in the HTML. There is no session file and
+nothing to load beside the markup.
+
+## The four attributes
+
+| Attribute | Holds | Shape | Goes on | Read at playback |
+| --- | --- | --- | --- | --- |
+| `data-fx-chain` | The effects, in signal order | JSON | `<audio>`, `<video>`, `<hf-audio-group>` | Yes |
+| `data-automation` | Envelopes on volume or an effect parameter | JSON | `<audio>`, `<video>`, `<hf-audio-group>` | Yes |
+| `data-fx-carve` | A voiceover carve's own settings | JSON | `<audio>`, `<video>` | No — see [below](#data-fx-carve) |
+| `data-audio-group` | The id of the group this clip belongs to | A plain id, not JSON | `<audio>` only | Yes |
+
+`data-audio-group` is the odd one: a bare string, and **ignored on `<video>`**.
+The other three are JSON. Of those, only `data-fx-chain` and `data-automation`
+can also sit on an `<hf-audio-group>`, where they apply to the group's whole bus;
+`data-fx-carve` belongs to a clip.
+
+**Write the JSON attributes double-quoted, escaping the JSON's own quotes as
+`&quot;` and `&` as `&amp;`** — as every example on this page does. The browser
+reads them through `getAttribute` and does not mind either way, but
+`scripts/carve.mjs` finds them with a `name="..."` regex, so a single-quoted
+attribute is invisible to it: a carve reports no existing chain and overwrites
+work it could not see.
+
+Nothing static validates a chain. Preview plays an unreadable chain **dry** so
+the composition stays workable; the render **fails the whole mix** rather than
+shipping a dry track that sounds plausible and is wrong.
+
+### `data-fx-chain`
+
+```html
+<audio
+  id="narration"
+  src="assets/vo.wav"
+  data-start="0"
+  data-duration="12"
+  data-fx-chain="{&quot;version&quot;:1,&quot;nodes&quot;:[
+    {&quot;type&quot;:&quot;highpass&quot;,&quot;id&quot;:&quot;n1&quot;,&quot;label&quot;:&quot;Remove Rumble&quot;,
+     &quot;params&quot;:{&quot;frequency&quot;:120,&quot;q&quot;:0.707,&quot;poles&quot;:&quot;2&quot;}},
+    {&quot;type&quot;:&quot;peaking&quot;,&quot;id&quot;:&quot;n2&quot;,&quot;label&quot;:&quot;Reduce Mud&quot;,
+     &quot;params&quot;:{&quot;frequency&quot;:250,&quot;gain&quot;:-3,&quot;q&quot;:1.2}},
+    {&quot;type&quot;:&quot;limiter&quot;,&quot;id&quot;:&quot;n3&quot;,&quot;enabled&quot;:false,
+     &quot;params&quot;:{&quot;limit&quot;:-1,&quot;attack&quot;:5,&quot;release&quot;:50,&quot;level_out&quot;:0}}
+  ]}"
+></audio>
+```
+
+Unescaped, that chain reads: a high-pass labelled Remove Rumble, a peaking cut
+labelled Reduce Mud, and a bypassed limiter.
+
+- **Order is signal order.** Each node processes what the one before produced.
+- `type` is an effect id from [the registry](#effect-registry). `params` are in
+  the units a person thinks in — dB, ms, Hz. Out-of-range values are clamped on
+  read, so a chain that parses is always safe to realise.
+- `id` is a stable handle. Automation addresses nodes by id, never by position,
+  so reordering a chain cannot re-point a lane at a different effect. A node
+  with no id loads fine but cannot be automated. Studio hands out the first free
+  `n1`, `n2`, …
+- `label` replaces the effect's own name in the rack. Write one whenever a node
+  is doing a named job — two `peaking` nodes otherwise show the same row twice
+  and you cannot tell the mud cut from the clarity lift.
+- `enabled: false` is bypass: the node stays in the chain, out of the signal
+  path. Absent means enabled.
+- `fromCarve: true` marks a node the carve analysis generated. `fromPreset`
+  carries the id of the preset that wrote the node, which is how re-applying a
+  preset replaces its own nodes in place. **Do not set `fromCarve` by hand** —
+  the next carve deletes exactly those nodes.
+
+### `data-automation`
+
+```html
+data-automation="{&quot;version&quot;:1,&quot;lanes&quot;:[
+  {&quot;target&quot;:&quot;volume&quot;,&quot;points&quot;:[{&quot;t&quot;:0,&quot;v&quot;:1},{&quot;t&quot;:2.5,&quot;v&quot;:0.4}]},
+  {&quot;target&quot;:&quot;fx.n2.gain&quot;,&quot;points&quot;:[{&quot;t&quot;:0,&quot;v&quot;:0},{&quot;t&quot;:1,&quot;v&quot;:-6,&quot;curve&quot;:0.4}]}
+]}"
+```
+
+That is two lanes: the track's volume dropping to 0.4 by 2.5 s, and node `n2`'s
+gain moving to −6 dB by 1 s along a bent segment.
+
+| Field | Meaning |
+| --- | --- |
+| `target` | `volume` for the track's own level, or `fx.<nodeId>.<param>` |
+| `t` | Seconds — on **which clock depends on where the lane lives**, see below |
+| `v` | The parameter's own unit — dB for a gain, Hz for a frequency, a linear multiplier for volume |
+| `curve` | −1 to 1, bends the segment *leaving* a point; positive holds low then rises late |
+| `viaX` / `viaY` | An interior point the segment passes through (progress 0–1, value travelled 0–1); supersedes `curve` when both are present |
+
+### Two clocks
+
+| Lane on | `t: 0` means |
+| --- | --- |
+| A clip (`<audio>` / `<video>`) | The start of **that clip**. A bed with `data-start="8"` has `t: 0` at composition time 8 |
+| A group (`<hf-audio-group>`) | **Composition time.** A group has no `data-start`, so its clock starts at zero |
+
+Getting this backwards is the most expensive mistake on the page: a group lane
+written in clip-relative time lands wherever the first member happens to start.
+Preview and render agree on both clocks.
+
+### Volume is not capped at 1
+
+`v` on a `volume` lane is a linear gain multiplier with a ceiling of **+12 dB**,
+which is about `3.981` — the same ceiling `data-volume` uses. A lane that boosts
+above unity is valid and will play; `1` is unity, not the maximum.
+
+A lane holds its first value backwards to the start of its clip and its last
+value forward to the end. **A bed that begins before the voice therefore needs an
+explicit "no cut" point at `t: 0`, or it starts out already ducked.** Maximum 512
+points per lane. A lane whose node is gone is pruned on read rather than
+erroring — so a mistyped `nodeId` costs you the envelope silently. Read ids back
+out of the chain rather than assuming what was minted.
+
+A `volume` lane and a GSAP tween on `volume` conflict: the lane wins and the
+tween is ignored. The linter reports that as `audio_volume_double_automation`.
+
+### `data-fx-carve`
+
+```html
+data-fx-carve="{&quot;enabled&quot;:true,&quot;sources&quot;:[&quot;voiceover&quot;],&quot;strength&quot;:0.25}"
+```
+
+Unescaped: `{"enabled":true,"sources":["voiceover"],"strength":0.25}`.
+
+- `sources` names **what this bed makes room for** — element ids, or a group id,
+  which expands to its current members on every analysis.
+- `strength` is 0–1 and derives the whole mechanism.
+- `enabled: false` keeps the settings and stops the carve. It exists because a
+  bed with exactly one candidate voice is carved by default; with "off" as an
+  absent attribute, switching it off would read as never-configured and the
+  default would put it back.
+
+This attribute is **not read at playback** — the chain and lanes it produced are
+what play. It exists so strength can be changed on an existing carve instead of
+being guessed back out of the filters.
+
+Older projects may carry six mechanism numbers (`maxCutDb`, `bands`, `q`,
+`intelligibilityBias`, `duckDb`, `headroomDb`) instead of `strength`. They still
+load: the depth maps back onto a strength and the rest is re-derived. A stored
+carve with no `enabled` reads as on, a single `source` reads as a one-voice
+`sources` list, and a stored `dynamic` is ignored — every carve follows the
+speech now.
+
+### `data-audio-group`
+
+```html
+<style>hf-audio-group { display: none !important; }</style>
+
+<hf-audio-group id="voiceover" data-label="Voiceover" data-volume="1"></hf-audio-group>
+
+<audio id="vo-intro"  data-audio-group="voiceover" src="assets/vo1.wav" …></audio>
+<audio id="vo-middle" data-audio-group="voiceover" src="assets/vo2.wav" …></audio>
+```
+
+Membership is held by the **member**, not by the group nesting its members, so a
+deleted clip simply disappears from the group on the next resolve and nothing
+dangles.
+
+- `<hf-audio-group>` is optional metadata: `data-label`, `data-volume`,
+  `data-hidden`, and its own `data-fx-chain` / `data-automation`. A group with
+  members but no element still resolves, using its id as the label.
+- **Audio only.** `data-audio-group` on a `<video>` is ignored, and groups do
+  not nest.
+- `data-audio-group=""` is no group at all.
+- The element must be inert. The runtime injects
+  `hf-audio-group{display:none!important}` so an unknown custom element cannot
+  take a flex gap or shift `:nth-child` — but author the rule yourself so a bare
+  preview never lays it out.
+- Group ids and element ids share one namespace.
+
+## Effect registry
+
+Sixteen effects. Values outside a range are clamped on read. **AUTO** marks a
+parameter an automation lane can drive; anything unmarked cannot move over time.
+`HF_AUDIO_FX` in `@hyperframes/core/audio-fx` is the source of truth.
+
+### Filter — which frequencies a track may occupy
+
+| Effect | Parameters |
+| --- | --- |
+| `highpass` | `frequency` 20–20000 Hz (300, log) **AUTO** · `q` 0.1–20 (0.707, log) **AUTO** · `poles` `1`\|`2` (2) |
+| `lowpass` | `frequency` 100–20000 Hz (8000, log) **AUTO** · `q` 0.1–20 (0.707, log) **AUTO** · `poles` `1`\|`2` (2) |
+| `peaking` | `frequency` 20–20000 Hz (1000, log) **AUTO** · `gain` −40–40 dB (0) **AUTO** · `q` 0.1–20 (1, log) **AUTO** |
+| `lowshelf` | `frequency` 20–2000 Hz (200, log) **AUTO** · `gain` −40–40 dB (0) **AUTO** |
+| `highshelf` | `frequency` 500–20000 Hz (4000, log) **AUTO** · `gain` −40–40 dB (0) **AUTO** |
+
+`q` is bandwidth — higher is narrower. `poles` is the slope: `2` is the usual
+biquad (12 dB/oct), `1` is gentler (6 dB/oct). Shelving filters have no `q`; the
+Web Audio spec leaves it unused for them.
+
+### Dynamics — how level behaves over time
+
+| Effect | Parameters |
+| --- | --- |
+| `gain` | `gain` −60–12 dB (0) **AUTO** |
+| `compressor` | `threshold` −60–0 dB (−24) · `ratio` 1–20 (4) · `attack` 0.01–2000 ms (20, log) · `release` 0.01–9000 ms (250, log) · `knee` 1–8 (2.83) · `makeup` 0–36 dB (0) · `mix` 0–1 (1) |
+| `limiter` | `limit` −24–0 dB (−1) · `attack` 0.1–80 ms (5) · `release` 1–8000 ms (50, log) · `level_out` −24–24 dB (0) |
+| `gate` | `threshold` −80–0 dB (−35) · `range` −80–0 dB (−24) · `ratio` 1–20 (10) · `attack` 0.01–9000 ms (1, log) · `release` 0.01–9000 ms (100, log) · `knee` 1–8 (2.83) |
+
+Cuts on `gain` reach −60 dB, boosts stop at +12: it is a level stage for making
+room, and a chain that could add 40 dB would clip long before that was useful.
+`knee` of 1 is a hard corner. `mix` below 1 blends the dry signal back in
+(parallel compression). `range` is how far down the gate pulls when closed.
+
+### Nonlinear — changes the waveform's shape
+
+| Effect | Parameters |
+| --- | --- |
+| `saturate` | `type` `tanh`\|`atan`\|`cubic`\|`exp`\|`alg`\|`quintic`\|`sin`\|`erf`\|`hard` (tanh) · `threshold` −40–0 dB (−6) · `output` −24–24 dB (0) **AUTO** · `oversample` 1–8× (4) |
+| `bitcrush` | `bits` 1–32 (8) · `samples` 1–250× (1) · `mix` 0–1 (1) |
+
+`tanh` is the gentlest curve, `hard` is outright clipping. Higher `oversample`
+costs more CPU and keeps aliasing down. `samples` repeats each sample N times — a
+crude downsample, which is where the lo-fi character comes from.
+
+### Time — where a track sits, and how it moves
+
+| Effect | Parameters |
+| --- | --- |
+| `delay` | `time` 1–5000 ms (250, log) **AUTO** · `feedback` 0.01–0.95 (0.35) **AUTO** · `mix` 0–1 (0.4) **AUTO** |
+| `reverb` | `size` 0.05–1 (0.7) · `damping` 0–1 (0.5) · `wet` 0–1 (0.35) **AUTO** · `dry` 0–1 (0.7) **AUTO** |
+| `chorus` | `delay` 1–100 ms (7) **AUTO** · `depth` 0–10 ms (2) **AUTO** · `speed` 0.01–10 Hz (1) **AUTO** · `mix` 0–1 (0.5) **AUTO** |
+| `phaser` | `in_gain` 0–1 (0.4) **AUTO** · `out_gain` 0–2 (0.74) **AUTO** · `delay` 0.1–5 ms (3) · `decay` 0–0.99 (0.4) · `speed` 0.1–2 Hz (0.5) **AUTO** · `type` `0`\|`1` (0) |
+| `pitchshift` | `semitones` −12–12 st (0, whole steps) · `mix` 0–1 (1) |
+
+`pitchshift` moves pitch without changing playback speed, which is what
+separates it from a playback-rate change. Neither of its parameters can be
+automated — it is a worklet.
+
+Reverb convolves a *generated* impulse and both preview and render generate the
+same one, so a room is reproducible without shipping an impulse file. Higher
+`damping` rolls the top off the tail faster. `feedback` is bounded below 1
+because at 1 it never decays.
+
+## Why some parameters cannot be automated
+
+Automation is handed to the audio thread once, as native `AudioParam` ramps and
+curves — that is what keeps it sample-accurate and identical between preview and
+render. A parameter can therefore only be automated if an `AudioParam` backs it.
+Three kinds do not:
+
+| Kind | Effects | Consequence |
+| --- | --- | --- |
+| Worklet processor options | `compressor`, `limiter`, `gate`, `bitcrush`, `pitchshift` | **No parameter is automatable at all** |
+| A WaveShaper curve | `saturate`'s `type`, `threshold`, `oversample` | Only its `output` stage is a real param |
+| A convolution impulse | `reverb`'s `size`, `damping` | `wet` / `dry` are gain stages and automate fine |
+
+**A lane on a non-automatable parameter is silently inert.** To make one of those
+behave differently over time, automate a `gain` stage around it instead: a lane
+on a `gain` before a compressor changes how hard the compressor is driven, which
+is most of what automating its threshold would have done.
+
+## Presets, jobs, and one-knob profiles
+
+Every one of these is a shortcut to a chain you could have built by hand. Open
+any of them and you find ordinary effects with their parameters showing.
+
+### Presets
+
+Twenty-two, in four families. Applying one **appends**; re-applying one already
+present replaces its own nodes in place, because position is signal order.
+
+| Family | Ids |
+| --- | --- |
+| Voice | `voice-clean`, `voice-broadcast`, `voice-warm` |
+| Repair | `rumble-cut`, `room-gate`, `boom-tame`, `harsh-tame` |
+| Character | `telephone`, `radio-am`, `megaphone`, `lofi-tape`, `pa-system`, `intercom`, `doofus-worble`, `chipmunk`, `giant`, `monster` |
+| Space | `room-tight`, `room-natural`, `hall`, `slap-echo`, `dub-throw` |
+
+`chipmunk`, `giant`, and `monster` are built on `pitchshift`, so they change the
+speaker rather than the channel.
+
+`voice-clean` is Remove Rumble → Reduce Mud → Even Out Loudness → Add Clarity →
+Peak Ceiling. `voice-broadcast` is denser and more forward; `voice-warm` adds
+body rather than cutting it.
+
+A preset's nodes are wrapped in a wet/dry blend, so `presetAmount` (0–1) fades
+the whole thing, and `fx.preset.<id>` is an automation target that ramps it over
+time. That is the only way to automate a preset as a unit — its nodes share no
+common parameter.
+
+### Jobs
+
+Five named `peaking` filters with the frequency already chosen. Picking the job
+is picking the range, which is what makes a single "how much" knob honest.
+
+| Job | Symptom | Sets |
+| --- | --- | --- |
+| Tame Boominess | Too much chest — it booms | 200 Hz, −4 dB, Q 1.4 |
+| Reduce Mud | Muffled, like it is behind cardboard | 250 Hz, −3 dB, Q 1.2 |
+| Reduce Boxiness | Sounds like a small room, or a box | 400 Hz, −3 dB, Q 1.4 |
+| Add Clarity | Words are hard to make out | 3 kHz, +2.5 dB, Q 1 |
+| Soften Harshness | Harsh and tiring to listen to | 3.2 kHz, −3 dB, Q 1.6 |
+
+Writing one by hand, carry the name in `label` — the parameters alone are not
+the job.
+
+**Every job also ships inside a preset at identical settings**, which is where
+the five came from. So check what a preset already contains before adding a job
+on top: `voice-clean` plus a Reduce Mud job is −6 dB at 250 Hz where −3 was
+meant.
+
+### One-knob profiles
+
+Five effects have no single parameter that can honestly be their face — a
+compressor's threshold means nothing without its ratio. They get a derived
+control instead, 0–1, setting several parameters together.
+
+| Effect | Knob | 0 → 1 | Sets |
+| --- | --- | --- | --- |
+| `compressor` | Evenness | Barely touched → very even, quite squashed | threshold, ratio, attack, release, makeup |
+| `gate` | Tightness | Only true silence → cuts quiet words too | threshold, range, release |
+| `saturate` | Warmth | Just a sheen → openly distorted | threshold, output |
+| `reverb` | Space | A small tight room → a big open hall | size, wet, dry |
+| `bitcrush` | Crush | Slightly gritty → destroyed | bits, samples, mix |
+
+Evenness, Warmth, and Space are **level-matched**: the make-up gain, output trim,
+and dry leg move with the drive, so turning the knob up does not also turn the
+track up. Tightness and Crush are not, because neither has a trim to move.
+
+The chain stores the mechanism values, not the knob position — the knob is read
+back by inverting the curve, so hand-editing a parameter under a profile is
+allowed and simply moves the knob.
+
+## Voiceover carve
+
+A carve is a **relationship, not an effect**. The settings live on the *bed* —
+the track that gets processed — and name the voices to listen to, exactly as a
+sidechain compressor does. Never put a carve on a voice track.
+
+`strength` derives six numbers that move together in any real mix: how deep to
+cut, how many bands, how wide, how far to favour intelligibility over raw voice
+energy, how far the level may drop, and how far under the voice to aim.
+
+| Strength | Result |
+| --- | --- |
+| `0` | Spectral only — one band, no level match at all |
+| `0.25` (default) | A 6 dB dip in three bands with 6 dB of level room |
+| `0.5` | The dip reaches 10 dB — where a carve starts being heard as an effect |
+| Above `0.5` | Deliberate territory for a loud bed under a quiet voice |
+
+Every value becomes an envelope of the speech's own level: silence leaves the bed
+alone, a loud passage pushes the carve to full depth. There is no static mode.
+
+Inside a carved bed the signal runs through the dips first, then the level match,
+then anything you built yourself — which is why a limiter you add still acts as
+the last ceiling.
+
+Voices are summed onto the bed's clock before anything is measured, so one
+analysis covers all of them. Voices that never play while the bed does are left
+out; they cannot mask it.
+
+**Name a group, not a run of clip ids.** A list of ids has to be exhaustively
+right and stays right only until the next edit — a fourth narration clip added
+later plays outside the carve's awareness and the bed silently fails to duck
+under it. A `sources` list naming two or more plain clip ids is reported as
+`audio_carve_ungrouped_sources`.
+
+There are two arrangements where naming the group is **worse** than naming ids,
+and both come from the group form resolving later and wider than the analysis
+that wrote it:
+
+| Arrangement | What would happen |
+| --- | --- |
+| The bed is itself a member of the voice group | The bed is handed to itself as a voice and carved against its own content |
+| The group also holds a member classified music or SFX | That member enters the sidechain on a later analysis, ducking the bed under a whoosh |
+
+Neither shows up on the run that writes it — the analysis sums the voices it
+detected, so the first pass is correct however wrong the stored attribute is. It
+surfaces on the next re-analysis, against a file the previous run declared good.
+Keep the bed in its own group.
+
+What a carve writes is an ordinary chain of `peaking` filters plus a `gain`
+stage, tagged `fromCarve`, and one automation lane per carved parameter. That
+tagging is the whole trick: a re-run replaces the previous carve and leaves every
+effect and lane you built by hand exactly where it was.
+
+### From the command line
+
+```bash
+node <SKILL_DIR>/scripts/carve.mjs --comp index.html
+```
+
+That is the whole command — it finds the voice and the bed itself and prints what
+it decided:
+
+```text
+bed    music-bed (name looks like music)
+voice  narration (only track left)
+carve  strength 0.25
+bands  400Hz -6dB q1.4, 1000Hz -3dB q1.4, 1600Hz -3.17dB q1.4
+level  216-point envelope, floor -6 dB
+```
+
+Name tracks with `--bed` / `--voice` (repeatable) when the automatic choice is
+wrong, `--strength` to push it, `--dry-run` to see the report and write nothing.
+It refuses when it cannot tell which track is the bed rather than carving the
+wrong one.
+
+**What it records in `sources`.** When every voice it analysed shares exactly one
+group, and that group is safe to name, it writes the group id. It falls back to
+the individual clip ids — and says so — when the group contains the bed or a
+member classified music or SFX, for the reasons in the table above. A group
+member classified voice or unknown that this run did not analyse is *not* a
+reason to fall back: picking up a clip that starts playing later is the whole
+point of naming the group.
+
+Track choice is by name first, using the same classifier Studio's picker uses, so
+the two cannot disagree: an id or filename that looks like music (`music`, `bgm`,
+`bed`, `score`…) is the bed, and everything else playing over it that is not
+SFX-shaped is a voice. Needs `ffmpeg` on `PATH` and `@hyperframes/core`
+installed in the project.
+
+## Groups, mute, and solo
+
+A group sums its members through one bus, and the bus carries the group's own
+volume, FX chain, and automation. In the render each group is sub-mixed into a
+single track at full composition length before entering the main mix, so a
+group-level effect hears the sum rather than each member separately.
+
+**Mute and solo are not symmetric, on purpose.**
+
+| Control | Where it lives | Reaches the export |
+| --- | --- | --- |
+| Mute | `data-hidden` on the group element or the clip | **Yes** — muted members are dropped from the rendered mix |
+| Solo ("hear only this") | Studio session state | **No** — it never reaches the engine |
+
+Solo is a listening tool. An element is audible while any solo is active only if
+it is itself soloed or its own group is soloed; a group bus is never itself
+attenuated by solo, so a soloed member's path out stays open. A group that is not
+soloed while one of its members is shows as half-lit — the display-only signal
+that some of what is under it still plays.
+
+## Preview and render
+
+Both read the same two attributes through the same builders, which is why
+preview predicts the render:
+
+| | Preview | Render |
+| --- | --- | --- |
+| Context | Live `AudioContext` | `OfflineAudioContext` in the headless browser |
+| Unreadable chain | Plays **dry**, so the composition stays workable | **Fails the whole mix** |
+| Volume lane | Scheduled on the graph | Baked into the PCM by the mixer |
+| Editing an attribute mid-playback | Picked up by a `MutationObserver` | n/a |
+
+Effects with a tail — `reverb`, `delay` — make the rendered track **longer** than
+its source, and the mix is told how much. A bed with reverb therefore no longer
+ends exactly at its `data-duration`. That is expected.
+
+## What the linter checks
+
+Almost no static gate covers a mix. Three rules exist:
+
+| Rule | Reports |
+| --- | --- |
+| `audio_carve_ungrouped_sources` | A carve naming two or more plain clip ids instead of a group |
+| `audio_volume_double_automation` | A `volume` lane on a track that also has a GSAP tween on `volume` — the lane wins, the tween is ignored |
+| `audio_volume_tween_overrides_gain` | An authored `data-volume` on a track whose `volume` is tweened — the tween's values are absolute and replace that gain rather than scaling it |
+
+Nothing validates the chain or the effect lanes at all. What enforces those is
+the render. Beyond that, a mix is verified by rendering and listening.
diff --git a/docs/studio/audio-automation.mdx b/docs/studio/audio-automation.mdx
new file mode 100644
index 000000000..4ce6e9812
--- /dev/null
+++ b/docs/studio/audio-automation.mdx
@@ -0,0 +1,119 @@
+---
+title: "Automate a parameter over time"
+sidebarTitle: "Automation lanes"
+description: "Draw an envelope on a track's volume or an effect's knob, shape a selection, and know which parameters can move at all."
+---
+
+A static setting cannot say "quieter while the interview is on screen" or "fade
+out over the last three seconds". An automation lane can: it is a set of points on
+one parameter, and the value moves between them.
+
+Lanes work on a track's own **volume** and on any supported effect parameter, and
+a [group](/studio/audio-groups) has lanes of its own that apply to its whole bus.
+
+## Show a track's lanes
+
+Use the `∿` toggle on the track or group row. It shows a count when lanes already
+exist, and it is independent of the row's expand caret — showing a group's members
+does not open its lanes.
+
+To start automating an effect parameter, automate it from the parameter's own
+control in the rack. A parameter with a lane shows as **Automated**, and its
+static control is disabled: the lane owns the value from then on.
+
+## Draw and edit an envelope
+
+Work directly on the lane:
+
+- **Add a point** on the lane at the time you want it.
+- **Drag a point** to move it in time or value.
+- **Type an exact value** rather than dragging, when the number matters. A volume
+  lane can go above unity — the ceiling is +12 dB, not 1.
+- **Bend a segment** by dragging its curve, so the value holds and then moves late
+  rather than travelling evenly.
+- **Select a time range** to work on several points at once.
+
+With a range selected, right-click it for the shape and cleanup menu:
+
+| Item | Does |
+| --- | --- |
+| **Ramp up** / **Ramp down** | Replaces the selection with a single move in one direction |
+| **Swell** | Rises and returns |
+| **Dip** | Falls and returns — the shape most ducking wants |
+| **Simplify** | Removes redundant points while keeping the shape. Needs at least three points in the selection |
+
+A selection can also be **copied and pasted** onto another lane, and **retimed** by
+stretching its edges — useful when narration moves and its ducking should move
+with it.
+
+## Two things that surprise people
+
+**A track lane's times are relative to its clip.** A bed starting at 8 s has its
+first point at composition time 8. Move the clip and its envelope moves with it.
+
+**A group lane's times are composition time.** A group has no start of its own,
+so its lanes are measured from the beginning of the video. If you are automating
+a group bus, read the times as absolute.
+
+**A lane holds its first value backwards** to the start of the clip, and its last
+value forward to the end. So a bed that begins before the voice needs an explicit
+"no cut" point at the start, or it begins already ducked. This is the single most
+common automation mistake.
+
+## Not every knob can move
+
+A parameter can only be automated if the audio engine can schedule it directly.
+Three kinds cannot:
+
+| These | Cannot be automated because |
+| --- | --- |
+| Compressor, limiter, gate, bitcrush, pitch shift | They are configured whole rather than knob-by-knob — **no parameter on any of them can move** |
+| Saturation's type, threshold, and oversample | They rebuild the distortion curve; only its output stage can move |
+| Reverb's size and damping | They regenerate the room; its wet and dry levels can move |
+
+**A lane on one of those is silently inert** — it stores fine and never does
+anything. Pitch shift is the one that catches people out, because a rising pitch
+sounds like something a lane should do: it cannot, and the lane will not report
+it. To make a compressor's behaviour change over time, automate a `gain` stage
+*before* it instead: that changes how hard the compressor is driven, which
+is most of what automating its threshold would have done.
+
+To fade a whole preset in or out, automate the preset itself rather than its
+parts — its nodes share no single parameter, so the preset as a unit is the only
+handle that works.
+
+The [effect registry](/reference/audio-effects#effect-registry) marks every
+parameter that can move.
+
+## What should happen
+
+- The value moves between your points, in preview and in the render identically.
+- A parameter with a lane reads **Automated** and its static control is disabled.
+- A [carve](/studio/voiceover-carve) writes lanes of its own, and they are
+  ordinary lanes: you can edit them afterwards like any others.
+
+## Common problems
+
+**The lane does nothing.** Either the parameter is one of those above, or the
+effect it pointed at is gone. A lane whose effect was deleted is dropped silently
+rather than reported.
+
+**A newly added effect arrives already "Automated".** A lane left behind by a
+deleted effect can be inherited by the next effect that takes the same internal
+id. Remove the stale lane.
+
+**The volume lane is ignored.** A `volume` lane and a timeline tween on the same
+track's volume conflict; the lane wins. Pick one.
+
+**The envelope is right but the level is wrong.** A tween's values are absolute
+and replace a track's own gain rather than scaling it. Check whether the track
+also carries a static level.
+
+**The bed ducks before anyone speaks.** The first point is holding backwards. Add
+a point at the clip's start.
+
+## Related topics
+
+- [Mix audio and apply effects](/studio/audio-effects)
+- [Make music sit under narration](/studio/voiceover-carve)
+- [Audio effects implementation](/reference/audio-effects#data-automation)
diff --git a/docs/studio/audio-effects.mdx b/docs/studio/audio-effects.mdx
new file mode 100644
index 000000000..a93145cbe
--- /dev/null
+++ b/docs/studio/audio-effects.mdx
@@ -0,0 +1,168 @@
+---
+title: "Mix audio and apply effects"
+sidebarTitle: "Effects and presets"
+description: "Open a track's effect rack, fix a voice with one preset, and add individual effects in an order that works."
+---
+
+Studio carries a full mixer. Every audio track has an effect rack: filters that
+decide which frequencies it may occupy, dynamics that decide how its level
+behaves, character effects that change the shape of the waveform, and space
+effects that put it somewhere.
+
+Everything you do here is written into the composition's HTML. There is no
+separate session file, so a mix survives being handed to someone else, committed,
+or rendered on another machine.
+
+## Open a track's effect rack
+
+Select an audio clip on the timeline. The right panel shows an **Audio FX**
+section for it, listing the chain from top to bottom in signal order and ending
+in **Out to mix**. An empty track reads "No effects on this track."
+
+Do not confuse it with the **Effects** section on the same panel — that one is
+visual effects for pictures, and has nothing to do with sound.
+
+You can also reach it without the panel: the **FX** button on an audio track's
+timeline header opens a shelf of presets, with **Open rack ›** at the bottom. The
+button shows a count when the track already has effects.
+
+## Fix a voice with one preset
+
+Presets are the fastest honest answer to "this voice sounds wrong". Each one is
+an ordinary chain you could have built by hand — open it and the individual
+effects are all showing.
+
+Start from the symptom rather than the effect list:
+
+| It sounds like | Reach for |
+| --- | --- |
+| Hum or thump underneath | `rumble-cut`, or a high-pass at 80 Hz |
+| Boomy, chesty, too close to the mic | **Tame Boominess** |
+| Muffled, like it is behind cardboard | **Reduce Mud** |
+| Words hard to make out | **Add Clarity**, or [carve the music](/studio/voiceover-carve) |
+| Harsh and tiring over a whole listen | **Soften Harshness** |
+| Some words much louder than others | **Evenness** on a compressor, or **Even Out Levels** |
+| Room tone audible between sentences | `room-gate` |
+| Voice and music fighting each other | [A carve on the music](/studio/voiceover-carve) — not an EQ on either |
+| Dry, recorded nowhere | `room-tight` or `room-natural` |
+| Just "amateur" | `voice-clean` |
+
+`voice-clean` is the default answer to "fix this voiceover": it removes rumble,
+reduces mud, evens the level, adds clarity, and ends in a peak ceiling.
+`voice-broadcast` is the same idea denser and more forward; `voice-warm` adds
+body instead of cutting it.
+
+Applying a preset **appends** to the chain, so cleaning a voice and then adding
+character is a real thing to do. Re-applying the same preset replaces its own
+nodes where they already sit.
+
+Every named job also ships inside a preset at identical settings, so check what a
+preset already contains before adding a job on top of it — `voice-clean` plus a
+Reduce Mud job is −6 dB at 250 Hz where −3 was meant. Expanding the preset in the
+rack shows its nodes by name, which is the fastest way to see it.
+
+Beyond the corrective families there are **Character** presets — `telephone`,
+`radio-am`, `megaphone`, `lofi-tape`, `pa-system`, `intercom`, `doofus-worble`,
+`chipmunk`, `giant`, `monster` — and **Space** presets — `room-tight`, `room-natural`, `hall`, `slap-echo`,
+`dub-throw`. Character presets are costumes rather than corrections, and they are
+tuned to be distinguishable from one another, so do not stack two. `chipmunk`,
+`giant`, and `monster` shift pitch, so they change who is speaking rather than
+what they are speaking through.
+
+## Add a single effect
+
+Use **+ effect** in the rack. The menu groups effects the way you would reach for
+them, in four families:
+
+| Family | Decides |
+| --- | --- |
+| **Filters** | Which frequencies the track may occupy |
+| **Dynamics** | How its level behaves over time |
+| **Non-linear** | The shape of the waveform — character and grit |
+| **Time** | Where it sits and how it moves: delay, reverb, chorus, phaser, and pitch shift |
+
+The menu offers the [named jobs](#fix-a-voice-with-one-preset) in place of a bare
+`peaking` filter, because picking `peaking` is picking a machine and leaving the
+real decision — which frequency range — for afterwards.
+
+Order matters, because each effect processes what the one before produced. Work in
+this order and each step hears a cleaner signal than it otherwise would:
+
+1. **Subtract before you add.** Cut rumble and mud first. A voice that sounds dull
+   often has too much low-mid rather than too little top.
+2. **Level after you filter.** A compressor reacts to whatever is loudest, and a
+   rumble it can no longer see is a rumble it stops chasing.
+3. **Relationships after level.** Carve the music once the voice itself is
+   settled.
+4. **Character, then ceiling.** Saturation and space go late; a limiter goes last,
+   where it can actually act as a ceiling. Anything after it is not bounded by it.
+
+Rename any node so the rack says what it is doing. Two `peaking` rows otherwise
+look identical and you cannot tell the mud cut from the clarity lift.
+
+Bypass a node instead of deleting it while you are deciding — it stays in the
+chain, out of the signal path, so you can compare without losing the settings.
+
+## Use the one-knob controls
+
+Five effects have no single parameter that could honestly be their face — a
+compressor's threshold means nothing without its ratio. Those show one derived
+knob instead:
+
+| Effect | Knob | 0 → 1 |
+| --- | --- | --- |
+| Compressor | **Evenness** | Barely touched → very even, quite squashed |
+| Gate | **Tightness** | Only true silence → cuts quiet words too |
+| Saturation | **Warmth** | Just a sheen → openly distorted |
+| Reverb | **Space** | A small tight room → a big open hall |
+| Bitcrush | **Crush** | Slightly gritty → destroyed |
+
+Evenness, Warmth, and Space are level-matched: the make-up gain, output trim, and
+dry leg move with the drive, so turning the knob up does not also turn the track
+up. Tightness and Crush are not, because neither has a trim to move.
+
+Editing a parameter underneath one of these knobs is allowed and simply moves the
+knob — the chain stores the mechanism, not the knob position.
+
+## Even out a drifting take
+
+**Even Out Levels** measures the track's own speaking passages and writes a gain
+envelope. Its target is that track's own 80th percentile rather than an absolute
+level, so an already-even track is left alone. Use it when passages drift over a
+whole take; use a compressor's **Evenness** when the problem is word-to-word
+dynamics. **Remove levelling** takes it back off.
+
+## What should happen
+
+- Preview is what the render will sound like: both build the same graph from the
+  same attributes.
+- A chain Studio cannot read plays **dry** in preview so the composition stays
+  workable — but it **fails the render** rather than shipping a track that sounds
+  plausible and is wrong. If preview sounds unprocessed, suspect the chain.
+- Reverb and delay make a track **longer** than its source. A bed with reverb no
+  longer ends exactly at its clip length; that is expected.
+
+## Common problems
+
+**Nothing sounds different.** Check the node is not bypassed, then check you are
+looking at **Audio FX** rather than the visual **Effects** section.
+
+**The voice got louder as well as cleaner.** A preset ending in a peak ceiling
+raises perceived loudness. Trim the track's own level rather than removing the
+ceiling.
+
+**A cut landed twice.** A preset already contained the job you added on top.
+Expand the preset and read its nodes by name.
+
+**It sounds worse after adding top end.** A muddy voice needs the low-mid cut
+first; lifting the top of a muddy voice makes it muddy *and* harsh.
+
+**There is hiss under the words.** Nothing here removes it. A gate closes the gaps
+between phrases and leaves the noise beneath speech untouched — a source with
+audible hiss needs a better source.
+
+## Related topics
+
+- [Make music sit under narration](/studio/voiceover-carve)
+- [Automate a parameter over time](/studio/audio-automation)
+- [Audio effects implementation](/reference/audio-effects)
diff --git a/docs/studio/audio-groups.mdx b/docs/studio/audio-groups.mdx
new file mode 100644
index 000000000..6a879e551
--- /dev/null
+++ b/docs/studio/audio-groups.mdx
@@ -0,0 +1,105 @@
+---
+title: "Group tracks, mute, and solo"
+sidebarTitle: "Groups, mute, and solo"
+description: "Give several audio clips one set of effects, one fader, and one mute — and know which of mute and solo reaches the export."
+---
+
+Five narration clips usually want one set of effects, one fader, and one mute —
+not five copies that drift apart as you edit. A group gives them that: its members
+sum through a single bus, and the bus carries the group's own volume, effects, and
+automation.
+
+## When to use a group
+
+- **Narration in several clips.** One rack for the whole voice, and one thing for
+  a [carve](/studio/voiceover-carve) to point at.
+- **More than a couple of sound effects.** One place to turn all of them down is
+  worth more than precise individual levels you will never revisit.
+- **Anything you want to mute as a unit** — an ambience layer, a music stem.
+
+A single clip does not need a group. Its own rack is already one place.
+
+## Create a group
+
+On an audio track holding more than one ungrouped clip, the **FX** button offers
+to group them first: it reads "Group these clips to add effects to all of them".
+Choose **Group**.
+
+Studio creates a group behind those clips and points anything that needed it — a
+carve, for instance — at the group rather than at the individual clip ids.
+
+## Read a group row
+
+A group gets its own timeline row, carrying:
+
+| Control | Does |
+| --- | --- |
+| Caret | Shows or hides the member rows beneath it |
+| `▤` and name | The group glyph and its label |
+| Count | How many members it holds |
+| Mute | Silences every member at once |
+| **Hear only this** | Solo — listens to this group while you work |
+| **FX** | Opens the group's own rack, applying to the summed bus |
+| `∿` | Shows or hides [the group's own automation lanes](/studio/audio-automation) |
+
+The caret and the `∿` toggle are independent: showing a group's members does not
+open their automation lanes, and opening the group's lanes does not expand its
+members.
+
+A group-level effect hears the **sum** of its members, not each one separately.
+That is the point of a bus — one compressor across a whole voiceover behaves
+differently from five compressors on five clips, and usually better.
+
+## Mute and solo are not symmetric
+
+This is the part worth remembering:
+
+| Control | What it does | In the export |
+| --- | --- | --- |
+| Mute | Silences a clip or a whole group | **Included** — muted audio is dropped from the render |
+| **Hear only this** | Listens to one thing while you work | **Ignored** — solo never reaches the render |
+
+So **mute is a mix decision and solo is a listening tool**. You can leave a solo
+active, render, and get the full mix — which is deliberate, because a forgotten
+solo silently shipping a one-track export would be much worse.
+
+A group that is not soloed while one of its members is appears **half-lit**: the
+display-only signal that some of what is under it still plays.
+
+## Membership lives on the member
+
+Worth knowing because it explains most surprises: each clip records which group it
+belongs to, rather than the group listing its members. Delete a clip and it simply
+disappears from the group; nothing dangles.
+
+Groups are **audio only** and do not nest. A group marker on a video clip is
+ignored.
+
+## What should happen
+
+- The group row appears with the members collapsed beneath it, and the
+  grouping offer disappears from that track's **FX** button.
+- Effects added to the group apply to everything under it at once.
+- Muting the group silences all members, in preview and in the render.
+
+## Common problems
+
+**The group's effects do nothing.** Check that the members actually carry the
+group, rather than that the group appears to list them.
+
+**Nothing happened when I grouped clips.** Grouping resolves the clips it was
+given against the timeline's current rows. If the track is collapsed, or its clips
+live inside a nested composition, expand it and try again.
+
+**Clips inside a nested composition are not offered grouping.** They arrive as
+separate rows rather than as one track holding several clips, so the grouping
+offer does not appear. Group them in the composition that owns them.
+
+**A soloed track was missing from the export.** It was not — solo cannot affect a
+render. Look for a mute.
+
+## Related topics
+
+- [Make music sit under narration](/studio/voiceover-carve)
+- [Automate a parameter over time](/studio/audio-automation)
+- [Audio effects implementation](/reference/audio-effects#groups-mute-and-solo)
diff --git a/docs/studio/voiceover-carve.mdx b/docs/studio/voiceover-carve.mdx
new file mode 100644
index 000000000..aa2712aa2
--- /dev/null
+++ b/docs/studio/voiceover-carve.mdx
@@ -0,0 +1,124 @@
+---
+title: "Make music sit under narration"
+sidebarTitle: "Voiceover carve"
+description: "Take only the frequencies a voice occupies out of a music bed, so the music keeps its character while speech stays intelligible."
+---
+
+Music under narration is the most common audio problem in a video, and the
+obvious fix is the wrong one.
+
+Turning the whole music track down works, and it costs the music all of its
+presence for as long as anyone is talking — the bed goes limp through the entire
+voiceover. But a voice does not need the whole spectrum. It needs the few bands it
+actually occupies. A **carve** takes only those out of the music, so the bed keeps
+its low end and its top: still music, while the voice stays intelligible.
+
+## When to use it
+
+Whenever a music bed plays under speech. It is not a polish step to reach if
+there is time — place both tracks, carve, and listen.
+
+Skip it only when there is no narration for the music to sit under: a music video,
+a title card, a montage cut to the track.
+
+## Carve a bed
+
+The carve is a module at the top of the **music** track's rack, not a separate
+tool. Select the music clip, open its **Audio FX** section, and the module asks
+you to pick the voices this bed should make room for.
+
+A bed with exactly one candidate voice above it is **already carved**, at the
+default strength, because that is what a bed under narration wants. Several
+candidates leaves the picker waiting rather than guessing which one is the voice.
+
+<Warning>
+  The carve belongs on the **music**, never on the voice. It names the tracks it
+  makes room for, the same way a sidechain compressor does — you select the track
+  that gets quieter and pick what makes it quieter. A voice carved against itself
+  is a bug, not a subtle mix choice.
+</Warning>
+
+## Set the strength
+
+One control does the whole job. It derives how deep to cut, how many bands, how
+wide they are, how far the level may drop, and how far under the voice to aim —
+because those move together in any real mix.
+
+| Strength | What you get |
+| --- | --- |
+| Default (0.25) | A 6 dB dip in three bands — audible without sounding like a hole |
+| Around 0.5 | The dip reaches 10 dB, where a carve starts being heard as an effect |
+| Higher | Deliberate territory for a loud bed under a quiet voice |
+| 0 | Spectral only — one band, no level matching at all |
+
+**Switch the carve off** keeps the settings and stops the carve, which is
+different from clearing it: a bed with one candidate voice would otherwise be
+carved again by default the moment it was re-evaluated.
+
+## What it writes
+
+Ordinary effects. Open the rack after carving and you will find a few `peaking`
+filters and a `gain` stage — nothing hidden, nothing proprietary.
+
+Two things follow from that:
+
+- **The envelopes are editable.** The carve always follows the speech, so every
+  value becomes an automation lane you can adjust by hand afterwards. Silence
+  leaves the music alone; a loud passage pushes the carve to full depth. There is
+  no fixed-depth mode, because a fixed dip thins the bed through every pause.
+- **Re-carving is safe.** The nodes a carve writes are tagged as its own, so
+  running it again at a new strength replaces exactly those and leaves every
+  effect and lane you built by hand where it was.
+
+Inside a carved bed the signal runs through the dips first, then the level match,
+then anything you added yourself — which is why a limiter you place stays the last
+ceiling.
+
+## Point it at a group, not at clips
+
+If narration arrives as several clips, [group them](/studio/audio-groups) and
+carve against the group.
+
+A carve pointed at individual clips has to list every one of them, and it stays
+right only until the next edit: add a fourth narration clip and it plays outside
+the carve's awareness, so the music silently fails to duck under it. A carve
+pointed at a group resolves membership every time the analysis runs, so a clip
+added later is covered without touching the carve.
+
+Studio does this for you when you pick a second ungrouped voice — it creates a
+group behind them and points the carve at that instead.
+
+## What should happen
+
+- The voice is legible without the bed sounding hollowed out.
+- The music comes **back up between phrases** rather than staying flat.
+- The bed keeps its bass and its top end. A carve that removed those would just
+  be a filter.
+
+## Common problems
+
+**The music sounds notched or hollow.** Strength is too high. Come back toward
+the default. This is the one failure mode with an obvious sound.
+
+**The voice is still buried.** A carve cannot fix a bed that is simply louder than
+the voice — spectral room does not solve a level problem. Compare the two tracks'
+actual loudness first. Machine-generated speech commonly arrives far below a
+mastered music track, and that gap is arithmetic rather than taste.
+
+**The bed starts out already ducked.** A lane holds its first value backwards to
+the start of its clip. A bed that begins before the voice needs an explicit "no
+cut" point at its start.
+
+**The music pumps.** The level envelope releases slowly on purpose, because music
+that snaps back the instant a word ends sounds like a machine doing it. If it
+still pumps, the gaps between phrases are shorter than the release — lower the
+strength rather than fighting the envelope.
+
+**Nothing was carved.** The picker leaves itself alone when several tracks could
+be the voice. Name the voice explicitly.
+
+## Related topics
+
+- [Mix audio and apply effects](/studio/audio-effects)
+- [Group tracks, mute, and solo](/studio/audio-groups)
+- [Audio effects implementation](/reference/audio-effects#voiceover-carve)