Timestamped overlays die when you recut the clock
add_timestamped_captions burns lines you wrote at start_sec and end_sec you set. Recut the video and every timestamp is a lie.
Timed overlays are a clock you author. You write each line. You set start_sec and end_sec. add_timestamped_captions burns the sequence onto the file. The tool does not detect beats. It does not transcribe. If you recut the picture, every number you typed is now attached to the wrong frame.
Add timed text overlays is the job. list_caption_fonts supplies a real font. Font, size, color, and position apply once to the whole set — not per line. That is a finishing constraint, not a reason to iterate the clock on a miss.
You are typesetting a timeline that must not move
A question at 0–2s, a stat at 2–4s, a punchline at 4–7s only works if those seconds still exist. Trim the head by a second and the punchline lands on the setup. Extend the clip and the last card sits in dead air, or vanishes. Punch a section out of the middle and every later cue is early.
That is why this is a later step. Picture lock is the moment the clock stops being a mood. Until then, put the copy in a doc. The composite is how you print a signed beat sheet onto a signed cut.
People reach for timed type because kinetic text looks like an edit. It is not an edit. It is labels on an edit. Story to video can still be in flux while you are "trying the cards." Those cards will not survive the next sample.
Authored copy, not speech
If the words are what someone said, you wanted auto captions. If there is one persistent badge, you wanted a fixed overlay. Timed overlays exist for a sequence you wrote: listicles, claim cards, a text-thread beat, a countdown. Legal and price lines belong here because a model must not render the digits.
Do not author those lines against a take you dislike. You will rewrite the copy when the new take has different pacing, and you will have paid for a render whose only job was to show you the type worked — which a still of the first frame could have shown.
estimate_cost on the actual file. Same billing family as add_video_captions. Cheap compared with a generate. Twice is still twice.
Order of operations
- Lock the cut. Duration, trims, and speed ramps are done.
- Script the beats against this clock, not against a storyboard duration.
- Burn the set once. If a line is wrong, fix the copy and burn again on the same keeper — not on a new generate.
If you are still choosing between two takes, neither of them gets the cards.
FAQ
Will the tool snap cues to cuts for me?
No. You supply the timestamps. Shot-change timing is a human pass on a locked cut.
Can each line have its own color?
Not in one render. Size, color, position, and font are set for the whole overlay set. If you need a different look per card, you are in a different workflow.
Why not time overlays on a 480p preview while I taste takes?
Because the preview's duration is not a contract. A later export with a different in-point invalidates every start_sec. Time against the file you will ship.
Is this how I caption a talking head?
Only if you are ignoring the audio on purpose. Speech-to-type is VEED. This tool is for lines nobody said, at times you choose.