How Video-Use Integrates Loudness Normalization at -14 LUFS into the Final Render for Social Media Standards

Video-use automatically applies two-pass FFmpeg loudnorm filtering during the final render to enforce -14 LUFS integrated loudness, -1 dBTP true-peak, and 11 LU loudness range, ensuring outputs meet YouTube, TikTok, Instagram, and other platform standards without manual re-encoding.

The browser-use/video-use repository streamlines video production by baking industry-standard loudness normalization directly into its rendering pipeline. By hard-coding the social media standard of -14 LUFS ( Loudness Units relative to Full Scale), the tool ensures that final exports are immediately ready for upload across major platforms, eliminating the need for external audio mastering or re-encoding.

Social Media Loudness Standards in Video-Use

The repository defines target constants in helpers/render.py that align with the normalization requirements used by YouTube, Instagram Reels, TikTok, X, and LinkedIn. These values represent the integrated loudness, true-peak ceiling, and acceptable loudness range that platforms expect for optimal playback.

Target Constants Defined in render.py

The module declares three global constants that drive the FFmpeg loudnorm filter:

# helpers/render.py (lines 690-695)

# Social-media standard: -14 LUFS integrated, -1 dBTP peak, LRA 11 LU.

# Matches YouTube / Instagram / TikTok / X / LinkedIn normalization targets.

LOUDNORM_I = -14.0          # target integrated loudness

LOUDNORM_TP = -1.0          # target true-peak

LOUDNORM_LRA = 11.0         # target loudness range

These constants ensure that every processed video adheres to the -14 LUFS standard rather than broadcast television's typical -4 LUFS, making the output immediately suitable for online consumption.

Two-Pass Loudness Measurement and Application

Video-use implements a two-pass normalization strategy to achieve broadcast-quality loudness correction. This approach first analyzes the source audio to measure its current statistics, then applies precise correction parameters in the final encode.

First Pass: Measuring Input Loudness

The measure_loudness() function runs FFmpeg in analysis mode using the loudnorm filter with print_format=json. This extracts the input's current integrated loudness (input_i), true-peak (input_tp), loudness range (input_lra), and threshold values without altering the file.

def measure_loudness(video_path: Path) -> dict[str, str] | None:
    filter_str = f"loudnorm=I={LOUDNORM_I}:TP={LOUDNORM_TP}:LRA={LOUDNORM_LRA}:print_format=json"
    cmd = ["ffmpeg", "-y", "-hide_banner", "-nostats",
           "-i", str(video_path), "-af", filter_str,
           "-vn", "-f", "null", "-"]
    proc = subprocess.run(cmd, capture_output=True, text=True)
    # JSON extracted from proc.stderr

This measurement phase ensures that the second pass can apply linear normalization with measured offsets rather than applying generic gain adjustments.

Second Pass: Applying Normalization Parameters

The apply_loudnorm_two_pass() function feeds the measured statistics back into FFmpeg alongside the target constants. When the preview flag is set to True (triggered by --draft), it uses a faster one-pass approximation instead of the precise two-pass method.

def apply_loudnorm_two_pass(input_path: Path, output_path: Path, preview: bool = False) -> bool:
    if preview:
        # One-pass approximation for draft renders

        filter_str = f"loudnorm=I={LOUDNORM_I}:TP={LOUDNORM_TP}:LRA={LOUDNORM_LRA}"
    else:
        measurement = measure_loudness(input_path)
        filter_str = (
            f"loudnorm=I={LOUDNORM_I}:TP={LOUDNORM_TP}:LRA={LOUDNORM_LRA}"
            f":measured_I={measurement['input_i']}"
            f":measured_TP={measurement['input_tp']}"
            f":measured_LRA={measurement['input_lra']}"
            f":measured_thresh={measurement['input_thresh']}"
            f":offset={measurement['target_offset']}:linear=true"
        )
    # FFmpeg execution logic follows

The linear=true parameter ensures that the gain adjustment applies consistently across the entire dynamic range without introducing distortion.

Integration with the Final Rendering Pipeline

