reconcile-timeline
Re-anchor a long-form job's timeline segments to the measured voiceover, and fix audio_duration. Long-form only. Shorts do not need this (their drift is sub-second).
Why this skill exists
The brief's timeline segment times are PREDICTED from a 155 wpm assumption when the brief was written. A TTS engine rarely speaks at exactly that pace. The elevenlabs-tts skill measures the real per-word timings (from the TTS engine's character alignment) and writes them into subtitles[], but it does NOT update the timeline segments and does NOT update audio_duration.
For a 30-second Short, predicted vs measured differ by a fraction of a second, so a Shorts pipeline can ignore it. For a multi-minute long-form video the gap grows across the runtime and the images visibly fall out of sync with the voiceover by the end. This skill closes that gap by re-anchoring every segment to the words it actually covers.
Usage
Run the script directly:
bash skills/reconcile-timeline/scripts/reconcile.sh <job-folder>
Example (the bundled demo job):
bash skills/reconcile-timeline/scripts/reconcile.sh examples/demo-job
What the script does
- Validates input.json exists and is valid JSON
- Guards against Shorts briefs (schema_version must be "3.0-long")
- Verifies measured word timings exist in subtitles[]
- Verifies every timeline segment has a non-empty vo_line
- Positionally matches each segment's vo_line against the measured word stream and rewrites start_time/end_time to real audio boundaries
- Safety-checks that total vo_line word count matches measured word count (within 5% tolerance)
- Merges reconciled timeline back into input.json and verifies monotonicity
Output
On success:
OK reconciled <N> segments to measured audio
audio_duration set to <S>s
On failure:
FAILED: <reason>
(with details to stderr, exit non-zero)
Notes
- The script is self-contained and does NOT require creating any temp files in the job folder beyond a transient jq script (reconcile.jq) and a temp merge file, both cleaned up on success.
- If step 6 fails (word count mismatch), the fix is upstream: ensure every spoken stretch has a corresponding timeline segment with its vo_line.
- An end card, if your pipeline has one, is additional to audio_duration and is NOT part of the timeline sum.
- Run this BEFORE your final video render so the renderer receives the measured audio_duration.