* 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.
The merged '## Timeline navigation' section documents a third arrow-key behaviour;
the 'selected area decides' paragraph read as exhaustive with only two. Fold in the
timeline-focus case and link the section. Coherence note from Rames.
The "One project, open end to end" section on Examples was four cards linking into
a GitHub folder. A reader on the docs site does not want to leave for a repo tree
to read a BRIEF.md. The section is gone, and so is the examples/docs-reference-project
folder it pointed at.
Also removed the prose references that leaned on it: the Reference Project
paragraph on Go further, the two GitHub-inspect links on Developers, and the
mention on the Studio landing. Each was reworded to talk about "a project"
generally rather than that specific folder.
Examples is now purely the nineteen finished films plus Start from a template.
The changelog entry recording #2977 is left as history. 0 broken links.
**canvas.mdx pointed at a Design section that does not exist.** The table sent
readers to "3D". PropertyPanelFlat.tsx renders Text, Style, Layout, Motion,
Grade, Effects, Overlays, Media — no 3D. 3D Transform is a labelled block inside
Layout (propertyPanelFlatLayoutSection.tsx:302). The table also had no row for
Motion or Effects, while the approved media-effects guide tells readers to "open
Effects in the Inspector" — so the canonical map of the Inspector said that
section did not exist. Four rows fixed or added.
**The two-card reuse example could not do what its prose promised.** Both
concepts/compositions.mdx and concepts/variables.mdx omitted data-duration on the
nested-composition hosts, then said `data-start="card-pro"` means "start when
that one ends". With no duration, resolveDurationForElement returns null and
startResolver.ts:180-184 falls back to targetStart + offset = 0 — both cards
stacked at t=0 on one track, which html-schema.mdx:104 says must never happen and
:99 lists data-duration as required for nested-composition clips. Both copies now
carry it.
Read against packages/studio/src rather than against the page's own prose.
- `J` / `Shift + J` jump to the previous and next keyframe
(useKeyframeKeyboard.ts:60). The keyframe table had no row for J at all.
- `Backspace` deletes a keyframe, not only `Delete` (same file, line 56).
- `Ctrl + Y` is redo (useAppHotkeys.ts:44). Only Ctrl+Shift+Z was listed, and
Ctrl+Y is the first thing a Windows user reaches for.
The page already warned that arrow keys mean different things depending on
selection. `J` and `K` do exactly the same and it did not say so — `K` is stop
during playback and add-keyframe with keyframes selected, which is a surprising
way to lose your place. That note now names them.
Everything else on the page checks out: 20 single-letter bindings in the source,
all now accounted for.
Adds the pages the rebuilt navigation is organised around, and moves the sidebar
onto that structure. Every entry points at a file that exists after this commit;
nothing is rewritten or removed yet, and no redirect is claimed yet.
- Studio (13 pages) — the editor had no section of its own
- One guide per creation workflow, matching the shipped agent skills
- Section hubs: Concepts, Catalog, Developers, Deploy, Workflows, Help,
Go further, Product updates, 30 Days of HyperFrames
Pages a later commit retires drop out of the sidebar here but still exist and
still resolve, so the site stays navigable at this commit.
Incidentally fixes a link to /concepts from the Lambda migration guide that is
broken on main today — the destination did not exist.
Vance Ingalls