# Why Subtitles Are Applied Last in the Filter Chain for video-use

> Learn why video subtitles are applied last in the FFmpeg filter chain. Discover how this ensures captions display clearly over all video elements and animations.

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

---

**In the `video-use` repository, subtitles are deliberately appended as the final filter in the FFmpeg chain to ensure captions render on top of all overlays and animations.**

The `browser-use/video-use` project constructs its video rendering pipeline through a strict, rule-driven ordering system. When processing edits through the `build_final_composite` function, the code concatenates base video layers, merges overlay animations, and only then applies the `subtitles` filter. This architectural decision ensures proper visual hierarchy while simplifying the filter-graph construction logic.

## The Rendering Pipeline Order

The core rendering logic resides in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), specifically within the `build_final_composite` function (lines 38-44). This function implements what the codebase refers to as **Rule 1**: subtitles must always be the final processing step.

According to the source code comments at the top of the file, the pipeline follows this sequence: *"single filter graph that overlays animations … and applies `subtitles` filter **LAST** → final.mp4"*【§ 3 – lines 5-10】. This design mandate ensures that subtitle rendering occurs only after all visual compositing is complete.

## Three Reasons for Final Subtitle Placement

### Correct Visual Stacking

In an FFmpeg filter graph, filters execute sequentially. Overlays—such as animated graphics or picture-in-picture clips—are added using `overlay=` filters. If subtitles were placed earlier in the chain, they would render underneath subsequent overlays, making captions invisible on frames containing overlapping elements. By applying subtitles last, the text is guaranteed to appear **on top of every visual element** in the final output.

### Simplified Filter-Graph Construction

Treating subtitles as a terminal step keeps the overlay-building logic independent of subtitle handling. The code can construct complex overlay chains without calculating subtitle positioning or worrying about filter interaction. This separation of concerns allows the `build_final_composite` function to append the subtitle filter only after confirming that all overlay layers have been merged into a single video stream.

### Consistent Styling

Subtitles are rendered using a forced style defined by the `SUB_FORCE_STYLE` constant, which is tuned specifically for vertical-video platforms. Applying this style after the overlay chain ensures the formatting is applied to the **final composited picture**, preventing subsequent video filters from altering text appearance or unintended visual artifacts.

## Implementation Details in render.py

The execution of Rule 1 appears explicitly in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) between lines 38-44. The function first constructs the overlay chain, then conditionally appends the subtitles filter:

```python

# Subtitles LAST — Rule 1

if has_subs:
    subs_abs = str(subtitles_path.resolve()).replace(":", r"\:").replace("'", r"\'")
    filter_parts.append(
        f"{current}subtitles='{subs_abs}':force_style='{SUB_FORCE_STYLE}'[outv]"
    )

```

This code generates the final filter graph segment: **base → overlays → subtitles → out**【§ 5 – lines 503-505】. The `subtitles` filter receives the output of the overlay chain (`current`) and produces the final output label `[outv]`, ensuring no further video processing occurs after subtitle burn-in.

## Rendering Commands and Options

To render a video with the default behavior (overlays first, subtitles last):

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

```

To render while skipping subtitles entirely:

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

```

To force subtitle generation while maintaining the correct filter order:

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

```

## Summary

- **Visual hierarchy demands last placement**: Subtitles must sit above all overlays to remain visible.
- **Code architecture enforces Rule 1**: The `build_final_composite` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) treats subtitles as a terminal operation.
- **Filter chain order is explicit**: The pipeline flows base video → overlays → subtitles → output.
- **Styling consistency**: `SUB_FORCE_STYLE` applies to the final composited frame without interference from overlay filters.

## Frequently Asked Questions

### What happens if subtitles are placed before overlays in the FFmpeg filter chain?

If the `subtitles` filter were inserted before `overlay` filters, the rendered text would be buried beneath any subsequent overlay layers. According to the `video-use` source code, this would make captions invisible on frames containing picture-in-picture elements or animated graphics, violating the project's visual design requirements.

### Where is the "subtitles last" rule documented in the codebase?

The rule appears as a comment at the top of [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) (lines 5-10) and is implemented in the `build_final_composite` function (lines 38-44). The comment explicitly states that the filter graph must apply the `subtitles` filter **LAST** when generating the final output file.

### Can I change the order of subtitle application in video-use?

The current architecture in `browser-use/video-use` hardcodes subtitles as the final step through Rule 1. While you could modify the `build_final_composite` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) to reposition the subtitle filter, doing so would break the visual stacking guarantees and potentially cause subtitles to appear underneath overlays.

### Why does the code escape colons and quotes in the subtitle path?

The `subtitles` filter in FFmpeg requires special character escaping to prevent filter graph syntax errors. In lines 40-41 of [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), the code replaces colons with `\\:` and single quotes with `\\'` to ensure the subtitle file path is correctly parsed within the filter string while maintaining cross-platform path compatibility.