Update to HeyGen

{
  "description": "Create edited talking-head videos with a confirmed HeyGen avatar and look, relevant B-roll, code-generated music and motion graphics, and reusable editing source. Use for presenter-led videos with post-production; deliver a finished MP4 and the code for continuing a series.",
  "included_files": [],
  "name": "talking-head",
  "skill_md_contents": "---\nname: talking-head\ndescription: Create edited talking-head videos with a confirmed HeyGen avatar and look, relevant B-roll, code-generated music and motion graphics, and reusable editing source. Use for presenter-led videos with post-production; deliver a finished MP4 and the code for continuing a series.\n---\n\n# Talking Head\n\n## 1. Purpose and production contract\n\n**This is an end-to-end edited-video workflow. The avatar render is an internal source asset. Never call `show_video` in this workflow, including while A-roll is pending or after it completes.** Use `get_video` to obtain readiness and source media; use the host's local/artifact media preview for the finished edited MP4. The production loop ends after the edit has received the single review round defined in step 9, any resulting corrections, final encoding, and delivery, subject to the concrete blockers in step 5. A raw avatar, a job ID, or a promise to edit later is not completion.\n\nProduce a finished presenter-led MP4: first let the user choose the avatar look, then confirm the script and necessary resources in a separate exchange, create A-roll through HeyGen `create_video_from_avatar`, and finish the coded edit with B-roll, motion graphics, and captions. Save and deliver the editing project alongside the finished video so the user can repeat the treatment in a series.\n\n**Every talking-head presenter must be a HeyGen avatar rendered with `create_video_from_avatar`.** This is the required path for consistent presenter identity. Do not substitute `text_to_video`, `image_to_video`, `reference_to_video`, Video Agent, Cinematic Avatar, or a newly generated person for the A-roll. B-roll and graphics supplement that avatar performance. If avatar creation or access is blocked, resolve that prerequisite rather than switching presenter technology.\n\nDefault to the user's own Avatar V digital twin, subject to confirmation of both avatar and look and verified engine support. The final edited video is rendered through code. Keep this workflow distinct from static picture-story production and animated-short generation. Their image-board and nine-keyframe requirements do not apply.\n\n**Portrait talking-head videos default to social-native, full-frame editing for Shorts, TikTok, and Reels.** A-roll and B-roll normally fill the 9:16 canvas edge to edge. Captions and graphics live over the image or briefly take over the whole frame. Avoid a persistent designed page containing a small video, headings, footers, rules, and a separate subtitle area. A requested slide presentation or another explicit format can use different framing; do not infer that format from a sophisticated visual style.\n\n**Preserve the A-roll's original background and baseline composition.** Background removal or replacement, subject cutouts, artificial background blur, torso fades, and decorative vignettes require an explicit user request. Do not crop, zoom, mask, or reposition suitable A-roll merely to decorate it or make room for text. A bounded image-B-roll split treatment from step 6 may temporarily scale and shift the intact A-roll while keeping the face visible, then restore its original framing. This is an editorial option within this workflow; it does not require an extra approval round. Ordinary output-resolution conversion and a specifically requested aspect-ratio conversion follow the limited rules in step 7.\n\n**Runtime is an approximate target; A-roll stays at its original 1.0× speed.** Never speed up, slow down, time-stretch, or otherwise warp the presenter video, dialogue, or finished composition to hit a requested length. Pitch-preserving time-stretching is also prohibited for duration matching. A small runtime difference is acceptable; preserve natural speech, voice quality, pauses, and lip sync.\n\n**Time is the primary information hierarchy.** Guide attention through successive reveals, transformations, cuts, and replacements. Spatial layout makes the current state clear; it must not ask viewers to scan several information regions while hearing the next idea. An animated page with all its labels visible is not a finished motion-graphics sequence.\n\nWriting this skill or discussing an idea does not authorize paid video generation. A request to make a video authorizes ordinary production after required resources and presenter selection are resolved. Preserve host permissions, consent requirements, service limits, and protections against duplicate paid creation.\n\n## 2. First choose the avatar look\n\n**The first user-facing interaction is avatar/look selection.** Open the look chooser and ask only for the presenter choice; wait for that selection before asking script/intake questions. Do not combine the avatar picker with script confirmation, topic discovery, or an upload checklist. Reuse an exact look already explicitly chosen in this conversation and proceed directly to the separate script exchange.\n\nResolve presenter selection before `create_video_from_avatar`. A named avatar, a look, and an engine are separate decisions. **Always let the user choose the exact look through the `list_avatars` widget on a widget-capable host.** Do not pick a look yourself, even when only one is available or a setup tool recommends an ID. A look the user already explicitly selected in this conversation can be reused; do not reopen the picker or request the same selection again.\n\nWhen available and applicable, use `prepare_avatar_video` for the A-roll presenter setup and follow its actual prerequisite instructions, preserving the existing topic or script. Use setup for presenter readiness and consent; keep its content-intake prompts for the separate script stage after look selection. This setup does not authorize rerouting the finished production to Video Agent, bypassing user look selection, or previewing the raw production A-roll. For an unresolved look, call `list_avatars` once to open the gallery; default to private avatars, or public when the user asks for presets. If the intended group is known, pass its returned group ID using the live schema to open its looks directly. Let the user browse and choose inside the widget. The widget owns pagination and opening looks: do not follow its cursor, prefetch pages, or repeatedly call it to enumerate the library. Reopen only when the user asks.\n\nRecommend the user's **private digital twin with an Avatar V-compatible look**, while leaving the actual look choice to the user. A text list of names/IDs, a default first result, or a recommended pair is not a substitute for opening `list_avatars`. If there are several private avatars, do not assume which person is the user. Never silently choose a public presenter or a different outfit because its engine is convenient. If this host genuinely lacks the widget, explain that limitation and use `list_avatar_groups` and `list_avatar_looks` to provide available previews for explicit user selection; never treat direct inventory discovery as permission to auto-select.\n\nThe look's returned ID is the `avatar_id`/`avatarId` input for video creation; a group ID is not a substitute. Check the selected look's returned `supported_api_engines` before passing an explicit engine. Request `avatar_v` only when that value is supported. If the chosen look cannot use Avatar V, explain the available supported choices and confirm a different compatible look or a supported engine. Do not silently downgrade or claim Avatar V was used merely because the avatar is a digital twin.\n\nIf the user has no usable avatar, **guide them through creating one first**. Use `open_avatar_creator` when available and permitted by its prerequisite flow, or direct them to the supported HeyGen avatar-creation path. Wait for creation, required consent, and ready status, then use `list_avatars` to let them choose the resulting look unless that exact choice was already made in the creation flow. Do not render with a placeholder person while the twin is processing. If the user explicitly chooses another existing HeyGen avatar or declines twin creation, honor that choice and let them select an existing look; do not force creation or silently substitute a presenter.\n\nResolve voice from the selected avatar's actual available/default voice or the user's stated choice. Preserve an explicitly selected voice and exact supplied speech. Do not invent voice or look IDs, clone a voice without the required authorization, or assume a voice reference is an engine setting.\n\n## 3. Then confirm the script and gather missing resources\n\nAfter the avatar look is chosen, use a separate exchange to confirm an existing script or gather enough information to write one. Ask for the missing resources needed for their actual subject. Be concrete: neighborhood photographs or street clips, the actual house and rooms, product photos and demonstration footage, a screen recording of a private app, logos, or brand assets. Reuse attachments already supplied and ask only for missing material. Include essential intake questions about topic or script, audience, target approximate length, destination/aspect ratio, language, and visual preferences in the same concise exchange when unresolved.\n\nWhen asking about length, phrase it as an approximation: “What's the target approximate length—about 30 seconds, a minute, or longer?” Explain briefly that the finished length may vary slightly to preserve natural delivery. Reuse an existing duration preference as a target instead of asking again or promising an exact runtime.\n\nExplain which images can be sourced online and which require the user's material. For a particular home, ask for that property's exterior and relevant interiors; generic stock houses cannot establish its actual features. For a neighborhood, establish the place precisely and request local imagery if reliable coverage cannot be found. For a product, request the exact model/version, angles, and details that the story needs. Do not ask the user to re-upload something already accessible.\n\nUse a request such as: “Please upload the house exterior, the rooms you want featured, and any branding. I can source neighborhood context online, but I need your photos to show this particular property accurately.” Adapt this to the brief rather than presenting an exhaustive upload checklist.\n\nSearch available public sources when they can fill a real gap. If online research later reveals that essential subject-specific imagery is unavailable or ambiguous, ask for that exact missing item. Wait for essential resources before committing paid A-roll to claims or visual sequences that depend on them. Optional B-roll need not block a video that communicates accurately without it; simplify the edit and state the omission rather than inventing evidence.\n\nUse the host's real attachment or local-file access mechanism. Do not fabricate paths, file IDs, URLs, or completed transfers. For an upload request, use an available file-capable conversation mechanism or a plain request; a text-only input form cannot collect an attachment.\n\n## 4. Establish the script and editorial plan\n\nWrite a clear spoken script with a strong opening, a coherent through-line, and a useful ending. Keep camera, graphics, and sound directions out of spoken text. Preserve an exact supplied script unless changes are authorized. Verify consequential or uncertain claims; distinguish real subject footage from illustrative stock and do not invent property features, neighborhood facts, product capabilities, testimonials, or numerical results.\n\nUse the following structure as a practical starting point, adapting it to the actual subject and length:\n\n1. **Hook:** open with a concrete question, tension, useful promise, or revealing contrast. Make the first spoken thought and visual hook work together over immediate presenter footage or relevant action. Lead with the actual problem, not an abstract slogan on a blank card. Avoid greetings or a long logo sequence that delays the reason to watch.\n2. **Orientation:** quickly establish what the viewer will learn and the context needed to understand it. Keep the promise narrow enough to fulfill.\n3. **Development:** progress through distinct ideas with evidence, examples, demonstrations, or consequences. Each beat should change what the viewer understands rather than repeat the headline.\n4. **Payoff and conclusion:** answer the opening question and synthesize the useful takeaway. Do not simply repeat the entire script or introduce a new unresolved topic at the end.\n5. **Call to action:** when appropriate, give one relevant next step tied to the video's value. Make it concrete and low-friction. Omit it when it would weaken an informational or emotional ending; avoid stacking several unrelated asks.\n\nDivide longer videos into meaningful chapters with a recurring rhythm: **chapter question or promise → explanation → evidence/example → concise takeaway → bridge to the next question**. This pattern provides orientation while leaving room to vary the footage and graphics. Use short chapter names and a consistent visual treatment; do not interrupt every paragraph with a full-screen divider. A chapter transition should resolve the previous point and establish a reason to continue. Short videos can use the same logic across a few beats without formal chapter cards. Include chapter boundaries, key evidence, takeaways, and the intended closing action in the script/edit plan.\n\nUse the requested orientation and treat the requested runtime as an approximate planning target. If they are unresolved, choose sensible defaults from the destination and communicate them briefly. Budget the script for a natural speaking pace with room for pauses; do not ask the avatar or voice to rush or stretch its delivery to hit a number. Once generated, the actual A-roll determines the edit timeline. For example, a 45-second target may finish at 47 seconds without correction. If a hard destination limit or a substantial mismatch requires a shorter version, revise the script or make content edits within the user's authorization; preserve exact supplied speech unless changes are approved. Never solve it by retiming A-roll. Present a newly written or revised script for confirmation in this script stage before paid generation; an exact script already explicitly approved needs no repeat confirmation. Resolve meaningful script uncertainty before paid generation. Do not add another asset-board or screenplay approval round beyond this script confirmation unless requested; avatar/look confirmation remains required.\n\nCreate an internal edit plan mapping script beats to presenter footage, B-roll, overlays, graphics, captions, and sound. **Always interrupt the plain A-roll with purposeful visual changes throughout the video.** Achieve that variety through timed captions, overlays, and cutaways while preserving the underlying A-roll image. Plan around changes in meaning and actual spoken cues; do not mechanically cut or trigger an effect every few seconds. Ordinary subtitles alone do not satisfy the visual-variety requirement. Brief clean presenter holds can let an important line land, but long unplanned stretches of bare A-roll need an editorial solution. A stable, readable graphic can sustain interest without constant movement. If exact-subject B-roll is unavailable, choose a useful abstract explanation or caption treatment rather than inventing imagery.\n\nChoose the treatment by the job of the current beat:\n\n| Treatment | Use it when | Execution and exit |\n| --- | --- | --- |\n| Brief A-roll with base subtitles | Trust, expression, a personal statement, a crucial qualification, or a payoff is best delivered by the person | Let the line land without competition; resume visual development at the next meaningful beat |\n| B-roll video | A real action, place, process, texture, or demonstration is the evidence | In portrait social edits, fill the frame with the relevant action; hold long enough to understand it, keep narration continuous, and return for the conclusion |\n| B-roll image | The exact subject exists as a photograph, screenshot, document, or before/after view | Give it a deliberate treatment: a brief readable insert over A-roll, a purposeful Ken Burns move, a detail reveal, or a temporary face-safe split; preserve evidence and maintain the audio flow |\n| Motion-graphic overlay on A-roll | One number, location, relationship, or label supports what the presenter is saying | Keep it small and outside the head region; clear it when that claim is finished |\n| Full-screen motion graphic | A mechanism, comparison, timeline, or transformation needs undivided attention | Reveal only the current state, transform or replace it on the next cue, and return to footage once explained; do not cut to a slide just to display a sentence |\n| Stylistic caption | The exact phrase, contrast, correction, or reveal is the event | Emphasize that spoken phrase briefly in the chosen style, then restore ordinary subtitles |\n| Chapter treatment | A longer video moves to a genuinely new question | Use a short consistent marker or divider with an audio bridge; avoid a title sequence that stalls momentum |\n\nDo not combine every treatment on the same beat. Choose one leading visual and only necessary support. A full-screen graphic is not a dashboard, and a dramatic caption cannot replace visual evidence when the claim requires it. Keep explanatory graphics, the active caption treatment, and the presenter from competing for the same focal area.\n\n**Choose one opinionated visual style suited to the subject, audience, and tone, then commit to it throughout the edit.** Use the [fifteen style directions in motion graphics](../motion-graphics/SKILL.md#choose-one-visual-style), including Swiss precision, paper-cut, watercolor, woodcut, and painterly surrealism, or create an equally specific original style. Make the choice rather than asking the user to art-direct routine details, while honoring supplied branding and explicit preferences. Do not average several styles into a generic template or switch aesthetics for each beat. Translate style into typography, color, and motion; it does not require persistent borders, large empty page margins, footer slogans, or tiny editorial labels. Briefly name the direction and why it fits.\n\nTranslate that direction into a concrete series style specification: palette, font families and weights, type scale, spacing/grid, shapes, line weights, texture or shading, framing, caption treatments, transitions, motion timing/easing, and audio character. Apply it consistently to opening hooks, ordinary subtitles, stylistic captions, lower thirds, charts, diagrams, overlays, generated edit assets, B-roll framing, and the closing. Variation should come from composition and emphasis within the chosen language; do not switch to an unrelated aesthetic for each beat. Preserve the factual appearance of real footage and products. Code-generated visuals must stay abstract or logical: charts, diagrams, geometric forms, and consistent icon assets. Do not construct figurative objects or scenes out of Python shapes. Save the specification and shared style values in the Python project configuration for reuse across episodes.\n\nApply the chosen style to captions, graphics, cutaways, and sound while retaining the presenter's actual setting and baseline framing. For portrait A-roll, use the confirmed look's native portrait composition. Do not manufacture text space by removing its background or reducing the person. For B-roll, select a native portrait source or a deliberate crop that preserves the evidence; if essential content would be lost, choose a better asset. An image-B-roll split may temporarily place the image beside or above/below the intact presenter, keeping the face visible throughout. Tile the full canvas, keep this layout local to its beat, and restore the original full-frame A-roll afterward. Avoid a persistent small presenter panel or floating inset. Safe zones constrain essential text and content, not the extent of the footage.\n\n**Make the style visible, not merely named.** Choose one suitable direction and commit without generating competing style studies or asking the user to choose a routine design preset. For example, tactile cobalt-and-cream paper collage can pair dimensional paper graphics with ink-like captions and matching generated illustrations; cinematic amber-and-ink can pair photographic inserts with bold condensed captions and precise light/mask reveals. These are examples, not universal defaults. A new accent color on generic dark cards is not an art direction. Carry the chosen material, palette, typography, lighting, shapes, and motion across graphics, image B-roll, and captions. Turn explanation into a visible event: an allocation block transfers, a shared exposure merges, a detail is revealed. Use narration for prose; keep only labels that identify what changes. Establish the visual promise in the opening and develop it through the middle and payoff.\n\n**Budget attention per beat.** Give each interval one named focal owner: presenter, B-roll detail, graphic transformation, or caption phrase. Only that owner receives the strongest contrast, largest scale, and attention-grabbing movement. When a graphic leads, keep speech captions compact and calm beside its focal region; do not animate keyword pops at the same time as a diagram reveal. When captions lead, settle the supporting image or graphic. Clear outgoing copy before the next reading task. Merge identical caption/graphic wording into one timed treatment while preserving all spoken information. Never stack a headline, paragraph, diagram labels, and an equally loud caption. Use compact phrase captions, usually roughly 2–5 words, one line when possible and at most two, regrouping rather than deleting meaning. Use bold, carefully spaced type, one meaningful accent word, local contrast protection, and a short controlled reveal. Avoid full-sentence boxes, scattered karaoke, and repeated decorative underlines. Caption style must be visibly designed even in ordinary speech beats, with quiet holds to make selected emphasis land.\n\nBefore designing edit assets, read [motion graphics](../motion-graphics/SKILL.md) for focused Python graphics and [captions](../captions/SKILL.md) for subtitle timing, opening hooks, and expressive emphasis. These are the owners of detailed graphic and caption guidance; pass them the same style specification, timeline, and shared one-round review budget. Their checks belong in the integrated review, not separate helper review cycles.\n\nOpen with a catchy, truthful hook caption. **Include synchronized subtitles throughout A-roll and B-roll by default**, with selective stylistic-caption moments in the middle. During hook/emphasis intervals, replace the ordinary subtitle treatment with one coherent text treatment that preserves the relevant spoken information, then resume base captions. Do not stack competing layers or drop unrelated words. Honor explicit user caption preferences and save a complete plain subtitle track with the project.\n\n## 5. Submit A-roll, prepare the edit, and stay in the production loop\n\nAfter look and script confirmation, submit `create_video_from_avatar` once with the confirmed look, supported engine, exact script or authorized audio source, selected voice where required, and explicit aspect ratio/resolution. Follow the live schema and casing. Prefer MP4 and 1080p when supported and appropriate; request native 9:16 for portrait social. Preserve the look's background/composition. Do not request background removal, transparency, replacement backgrounds, or subject extraction unless explicitly requested. Keep music, effects, titles, captions, and B-roll out of this source render; they belong in the edit. Do not duplicate narration by submitting both speech text and an audio source improperly. Record the request and returned source ID, look, engine, and voice.\n\n**Tool-result handling: `create_video_from_avatar` → `get_video` → coded edit → final media preview. Never insert `show_video`.** Generic avatar-tool guidance may say “show immediately” or let the player poll; that describes delivery of a standalone avatar video. Here the user requested an edited production and the avatar is only an intermediate asset: use this workflow's explicit polling and final-only delivery rules instead of standalone-avatar preview defaults. A `show_video` recommendation in a creation/setup/status response does not turn the source into the deliverable. Do not mount a raw player to check readiness, obtain a link, or signal progress. Use `get_video` directly with the returned ID, then follow this loop:\n\n| Observed state | Required next work |\n| --- | --- |\n| Submitted; ID returned | Save the ID and perform a status read with `get_video`, respecting any returned first-poll delay. Begin independent edit preparation immediately. |\n| Queued, processing, or another nonterminal generation state | Continue useful preparation between `get_video` reads. Honor the returned interval, or wait about thirty seconds between reads when none is supplied. Do not end the turn or ask the user to come back. |\n| Edit preparation finished; A-roll still pending | Keep waiting and polling silently. Finished scaffolding is not a reason to leave the loop. |\n| Completed/ready with usable media | Retrieve the source, inspect framing, measure duration, and obtain actual speech timing. Fit the prepared assets to it and continue through editing, quality review, final encoding, and delivery. Do not stop at source completion. |\n| Reported ready but media is not yet available | Follow a documented retrieval/readiness path; do not invent a URL or call `show_video`. If the host cannot transfer the bytes, report that concrete blocker and preserve the project. |\n| Terminal failure/cancellation or actual access/execution error | Preserve the ID and completed work and report the returned issue. Apply the service's bounded read-retry guidance where relevant; never resubmit paid generation to check status or blindly recreate a failed job. |\n\n**Use rendering time for real production work.** Before A-roll is ready, build the graphic compositions and transitions, prepare B-roll assets and their entry/move/hold/exit treatments, render caption typography/highlight assets, and implement the edit/compositing code. Prepare the optional image batch from step 6 in this interval too. Use semantic anchors such as exact script phrases and parameterized event durations, not invented final timestamps. Check one representative graphic/caption layout on the full output canvas while implementing it, then reuse the established style values and rendering functions. Do not keep redesigning completed assets while waiting for A-roll. Alternate preparation with due status reads; when the host supports independent concurrent jobs, let image generation and avatar rendering overlap. Do not block all preparation behind the first pending status or prepare only a written plan.\n\nAfter retrieval, replace provisional timings with actual word/phrase alignment, inspect the rendered head bounds, fit every caption and B-roll/graphic cue, and review their overlaps. Do not use estimated script timing in the final export. Save the actual returned HeyGen video-page URL, or verify the supported heygen.com route for the source ID, for the raw-asset link at delivery. An expiring media URL is not that page. Retrieve media only through supported transferable URLs/file access; do not invoke app-only download helpers requiring a user widget click.\n\n**Stay in the loop until the whole authorized task is finished.** This persistence requirement applies to obtaining the source and delivering the edit; it does not extend the one-round review budget. Once preparation is complete, wait between status reads rather than repeatedly inspecting unchanged assets. Do not issue a final answer, a “your avatar is ready” handoff, or a “shall I add the edits?” question before completing the edited output. No messages merely saying generation is still pending. Meaningful production decisions, real failures, and required user input may be communicated; ordinary latency and routine creative choices are not blockers. Stop early only for a terminal failure/cancellation, a real access/execution blocker, an explicit user stop, or a genuinely missing required decision. Do not invent a timeout or use an arbitrary number of successful pending reads as a reason to abandon the task.\n\n## 6. Compile useful B-roll\n\nCombine the user's uploaded photos and videos with relevant online images and footage where appropriate. Search for the actual location, building, product variant, process, or context the script describes. Open source pages to confirm identity and provenance; a search thumbnail or matching filename is insufficient. Prefer authoritative subject sources and assets with clear reuse terms. Online availability alone does not establish permission to reuse a video or image.\n\nRecord the source page, media reference, creator, license or permission basis, required attribution, and intended use for each online asset. Retain user-upload provenance too. Use media that can actually be obtained and incorporated within the available tools and permissions. Do not bypass access controls, remove watermarks, or download remote media to evade host display restrictions. If access or reuse is unresolved, use a suitable cleared alternative or ask for the user's own material.\n\nMatch each asset to the specific **action or claim**, not merely a broad noun. A generic laptop shot says little about distraction; a relevant task interruption or a visible planning action can advance that story. Vary useful shot scale and action across the sequence. **Never reuse the same B-roll image in separate intervals of one video**, including callbacks, recaps, and the ending. Track each image's source identity and derivatives in the asset manifest; a crop, mirror, zoom, recolor, or renamed file still counts as the same image. One continuous treatment can change framing, but once the image exits, use a distinct relevant image or another visual treatment. Reuse cached assets for rerenders of their existing placements. Repeating a video clip is a separate editorial decision and must have a deliberate purpose. Track whether footage depicts the actual subject or is illustrative context. Do not present a generic interior as the listed home, an adjacent town as the named neighborhood, or a similar product as the actual model. Label illustration when needed and avoid implied factual evidence. Ask for missing exact-subject imagery when substitution would mislead.\n\nInspect asset dimensions, orientation, duration, and content sufficiently to make useful crop and timing decisions. Prefer native vertical footage for portrait edits; otherwise test the actual crop before selecting the shot. Keep faces, important property details, labels, and product features visible and clear of platform controls. Silence unrelated source-video audio unless it contributes intentionally. Organize assets with stable names and retain originals. Avoid irrelevant landscape stock reduced to a strip while most of the portrait frame is empty.\n\n### Optional imagegen B-roll: one batch, at most five images\n\nWhen native imagegen is available and original illustrations or conceptual images would improve the story, create **up to five distinct B-roll images in one batch for the video**. This is optional, not a quota. Decide all image subjects and write all prompts before starting generation. Use a real multi-image batch interface when provided, or dispatch one call per distinct image concurrently in one orchestration batch when supported. Do not await image 1 before launching image 2, run serial batches, or generate a second batch of aesthetic alternatives. Count all requested outputs/variants toward the five-image limit. Use the actual tool schema; do not invent a batch/count field or ask for a tiled contact sheet as a substitute for separate usable assets. If concurrency/multi-image output is unavailable, generate at most one image or use existing assets instead of serializing five slow calls. Do not switch to a different paid image service merely to bypass this constraint.\n\nEach prompt must carry the same chosen art direction: material/rendering style, palette, lighting, texture, and shape language; give it a distinct narrative job, subject/action, composition, output orientation, and crop/movement room. Design for the planned treatment and caption region. Ask for image content without baked-in captions, titles, labels, or logos; render precise text in code. Preserve real product/person/place identity where applicable. Generated conceptual images must not masquerade as documentary evidence or invent details about the user's actual subject. Use real supplied/sourced media when the claim requires it.\n\nSave each returned image as a separate asset and inspect it before use for style fit, relevance, defects, and sufficient resolution for the intended crop. Drop an unusable image or replace its beat with another available treatment; do not automatically regenerate the batch. Record the prompt, returned asset identity, and its one continuous timeline placement. **No image may reappear later in the video**, whether generated, supplied, or sourced; a different crop, recolor, mirror, filename, or zoom is still the same source. A batch of five is not permission to loop five images through the runtime.\n\n**Art-direct every image-based B-roll beat so the edit keeps flowing.** Do not simply park an untreated photograph full screen. Choose a treatment that serves the current idea and the established style:\n\n| Treatment | Execution |\n| --- | --- |\n| Brief insert over A-roll | Reveal the image on its spoken cue with a purposeful slide, mask, or quick cut; let it register, then clear it. Keep the face visible and the image readable. A brief flash means one legible insert, not strobing or a blink-too-fast evidence shot. |\n| Push-in / pull-out / Ken Burns | Push in to reveal a detail, pull out to reveal context, or pan along a meaningful relationship. Define start/end crops and easing; use one purposeful move with a readable hold, not a repeated in/out loop. Animate only this image and avoid exposed edges or loss of essential detail. |\n| Temporary split screen | Let the image occupy roughly half the canvas and temporarily scale/shift the intact A-roll to the other side or below. Preserve its background and proportions, keep the face fully visible along the whole transition, and restore baseline framing on exit. Do not cut out the presenter or create a permanent page layout. |\n| Guided detail reveal | Introduce a document, screenshot, or photograph at useful scale, then reveal or highlight its relevant detail. Keep essential labels stable long enough to read; the treatment may settle into a hold. |\n| Shading / dimensional treatment | Use a restrained light sweep, local shading, or a consistent edge/shadow treatment on image B-roll when it belongs to the chosen style. Keep the important detail visible and factual. Apply it to that B-roll layer only, never as a presenter-body fade or a full-composition vignette. |\n| Motivated image transition | Match a focal position, color, or shape across a cut, or use one style-consistent mask/wipe to reveal the next distinct asset. Keep most cuts clean; a transition must connect beats and leave enough time to see the image. |\n\nRecord entry, focal move or reveal, start/end crop, readable hold, exit, shading if used, and any temporary presenter transform in the cue sheet. Preserve a clear image focal point; do not combine every treatment on one asset. Maintain continuous narration and style-consistent captions across the beat. Vary treatments by meaning rather than applying the same zoom everywhere; avoid motion that obscures evidence or interrupts the argument. If an image cannot carry its beat clearly, choose another asset or a graphic instead of replaying an earlier photo.\n\n## 7. Edit the completed A-roll through code\n\n**Use Python as the default coding language for editing, motion graphics, captions, procedural music, and sound effects.** Build a reproducible Python project using available imaging, audio, and video libraries and/or Python-driven FFmpeg. Use another programming language or rendering stack only when the user explicitly requests it. Inspect the actual environment and use supported installed capabilities. Do not require a particular unprovided library or invent a rendering API. If Python execution or necessary rendering capabilities are unavailable, explain the specific blocker rather than silently switching stacks or claiming an MP4 exists.\n\nKeep the avatar performance and its original dialogue audio as the timing spine at **1.0× playback speed**, including while B-roll or graphics cover the presenter. Measure the real source duration and derive speech-aligned edits from actual audio or returned timing; transcribe and align locally when needed and available. Retain corrected word/phrase times. Do not estimate them from script length. Never apply a target/source duration ratio, speed ramp, audio tempo filter, time-stretch, or sample-rate/frame-rate reinterpretation that changes playback speed. Output frame-rate and sample-rate conversion must preserve elapsed time and speech speed. Keep picture and dialogue paired; avoid cutting words, drifting lip sync, or changing the confirmed presenter's face through an effect.\n\nTreat the intact A-roll as a full-frame base layer. Outside a planned image-B-roll split interval or an explicitly requested framing treatment, when source and output aspect ratios match, preserve the entire image and scale uniformly only to the output resolution: the source rectangle maps to `(0, 0, output_width, output_height)`, without an extra crop, offset, padding, or alpha mask. For a split, transform only the A-roll layer for that bounded interval, preserve its background and proportions, and restore its baseline on exit. Do not apply a decorative scale/translation to the composition root or finished video; that moves every layer and can create an off-center, undersized export even when the file dimensions are correct. Keep caption-safe coordinates local to captions and graphic layers.\n\nIf a specifically requested aspect-ratio conversion requires a crop, make only the minimum necessary adaptation, retain the background, and inspect the resulting framing before proceeding. If essential content cannot survive that conversion, resolve the framing choice with the user. A format conversion does not authorize later zooms, punch-ins, subject extraction, or decorative margins. Keep B-roll fitting and graphic animations local to their own layers and intervals. After a cutaway, restore the same A-roll scale and position.\n\n**Center overlays against the full output canvas.** Declare final `W`, `H` once. Default caption groups to horizontal center `cx = W/2` and full-screen graphic groups to `(W/2, H/2)`, then make only a deliberate vertical adjustment for captions/UI or a documented composition choice. The center is 540 horizontally on a 1080×1920 export, regardless of presenter placement, a split panel, or platform exclusions. Use the measured visible group bounds, including typography, outlines, shadows, and backplates; a full-size transparent overlay or background rectangle must not count as the content bounds. For local bounds `(left, top, right, bottom)`, translate by `dx = cx - (left + right)/2` and `dy = cy - (top + bottom)/2`. Center multiline text within that group. Apply the local-to-output transform exactly once and keep the composition root unchanged.\n\nAsymmetric UI exclusions reduce available width without moving the center. At the chosen vertical band, if the usable horizontal interval is `[L, R]` and contains `cx`, the largest centered width is `2 * min(cx - L, R - cx)`. Thus x=8–80% permits a centered group within x=20–80%, **not a group centered at 44%**. Regroup words, narrow the graphic, move vertically, or use a cutaway when bounds conflict; do not shrink type below readability. Document any necessary intentional offset rather than silently inheriting a helper's left margin. Inspect both the settled group's numerical center and its optical balance, plus entrance/exit clipping. A wide but nearly invisible decoration must not conceal off-center main content.\n\nBuild a cue sheet before final animation: each beat includes source in/out, final start/end, exact spoken anchor, leading visual, caption mode, graphic states and their reveal/hold/clear times, and sound cue. Specify what changes at each cue and why; a scene name plus one static layout is insufficient for a multi-part explanation. Distinguish source-media time from final-video time. Each retained A-roll segment advances one source second per final-video second; its final duration equals its retained source duration, within frame/sample rounding. Update all downstream cues after any dialogue trim; do not patch caption offsets by eye while leaving graphics on the old clock.\n\nPlace B-roll or supporting context just before or on the relevant spoken idea when that helps comprehension. Land a reveal or important number on its actual cue, and keep the evidence visible through the explanation. Return to the face for an emotional reaction, qualification, conclusion, or invitation. Let the audience register an image before replacing it; a complex diagram needs more time than a familiar close-up. If the beat cannot accommodate the material, simplify or divide the visual rather than rushing the viewer.\n\n**Default to hard cuts for most moves from A-roll to full-screen graphics, back to the presenter, and between graphic scenes.** They suit brisk explanations and simple charts, quotes, or comparisons. Land the cut on a spoken cue, punchline, or resolved visual beat. Let presenter audio continue over a cutaway (an L-cut relationship); where useful, introduce the next thought's audio before returning to its picture (a J-cut relationship). Keep source picture and dialogue aligned wherever the mouth is visible. Do not shift the audio of a visible face to simulate an audio bridge. Preserve meaningful pauses and breaths. Cover authorized dialogue edits with relevant B-roll where useful and inspect the audio joins for clipped consonants, duplicate syllables, or abrupt ambience changes.\n\nUse stylized transitions selectively when a shared visual element connects the shots, a major chapter/time/mood shift needs a marker, or a smoother handoff serves the established cinematic tone. Apply the [cut and transition guidance](../motion-graphics/SKILL.md#choose-cuts-and-scene-transitions): an existing graphic bar can wipe across A-roll to reveal the next scene, a matched shape can connect shots with a hard cut, and a brief dissolve can soften a reflective break. Keep zooms and any directional blur on graphic/transition layers; do not add punch-ins, blur, warping, or reframing to the presenter merely for an effect. Fit the bridge inside the beat, preserve narration and caption continuity, and settle before the incoming graphic must be read. Return to baseline A-roll framing on exit. Most boundaries should remain hard cuts; a polished brand video does not need a different preset at every change.\n\nSet visual cues from speech and meaning first, then fit music accents around them. Do not move a crucial explanation to the nearest music beat or add a sound effect to every cut. Use contrast in pace: a brief energetic hook, clear evidence beats, space for a takeaway, and a deliberate close. Maintain visual variety across the video without turning every instant into another reading task.\n\nAudit the moments **between** spoken phrases as well as the phrases themselves. Preserve breaths and intentional anticipation, but trim unnecessary generated lead-in, dead pauses, and tails when ordinary editing is authorized. Make those cuts for editorial clarity, never to shave off fractions of a second until a target is met. Do not remove natural pauses, cut off a line, freeze/repeat frames, loop footage, or add silence or a static card to force a nominal runtime. End after the last useful payoff or CTA and its necessary reading/resolve time; the final few seconds need as much editorial purpose as the opening. A multi-second silent slogan hold after the speech ends needs a specific reason.\n\nBefore placing motion graphics, visual hooks, or captions over the A-roll, extract and inspect a representative screenshot of the actual rendered presenter, including the original background. Locate the head and face and define a padded exclusion region in the final output coordinates. The head usually moves little in this format, so one representative frame is normally sufficient; do not require continuous tracking. Keep informational overlay text and graphics, including their animated entrance and exit paths, outside that region. A brief scene-covering wipe replaces the shot and follows the transition rules above. Save the bounds with the baseline A-roll placement. For each planned image-B-roll split, transform the head bounds with the A-roll and check entrance, hold, and exit for a fully visible face; hand those interval-specific bounds to graphics and captions. If an overlay collides, change the overlay's position, size, wording, or timing, or use a separate full-screen graphic beat. Do not introduce a presenter transform merely to fix text collisions. Recompute bounds for a necessary output conversion, planned split, explicitly requested framing change, or new look.\n\n**Prefer captions in a top or bottom band within the usable safe area**, leaving the central region available for the narrator and motion graphics. Keep them horizontally centered on the full canvas. Choose the band that clears the actual face and the current graphic, and keep that position stable across ordinary cues; switch bands only at a meaningful shot/layout change when needed. Bottom captions must sit above platform descriptions, account/audio controls, and navigation with breathing room; top captions must sit below top controls and clear the head. Fit the entire text group, including stroke, shadow, and animation, inside the usable bounds—not merely its baseline. Use the [captions skill's platform-mask procedure](../captions/SKILL.md#7-coordinate-caption-modes-and-layout) in the existing single review round. A central hook/emphasis treatment is appropriate when the words are the primary visual; if neither band fits ordinary captions, simplify the graphic or use a cutaway before covering the narrator. Carry the same UI exclusions into graphic labels and essential B-roll details. Keep footage full frame without a blank caption gutter or a presenter transform to create text space.\n\nBuild a publication-ready edit using the elements below. The mix is a creative choice, but an immediate visual hook, default subtitle coverage, and recurring disruptions of plain A-roll are required. Sustain interest through the middle and closing as well as the opening; do not spend all the editorial effort on an intro and leave the rest untouched.\n\n**Build a clear, cohesive edit with deliberate graphics, image treatments, and readable captions.** Apply the chosen style throughout the video and time visual changes to the speech. Reuse successful layouts and assets where appropriate while retaining the rule against repeated B-roll images. Use the single review in step 9 to catch concrete problems; do not pursue open-ended polish, redesign working sections, or spend extra iterations on subjective alternatives. Quality is established by the checks below, not by time spent.\n\nEffort should improve the requested edit without restyling the source footage. When revising a video, preserve caption treatments, motion graphics, timing, and other elements the user explicitly liked. Fix the identified background or framing problem at its source; do not compensate by redesigning successful graphics or adding another effect.\n\n1. **Background music written through code.** Compose an original instrumental bed programmatically: generate note sequences, harmony, rhythm, instrumentation, envelopes, and an arranged ending with a supported synthesis/audio library or direct PCM/WAV synthesis. Save that composition code and its seed. Fit its mood and tempo to the subject, leave space for speech, and duck it under the presenter. Do not replace this step with selecting a stock track or calling a music-generation service. Omit music for a brief that benefits from silence or explicitly requests none.\n2. **Sound effects.** Add restrained transitions, accents, clicks, or other motivated effects at actual visual events. Generate simple effects in code when practical, or use appropriately cleared/user-supplied effects. Shape transients, volume, and decay so effects support the beat without masking consonants or punctuating every cut.\n3. **Motion graphics and captions.** Apply the linked skills. Storyboard successive visible states, validate each readable hold, and keep one dominant focal point at each moment. Use abstract/logical representations or real icon assets. Clear completed information instead of accumulating a slide. Coordinate subtitles, opening hooks, and selected emphasis moments from one caption schedule; avoid redundant headings and competing text layers.\n4. **B-roll integration.** Place actual images/videos over the relevant A-roll beats while preserving presenter audio. Default to edge-to-edge cutaways for portrait social; use canvas-filling split screens only when simultaneous views help. Normalize source sizes and frame rates through the renderer and inspect cover crops. Use clean cuts and subtle moves for a reason; maintain a clear route back to the presenter.\n5. **Finishing.** Balance speech, music, and effects; prevent clipping, distracting loudness jumps, and abrupt endings. Set explicit frame rate and dimensions, and derive export duration from the completed natural-speed timeline. Never force the composition to the requested target by changing playback speed, truncating speech, or padding it. Export a broadly playable MP4, normally H.264 video with AAC audio and a compatible pixel format when supported. Resolve the last beat and audio cleanly, with no padded static outro.\n\nUse the rendered avatar for identity continuity; code handles composition and presentation. Correct an edit problem in code without paying for new A-roll. Regenerate A-roll only when a user-authorized change actually requires it, such as revised spoken words or a different confirmed look.\n\n## 8. Save a reusable series project\n\nSave the actual working source used to produce the final MP4, not a pseudocode sketch written afterward. Keep the project in a persistent deliverable directory with:\n\n- Editing/composition source, procedural music and effects source, and a single documented render command.\n- A configuration file for title, chapter/episode metadata, input paths, cue sheet, corrected transcript/alignment, caption modes, colors, fonts, lower thirds, graphics, and output settings so another episode can reuse the treatment, plus a complete plain subtitle sidecar.\n- Separate values for the approximate target length, measured source duration, and final edited duration. The target informs script planning; it must never become a playback-rate multiplier or forced export length.\n- Original A-roll dimensions/background, baseline placement, any necessary format conversion or explicitly requested framing treatment, head exclusion bounds, and destination UI masks/provisional safe-zone profiles.\n- Required dependency/version information, any deterministic seeds, and the actual assets needed for a repeat render where redistribution is permitted.\n- An asset/timeline manifest identifying A-roll, avatar/look/engine, B-roll source identities and single image placements, any imagegen batch/prompts and total requested outputs, image treatments and bounded split transforms, source provenance and attribution, generated audio, and speech timing.\n- Brief instructions identifying what to replace for the next episode, where to update timings for new A-roll, and which branding/animation settings carry across episodes.\n\nUse project-relative paths and avoid relying on a temporary directory, machine-specific absolute paths, expired signed URLs, secrets, or credentials. Save transferable media locally when authorized; where redistribution is restricted, record the lawful retrieval requirement and clearly identify the missing dependency. Never describe a project as self-contained if it requires inaccessible assets. Zip the reusable project when useful, preserving source and attribution files.\n\n## 9. One review round, then deliver the finished MP4\n\n**Cap post-editing review at one round for the whole video.** This is one inspection of the assembled cut, one consolidated list of concrete fixes, and at most one correction batch before the final export. Motion-graphics and captions share this same round; do not add separate story, design, motion, caption, or per-scene review cycles. Implementation checks such as measuring text bounds or testing a renderer do not justify repeated aesthetic previews. Further creative review or polish requires a later explicit user request; do not ask for one just to prolong production.\n\nRender one inexpensive preview with actual audio. Review the full short video once at normal speed and phone size. For longer videos, use one review session covering continuous passages from each chapter, the opening/ending, major handoffs, and flagged cues; report unreviewed portions. Use the same preview and selected diagnostic frames for all checks below instead of rerendering or replaying the full cut for each criterion:\n\n- **Focus and style:** one dominant visual per interval; concise text; consistent typography, colors, image treatments, and motion; purposeful B-roll/graphics through the middle; a clear opening and ending. Flag obvious clutter, generic filler, competing reading tasks, and extended unintended bare A-roll. Do not reopen a working style for subjective alternatives.\n- **Placement and captions:** measured visible content centered against the full canvas, readable phrases timed to actual speech, complete subtitle coverage, no doubled hook/emphasis layers, and clear face/platform regions. Use centerlines, measured bounds, and UI masks on representative frames, including the longest caption and a graphic handoff; remove those guides from the export.\n- **Source integrity and B-roll:** original presenter background/framing retained, temporary splits keep the face visible and return to baseline, no duplicate image source in separate intervals, and image movements preserve the relevant detail. Check the first presenter shot and each distinct layout's return against the source; reuse that result for repetitions of the same transform.\n- **Timing and sound:** retained A-roll and dialogue remain at 1.0×, source/final segment durations match, captions and graphic cues follow actual alignment, and dialogue remains intelligible beneath music/effects. Check representative lip sync, audio joins, and the ending. Reject speed multipliers, target-duration stretching, cropped words, and artificial padding; accept small differences from the approximate target runtime.\n\nCollect findings during that single review, then fix them together in one local correction batch while preserving successful A-roll and assets. Prefer the smallest correction that resolves the observed issue: remove redundant text, correct an anchor or cue, simplify a collision, or adjust a level. Do not produce alternate versions or restart a full review after each fix. If the preview already passes, proceed directly to final export.\n\nAfter final encoding, perform only a brief technical verification: valid playable MP4, intended dimensions, duration matching the edit, expected audio stream, and spot checks of corrected locations for the specific defects found. This is not a second aesthetic review or full-video replay. Repair an actual render/export failure with targeted diagnostics; do not use that exception to start another design or polish cycle. When the file is valid and identified corrections are verified, deliver it. State material unresolved issues or review limitations honestly; do not claim playback/listening checks that were unavailable or certify all factual details from a successful encode. Report measured runtime.\n\n**Show the finished edited video first, then give download and raw-asset links underneath.** On hosts supporting local video, embed the actual final MP4 inline using the host's media syntax (for example `![Finished video](/absolute/path/final.mp4)`). Use a supported artifact/video preview for the edited output where available. Do not call `show_video` for the raw A-roll at delivery either; provide its HeyGen page as a link beneath the final preview. Verify the preview points to the final encoded file with the edits applied, not a similarly named source file. If inline playback is unavailable, state that limitation and provide the playable final artifact without claiming it was shown. Beneath the preview provide clearly labeled links to **Download final video**, **Raw A-roll on HeyGen** (the saved verified heygen.com page), and the reusable source-project folder/archive. If the raw page URL cannot be verified, report that specific missing link and retain the source ID instead of fabricating one. Include measured runtime and material review limitations briefly. The HeyGen raw player, pending ID, thumbnail, and source code alone do not satisfy delivery. State that the project can be referenced to request the same style in future episodes.\n\nRetain the compact project ledger for revisions and reuse. Do not publish to social accounts, upload unrelated material, or perform account actions beyond the requested production. For failed or cancelled paid jobs, explain the returned issue without automatically recreating them; reconcile an uncertain write outcome before any retry.\n"
}