# What Is the Role of helpers/render.py in the video-use Project Architecture?

> Discover how helpers/render.py orchestrates video creation in the video-use project. This Python script transforms EDL JSON files into final videos through extraction, compositing, and normalization.

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

---

**[`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) serves as the command-line orchestrator that transforms declarative EDL (Edit Decision List) JSON files into polished final videos by coordinating extraction, color grading, concatenation, subtitle generation, overlay compositing, and loudness normalization.**

In the browser-use/video-use repository, [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) functions as the central driver of the video-production pipeline. This module implements the "HEURISTICS render pipeline" rules defined in its module docstring (lines 1-10) and delegates specialized tasks to companion utilities while maintaining strict control over PTS timing and output quality.

## The Orchestrator Pattern in video-use

Rather than handling video processing internally, [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) acts as a **workflow engine** that reads a declarative edit decision and invokes specialized helpers at each stage. It resides in the `helpers/` directory alongside [`grade.py`](https://github.com/browser-use/video-use/blob/main/grade.py), [`transcribe.py`](https://github.com/browser-use/video-use/blob/main/transcribe.py), and [`timeline_view.py`](https://github.com/browser-use/video-use/blob/main/timeline_view.py), but uniquely holds responsibility for sequencing operations and managing the state between pipeline phases. The file enforces architectural constraints such as lossless intermediate formats and precise PTS (Presentation Timestamp) shifts to ensure overlays and subtitles align correctly with the final output timeline.

## The Six-Stage Rendering Pipeline

The core logic inside [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) executes a deterministic six-stage pipeline that converts raw source footage into delivery-ready MP4s.

### 1. Per-Segment Extraction and Color Grading

The process begins with `extract_segment()` (lines 61-86), which isolates individual clips from source files according to the EDL ranges. During extraction, the helper applies optional **color-grade filters**, performs HDR-to-SDR tone-mapping for compatibility, executes portrait scaling transformations, and inserts 30 ms audio fades at clip boundaries to prevent clicking. This stage delegates color preset selection to [`grade.py`](https://github.com/browser-use/video-use/blob/main/grade.py) via the `auto_grade_for_clip` helper.

### 2. Lossless Concatenation

Once segments are extracted and graded, `concat_segments()` (lines 66-84) joins them using FFmpeg's concat demuxer to avoid generational loss. This step produces a base video stream that maintains the full quality of the graded extracts before any destructive compositing or encoding occurs.

### 3. Subtitle Generation from Transcripts

When the `--build-subtitles` flag is provided, `build_master_srt()` (lines 86-124) aggregates per-source transcript JSON files—generated previously by [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py)—into a single master SRT file. This master subtitle track respects the temporal offsets defined in the EDL, ensuring captions align with the concatenated timeline rather than individual source files.

### 4. Overlay Compositing and PTS Management

The `build_final_composite()` function (lines 93-167) layers graphics, animations, and the generated subtitle track onto the base video. Critically, this function calculates **PTS shifts** so that each overlay starts at the correct output timestamp regardless of its position in the concatenated sequence. Subtitles are composited last to ensure they remain visible above all graphic elements.

### 5. Loudness Normalization for Delivery

To meet social-media audio standards, `apply_loudnorm_two_pass()` (lines 88-90) executes a two-pass loudness normalization targeting **-14 LUFS** integrated loudness, **-1 dBTP** true peak, and **LRA 11** (Loudness Range). This step can be disabled with `--no-loudnorm` for faster draft renders when audio compliance is not required.

### 6. CLI Interface and Workflow Wiring

The `main()` function (lines 72-102) parses command-line arguments—including `--preview`, `--draft`, `--build-subtitles`, and `--no-loudnorm` toggles—and wires the six stages into an executable graph. It handles temporary file management, error propagation between stages, and final MP4 encapsulation.

## Integration with Helper Modules

[`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) maintains loose coupling with the rest of the codebase through well-defined helper imports:

- **[`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py)**: Supplies color-grade presets and the `auto_grade_for_clip` utility used during the extraction phase.
- **[`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py)**: Produces per-source transcript JSON files consumed by the subtitle builder.
- **[`helpers/timeline_view.py`](https://github.com/browser-use/video-use/blob/main/helpers/timeline_view.py)**: Generates visual timeline representations of the EDL for debugging edit plans before rendering.

This architecture allows [`render.py`](https://github.com/browser-use/video-use/blob/main/render.py) to remain focused on orchestration while domain-specific logic resides in dedicated modules.

## Command-Line Usage Examples

Render a full-resolution video from an EDL:

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

```

Create a quick preview with lower bitrate for client review:

```bash
python helpers/render.py path/to/edl.json -o preview.mp4 --preview

```

Generate subtitles from existing transcripts during the render:

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

```

Produce a draft without loudness normalization for faster internal iteration:

```bash
python helpers/render.py path/to/edl.json -o draft.mp4 --no-loudnorm

```

## Summary

- **[`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)** is the pipeline orchestrator that implements the HEURISTICS render workflow defined in the project's architecture.
- It processes **EDL JSON** through six distinct stages: extraction, concatenation, subtitle building, compositing, loudness normalization, and CLI management.
- The module preserves video quality via **lossless concatenation** before applying destructive compositing operations.
- It enforces broadcast audio standards through **two-pass loudnorm** targeting -14 LUFS integrated loudness.
- Flexible CLI flags support preview, draft, and subtitle-generation workflows without modifying the core EDL.

## Frequently Asked Questions

### What is an EDL in the context of video-use?

An **EDL (Edit Decision List)** is a JSON file that declaratively describes which segments to extract from source videos, their order on the timeline, and any associated metadata such as transcript files or overlay assets. [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) parses this file to determine the exact frame ranges and temporal offsets required for the final output.

### How does helpers/render.py handle color grading?

The module delegates color transformations to [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) while managing the extraction workflow. During the `extract_segment()` phase, it applies **HDR-to-SDR tone-mapping**, portrait scaling, and optional preset grades before passing the graded clips to the concatenation stage, ensuring consistent color science across heterogeneous source footage.

### Can I skip loudness normalization during rendering?

Yes. Pass the `--no-loudnorm` flag to bypass the `apply_loudnorm_two_pass()` step (lines 88-90). This reduces render time significantly and is useful for internal drafts where strict adherence to -14 LUFS broadcast standards is unnecessary, though it should be enabled for final delivery to social platforms.

### What is the difference between preview and draft modes?

The **preview** mode (activated with `--preview`) typically renders at lower resolution or bitrate for quick client approvals, while **draft** mode (often implied by `--no-loudnorm` or similar flags) may retain full resolution but skips computationally expensive steps like loudness normalization or final compositing to accelerate the feedback loop during post-production.