skills/talking-head-guide/references/captions.md

- Captions are edited as an SRT-like ordered Card list. Read once with `read_captions`, then use its Card ids and revision with `set_card_text`, `set_card_style`, `set_card_span_style`, `merge_cards`, or `reset_card`. Caption style uses `captionStyle:{version:1,...}` CSS slots with parallel `fontFamily`, `fontFallbacks`, `presentation`, and `pagination`; geometry belongs to layout, never captionStyle. If the user identifies one Card, use `set_card_style`; if they identify exact text/words, use `set_card_span_style`. Each span entry has sibling fields: `{"text":"...","style":{...},"activeStyle":{"animation":{...}}}`. `style` is the always-visible appearance; `activeStyle` applies only while that span's timed words are spoken. NEVER put `activeStyle` inside `style`. Animation samples the active overlay over the stable normal text. If the highlight background itself should fade or move, put `backgroundColor` in `activeStyle`, not `style`; a background in `style` stays visible throughout, and animation with no active paint difference can be invisible. Span animation supports deterministic enter/exit keyframes using `opacity`, typed `transform` fields (`translateX`, `translateY`, `scale`, `rotate`), and bounded `clipPath:"inset(...)"`. For a true left-to-right highlighter wipe use `inset(0 100% 0 0)` to `inset(0)`; do not use polygon/path/round clipping or browser animation names. "Swipe" is an intent to encode with inset or translate keyframes, not a literal `highlightAnimation:"swipe"` value. Never move a span request to track-wide `style`/`source_update`, and never claim Card or span animation is unsupported. Apply global segmentation with one `style` pacing call (`auto`, `phrase`, or `word`); `resegment_cards` is only its legacy alias and must not be expanded into sequential `split_card` calls. Pacing structurally rematerializes Cards and invalidates prior Card ids, so run `read_captions` afterward, repair any reported translation coverage, and use the new ids. Font size and box geometry are not segmentation actions. Legacy `display_text` word overrides are compatibility-only. NEVER edit the transcript to fix caption wording or boundaries — `manage_transcript fix` is only for an ASR-misheard source word.

- Exact-word font sizing is supported. To make highlighted or named words larger or smaller, call `set_card_span_style` again for the same text with `style.fontSizeScale` (for example, `1.15` for 15% larger); the existing span style is merged and preserved. `fontSizeScale` is relative to the Card's effective font size. NEVER use Card-level `sizePx` or `fontSizeRatio` for this request, never resize every Card containing a highlighted word, and never claim partial-text sizing is unsupported.

### Goal

Improve accessibility and engagement with on-screen text.

Captions start from the source transcript. When the user asks for translation or bilingual captions, use `edit_captions` action `translate`; its `languageCode` is the translation target. Languages are ordinary caption sources, so use `set_sources` to switch among translations that already exist.

### Presets

Prefer built-in caption presets because they provide more stable, tested results. Use only real built-in `edit_captions` preset names; there is no `youtube` or `vox` preset.

- For a general style request, first list the language-aware presets with `edit_captions` action `template`, then choose one or offer relevant returned presets for the user to choose from.
- Use custom `style` / `layout` only when the user clearly requests a custom look or a specific adjustment.
- For adjustments, start from the closest preset and change only the requested properties.

### Optional emphasis follow-up

After captions are first created and verified, if the user has not already requested emphasis, ask once whether they want it. Base the question on the actual caption content: mention only relevant categories—such as data, concepts or conclusions, people, organizations or product names, steps or actions, and contrasts or risks—and include an option to let the Agent decide. Treat a chosen category as guidance, not a requirement to emphasize every match. Do not interrupt an explicitly requested end-to-end workflow; offer this only after the requested work is complete.

Emphasis is opt-in. Once requested, read the complete caption sequence with `read_captions`. First choose Cards whose content adds distinct value for understanding, recall, action, decision, state tracking, or an expressive payoff. Suppress setup, filler, and repeated payloads; allow adjacent selections when each adds something independent, and let the content determine how many spans to emphasize.

Within each eligible Card, choose the smallest contiguous verbatim span that remains truthful. Preserve negation or modality, conditions, scope or uncertainty, required units or referents, indispensable action objects, and both sides of a contrast when needed. If the same text occurs more than once, use `occurrence`; use `languageCode` to target one bilingual projection.

Apply the requested spans with `set_card_span_style`, then read the captions again and verify the resulting `inlineStyles`. Do not change caption wording, timing, Card boundaries, line breaks, position, pacing, or overall style.