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 <name>); 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": "<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.
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.