Options

The options for this filter are divided into the following sections:

These options control the overall output mode. By default, libplacebo will try to preserve the source colorimetry and size as best as it can, but it will apply any embedded film grain, dolby vision metadata or anamorphic SAR present in source frames.

w, h

Set the output video dimension expression. Default value is the input dimension.

Allows for the same expressions as the scale filter.

format

Set the output format override. If unset (the default), frames will be output in the same format as the respective input frames. Otherwise, format conversion will be performed.

force_original_aspect_ratio, force_divisible_by

Work the same as the identical scale filter options.

normalize_sar

If enabled, output frames will always have a pixel aspect ratio of 1:1. This will introduce padding/cropping as necessary. If disabled (the default), any aspect ratio mismatches, including those from e.g. anamorphic video sources, are forwarded to the output pixel aspect ratio.

pad_crop_ratio

Specifies a ratio (between 0.0 and 1.0) between padding and cropping when the input aspect ratio does not match the output aspect ratio and normalize_sar is in effect. The default of 0.0 always pads the content with black borders, while a value of 1.0 always crops off parts of the content. Intermediate values are possible, leading to a mix of the two approaches.

colorspace, color_primaries, color_trc, range

Configure the colorspace that output frames will be delivered in. The default value of auto outputs frames in the same format as the input frames, leading to no change. For any other value, conversion will be performed.

See the setparams filter for a list of possible values.

apply_filmgrain

Apply film grain (e.g. AV1 or H.274) if present in source frames, and strip it from the output. Enabled by default.

apply_dolbyvision

Apply Dolby Vision RPU metadata if present in source frames, and strip it from the output. Enabled by default. Note that Dolby Vision will always output BT.2020+PQ, overriding the usual input frame metadata. These will also be picked as the values of auto for the respective frame output options.

The options in this section control how libplacebo performs upscaling and (if necessary) downscaling. Note that libplacebo will always internally operate on 4:4:4 content, so any sub-sampled chroma formats such as yuv420p will necessarily be upsampled and downsampled as part of the rendering process. That means scaling might be in effect even if the source and destination resolution are the same.

upscaler, downscaler

Configure the filter kernel used for upscaling and downscaling. The respective defaults are spline36 and mitchell. For a full list of possible values, pass help to these options. The most important values are:

none

Forces the use of built-in GPU texture sampling (typically bilinear). Extremely fast but poor quality, especially when downscaling.

bilinear

Bilinear interpolation. Can generally be done for free on GPUs, except when doing so would lead to aliasing. Fast and low quality.

nearest

Nearest-neighbour interpolation. Sharp but highly aliasing.

oversample

Algorithm that looks visually similar to nearest-neighbour interpolation but tries to preserve pixel aspect ratio. Good for pixel art, since it results in minimal distortion of the artistic appearance.

lanczos

Standard sinc-sinc interpolation kernel.

spline36

Cubic spline approximation of lanczos. No difference in performance, but has very slightly less ringing.

ewa_lanczos

Elliptically weighted average version of lanczos, based on a jinc-sinc kernel. This is also popularly referred to as just "Jinc scaling". Slow but very high quality.

gaussian

Gaussian kernel. Has certain ideal mathematical properties, but subjectively very blurry.

mitchell

Cubic BC spline with parameters recommended by Mitchell and Netravali. Very little ringing.

lut_entries

Configures the size of scaler LUTs, ranging from 1 to 256. The default of 0 will pick libplacebo’s internal default, typically 64.

antiringing

Enables anti-ringing (for non-EWA filters). The value (between 0.0 and 1.0) configures the strength of the anti-ringing algorithm. May increase aliasing if set too high. Disabled by default.

sigmoid

Enable sigmoidal compression during upscaling. Reduces ringing slightly. Enabled by default.

Libplacebo comes with a built-in debanding filter that is good at counteracting many common sources of banding and blocking. Turning this on is highly recommended whenever quality is desired.

deband

Enable (fast) debanding algorithm. Disabled by default.

deband_iterations

Number of deband iterations of the debanding algorithm. Each iteration is performed with progressively increased radius (and diminished threshold). Recommended values are in the range 1 to 4. Defaults to 1.

deband_threshold

Debanding filter strength. Higher numbers lead to more aggressive debanding. Defaults to 4.0.

deband_radius

Debanding filter radius. A higher radius is better for slow gradients, while a lower radius is better for steep gradients. Defaults to 16.0.

deband_grain

Amount of extra output grain to add. Helps hide imperfections. Defaults to 6.0.

A collection of subjective color controls. Not very rigorous, so the exact effect will vary somewhat depending on the input primaries and colorspace.

brightness

Brightness boost, between -1.0 and 1.0. Defaults to 0.0.

contrast

Contrast gain, between 0.0 and 16.0. Defaults to 1.0.

saturation

Saturation gain, between 0.0 and 16.0. Defaults to 1.0.

hue

