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)