media-use

eval-report.html

SFX Credits

All sound effects in this directory are sourced from Pixabay and used under the Pixabay Content License.

The Pixabay license allows free use for commercial and non-commercial purposes without attribution, but attribution is appreciated and given here for transparency.

Files

The following .mp3 files are bundled with this skill:

• chime.mp3
• click.mp3 / click-soft.mp3
• error.mp3
• glitch-1.mp3 / glitch-2.mp3 / glitch-3.mp3
• impact-bass-1.mp3 / impact-bass-2.mp3
• key-press.mp3
• notification.mp3
• ping.mp3
• pop.mp3
• riser.mp3
• sparkle.mp3
• typing.mp3
• whoosh.mp3 / whoosh-short.mp3 / whoosh-cinematic.mp3

See manifest.json for per-file metadata (duration, energy character, recommended use).

License

All files are distributed under the Pixabay Content License, which permits:

• Commercial and non-commercial use
• Modification and remixing
• Redistribution as part of derivative works (such as videos rendered with HyperFrames)

without any attribution requirement.

{
  "chime": {
    "file": "chime.mp3",
    "duration": 2.5,
    "description": "Soft melodic chime — gentle positive beat: success/confirmation or a lighthearted transition. Sync to the visual moment."
  },
  "click-soft": {
    "file": "click-soft.mp3",
    "duration": 0.37,
    "description": "Quiet short click — low-key UI tap / soft selection. Short accent, sync exactly to the on-screen action."
  },
  "click": {
    "file": "click.mp3",
    "duration": 0.37,
    "description": "Crisp UI click — button press, toggle, selection. Short accent, sync exactly to the on-screen action."
  },
  "error": {
    "file": "error.mp3",
    "duration": 1.62,
    "description": "Negative / error tone — failure state, a 'wrong' beat, or a glitchy interruption."
  },
  "glitch-1": {
    "file": "glitch-1.mp3",
    "duration": 2.64,
    "description": "Punchy digital glitch — hard-cut accent or sudden reveal. Trigger on the hit; let the decay bleed into the next shot (J-cut)."
  },
  "glitch-2": {
    "file": "glitch-2.mp3",
    "duration": 3.5,
    "description": "Harsh, longer glitch — chaotic / jarring transition or a distorted reveal."
  },
  "glitch-3": {
    "file": "glitch-3.mp3",
    "duration": 3.1,
    "description": "Low-key glitch texture — subtle digital shift, minimal transition that sits under other audio."
  },
  "impact-bass-1": {
    "file": "impact-bass-1.mp3",
    "duration": 2.12,
    "description": "Bass impact hit — logo/hero snap, headline slam. Trigger on the visual landing; decay carries into the next shot (J-cut)."
  },
  "impact-bass-2": {
    "file": "impact-bass-2.mp3",
    "duration": 2.59,
    "description": "Bass impact with a short swell — brief anticipation then a deep hit. Place so the peak lands on the reveal."
  },
  "key-press": {
    "file": "key-press.mp3",
    "duration": 0.4,
    "description": "Single key press — one keystroke / terminal-input beat. Short accent, sync to the typed character."
  },
  "notification": {
    "file": "notification.mp3",
    "duration": 2.46,
    "description": "Notification chime — alert, message-in, toast/badge appears. Sync to the element entering."
  },
  "ping": {
    "file": "ping.mp3",
    "duration": 1.32,
    "description": "Sharp electronic ping — punchy accent on a key reveal or data point. Sync to the beat."
  },
  "pop": {
    "file": "pop.mp3",
    "duration": 0.72,
    "description": "Quick pop — element appear/spawn, chip/tag/badge in. Small precise accent, sync to the pop-in."
  },
  "riser": {
    "file": "riser.mp3",
    "duration": 10.03,
    "description": "Long cinematic riser (~10s build, peak at the end). Trigger at (climax_time − 10.03s) so it crests exactly on the reveal."
  },
  "sparkle": {
    "file": "sparkle.mp3",
    "duration": 1.8,
    "description": "Bright sparkle / shimmer — magical reveal or 'shine' highlight on a hero element. Sync to the highlight."
  },
  "typing": {
    "file": "typing.mp3",
    "duration": 1.5,
    "description": "Typing burst (~1.5s of keys) — keyboard / code typing reveal, text-being-typed beat. Start as the text begins typing."
  },
  "whoosh-cinematic": {
    "file": "whoosh-cinematic.mp3",
    "duration": 5.54,
    "description": "Cinematic whoosh build (~5.5s) — sweeping scene transition. Align so the swell peaks on the cut."
  },
  "whoosh-short": {
    "file": "whoosh-short.mp3",
    "duration": 0.57,
    "description": "Short whoosh — quick swipe/slide accent, fast element move, snappy transition. Sync to the motion."
  },
  "whoosh": {
    "file": "whoosh.mp3",
    "duration": 0.57,
    "description": "Punchy whoosh/impact — fast reveal or hard transition accent. Sync to the motion."
  }
}

Background music (BGM)

One music bed per composition, produced by the shared audio engine (scripts/audio.mjs → scripts/lib/bgm.mjs). Two routes, chosen by the engine's one switch — whether a HeyGen credential is present:

• HeyGen retrieval — the default when credentialed. Search HeyGen's music catalog by mood, download the top track. No generation; same ~/.heygen / $HEYGEN_API_KEY credential as TTS.
• Local generation (Lyria → MusicGen) — the fallback when there is no credential (or when asked for explicitly). Generate a WAV from a mood prompt. There is no npx hyperframes bgm command; the engine spawns scripts/lyria-recipe.py or an inline MusicGen script directly.

Run the Preflight first — no credential is not a green light to silently generate locally. Before generating, complete the sign-in Preflight (see ../../SKILL.md → Preflight): run npx hyperframes auth status, recommend signing in, and STOP for the user's choice (sign in for HeyGen's music library, or continue offline with local generation). This applies to a one-off "generate a BGM" request just as much as inside a full workflow.

Driving it from the request

audio_request.json → bgm: { mode?, query?, prompt? }:

