Update to HeyGen

{
  "description": "Create narration voiceovers with HeyGen speech synthesis and hand off verified audio and timing for editing. Use for standalone voiceovers or a parent video's off-screen narration; preserve approved wording and voice identity.",
  "included_files": [],
  "name": "narrator",
  "skill_md_contents": "---\nname: narrator\ndescription: Create narration voiceovers with HeyGen speech synthesis and hand off verified audio and timing for editing. Use for standalone voiceovers or a parent video's off-screen narration; preserve approved wording and voice identity.\n---\n\n# Narrator\n\n## 1. Scope and handoff\n\nTurn an agreed spoken script into clear, natural narration using HeyGen **`create_speech`**. Return the accepted audio, measured duration, exact spoken text, voice/engine provenance, and any reliable timing data to the calling workflow. Do not generate an avatar or a video to obtain a voiceover.\n\nInherit the parent's script, language, audience, voice preference, runtime target, approval state, and output/display requirements. Use [script writer](../script-writer/SKILL.md) when writing or revising copy is requested; do not silently rewrite approved wording. Narration preparation does not change a parent's editing technology or its review gates. For example, picture-story's explicit HeyGen Voice requirement still applies.\n\nInspect the live callable schemas before synthesis. Tool namespace prefixes and field casing vary by host. Refer to the actual tools, not an invented API wrapper. Do not assume that REST API or web-editor capabilities are exposed by the connected MCP tools.\n\n## 2. HeyGen speech tool contract\n\n| Tool | Use | Boundary |\n| --- | --- | --- |\n| `choose_voice` | User browses public/private compatible voices and existing previews | The current picker is Starfish-oriented. “Add to chat” selects a reference; “Create speech” requests one call for one agreed script. |\n| `list_voices` | User delegates choice; fetch a small matching catalog page | The current tool returns speech-compatible Starfish voices and directs use of `engine: \"starfish\"`. Do not infer another engine's compatibility. |\n| `create_speech` | Synthesize the agreed text with a verified voice | Returns audio URL, duration, and optional word timestamps; may open an inline player. Each call consumes quota. |\n| `create_speech_without_player` | Synthesize an internal narration asset without opening a player | Same synthesis purpose and quota/retry rules; use only when actually exposed. |\n\nPass the script in the schema's text field and the returned voice ID in its voice field; some hosts use `voiceId`, others `voice_id`. Inspect input limits, language/locale, supported settings, and output fields rather than copying a request from another adapter. Omit unsupported options. Do not fabricate a timestamp flag, speech job ID, status endpoint, pronunciation dictionary, or SSML support.\n\nUse an explicit `engine: \"heygen_voice\"` for compatible voices and `engine: \"starfish\"` for Starfish. Omitting the engine uses the voice's saved default/settings, not a guarantee of a particular engine. The legacy `orca` token is a compatibility alias; use it only when the connected schema supports that mapping. Record what was requested and what was returned without inventing identity equivalence from a label alone.\n\nIf the parent requires HeyGen Voice, find an actually compatible voice through supported discovery or resolve the missing selection. Do not use the Starfish discovery path and then silently omit/change the required engine. Do not infer MCP support for professional-clone-only synthesis or Turbo from marketing pages or a REST example. Preserve explicit user engine preferences when supported.\n\nCurrent error meanings include HTTP 400 for unsupported/incompatible engine, plan, locale, or language, and HTTP 403 `ai_vendor_access_restricted` for workspace vendor restrictions. Report the returned cause. After a generation failure or timeout, user approval is required before another generation; no automatic fallback engine or retry. This also applies to an apparently unsuccessful request whose outcome is unknown.\n\n## 3. Resolve the voice without unnecessary auditions\n\nReuse a voice the user has already selected. Otherwise offer the real voice picker or a brief description of the desired voice. Resolve language, accent, warmth, register, energy, and intended delivery only as needed. Match the audience and material: clear conversational authority for an explanation, space for reflection in a story, or direct energy for a short product demonstration.\n\nUse `choose_voice` when the user wants to browse. Wait for the actual returned choice; an “Add to chat” action provides a voice reference and is not itself a generation request. If the user delegates selection, use `list_voices` or the current compatible catalog search, find a real returned ID, and preserve any engine restrictions in that result/tool contract. The current `list_voices` path is Starfish-specific; it does not prove support for HeyGen Voice. Do not invent voices or silently switch an explicitly requested engine to make a selected ID work.\n\nDo not generate samples or alternate takes merely to audition voices. Catalog previews can support selection. Creating a custom clone is a separate user request with the actual service's consent requirements; possession of a photo or recording does not establish consent. A compatible existing authorized voice does not need a new cloning process.\n\n## 4. Prepare speech-ready text\n\nSeparate `spoken_text` from visual direction and production notes. Do not send chapter numbers, cue times, stage directions, Markdown headings, or bracketed emotion prompts as narration. Use plain text unless the selected engine and tool explicitly support the needed markup.\n\nRead for breath and sense. Check names, acronyms, dates, numbers, units, URL pronunciation, language switches, and phrases whose meaning changes with emphasis. Keep a pronunciation note alongside the script. Use a documented pronunciation control if available; otherwise propose an authorized text adaptation rather than inventing a field or silently replacing locked words. Save both approved written copy and the exact submitted speech text when they differ.\n\nNatural pauses and conversational phrasing come from a well-written script and appropriate voice, not extreme punctuation or a speed parameter used to fit a stopwatch. Preserve selected delivery settings when suitable. Runtime estimates are planning aids; never increase delivery speed or stretch rendered audio to force a nominal duration. A parent workflow may set a fixed speed default for its whole narration track, applied after synthesis rather than through HeyGen (the UGC voiceover formats use 1.1x with FFmpeg `atempo`); that is a delivery choice, never a duration fit.\n\nPrefer one coherent take for a short voiceover. For longer scripts, respect the actual tool text limit and split at semantic boundaries with complete thoughts. Record the agreed chunk plan and count before a batch; a voice-picker “Create speech” selection authorizes one call with one agreed script, not multiple samples or a batch. Reuse the same voice and supported settings across authorized chunks. Do not split speech into one request per visual state when continuous prosody would work better.\n\n## 5. Synthesize once and retain the result\n\nCall `create_speech` with the approved text and verified voice/engine settings. When the parent needs internal assets and the host exposes it, `create_speech_without_player` is the documented alternative returning the same kind of audio result without opening a player. Do not invent a `hidden` or preview-suppression field. A tool-managed player is not another generation request, and hearing/downloading its result must not trigger synthesis again.\n\nRecord the submitted text, real voice ID, explicit/default engine choice, language/settings, returned identifiers, audio reference, and duration. Keep credentials out of the project. Use the returned audio URL or asset through the host's permitted media-access path. Preserve a local original when authorized and available; do not assume an expiring URL is a reusable source asset. Check format from the actual file, not its extension.\n\n**After a generation error or timeout, ask the user before another generation.** Preserve any returned identifier, reconcile an uncertain outcome using supported read/status tools if available, and report the actual failure. Do not automatically retry, switch voices/engines, create a replacement take, or repeat a widget's user-triggered regeneration. Do not invent a speech-status tool when none exists. A plan/locale/vendor-policy error needs its real cause resolved.\n\n## 6. Validate content, delivery, and timing\n\nListen to the full short take; for longer narration review every chunk, all joins, and suspect passages. Compare against the approved text, especially names, numbers, units, negations, repeated/omitted words, and the end of each sentence. Evaluate intelligibility, pronunciation, emotional fit, breath, and continuity as well as transcript fidelity. A correct transcript cannot establish pleasant delivery.\n\nMeasure actual audio duration. Preserve optional returned word timestamps when supplied and reliable; validate them against the recording. Otherwise use available transcription/alignment and correct errors. Do not distribute words evenly across the duration. If only phrase timing is reliable, provide that and let [captions](../captions/SKILL.md) avoid word-level highlighting. If audio inspection or alignment is unavailable, identify the limitation rather than reporting a passed review.\n\nKeep originals unchanged. Where the parent permits local audio preparation, trim unnecessary leading/trailing silence or join chunks only at meaningful boundaries, preserving breaths and consonants. Use short boundary fades only where they cannot erase speech. Store explicit source-to-final mappings and update timing after edits. Preserve speed and pitch at 1.0×, apart from a parent workflow's fixed whole-track speed default, which keeps the pitch. Do not denoise clean synthesis heavily or apply effects that make it metallic. Follow parent restrictions when local processing is disallowed.\n\nA defective take or substantial duration mismatch may require a script revision or additional paid synthesis. Obtain the required approval for that change/call; retain accepted takes. Graphics and music should fit the accepted narration, not demand its regeneration for convenience.\n\n## 7. Deliver the narration handoff\n\nFor standalone narration, provide the actual playable audio/file and measured duration. For a parent video, keep intermediate display consistent with its contract and hand off the audio internally. Save exact submitted and actual spoken text, corrected timing with its coordinate system, voice/engine/settings, source identifiers, pronunciation notes, original audio, any edit mapping, and review limitations. The video editor owns final mixing; the captions skill owns subtitle segmentation and rendering.\n"
}