spoken-captions

Captions

Every word on screen comes from a transcript, with its times as the transcript gives them. Never rewrite the word times.

The transcript

1. Probe before you transcribe. Check hasAudio from picsart_media_probe first, and skip only when it reports hasAudio: false, as the footage-analysis skill says.
2. Transcribe with picsart_media_transcribe:
   • a voice-over you generated: each generated voice line. It is our own clean audio, so the word edges are exact.
   • the user's own footage: each source once, as the footage-analysis skill says. Reuse that transcript; never transcribe a cut.

The tool's notes name any segment it returned without word times. Caption that segment as one block over its own start and end; it cannot carry a highlight.

Captions on a voice-over

Place each line as a captions layer through picsart_scene_patch: content: { kind: "captions", transcript, timeOffset }, where transcript is the tool's transcript as returned (it is already shaped for a captions layer) and timeOffset is the line's start in the video.

2–4 words per caption. The caption style's offset is measured from the frame center ([0, -670] puts it at y ≈ 290 in a 1080×1920 frame, below the top 250 px the platforms cover); keep captions in a dark band of the layout, never over a panel or the focus point.

Readable over any picture, and the spoken word lit. A caption crosses moving footage, so give its style an outline and light the word being spoken:

"style": {
  "effects": [{"id": "stroke", "params": {"width": "<px>", "color": "<outline colour>"}}],
  "decorations": [{"target": "highlighted", "place": "text", "color": "<highlight colour>"}]
}

Read the effect's id and params from picsart_scene_capabilities (effects) rather than from here; this shape passed picsart_scene_validate on 2026-10-05. One highlight colour for the whole video, the brand's when it has one.

Words on a cut reel

A reel cut from the user's footage plays each source in pieces, so its words are placed from the scene the user approved, with python3 scripts/reel_text.py words.json:

{
  "scene": "scene.json",
  "transcripts": {"talk": "transcript-talk.json"},
  "captions": {"style": {"font": {"size": 64}, "offset": [0, 440]}},
  "highlights": [
    {"clip": 0, "say": "revenue tripled", "text": "Revenue tripled"},
    {"clip": 4, "say": "nobody tells you this"}
  ]
}

transcripts maps each spoken source's asset id to its saved transcript. Ask for captions, highlights or both. The script reads each clip's place on the reel and its trim from the scene, so a clip the user retrimmed in the editor is read as they left it, and it prints the scene with the new layers on top. A phrase it had to cut short comes back in notes.

• Captions become one captions layer per spoken clip, open while that clip plays its source, with the source's transcript as returned. A clip held past its trim.out freezes on its last frame, so its captions close where the trim ends. The reel ends at the composition's duration, or with none at the track layer's: captions stop there. A photo, a muted clip, a shot without a transcript or a clip past the reel's end gets none, and a highlight on a muted clip or one past the end is refused.
• Highlights all go on one captions layer, one segment per phrase, each on a pill the renderer fits to the measured words. Pass highlightStyle to change the look; the font follows the scene-building-basics skill.

Choosing highlights

Highlights are a few lines worth reading, not subtitles.

• 2–4 per reel, 2–6 words each, verbatim from the transcript. say is what was said; text may drop a filler word or fix its case, never change what it says.
• Pick the hook, the number, the rehook (the turn near the middle, as the retention-hooks skill names it) and the payoff: the words a viewer should remember. Skip greetings, filler and anything already said on screen.
• Draft them before you place them: each phrase with its clip, so the use case can offer them. The reel is complete without them.
• One at a time. The script holds each from its first word to half a second past its last, 1.5–3 s, and never past its clip or into the next phrase.
• Big, high-contrast, inside the platform's safe band and off the face. The use case names the band. With captions on too, keep the two in different bands.

Check the result as the quality-review skill says, with a frame at each phrase's start.