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, load it with skill_get (Scenario MCP) or
ask the user to install it (https://github.com/scenario-labs/skills#install); 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
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).
model_schema_get on model_scenario-caption-studio.
- Price it:
model_run with dry_run: true and
parameters={"video": "<asset_id>", "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.
- 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.
- 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.
- 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.
- 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.
1---2name: scenario-caption-studio3description: "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."4license: MIT5metadata:6 source: https://skillmd.com/skills/scenario-labs/scenario-caption-studio7---89# Scenario Caption Studio1011## Overview1213Caption Studio is one tool model, `model_scenario-caption-studio`: a video in, its speech14transcribed (Whisper) or an existing SRT applied, styled captions out, burned into the picture or15delivered as a soft track and an `.srt` sidecar. It translates into 18 languages and styles captions16three ways. Running that one member is this skill's whole purpose, so the id is named rather than17discovered and `model_schema_get` starts the flow directly; availability differs per team, so a18member the team lacks is a gap to flag, not a cue to substitute. Connection and the core loop: see19the `scenario` skill.2021Captioning is the last pass on a finished cut: assemble first (`scenario-video-assembly`), then22caption the master once. Captions carry the transcript only; text that must appear letter-perfect23without being spoken (CTAs, prices, legal supers) is `scenario-text-overlay` territory. If a sibling24skill named here is missing from your available skills, load it with `skill_get` (Scenario MCP) or25ask the user to install it (https://github.com/scenario-labs/skills#install); unattended, proceed26from tool schemas and flag the gap.2728## Ask once, then caption2930The destination decides nearly every parameter, so collect one round of answers before touching the31schema: where the video ships (a sound-off mobile feed, a paid placement, a seated long-form32viewer), whether the spoken language stays or translates (`targetLanguage`, `auto` keeps it), brand33colors if any, and which deliverable the platform wants. The deliverable is three switches:34burned-in pixels are `outputSubtitles: "video_image"` (the default), the toggleable track is35`"video_data"`, the sidecar file is `outputSrt: true`, and an SRT-only pass is that plus36`outputVideo: false`, the first pass when the words must be letter-perfect: it priced the same as a37burn-in at authoring time, so it buys certainty rather than savings, proving the words before any38pixels are paid for. Then map the answers:3940| Destination | Style | Segmentation | Position | Output |41| ---------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |42| 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 |43| 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 |44| 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 |45| Cinematic piece, trailer, festival cut | `cinematic-fade` | Sentence-length cues, `maxSegmentDuration` about 6 | `bottom` | Burn in |4647Rows are authoring-time starting points to confirm with the user, not platform contracts;48unattended, the task's own instructions answer the interview and the matching row's defaults fill49what they leave unsaid. The per-placement safe zones behind the position column live in50`scenario-formats`. `middle` renders at frame center, which on a centered talking head is the mouth:51caption a selfie cut only once its face sits in the upper third (reframe in assembly), because the52schema offers no lower-third position. An uploaded track beats burn-in for long-form because viewers53toggle and restyle it, assistive tech reads it, and platforms index it for search; burn-in wins54wherever the style is the point or a track cannot travel with the file.5556## The style ladder5758Three tiers: `stylePreset` picks a ready-made look (7 presets, empty for the default); `stylePrompt`59describes a look in plain words and builds a matching style (it carries `cost_impact`); `themeTsx`60supplies a full custom theme that replaces the preset, with `stylePrompt` then refining that theme.61There is no font parameter: type rides inside the tiers, and it is the strongest signal a style62sends, so when the type itself must carry the mood or the brand, put the intent into `stylePrompt`63in plain words (the weight, the letterform class, the feeling: "heavy condensed sans, high-energy",64"light geometric sans, quiet and premium"); an exact brand face is `themeTsx` territory, and65`scenario-text-overlay` chooses faces by meaning for the text cards around the captions. Presets66also restyle the words themselves: an authoring-time run of `tiktok-bouncy` uppercased every67caption, and the other presets are unverified for casing, so when exact casing matters (a product68name, "LoRA") steer with `stylePrompt` or `themeTsx` and verify a frame before delivering.69`fontColor` sets the body text (contrast beats aesthetics: white body text survives every backdrop70the presets put behind it), and `accentColorStart`/`accentColorEnd` drive the highlight animation71(karaoke fills, pops): spend the accent on one thing, usually the brand color, with equal values for72a solid and different values for a gradient. Auto sizing (`fontSizePx` empty) rendered words about7330 pixels tall on a 1080x1920 frame at authoring time, unreadable on a phone feed: for vertical74social set `fontSizePx` explicitly (60 to 90 on a 1920-tall frame is the authoring-time starting75point) and judge a frame at phone scale. `outputTsx: true` returns the theme a run used, so a look76that landed can be replayed exactly on the next video.7778## Getting the words right7980- When narration was authored, retain that script as the wording reference. Compare the transcript81 against it for missing, repeated or altered words before burning; a spelling hint is not that82 comparison. Derive cue times from the actual recording, not word count or the planned shot83 duration. Correct the SRT through the supported input below; do not invent a script-alignment84 parameter.85- `transcriptionPrompt` is a spelling hint, not a style field: list the names, brands, and jargon86 the audio contains. The hint raises the odds without guaranteeing them (an authoring-time run87 misspelled a hinted name twice), so check the transcript for every required name before trusting a88 burn-in, and on a miss retry with `large-v3` or a sharper hint.89- `modelSize` trades accuracy for speed and cost (`cost_impact`): the `medium` default is fine for90 clean voiceover; step up to `large-v3` for noisy audio, accents, or dense terminology; `.en`91 variants are English-only.92- The model transcribes whatever audio the master carries, so balance the music bed against dialogue93 before captioning (`scenario-video-assembly`), never after.94- Corrections and restyles ride the `subtitles` input, whose contract is inline content, not a95 reference (authoring-time): pass the SRT text itself, base64-encoded, as the value. An `asset_...`96 id is not dereferenced there; the id string is base64-decoded as if it were content, and the run97 still reports success, bills, and renders zero captions (`segment_count: 0` in the job record is98 the tell). Reuse is therefore: `outputSrt: true` returns the transcript as an asset,99 `asset_download` it, correct spellings locally if needed, and feed the edited text back100 base64-encoded, which also covers `upload_asset` having no text kind (authoring-time fact). The101 SRT inherits the run's segmentation (a karaoke run returns word-per-cue), so re-chunk it locally102 before an ads upload or a calmer restyle. Never deliver a `subtitles` run on job status alone:103 sweep the output as the worked example reviews it, and when captions are missing, `asset_get` the104 subtitles asset the job consumed to see what it received. The schema does not say whether105 segmentation caps re-chunk a supplied SRT, so set segmentation when transcribing and omit the caps106 alongside `subtitles`.107108## Worked example: a vertical social short, then a Spanish variant1091101. `asset_get` the assembled master: confirm duration and that it is the finished cut, since the111 price tracks the footage (`video` carries `cost_impact`; trim first, `scenario-video-editing`).1122. `model_schema_get` on `model_scenario-caption-studio`.1133. Price it: `model_run` with `dry_run: true` and114 `parameters={"video": "<asset_id>", "stylePreset": "tiktok-bouncy", "maxSegmentWords": 4, "textPosition": "middle", "transcriptionPrompt": "Scenario, LoRA, Flux", "outputSrt": true}`.115 Re-estimate after changing `targetLanguage`, `modelSize`, `stylePrompt`, or `outputSubtitles`:116 all carry `cost_impact`.1174. Run it with `wait: false`, then `jobs_wait` with the `job_id`; on timeout re-call with the118 returned `pending_job_ids`, never `job_get` in a loop.1195. Review before deriving, since a successful job proves nothing about what rendered: download the120 SRT sidecar with `asset_download` (no `format`: it converts images only; a run that returns both121 video and SRT lists the two asset ids in no fixed order, and `asset_get` tells them apart by122 `mimeType`) and check its text against the authored script and required names; then download the123 video and sweep it into contact sheets (`ffmpeg -vf "fps=2"`), reading the burned captions for124 spelling, casing, and placement. Inspect at the intended display size, including backing panels:125 keep faces, hands, demonstrated actions and essential UI clear, and keep placement stable within126 a cue. Listen against cue starts and ends; a correct transcript does not prove synchronization.127 Sample frames immediately before and after cue boundaries as well as within them: reveals and128 fades can exceed supplied SRT times, and a flash under 100 ms survives an `fps=2` sweep. If129 strict boundaries are required, verify the actual theme or report the limitation; a correct130 sidecar alone is not a pass. Check the final spoken word survives, comparing audio and video131 streams separately; a shorter audio stream containing the complete narration may simply omit132 trailing silence.1336. Spanish variant: add `targetLanguage: "es"` to the same parameters, `transcriptionPrompt`134 included, and `dry_run` again (it moves the price) before running. Translation happens inside the135 run, so one master yields a variant per market. Latin-script segmentation caps do not transfer to136 Chinese, Japanese, or Korean (streaming style guides run them at a third of the characters per137 line), so revisit `maxSegmentChars` per target language.1387. File the master, variants, and SRT assets in a collection (`scenario` skill) so the delivery set139 stays findable.140141## Common mistakes142143- Captioning each clip before assembly: caption the finished master once, or cues drift across cuts144 and every edit orphans its captions.145- Expecting the preset look on the soft track: `video_data` renders as plain text the viewer146 toggles; styling survives only when burned in.147- Styling legal lines or CTAs as captions: disclosures carry locked wording, size, and dwell time148 that caption logic would re-chunk and retime, and a toggleable track fails "visible without viewer149 action" rules outright; exact unspoken text is a `scenario-text-overlay` card composited in150 assembly.151- Setting `maxSegmentWords: 1` without a karaoke or pop preset: one-word cues flash as a slideshow152 unless the style animates them. With a pop preset (the ones that reveal words inside a cue:153 `tiktok-bouncy`, `word-pop`, and the karaoke pair at authoring time), never end a cue on a154 one-letter word: pop-in timing follows character count, so a trailing "I" or "a" showed for about155 70 ms at authoring time. Re-chunking a supplied SRT means owning its timings too: a supplied SRT156 carries cue times only, so a pop preset spreads its words evenly across each cue and the highlight157 drifts from the voice wherever a cue outlasts the speech; keep each cue's end on the spoken span,158 and extend only the last cue to the clip's end.159- Treating a `jobs_wait` timeout as failure: re-call with `pending_job_ids`; video tool jobs outlast160 the wait window routinely.