Command · Caption Style
captions.setStyle
Changes how a caption track looks: font, size (fraction of the frame height), fill, outline, shadow, background box, placement (bottom, top or a custom position), alignment, width, karaoke highlight, speaker names.
- v1
- Capability EditSequence
- Tool
captions_setStyle
Request
{
"command": "captions.setStyle",
"params": {
"style": {
"box": false,
"fontSize": 0.05,
"outlineWidth": 0.08
}
}
}Parameters
captionTrackinteger (1..)- Caption track id (sequence.summary lists them). Default: the sequence's first.
sequenceinteger (1..)- Sequence id; only needed when the project has several.
styleobjectRequired- Style fields to change; the others keep their values.
style.alignment`left` | `center` | `right`- Line alignment.
style.allowOverlapboolean- Cues of the track may overlap (stacked).
style.animation`none` | `pop` | `fade` | `wordByWord`- Kinetic captions (reserved: drawn as none today).
style.boxboolean- A background box behind the text.
style.boxColorstring | array, min 3- Box colour. "#RRGGBB", or [red, green, blue] from 0 to 1.
style.boxOpacitynumber (0.0..1.0)- Box opacity.
style.boxPaddingnumber (0.0..2.0)- Box padding, fraction of the font size.
style.boxRadiusnumber (0.0..2.0)- Box corner radius, fraction of the font size.
style.brandobject- C.13: brand kit colours and font role that override the colours and font above while the project's kit has them (brand.set re-themes the captions); fields not given keep their values.
style.brand.boxstring- A brand kit colour for the box.
style.brand.fillstring- A brand kit colour for the text ("" = none).
style.brand.fontstring- A brand kit font role ("body") for the family and weight.
style.brand.highlightstring- A brand kit colour for the karaoke highlight.
style.brand.outlinestring- A brand kit colour for the outline.
style.brand.shadowstring- A brand kit colour for the shadow.
style.fillstring | array, min 3- Text colour. "#RRGGBB", or [red, green, blue] from 0 to 1.
style.fontFamilystring- Font family; empty: the platform's sans-serif.
style.fontSizenumber (0.005..0.5)- Font size as a fraction of the frame height (0.0444 = 48 px on 1080p).
style.fontWeightinteger (100..900)- 100..900 (400 regular, 700 bold).
style.highlightstring | array, min 3- Karaoke: colour of the words already spoken. "#RRGGBB", or [red, green, blue] from 0 to 1.
style.lineSpacingnumber (0.5..3.0)- Line spacing (1 = the font's).
style.maxWidthnumber (0.1..1.0)- Widest text block, fraction of the frame width.
style.outlinestring | array, min 3- Outline colour. "#RRGGBB", or [red, green, blue] from 0 to 1.
style.outlineWidthnumber (0.0..0.5)- Outline width, fraction of the font size (0 = none).
style.placement`bottom` | `top` | `custom`- Bottom or top of the safe area, or at positionX/positionY.
style.positionXnumber (0.0..1.0)- Custom placement: centre of the text, fraction of the frame width.
style.positionYnumber (0.0..1.0)- Custom placement: centre of the text, fraction of the frame height.
style.safeAreanumber (0.0..0.4)- Safe-area inset from each frame edge, fraction of the frame.
style.shadowAnglenumber (-360.0..360.0)- Shadow direction in degrees, clockwise from the x axis.
style.shadowColorstring | array, min 3- Shadow colour. "#RRGGBB", or [red, green, blue] from 0 to 1.
style.shadowDistancenumber (0.0..2.0)- Shadow distance, fraction of the font size.
style.shadowOpacitynumber (0.0..1.0)- Shadow opacity (0 = none).
style.shadowSoftnessnumber (0.0..2.0)- Shadow blur, fraction of the font size.
style.showSpeakersboolean- Start each cue with its speaker's name in the speaker's colour.
Discussion
Changes how a caption track looks: font, size (fraction of the frame height), fill, outline, shadow, background box, placement (bottom, top or a custom position), alignment, width, karaoke highlight, speaker names. Fields not given keep their values. Preview and burn-in export both use it.
Run it with wabcut-cli cmd <project> --json, from an MCP client as captions_setStyle, or from an extension. See Edit commands for requests, references and results.
See also
captions.*
- captions.addCue
Add Caption. Adds a cue from "start" to "end" (or for "duration").
- captions.addTrack
New Caption Track. Adds an empty caption track, styled by a preset (built in: Clean, Bold Box, Podcast, Shorts, Thai-friendly; or one of the project's) and/or style fields.
- captions.applyPreset
Apply Caption Preset. Gives a caption track the style of a preset: built in (Clean, Bold Box, Podcast, Shorts, Thai-friendly) or one of the project's.
- captions.generate
Generate Captions. Makes a caption track from the transcript: cues of at most maxLines lines of maxCharsPerLine characters and maxDuration seconds, broken at pauses, speaker changes and sentence ends; Thai lines break between words, never at spaces that are not there.
- captions.generateFromTranscript
Captions from Transcript. Makes a caption track from the sequence's transcript (with the project's corrections and speakers): cues of at most maxLines lines of maxCharsPerLine characters and maxDuration, broken at pauses, speaker changes and (optionally) sentence ends, at least "gap" apart.
- captions.get
Caption Cues. The cues of a caption track (default: the sequence's first) as arrays in cueFields order: start, end, text (its lines joined by newlines).
- captions.mergeCues
Merge Captions. Joins "count" consecutive cues (default 2) into one, its text re-wrapped to maxLines lines of maxCharsPerLine characters.
- captions.presets
Caption Presets. The caption presets: built in, then the project's, each with its style.
- captions.remove
Delete Caption Track. Deletes a caption track of the sequence.
- captions.removeCue
Delete Caption. Deletes a cue of a caption track.
- captions.removePreset
Delete Caption Preset. Deletes one of the project's caption presets.
- captions.savePreset
Save Caption Preset. Saves a named caption style in the project: a caption track's style, with "style" fields applied on top (or the default look).
- captions.setTrack
Caption Track Settings. Renames a caption track, sets its language or shows/hides it.
- captions.shiftCues
Shift Captions. Moves the cues that start in [from, to) (default: all of them) by a signed delta, e.g. to resync captions.
- captions.splitCue
Split Caption. Cuts a cue in two at a time inside it.
- captions.translate
Translate Captions. Translates a caption track into new caption tracks, one per language, keeping the cue timing: cues that would read too fast in the target language borrow time from the gaps, merge with a neighbour or move words across, and text that does not fit two lines is split into more cues (Thai broken between words).
- captions.updateCue
Edit Caption. Changes a cue's text, start, end or speaker (null clears the speaker).
- captions.updateFromTranscript
Update Captions from Transcript. Rewrites the text of a caption track's cues from the transcript words under them (after transcript corrections), keeping their timing and style; cues with no words under them stay as they are.