dsh-hyperframes 0.9.1 → 0.9.3

package/skills/hyperframes-animation/transitions/overview.md

@@ -1,153 +0,0 @@
-# Scene Transitions
-
-A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
-
-## Contents
-
-- Animation rules for multi-scene compositions
-- Energy and mood transition selection
-- Narrative position
-- Blur intensity
-- Presets
-- Implementation
-- CSS vs shader guidance
-- Shader-compatible CSS rules
-- Visual pattern warnings
-
-## Animation Rules for Multi-Scene Compositions
-
-These are non-negotiable for every multi-scene composition:
-
-1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.
-2. **Every scene uses entrance animations.** Elements animate IN — opacity, position, scale, etc. No scene should pop fully-formed onto screen. Use `gsap.fromTo()` (not `gsap.from()`) so the start state is explicit: `from()` animates _to_ current CSS, so pairing it with CSS `opacity: 0` is a 0→0 noop and the element never appears (see `/hyperframes-core` → sub-compositions).
-3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.
-4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.
-
-```js
-// ❌ BANNED — fading the outgoing scene out, then the next scene just runs its entrance.
-//    This is a jump cut with a dip, not a transition.
-tl.to("#s1", { opacity: 0, duration: 0.4 }, 4.0);
-tl.from("#s2 .headline", { y: 40, opacity: 0 }, 4.4);
-
-// ✅ CORRECT — outgoing and incoming animate AT THE SAME TIME T; the motion IS the handoff.
-const T = 4.0;
-tl.to("#s1", { yPercent: -100, filter: "blur(8px)", duration: 0.5, ease: "power3.in" }, T);
-tl.fromTo("#s2", { yPercent: 100 }, { yPercent: 0, duration: 0.5, ease: "power3.out" }, T);
-```
-
-> **You are NOT done after this file.** This overview gives you _which_ transition and _when_. Before writing any transition you MUST open **`catalog.md`** in this directory for the GSAP code and the hard rule every transition follows — _position new scene → animate outgoing → swap → animate incoming → clean up overlays_ — plus the per-category `css-*.md` files for specifics. Authoring transitions from this overview alone is how you end up shipping the ❌ pattern above.
-
-## Energy → Primary Transition
-
-| Energy                                   | CSS Primary                  | Shader Primary                       | Accent                         | Duration  | Easing                 |
-| ---------------------------------------- | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ---------------------- |
-| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Cross-warp morph, thermal distortion | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |
-| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Whip pan, cinematic zoom             | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |
-| **High** (promos, sports, music, launch) | Zoom through, overexposure   | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`       |
-
-Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.
-
-## Mood → Transition Type
-
-Think about what the transition _communicates_, not just what it looks like.
-
-| Mood                     | Transitions                                                                                                                          | Why it works                                                                                |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| **Warm / inviting**      | Light leak, blur crossfade, focus pull, film burn · **Shader:** thermal distortion, light leak, cross-warp morph                     | Soft edges, warm color washes. Nothing sharp or mechanical.                                 |
-| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve · **Shader:** gravitational lens                                                   | Content transforms mechanically — compressed, shrunk, sliced, gridded.                      |
-| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter · **Shader:** whip pan                                                            | Like turning a page or slicing a layout. Clean directional movement.                        |
-| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration · **Shader:** glitch, chromatic split                                  | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines. |
-| **Tense / edgy**         | Glitch, VHS, chromatic aberration, ripple · **Shader:** ridged burn, glitch, domain warp                                             | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.   |
-| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe · **Shader:** ripple waves, swirl vortex                                | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.        |
-| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, color dip to black · **Shader:** cinematic zoom, gravitational lens, domain warp | Scale, weight, light extremes. Shader transitions add per-pixel depth.                      |
-| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black · **Shader:** cross-warp morph, thermal distortion                                    | Restraint. Cross-warp morph flows both scenes into each other organically.                  |
-| **Retro / analog**       | Film burn, light leak, VHS, clock wipe · **Shader:** light leak                                                                      | Organic imperfection. Warm color bleeds, scan line displacement.                            |
-
-## Narrative Position
-
-| Position                   | Use                                                                        | Why                                                   |
-| -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |
-| **Opening**                | Your most distinctive transition. Match the mood. 0.4-0.6s                 | Sets the visual language for the entire piece.        |
-| **Between related points** | Your primary transition. Consistent. 0.3s                                  | Don't distract — the content is continuing.           |
-| **Topic change**           | Something different from your primary. Staggered blocks, shutter, squeeze. | Signals "new section" — the viewer's brain resets.    |
-| **Climax / hero reveal**   | Your boldest accent. Fastest or most dramatic.                             | This is the payoff — spend your best transition here. |
-| **Wind-down**              | Return to gentle. Blur crossfade, crossfade. 0.5-0.7s                      | Let the viewer exhale after the climax.               |
-| **Outro**                  | Slowest, simplest. Crossfade, color dip to black. 0.6-1.0s                 | Closure. Don't introduce new energy at the end.       |
-
-## Blur Intensity by Energy
-
-| Energy     | Blur    | Duration | Hold at peak |
-| ---------- | ------- | -------- | ------------ |
-| **Calm**   | 20-30px | 0.8-1.2s | 0.3-0.5s     |
-| **Medium** | 8-15px  | 0.4-0.6s | 0.1-0.2s     |
-| **High**   | 3-6px   | 0.2-0.3s | 0s           |
-
-## Presets
-
-| Preset     | Duration | Easing            |
-| ---------- | -------- | ----------------- |
-| `snappy`   | 0.2s     | `power4.inOut`    |
-| `smooth`   | 0.4s     | `power2.inOut`    |
-| `gentle`   | 0.6s     | `sine.inOut`      |
-| `dramatic` | 0.5s     | `power3.in` → out |
-| `instant`  | 0.15s    | `expo.inOut`      |
-| `luxe`     | 0.7s     | `power1.inOut`    |
-
-## Implementation
-
-Read `catalog.md` in this directory for GSAP code and hard rules for every transition type, and the `css-*.md` files for per-category implementation details.
-
-| Category    | CSS                                                            | Shader (WebGL)                                                            |
-| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| Push/slide  | Push slide, vertical push, elastic push, squeeze               | Whip pan                                                                  |
-| Scale/zoom  | Zoom through, zoom out, gravity drop, 3D flip                  | Cinematic zoom, gravitational lens                                        |
-| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris                                                                  |
-| Dissolve    | Crossfade, blur crossfade, focus pull, color dip               | Cross-warp morph, domain warp                                             |
-| Cover       | Staggered blocks, horizontal blinds, vertical blinds           | —                                                                         |
-| Light       | Light leak, overexposure burn, film burn                       | Light leak (shader), thermal distortion                                   |
-| Distortion  | Glitch, chromatic aberration, ripple, VHS tape                 | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |
-| Pattern     | Grid dissolve, morph circle                                    | —                                                                         |
-
-## Transitions That Don't Work in CSS
-
-Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.
-
-## CSS vs Shader
-
-CSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas — they can warp, dissolve, and morph in ways CSS cannot.
-
-**Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package — import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.
-
-**Mixing is supported.** You can have some transitions use WebGL shaders and others use a CSS crossfade in the same composition. Omit the `shader` field on any `TransitionConfig` entry to get a smooth opacity crossfade instead of a WebGL effect:
-
-```js
-var tl = HyperShader.init({
-  bgColor: "#000",
-  accentColor: "#6366f1",
-  scenes: ["s1", "s2", "s3", "s4"],
-  transitions: [
-    { time: 4.0, shader: "sdf-iris", duration: 0.7 }, // WebGL shader
-    { time: 8.5, duration: 0.8 }, // no shader → CSS crossfade
-    { time: 13.0, shader: "domain-warp", duration: 0.6 }, // WebGL shader
-  ],
-});
-```
-
-HyperShader manages all scene visibility regardless of transition type. Let it create the timeline (don't pass `timeline:` into `init()`) and add your beat animations to the returned `tl` after the call.
-
-## Shader-Compatible CSS Rules
-
-Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:
-
-1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.
-2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.
-3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.
-4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.
-5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.
-6. **Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config.** The package captures scene elements via html2canvas. Both the CSS `background-color` on `.scene` and the `bgColor` config must match. Without either, the texture renders as black.
-
-These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
-
-## Visual Pattern Warning
-
-Avoid transitions that create visible repeating geometric patterns — grids of tiles, hexagonal cells, uniform dot arrays, evenly-spaced blob circles. These look cheap and artificial regardless of the math behind them. Organic noise (FBM, domain warping) is good because it's irregular. Geometric repetition is bad because the eye instantly sees the grid.

package/skills/hyperframes-audio/references/attributes.md

@@ -1,138 +0,0 @@
-# The three audio attributes
-
-All three go on the `<audio>` / `<video>` element itself, JSON-encoded, so a
-composition carries its whole mix in the HTML with nothing to load beside it.
-`data-fx-chain` and `data-automation` also go on an `<hf-audio-group>` bus,
-where they mean the same thing over the summed members — with one difference
-worth knowing: a group's automation runs on COMPOSITION time, since a bus has no
-`data-start` of its own. `data-fx-carve` is clip-only; a bus has no carve.
-Nothing static validates them: preview plays an unreadable chain dry to stay
-workable, and the render refuses the whole mix rather than shipping a dry track
-that sounds plausible and is wrong.
-
-## `data-fx-chain` — the effects
-
-```json
-{
-  "version": 1,
-  "nodes": [
-    {
-      "type": "highpass",
-      "id": "n1",
-      "label": "Remove Rumble",
-      "params": { "frequency": 120, "q": 0.707, "poles": "2" }
-    },
-    {
-      "type": "peaking",
-      "id": "n2",
-      "fromCarve": true,
-      "params": { "frequency": 1600, "gain": -6, "q": 1.4 }
-    },
-    {
-      "type": "limiter",
-      "id": "n3",
-      "enabled": false,
-      "params": { "limit": -1, "attack": 5, "release": 50, "level_out": 0 }
-    }
-  ]
-}
-```
-
-**Write these attributes double-quoted, with the JSON's own quotes as `&quot;`.**
-The browser reads them through `getAttribute` and does not care, but
-`scripts/carve.mjs` finds them with a `name="..."` regex, so a single-quoted
-attribute is invisible to it — the carve reports no existing chain and quietly
-overwrites work it could not see. `&` becomes `&amp;`; nothing else needs
-escaping.
-
-- **Order is signal order.** Each node processes what the one before produced.
-- `type` is an effect id from the registry. `params` are in the units a person
-  thinks in — dB, ms, Hz — and 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 the chain cannot re-point a lane at a different effect. A node
-  with no id loads fine but cannot be automated. Writing a chain by hand, any
-  unique string works; Studio hands out the first free `n1`, `n2`, … so matching
-  that convention keeps a hand-written chain and an edited one looking alike.
-- `label` is what the rack calls this node, replacing the effect's own name.
-  Write one whenever the node is doing a named job — a chain with two `peaking`
-  nodes otherwise shows the same row twice and the author cannot tell which is
-  the mud cut and which is the clarity lift. Presets and jobs always set it; a
-  hand-written node should too. See `presets.md` for the names they use.
-- `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. Re-running the
-  carve replaces exactly these and leaves hand-built effects alone. **Do not set
-  it by hand**: a node tagged this way will be deleted by the next carve.
-
-## `data-automation` — the envelopes
-
-```json
-{
-  "version": 1,
-  "lanes": [
-    {
-      "target": "volume",
-      "points": [
-        { "t": 0, "v": 1 },
-        { "t": 2.5, "v": 0.4 }
-      ]
-    },
-    {
-      "target": "fx.n2.gain",
-      "points": [
-        { "t": 0, "v": 0 },
-        { "t": 1, "v": -6, "curve": 0.4 }
-      ]
-    }
-  ]
-}
-```
-
-- `target` is `volume` for the track's own level, or `fx.<nodeId>.<param>`.
-- `t` is **seconds from the start of the clip**, not of the composition. A bed
-  starting at `data-start="8"` has `t: 0` at composition time 8.
-- `v` is in the parameter's own unit: dB for a gain, Hz for a frequency, 0..1 for
-  volume.
-- A lane holds its first value backwards to the start of its clip and its last
-  value forward to the end. So a bed that begins before the voice needs an
-  explicit "no cut" point at `t: 0`, or it starts out already ducked.
-- `curve` (-1..1) bends the segment _leaving_ a point: positive holds low then
-  rises late. `viaX`/`viaY` name an interior point the segment passes through
-  (progress 0..1, value travelled 0..1) and supersede `curve` when both are
-  present — that is what the timeline writes when a bend is dragged.
-- 512 points per lane, maximum.
-- A lane whose node is gone is pruned on read rather than erroring.
-
-**A lane on a non-automatable parameter is silently inert.** Automation is
-delivered as native `AudioParam` scheduling, so a knob that no `AudioParam` backs
-cannot move: worklet processor options, a WaveShaper curve and a convolution
-impulse are all set wholesale. `fx-registry.md` marks each parameter; the four
-worklet effects (`compressor`, `limiter`, `gate`, `bitcrush`) have none at all.
-
-## `data-fx-carve` — the carve's settings
-
-```json
-{ "enabled": true, "sources": ["narration", "interview-guest"], "strength": 0.35 }
-```
-
-- `sources` are the **element ids of every voice this bed makes room for**. They live
-  on the bed being processed, not on the voices. Summed onto the bed's clock before
-  the analysis, so one set of filters and envelopes covers all of them.
-- `strength` 0..1 derives the whole mechanism (see `carveProfile`).
-- There is no `dynamic`: a carve always follows the speech.
-- `enabled` is whether the carve applies. It exists because a bed with exactly one
-  candidate voice is carved by default: with "off" represented by an absent
-  attribute, switching it off would read as never-configured and the default would
-  put it back. `enabled: false` keeps the settings and stops the carve.
-
-This attribute is not read at playback — the chain and lanes it produced are what
-play. It exists so the settings can be read back and re-derived rather than
-guessed from the filters, which is what makes changing strength on an existing
-carve possible.
-
-Older projects may carry the six mechanism numbers (`maxCutDb`, `bands`, `q`,
-`intelligibilityBias`, `duckDb`, `headroomDb`) instead of `strength`. They still
-load: the depth maps back onto a strength and everything else is re-derived. A
-stored carve with no `enabled` reads as on, and a single `source` reads as a one-voice
-`sources` list. A stored `dynamic` is ignored — every carve follows the speech now.

