How Subtitles Are Generated With Output-Timeline Offsets After Segment Concatenation in video-use

The video-use pipeline stitches per-source transcripts into a unified SRT by accumulating segment durations as offsets, ensuring each caption aligns with the final concatenated video timeline.

The browser-use/video-use repository automates complex video editing workflows, including the generation of synchronized subtitles after multiple clips are concatenated. When you enable the --build-subtitles flag, the system produces a master SRT file that accounts for temporal shifts introduced by segment reordering and trimming. This article explains how video-use calculates output-timeline offsets to keep subtitles perfectly aligned with the final rendered video.

The Core Pipeline in helpers/render.py

The subtitle generation logic resides in helpers/render.py, specifically within the build_master_srt function. This routine processes an Edit Decision List (EDL) to assemble transcript snippets from multiple sources into a single, timeline-accurate subtitle track.

Accumulating Offsets Across EDL Ranges

The function iterates over each range in the EDL, where each range represents one extracted clip. A running variable seg_offset (initialized to 0.0) tracks the cumulative duration of all previously processed segments.

for r in edl["ranges"]:
    src_name = r["source"]
    seg_start = float(r["start"])
    seg_end = float(r["end"])
    seg_duration = seg_end - seg_start

This offset accumulator is critical because it ensures that subtitles from later segments appear after those from earlier segments in the final output, regardless of their original source timestamps.

Loading and Validating Transcripts

Transcripts are stored as JSON files under edit_dir/transcripts/<source>.json. If a transcript is missing for a specific range, the segment is skipped, but the seg_offset is still incremented to maintain timeline integrity.

Selecting Relevant Words

The helper _words_in_range filters the transcript for word objects whose temporal intervals overlap the current segment boundaries. This extracts only the dialogue occurring within the specified clip.

Chunking Words into Caption Blocks

To maintain readability, words are grouped into chunks of at most two words, breaking early on punctuation marks defined by PUNCT_BREAK. This prevents overly long lines in the final SRT output.

Calculating Output-Timeline Timestamps

The essential step occurs when converting segment-relative timestamps to output-timeline coordinates. For each word chunk, the code calculates local start and end times, then applies the cumulative offset:

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

This mathematical shift aligns every caption with the concatenated video timeline. The max(0.0, ...) guard ensures no negative timestamps while the + seg_offset places the cue at the correct position in the final output.

Formatting and Writing the SRT

The _srt_timestamp helper converts floating-point seconds into the standard HH:MM:SS,mmm SRT format. After processing all ranges, entries are sorted by start time and written to edit_dir/master.srt.

CLI Usage and FFmpeg Integration

To generate subtitles during rendering, invoke the script with the --build-subtitles flag:

python helpers/render.py edl.json -o final.mp4 --build-subtitles

This produces edit_dir/master.srt, which can later be burned into the video using FFmpeg's subtitles filter with the style defined in SUB_FORCE_STYLE at the top of helpers/render.py:

ffmpeg -i base.mp4 -vf "subtitles='edit/master.srt':force_style='FontName=Helvetica,FontSize=18,Bold=1,MarginV=90'" -c:a copy final_with_subs.mp4

Summary

• Offset accumulation: The seg_offset variable tracks cumulative duration across all EDL ranges to maintain timeline continuity.
• Temporal alignment: The formula max(0.0, local_time - seg_start) + seg_offset converts segment-relative timestamps to output-timeline coordinates.
• File locations: Generation logic lives in helpers/render.py, consuming transcripts from edit_dir/transcripts/ and outputting to edit_dir/master.srt.
• Chunking strategy: Words are grouped into two-word captions for readability, respecting punctuation breaks.
• CLI trigger: The --build-subtitles flag activates the build_master_srt pipeline during video rendering.

Frequently Asked Questions

What happens if a source transcript is missing?

If build_master_srt cannot locate a transcript JSON for a specific EDL range, it skips that segment's subtitles but still increments seg_offset by the segment's duration. This preserves the timeline alignment for subsequent segments.

How does the system handle word-level timing accuracy?

The _words_in_range function selects individual word objects based on their precise start and end timestamps within the source transcript. This allows sub-second accuracy when aligning captions to the output timeline, even after segments are reordered or trimmed.

Why are subtitles chunked into two-word blocks?

The chunking logic limits captions to two words (breaking on PUNCT_BREAK) to ensure on-screen readability. This prevents dense text blocks that might overwhelm viewers, adhering to standard subtitling best practices for quick consumption.

Can I customize the subtitle appearance?

Yes. The SUB_FORCE_STYLE constant in helpers/render.py defines default styling parameters including font, size, and margins. When burning subtitles with FFmpeg, you can override these values in the force_style parameter of the subtitles video filter.

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