[jerrai-bot-heygen]

What

hyperframes audio <file> --read --layer music|sfx|voice: a file the caller declares holds one layer is read whole as that layer, with no stem separation and nothing uploaded.

Why

audio --read reads music only from separated stems, so a file known to be a single music, effect or voice take still pays for separation. Rory OK'd this proposal (C0BEH487Q7R, 2026-11-07). The consumer is heygen-com/experiment-framework#66322, held until this ships; it calls hyperframes audio <file> --read --quality local --layer <voice|sfx|music> [--range a,b] [--transcript words] once audio --help lists --layer.

Related work

Consumer: experiment-framework#66322.

How

• commands/audio.ts: --layer parsed by parseLayer; unknown values fail with --layer is music, sfx, voice; got <value>; --layer without --read is rejected. --help text added.
• audio/read/read.ts: analyzeLayer decodes the whole file and runs the existing analysis on it: music through readMusic (sections, tempo, levels), voice through voiceFromWords/voiceFromActivity (words and pauses), sfx through findEffects. Other layers are null.
• types.ts: ReadAudio.layer? records the declared layer, present only when declared. The cache entry must match the declared layer, so a layered read never reuses a mix read and vice versa.
• No change without the flag: same code path, same JSON (no new field), same cache behaviour. Docs: docs/packages/cli.mdx.

Test plan

• Unit tests added/updated: audio/read/read.test.ts (music, voice and sfx read whole with zero stem requests, cache kept apart from a mix read, no layer field when undeclared); commands/audio.command.test.ts (each layer passed through, absent flag, bad value, --layer without --read).
• vitest run on those two files: 23 passed. oxfmt and oxlint clean on changed files.
• Manual testing performed
• Documentation updated

— Jerrai

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 7, 2026, 2:46 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 2 nits · head 3a756902

No-flag path is unchanged (base() adds no layer, cache check entry.analysis.layer === layer holds for old entries), and analyzeLayer never reaches stemsFor/describeStems, so nothing uploads at any --quality. CI ran the new suites with ffmpeg (read.test.ts 17 tests, flake gate 10/10 on both files).

• nit: the text header for a layered read is still <file> · N s · not separated (format.ts header); only --json shows the declared layer. A · read as <layer> suffix would make text-mode output say why nothing was separated.

Scope

Read in full: audio/read/read.ts, commands/audio.ts, types.ts, both tests, docs hunk. Checked format.ts against null voice/effects/music. No prior reviews on the PR.

[heygengenesis]

nit: layered and mix reads share one cache slot (jsonPath/textPath are keyed only on name + sha, line 465), so they are never confused but they do overwrite each other: reading the same file alternately with and without --layer (or with two different layers) re-analyses every time, and a textPath handed out by the earlier read now holds the other read. Harmless for the Cut Room consumer, which only reads its own single-layer takes with the flag; adding the layer to stem (e.g. ${stem}-${layer}) would keep both. Stems on disk are untouched either way, so no re-upload.