How render.py Handles Video Codecs and Container Formats in Video-Use

The render.py script standardizes all output to H.264 video with AAC audio inside an MP4 container, using ffmpeg for extraction, tone-mapping HDR sources to SDR, and lossless stream copying during concatenation to avoid generational loss.

The video-use repository by browser-use provides automated video editing utilities, with helpers/render.py serving as the core rendering engine. This script manages the entire transcoding pipeline, enforcing consistent video codecs and container formats across diverse source footage while optimizing for social-media delivery standards.

Standardizing Codecs and Containers with ffmpeg

The script enforces a strict codec-container strategy through three distinct processing stages, ensuring predictable output regardless of input variability.

Per-Segment Extraction to H.264 and AAC

During the initial extraction phase, the extract_segment function (lines 1999‑2007) invokes ffmpeg with explicit encoder flags:

-c:v libx264 -c:a aac

This configuration transcodes every source segment to H.264 video and AAC audio, outputting individual MP4 files regardless of the original codec. By normalizing at the extraction stage, render.py eliminates compatibility issues from heterogeneous source formats.

Lossless Concatenation via Stream Copying

When joining extracted clips, the concat_segments function (lines 667‑679) utilizes ffmpeg’s concat demuxer with the -c copy flag. This stream copy operation preserves the already-encoded H.264 and AAC streams without re-encoding, avoiding generational quality loss while maintaining the MP4 container format. The script automatically applies this optimization when all segments share compatible codecs.

HDR Source Handling and Tone Mapping

High Dynamic Range (HDR) footage requires special handling to ensure compatibility with standard playback devices.

Automatic HDR Detection

Before processing each segment, render.py checks the source’s color transfer characteristics (lines 120‑130) to identify HDR formats. The script specifically detects HLG (Hybrid Log-Gamma) and PQ (Perceptual Quantizer) transfers defined in the HDR_TRANSFERS constant.

SDR Conversion Pipeline

When HDR content is detected, the script prepends the TONEMAP_CHAIN filter chain (lines 111‑117) to the video filter graph. This applies tone-mapping to convert HDR content to SDR (Rec. 709) during the extraction phase, ensuring the final H.264 output displays correctly on non-HDR displays.

Final Compositing and Audio Processing

After optional overlays or subtitles are applied, the script performs final encoding and audio normalization.

High-Quality Output Encoding

The final compositing stage (lines 555‑566) encodes video using:

-c:v libx264 -preset fast -crf 18

Audio streams use -c:a copy since they were already normalized to AAC during extraction. This produces a single MP4 file optimized for upload to social media platforms.

Optional Loudness Normalization

If enabled, the apply_loudnorm_two_pass function (lines 331‑345) executes a two-pass loudnorm filter on the audio stream. Despite the additional processing, the audio codec remains AAC, maintaining container compatibility without transcoding.

Command-Line Usage Examples

Extract a segment with default codec settings:

python helpers/render.py my_edl.json -o final.mp4

The script invokes ffmpeg with -c:v libx264 -c:a aac, producing final.mp4 with standardized codecs.

Generate a lower-bitrate preview while maintaining the same codec standards:

python helpers/render.py my_edl.json -o preview.mp4 --preview

This adjusts the libx264 preset to medium and CRF to 22, still delivering H.264/AAC within an MP4 container.

Summary

• Standardized Output: render.py enforces H.264 video + AAC audio inside MP4 containers via ffmpeg, as implemented in helpers/render.py (lines 1999‑2007).
• Lossless Concatenation: The concat_segments function (lines 667‑679) uses -c copy to join clips without re-encoding.
• HDR Compatibility: Automatic detection of HLG/PQ transfers (lines 120‑130) triggers tone-mapping to SDR using TONEMAP_CHAIN (lines 111‑117).
• Audio Consistency: Optional loudness normalization via apply_loudnorm_two_pass (lines 331‑345) preserves the AAC codec throughout the pipeline.

Frequently Asked Questions

What container format does render.py output?

The script exclusively outputs MP4 files. Regardless of the source format, every intermediate segment and the final composite use the MP4 container, ensuring broad compatibility with social media platforms and playback devices.

Does render.py re-encode video during concatenation?

No. During the concatenation phase, render.py uses ffmpeg’s -c copy flag (lines 667‑679) to perform lossless stream copying. This preserves the H.264 encoding from the extraction phase without introducing generational quality loss.

How does render.py handle HDR video sources?

The script detects HDR content by checking for HLG or PQ color transfers (lines 120‑130). When detected, it automatically applies the TONEMAP_CHAIN filter (lines 111‑117) during extraction to convert HDR to SDR (Rec. 709), ensuring the final H.264 output displays correctly on standard screens.

Can I change the video codec from H.264 to something else?

According to the source code in helpers/render.py, the script hardcodes -c:v libx264 for both segment extraction (lines 1999‑2007) and final compositing (lines 555‑566). There are no command-line flags to override the video codec, as the tool is specifically optimized for H.264/AAC/MP4 delivery standards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}