--- name: scenario-caption-studio description: "Use when a video needs its spoken words on screen through Scenario via MCP: burned-in styled captions for a TikTok, Reels, or Shorts cut, ad captions for sound-off feeds, YouTube subtitles, an SRT sidecar, transcription of a clip's audio, captions translated into another language, karaoke or word-by-word styles, or restyling and correcting an existing transcript. Keywords: captions, subtitles, SRT, transcribe, karaoke, word-by-word, burn in, closed captions, translate video, caption style." license: MIT --- # Scenario Caption Studio ## Overview Caption Studio is one tool model, `model_scenario-caption-studio`: a video in, its speech transcribed (Whisper) or an existing SRT applied, styled captions out, burned into the picture or delivered as a soft track and an `.srt` sidecar. It translates into 18 languages and styles captions three ways. Running that one member is this skill's whole purpose, so the id is named rather than discovered and `model_schema_get` starts the flow directly; availability differs per team, so a member the team lacks is a gap to flag, not a cue to substitute. Connection and the core loop: see the `scenario` skill. Captioning is the last pass on a finished cut: assemble first (`scenario-video-assembly`), then caption the master once. Captions carry the transcript only; text that must appear letter-perfect without being spoken (CTAs, prices, legal supers) is `scenario-text-overlay` territory. If a sibling skill named here is missing from your available skills, ask the user to install it (`npx skills add scenario-labs/skills --skill `); unattended, proceed from tool schemas and flag the gap. ## Ask once, then caption The destination decides nearly every parameter, so collect one round of answers before touching the schema: where the video ships (a sound-off mobile feed, a paid placement, a seated long-form viewer), whether the spoken language stays or translates (`targetLanguage`, `auto` keeps it), brand colors if any, and which deliverable the platform wants. The deliverable is three switches: burned-in pixels are `outputSubtitles: "video_image"` (the default), the toggleable track is `"video_data"`, the sidecar file is `outputSrt: true`, and an SRT-only pass is that plus `outputVideo: false`, the first pass when the words must be letter-perfect: it priced the same as a burn-in at authoring time, so it buys certainty rather than savings, proving the words before any pixels are paid for. Then map the answers: | Destination | Style | Segmentation | Position | Output | | ---------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Social mobile short (9:16 Shorts, Reels) | `tiktok-bouncy` or `word-pop`; `karaoke-fill` when music drives | `maxSegmentWords` 3 to 5; 1 with a karaoke preset | `middle`: platform UI and native auto-captions own the bottom | Burn in | | Ad short, performance cut | `modern-chip` or `minimal-underline`, accents set to brand color | 3 to 7 words per cue | `bottom`, or `top` when an end card or overlay sits below | Burn in for sound-off feeds; add `outputSrt` for the platform's caption upload | | YouTube long-form, tutorial, interview | Default look or `cinematic-fade`; restraint reads as professionalism | `maxLines` 2, `maxSegmentChars` 84 (two 42-character lines, the broadcast convention) | `bottom` | `outputSrt` for the platform's closed captions; burn in only for re-embeds | | Cinematic piece, trailer, festival cut | `cinematic-fade` | Sentence-length cues, `maxSegmentDuration` about 6 | `bottom` | Burn in | Rows are authoring-time starting points to confirm with the user, not platform contracts; unattended, the task's own instructions answer the interview and the matching row's defaults fill what they leave unsaid. The per-placement safe zones behind the position column live in `scenario-formats`. `middle` renders at frame center, which on a centered talking head is the mouth: caption a selfie cut only once its face sits in the upper third (reframe in assembly), because the schema offers no lower-third position. An uploaded track beats burn-in for long-form because viewers toggle and restyle it, assistive tech reads it, and platforms index it for search; burn-in wins wherever the style is the point or a track cannot travel with the file. ## The style ladder Three tiers: `stylePreset` picks a ready-made look (7 presets, empty for the default); `stylePrompt` describes a look in plain words and builds a matching style (it carries `cost_impact`); `themeTsx` supplies a full custom theme that replaces the preset, with `stylePrompt` then refining that theme. There is no font parameter: type rides inside the tiers, and it is the strongest signal a style sends, so when the type itself must carry the mood or the brand, put the intent into `stylePrompt` in plain words (the weight, the letterform class, the feeling: "heavy condensed sans, high-energy", "light geometric sans, quiet and premium"); an exact brand face is `themeTsx` territory, and `scenario-text-overlay` chooses faces by meaning for the text cards around the captions. Presets also restyle the words themselves: an authoring-time run of `tiktok-bouncy` uppercased every caption, and the other presets are unverified for casing, so when exact casing matters (a product name, "LoRA") steer with `stylePrompt` or `themeTsx` and verify a frame before delivering. `fontColor` sets the body text (contrast beats aesthetics: white body text survives every backdrop the presets put behind it), and `accentColorStart`/`accentColorEnd` drive the highlight animation (karaoke fills, pops): spend the accent on one thing, usually the brand color, with equal values for a solid and different values for a gradient. Auto sizing (`fontSizePx` empty) rendered words about 30 pixels tall on a 1080x1920 frame at authoring time, unreadable on a phone feed: for vertical social set `fontSizePx` explicitly (60 to 90 on a 1920-tall frame is the authoring-time starting point) and judge a frame at phone scale. `outputTsx: true` returns the theme a run used, so a look that landed can be replayed exactly on the next video. ## Getting the words right - When narration was authored, retain that script as the wording reference. Compare the transcript against it for missing, repeated or altered words before burning; a spelling hint is not that comparison. Derive cue times from the actual recording, not word count or the planned shot duration. Correct the SRT through the supported input below; do not invent a script-alignment parameter. - `transcriptionPrompt` is a spelling hint, not a style field: list the names, brands, and jargon the audio contains. The hint raises the odds without guaranteeing them (an authoring-time run misspelled a hinted name twice), so check the transcript for every required name before trusting a burn-in, and on a miss retry with `large-v3` or a sharper hint. - `modelSize` trades accuracy for speed and cost (`cost_impact`): the `medium` default is fine for clean voiceover; step up to `large-v3` for noisy audio, accents, or dense terminology; `.en` variants are English-only. - The model transcribes whatever audio the master carries, so balance the music bed against dialogue before captioning (`scenario-video-assembly`), never after. - Corrections and restyles ride the `subtitles` input, whose contract is inline content, not a reference (authoring-time): pass the SRT text itself, base64-encoded, as the value. An `asset_...` id is not dereferenced there; the id string is base64-decoded as if it were content, and the run still reports success, bills, and renders zero captions (`segment_count: 0` in the job record is the tell). Reuse is therefore: `outputSrt: true` returns the transcript as an asset, `asset_download` it, correct spellings locally if needed, and feed the edited text back base64-encoded, which also covers `upload_asset` having no text kind (authoring-time fact). The SRT inherits the run's segmentation (a karaoke run returns word-per-cue), so re-chunk it locally before an ads upload or a calmer restyle. Never deliver a `subtitles` run on job status alone: sweep the output as the worked example reviews it, and when captions are missing, `asset_get` the subtitles asset the job consumed to see what it received. The schema does not say whether segmentation caps re-chunk a supplied SRT, so set segmentation when transcribing and omit the caps alongside `subtitles`. ## Worked example: a vertical social short, then a Spanish variant 1. `asset_get` the assembled master: confirm duration and that it is the finished cut, since the price tracks the footage (`video` carries `cost_impact`; trim first, `scenario-video-editing`). 2. `model_schema_get` on `model_scenario-caption-studio`. 3. Price it: `model_run` with `dry_run: true` and `parameters={"video": "", "stylePreset": "tiktok-bouncy", "maxSegmentWords": 4, "textPosition": "middle", "transcriptionPrompt": "Scenario, LoRA, Flux", "outputSrt": true}`. Re-estimate after changing `targetLanguage`, `modelSize`, `stylePrompt`, or `outputSubtitles`: all carry `cost_impact`. 4. Run it with `wait: false`, then `jobs_wait` with the `job_id`; on timeout re-call with the returned `pending_job_ids`, never `job_get` in a loop. 5. Review before deriving, since a successful job proves nothing about what rendered: download the SRT sidecar with `asset_download` (no `format`: it converts images only; a run that returns both video and SRT lists the two asset ids in no fixed order, and `asset_get` tells them apart by `mimeType`) and check its text against the authored script and required names; then download the video and sweep it into contact sheets (`ffmpeg -vf "fps=2"`), reading the burned captions for spelling, casing, and placement. Inspect at the intended display size, including backing panels: keep faces, hands, demonstrated actions and essential UI clear, and keep placement stable within a cue. Listen against cue starts and ends; a correct transcript does not prove synchronization. Sample frames immediately before and after cue boundaries as well as within them: reveals and fades can exceed supplied SRT times, and a flash under 100 ms survives an `fps=2` sweep. If strict boundaries are required, verify the actual theme or report the limitation; a correct sidecar alone is not a pass. Check the final spoken word survives, comparing audio and video streams separately; a shorter audio stream containing the complete narration may simply omit trailing silence. 6. Spanish variant: add `targetLanguage: "es"` to the same parameters, `transcriptionPrompt` included, and `dry_run` again (it moves the price) before running. Translation happens inside the run, so one master yields a variant per market. Latin-script segmentation caps do not transfer to Chinese, Japanese, or Korean (streaming style guides run them at a third of the characters per line), so revisit `maxSegmentChars` per target language. 7. File the master, variants, and SRT assets in a collection (`scenario` skill) so the delivery set stays findable. ## Common mistakes - Captioning each clip before assembly: caption the finished master once, or cues drift across cuts and every edit orphans its captions. - Expecting the preset look on the soft track: `video_data` renders as plain text the viewer toggles; styling survives only when burned in. - Styling legal lines or CTAs as captions: disclosures carry locked wording, size, and dwell time that caption logic would re-chunk and retime, and a toggleable track fails "visible without viewer action" rules outright; exact unspoken text is a `scenario-text-overlay` card composited in assembly. - Setting `maxSegmentWords: 1` without a karaoke or pop preset: one-word cues flash as a slideshow unless the style animates them. With a pop preset (the ones that reveal words inside a cue: `tiktok-bouncy`, `word-pop`, and the karaoke pair at authoring time), never end a cue on a one-letter word: pop-in timing follows character count, so a trailing "I" or "a" showed for about 70 ms at authoring time. Re-chunking a supplied SRT means owning its timings too: a supplied SRT carries cue times only, so a pop preset spreads its words evenly across each cue and the highlight drifts from the voice wherever a cue outlasts the speech; keep each cue's end on the spoken span, and extend only the last cue to the clip's end. - Treating a `jobs_wait` timeout as failure: re-call with `pending_job_ids`; video tool jobs outlast the wait window routinely.