mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-08-31 02:41:44 +00:00
Vance Ingalls
0eca7b1e0a
* 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.
120 lines
5.3 KiB
Plaintext
120 lines
5.3 KiB
Plaintext
---
|
|
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)
|