{"id":"4baa3049-d3fa-4daf-b8fd-2045ea97078a","entityType":"agent","slug":"clawhub-heygen-com-hyperframes-audio","name":"hyperframes-audio","canonicalUrl":"https://www.xpersona.co/agent/clawhub-heygen-com-hyperframes-audio","canonicalPath":"/agent/clawhub-heygen-com-hyperframes-audio","generatedAt":"2026-10-11T01:45:00.362Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:47:30.096Z","emptyReason":null},"description":"Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (``). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17fpgb0p797dzkbtbrxw5x1hh89qs64:hyperframes-audio","sourceUrl":"https://clawhub.ai/heygen-com/hyperframes-audio","homepage":"https://clawhub.ai/heygen-com/skills/hyperframes-audio","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/heygen-com/hyperframes-audio","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/heygen-com/skills/hyperframes-audio","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"hyperframes-audio technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:47:30.096Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:47:30.096Z","emptyReason":null},"stars":null,"forks":null,"downloads":1238,"packageName":null,"latestVersion":"1.0.15","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:47:30.031Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T22:47:30.096Z","lastCrawledAt":"2026-10-10T22:47:30.031Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T22:47:30.031Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.15","createdAt":"2026-10-10T18:44:55.961Z","changelog":"Synced from 3746703 (main)","fileCount":10,"zipByteSize":43042},{"version":"1.0.14","createdAt":"2026-10-10T05:07:18.487Z","changelog":"Synced from f46033d (main)","fileCount":10,"zipByteSize":42500},{"version":"1.0.13","createdAt":"2026-10-04T19:17:39.739Z","changelog":"Synced from 173103d (main)","fileCount":9,"zipByteSize":42232},{"version":"1.0.12","createdAt":"2026-09-27T21:19:32.845Z","changelog":"Synced from ff6e210 (main)","fileCount":9,"zipByteSize":42304},{"version":"1.0.11","createdAt":"2026-09-20T16:22:31.001Z","changelog":"Synced from 0c158be (main)","fileCount":9,"zipByteSize":42374},{"version":"1.0.10","createdAt":"2026-09-11T21:20:43.820Z","changelog":"Synced from b848d81 (main)","fileCount":9,"zipByteSize":42349},{"version":"1.0.9","createdAt":"2026-08-24T02:20:11.430Z","changelog":"Synced from 2685c8f (main)","fileCount":9,"zipByteSize":41855},{"version":"1.0.8","createdAt":"2026-08-22T12:17:25.678Z","changelog":"Synced from f0cc9b1 (main)","fileCount":9,"zipByteSize":40472}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17fpgb0p797dzkbtbrxw5x1hh89qs64:hyperframes-audio","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17fpgb0p797dzkbtbrxw5x1hh89qs64:hyperframes-audio` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/heygen-com/hyperframes-audio before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T01:45:00.355Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-hyperframes-audio/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:47:30.096Z","emptyReason":null},"readme":"Skill: hyperframes-audio\n\nOwner: heygen-com\n\nSummary: Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (``). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.\n\nTags: latest:1.0.15\n\nVersion history:\n\nv1.0.15 | 2026-10-10T18:44:55.961Z | user\n\nSynced from 3746703 (main)\n\nv1.0.14 | 2026-10-10T05:07:18.487Z | user\n\nSynced from f46033d (main)\n\nv1.0.13 | 2026-10-04T19:17:39.739Z | user\n\nSynced from 173103d (main)\n\nv1.0.12 | 2026-09-27T21:19:32.845Z | user\n\nSynced from ff6e210 (main)\n\nv1.0.11 | 2026-09-20T16:22:31.001Z | user\n\nSynced from 0c158be (main)\n\nv1.0.10 | 2026-09-11T21:20:43.820Z | user\n\nSynced from b848d81 (main)\n\nv1.0.9 | 2026-08-24T02:20:11.430Z | user\n\nSynced from 2685c8f (main)\n\nv1.0.8 | 2026-08-22T12:17:25.678Z | user\n\nSynced from f0cc9b1 (main)\n\nv1.0.7 | 2026-08-21T16:42:56.932Z | user\n\nSynced from 485c037 (main)\n\nv1.0.6 | 2026-08-19T22:08:59.891Z | user\n\nSynced from 228eabd (main)\n\nv1.0.5 | 2026-08-19T21:36:50.129Z | user\n\nSynced from b3c43e2 (main)\n\nv1.0.4 | 2026-08-18T14:17:55.492Z | user\n\nSynced from afafca4 (main)\n\nv1.0.3 | 2026-08-16T18:02:56.852Z | user\n\nSynced from 67edb01 (main)\n\nv1.0.2 | 2026-08-13T20:54:04.394Z | user\n\nSynced from e3ec48a (main)\n\nv1.0.1 | 2026-08-13T09:36:44.027Z | user\n\nSynced from d18cbcb (main)\n\nv1.0.0 | 2026-08-13T09:17:22.698Z | auto\n\nInitial release of hyperframes-audio.\n\n- Adds tools for mixing pre-placed audio in HyperFrames compositions.\n- Supports voiceover carves (frequency/level ducking using dynamic sidechain).\n- Implements effect chains, including EQ, compression, saturation, time effects, and automation envelopes, attached to audio/video elements.\n- Provides deterministic preview/render pipeline using Web Audio API; ensures WYSIWYG mixing experience across live and offline contexts.\n- Documents exact attribute specifications and effect parameters for integration and authoring tools.\n\nArchive index:\n\nArchive v1.0.15: 10 files, 43042 bytes\n\nFiles: references/attributes.md (6223b), references/diagnosis.md (12080b), references/fx-registry.md (7981b), references/presets.md (13155b), scripts/carve.mjs (23848b), scripts/carve.test.mjs (11818b), scripts/lib/main-module.mjs (479b), skill-card.md (1888b), SKILL.md (25976b), _meta.json (137b)\n\nFile v1.0.15:SKILL.md\n\n---\nname: hyperframes-audio\ndescription: >\n Use when audio already placed in a HyperFrames composition needs to be mixed:\n fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking,\n a music bed that fights a voiceover (voiceover carve), effects on a track\n (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser,\n bitcrush), automation envelopes drawn on a track's volume or any effect\n parameter, or one submix bus carrying a chain, a fader and an automation clock\n for several tracks at once (``).\n Don't use for sourcing or generating audio — finding BGM, SFX, or making a\n voiceover is `/media-use`. Don't use for clip timing or track layout, which is\n `/hyperframes-core`.\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.\n\n# HyperFrames Audio\n\nA mix is a set of relationships, not a stack of processors. Two tracks that each\nsound right alone can be unlistenable together, and the fix is almost never \"turn\none down\" — it is finding what they are fighting over and giving it to whichever\none needs it. Every tool here exists to express one of those relationships.\n\nEffects live on the element as `data-fx-chain`, and preview and render run the\nsame Web Audio graph — the studio in a live context, the engine in an offline one\ninside the browser it already drives. There is one implementation of each effect,\nso what you hear while scrubbing is what gets written. You never tune twice.\n\nClip timing remains `/hyperframes-core`: audio/video trims and source ranges use\n`data-start`, `data-duration`, and `data-media-start`, and crossfades overlap\nclips on different tracks. This skill owns placed-track fade-in/fade-out,\ncrossfade envelopes, track gain/track volume, volume and effect automation,\nducking/voiceover carve, and the effect chain. `/media-use` owns sourcing,\ngeneration, and preprocessing.\n\nConstant `data-playback-rate` (`0.1..10`) is render-safe for picture and\npitch-preserved sound when matching audio/video elements use the same timing,\nsource offset, and rate. A speed ramp is a `rate` lane in `data-automation`\n(see `docs/reference/speed-ramps`); it wins over the constant and keeps pitch\nin preview and render. HyperFrames does not\nprovide automatic waveform sync or drift correction.\nFor copyable cut/crossfade/retime recipes, use `/hyperframes-core` → `references/creator-editing-recipes.md`.\n\nThree attributes carry everything, on the audio/video element itself — or, for\nthe first two, on an `` bus (see \"One bus for many tracks\"):\n\n| Attribute | Holds |\n| ----------------- | --------------------------------------------------------- |\n| `data-fx-chain` | the effects, in signal order |\n| `data-automation` | envelopes on this track's volume or its effect parameters |\n| `data-fx-carve` | the carve's own settings, so it can be re-derived |\n\nThe shipped effect families are gain, EQ (highpass, lowpass, peaking, shelves),\ncompressor, limiter, truepeak (lookahead true-peak limiter), gate, saturate, delay, reverb, chorus, phaser, and bitcrush.\n\nExact JSON for each, and the rules a lane must satisfy: `references/attributes.md`.\nEvery effect with its parameters, ranges and units: `references/fx-registry.md`.\nHow to work out what is wrong with a file you cannot hear:\n`references/diagnosis.md`.\n**Presets, named jobs and one-knob profiles, plus a symptom-to-fix table:\n`references/presets.md`** — read that before hand-building a chain, because one\nof the presets or named jobs usually already names the problem.\n\n## How it fits together\n\nTwo authoring surfaces write those attributes; two runtimes read them through the\nsame builders. That shared middle is why preview predicts the render.\n\n```mermaid\nflowchart TB\n voice[\"voice track
media file\"]\n bed[\"music bed
media file\"]\n\n subgraph AUTHOR[\"Authoring — the only things that write attributes\"]\n panel[\"Studio
Voiceover carve control\"]\n script[\"scripts/carve.mjs
detects the pair\"]\n analysis[\"core/audioCarve.ts
carveProfile · analyseCarveBands
analyseCarveDuck · analyseCarveDynamics\"]\n panel --> analysis\n script --> analysis\n end\n\n voice --> analysis\n bed --> analysis\n\n subgraph ATTRS[\"Written onto the bed element\"]\n carveAttr[\"data-fx-carve
sources · strength\"]\n chainAttr[\"data-fx-chain
peaking xN + gain, tagged fromCarve\"]\n autoAttr[\"data-automation
a lane per carved parameter\"]\n end\n\n analysis --> carveAttr\n analysis --> chainAttr\n analysis --> autoAttr\n\n subgraph SHARED[\"One implementation, read by both\"]\n build[\"audioFxGraph.ts · buildFxChain\"]\n sched[\"audioFxAutomation.ts · scheduleChainAutomation\"]\n end\n\n chainAttr --> build\n autoAttr --> sched\n\n build --> preview[\"Preview
live AudioContext
attachElementFxChain\"]\n sched --> preview\n build --> render[\"Render
OfflineAudioContext in the headless browser
applyAudioFxChain\"]\n sched --> render\n\n preview --> heard[\"what you hear while scrubbing\"]\n render --> wav[\"processed WAV
+ chainTailSeconds so the mix lets the tail through\"]\n wav --> mix[\"engine · audioMixer
volume lane baked into the PCM here, not in the graph\"]\n mix --> out[\"the rendered mix\"]\n\n edit[\"editing the attribute mid-playback\"] -.->|MutationObserver| preview\n```\n\nThe carve's own settings are never read at playback — the chain and lanes it\nproduced are what play. `data-fx-carve` exists so strength can be changed on an\nexisting carve instead of guessed back out of the filters.\n\nInside a carved bed the signal runs through the dips first, then the level match,\nthen anything you built yourself — which is why a limiter you add still acts as\nthe last ceiling:\n\n```mermaid\nflowchart LR\n src[\"decoded bed\"] --> p1[\"peaking
400 Hz\"]\n p1 --> p2[\"peaking
1 kHz\"]\n p2 --> p3[\"peaking
1.6 kHz\"]\n p3 --> g[\"gain
level match\"]\n g --> hand[\"your own effects
e.g. limiter\"]\n hand --> dest[\"track gain, then out\"]\n\n l1[\"lane fx.n1.gain\"] -.->|\"envelope of the voice's
level in that band\"| p1\n l4[\"lane fx.n4.gain\"] -.->|\"how far the bed
ducks overall\"| g\n```\n\n## First, work out what is wrong\n\nThe table below starts from \"it sounds boomy\" — which presumes somebody already\nlistened and said so. Handed a file and \"fix this\", you have no such sentence\nand you cannot listen, so you have to measure. One rule governs all of it:\n\n> **The absolute spectrum of a single unknown voice cannot be diagnosed.**\n> Formants are ±10 dB, fundamentals run 85–255 Hz, and sentences decline 5–6 dB\n> as they end. Every one of those reads as a defect on its own, and every one of\n> them is the speaker.\n\nSo compare, and compare against something **inside the same file**: the clean\noriginal if it exists, otherwise the pauses — whatever is audible in a gap is\nadditive, and the gap's spectrum is the channel rather than the voice. Comparing\nagainst a published average spectrum or a synthesised control voice does not\nwork: two speakers differ by more than most defects, and both wrong answers in\nthe evaluation behind this guidance came from exactly that.\n\nWhen there is no original and no usable silence, a static tonal defect is\ngenuinely under-determined. Say so and offer the readings that fit, rather than\npicking one and building a chain on it.\n\nCommands, traps and worked recipes: **`references/diagnosis.md`**. Read it\nbefore diagnosing a file nobody has described.\n\n## Start from the symptom\n\nOnce you know the band and the kind, name what is wrong with the audio. Most bad audio is\none or two of these, and each has a shipped answer:\n\n| It sounds like | Reach for |\n| ---------------------------------- | -------------------------------------------------- |\n| Hum or thump underneath | `rumble-cut`, or a `highpass` at 80 Hz |\n| Boomy, chesty | **Tame Boominess** job (200 Hz) |\n| Muffled, behind cardboard | **Reduce Mud** job (250 Hz) |\n| Words hard to make out | **Add Clarity** job (3 kHz), or carve the bed |\n| Harsh and tiring | **Soften Harshness** job (3.2 kHz) |\n| Some words much louder than others | **Evenness** on a compressor, or Even Out Levels |\n| Room tone between sentences | `room-gate` |\n| Voice and music fighting | **Voiceover carve** — not an EQ on either |\n| Dry, recorded nowhere | `room-tight` or `room-natural` |\n| Just \"amateur\" | `voice-clean`, which is four of the above in order |\n\nFull catalogue, what each preset contains, the band vocabulary, and what is\ndeliberately NOT covered (de-essing, noise removal, tone match):\n`references/presets.md`.\n\nSubtract before you add, level after you filter, relationships after level,\ncharacter and ceiling last. Each step changes what the next one hears — a\ncompressor set before a high-pass spends its time chasing rumble.\n\n## Reach for a family by the problem, not the name\n\n**Filters** (`highpass`, `lowpass`, `peaking`, `lowshelf`, `highshelf`) decide\nwhich frequencies a track is allowed to occupy. This is the first tool for two\nsources colliding, because collisions happen in bands: a bed and a voice both\nwant 1–3 kHz, and taking that from the bed costs the bed far less than turning\nthe whole thing down costs the mix. A high-pass on a voice is the standard fix\nfor rumble; a low-pass darkens or muffles deliberately.\n\n**Dynamics** (`gain`, `compressor`, `limiter`, `truepeak`, `gate`) decide how a track's level\nbehaves over time. Compression narrows the distance between loud and quiet so the\nquiet parts can come up. A limiter is a ceiling — it does not shape anything, it\nguarantees nothing gets past. `limiter` follows the level, so for a delivery\nceiling use `truepeak`, which looks ahead and measures the inter-sample peak. It\nholds a 4x estimate at the ceiling, not the waveform itself, so full-band noise can\nend up to 1.7 dB over: under a hard delivery limit set the ceiling at least 2 dB\nbelow it. A gate removes what is below a threshold, which is\nhow you silence room tone between phrases. `gain` is a plain level stage, and it\nis what an automation lane rides when a track has to move out of the way.\n\n**Nonlinear** (`saturate`, `bitcrush`) changes the waveform's shape, which adds\nharmonics that were not there. Reach for it when a track needs character or\ngrit rather than correction — and remember it is generative: it makes a thin\nsource denser, not cleaner.\n\n**Time** (`delay`, `reverb`, `chorus`, `phaser`) puts a track in a space or gives\nit width. These are the ones that most easily wreck a mix, because a tail or a\ndetuned copy occupies the same room a voice needs. Use them on the thing that\nshould sit _behind_ something else, and keep the wet amount lower than sounds\nright in isolation.\n\nThe chain is serial: each effect processes what the one before it produced. So\ncorrective filtering goes early, character in the middle, and a limiter last\nwhere it can actually act as a ceiling.\n\n## Voiceover carve\n\n**The problem it solves.** A music bed under a voice makes the voice hard to\nfollow. The reflex is to duck the whole bed, which works and costs the bed all of\nits presence — the music goes limp for the entire voiceover. But the voice does\nnot need the whole spectrum. It needs the few bands it actually occupies. Carve\ntakes only those, and the bed keeps its low end and its top, so it is still music\nwhile the voice is still intelligible.\n\n**It is a relationship, not an effect.** The settings live on the _bed_ — the\ntrack that gets processed — and they name the voices to listen to, exactly as a\nsidechain compressor does: you select the track that gets quieter and pick what\nmakes it quieter. **Never put a carve on a voice track.** A voice carved against\nitself is a bug, not a subtle mix choice.\n\n**Every voice, not one of them.** `sources` is a list, because a bed usually runs\nunder a whole sequence — a narrator, an interview answer, a second presenter. They\nare summed onto the bed's own clock before anything is measured (`mixCarveSources`),\nso one analysis covers all of them: the bands come from all the speech there is, and\nthe envelopes rise wherever any of it is happening. Voices that never play while the\nbed does are left out; they cannot mask it.\n\n**A carve against more than one clip id is wrong. Group the clips and carve\nagainst the group.** This is an invariant, not a tip. Naming clips one by one has\nto be exhaustively right and stays right only until the next edit — a fourth\nnarration clip added later plays outside the carve's awareness, and the bed\nfails to duck under it silently. Naming the group instead resolves membership at\nanalysis time, so a clip added to the group later is covered without touching\n`sources` at all:\n\n```html\n\n\n\n\n\n\n```\n\nA `sources` list naming two or more plain clip ids instead of a group is caught\nby the `audio_carve_ungrouped_sources` lint rule — it still works, but it is the\nversion that silently rots when a clip is added.\n\n**Keep the carve group a voice group: no bed, no SFX, no music.** A group id in\n`sources` resolves to every _current_ member on _every_ analysis, so the group\nyou name is the group you get later — not the tracks that were measured when it\nwas written. Two ways that bites:\n\n- **The bed in its own source group.** It is handed to itself as a voice and\n carved against its own content — the \"never carve a track against itself\" rule\n arriving one re-analysis later.\n- **An SFX or music clip in the voice group.** It enters the sidechain on the\n next analysis and the bed starts ducking under a whoosh, even though the run\n that wrote the attribute never measured it.\n\nBoth are invisible at the moment the carve is written: the analysis sums the\nvoices it detected and never round-trips through group resolution, so the first\npass is genuinely correct and only the next one is wrong. So give each role its\nown group — `music` for the bed, `voiceover` for the narration, `sfx` for the\nhits — and keep the group named in `sources` holding nothing but voices.\n\n`carve.mjs` refuses to write the group form when it sees either case, records\nclip ids, and says on stderr which member blocked it. The\n`audio_carve_ungrouped_sources` rule then points at the arrangement instead of\nthe CLI quietly persisting a wider carve than it measured.\n\nA voice that this run left out is **not** one of these cases and does not block\nthe group form: `carve.mjs` only analyses voices that overlap the bed, and\npicking up a clip that plays later without an edit to `sources` is the whole\nreason to name the group.\n\n### One bus for many tracks\n\nMembership alone is enough to carve against, as above — but add an\n`` element with that id and the group becomes a real submix bus:\none chain, one fader, one automation clock for every member.\n\n```html\n\n\n\n\n```\n\n**Reach for the bus when the same treatment belongs on several tracks.** Four\nnarration clips that each want the same compressor is four chains to keep in\nstep, and they drift the moment one is edited; on the bus it is one chain, and\nthe compressor sees the whole voice rather than each clip in isolation — which is\nthe point, since a compressor cannot ride a sequence it only hears a third of.\nPer-clip chains remain right for what is genuinely per-clip: one noisy take that\nneeds its own de-esser.\n\n| On the bus | Does |\n| ----------------- | ----------------------------------------- |\n| `data-fx-chain` | one chain over the summed members |\n| `data-automation` | envelopes on the bus, in COMPOSITION time |\n| `data-volume` | one fader for every member (default 1) |\n| `data-label` | the display name; falls back to the id |\n| `data-hidden` | drops every member from the mix |\n\n**Group automation is composition time, not clip time.** A bus has no\n`data-start` — members are already at their composition positions when they\nreach it — so `t: 0` in a group lane is the start of the composition, not of any\nclip. A lane on a clip is clip-local; the same numbers mean different instants on\nthe two, which is the one thing to get right when moving an envelope from a clip\nup onto its bus.\n\n**A carve stays on the clip.** `data-fx-carve` is not a group attribute. The bed\nbeing carved is a single track, and it is that track which carries\n`data-fx-carve` — pointed AT a group, per the rule above. Group and carve meet in\n`sources`, not on one element. A carve written onto a bus is half an effect\napplied twice: the level half measures the bed's own audio, which a bus has none\nof, so only the filters survive — and a bus and its members are one signal path,\nso the bed then runs through the bus's filters AND its own. The\n`audio_group_carve_attr` lint rule catches it.\n\n**One clip is not a bus.** A group exists to give several tracks one chain, one\nfader and one clock. Wrapping a single clip in a bus buys nothing the clip's own\n`data-fx-chain` does not already do, and it doubles the places a later edit has\nto land. The one reason to do it anyway: a bus's automation clock is composition\ntime, so a single-member bus is how a lane on that clip gets composition-time\ntiming.\n\n**One knob.** `strength` is 0..1 and derives everything: how deep to cut, how\nmany bands, how wide, how far to favour intelligibility over raw voice energy,\nhow far the level may drop, how far under the voice to aim. Those six move\ntogether in any real mix — a gentle carve is a shallow cut in few bands with\nlittle ducking, a hard one is deeper in more bands with more — so they are one\nrelationship written once, in `carveProfile`. `carve.mjs` defaults to `0.8` —\nsix bands from 250 Hz to 2.5 kHz cut about 7 dB each and 15 dB at 1.6 kHz, with\n19 dB of level room — because a bed under narration has to get out of the way\nfirst and be music second; `0.25` (a 6 dB dip in three bands, 6 dB of room) kept\nthe bed present but still let it fight the voice, and was judged too weak in\npractice. At `0.5` the dip reaches 10 dB, which is where a carve starts being\nheard as an effect rather than as room for the voice. Drop the strength when the\nbed is the point and the voice is sparse. `0` is spectral only — one band, no\nlevel match at all.\n\n**Carve by default — required whenever music plays under a voice.** A bed\nunder any voice track (narration, avatar speech, interview, voiceover) gets a\ncarve as part of finishing the mix, not as a polish step to get to if there is\ntime. Place both tracks, run the command below (default strength `0.8`; add\n`--bed` / `--voice` when detection picks wrong), confirm the written\n`data-fx-carve`, `data-fx-chain` and `data-automation` with `npx hyperframes check`,\nand only then render. A volume duck on its own is not a finished mix: it leaves\nthe voice and the bed fighting in the 1–3 kHz band and costs the bed all of its\npresence for the whole voiceover. Skip the carve only when there is no voice for\nthe music to sit under — a music video, a title card, a montage cut to the track.\n\n**It always follows the voice.** There is no static mode: a fixed depth thins the\nbed through every pause, and once you have heard both there is no reason to want it.\nEvery value becomes an envelope of the speech's own level — silence leaves the bed\nalone, a loud passage pushes the carve to full depth — written as ordinary automation,\nwhich is why the lanes show up in the timeline and can be edited afterwards.\n\n**Level matching is part of it.** Spectral carving cannot fix a bed that is\nsimply louder than the voice. So the carve also measures how far over the voice\nthe bed sits and writes a `gain` stage driven by an envelope. That envelope releases slowly on\npurpose — music that snaps back to full the instant a word ends sounds like a\nmachine doing it.\n\n**Running it.** In Studio the carve is one module at the top of a track's effect\nrack — voice, strength, and the analysis it produced, in one card. It is\nthere whenever another track could be the voice, and a bed with exactly **one**\ncandidate above it is carved by default, at the default strength:\nthat is what a bed under narration wants, and the module is where you change or\nswitch it off. Several candidates leaves the picker waiting rather than guessing.\nHeadless —\nwhich is the path when you are authoring a composition rather than editing one:\n\n```bash\nnode /scripts/carve.mjs --comp index.html\n```\n\nThat is the whole command. It finds the voice and the bed itself, carves\nat the default strength, and prints what it decided:\n\n```\nbed music-bed (name looks like music)\nvoice narration (only track left)\ncarve strength 0.8, 1 voice\nbands 250Hz -7.4dB q2.06, 400Hz -7.4dB q2.06, 630Hz -7.4dB q2.06, 1000Hz -7.4dB q2.06, 1600Hz -14.8dB q2.06, 2500Hz -7.4dB q2.06\nlevel 273-point envelope, floor -19.2 dB\n```\n\nName the tracks with `--bed` / `--voice` (repeatable) when the automatic choice is\nwrong, `--strength` to push it, `--dry-run` to see that report and write nothing.\n\n**How it picks the tracks.** Names first, because that is what you already told it\nand the answer is explainable — `classifyAudioName` in core, the same classifier\nStudio's own picker uses, so the two cannot disagree. A track whose id or filename\nlooks like music (`music`, `bgm`, `bed`, `score`…) is the bed; everything else that\nplays over it and is not SFX-shaped is a voice. Audio elements are preferred: video\ncounts only when no audio track is left to be the voice, or every B-roll clip in the\ncomposition would read as somebody talking. **It refuses when it cannot tell which\ntrack is the bed** rather than carving the wrong one — typing one id is cheap.\n\nSame analysis functions as the panel, so the result is identical. Needs `ffmpeg`\non PATH and `@hyperframes/core` installed in the project (`npm i -D\n@hyperframes/core`) — the CLI inlines core rather than shipping it, so it cannot\nbe borrowed from there.\n\n**What it writes** is an ordinary chain of peaking filters plus a gain stage,\ntagged `fromCarve`. That tagging is the whole trick: a re-run replaces the\nprevious carve and leaves every effect you built by hand — and every lane you\ndrew by hand — exactly where it was. So re-carving at a new strength is safe and\nrepeatable, and `data-fx-carve` exists so the settings can be read back rather\nthan guessed from the filters.\n\n## Automation\n\nA lane is a set of breakpoints on one parameter: `{t, v}` in clip-local seconds\nand the parameter's own units. Targets are `volume` for the track's level, or\n`fx..` for an effect's knob.\n\n**Only some parameters can be automated, and a lane on the others is silently\ninert.** A knob is automatable when a Web Audio `AudioParam` backs it. The\nworklet-based effects — `compressor`, `limiter`, `truepeak`, `gate`, `bitcrush` — expose\nnone at all, so no lane on any of their parameters will ever move: to make a\ncompressor's behaviour change over time, automate a `gain` stage before it\ninstead. `references/fx-registry.md` marks every parameter.\n\n## Verify\n\nAlmost no static gate covers the mix. The linter reads `data-automation` for\nexactly one conflict — `audio_volume_double_automation`, a volume lane on a track\nthat also has a GSAP tween on `volume`, where the lane wins and the tween is\nignored — plus `audio_volume_tween_overrides_gain`, an authored `data-volume`\non a track whose `volume` is tweened, where the tween's values are absolute and\nreplace that gain instead of scaling it. Nothing validates the\nchain or the effect lanes at all. What\nenforces those is the render: a chain it cannot parse fails the whole mix rather\nthan quietly writing the dry signal, because a mix that sounds plausible and is\nwrong is worse than a refusal. Preview is the opposite by design: an unreadable\nchain plays dry so the composition stays workable.\n\nA lane pointing at a node the chain does not have is pruned on read, not an\nerror — so a typo'd `nodeId` costs you the envelope silently. Read the ids back\nout of the chain rather than assuming what was minted.\n\nEffects with a tail (`reverb`, `delay`) make the rendered track **longer** than\nits source, and the mix is told how much by the chain. So a bed with reverb no\nlonger ends exactly at its `data-duration`; that is expected, not a bug.\n\nBeyond that, a mix is verified by rendering and listening. For a carve: the voice\nshould be legible without the bed sounding hollowed, and the bed\nshould come back up between phrases rather than staying flat. If the bed sounds\nnotched rather than simply quieter under the voice, the strength is too high —\nthat is the one failure mode with an obvious sound.\n\nFile v1.0.15:_meta.json\n\n{\n \"ownerId\": \"kn77d06grj6xqp3dqwkk4bavhn89pegt\",\n \"slug\": \"hyperframes-audio\",\n \"version\": \"1.0.15\",\n \"publishedAt\": 1791657895961\n}\n\nFile v1.0.15:references/attributes.md\n\n# The three audio attributes\n\nAll three go on the `