How Output-Timeline Subtitle Offsets Work After Segment Concatenation in video-use

The video-use toolkit recalculates subtitle timestamps by adding a running seg_offset to each word's local time, ensuring captions align perfectly with the final concatenated video timeline.

The video-use repository provides lossless video editing capabilities that depend on precise subtitle synchronization across multiple source segments. When concatenating clips from different sources, output-timeline subtitle offsets must be recomputed to reflect the cumulative duration of preceding segments. This logic, implemented in helpers/render.py, converts absolute transcript timestamps into relative positions that match the final composited output.

Understanding the Offset Calculation Logic

The subtitle generation process in build_master_srt walks through each edit decision list (EDL) range and transforms source-relative timestamps into global output coordinates.

Iterating the EDL Ranges

The function processes the edl["ranges"] list sequentially, starting at line 28 of build_master_srt. Each range contains a source identifier (source), start time (start), and end time (end), defining which portion of a source clip appears in the final edit.

Tracking Cumulative Duration

A variable seg_offset (initialized at line 26) maintains the total duration of all previously processed segments. After handling each range, the script increments this accumulator by the current segment's duration using seg_offset += seg_duration.

Mapping Transcript Words

For each range, the helper _words_in_range filters the source transcript to return only words whose timestamps fall within the segment boundaries (seg_start to seg_end).

The Mathematical Transformation

The core conversion happens through a precise calculation that shifts local segment times into the global output timeline. For each word chunk, the script computes:

out_start = max(0.0, local_start - seg_start) + seg_offset
out_end   = max(0.0, local_end   - seg_start) + seg_offset

Here, local_start and local_end represent the absolute word timestamps from the original transcript, while seg_start marks the segment's beginning. The subtraction yields the word's position within the segment, and adding seg_offset shifts it into the global output timeline.

Building the Final SRT

After processing all ranges, the script sorts the collected (out_start, out_end, text) tuples by start time and writes them to master.srt using the _srt_timestamp formatter. Because concat_segments performs lossless concatenation that preserves exact segment durations, the cumulative seg_offset values correspond precisely to the positions where segments appear in the final MP4. The subtitles are overlaid last during compositing in build_final_composite, ensuring they sit atop the concatenated video.

Practical Implementation Example

Consider an EDL specifying two sources:

{
  "sources": {
    "cam1": "videos/cam1.mp4",
    "cam2": "videos/cam2.mp4"
  },
  "ranges": [
    { "source": "cam1", "start": 10.0, "end": 20.0 },
    { "source": "cam2", "start": 5.0, "end": 12.0 }
  ]
}

With transcripts containing a word at 12.3 s in cam1 and 8.5 s in cam2:

1. Segment 1 (cam1): Duration = 10 s, seg_offset = 0 s. Output start = (12.3 - 10.0) + 0 = 2.3 s.
2. Segment 2 (cam2): Duration = 7 s, seg_offset = 10 s. Output start = (8.5 - 5.0) + 10 = 13.5 s.

The resulting master.srt contains:

1
00:00:02,300 --> 00:00:02,800
WORD_FROM_CAM1

2
00:00:13,500 --> 00:00:13,900
WORD_FROM_CAM2

Summary

• Dynamic recalculation: Subtitle offsets are computed on the fly using seg_offset rather than using static transcript times.
• Lossless alignment: The concat_segments function preserves exact durations, ensuring offsets match the final video structure.
• Final overlay: Subtitles are applied as the last filter step in build_final_composite to ensure visibility.
• Core implementation: All logic resides in helpers/render.py, specifically within build_master_srt and supporting helpers.

Frequently Asked Questions

What is the primary purpose of output-timeline subtitle offsets?

The primary purpose is to remap absolute transcript timestamps from multiple source files into a single continuous timeline that matches the final concatenated video. This ensures that captions appear at the correct moment relative to the edited output, not the original source files.

How does video-use ensure subtitle accuracy across segment boundaries?

The script maintains a running seg_offset accumulator that tracks the cumulative duration of all previously processed segments. By adding this offset to each word's local segment time, the system guarantees that timestamps increase monotonically across the entire output, regardless of where segments originated in their source files.

Why must subtitles be recalculated rather than using original timestamps?

Original timestamps reference positions within source files, but the final output is a concatenation of trimmed segments. Since segments may start at arbitrary points in their sources and appear in any order, static timestamps would misalign with the final video. The recalculation adjusts for both segment trimming and sequential positioning.

Where in the codebase is the subtitle overlay applied?

The overlay occurs in build_final_composite within helpers/render.py, where the subtitles filter is added as the final processing step. This placement ensures that captions render on top of all video layers and effects while maintaining synchronization with the losslessly concatenated base video.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}