Configure Frame Threading and WPP in FFmpeg libx265

This article explains how to configure the frame-threads and Wavefront Parallel Processing (wpp) options in the FFmpeg libx265 encoder. By customizing these parameters, you can optimize CPU utilization, control memory usage, and balance encoding speed against compression efficiency.

Understanding the Parameters

When encoding HEVC/H.265 video with libx265, parallel processing is primarily controlled by two mechanisms:

  • frame-threads: Determines the number of frames being encoded in parallel. Increasing this value improves encoding speed on multi-core processors but increases memory consumption and introduces a slight latency in the encoding pipeline.
  • wpp (Wavefront Parallel Processing): Allows rows of Coding Tree Units (CTUs) within a single frame to be encoded in parallel. WPP provides a significant speed boost with almost no loss in compression efficiency and very low latency.

By default, libx265 automatically detects your CPU core count and configures optimal defaults for both settings. However, manual configuration is necessary for specific low-latency, streaming, or resource-constrained environments.

How to Configure in FFmpeg

Both options are configured using the -x265-params flag in FFmpeg. Parameters are passed as key-value pairs separated by colons.

1. Configuring frame-threads

To manually set the number of frame threads, define frame-threads=N, where N is the number of threads. Setting this to 1 disables frame-level parallelism.

ffmpeg -i input.mp4 -c:v libx265 -x265-params frame-threads=4 output.mp4

2. Configuring wpp

WPP is enabled by default. You can explicitly enable it using wpp=1 or disable it using wpp=0 (or no-wpp=1). Disabling WPP is rarely recommended unless you are targeting hardware decoders with strict compatibility limitations.

ffmpeg -i input.mp4 -c:v libx265 -x265-params wpp=0 output.mp4

3. Combining Both Options

To customize both settings simultaneously, separate them with a colon inside the -x265-params argument:

ffmpeg -i input.mp4 -c:v libx265 -x265-params frame-threads=2:wpp=1 output.mp4

  • For Ultra-Low Latency (Live Streaming): Disable frame threading to prevent frame buffering latency, and rely solely on WPP for multi-core acceleration.

    ffmpeg -i input.mp4 -c:v libx265 -x265-params frame-threads=1:wpp=1 output.mp4

  • For Maximum Speed (Batch Transcoding): Allow moderate frame threading alongside WPP. A common rule of thumb for frame-threads is to set it to the log2 of your CPU core count (e.g., 2 to 4 threads for an 8-core CPU).

    ffmpeg -i input.mp4 -c:v libx265 -x265-params frame-threads=3:wpp=1 output.mp4