Captions in Pireel Studio are a global preset layer laid from the spoken transcript: ONE setting styles the WHOLE video. They are not per-block edits — a single set_captions call turns them on, restyles them, or repositions them everywhere at once, and cutting the video re-lays them automatically (never hand-fix captions after a cut).
The keyword-slam "花字" effect is a different thing: that is an overlay block (BYO flow via compose_block_brief → apply_block), not the caption layer.
Tools
set_captions {preset?, yPct?, scale?}— turn captions on and/or restyle:preset— a style id from the catalog below. Passing it (re)builds the layer from the transcript, enabling captions if off; ASR runs first automatically if there is no transcript yet. Never invent an id.yPct— the caption baseline's distance from the TOP as a percentage. Smaller = higher on screen. Omit to keep current.scale— size multiplier;1= the preset's default. Omit to keep current.- Omit
presetto only reposition/resize the current captions (e.g. "move the subtitles up a bit" →set_captions {yPct: <smaller>}; "make them bigger" →set_captions {scale: 1.2}).
remove_captions— turn the whole layer off. It does not touch keyword blocks (delete those withdelete_block).set_caption_translations {items?, shotId?, clear?}— bilingual subtitles (see below).
get_state reports the current caption status (Captions: ON — preset …, baseline …% from top or off).
Bilingual subtitles (translation line)
A second, smaller line under each caption showing YOUR translation of that sentence — you translate, the tool only stores. This costs no Pireel credits.
read_script— the transcript comes back as numbered rows (0. [x–y s] text).- Translate every row yourself into the target language (keep each translation one sentence, no timestamps).
set_caption_translations {items: [{index: 0, text: "…"}, …]}—indexis the row number from step 1. Batch all rows in ONE call.- If captions are off, the tool says so — follow with
set_captions {preset}to show them.
Notes:
- Translations attach to the transcript, so cuts/restyles/re-lays keep them; re-transcribing a new file drops them.
- Inserted clips have their own transcript — translate those with a second call passing
shotId(the inserted-clip shot id fromread_script). - Fix one line: resend just that
{index, text}. Remove one:text: "". Remove all:{clear: true}. - The translation line inherits the caption preset's look (smaller, no per-word animation) — there is no separate style knob for it.
The 18 presets — two modes
emphasis (word-by-word emphasis) — the whole line stays on screen; the word currently being spoken is highlighted (color change, underline slide, or box pop). Energetic, spoken-word feel.
| id | look |
|---|---|
em-yellow |
white text, yellow current word, drop shadow (the classic default) |
em-green |
white text, neon-green current word, drop shadow |
em-purple-black |
black bar, white text, purple current word |
em-serif-black |
black bar, serif, teal current word |
em-underline |
black bar, white underline slides under the current word |
em-blue-line |
light bar, dark text, blue underline on the current word |
em-box-purple |
purple bar, dark box pops behind the current word |
em-box-blue |
blue bar, black box pops behind the current word |
em-pink |
pink bar, soft-pink text, current word flips to white |
em-gold-serif |
cream bar, gold serif text, darker-gold current word |
line (full-sentence subtitle) — clean line-by-line fade-in, no per-word animation. Calm, documentary/informational feel.
| id | look |
|---|---|
ln-clean |
bare white text with shadow, no bar |
ln-black |
black bar, white text |
ln-navy |
navy-gray bar, white serif |
ln-white |
white bar, blue italic text |
ln-orange |
orange bar, bold white text |
ln-yellow |
yellow bar, black text |
ln-red |
red bar, white monospace |
ln-mint |
mint text with shadow, no bar |
Choosing
- Bare "add subtitles" with no style preference → default to a clean line preset (
ln-cleanis the safe pick). - High-energy talking-head / hook-driven content, or the user says "highlight the words as I speak" → an emphasis preset (
em-yellowif no color preference). - Match the attached frame/theme palette when one exists (e.g. a dark editorial theme pairs with
em-serif-blackorln-navy; a loud commerce theme withem-box-blueorln-yellow). Content fit beats variety. - User names a color/mood ("yellow captions", "something serif") → pick the preset whose look matches; do not try to restyle beyond the catalog.
Position and size
- Default placement is fine for most videos; adjust when captions collide with graphics or the speaker's face (check shot treatments —
split-l/rand corner framings change where free space is). - "Higher/lower" → nudge
yPct(smaller = higher). "Bigger/smaller" →scalearound 1 (e.g. 1.15 / 0.85). These are independent of the preset and of each other.
Recovery
- If the user dislikes the result: another
set_captionswith a different preset is cheaper thanundoand keeps position tweaks explicit. - "No captions" / "turn them off" →
remove_captions, notdelete_blocks.