# How to Debug Subtitle Misalignment Issues in Video-Use Rendered Videos

> Fix subtitle misalignment in video-use rendered videos. Learn to debug timestamp conversion, filter graph order, and missing file issues for flawless captions.

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

---

**Subtitle misalignment in video-use output stems from three root causes: incorrect timestamp conversion in the master SRT, subtitles applied before overlays in the filter graph, or missing subtitle files.**

The `browser-use/video-use` repository automates video rendering from multiple source transcripts, but timing errors can occur when the pipeline converts word-level timestamps into output-timeline coordinates. This guide provides a systematic debugging workflow based on the actual source code implementation to help you identify and fix subtitle synchronization issues.

## Verify Master SRT Timestamp Conversion

The `build_master_srt` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) (lines 15-75) converts per-source transcript timestamps into output-timeline timestamps by applying segment offsets. Incorrect calculations here cause persistent drift throughout the video.

### Check the Offset Calculations

The conversion logic applies accumulated segment offsets to local timestamps:

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

```

**Hard Rule 5** in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) (lines 22-27) mandates that the master SRT must use output-timeline offsets. If your subtitles appear consistently early or late by a fixed duration, the `seg_offset` accumulation logic at lines 28-73 is likely miscalculating the accumulated segment durations.

### Inspect Generated Files

Verify that `edit/master.srt` contains monotonically increasing timestamps starting near 0 seconds. Compare cue timestamps against the source transcript JSON to ensure the difference equals the expected segment offset.

```bash

# Display first 10 cues from the master SRT

head -n 40 edit/master.srt

# Check raw transcript timestamps for a specific source

jq '.words[] | {text, start, end}' edit/transcripts/C0103.json | head

```

## Validate Subtitle Filter Order in FFmpeg Pipeline

**Hard Rule 1** requires subtitles to be the *last* filter in the filter graph. If subtitles are applied before overlays, they will be hidden or appear misaligned.

### Confirm Filter Graph Structure

The `build_final_composite` function (lines 95-170 in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)) assembles the filter graph in three stages. The subtitles filter must appear at lines 38-44:

```python
filter_parts.append(
    f"{current}subtitles='{subs_abs}':force_style='{SUB_FORCE_STYLE}'[outv]"
)

```

Examine the generated FFmpeg command output to verify that `-filter_complex` ends with the `subtitles=` filter. If the subtitles parameter appears before overlay filters, the pipeline violates Hard Rule 1.

### Test with the --no-subtitles Flag

Run the render script with `--no-subtitles` to isolate the issue:

```bash
python helpers/render.py edit/edl.json -o final.mp4 --no-subtitles

```

If the video renders correctly without subtitles, the misalignment originates from the subtitle filter placement or the SRT file itself, not the underlying video composition.

## Check Subtitle File Path Resolution

The script silently skips the subtitle filter if the resolved path does not exist. The existence check occurs at lines 8-10 of `build_final_composite`:

```python
has_subs = subtitles_path is not None and subtitles_path.exists()

```

**Verify file presence** by checking the resolved path printed by the script (look for "subtitles: yes/no" in the output). If you specified `--build-subtitles`, confirm that the function successfully wrote the file via `out_path.write_text` at the end of `build_master_srt`.

## Inspect Final Video with ffprobe

Use `ffprobe` to extract embedded subtitle timestamps and compare them against your master SRT:

```bash

# Check subtitle stream metadata

ffprobe -loglevel error -show_entries stream=index,codec_type:stream_tags=language \
        -select_streams s -i final.mp4

# Dump first 10 seconds of subtitle timestamps

ffprobe -loglevel error -show_entries frame=pkt_pts_time:stream_index=2 \
        -select_streams s -read_intervals 0%+10 -i final.mp4

```

The `pkt_pts_time` values should match the timestamps in `edit/master.srt`. Any deviation indicates a mismatch between the generated SRT and the filter graph application.

## Enable Verbose FFmpeg Logging

Modify the command construction in `build_final_composite` to expose the exact filter chain:

```python
cmd = [
    "ffmpeg", "-y", "-loglevel", "info",  # Add this flag

    *inputs,
    "-filter_complex", filter_complex,
    # ... remaining arguments

]

```

Re-run the render and examine the output for the `filter_complex` string. Confirm that the subtitle filter appears as the final element producing the `[outv]` output label.

## Summary

- **Master SRT timestamp conversion** happens in `build_master_srt` (lines 15-75) and must account for segment offsets according to Hard Rule 5.
- **Subtitle filter order** must place the subtitles filter last in the filter graph (Hard Rule 1), implemented at lines 38-44 of `build_final_composite`.
- **File existence validation** occurs at lines 8-10 and silently disables subtitles if the path is invalid.
- **ffprobe verification** confirms that embedded subtitle timestamps match the source SRT file.
- **Verbose logging** reveals the exact FFmpeg filter chain for manual inspection.

## Frequently Asked Questions

### Why do my subtitles appear at the wrong time even though the SRT file looks correct?

If the SRT timestamps appear correct but the video shows misalignment, the `seg_offset` calculation in `build_master_srt` (lines 28-73) likely contains an arithmetic error. Verify that the accumulated offsets correctly map local transcript times to the output timeline by comparing the difference between a transcript JSON timestamp and the corresponding SRT cue time.

### How can I tell if subtitles are being hidden by video overlays?

Run the render with `--no-subtitles` first. If the underlying video composition looks correct without subtitles but the overlay appears to cover the text when subtitles are enabled, the subtitle filter is positioned before the overlay filters in the filter graph. According to Hard Rule 1 in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md), the subtitles filter must be the last element in the chain, as implemented at lines 38-44 of `build_final_composite`.

### What causes subtitles to disappear completely from the rendered output?

The script checks `subtitles_path.exists()` at lines 8-10 of `build_final_composite` and sets `has_subs = False` if the file is missing. Check that the resolved path points to an existing file and that `--build-subtitles` actually wrote the file to disk (the function ends with `out_path.write_text`). The script indicates file presence with a "subtitles: yes/no" message in the output.

### How do I manually rebuild the master SRT for testing?

Import the `build_master_srt` function from [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) and call it with the EDL JSON and output directory:

```python
from helpers.render import build_master_srt
import json
from pathlib import Path

edl = json.loads(Path('edit/edl.json').read_text())
build_master_srt(edl, Path('edit'), Path('edit/master_test.srt'))

```