Configuration

All configuration values default to None unless otherwise specified. For FFmpeg codec settings, a None value means that it uses ffmpeg’s own default value for when the flag is unspecified.

Here are some general resources on ffmpeg’s encoding flags, and how to choose encoding settings that fit your use-case.

General

IMAGE_ENGINE

The engine to use for non-video files. It defaults to 'thumbor.engines.pil', which is thumbor’s default value for ENGINE

FFMPEG_ENGINE

The engine to use for video files. It defaults to 'thumbor_video_engine.engines.ffmpeg'.

GIFSICLE_PATH

The path to the gifsicle binary. It defaults to None, in which case it looks for gifsicle in PATH. This is only used if GIF_ENGINE is set to 'thumbor_video_engines.engines.gif'. As of version 6.7.0, thumbor does not support configuring this value.

GIFSICLE_ARGS

A list of additional args to pass to gifsicle. This is only used if GIF_ENGINE is set to 'thumbor_video_engines.engines.gif'.

FFMPEG_USE_GIFSICLE_ENGINE

Equivalent to USE_GIFSICLE_ENGINE, but for the FFmpeg engine. It defaults to False. If True, it will perform any image operations on animated gifs (e.g. cropping and resizing) using gifsicle (by way of GIF_ENGINE).

FFMPEG_HANDLE_ANIMATED_GIF

Whether to process animated gifs with the FFmpeg engine. It defaults to True.

FFMPEG_GIF_AUTO_WEBP

Specifies whether animated WebP format should be used automatically if the source image is an animated gif and the request accepts it (via Accept header). It defaults to True, but only works when AUTO_WEBP is also enabled.

FFMPEG_GIF_AUTO_H264

Specifies whether H264 format should be used automatically if the source image is an animated gif and the request accepts it (via Accept: video/*). It defaults to False.

FFMPEG_GIF_AUTO_H265

Specifies whether H265 format should be used automatically if the source image is an animated gif and the request accepts it (via Accept: video/*). It defaults to False.

FFPROBE_PATH

Path for the ffprobe binary. It defaults to '/usr/local/bin/ffprobe'.

H.264 (MP4)

FFMPEG_H264_TWO_PASS

Whether to use two-pass encoding for h264 in FFmpeg. Default False.

FFMPEG_H264_CRF

-crf. The constant quality to use by FFmpeg for h264 encoding.

FFMPEG_H264_VBR

-b:v: The average bitrate to be used by FFmpeg for h264 encoding.

FFMPEG_H264_MINRATE

-minrate: minimum bound for bitrate.

FFMPEG_H264_MAXRATE

-maxrate: maximum bound for bitrate.

FFMPEG_H264_BUFSIZE

-bufsize: The rate control buffer. Used to determine the range across which the requested average bitrate and min/max should be enforced.

FFMPEG_H264_PRESET

-preset. A collection of options that will provide a certain encoding speed to compression ratio. A slower preset will provide better compression (compression is quality per filesize). This means that, for example, if you target a certain file size or constant bit rate, you will achieve better quality with a slower preset. Similarly, for constant quality encoding, you will simply save bitrate by choosing a slower preset.

Use the slowest preset that you have patience for. The available presets in descending order of speed are: ultrafast, superfast, veryfast, faster, fast, medium (default), slow, slower, veryslow

FFMPEG_H264_PROFILE

-profile: Determines h264 compatibility version.

FFMPEG_H264_LEVEL

-level: Controls h264 feature set, which affects device compatibility.

FFMPEG_H264_TUNE

-tune: Change settings based upon the specifics of your input

FFMPEG_H264_QMIN

-qmin: Set the minimum video quantizer scale.

FFMPEG_H264_QMAX

-qmax: Set the maximum video quantizer scale.

H.265 (aka HEVC)

FFmpeg H.265 Encoding Guide

FFMPEG_H265_TWO_PASS

Whether to use two-pass encoding for h265 encoding. Default False.

FFMPEG_H265_PRESET

-preset. A collection of options that will provide a certain encoding speed to compression ratio. Same values as h264

FFMPEG_H265_LEVEL

-level: Controls h265 feature set, which affects device compatibility.

FFMPEG_H265_MAXRATE

The –vbv-maxrate flag passed to FFmpeg for h265 encoding.

FFMPEG_H265_BUFSIZE

The –vbv-bufsize flag passed to libx265.

FFMPEG_H265_CRF_MIN

The –crf-min flag passed to libx265.

FFMPEG_H265_CRF_MAX

The –crf-max flag passed to libx265.

FFMPEG_H265_PROFILE

-profile: Determines h265 compatibility version.

FFMPEG_H265_TUNE

-tune: Change settings based upon the specifics of your input. Same as h264.

FFMPEG_H265_CRF

-crf: the constant quality to use by FFmpeg for h264 encoding.

FFMPEG_H265_VBR

-b:v: The average bitrate to be used by FFmpeg for h265 encoding.

VP9 (WebM)

FFMPEG_VP9_TWO_PASS

Whether to use two-pass encoding for VP9 in FFmpeg. Default False.

FFMPEG_VP9_VBR

-b:v. The average bitrate to be used by FFmpeg for VP9 encoding.

FFMPEG_VP9_LOSSLESS

-lossless. Whether to enable lossless encoding for VP9. Default False.

FFMPEG_VP9_DEADLINE

-deadline: can be set to:

good:the default and recommended for most applications.
best:recommended if you have lots of time and want the best compression efficiency.
realtime:recommended for live / fast encoding.

FFMPEG_VP9_CRF

-crf. The constant quality to use by FFmpeg for VP9 encoding.

FFMPEG_VP9_CPU_USED

-cpu-used: Affects compilation speed and quality trade-off

FFMPEG_VP9_ROW_MT

-row-mt. Whether to enable row-based multithreading for VP9 encoding.

FFMPEG_VP9_MINRATE

-minrate: minimum bound for bitrate.

FFMPEG_VP9_MAXRATE

-maxrate: maximum bound for bitrate.

Animated WebP

FFMPEG_WEBP_LOSSLESS

-lossless: enables/disables use of lossless mode. libwebp default is False.

FFMPEG_WEBP_COMPRESSION_LEVEL

-compression_level: range 0-6, default 4. Higher values give better quality but slower speed. For lossless, it controls the size/speed trade-off.

FFMPEG_WEBP_QSCALE

-qscale: For lossy encoding, controls quality 0 to 100. For lossless, controls cpu and time spent compressing. libwebp built-in default 75.

FFMPEG_WEBP_PRESET

-preset Configuration preset. Consult FFmpeg libwebp codec documentation for more information.

Example Configuration

ENGINE = 'thumbor_video_engine.engines.video'
FFMPEG_USE_GIFSICLE_ENGINE = True
FFMPEG_PATH = '/usr/bin/ffmpeg'
FFPROBE_PATH = '/usr/bin/ffprobe'
FFMPEG_H264_MAXRATE = '1200k'
FFMPEG_H264_BUFSIZE = '2400k'
FFMPEG_H264_CRF = 24
FFMPEG_H265_MAXRATE = '1500'
FFMPEG_H265_BUFSIZE = '3000'
FFMPEG_H265_CRF = 28
FFMPEG_VP9_VBR = '2M'
FFMPEG_VP9_CRF = 30
FFMPEG_VP9_MINRATE = '1500k'
FFMPEG_VP9_MAXRATE = '2500k'
FFMPEG_VP9_CPU_USED = 4
FFMPEG_VP9_ROW_MT = True
FFMPEG_WEBP_COMPRESSION_LEVEL = 3
FFMPEG_WEBP_QSCALE = 80