* fix(skills): skill scripts run when the skills dir is a symlink
* test(skills): plugin launcher fixture ships the shared main-module helper like an install
* fix(skills): the CLI's cube validator runs through a symlink too, and the guard check is stricter
* docs(skills): long agent-started renders run detached in their own process group
* docs(cli): detached renders start in their own process group, on macOS too
* docs(cli): the detached render recipe never waits on terminal input
* feat(media-use): reach HeyGen through a host app's gateway (HEYGEN_API_BASE)
- The audio engine sends every HeyGen call to $HEYGEN_API_BASE when set, as the heygen CLI does; plain HTTP needs
$HEYGEN_ALLOW_HTTP=1, the CLI's own rule. A host gateway (that base with its own key) wins over a host OAuth token.
- The skill says: inside a host that gives HeyGen access, no CLI install or sign-in, prefer the host's own HeyGen
tools, relay a refused call's message as written and do not switch providers on your own.
HyperFrames Desktop sets these variables when a HeyGen API key is saved in its Settings, so media-use's TTS, catalog
search and avatar calls are paid by that key.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(media-use): format the edited tables and regenerate the skills manifest
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(media-use): host access applies only when HEYGEN_API_BASE is set; HeyGen credentials stay on HeyGen hosts
- The "use the host's own tools first / no CLI sign-in" guidance is now conditional on HEYGEN_API_BASE alone, so an
agent outside such a host (Claude Code with a HeyGen MCP connector, say) keeps today's media-use journey. The
compressed copies in README, CLAUDE.md, the prompting overview, general-video and the capability menu are back to
main's wording.
- A base outside heygen.com gets no stored or host OAuth credential, only a key set for it (review on #5181).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(media-use): a project's .env cannot set the HeyGen base or allow HTTP
loadEnvFromDir copied HEYGEN_API_BASE from a project file into process.env, and the host gateway path then sent the
person's shell HEYGEN_API_KEY to that host. A host app sets HEYGEN_API_BASE and HEYGEN_ALLOW_HTTP in the environment
it spawns, never in a project file, so the .env loader skips both.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(media-use): use a host app's music tools; fail loudly without the heygen CLI
* fix(media-use): name the heygen CLI only for music and sound effects; keep the sfx test offline
* fix(skills): workflow skills use a host app's own music tools first
* fix(skills): say how a host app's music track reaches the narrated workflows
* fix(skills): set a host app's music track after the last audio pass
* fix(skills): a host-music film with no narration still fetches its sound effects
* fix(media-use): keep the stub-failure test off the machine's heygen CLI; sync the skills manifest
* fix(skills): audio passes keep a host app's music and sounds; silent needs no sound cues
* fix(skills): host audio keeps string frames, stops on a broken audio_meta.json, survives a re-run
* fix(skills): report a host audio entry with no path and a broken sidecar instead of crashing
* fix(skills): keep host audio written while an audio pass runs
* test(cli): serve the telemetry capture while the resolve child waits on it
* test(cli): fail the telemetry capture when the resolve child exits non-zero
* style(skills): wrap the host audio comment to the 120-column limit
* feat(media-use): clone, list and delete HeyGen voices, and accept a host OAuth token
heygen-voice.mjs clones a voice from an mp3 or wav file, lists cloned voices by name prefix, and deletes one, printing HeyGen's own error message on any refusal. HEYGEN_ACCESS_TOKEN is now the first credential source and is sent as an OAuth Bearer token.
* fix(media-use): heygen-tts prints HeyGen's own refusal instead of a generic line
* chore(media-use): regenerate the skills manifest for the voice scripts
* fix(media-use): voice list stops on a repeated page, delete accepts an empty reply, plain refusals
* test(media-use): a voice list that pages forever fails at once instead of hanging
* docs(media-use): keep heygen-voice's header to three lines, usage lives in tts.md
* fix(media-use): say to fix an unreadable credentials path, not to log in again
* fix(media-use): provider=heygen gives the same fix hint as the auth headers
* test(media-use): restore env in the pickProvider test with a plain if
* fix(media-use): a credentials folder means no HeyGen credential, not a crash
* fix(media-use): keep heygenCredential never-throws for any unreadable credentials path
* fix(media-use): skip a .env folder when loading HeyGen credentials
heygen-tts.mjs and audio.mjs crashed with EISDIR when a parent folder held
a .env directory instead of a file.
* fix(media-use): still load a .env that is a pipe or a locked folder's file
* fix(media-use): read a .env without checking it first, so it cannot change in between
* fix(media-use): forward TTS speed to Kokoro
synthesizeOne built the `npx hyperframes tts` argv without --speed, so a
request speed (audio_request.json `speed` or audio.mjs --speed) was ignored
on the Kokoro path and every line rendered at 1.0. Forward it when it is not
the default.
Kokoro now enforces the CLI's speed range, so audio.mjs rejects a speed
outside (0, 3] up front instead of dropping every line with an opaque
subprocess exit.
Fixes#4926
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
* fix(media-use): reject zero and non-numeric TTS speed
`Number(x) || 1.0` turned 0 and non-numeric speeds into 1 before the range
check, so they passed silently. The engine now parses the raw request or
--speed value once, with no fallback, and the faceless-explainer,
pr-to-video and product-launch-video adapters forward the raw flag instead
of applying their own copy of the fallback.
Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>
---------
Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
* fix(media-use): honour HYPERFRAMES_PYTHON in the audio engine (#4614)
resolvePythonCommand() only probed python3/python on PATH, so on PEP 668
systems set up with a venv via HYPERFRAMES_PYTHON (the documented setup),
doctor reported MusicGen installed while BGM was silently skipped.
Check HYPERFRAMES_PYTHON first, as the CLI's findPython() does, and fall
through to the PATH probe when the override doesn't run.
* fix(media-use): require a Python 3 version from the interpreter probe
Address review on #4723:
- The probe accepted any executable that exits 0, so a Python 2
HYPERFRAMES_PYTHON (or python on PATH) was taken while the CLI's
validatePythonOverride() rejects it. Require "Python 3" in the
--version output, reading stderr too since Python 2 prints there.
- Regenerate skills-manifest.json for the media-use change.
* chore(skills): regenerate manifest without local __pycache__
* chore(media-use): trim python resolver comments to the comment limit
* style(media-use): format the python probe test
---------
Co-authored-by: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
* fix(media-use): record agent-made voice, music and sound effects in the project's media manifest
* fix(media-use): record in place only when --source says the agent made the file
* test(media-use): a rewritten agent file keeps one manifest record
* fix(media-use): leave a person's own sound effect unlabelled and mark locally made music generated
* refactor(media-use): record agent audio in-process through the shared manifest library
* style(media-use): format the in-process recording and refresh the skills manifest
* chore(skills): refresh the skills manifest for the media-use changes
* fix(media-use): report a broken ffprobe setting plainly and document the project sfx source
* style(skills): format the pipeline manifest assertion
* chore(skills): refresh the skills manifest
* fix(media-use): never replace a voice, music or sound file the person put in the project
* style(media-use): format the keep-person-files change
* chore(skills): refresh the skills manifest
* fix(media-use): a regenerated file gets a fresh record, and lookups skip the replaced one
* test(media-use): a replaced record no longer answers a prompt lookup in the CLI
* chore(skills): refresh the skills manifest
* chore(skills): refresh the skills manifest from a clean tree
* fix(media-use): never give a recorded file the id of a download in flight
* chore(skills): refresh the media-use manifest hash
* fix(media-use): say when audio lands on a new name, and never let two lines share one
* style(media-use): format the keep-files change
* chore(skills): refresh the media-use manifest hash
* fix(media-use): keep two sound effects off one file when a name is taken
* refactor(media-use): drop a set the one-at-a-time downloads never needed
* chore(skills): refresh the media-use manifest hash
* fix(media-use): keep two sound effects off one recorded file on a rerun
* style(media-use): format the rerun test
* chore(skills): refresh the media-use manifest hash
* fix(media-use): list only a file's newest record in candidates and the media index
* revert(media-use): leave promote as it was, nothing calls it
* test(media-use): give the index test's two assets their own files
* chore(skills): refresh the media-use manifest hash
* chore(skills): regenerate the manifest after merging the base branch
* fix(core): a figma import lists each media file once, like media-use
* fix(media-use): record agent-made voice, music and sound effects in the project's media manifest
* fix(media-use): record in place only when --source says the agent made the file
* test(media-use): a rewritten agent file keeps one manifest record
* fix(media-use): leave a person's own sound effect unlabelled and mark locally made music generated
* refactor(media-use): record agent audio in-process through the shared manifest library
* style(media-use): format the in-process recording and refresh the skills manifest
* chore(skills): refresh the skills manifest for the media-use changes
* fix(media-use): report a broken ffprobe setting plainly and document the project sfx source
* style(skills): format the pipeline manifest assertion
* chore(skills): refresh the skills manifest
* fix(media-use): a regenerated file gets a fresh record, and lookups skip the replaced one
* test(media-use): a replaced record no longer answers a prompt lookup in the CLI
* chore(skills): refresh the skills manifest
* chore(skills): refresh the skills manifest from a clean tree
* fix(media-use): never give a recorded file the id of a download in flight
* chore(skills): refresh the media-use manifest hash
* fix(media-use): list only a file's newest record in candidates and the media index
* revert(media-use): leave promote as it was, nothing calls it
* test(media-use): give the index test's two assets their own files
* chore(skills): refresh the media-use manifest hash
* fix(core): a figma import lists each media file once, like media-use
The contract test only walked packages/*/src and only .ts, so it could not see
the shipped agent tools under skills/**, which are .mjs/.cjs. 19 call sites
there and in package tests were still missing `--` immediately before the
input while the suite reported the bug class closed — a dash-prefixed filename
is parsed as an option and fails the same way.
Sweeps packages/, skills/ and scripts/ now, including .mjs/.cjs and test
files (dither.test.mjs was one of the broken sites). Excludes only the
contract test itself, which documents the contract with example argvs
including a deliberately misordered one.
Two guards were fixed while widening: the terminator must never be inserted
after `-i`, which consumes the next token (a blind pass hit an ffmpeg input
and a base64 -i), and comment prose describing a spawn is not a spawn.
Also routes every audioPadTrim probe failure through one sanitizer at the
boundary. runFfprobeJson scrubbed its own stderr, but
defaultProbeVideoFrameInfo threw `no video stream in ${videoPath}` raw into
the public PadTrimAudioResult.error, and an injected probe can throw anything.
The redaction unit tests all passed with the caller wiring deleted; the new
public-path regressions fail without it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Send `X-HeyGen-Client-Source: media-use` on every media-use HeyGen API
request (both auth types, via heygenAuthHeaders + the heygenJSON transport),
so backend billing meta can isolate media-use consumption from other free
TTS and avatar-video usage. Unconditional of auth type — a paying user's
media-use call is still media-use — unlike the OAuth-only cli-source header
that gates the free allowance.
* fix(hyperframes-media): surface the real reason a TTS line failed
synthesizeHeygen() swallowed every failure into a bare { ok:false }: a thrown
HTTP error (e.g. 402 plan_upgrade_required from heygenJSON) was caught and
discarded, a missing audio_url / failed audio fetch / failed transcode all
returned nothing. audio.mjs then logged 'TTS failed — omitted' for every line
with zero detail, so the actual cause took a hand-rolled repro to find.
Each failure path now returns an { error } string (the caught message, the HTTP
status, or the specific stage that failed), and audio.mjs appends it to the
anomaly. The subprocess providers (elevenlabs/kokoro) get the same treatment via
a shared synthResult() helper. synthesizeHeygen takes an injectable deps arg so
the failure paths are unit-tested (thrown 402, non-ok fetch, missing audio_url).
* fix(media-use): report wav transcode failures accurately
* chore: regenerate skills manifest
Behavior fixes surfaced by the prompt-guide validation campaign (Tier 1+2
of the upstream bug list; Tier 3 tracked in #2107). Split out from the
doc-only updates, which follow in a separate PR.
- BGM level: default bed volume under narration was 0.8 linear (~-2 dB,
~16 dB too hot vs voice). Now 0.12 (~-18 dB) via shared
bgmDefaultVolume() in media-use bgm.mjs + assemble-index fallbacks in
faceless-explainer / pr-to-video / product-launch-video. Explicit
volume still wins; silent-film 0.9 and music-to-video unchanged.
Adds bgm.test.mjs (3 cases); bgm.md reference updated to match.
- Caption accent: semanticColors() ranked accents purely by chroma, so a
preserved status red (#dc2626) outranked the brand accent and captions
highlighted in error-red. Status-keyed colors now excluded via shared
STATUS_ROLE_KEY regex consumed by both tokens.mjs and build-frame.mjs
(all three skill copies kept in sync).
- Voice threading: workflow SKILL.md Step 3.1 blocks now instruct
choosing the narration voice from the user's ask and passing
--voice <id>; previously "a male voice" was silently ignored and the
default (Marcia/am_michael) always won.
- fetch-pr shipping version: MERGED PRs get best-effort shipped_version
+ version_source in pr.json (first release published at/after merge,
else default-branch package.json marked unreleased); ingest surfaces
it as a 'Shipped in:' brief line; story-design.md forbids inventing
versions when absent.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(media-use): use CLI free HeyGen usage
* fix(media-use): address #2027 R1 nits — gate cli-source header to OAuth, export origin constant
- X-HeyGen-Source is now sent only on OAuth (Bearer) requests, not API-key ones —
the backend ignores it for API-key traffic (normal billing), so it was dead
metadata there. buildAuthHeaders + heygenAuthHeaders + tests updated.
- Export HEYGEN_CLI_ORIGIN_HEADER ("X-HeyGen-Client-Origin") for future cli:<origin>
consumers.
- Document the deliberate paid/X4 confirm-before-call decision on heygen.tts.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv
* refactor(cli): drop unused origin-header export, dedup auth-client tests
Fallow flagged 5 findings on this PR:
- major: HEYGEN_CLI_ORIGIN_HEADER was exported but never emitted or
imported — speculative dead code ("future consumers"). Remove it; a
real consumer can add the constant when one exists.
- 4x minor duplication in client.test.ts: fold the repeated
`.rejects.toSatisfy(auth-code)` assertion into expectAuthCode(), and the
repeated try/catch scrubbed-message assertion into expectRejectionMessage().
No behavior change; auth/client tests still 17/17.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The ElevenLabs provider spawns a Python helper that writes straight to wavAbs
via a bare open(), which (unlike heygen/kokoro) never creates the parent dir —
so on a fresh project the save throws ENOENT and the line is silently dropped
as 'TTS failed - omitted'. mkdir -p the dir first, guarded so a mkdir failure
(EACCES/EROFS) returns { ok:false } like the rest of the branch rather than
throwing. (Migrated from #1960, whose skills/hyperframes-media path was retired
into skills/media-use; the bug moved with it.)