# How to Fix Subtitle Misalignment Issues After Concatenating Video Segments

> Fix subtitle misalignment after concatenating video clips. Learn to build a master SRT file with cumulative offsets for accurate timing using browser-use/video-use.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: how-to-guide
- Published: 2026-07-08

---

**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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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:
   ```bash
   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:
   ```bash
   cat master.srt | less
   ```

4. **Optional: Skip subtitles** — If you prefer a clean video without captions, use the `--no-subtitles` flag instead:
   ```bash
   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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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.