• mode — retrieve | generate | none. Omit for auto (retrieve when credentialed, else generate). An explicit retrieve is strict: no credential ⇒ skip, never a detached generate (so a caller with no wait-bgm step, e.g. product-launch, can't get a pending job it won't await).
• query — the mood, used for retrieval and as a fallback prompt seed (e.g. a storyboard's music: field, falling back to message → arc → "calm cinematic underscore").
• prompt — an explicit full prompt for generation; omit and the engine infers one (see Mood inference). Optional blob / archetype / arc feed that inference.

Both routes keep a file of yours already at the output name: the engine writes the next free name (track-2.mp3), reports it as an anomaly, and bgm.path carries the real path.

HeyGen retrieval (default)

searchSounds(query, "music", { limit: 5 }) → GET /audio/sounds?query=<mood>&type=music&limit=5. Take the top result (ranked by score), download its presigned audio_url → assets/bgm/track.mp3. Synchronous. No match → skip (BGM is optional; never fail the render over it). Cue written to audio_meta.json:

{
  "path": "assets/bgm/track.mp3",
  "volume": 0.12,
  "mode": "retrieve",
  "query": "calm cinematic underscore",
  "duration_s": 42.0,
}

volume comes from the engine's bgmDefaultVolume(): BGM_BED_VOLUME (currently 0.12 ≈ -18 dB — a bed under the voice) under narration, BGM_SILENT_VOLUME (currently 0.9) for a silent film (no voice). Tune those constants in scripts/lib/bgm.mjs, not call sites. An explicit volume in audio_meta.json always overrides this default. bgm_pending is false — the file is on disk when the engine returns.

For short launch videos, do not assume the beginning of the retrieved file is the best edit point. Check the opening against later five-second sections. If the track starts with a quiet build but a later section has a stronger, clean musical entrance, trim from that section and apply a short fade-in and longer fade-out. Repeat this check whenever the composition duration changes; the final music file must cover the full cut without a silent tail.

Local generation (fallback) — Lyria → MusicGen

Spawned detached so voice work isn't blocked; audio_meta.bgm_pending: true and bgm_pid / bgm_log are set until it finishes. Run scripts/wait-bgm.mjs before assembling — it polls the output file / process / log, detects crashes, and writes bgm_status.json (status: ready | failed | timeout | disabled). A failed/absent track is simply omitted; it never blocks voice/SFX.

Output → assets/bgm/track.wav, target = total voice duration. MusicGen generates one seed clip (≤28–30s, under the decoder's positional limit) then crossfade-loops it up to the target (or trims down if shorter), avoiding per-segment seams. Backend selection is by what can actually run: Lyria only when import google.genai succeeds, else MusicGen; if neither can be made to run, BGM is skipped (voice + SFX still render).

Mood inference (the generate prompt)

inferBgmPrompt() in scripts/lib/bgm.mjs: an explicit prompt wins; otherwise industry-keyword base → narrative-archetype shape → emotional-arc tiebreaker.

Archetype then reshapes the arc — PAS → "MINOR to MAJOR" build; BAB / future-pacing → aspirational rising; feature-cascade → +10 BPM driving; demo-loop → −8 BPM minimal. The emotional arc breaks remaining ties (tension→relief, excitement, trust/reassurance).

Lyria knobs (direct recipe use)

The engine bakes BPM / scale into the prompt text (via the inference above) and passes only --output / --duration / --prompt to the recipe. If you invoke scripts/lyria-recipe.py directly you can also set: --bpm (90–110 calm, 110–130 energetic), --brightness (0–1, ≥0.7 promotional), --density (0–1, higher = fuller), --scale (MAJOR / MINOR / PENTATONIC / …), --negative-prompt (styles to exclude). MusicGen ignores all of these — put the mood in the prompt.

Failure modes

BGM failure never blocks a render.

Captions

The live search is the source of truth for what the registry has. The table(s) below are a hand-maintained sample and under-cover by design: run npx hyperframes catalog --query "<what you want>" --json — it needs nothing installed — before concluding the registry lacks something. Item names here are checked against registry/registry.json by bun run lint:skills.

Before authoring: confirm the transcript came from the right Whisper model. CLI default small.en silently translates non-English audio — see ../transcribe.md (../transcribe.md) → "Language Rule" and transcript-handling.md (transcript-handling.md) for the mandatory quality check.

Analyze spoken content to determine caption style. If user specifies a style, use that. Otherwise, detect tone from the transcript.

Transcript Source

[
  { "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]

id (w0, w1, …) is the stable reference for per-word overrides and is added by hyperframes transcribe. It's optional for backwards compatibility with hand-authored transcripts. See ../transcribe.md (../transcribe.md) → "Output Shape" for how this is produced, and transcript-handling.md (transcript-handling.md) for cleanup before consumption.

Style Detection (When No Style Specified)

Read the full transcript before choosing. Four dimensions:

1. Visual feel — corporate→clean; energetic→bold; storytelling→elegant; technical→precise; social→playful.

2. Color palette — dark+bright for energy; muted for professional; high contrast for clarity; one accent color.

3. Font mood — heavy/condensed for impact; clean sans for modern; rounded for friendly; serif for elegance.

4. Animation character — scale-pop for punchy; gentle fade for calm; word-by-word for emphasis; typewriter for technical.

Per-Word Styling

Scan for words deserving distinct treatment:

• Brand/product names — larger size, unique color
• ALL CAPS — scale boost, flash, accent color
• Numbers/statistics — bold weight, accent color
• Emotional keywords — exaggerated animation (overshoot, bounce)
• Call-to-action — highlight, underline, color pop
• Marker highlight — for beyond-color emphasis (highlight sweep, circle, burst, scribble, sketchout), see hyperframes-animation/rules/css-marker-patterns.md.

Script-to-Style Mapping

Word Grouping

• High energy: 2-3 words. Quick turnover.
• Conversational: 3-5 words. Natural phrases.
• Measured/calm: 4-6 words. Longer groups.

Break on sentence boundaries, 150ms+ pauses, or max word count.

Positioning

• Landscape (1920x1080): Bottom 80-120px, centered
• Portrait (1080x1920): Lower middle ~600-700px from bottom, centered
• Never cover the subject's face
• position: absolute — never relative
• One caption group visible at a time

Text Overflow Prevention

Use window.__hyperframes.fitTextFontSize():

var result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
  fontFamily: "Outfit",
  fontWeight: 900,
  maxWidth: 1600,
});
el.style.fontSize = result.fontSize + "px";

Options: maxWidth (1600 landscape, 900 portrait), baseFontSize (78), minFontSize (42), fontWeight, fontFamily, step (2).

CSS safety nets: max-width on container, overflow: visible (not hidden — hidden clips scaled emphasis words and glow effects), position: absolute, explicit height. When per-word styling uses scale > 1.0, compute maxWidth = safeWidth / maxScale to leave headroom.

Container pattern: Full-width absolute container, centered. Do not use left: 50%; transform: translateX(-50%) — causes clipping at composition edges.

Caption Exit Guarantee

Every group must have a hard kill after exit animation:

tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
// `tl.set` is an instant flip, not a tween — safe to set `visibility` here (core's "no animating
// visibility" rule applies to tweens, which can't smoothly interpolate non-numeric values anyway).
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end);

Self-lint after building timeline — place before window.__timelines[id] = tl so it runs at composition init:

GROUPS.forEach(function (group, gi) {
  var el = document.getElementById("cg-" + gi);
  if (!el) return;
  tl.seek(group.end + 0.01);
  var computed = window.getComputedStyle(el);
  if (computed.opacity !== "0" && computed.visibility !== "hidden") {
    console.warn(
      "[caption-lint] group " + gi + " still visible at t=" + (group.end + 0.01).toFixed(2) + "s",
    );
  }
});
tl.seek(0);

Pre-Built Caption Components

Before building caption styles from scratch, check the registry — 15 ready-to-use caption components cover the most common styles. Install with npx hyperframes add <name> and wire as a sub-composition via data-composition-src (see hyperframes-registry).

npx hyperframes catalog --tag caption-style   # list all caption components
npx hyperframes add caption-highlight         # install a specific one

Related: caption-blend-difference (tagged text / blend-mode, not caption-style, so it won't appear under the filter above) auto-inverts text against any background via mix-blend-mode: difference — useful when the background is busy or unpredictable.

Browse all with previews: hyperframes.heygen.com/catalog

Caption components ship with transparent backgrounds — they're pure overlays. If the underlying video is bright or busy, add a contrast layer (e.g. a semi-transparent dark div) in the host composition beneath the caption sub-composition, not inside the component itself.

Further References

• motion.md (motion.md) — karaoke, marker effects, audio-reactive modulation, scatter exits.
• transcript-handling.md (transcript-handling.md) — input formats, quality checks, cleaning, external API fallback.
• hyperframes-animation/rules/css-marker-patterns.md — marker highlighting (deterministic, fully seekable).

Constraints

• Deterministic. No Math.random(), no Date.now().
• Sync to transcript timestamps.
• One group visible at a time.
• Every group must have a hard tl.set kill at group.end.
• Fonts: the compiler auto-embeds only its built-in mapped set (Inter, Roboto, Montserrat, …) — for those, just declare font-family in CSS. Any other font (a brand/custom font like TT Norms Pro, or a non-Latin CJK/Devanagari family) is not auto-supplied: it needs an @font-face pointing at a real .woff2 shipped with the project, or the text silently falls back to a generic font in the render. Don't assume a font-family you can see locally will render — the render machine is a clean headless Chrome with no installed fonts.

Dynamic Caption Techniques

You are here because SKILL.md told you to read this file before writing animation code. Pick your technique combination from the table below based on the energy level you detected from the transcript, then implement using standard GSAP patterns.

Technique Selection by Energy

All energy levels use karaoke highlight as the baseline. The difference is intensity — high energy gets accent color + glow + 15% scale pop on active words, low energy gets a gentle white shift with 3% scale.

Emphasis words always break the pattern. When a word is flagged as emphasis (emotional keyword, ALL CAPS, brand name), give it a stronger animation than surrounding words (larger scale, accent color, overshoot ease). This creates contrast.

Marker highlight modes add a visual layer on top of karaoke. For emphasis words that need more than color/scale, add a marker-style effect: highlight sweep, circle, burst, scribble, or sketchout. See hyperframes-animation/rules/css-marker-patterns.md for implementation details. Match mode to energy: burst for hype, circle for key terms, highlight for standard, scribble for subtle.

Audio-Reactive Captions (Mandatory for Music)

If the source audio is music (vocals over instrumentation, beats, any musical content), you MUST extract audio data and add audio-reactive animations. This is not optional — music without audio reactivity looks disconnected. Even low-energy ballads get subtle bass pulse and treble glow.

No special wiring is needed. The group loop already iterates over every caption group to build entrance, karaoke, and exit tweens. At that point, read the audio data for each group's time range and use it to modulate the group's animation intensity with regular GSAP tweens.

// Load audio data inline (same pattern as TRANSCRIPT)
var AUDIO = JSON.parse(audioDataJson); // { fps, totalFrames, frames: [{ bands: [...] }] }

GROUPS.forEach(function (group, gi) {
  var groupEl = document.getElementById("cg-" + gi);
  if (!groupEl) return;

  // Read peak energy for this group's time range
  var startFrame = Math.floor(group.start * AUDIO.fps);
  var endFrame = Math.min(Math.floor(group.end * AUDIO.fps), AUDIO.totalFrames - 1);
  var peakBass = 0;
  var peakTreble = 0;
  for (var f = startFrame; f <= endFrame; f++) {
    var frame = AUDIO.frames[f];
    if (!frame) continue;
    peakBass = Math.max(peakBass, frame.bands[0] || 0, frame.bands[1] || 0);
    peakTreble = Math.max(peakTreble, frame.bands[6] || 0, frame.bands[7] || 0);
  }

  // Modulate entrance — louder groups enter bigger and glowier
  tl.to(
    groupEl,
    {
      scale: 1 + peakBass * 0.06,
      textShadow:
        "0 0 " + Math.round(peakTreble * 12) + "px rgba(255,255,255," + peakTreble * 0.4 + ")",
      duration: 0.3,
      ease: "power2.out",
    },
    group.start,
  );

  // Reset at exit so audio-driven values don't persist
  tl.set(groupEl, { scale: 1, textShadow: "none" }, group.end - 0.15);
});

This shapes the animation at build time, not playback time — no per-frame callbacks, no tl.call() loops, no async fetch timing issues. Loud groups come in with more weight and glow; quiet groups come in soft. The audio data modulates how much, the content determines what.

Keep audio reactivity subtle — 3-6% scale variation and soft glow. Heavy pulsing makes text unreadable.

To generate the audio data file:

python3 skills/hyperframes-creative/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json

Combining Techniques

Don't use the same highlight animation on every group — cycle through styles using the group index. Don't combine multiple competing animations on the same word at the same timestamp. Vary techniques across groups to match the content's pace changes.

Marker highlight effects layer well with karaoke — use karaoke for the word-by-word reveal, then add a marker effect on emphasis words only. For example: karaoke highlights each word in white, but brand names get a yellow highlight sweep and stats get a red circle. Cycle marker modes across groups for visual variety.

Runtime Tools

Caption motion uses standard HyperFrames runtime APIs. Use the canonical sources:

• GSAP timeline + tween syntax — hyperframes-animation/adapters/gsap.md (eases, position parameter, performance)
• window.__hyperframes.fitTextFontSize / pretext — hyperframes-core/references/determinism-rules.md → Layout Contract (overflow prevention, per-frame text measurement)
• Audio data extraction — generate via python3 skills/hyperframes-creative/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json, then load inline as shown in "Audio-Reactive Captions" above

Transcript Guide

For the transcribe CLI invocation, the .en-translates-non-English rule, and whisper model selection, see ../transcribe.md (../transcribe.md). This file covers what to do with the resulting transcript when authoring captions: input formats, mandatory quality checks, cleaning code, external-API fallbacks.

Supported Input Formats

The CLI auto-detects and normalizes these formats:

Word-level timestamps produce better captions. SRT/VTT give phrase-level timing, which works but can't do per-word animation effects.

Transcript Quality Check (Mandatory)

After every transcription, read the transcript and check for quality issues before proceeding. Bad transcripts produce nonsensical captions. Never skip this step.

What to look for

Automatic retry rules

If more than 20% of entries are ♪/� tokens, or the transcript contains obvious nonsense words, the transcription failed. Do not proceed with the bad transcript. Instead:

1. Retry with medium.en if the original used small.en or smaller:

   npx hyperframes transcribe audio.mp3 --model medium.en

2. If medium.en also fails (still >20% music tokens or garbled), tell the user the audio is too noisy for local transcription and suggest:
   • Providing lyrics manually as an SRT/VTT file
   • Using an external API (OpenAI or Groq Whisper — see below)
3. Always clean the transcript before building captions — filter out ♪/� tokens and entries where text is a single non-word character. Only real words should reach the caption composition.

Cleaning a transcript

After transcription (even with a good model), strip non-word entries:

var raw = JSON.parse(transcriptJson);
var words = raw.filter(function (w) {
  if (!w.text || w.text.trim().length === 0) return false;
  if (/^[♪�\u266a\u266b\u266c\u266d\u266e\u266f]+$/.test(w.text)) return false;
  if (/^(huh|uh|um|ah|oh)$/i.test(w.text) && w.end - w.start < 0.1) return false;
  return true;
});

For model-selection guidance by content type, see ../transcribe.md (../transcribe.md) → "Picking a model by content type".

Using External Transcription APIs

For the best accuracy, use an external API and import the result:

OpenAI Whisper API (recommended for quality):

# Generate with word timestamps, then import
curl https://api.openai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F file=@audio.mp3 -F model=whisper-1 \
  -F response_format=verbose_json \
  -F "timestamp_granularities[]=word" \
  -o transcript-openai.json

npx hyperframes transcribe transcript-openai.json

Groq Whisper API (fast, free tier available):

curl https://api.groq.com/openai/v1/audio/transcriptions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -F file=@audio.mp3 -F model=whisper-large-v3 \
  -F response_format=verbose_json \
  -F "timestamp_granularities[]=word" \
  -o transcript-groq.json

npx hyperframes transcribe transcript-groq.json

If No Transcript Exists

1. Check the project root for transcript.json, .srt, or .vtt files.
2. If none found, run ../transcribe.md (../transcribe.md) — pick the starting model from "Picking a model by content type" there.
3. Run the quality check above. If it fails, retry with a larger model or fall back to manual lyrics / external API.

Background Removal

Make a transparent overlay (typical: a talking head over an arbitrary scene). Uses u2net_human_seg (Apache-2.0).

npx hyperframes remove-background subject.mp4 -o transparent.webm          # default: VP9 + alpha
npx hyperframes remove-background subject.mp4 -o transparent.mov           # ProRes 4444 (editing)
npx hyperframes remove-background portrait.jpg -o cutout.png               # single-image cutout
npx hyperframes remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                           # both layers, one pass
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info                                   # detected providers

Output Format

• .webm (VP9 alpha) — default. Plug straight into <video> for Chrome-native transparent playback (~1 MB / 4s @ 1080p).
• .mov (ProRes 4444) — round-trip in editors (Premiere / Resolve / DaVinci). ~50 MB / 4s.
• .png — single-image cutout.

Quality (--quality)

Controls VP9 encoder CRF only — segmentation quality is fixed. Higher quality keeps the cutout's RGB closer to the source MP4 (important when overlaying the cutout on its own source).

Device (--device)

auto (default) picks CoreML on Apple Silicon, CUDA when available, otherwise CPU. Force with --device cpu | coreml | cuda. CUDA requires HYPERFRAMES_CUDA=1 plus a GPU-enabled onnxruntime-node build. Use --info to inspect detected providers without rendering.

Compositing patterns — pick the right one

The cutout WebM is a re-encoded copy of the source MP4's RGB. What sits behind it matters.

Text-behind-subject pattern (two non-obvious rules)

Putting a headline behind a presenter cutout:

<video
  src="presenter.mp4"
  id="bg"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>

<div class="cutout-wrap" style="position:absolute; inset:0; z-index:3; opacity:0">
  <video
    src="presenter.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

// Flip the wrapper's opacity at the cut, NOT the video's
tl.set(".cutout-wrap", { opacity: 1 }, 3.3);

Two rules that are easy to miss:

1. Wrap the cutout <video> in a non-timed <div> and animate the wrapper's opacity, not the video element's. The framework forces opacity: 1 on active clips (any element with data-start / data-duration), so animating the video's opacity directly is silently overridden. The wrapper has no data-* attributes, so it's owned by your CSS / GSAP.
2. Both videos use data-start="0" and data-media-start="0" so the framework decodes them in sync from t=0. Late-mounting the cutout (data-start=3.3) introduces a seek + warm-up that lands a frame off the base mp4 — visible as one frame of misalignment at the cut.

Layer separation (--background-output)

Emits a second transparent video alongside the cutout: same source RGB, alpha is 255 - mask instead of mask. The cutout has the subject opaque; the plate has the surroundings opaque (with a transparent hole where the subject was). Use it when text / graphics need to live between the two layers.

Both share the same --quality and run from a single inference pass — only encode cost roughly doubles. Only valid for video inputs with .webm / .mov outputs.

Hole-cut, not inpainted. The subject region in plate.webm is fully transparent — composite something opaque under it to fill the hole.

Single test for whether --background-output is the right tool: will anything ever be visible through the subject's silhouette where the subject used to be? If no, you don't need the plate — subject.webm alone over a different background is enough.

Use case → right tool

Canonical 3-layer template (plate + content + cutout)

Ship just the two transparent layers and let arbitrary content live between them — no original mp4 needed:

<!-- z=1 plate: surroundings opaque, subject silhouette transparent -->
<video
  src="plate.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<!-- z=2 your content lives between the layers -->
<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>

<!-- z=3 cutout floats the subject back on top -->
<div class="cutout-wrap" style="position:absolute; inset:0; z-index:3">
  <video
    src="subject.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

Functionally equivalent to the text-behind-subject pattern above, but doesn't require shipping the original mp4 — the plate replaces it. Use this when delivering just the two transparent layers as a reusable asset.

When remove-background is NOT the right tool

If a user asks for "the room without the person, displayed standalone" (no subject anywhere, no compositing on top), --background-output is wrong — its plate has a transparent hole, not a filled-in clean plate. They need an inpainter: LaMa, ProPainter, or E2FGVI. Tell them this command can't do it.

Requirements & Caches

Credential & key priority

Run npx hyperframes auth status to see what's configured and which engines a workflow will use (see the skill's Preflight section). Keys resolve in this order — first match wins:

hyperframes auth login (browser OAuth) is the recommended setup: one sign-in, every project, no per-repo .env. An OAuth login is sent as Authorization: Bearer; an API key as X-Api-Key; both are tagged with X-HeyGen-Source: cli. OAuth CLI users can consume the web-plan free allowance for HeyGen TTS (10 min/month); API keys follow the normal API billing path. With no HeyGen credential, voice/BGM run fully locally (Kokoro / MusicGen) — hyperframes auth status and hyperframes doctor both report whether those local deps are installed.

Model caches & system dependencies

Each command downloads its own model on first run and caches it under ~/.cache/hyperframes/:

• TTS (HeyGen) — no local deps; needs a HeyGen credential + ffmpeg on PATH (to transcode the mp3 response to .wav). Credential resolves like the CLI: $HEYGEN_API_KEY → $HYPERFRAMES_API_KEY → ~/.heygen/credentials (shared with heygen-cli; run npx hyperframes auth login). An OAuth login is sent as Authorization: Bearer; an API key as X-Api-Key; both include X-HeyGen-Source: cli so the backend can apply CLI OAuth free usage.
• TTS (ElevenLabs) — same as HeyGen: API key + ffmpeg.
• TTS (Kokoro) — Kokoro-82M (~311 MB) + voices (~27 MB) in tts/. Requires Python 3.8+ with kokoro-onnx and soundfile (pip install kokoro-onnx soundfile). Non-English text also needs espeak-ng system-wide.
• BGM (Lyria) — needs $GEMINI_API_KEY or $GOOGLE_API_KEY + pip install google-genai. No local model cache.
• BGM (MusicGen) — pip install transformers torch soundfile. facebook/musicgen-small (~300 MB) cached under ~/.cache/huggingface/ on first run.
• Transcribe — Whisper model size depending on choice (75 MB – 3.1 GB) in whisper/, downloaded from HuggingFace on first use. whisper.cpp itself is NOT bundled: the CLI resolves it from PATH, installs via Homebrew (macOS), or builds it from source with git+cmake on first use ($HYPERFRAMES_WHISPER_PATH overrides).
• Remove-background — u2net_human_seg (~168 MB ONNX) in background-removal/models/. Peak inference RAM ~1.5 GB.

Run npx hyperframes doctor if a command fails because of a missing dependency.

Sound effects (SFX)

Named sound effects, produced by the shared audio engine (scripts/audio.mjs → scripts/lib/sfx.mjs). Provider-gated by the engine's one switch — whether a HeyGen credential is present, decided once (not per cue):

• HeyGen credential present → retrieve every cue from HeyGen's audio library (/v3/audio/sounds, type=sound_effects, min_score=0.4). Search-and-download, not generation. The bundled library is NOT consulted.
• No credential → the bundled 21-file library (assets/sfx/ + manifest.json): match each cue name, copy the matched file into the project. Offline, deterministic, free.

There is no npx hyperframes sfx command. SFX is never generated — it is retrieved (online) or taken from the bundled library (offline).

Cues — request → meta

Each line names the effects it wants: lines[].sfx: ["whoosh", "ui click"]. The engine flattens these into cues, resolves them per the switch, dedupes identical (id, name) pairs (the same effect named twice downloads/copies once), and writes audio_meta.sfx[]:

{
  "id": "3",                       // joins the cue to the caller's model (frame / scene / segment)
  "name": "whoosh",
  "file": "assets/sfx/whoosh.mp3", // downloaded or copied, relative to project root
  "source": "heygen" | "local",    // which route resolved it
  "offset_s": 0,                   // delay from the line's start
  "duration_s": 0.57,
  "volume": 0.35                   // SFX sit UNDER voice + BGM
}

A cue that matches nothing is skipped (recorded as an anomaly); SFX never blocks a render. Neither route replaces a file of yours already at the output name: the cue gets the next free name (whoosh-2.mp3), reported as an anomaly, and file carries the real path.

HeyGen retrieval (credentialed)

searchSounds(name, "sound_effects", { limit: 3, minScore: 0.4 }) → top hit → assets/sfx/<slug>.mp3. Results are ranked by score (each carries a presigned audio_url, duration, description). The floor is 0.4 because good SFX hits score ~0.5–0.67 — below the API's default 0.7, which would silently drop most named cues (only whoosh/swoosh-family clears 0.7). duration_s comes from the result (else 1.0). Name effects concretely (glass shatter, not dramatic sound); a vague query returns a poor match.

Bundled library (no credential)

21 curated files in assets/sfx/, indexed by manifest.json — { file, duration, description } per key (e.g. whoosh, pop, click, chime, riser, impact-bass-1, glitch-1, typing, …). A cue name resolves by manifest key, file basename, or slug, so whoosh, whoosh.mp3, or "ui click" (→ slug) all match. Matched files are copied into the project's assets/sfx/; duration_s comes from the manifest, so timing is known offline — e.g. riser is 10.03s, so trigger it at climax − 10.03s. The manifest's description field carries placement hints per effect; read assets/sfx/manifest.json for the full set and usage.

Rules

• Volume ~0.35. SFX must sit under narration and BGM, not fight them.
• No match → skip, don't fail. A missing effect logs an anomaly and moves on; never a render blocker.
• Retrieval (credentialed) or bundled library (offline) — never generation. You search HeyGen by text, or match a name against the 21-file manifest.
• One asset per distinct name. Reuse across lines is deduped to a single download/copy, many cues.
• The switch is global, not per cue. With a credential, retrieval handles even the long tail (effects not in the 21); without one, only the 21 bundled names resolve.

Transcription

Create normalized word-level timestamps. Always specify --model explicitly — the CLI default is small.en, which silently translates non-English audio into English.

npx hyperframes transcribe audio.mp3  --model small.en             # known English
npx hyperframes transcribe video.mp4  --model small --language es  # known Spanish
npx hyperframes transcribe audio.mp3  --model small                # unknown language (auto-detect)
npx hyperframes transcribe subtitles.srt                           # import existing
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

Language Rule (Non-Negotiable)

.en models (tiny.en / base.en / small.en / medium.en) translate non-English audio into English. This silently destroys the original language.

1. Known English → --model small.en (or medium.en for music / noisy audio)
2. Known non-English → --model small --language <iso-code> (no .en suffix)
3. Unknown language → --model small (whisper auto-detects)

CLI default is small.en — do not rely on it; always pass --model to make the choice explicit. --language also filters out non-target-language segments from mixed-language audio.

Model Sizes

Picking a model by content type

1. Speech over silence / light background → small.en
2. Speech over music, or music with vocals → start with medium.en
3. Produced music track (vocals + full instrumentation) → start with medium.en; expect to need manual lyrics or an external API (captions/transcript-handling.md (captions/transcript-handling.md) → "Using External Transcription APIs")
4. Multilingual → medium or large-v3 (no .en suffix), pair with --language

Output Shape

Compositions consume a flat array of word objects. The id (w0, w1, …) is added during normalization for stable references in caption overrides; optional for backwards compatibility.

[
  { "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]

For mandatory caption-quality checks, retry rules, and the OpenAI/Groq Whisper API import path, see captions/transcript-handling.md.

TTS → Captions

When no recorded voiceover exists, generate one and obtain word-level caption timing. Two paths depending on which TTS provider is in use:

Path A — HeyGen (single call, no Whisper)

HeyGen returns word timestamps in the same response as the audio. Use the bundled REST helper (the hyperframes tts command is Kokoro-only):

node skills/media-use/audio/scripts/heygen-tts.mjs \
  script.txt --output narration.wav --words narration.words.json

narration.words.json is already in the [{ id, text, start, end }] shape the captions pipeline consumes — no separate transcribe pass.

Path B — Gemini / ElevenLabs / Kokoro (TTS → transcription)

These adapters supply audio without word data. The shared audio engine runs transcription automatically when timings are absent. For Gemini, use the request in Text to speech (tts.md#gemini-narration), then consume audio_meta.json → voices[].words.

For a standalone local Kokoro generation, generate the audio, then transcribe:

npx hyperframes tts script.txt --voice af_heart --output narration.wav
npx hyperframes transcribe narration.wav --model small.en   # voice af_heart is American English

Whisper extracts precise word boundaries from the generated audio, so caption timing matches delivery without hand-tuning. Match --model to the voice's language (use small.en for a/b prefixes, small --language <code> otherwise). Then consume transcript.json via the caption references in captions/.

For Gemini, verify that transcription preserved the script, especially names, numbers, and delivery pauses. If words is empty, resolve the transcription failure before captioning. Generate and align again after changing the read.

Text To Speech

npx hyperframes tts synthesizes locally with Kokoro. It does not accept a --provider or --words flag. For HeyGen audio plus word timestamps, use the bundled heygen-tts.mjs script below.

Run the Preflight first — no credential is not a green light to silently use the local voice. Before generating a voiceover, complete the sign-in Preflight (see ../../SKILL.md → Preflight): run npx hyperframes auth status, recommend signing in, and STOP for the user's choice (sign in for HeyGen voices, or continue offline with local Kokoro). This applies to a one-off "generate a voiceover" request just as much as inside a full workflow.

Narrating a HyperFrames docs video

Anything that will sit on hyperframes.heygen.com uses one narrator, so the site does not sound like two products.

curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/SAz9YHcvj6GT2YYXdXww" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"...","model_id":"eleven_multilingual_v2"}' -o take.mp3

This is the voice every user-journey film on the docs site already uses. Falling back to local Kokoro because a key was not to hand produces a film that sounds wrong beside the others — three docs videos were built that way and had to be re-voiced. If you cannot reach ElevenLabs, say so and stop rather than substituting a different voice.

Use another voice only for a documented reason, and write the reason down.

Available routes

Gemini is an explicit alternative to the automatic provider order below. A request to use Gemini already chooses the provider; do not redirect that user to HeyGen sign-in. Read the Gemini section for its credential requirement.

# Local Kokoro CLI
npx hyperframes tts "Welcome to HyperFrames" -o narration.wav

Self-contained HeyGen (no CLI) — scripts/heygen-tts.mjs

The published hyperframes tts CLI synthesizes locally with Kokoro only. When you want HeyGen specifically — best quality plus word timestamps in one call — use the skill's bundled script, which calls the HeyGen v3 REST API directly and needs no CLI provider plumbing:

The script resolves a HeyGen credential the same way the CLI does — first source wins: a host-injected OAuth $HEYGEN_ACCESS_TOKEN → $HEYGEN_API_KEY → $HYPERFRAMES_API_KEY → a project .env (auto-loaded, walks up ≤5 dirs) → ~/.heygen/credentials (shared with heygen-cli; $HEYGEN_CONFIG_DIR overrides the dir). An OAuth login is sent as Authorization: Bearer; an API key as X-Api-Key; both include X-HeyGen-Source: cli. OAuth CLI users can consume the web-plan free allowance (10 min/month) before paid usage; API keys follow normal API billing. If the only credential is an expired OAuth token it stops with a hint to run npx hyperframes auth refresh.

# Only needed if you haven't run `npx hyperframes auth login`:
export HEYGEN_API_KEY=...   # or put it in a project .env

# Synthesize + capture word timestamps in one call (skips a Whisper pass)
node skills/media-use/audio/scripts/heygen-tts.mjs \
  "Welcome to HyperFrames." -o narration.wav --words narration.words.json

node skills/media-use/audio/scripts/heygen-tts.mjs ./script.txt -o narration.wav
node skills/media-use/audio/scripts/heygen-tts.mjs --list   # public starfish voices

• Voice: --voice <id> must be a starfish voice_id (--list, or GET /v3/voices?engine=starfish) or one of your cloned voice ids (below). v2-catalog ids are rejected with HTTP 400. Omit --voice (English) and it defaults to Marcia (05f19352e8f74b0392a8f411eba40de1, a fixed default so the choice is deterministic). Non-English with no --voice falls back to the first matching catalog voice.
• Output: .wav → transcoded to 44.1k mono via ffmpeg; .mp3 → raw bytes (no ffmpeg needed).
• Words: --words <path> writes the flat [{id,text,start,end}] shape below, drop-in for the captions pipeline. HeyGen's <start>/<end> boundary sentinels are filtered out and ids are re-contiguous.
• Non-English: --lang <code> (anything but en) is sent as the request language.

Cloned voices — scripts/heygen-voice.mjs

Clone a voice from an mp3 or wav recording, then pass the printed id to heygen-tts.mjs --voice. Same credential resolution as above. Any API refusal (clone limit reached, plan upgrade required, voice not found) prints HeyGen's own message to stderr and exits 1.

node skills/media-use/audio/scripts/heygen-voice.mjs clone take.mp3 --name "My voice"  # → {"voice_id":"..."}
node skills/media-use/audio/scripts/heygen-voice.mjs list --prefix "My"   # → [{"voice_id","name","created_at"}]
node skills/media-use/audio/scripts/heygen-voice.mjs delete <voice_id>

clone waits up to 120 s for the clone to finish. list reads GET /v3/voices?type=private.

When to use which provider

Gemini narration

Use the shared audio engine, not hyperframes tts. Authenticate with either:

• GEMINI_API_KEY or GOOGLE_API_KEY (first set key wins).
• A service-account JSON file at GOOGLE_APPLICATION_CREDENTIALS, or injected JSON in GCS_CREDS. Install google-auth requests in the Python 3 environment used by the helper. A configured file takes precedence over injected JSON.

API keys take precedence over service accounts: unset both key variables to use OAuth. Never put credentials in a request file or composition. The helper obtains a fresh OAuth token for each generation with the generative-language.retriever scope. The quota project resolves from GOOGLE_CLOUD_PROJECT, then GCLOUD_PROJECT_ID, then the service-account JSON. User ADC files and metadata-server authentication are not supported.

Both routes call the Gemini Developer Interactions API, not Cloud TTS or Vertex AI. Those APIs have separate model catalogs and access requirements.

Save this as audio_request.json in the project:

{
  "provider": "gemini",
  "tts_model": "gemini-3.8-flash-tts",
  "voice": "Kore",
  "lang": "en",
  "style": "Warm, clear, conversational. Leave a short pause between sentences.",
  "lines": [
    { "id": "intro", "text": "Every word has a moment. Let the picture follow the voice." }
  ],
  "bgm": { "mode": "none" }
}

node <SKILL_DIR>/audio/scripts/audio.mjs \
  --request ./audio_request.json --hyperframes . --out ./audio_meta.json --only tts

The engine saves assets/voice/intro.wav (or intro-2.wav when a file of yours already has that name; voices[].path says which), measures its duration, and transcribes it into voices[].words in audio_meta.json. Check that every requested line has audio and nonempty word timings before building a captioned video. Review the timings against the actual audio; transcription is estimated alignment, not native TTS timestamps. Do not distribute words evenly across a clip.

• Models: gemini-3.8-flash-tts (default), gemini-3.8-flash-lite-tts, gemini-3.1-flash-tts-preview, gemini-2.5-pro-preview-tts, and gemini-2.5-flash-preview-tts. Use these exact Developer API IDs; Cloud TTS aliases such as gemini-2.5-flash-tts are not accepted.
• Voice: Kore by default; pass another prebuilt voice or an existing custom voice ID for 3.8. Older models require prebuilt voices. Creating or replicating voices is outside this helper.
• Delivery: Put directions in style, not in spoken text. Each line can override style. 3.8 uses structured annotations; older models receive a delivery prompt before the transcript. Check that directions were not spoken. Use style for pacing; numeric speed must be omitted or 1.
• Audio: 3.8 returns a complete WAV. Older models return mono 16-bit PCM, which the helper wraps as WAV at the returned sample rate without resampling. No generation calls run during playback or rendering.
• Timing: This adapter requests no native word timestamps. It uses the existing transcription pass. lang selects transcription language; Gemini infers speech language from the text.
• Workflow adapters: Product-launch, faceless-explainer, and PR-video audio scripts accept --provider gemini --voice Kore --tts-model gemini-3.8-flash-tts --style "Warm and clear".

An API error is reported as a failed line; an explicitly chosen Gemini voice never silently falls back to another provider. Check the engine's anomalies and output metadata, not only its exit code.

API contract: Google's speech generation guide.

ffmpeg requirement

HeyGen + ElevenLabs return mp3. The bundled HeyGen helper transcodes to wav when --output ends in .wav (the default and what downstream ffprobe + Whisper expect). If you'd rather skip the transcode, pass -o file.mp3. Without ffmpeg on PATH, wav output from cloud providers fails; the local Kokoro CLI writes wav directly.

Voice selection (Kokoro)

Default af_heart. Curated picks:

Run npx hyperframes tts --list for the bundled set.

Multilingual (Kokoro voice prefix → language)

The first letter of a Kokoro voice ID picks the phonemizer language; --lang overrides auto-detection.

npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora
npx hyperframes tts "Today is a nice day" --voice af_heart

Valid --lang codes (only needed to override the voice's auto-detected language): en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh.

Non-English phonemization requires espeak-ng system-wide (brew install espeak-ng / apt-get install espeak-ng).

Speed

• 0.7-0.8 — tutorial, complex content, accessibility
• 1.0 — natural pace (default)
• 1.1-1.2 — intros, transitions, upbeat content
• 1.5+ — rarely appropriate, test carefully

The hyperframes tts command honors --speed for Kokoro. Provider-specific helpers document their own pacing controls.

Long scripts

Past a few paragraphs, write the text to a .txt file and pass the path. Inputs over ~5 minutes of speech may benefit from splitting into segments.

HeyGen word-timestamp shape

When --words <path> is passed to a HeyGen call, the file is written in the same flat shape transcribe produces — drop-in compatible with the captions pipeline:

[
  { "id": "w0", "text": "Hi", "start": 0.0, "end": 0.21 },
  { "id": "w1", "text": "there", "start": 0.22, "end": 0.55 }
]

For ElevenLabs / Kokoro, run npx hyperframes transcribe narration.wav --model small.en to get the same shape.

#!/usr/bin/env node
// audio.mjs — the shared HyperFrames audio engine. ONE implementation of TTS +
// BGM + SFX for every video workflow (product-launch, general-video, pr-to-video,
// …). Workflows do NOT vendor a copy: they write a neutral `audio_request.json`
// (a tiny per-workflow adapter maps their storyboard/scenes into it) and call:
//
//   node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
//
// The three capabilities degrade on ONE switch — whether HeyGen is configured
// (credential present, NOT the CLI). This mirrors the table in ../SKILL.md:
//
//   TTS : HeyGen REST → ElevenLabs → Kokoro (CLI)
//   BGM : HeyGen retrieve  → (no credential) Lyria/MusicGen generate
//   SFX : HeyGen retrieve  → (no credential) bundled 19-file library
//
// ── audio_request.json (input) ────────────────────────────────────────────────
//   {
//     "provider": "auto",          // auto|heygen|elevenlabs|kokoro|gemini (override: --provider)
//     "lang": "en", "speed": 1.0,
//     "lines": [                   // one TTS unit each; id joins back to the caller's model
//       { "id": "01", "text": "...", "sfx": ["whoosh", "ui click"] }
//     ],
//     "bgm": { "mode": "retrieve", // retrieve|generate|none (override: --bgm-mode / --no-bgm)
//              "query": "calm cinematic underscore",   // mood for retrieval
//              "prompt": null,      // full prompt for generation (else inferred)
//              "blob": "...", "archetype": "...", "arc": "..." }  // optional mood-inference hints
//   }
//
// ── audio_meta.json (output, id-keyed) ───────────────────────────────────────
//   { tts_provider, voice_id,
//     bgm: { path, volume, mode, query?, duration_s? } | null,
//     bgm_pending, bgm_provider, bgm_pid, bgm_log, bgm_mode, bgm_target_duration_s, …,
//     voices: [ { id, path, duration_s, words: [{id,text,start,end}] } ],
//     sfx:    [ { id, name, file, source, offset_s, duration_s, volume } ],
//     total_duration_s }
//
// --only tts,bgm,sfx  runs a subset and MERGES into an existing --out (so a
// workflow can do TTS+BGM early, then SFX later once cues exist). When BGM uses
// the generate path it is spawned detached (bgm_pending:true) — run wait-bgm.mjs
// before assembling.

import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { heygenAuthHeaders, heygenCredential, loadEnvFromDir } from "./lib/heygen.mjs";
import {
  ffprobeDuration,
  pickProvider,
  resolveVoiceId,
  synthesizeOne,
  transcribeWav,
  withWordIds,
} from "./lib/tts.mjs";
import { generateBgmDetached, inferBgmPrompt, retrieveBgm } from "./lib/bgm.mjs";
import { resolveSfx } from "./lib/sfx.mjs";
import { mapWithConcurrency } from "./lib/concurrency.mjs";
import { openAudioMeta } from "./lib/audio-meta.mjs";
import { recordInManifest, voicePaths, writtenAssets } from "./lib/media-record.mjs";

const HERE = dirname(fileURLToPath(import.meta.url));
const argv = process.argv.slice(2);
const flag = (name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
const has = (name) => argv.includes(`--${name}`);
const die = (m) => {
  console.error(`✗ audio engine: ${m}`);
  process.exit(1);
};
const r3 = (x) => Number(x.toFixed(3));

// Two independent reports of an unbounded Promise.all over TTS lines
// overwhelming a machine: one OOM'd 12/13 concurrent Kokoro TTS +
// whisper-transcribe lines on a resource-constrained laptop, the other saw
// 7/8 lines fail on first run (concurrent cold-start model loads) and pass on
// retry once the model was cached. Kokoro/Whisper each load their own local
// model per subprocess, so firing every line at once multiplies that cost by
// the line count. mapWithConcurrency caps how many run at once — still
// parallel, just bounded.
const ttsConcurrency = Math.max(1, Number(process.env.HYPERFRAMES_TTS_CONCURRENCY) || 4);

const hyperframesDir = resolve(flag("hyperframes", "."));
const requestPath = resolve(flag("request", join(hyperframesDir, "audio_request.json")));
const outPath = resolve(flag("out", join(hyperframesDir, "audio_meta.json")));
const sfxLibDir = resolve(flag("sfx-lib", join(HERE, "..", "assets", "sfx")));
const lyriaRecipe = resolve(flag("lyria-recipe", join(HERE, "lyria-recipe.py")));
const onlyArg = flag("only", "tts,bgm,sfx");
const only = new Set(
  onlyArg
    .split(",")
    .map((s) => s.trim())
    .filter(Boolean),
);
const providerOverride = flag("provider", null);
const bgmModeOverride = flag("bgm-mode", null);
const noBgm = has("no-bgm");
const voiceOverride = flag("voice", null);
const speedOverride = flag("speed", null);
const langOverride = flag("lang", null);
const seedSeconds = Number(flag("seed-seconds", "28")) || 28;

if (!existsSync(requestPath)) die(`audio_request.json not found at ${requestPath}`);
let request;
try {
  request = JSON.parse(readFileSync(requestPath, "utf8"));
} catch (e) {
  die(`audio_request.json parse: ${e.message}`);
}
const lines = Array.isArray(request.lines) ? request.lines : [];
const lang = langOverride || request.lang || "en";
const speedInput = speedOverride ?? request.speed ?? 1;
const speed = Number(speedInput);
if (!(speed > 0 && speed <= 3))
  die(`speed must be above 0 and at most 3, got ${JSON.stringify(speedInput)}`);

// ── env + HeyGen availability (the single switch) ─────────────────────────────
loadEnvFromDir(hyperframesDir);
const heygenOK = heygenCredential() !== null;

// ── merge base: preserve sections not selected by --only ──────────────────────
const audioMeta = openAudioMeta(outPath);
const prev = audioMeta.value;
const anomalies = [];

// ── TTS ───────────────────────────────────────────────────────────────────────
let voices = prev.voices ?? [];
let ttsProvider = prev.tts_provider ?? null;
let voiceId = prev.voice_id ?? null;
if (only.has("tts") && lines.length) {
  try {
    ttsProvider = pickProvider(
      providerOverride || (request.provider === "auto" ? null : request.provider),
    );
  } catch (e) {
    die(e.message);
  }
  voiceId = await resolveVoiceId({
    provider: ttsProvider,
    userVoice: voiceOverride || request.voice,
    lang,
  });
  console.error(`· tts: ${ttsProvider} · voice ${voiceId} · ${lines.length} line(s)`);
  const paths = voicePaths(hyperframesDir, lines, anomalies);
  const synthLine = async (line) => {
    const id = String(line.id);
    const text = String(line.text ?? "").trim();
    if (!text) {
      anomalies.push(`line ${id}: empty text — skipped`);
      return null;
    }
    const rel = paths.get(id);
    const abs = join(hyperframesDir, rel);
    const { ok, words, error } = await synthesizeOne({
      provider: ttsProvider,
      text,
      voiceId,
      lang,
      speed,
      model: flag("tts-model", request.tts_model),
      style: flag("style", line.style ?? request.style),
      wavAbs: abs,
      hyperframesDir,
    });
    if (!ok) {
      anomalies.push(`line ${id}: TTS failed — omitted${error ? ` (${error})` : ""}`);
      return null;
    }
    let wordArr = words; // heygen: native; else transcribe
    if (!wordArr) wordArr = await transcribeWav({ wavRel: rel, lang, hyperframesDir });
    const dur = ffprobeDuration(abs);
    if (!isFinite(dur) || dur <= 0) {
      anomalies.push(`line ${id}: bad voice duration — omitted`);
      return null;
    }
    return { id, path: rel, duration_s: r3(dur), words: withWordIds(wordArr) };
  };
  const results = await mapWithConcurrency(lines, ttsConcurrency, synthLine);
  voices = results.filter(Boolean);
  for (const v of voices)
    console.error(`  voice ${v.id}: ${v.path} (${v.duration_s}s, ${v.words.length} words)`);
}
const hasVoice = voices.length > 0;
const totalDuration = r3(voices.reduce((a, v) => a + (v.duration_s || 0), 0));

// ── BGM ─────────────────────────────────────────────────────────────────────
let bgm = prev.bgm ?? null;
const bgmFields = {
  bgm_pending: prev.bgm_pending ?? false,
  bgm_provider: prev.bgm_provider ?? null,
  bgm_pid: prev.bgm_pid ?? null,
  bgm_log: prev.bgm_log ?? null,
  bgm_mode: prev.bgm_mode ?? null,
  bgm_target_duration_s: prev.bgm_target_duration_s ?? null,
  bgm_seed_duration_s: prev.bgm_seed_duration_s ?? null,
  bgm_loop_count: prev.bgm_loop_count ?? null,
};
if (only.has("bgm")) {
  bgm = null;
  Object.keys(bgmFields).forEach((k) => (bgmFields[k] = k === "bgm_pending" ? false : null));
  // Mode resolution. An EXPLICIT mode (flag or request.bgm.mode) is strict:
  // "retrieve" means retrieve-or-nothing — it never silently starts a detached
  // generate (a caller with no wait-bgm step, e.g. product-launch, must not get
  // a pending job it can't await). Only the UNSET/auto default picks generate
  // when HeyGen is absent.
  const explicitMode = bgmModeOverride || request.bgm?.mode || null;
  let mode = noBgm ? "none" : explicitMode || (heygenOK ? "retrieve" : "generate");
  if (mode === "retrieve" && !heygenOK) {
    anomalies.push(
      "bgm: retrieve requires a HeyGen credential — skipped (no generate fallback for an explicit retrieve)",
    );
    mode = "none";
  }

  if (mode === "none") {
    console.error(`· bgm: disabled`);
  } else if (mode === "retrieve") {
    try {
      bgm = await retrieveBgm({
        query: request.bgm?.query,
        headers: heygenAuthHeaders(),
        hyperframesDir,
        hasVoice,
        anomalies,
      });
      if (bgm) {
        bgmFields.bgm_provider = "heygen";
        bgmFields.bgm_mode = "retrieve";
        console.error(`  bgm: ${bgm.path} (retrieve "${bgm.query}")`);
      } else {
        anomalies.push(`bgm: no music match for "${request.bgm?.query ?? ""}" — skipped`);
      }
    } catch (e) {
      anomalies.push(`bgm retrieve failed: ${e.message} — skipped`);
    }
  } else {
    // generate
    const prompt = inferBgmPrompt({
      userPrompt: request.bgm?.prompt,
      blob: request.bgm?.blob || request.bgm?.query,
      archetype: request.bgm?.archetype,
      arc: request.bgm?.arc,
    });
    const gen = generateBgmDetached({
      prompt,
      durationS: totalDuration || 30,
      hyperframesDir,
      lyriaRecipe: existsSync(lyriaRecipe) ? lyriaRecipe : null,
      seedSeconds,
      hasVoice,
      anomalies,
    });
    if (gen.disabled) {
      anomalies.push(`bgm: ${gen.reason}`);
    } else {
      bgm = { path: gen.path, volume: gen.volume, mode: gen.mode, duration_s: null };
      bgmFields.bgm_pending = true;
      bgmFields.bgm_provider = gen.provider;
      bgmFields.bgm_pid = gen.pid;
      bgmFields.bgm_log = gen.log;
      bgmFields.bgm_mode = gen.mode;
      bgmFields.bgm_target_duration_s = gen.target_duration_s ?? null;
      bgmFields.bgm_seed_duration_s = gen.seed_duration_s ?? null;
      bgmFields.bgm_loop_count = gen.loop_count ?? null;
      console.error(`  bgm: launched ${gen.provider} (detached, pid ${gen.pid}) → ${gen.path}`);
    }
  }
}

// ── SFX ─────────────────────────────────────────────────────────────────────
let sfx = prev.sfx ?? [];
if (only.has("sfx")) {
  const cues = lines.flatMap((l) =>
    (Array.isArray(l.sfx) ? l.sfx : [])
      .map((name) => ({ id: String(l.id), name: String(name).trim() }))
      .filter((c) => c.name),
  );
  const headers = heygenOK && cues.length ? heygenAuthHeaders() : null;
  const res = await resolveSfx({ cues, heygenOK, headers, hyperframesDir, sfxLibDir });
  sfx = res.sfx;
  anomalies.push(...res.anomalies);
  console.error(
    `· sfx: ${sfx.length} cue(s) resolved (${heygenOK ? "heygen retrieval" : "bundled library"})`,
  );
}

// ── write audio_meta.json ─────────────────────────────────────────────────────
const meta = {
  tts_provider: ttsProvider,
  voice_id: voiceId,
  bgm,
  ...bgmFields,
  voices,
  sfx,
  total_duration_s: totalDuration,
};
mkdirSync(dirname(outPath), { recursive: true });
audioMeta.write(meta);
const written = writtenAssets({ only, lines, voices, ttsProvider, bgm, bgmFields, sfx });
anomalies.push(...recordInManifest(hyperframesDir, written));

console.log(`✓ audio engine → ${outPath}`);
console.log(`  heygen: ${heygenOK ? "yes" : "no"}  ·  ran: ${[...only].join(",")}`);
console.log(
  `  voices: ${voices.length}  ·  bgm: ${bgm ? `${bgmFields.bgm_provider}${bgmFields.bgm_pending ? " (pending)" : ""}` : "none"}  ·  sfx: ${sfx.length}`,
);
console.log(`  total voice duration: ${totalDuration}s`);
if (anomalies.length) {
  console.log(`\nanomalies (non-fatal):`);
  for (const a of anomalies) console.log(`  - ${a}`);
}

import { strict as assert } from "node:assert";
import { test } from "node:test";
import { mkdtempSync, mkdirSync, readFileSync, rmSync, existsSync, writeFileSync } from "node:fs";
import { spawnSync } from "node:child_process";
import { join, dirname } from "node:path";
import { tmpdir } from "node:os";
import { fileURLToPath } from "node:url";
import { recordInManifest } from "./lib/media-record.mjs";
import { resolveSfx } from "./lib/sfx.mjs";

// Proves the relocated engine (skills/media-use/audio/) still resolves its
// bundled SFX library from the moved location — the path most likely to break
// on a subtree move. Offline (heygenOK:false), no network.

const HERE = dirname(fileURLToPath(import.meta.url));
const sfxLibDir = join(HERE, "..", "assets", "sfx"); // same offset the engine uses

test("bundled SFX library resolves from the relocated path", async () => {
  assert.ok(existsSync(join(sfxLibDir, "manifest.json")), "moved manifest is present");
  const dir = mkdtempSync(join(tmpdir(), "mu-audio-"));
  try {
    const { sfx, anomalies } = await resolveSfx({
      cues: [{ id: "1", name: "whoosh" }],
      heygenOK: false,
      hyperframesDir: dir,
      sfxLibDir,
    });
    assert.equal(sfx.length, 1, `expected 1 resolved cue, got anomalies: ${anomalies.join("; ")}`);
    assert.equal(sfx[0].source, "local");
    assert.match(sfx[0].file, /assets\/sfx\//);
    assert.ok(existsSync(join(dir, sfx[0].file)), "matched SFX copied into the project");
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test("an unknown cue is reported, not fatal", async () => {
  const dir = mkdtempSync(join(tmpdir(), "mu-audio-"));
  try {
    const { sfx, anomalies } = await resolveSfx({
      cues: [{ id: "1", name: "definitely-not-a-real-sfx" }],
      heygenOK: false,
      hyperframesDir: dir,
      sfxLibDir,
    });
    assert.equal(sfx.length, 0);
    assert.ok(anomalies.some((a) => /not in bundled library/.test(a)));
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test("a person's own file under a bundled name survives, and the cue gets the next free name", async () => {
  const dir = mkdtempSync(join(tmpdir(), "mu-audio-"));
  try {
    const own = join(dir, "assets", "sfx", "whoosh.mp3");
    mkdirSync(dirname(own), { recursive: true });
    writeFileSync(own, "the person's own whoosh");
    const resolve = () =>
      resolveSfx({
        cues: [{ id: "1", name: "whoosh" }],
        heygenOK: false,
        hyperframesDir: dir,
        sfxLibDir,
      });

    const first = await resolve();
    const second = await resolve();

    assert.equal(readFileSync(own, "utf8"), "the person's own whoosh");
    assert.deepEqual(
      [first, second].map(({ sfx }) => [sfx[0].file, sfx[0].source]),
      [
        ["assets/sfx/whoosh-2.mp3", "local"],
        ["assets/sfx/whoosh-2.mp3", "local"],
      ],
    );
    assert.deepEqual(
      readFileSync(join(dir, "assets/sfx/whoosh-2.mp3")),
      readFileSync(join(sfxLibDir, "whoosh.mp3")),
    );
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

test("two effects never share a file when one's name is taken by the person, run after run", async () => {
  const dir = mkdtempSync(join(tmpdir(), "mu-audio-"));
  try {
    mkdirSync(join(dir, "assets", "sfx"), { recursive: true });
    writeFileSync(join(dir, "assets", "sfx", "glitch.mp3"), "the person's own glitch");
    const realFetch = globalThis.fetch;
    globalThis.fetch = async (url) => {
      const query = new URL(url).searchParams.get("query");
      if (query)
        return Response.json({ data: [{ audio_url: `https://sound.test/${query}`, score: 0.6 }] });
      return new Response(`bytes of ${new URL(url).pathname}`);
    };
    const run = async (names) => {
      const { sfx } = await resolveSfx({
        cues: names.map((name, index) => ({ id: String(index), name })),
        heygenOK: true,
        headers: {},
        hyperframesDir: dir,
        sfxLibDir,
      });
      const files = sfx.map(({ file }) => file);
      recordInManifest(
        dir,
        [...new Set(files)].map((path) => ({ path, type: "sfx", source: "search" })),
      );
      return files;
    };
    try {
      assert.deepEqual(await run(["glitch"]), ["assets/sfx/glitch-2.mp3"]);
      assert.deepEqual(await run(["glitch", "glitch 2", "glitch"]), [
        "assets/sfx/glitch-2.mp3",
        "assets/sfx/glitch-2-2.mp3",
        "assets/sfx/glitch-2.mp3",
      ]);
    } finally {
      globalThis.fetch = realFetch;
    }
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});

// The engine owns speed parsing; a fallback before the check would turn 0 or junk into 1.
function runEngineWith(request, ...args) {
  const dir = mkdtempSync(join(tmpdir(), "audio-speed-range-"));
  try {
    writeFileSync(join(dir, "audio_request.json"), JSON.stringify({ lines: [], ...request }));
    return spawnSync(process.execPath, [join(HERE, "audio.mjs"), "--hyperframes", dir, ...args], {
      encoding: "utf8",
    });
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

for (const [label, request, args, shown] of [
  ["request speed 5", { speed: 5 }, [], "5"],
  ["request speed 0", { speed: 0 }, [], "0"],
  ["request speed -1", { speed: -1 }, [], "-1"],
  ["request speed text", { speed: "fast" }, [], '"fast"'],
  ["--speed 0", {}, ["--speed", "0"], '"0"'],
  ["--speed text", { speed: 1 }, ["--speed", "abc"], '"abc"'],
]) {
  test(`${label} stops the engine before any TTS runs`, () => {
    const r = runEngineWith(request, ...args);
    assert.equal(r.status, 1);
    assert.ok(r.stderr.includes(`speed must be above 0 and at most 3, got ${shown}`), r.stderr);
  });
}

test("a numeric string speed, as the adapters forward it, passes the check", () => {
  assert.doesNotMatch(runEngineWith({ speed: "0.8" }, "--only", "tts").stderr, /speed must/);
});

import assert from "node:assert/strict";
import { test } from "node:test";
import { mkdtempSync, writeFileSync, readFileSync, mkdirSync, rmSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { spawnSync } from "node:child_process";

// Exercise the actual engine and provider together; only the paid API and
// external audio tools are fixtures. This is not a live synthesis/render test.
for (const expired of [false, true]) {
  for (const only of ["tts", "tts,bgm,sfx"]) {
    // With expired credentials the person already has an assets/voice/intro.wav, which the engine must keep.
    const voicePath = expired ? "assets/voice/intro-2.wav" : "assets/voice/intro.wav";
    test(`Gemini engine returns caption metadata with ${expired ? "expired" : "absent"} HeyGen credentials (${only})`, (t) => {
      const dir = mkdtempSync(join(tmpdir(), "hf-gemini-pipeline-"));
      t.after(() => rmSync(dir, { recursive: true, force: true }));
      if (expired) {
        mkdirSync(join(dir, "assets/voice"), { recursive: true });
        writeFileSync(join(dir, "assets/voice/intro.wav"), "the person's own intro");
      }
      const config = join(dir, "heygen");
      mkdirSync(config);
      if (expired)
        writeFileSync(
          join(config, "credentials"),
          JSON.stringify({
            oauth: { access_token: "expired-fixture", expires_at: "2000-01-01T00:00:00Z" },
          }),
        );
      const bin = join(dir, "bin");
      mkdirSync(bin);
      const preload = join(dir, "fetch.mjs");
      writeFileSync(
        preload,
        `
import assert from 'node:assert/strict';
globalThis.fetch = async (url, options) => {
  assert.equal(url, 'https://generativelanguage.googleapis.com/v1beta/interactions');
  const body = JSON.parse(options.body);
  assert.equal(body.model, 'gemini-3.8-flash-lite-tts');
  assert.equal(body.input[0].content[0].annotations[0].style, 'Line direction');
  const bytes = Buffer.alloc(48);
  bytes.write('RIFF'); bytes.write('WAVE', 8);
  return Response.json({status:'completed', steps:[{type:'model_output', content:[
    {type:'audio', mime_type:'audio/wav', data:bytes.toString('base64')}
  ]}]});
};
`,
      );
      writeFileSync(
        join(bin, "npx"),
        `#!${process.execPath}
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const args = process.argv.slice(2);
assert.deepEqual(args.slice(0, 3), ['hyperframes', 'transcribe', '${voicePath}']);
assert.ok(fs.existsSync(args[2]));
assert.equal(args[args.indexOf('--model')+1], 'small.en');
fs.writeFileSync(path.join(args[args.indexOf('--dir')+1], 'transcript.json'), JSON.stringify([
 {text:'Hello',start:0.1,end:0.4}, {text:'there.',start:0.5,end:0.9}
]));
`,
        { mode: 0o755 },
      );
      writeFileSync(join(bin, "ffprobe"), "#!/bin/sh\necho 1.25\n", { mode: 0o755 });
      writeFileSync(join(dir, ".env"), "");
      writeFileSync(
        join(dir, "audio_request.json"),
        JSON.stringify({
          provider: "gemini",
          tts_model: "gemini-3.8-flash-lite-tts",
          style: "Global direction",
          lines: [{ id: "intro", text: "Hello there.", style: "Line direction" }],
          bgm: { mode: "none" },
        }),
      );
      const result = spawnSync(
        process.execPath,
        [
          "--import",
          preload,
          new URL("./audio.mjs", import.meta.url).pathname,
          "--hyperframes",
          dir,
          "--only",
          only,
        ],
        {
          encoding: "utf8",
          env: {
            ...process.env,
            HEYGEN_CONFIG_DIR: config,
            HEYGEN_API_KEY: "",
            HYPERFRAMES_API_KEY: "",
            GEMINI_API_KEY: "fixture-key",
            PATH: `${bin}:${process.env.PATH}`,
          },
        },
      );
      assert.equal(result.status, 0, result.stderr);
      const meta = JSON.parse(readFileSync(join(dir, "audio_meta.json"), "utf8"));
      assert.equal(meta.tts_provider, "gemini");
      assert.equal(meta.voice_id, "Kore");
      assert.deepEqual(meta.voices, [
        {
          id: "intro",
          path: voicePath,
          duration_s: 1.25,
          words: [
            { id: "w0", text: "Hello", start: 0.1, end: 0.4 },
            { id: "w1", text: "there.", start: 0.5, end: 0.9 },
          ],
        },
      ]);
      assert.equal(meta.total_duration_s, 1.25);
      const manifest = readFileSync(join(dir, ".media/manifest.jsonl"), "utf8").trim().split("\n");
      assert.deepEqual(
        manifest
          .map((line) => JSON.parse(line))
          .map(({ path, type, source }) => [path, type, source]),
        [[voicePath, "voice", "generated"]],
      );
      if (expired)
        assert.equal(
          readFileSync(join(dir, "assets/voice/intro.wav"), "utf8"),
          "the person's own intro",
        );
    });
  }
}

#!/usr/bin/env node
// Self-contained HeyGen TTS — single text in → one wav (+ optional words JSON)
// out. A thin CLI over lib/tts.mjs (the same code the audio engine uses), so the
// HeyGen REST call, starfish voice pick, mp3→wav transcode, and word-timestamp
// filtering live in exactly one place. Bypasses the `hyperframes` CLI, which in
// the published build is Kokoro-only.
//
// Usage:
//   node heygen-tts.mjs "Text to speak"  -o narration.wav [--words narration.words.json]
//   node heygen-tts.mjs ./script.txt     -o narration.wav --words narration.words.json
//   node heygen-tts.mjs "Bonjour"        -o fr.wav --lang fr --voice <id>
//   node heygen-tts.mjs --list           # list starfish voices and exit
//
// Flags: -o/--output (.wav → ffmpeg transcode; .mp3 → raw bytes), --words,
//   --voice (starfish id), --speed, --lang, --list.
// Requires: $HEYGEN_API_KEY / OAuth ~/.heygen credentials and ffmpeg for .wav output.

import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { heygenAuthHeaders, heygenJSON, loadEnvFromDir } from "./lib/heygen.mjs";
import { ffprobeDuration, resolveVoiceId, synthesizeOne, withWordIds } from "./lib/tts.mjs";

const argv = process.argv.slice(2);
function flag(name, def) {
  const i = argv.indexOf(`--${name}`);
  if (i < 0) return def;
  if (i + 1 >= argv.length) return true;
  const v = argv[i + 1];
  return v.startsWith("--") ? true : v;
}
const die = (m) => {
  console.error(`✗ heygen-tts: ${m}`);
  process.exit(1);
};

// First arg that isn't a flag or the -o value is the text / .txt path.
const positional = (() => {
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a.startsWith("--")) {
      const next = argv[i + 1];
      if (next && !next.startsWith("--")) i++;
      continue;
    }
    if (a === "-o") {
      i++;
      continue;
    }
    return a;
  }
  return null;
})();

const output = resolve(
  (typeof flag("output") === "string" && flag("output")) ||
    (argv.includes("-o") && argv[argv.indexOf("-o") + 1]) ||
    "narration.wav",
);
const wordsPath = typeof flag("words") === "string" ? resolve(flag("words")) : null;
const userVoice = typeof flag("voice") === "string" ? flag("voice") : null;
const speedRaw = typeof flag("speed") === "string" ? Number(flag("speed")) : 1.0;
const speed = isFinite(speedRaw) && speedRaw > 0 ? speedRaw : 1.0;
const lang = typeof flag("lang") === "string" ? flag("lang") : "en";
const listOnly = flag("list") === true;

loadEnvFromDir(process.cwd());
let authHeaders;
try {
  authHeaders = heygenAuthHeaders();
} catch (e) {
  die(e.message);
}

// ---------- --list ----------
if (listOnly) {
  const payload = await heygenJSON(`/voices?engine=starfish&type=public&limit=50`, {
    headers: authHeaders,
  });
  for (const v of payload.data ?? payload.voices ?? []) {
    console.log(`${v.voice_id}\t${v.name}\t${v.language ?? ""}`);
  }
  process.exit(0);
}

// ---------- resolve text + voice ----------
if (!positional) die("no text given. Pass a string or a .txt path, or use --list.");
const text =
  positional.endsWith(".txt") && existsSync(resolve(positional))
    ? readFileSync(resolve(positional), "utf8").trim()
    : positional;
if (!text) die("input text is empty");

const voiceId = await resolveVoiceId({ provider: "heygen", userVoice, lang });
if (!userVoice) console.error(`· using voice ${voiceId}`);

// ---------- synthesize (shared engine code) ----------
const { ok, words, error } = await synthesizeOne({
  provider: "heygen",
  text,
  voiceId,
  lang,
  speed,
  wavAbs: output,
  hyperframesDir: process.cwd(),
});
// HeyGen's own refusal, verbatim: a caller shows it or acts on it (a deleted voice, a limit).
if (!ok) die(error ?? "synthesis failed (HeyGen request/transcode error)");

let wordCount = 0;
if (wordsPath) {
  if (words && words.length) {
    mkdirSync(dirname(wordsPath), { recursive: true });
    writeFileSync(wordsPath, JSON.stringify(withWordIds(words), null, 2));
    wordCount = words.length;
  } else {
    console.error("⚠ no word_timestamps in response — run `hyperframes transcribe` instead");
  }
}

const dur = ffprobeDuration(output);
const durStr = isFinite(dur) ? ` (${dur.toFixed(2)}s)` : "";
console.log(`✓ ${output}${durStr}${wordCount ? ` · ${wordsPath} (${wordCount} words)` : ""}`);

import { test } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";

const script = fileURLToPath(new URL("./heygen-tts.mjs", import.meta.url));
// Every fetch answers as HeyGen does for a voice that no longer exists.
const refusing = `data:text/javascript,globalThis.fetch = async () => new Response(${JSON.stringify(
  JSON.stringify({ error: { code: "voice_not_found", message: "Voice not found: vc_gone" } }),
)}, { status: 404, headers: { "content-type": "application/json" } });`;

test("a refused speech prints HeyGen's own message, so a caller can act on it", () => {
  const dir = mkdtempSync(join(tmpdir(), "heygen-tts-"));
  const run = spawnSync(
    process.execPath,
    ["--import", refusing, script, "Hello", "--voice", "vc_gone", "-o", join(dir, "out.mp3")],
    {
      cwd: dir,
      encoding: "utf8",
      env: {
        ...process.env,
        HEYGEN_API_KEY: "",
        HYPERFRAMES_API_KEY: "",
        HEYGEN_ACCESS_TOKEN: "t",
      },
    },
  );
  assert.equal(run.status, 1);
  assert.match(run.stderr, /✗ heygen-tts: Voice not found: vc_gone\n/);
  assert.doesNotMatch(
    run.stderr,
    /HTTP 404|"error"/,
    "HeyGen's message alone, not the raw response",
  );
});