package/skills/hyperframes-audio/references/diagnosis.md

@@ -1,276 +0,0 @@
-# Diagnosing audio you cannot hear
-
-The symptom table in `SKILL.md` starts from "it sounds boomy". That presumes
-somebody already listened and said so. Handed a file and "fix this", you have
-no such sentence — and you cannot listen. This is how to get one.
-
-It is worth being blunt about the difficulty first, because the failure mode is
-not "no answer", it is **a confident wrong answer**:
-
-> **The absolute spectrum of a single unknown voice cannot be diagnosed.**
-
-Every voice has peaks and dips of exactly the size an injected filter has.
-Formants are ±10 dB. A speaker's fundamental sits anywhere from 85 to 255 Hz.
-Sentences decline 5–6 dB from start to end as a matter of ordinary prosody. Look
-at one spectrum on its own and you will find "defects" in all of it, and the
-ones you find will be the speaker.
-
-So diagnosis is always **comparison**. The whole method is choosing the right
-thing to compare against.
-
----
-
-## Compare against something inside the same file
-
-Ranked by how much they can tell you. Prefer the highest one available.
-
-### 1. The clean original, if it exists
-
-If the undamaged take is on disk, this is the whole job — measure both, subtract,
-and the difference _is_ the defect. Nothing below is as good. Look for it before
-anything else.
-
-### 2. The pauses
-
-The strongest reference that lives inside a single file. Speech stops; whatever
-is still there in the gap is not the voice.
-
-**What it answers: "was something added?"**
-
-Anything audible in the pauses is additive — hum, rumble, hiss, room tone. It was
-laid on top, so it can be subtracted, and this is a reliable positive finding.
-
-**What it does NOT answer: "was something filtered?"** — and getting this
-backwards is how the method produces a confident wrong answer.
-
-A filter multiplies. Applied to a file whose gaps already sit at the
-quantisation floor, it leaves them at the quantisation floor: near-silence times
-anything is still near-silence. So the pause carries no trace of it. Measured on
-one take with a −9 dB shelf above 2.5 kHz applied to the whole file:
-
-|                   | 1 kHz | 5 kHz | tilt      |
-| ----------------- | ----- | ----- | --------- |
-| pause, undamaged  | −91.0 | −91.0 | +0.0      |
-| pause, shelved    | −91.0 | −91.0 | **+0.0**  |
-| speech, undamaged | −34.7 | −42.8 | −8.1      |
-| speech, shelved   | −35.4 | −48.5 | **−13.1** |
-
-The defect is a clear 5 dB in the speech and **exactly zero** in the pause.
-
-So: **never use a null result from the pause spectrum to rule out EQ.** A run
-that did exactly that — measured the pause, found it smooth, and concluded
-"static EQ of any type or Q is ruled out" — went on to treat an inaudible
-−72 dBFS rumble as the defect and shipped a high-pass for a file whose actual
-problem was that it had no top end.
-
-The pause spectrum _is_ a transfer function only when the gaps carry a real
-recorded noise floor that passed through the same filter. A room-tone bed does;
-a digitally clean take does not. Check which you have before trusting it: if the
-gaps are within a few dB of the quantisation floor, this reference can find
-additive content and nothing else.
-
-### 3. The speech's own tilt, for a suspected filter
-
-When the pause cannot see a filter (above), the only thing left carrying it is
-the speech. Read the tilt across a few 1/3-octave bands rather than any single
-one — `1k / 3.2k / 5k / 7k` is enough to see a shelf:
-
-```bash
-for f in 1000 3200 5000 7000; do third voice.wav $f; done
-```
-
-Speech falls away steadily above about 1 kHz, so a downward slope is expected;
-what you are looking for is a slope that keeps steepening, or a step. In the
-table above, −8.1 dB from 1 k to 5 k is an ordinary voice and −13.1 dB is the
-same voice with 9 dB taken off the top.
-
-**This is a candidate, not a verdict.** Where the ordinary slope ends and a
-defect begins is speaker-dependent, and you have no baseline for this speaker.
-Say what you measured and what it would mean, and let somebody hear it.
-
-### 4. The file against itself over time
-
-For anything level-related, compare each passage to the track's own median rather
-than to a target. That is what `levellingResult` does, and it is why an already
-even track comes back untouched.
-
----
-
-## Do not compare against a different voice
-
-Both wrong answers in the evaluation that produced this page came from an
-external reference, and both were argued rigorously from bad ground:
-
-- **A published average spectrum** (LTASS and friends). One run concluded
-  "+10 dB above 7 kHz, split-half stable, gating-independent" on a file whose
-  actual defect was +6.6 dB at 200 Hz. Its supporting claim — 10 kHz sitting
-  6.2 dB above 6.3 kHz — measured 0.6 dB on re-check, and measured the same in
-  the clean original. Published curves are mixed-sex, mixed-corpus, and
-  mixed-microphone; the gap between them and any one speaker is larger than most
-  defects.
-- **A synthesised control voice** (`say`, a TTS take, another narrator). One run
-  generated a control this way, found the spectrum "normal", and missed a −6.9 dB
-  shelf. Two speakers differ by more than 7 dB across the top octaves as a matter
-  of course, so a cross-voice comparison cannot resolve a defect that size.
-
-If neither the original nor usable pauses exist — continuous speech, or gaps that
-are digital silence and so carry no channel — then a static tonal defect is
-**genuinely under-determined**.
-
-Report that. It is a finding, not a failure to find one, and it is the correct
-answer rather than the fallback when the better methods are unavailable. Give
-the author the two or three readings that fit and ask which they hear; they can
-listen, and that one sentence from them collapses the whole problem.
-
-**This is the point where a capable agent goes wrong.** Told a thing is
-under-determined, the instinct is to invent a cleverer measurement and escape
-it — and something will always be found, because a single voice's spectrum is
-full of peaks and valleys that survive any amount of statistical rigour. An
-elaborate novel method reaching a confident conclusion, on a file where the two
-reliable references were both unavailable, is the _signature_ of this failure,
-not evidence against it. If you notice yourself building one, stop and report
-the ambiguity instead.
-
----
-
-## Recipes
-
-### Compare loudness from the bytes the listener actually hears
-
-Do not call two clips equally loud because their Studio faders, waveform peaks,
-or cached asset metadata match. Those are controls and proxies, not a loudness
-measurement. Resolve the exact URLs used by preview/render, download or inspect
-those exact served bytes, and measure each decoded stream with FFmpeg's
-`ebur128` filter. Compare the integrated LUFS values.
-
-For a target loudness, the required move is:
-
-```text
-gain_db = target_lufs - measured_lufs
-linear_gain = 10 ** (gain_db / 20)
-```
-
-When both clips are local authored `<audio>` elements with stable ids, use the
-CLI instead of transcribing that arithmetic by hand:
-
-```bash
-npx hyperframes normalize-audio --reference target-audio --target user-audio
-npx hyperframes normalize-audio --reference target-audio --target user-audio --write
-```
-
-The first command is a dry run. The second writes only the target's
-`data-volume`, after accounting for both existing gains and refusing a boost
-that would clip or exceed Studio's ceiling. Always choose the reference from the
-author's stated intent; the command does not guess which clip should define the
-mix.
-
-Studio's clip-gain fader uses `0 dB` / linear gain `1` at its physical midpoint
-and provides up to `+12 dB` on the upper half. After changing gain, measure the
-served preview/render bytes again. If a listener still hears a mismatch, trust
-the report and first verify the asset URL and bytes are current; do not explain
-it away with matching peaks or a stale proxy measurement.
-
-All verified with ffmpeg 8.1.1. `-hide_banner` keeps the output readable;
-`volumedetect` prints to stderr, so do not silence it with `-v error`.
-
-### Band energy, in proportional bands
-
-**Use proportional bandwidths or the numbers lie.** A fixed 2000 Hz-wide band at
-10 kHz collects more energy than a 1200 Hz-wide band at 6.3 kHz for no reason but
-its width, which manufactures a high-frequency excess that is not there. One
-third of an octave is `f × 0.2316`.
-
-```bash
-third() {
-  w=$(python3 -c "print(round($2*0.2316))")
-  ffmpeg -hide_banner -i "$1" -af "bandpass=f=$2:width_type=h:w=$w,volumedetect" \
-    -f null - 2>&1 | grep -m1 mean_volume
-}
-third voice.wav 200     # weight / boom
-third voice.wav 3200    # presence / harshness
-```
-
-Read them as a shape across 100 / 200 / 400 / 1k / 3.2k / 7k, and read the shape
-against a reference from the list above — never on its own.
-
-### The noise floor, and what is in it
-
-```bash
-ffmpeg -hide_banner -i voice.wav -af astats=metadata=1 -f null - 2>&1 | grep -i 'noise floor'
-```
-
-`-inf` means digital silence in the gaps: no additive noise, so rumble, hiss and
-room tone are all ruled out in one command. A real number is the level of
-whatever is sitting under the voice. To see its _shape_, cut a pause out with
-`-ss`/`-t` and run the band recipe on that slice alone.
-
-### Level over time
-
-```bash
-ffmpeg -hide_banner -i voice.wav -af ebur128=framelog=quiet -f null - 2>&1 | tail -6
-```
-
-LRA under ~3 LU is even. Then window it, because LRA hides a single sagging
-passage:
-
-```bash
-for s in 0 1.2 2.4 3.6 4.8 6.0; do
-  ffmpeg -hide_banner -ss $s -t 1.2 -i voice.wav -af volumedetect -f null - 2>&1 |
-    grep -m1 mean_volume
-done
-```
-
-**A 4–6 dB spread across windows is normal speech**, not a defect — sentences
-decline as they end. Injected unevenness looks like 12 dB or more. Levelling a
-track that only has declination flattens the prosody and is heard as robotic.
-
-### Pitch, before blaming the low end
-
-```bash
-ffmpeg -hide_banner -i voice.wav -af "lowpass=f=400,astats=metadata=1" -f null - 2>&1 | grep -i 'peak level'
-```
-
-A voice has no energy below its own fundamental, so a "missing" 100 Hz on a
-speaker whose F0 is 210 Hz is the speaker, not a rolloff.
-
-The same fact runs the other way, and that direction is the trap: **a boost near
-the fundamental is indistinguishable from that voice being naturally chesty.**
-Both look like energy at F0, because both are.
-
-So the rule is symmetric, and the dangerous half is the second one:
-
-- Do not call a peak at F0 a defect on its own evidence.
-- **Do not dismiss one either.** "The peak is at 200 Hz, F0 is 185 Hz, therefore
-  it is the fundamental" is not a diagnosis — it is the same observation
-  restated, and it discards the one candidate most likely to be real. Boominess
-  _is_ excess energy at the bottom of a voice; that is what the word means.
-
-What you can do is measure how much, against the same file's midrange:
-
-```bash
-third voice.wav 200      # or the nearest 1/3-octave band to F0
-third voice.wav 1000
-```
-
-In an ordinary take these land within a couple of dB of each other. A low band
-sitting **more than about 4 dB above the 1 kHz band** is a strong boom or mud
-candidate. Measured across one voice damaged several ways: undamaged +0.9,
-harsh +0.6, dull +2.0; boomy +6.7, muddy +5.8. Treat the figure as indicative
-rather than a threshold — it is one speaker — but the separation is wide, and a
-reading up at +6 is worth raising even when you cannot explain it.
-
-It still cannot tell you whether a filter did that or the speaker did, so report
-it as a candidate. That is the whole answer here: measure it, name it, hand the
-choice to somebody who can hear it.
-
----
-
-## Then, and only then, the symptom table
-
-Measurement gives you the band and the kind. `SKILL.md`'s table and
-`presets.md`'s fuller one turn that into a fix. Going the other way round —
-picking a plausible fix and finding evidence for it — is how both wrong answers
-in the evaluation happened, and both were long, careful and confident.
-
-One habit that catches it: before applying anything, state what you would expect
-to measure **if you are wrong**, and check that too.

