Captions for an AI Producer project

Captions are moments you write, the same way as any other motion graphic: one visual moment per stretch of speech, each a composition under the composition contract whose cues are static text elements shown and hidden on the moment's own paused timeline. Static text in a moment is what the editor lets the user select, retype, recolor and change the font of, so every word a caption shows is written in the composition's HTML, never generated by its script. Never call build_captions, never use the narrator-captions id, and never write compositions/narrator_captions.html or compositions/transcript-src.json: those are the service's own caption layer, which this skill does not use.

Timing

Write the captions once the speaker cut is final. Run caption_cues.py on the render-engine directory:

python3 <loaded-aip-skill>/scripts/caption_cues.py <render-engine-root> --max-words 4

It synchronizes compositions/editing-script.json with the cut in index.html, as preflight's --sync-editing-script does, so that document goes in the same upload, and prints one row per caption moment: id, src, start on the cut, duration, src_anchor (the source second at start), and cues, each with in, out and its words as [text, in, out], in seconds from the moment's start. Take every time from it, never from arithmetic of your own on get_transcript. A moment never spans a speaker cut, a sentence end or a long pause, so when the user later cuts between two moments in the editor, each moves whole with its source anchor. A cut inside a moment leaves its later words early, and one that removes its first word hides the whole moment, because the editor hides a moment whose anchor is cut away; either way the moment is right again once you write it afresh for the new cut. --max-words is how many words a cue shows at once: 4 by default, 1 for a look that shows one word at a time, and 8 to 12 for speech whose transcript words are a character or two each, such as Chinese or Japanese. You may merge two cues or split one at a word boundary, using the words' own times, and correct a word's spelling, casing or punctuation; never change what was said.

Mount each row as a moment host, after every other moment inside the root and all on one track no other moment uses, so the captions draw above every moment: