ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-04 16:42:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(audio): document the audio effects system (#3420)

Browse Source 
* 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
`"`, 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.
This commit is contained in:
Vance Ingalls
2026-08-22 05:49:35 -07:00
committed by GitHub
parent c594023895
commit 0eca7b1e0a
9 changed files with 1184 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs.json
+13 -2
View File
@@ -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"
]
},
{
docs/guides/voice-and-audio.mdx
+4 -1
View File
@@ -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.
docs/prompting/audio-effects.mdx
+177
View File
@@ -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.*
docs/prompting/media-and-audio.mdx
+2 -2
View File
@@ -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
docs/reference/audio-effects.mdx
+472
View File
@@ -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.
docs/studio/audio-automation.mdx
+119
View File
@@ -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)
docs/studio/audio-effects.mdx
+168
View File
@@ -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)
docs/studio/audio-groups.mdx
+105
View File
@@ -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)
docs/studio/voiceover-carve.mdx
+124
View File
@@ -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)