Hue shift in radians, between -3.14 and 3.14. Defaults to 0.0. This will rotate the UV subvector, defaulting to BT.709 coefficients for RGB inputs.

gamma

Gamma adjustment, between 0.0 and 16.0. Defaults to 1.0.

cones

Cone model to use for color blindness simulation. Accepts any combination of l, m and s. Here are some examples:

m

Deuteranomaly / deuteranopia (affecting 3%-4% of the population)

l

Protanomaly / protanopia (affecting 1%-2% of the population)

l+m

Monochromacy (very rare)

l+m+s

Achromatopsy (complete loss of daytime vision, extremely rare)

cone-strength

Gain factor for the cones specified by cones, between 0.0 and 10.0. A value of 1.0 results in no change to color vision. A value of 0.0 (the default) simulates complete loss of those cones. Values above 1.0 result in exaggerating the differences between cones, which may help compensate for reduced color vision.

To help deal with sources that only have static HDR10 metadata (or no tagging whatsoever), libplacebo uses its own internal frame analysis compute shader to analyze source frames and adapt the tone mapping function in realtime. If this is too slow, or if exactly reproducible frame-perfect results are needed, it’s recommended to turn this feature off.

peak_detect

Enable HDR peak detection. Ignores static MaxCLL/MaxFALL values in favor of dynamic detection from the input. Note that the detected values do not get written back to the output frames, they merely guide the internal tone mapping process. Enabled by default.

smoothing_period

Peak detection smoothing period, between 0.0 and 1000.0. Higher values result in peak detection becoming less responsive to changes in the input. Defaults to 100.0.

minimum_peak

Lower bound on the detected peak (relative to SDR white), between 0.0 and 100.0. Defaults to 1.0.

scene_threshold_low, scene_threshold_high

Lower and upper thresholds for scene change detection. Expressed in a logarithmic scale between 0.0 and 100.0. Default to 5.5 and 10.0, respectively. Setting either to a negative value disables this functionality.

overshoot

Peak smoothing overshoot margin, between 0.0 and 1.0. Provides a safety margin to prevent clipping as a result of peak smoothing. Defaults to 0.05, corresponding to a margin of 5%.

The options in this section control how libplacebo performs tone-mapping and gamut-mapping when dealing with mismatches between wide-gamut or HDR content. In general, libplacebo relies on accurate source tagging and mastering display gamut information to produce the best results.

intent

Rendering intent to use when adapting between different primary color gamuts (after tone-mapping).

perceptual

Perceptual gamut mapping. Currently equivalent to relative colorimetric.

relative

Relative colorimetric. This is the default.

absolute

Absolute colorimetric.

saturation

Saturation mapping. Forcibly stretches the source gamut to the target gamut.

gamut_mode

How to handle out-of-gamut colors that can occur as a result of colorimetric gamut mapping.

clip

Do nothing, simply clip out-of-range colors to the RGB volume. This is the default.

warn

Highlight out-of-gamut pixels (by coloring them pink).

darken

Linearly reduces content brightness to preserves saturated details, followed by clipping the remaining out-of-gamut colors. As the name implies, this makes everything darker, but provides a good balance between preserving details and colors.

desaturate

Hard-desaturates out-of-gamut colors towards white, while preserving the luminance. Has a tendency to shift colors.

tonemapping

Tone-mapping algorithm to use. Available values are:

auto

Automatic selection based on internal heuristics. This is the default.

clip

Performs no tone-mapping, just clips out-of-range colors. Retains perfect color accuracy for in-range colors but completely destroys out-of-range information. Does not perform any black point adaptation. Not configurable.

st2094-40

EETF from SMPTE ST 2094-40 Annex B, which applies the Bezier curves from HDR10+ dynamic metadata based on Bezier curves to perform tone-mapping. The OOTF used is adjusted based on the ratio between the targeted and actual display peak luminances.

st2094-10

EETF from SMPTE ST 2094-10 Annex B.2, which takes into account the input signal average luminance in addition to the maximum/minimum. The configurable contrast parameter influences the slope of the linear output segment, defaulting to 1.0 for no increase/decrease in contrast. Note that this does not currently include the subjective gain/offset/gamma controls defined in Annex B.3.

bt.2390

EETF from the ITU-R Report BT.2390, a hermite spline roll-off with linear segment. The knee point offset is configurable. Note that this parameter defaults to 1.0, rather than the value of 0.5 from the ITU-R spec.

bt.2446a

EETF from ITU-R Report BT.2446, method A. Designed for well-mastered HDR sources. Can be used for both forward and inverse tone mapping. Not configurable.

spline

Simple spline consisting of two polynomials, joined by a single pivot point. The parameter gives the pivot point (in PQ space), defaulting to 0.30. Can be used for both forward and inverse tone mapping.

reinhard

Simple non-linear, global tone mapping algorithm. The parameter specifies the local contrast coefficient at the display peak. Essentially, a parameter of 0.5 implies that the reference white will be about half as bright as when clipping. Defaults to 0.5, which results in the simplest formulation of this function.

