caption-this

I'd like you to add a skill to Wideframe called "caption-this".

Save the SKILL.md below exactly as written, then confirm I can run it by saying /caption-this.

---
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 `<name>_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 `<name>.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 `<name>_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.