package/skills/hyperframes-audio/references/fx-registry.md

@@ -1,84 +0,0 @@
-# Effect registry
-
-Every effect, its parameters and the usable range of each. Values outside a range
-are clamped on read, so anything that parses is safe to realise. **AUTO** marks a
-parameter an automation lane can drive; anything unmarked cannot move over time
-(see the note at the bottom).
-
-Generated from `HF_AUDIO_FX` in `@hyperframes/core/audio-fx`, which is the source
-of truth — if this table and the code disagree, the code is right.
-
-## Filter — which frequencies a track may occupy
-
-| Effect      | Parameter                                                                                                   |
-| ----------- | ----------------------------------------------------------------------------------------------------------- |
-| `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, so a control would have moved nothing.
-
-## Dynamics — how level behaves over time
-
-| Effect       | Parameter                                                                                                                                                                      |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `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` go to −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, higher eases into it. `mix` below 1 blends the dry
-signal back in (parallel compression). `range` is how far down the gate pulls
-when closed — a gate that pulls all the way to silence sounds like a switch.
-
-## Nonlinear — changes the waveform's shape
-
-| Effect     | Parameter                                                                                                                                                                  |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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 and `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 — space and width
-
-| Effect   | Parameter                                                                                                                                                           |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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) |
-
-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, which is what makes a large room
-sound like a soft one. `feedback` near the top of its range is a very long tail;
-it 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, which 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:
-
-- **worklet processor options** — `compressor`, `limiter`, `gate` and `bitcrush`
-  are AudioWorklets configured wholesale, so **none of their parameters are
-  automatable at all**.
-- **a WaveShaper curve** — `saturate`'s `type`, `threshold` and `oversample`
-  rebuild the curve; only its `output` stage is a real param.
-- **a convolution impulse** — `reverb`'s `size` and `damping` regenerate the
-  impulse; `wet`/`dry` are gain stages and automate fine.
-
-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.