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

> Learn how video-use generates subtitles with output timeline offsets after segment concatenation. The pipeline stitches transcripts into a unified SRT, aligning captions with the final video timeline.

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

---

**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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)

The subtitle generation logic resides in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/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.

```python
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:

```python
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:

```bash
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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py):

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