How to Fix Subtitle Misalignment Issues After Concatenating Video Segments

When concatenating video clips with video-use, subtitle timestamps must be recalculated against the new timeline by building a master SRT file that applies cumulative segment offsets to each caption.

The browser-use/video-use repository provides a rendering pipeline that automatically resolves subtitle misalignment issues after concatenating video segments. When you concatenate multiple clips, the raw subtitle files retain their original timestamps, causing captions to appear too early or too late relative to the final edit. The solution implemented in helpers/render.py generates a master subtitle file with timestamps shifted to match the concatenated timeline.

Why Subtitles Drift After Concatenation

When you concatenate several video segments, each source clip maintains its own independent timeline. If you use the original SRT files directly, the captions reference timestamps from their respective source videos rather than the final composite timeline. This causes visible subtitle drift where captions appear before or after their corresponding audio in the concatenated output.

The video-use repository addresses this by treating subtitle generation as a post-processing step that accounts for the cumulative duration of all preceding segments.

The Solution: Building a Master SRT with Timeline Offsets

The repository solves subtitle misalignment through the build_master_srt function in helpers/render.py (lines 315-376). This function creates a unified subtitle file by applying a running offset to each segment's captions.

Collect Per-Source Transcripts

The pipeline first gathers transcripts generated by the transcribe helper for each source clip. These transcripts contain word-level timing data that serves as the foundation for accurate caption placement.

Compute Running Segment Offsets

As the function iterates over the EDL (Edit Decision List) ranges, it calculates a seg_offset value representing the cumulative duration of all previously processed segments. According to the offset logic in helpers/render.py (lines 26-38), the code groups words into 2-word chunks and adds seg_offset to each chunk's out_start and out_end timestamps. This ensures that captions from the second segment start after the first segment ends, and so on throughout the timeline.

Render Subtitles as the Final Filter

The build_final_composite function (lines 382-445) applies the subtitles filter as the last element of the filter-complex. This placement is critical because it ensures the shifted timestamps are applied after all video overlays and processing, maintaining synchronization with the final composited timeline.

Step-by-Step Fix

Follow these steps to ensure your subtitles align correctly after concatenation:

1. Verify your EDL ranges — Ensure the ranges list in your EDL JSON contains accurate start and end values for each segment. The offset calculation depends entirely on these durations.

2. Generate aligned subtitles — Use the --build-subtitles flag when rendering:

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

   This command generates a fresh master.srt file with proper offsets and uses it in the final composite.

3. Verify the output — After rendering, inspect the generated master.srt file in the same folder as your EDL:

   cat master.srt | less

4. Optional: Skip subtitles — If you prefer a clean video without captions, use the --no-subtitles flag instead:

   python helpers/render.py my_video.edl -o final.mp4 --no-subtitles

Common Pitfalls to Avoid

• Using external SRT files without rebuilding — Always supply the --build-subtitles flag. If omitted, the script searches for a pre-existing subtitle file with incorrect timestamps, causing misalignment.

• Incorrect EDL range values — Typos in start or end timestamps within the EDL JSON propagate directly into the offset calculation, shifting all subsequent captions by the error amount.

• Missing transcript files — If a source segment lacks a transcript JSON, build_master_srt skips that segment and prints a warning. Those segments will appear without captions in the final output.

Summary

• Subtitle misalignment occurs because original SRT timestamps don't account for the concatenated timeline.
• The build_master_srt function in helpers/render.py resolves this by applying a running seg_offset to each caption's start and end times.
• Always use the --build-subtitles CLI flag to generate a timeline-aware master.srt file.
• Subtitles are applied last in the filter-complex via build_final_composite to ensure proper synchronization.
• Verify EDL ranges contain accurate timestamps, as the offset calculation depends on cumulative segment durations.

Frequently Asked Questions

Why do my subtitles appear at the wrong time after joining video clips?

When concatenating video segments, each source clip maintains its original timeline. Without recalculation, captions reference timestamps from their respective source videos rather than the final composite timeline. The video-use repository fixes this by generating a master SRT file that adds cumulative segment offsets to each caption's timing.

How does the build_master_srt function calculate the correct timestamps?

The function walks through each EDL range and maintains a seg_offset variable representing the total duration of all preceding segments. It groups transcript words into 2-word chunks, then adds the current seg_offset to each chunk's out_start and out_end values. This ensures captions align with the concatenated video timeline as implemented in helpers/render.py (lines 315-376).

Can I use my own SRT file instead of generating one?

No, using an external SRT file without rebuilding will cause misalignment because external files lack the segment offset calculations. You must use the --build-subtitles flag to trigger the build_master_srt function, which creates a properly offset master file from the per-source transcripts.

What happens if a video segment has no transcript?

If a source segment lacks a transcript JSON file, build_master_srt skips that segment and prints a warning to the console. The final video will not contain captions for that specific segment, but all other segments will align correctly provided their transcripts exist.

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