Loudness normalization integrates at the terminal stage of the rendering workflow, occurring after all visual elements—overlays, subtitles, and color grading—have been composited into a temporary "pre-norm" file.

The Default Rendering Flow

In helpers/render.py (lines 644-652), the main execution logic checks for the --no-loudnorm flag before deciding whether to apply normalization:

# helpers/render.py – main rendering flow excerpt

if args.no_loudnorm:
    build_final_composite(base_path, overlays, subs_path, out_path, edit_dir)
else:
    tmp_composite = out_path.with_suffix(".prenorm.mp4")
    build_final_composite(base_path, overlays, subs_path, tmp_composite, edit_dir)
    print("loudness normalization → social-ready (-14 LUFS / -1 dBTP / LRA 11)")
    apply_loudnorm_two_pass(tmp_composite, out_path, preview=args.draft)
    tmp_composite.unlink(missing_ok=True)

This workflow ensures that visual compositing occurs only once, while the audio normalization operates on the final mixed track. The temporary prenorm.mp4 file is automatically deleted after successful normalization, leaving only the platform-compliant final output.

Rendering Commands and Usage Examples

The following commands demonstrate how to control loudness normalization behavior during the final render.

Default Render (Social-Ready Loudness)

Run the standard pipeline to produce a -14 LUFS compliant video:

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

Result: The system creates a temporary pre-norm composite, measures its loudness, applies two-pass normalization, and outputs final.mp4 ready for immediate upload to social platforms.

Skip Loudness Normalization

Bypass the audio processing for custom mastering workflows:

python helpers/render.py my_edit.edl.json -o final.mp4 --no-loudnorm

Result: The composite writes directly to final.mp4 without any loudness analysis or adjustment, preserving the source audio levels.

Preview Render (Fast One-Pass)

Generate a quick draft using the approximation mode:

python helpers/render.py my_edit.edl.json -o preview.mp4 --draft

Result: Uses apply_loudnorm_two_pass(..., preview=True) for faster encoding, applying target constants without first-pass measurement. This produces smaller files faster but with less precise loudness correction.

Summary

• Target standards: Video-use hard-codes -14 LUFS integrated loudness, -1 dBTP true-peak, and 11 LU loudness range in helpers/render.py to match YouTube, TikTok, Instagram, and LinkedIn requirements.
• Two-pass process: The measure_loudness() and apply_loudnorm_two_pass() functions implement FFmpeg's loudnorm filter with measured input statistics for precise linear correction.
• Pipeline integration: Normalization occurs after visual compositing, using temporary pre-norm files that are cleaned up automatically after processing.
• User control: The --no-loudnorm flag disables processing, while --draft enables fast one-pass approximation for preview renders.

Frequently Asked Questions

Why does video-use target -14 LUFS instead of -4 LUFS?

The repository intentionally follows the social media standard of -14 LUFS rather than the -4 LUFS commonly used for broadcast television. This ensures that videos uploaded to YouTube, Instagram Reels, TikTok, X, and LinkedIn match the loudness envelope these platforms expect, preventing automatic volume adjustments or quality degradation during platform transcoding.

Can I customize the loudness targets in video-use?

Currently, the loudness targets are hard-coded as LOUDNORM_I, LOUDNORM_TP, and LOUDNORM_LRA in helpers/render.py. To use different values—such as -4 LUFS for broadcast or -23 LUFS for podcasting—you must manually edit these constants in the source file before running the render pipeline.

What is the difference between preview and final render loudness processing?

Final renders use a two-pass approach: first measuring the source audio statistics with measure_loudness(), then applying precise correction via apply_loudnorm_two_pass(). Preview/draft renders (--draft flag) skip the measurement phase and use a one-pass approximation, which is significantly faster but less accurate, making it suitable for quick reviews but not final distribution.

Which social media platforms require -14 LUFS normalization?

The -14 LUFS standard is widely adopted by YouTube, Instagram (including Reels), TikTok, X (formerly Twitter), and LinkedIn. By encoding to this specification, video-use ensures that your content maintains consistent perceived loudness across all these platforms without triggering automated gain adjustments during upload.

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