mobius

Generalization of the reinhard tone mapping algorithm to support an additional linear slope near black. The tone mapping parameter indicates the trade-off between the linear section and the non-linear section. Essentially, for a given parameter x, every color value below x will be mapped linearly, while higher values get non-linearly tone-mapped. Values near 1.0 make this curve behave like clip, while values near 0.0 make this curve behave like reinhard. The default value is 0.3, which provides a good balance between colorimetric accuracy and preserving out-of-gamut details.

hable

Piece-wise, filmic tone-mapping algorithm developed by John Hable for use in Uncharted 2, inspired by a similar tone-mapping algorithm used by Kodak. Popularized by its use in video games with HDR rendering. Preserves both dark and bright details very well, but comes with the drawback of changing the average brightness quite significantly. This is sort of similar to reinhard with parameter 0.24.

gamma

Fits a gamma (power) function to transfer between the source and target color spaces, effectively resulting in a perceptual hard-knee joining two roughly linear sections. This preserves details at all scales fairly accurately, but can result in an image with a muted or dull appearance. The parameter is used as the cutoff point, defaulting to 0.5.

linear

Linearly stretches the input range to the output range, in PQ space. This will preserve all details accurately, but results in a significantly different average brightness. Can be used for inverse tone-mapping in addition to regular tone-mapping. The parameter can be used as an additional linear gain coefficient (defaulting to 1.0).

tonemapping_param

For tunable tone mapping functions, this parameter can be used to fine-tune the curve behavior. Refer to the documentation of tonemapping. The default value of 0.0 is replaced by the curve’s preferred default setting.

tonemapping_mode

This option determines how the tone mapping function specified by tonemapping is applied to the colors in a scene. Possible values are:

auto

Automatic selection based on internal heuristics. This is the default.

rgb

Apply the function per-channel in the RGB colorspace. Per-channel tone-mapping in RGB. Guarantees no clipping and heavily desaturates the output, but distorts the colors quite significantly. Very similar to the "Hollywood" look and feel.

max

Tone-mapping is performed on the brightest component found in the signal. Good at preserving details in highlights, but has a tendency to crush blacks.

hybrid

Tone-map per-channel for highlights and linearly (luma-based) for midtones/shadows, based on a fixed gamma 2.4 coefficient curve.

luma

Tone-map linearly on the luma component (CIE Y), and adjust (desaturate) the chromaticities to compensate using a simple constant factor. This is essentially the mode used in ITU-R BT.2446 method A.

inverse_tonemapping

If enabled, this filter will also attempt stretching SDR signals to fill HDR output color volumes. Disabled by default.

tonemapping_crosstalk

Extra tone-mapping crosstalk factor, between 0.0 and 0.3. This can help reduce issues tone-mapping certain bright spectral colors. Defaults to 0.04.

tonemapping_lut_size

Size of the tone-mapping LUT, between 2 and 1024. Defaults to 256. Note that this figure is squared when combined with peak_detect.

By default, libplacebo will dither whenever necessary, which includes rendering to any integer format below 16-bit precision. It’s recommended to always leave this on, since not doing so may result in visible banding in the output, even if the debanding filter is enabled. If maximum performance is needed, use ordered_fixed instead of disabling dithering.

dithering

Dithering method to use. Accepts the following values:

none

Disables dithering completely. May result in visible banding.

blue

Dither with pseudo-blue noise. This is the default.

ordered

Tunable ordered dither pattern.

ordered_fixed

Faster ordered dither with a fixed size of 6. Texture-less.

white

Dither with white noise. Texture-less.

dither_lut_size

Dither LUT size, as log base2 between 1 and 8. Defaults to 6, corresponding to a LUT size of 64x64.

dither_temporal

Enables temporal dithering. Disabled by default.

libplacebo supports a number of custom shaders based on the mpv .hook GLSL syntax. A collection of such shaders can be found here: https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders

A full description of the mpv shader format is beyond the scope of this section, but a summary can be found here: https://mpv.io/manual/master/#options-glsl-shader

custom_shader_path

Specifies a path to a custom shader file to load at runtime.

custom_shader_bin

Specifies a complete custom shader as a raw string.

All of the options in this section default off. They may be of assistance when attempting to squeeze the maximum performance at the cost of quality.

skip_aa

Disable anti-aliasing when downscaling.

polar_cutoff

Truncate polar (EWA) scaler kernels below this absolute magnitude, between 0.0 and 1.0.

disable_linear

Disable linear light scaling.

disable_builtin

Disable built-in GPU sampling (forces LUT).

force_icc_lut

Force the use of a full ICC 3DLUT for gamut mapping.

disable_fbos

Forcibly disable FBOs, resulting in loss of almost all functionality, but offering the maximum possible speed.

Commands

This filter supports almost all of the above options as commands.