--- name: caption-this description: Add captions to a clip or a sequence, timed to speech and formatted to a readable standard, as a Premiere captions track, a sidecar SRT, or burned in. Use when someone says "captions", "subtitles", "add text of what they're saying", "SRT", or asks for a social clip people can watch on mute. Works on raw clips, an existing Premiere sequence, or a sequence Wideframe just built. argument-hint: "[path-to-clip, sequence, or prproj]" --- # Caption This Caption readability depends on line length, timing, and delivery format. This skill uses a readable standard by default, asks one question about delivery format, and checks cues before handing over. ## Scope Dialogue captions timed to speech. Not lower thirds, not titles. Translation only if the user asks for a language other than the spoken one. ## Step 0: Resolve the input and ask the one question Accept a clip, a folder, a Wideframe sequence, or a `.prproj` plus a sequence name. If a `.prproj` was given with no sequence named, inspect it and pick the most recently modified sequence, stating the choice. Ask one question, with the default first: "Captions as a Premiere captions track (default), a separate SRT file, or burned into the video?" If the user already said which, skip the question. Everything else uses these defaults and is stated in the report, not asked: - 2 lines maximum, 32 characters per line for vertical video, 42 for horizontal. - Reading speed at or under 17 characters per second; cues that exceed it are split. - Minimum cue duration 1 second, gap between cues at least 2 frames. - No speaker labels unless more than one speaker is present, then `NAME:` prefixes. - Sentence case, standard punctuation, numerals for numbers over ten. - Profanity kept as spoken. ## Step 1: Transcribe 1. `caltools media-info-batch` to get fps, resolution and orientation (which picks the line length). 2. `caltools media-transcript-get-batch` with word-level timestamps on the clip, or on every clip in the sequence in timeline order. 3. `caltools job-poll` until done. Evaluation: a word list with start and end times covers the full duration; gaps longer than 5 seconds with audio present are flagged as possible transcription misses. ## Step 2: Build the cues Group words into cues that honor the line length, line count, reading speed and minimum duration. Break at clause boundaries before commas and conjunctions; never split a name or a number across lines. Snap cue starts to the first word and cue ends to the last word, then extend short cues to the minimum duration if the gap allows. Spot-check ten cues against the audio at random. If more than one is mistimed by over 200 ms, re-run transcription on that range. Evaluation: zero cues exceed the limits; a list of any the source forced (a single very long word, back-to-back rapid speech) is kept for the report. ## Step 3: Deliver in the chosen format Premiere captions track (default): 1. `caltools prproj edit add_caption` for every cue on a new captions track in the target sequence, working on a copy `_captions.prproj`. 2. `caltools prproj validate`; fix and re-run on any error. 3. `caltools prproj inspect`: caption count equals cue count. Sidecar SRT: 1. Write `.srt` next to the media with sequential numbering and `HH:MM:SS,mmm` timing. 2. Validate: cues in order, no overlaps, no empty cues, file parses. Burned in: 1. `caltools sequence-text-overlay-add` per cue with a safe-area position (bottom, above the platform UI zone for vertical), white text with a dark stroke, a font size that reads at phone scale. 2. `caltools sequence-render-final` to `_captioned.mp4` at the source resolution and frame rate. 3. `sequence-render-frames` at three cue midpoints to confirm text is inside the frame and legible. In all three cases, also render a short review MP4 of the captioned result (`sequence-render-final`) so the user can watch it on mute before opening Premiere. Evaluation: the count of delivered captions equals the cue count from Step 2, and the review render plays. ## Step 4: Report Give the file paths, the cue count, the standard used (lines, characters, reading speed), the number of cues the source forced past a limit, and the ten-cue spot-check result. Then name the next steps: `social-clips` if this was a horizontal piece, or a style pass (font, color, position) if they want the burn-in to match a brand. ## Done when - Every cue is timed to the speech, non-overlapping, and within the readability limits (exceptions listed). - The chosen format was delivered and validated: captions track passes `prproj validate` with counts reconciled, SRT parses, or burned-in frames are legible. - A review MP4 exists. - The user answered one question (format) and nothing else was asked.