Repository navigation
Tonemap
HDR tone and gamut mapping on the CPU, a port of vs-placebo's Tonemap.
vszip.Tonemap(
clip: vs.VideoNode,
src_csp: int = 1,
dst_csp: int = 0,
dst_prim: int | None = None,
src_max: float = 0,
src_min: float = 0,
dst_max: float = 0,
dst_min: float = 0,
dynamic_peak_detection: bool = True,
smoothing_period: float = 20.0,
scene_threshold_low: float = 1.0,
scene_threshold_high: float = 3.0,
percentile: float = 100.0,
black_cutoff: float = 1.0,
gamut_mapping: int = 1,
tone_mapping_function: int = 5,
tone_mapping_function_s: str | None = None,
tone_mapping_param: float = (per function),
metadata: int = 0,
use_dovi: bool = (src_csp == 3),
dovi_el: vs.VideoNode | None = None,
show_clipping: bool = False,
contrast_recovery: float = 0.0,
contrast_smoothness: float = 3.5,
lut_size: int = 256,
mastering_clip: float = 1.0,
film_strength: float = 0.3,
inverse_tone_mapping: bool = False,
knee_adaptation: float = 0.4,
knee_minimum: float = 0.1,
knee_maximum: float = 0.8,
knee_default: float = 0.4,
knee_offset: float = 1.0,
slope_tuning: float = 1.5,
slope_offset: float = 0.2,
spline_contrast: float = 0.5,
reinhard_contrast: float = 0.5,
linear_knee: float = 0.3,
exposure: float = 1.0,
gamut_expansion: bool = False,
lut3d_size: Sequence[int] = (48, 32, 256),
lut3d_tricubic: bool = False,
perceptual_deadzone: float = 0.3,
perceptual_strength: float = 0.8,
colorimetric_gamma: float = 1.8,
softclip_knee: float = 0.7,
softclip_desat: float = 0.35,
cache_frame: bool = True,
)Coming from vs-placebo:
- Shared arguments keep vs-placebo's names and defaults.
- The positional layout differs. vszip inserts
black_cutoffafterpercentileand has novisualize_lutorlog_level. A positional call can therefore bind a different argument without failing. - So convert positional arguments to keywords before replacing
core.placebo.Tonemapwithcore.vszip.Tonemap.
See also Differences from vs-placebo.
# HDR10 -> SDR BT.709
sdr = clip.vszip.Tonemap(src_csp=1, dst_csp=0)
# Dolby Vision (profile 5/8, or the base layer of 4/7): every frame must
# carry the DolbyVisionRPU frame prop. Use BestSource R22 or newer (see the
# note below)
src = core.bs.VideoSource("dv.mkv")
sdr = src.vszip.Tonemap(src_csp=3)
# Dolby Vision with its FEL enhancement layer as a second clip of the same
# frames: the RPUs are then read from the EL clip
bl = core.bs.VideoSource("bl.hevc")
el = core.bs.VideoSource("el.hevc")
sdr = bl.vszip.Tonemap(src_csp=3, dovi_el=el)
# by name instead of number
sdr = clip.vszip.Tonemap(tone_mapping_function_s="bt2390", gamut_mapping=0)Source filter for Dolby Vision. Use BestSource R22 or newer (pip install -U vapoursynth-bestsource). Both BestSource and FFMS2 export DolbyVisionRPU, but only R22 got every frame right in testing. Tested against the RPU NAL units in the streams themselves:
- BestSource R22 attached each frame its own RPU on every tested file (MP4, MKV, raw HEVC), in any access order.
- FFMS2 5.2.1 (the latest on PyPI) gets some MP4s wrong. On Dolby's Sol Levante MP4s (profiles 5, 8.1 and 8.4) it gives one frame per 48 (45, 93, 141, …) the previous frame's RPU, losing 86–125 of each file's distinct RPUs. With random access it sometimes gets them right, so the result depends on access order. No error is raised; those frames just decode with their neighbour's metadata. MKV files were correct.
- BestSource R18 and older dropped the prop on those same frames instead. A frame without its RPU fails Dolby Vision processing; with peak detection on, so does any later frame whose detection window reaches it.
-
Formats. Input is RGB or YUV (4:4:4, 4:2:2, 4:2:0, 4:4:0):
- HDR10/HLG: 9..16-bit integer or 32-bit float;
- Dolby Vision (
src_csp=3) and its EL: 9..16-bit integer YUV only.
Output is RGB48/YUV444P16 for integer input, RGBS/YUV444PS for float input.
-
Integer depths below 16 bit.
-
Limited range: read as if shifted to 16 bit, bit-identical to converting the clip with
resize.Pointfirst (what vs-placebo needs). -
Full-range HDR10/HLG: BT.2100 full-range scaling to 16 bit (luma × 65535 / (2^bits − 1), chroma likewise around mid-grey), unrounded. That stays within
resize.Point's rounding, but is not a plain shift. - Dolby Vision: reads code / 2^bits, the RPU's own scale. For a full-range base layer (profile 5), pass the native depth: a 16-bit conversion rescales the codes instead of shifting them.
-
Limited range: read as if shifted to 16 bit, bit-identical to converting the clip with
-
YUV matrix. YUV input is decoded as BT.2020 NCL, as vs-placebo does.
-
Frame props read:
-
_Range(or_ColorRange) and_ChromaLocation; -
ContentLightLevelMax,ContentLightLevelAverage; -
MasteringDisplayMinLuminance,MasteringDisplayMaxLuminance; -
MasteringDisplayPrimariesX,MasteringDisplayPrimariesY; -
MasteringDisplayWhitePointX,MasteringDisplayWhitePointY; -
PLSceneMax,PLSceneAvg, in nits: a 1-valuePLSceneMaxis CIE Y, a 3-value one is HDR10+.
Without mastering primaries, Display P3 is assumed, as in vs-placebo.
-
-
Frame props written.
_Matrix,_Transfer,_Primariesand_Rangeare set for the target, and_ChromaLocationis removed. -
Chroma. Subsampled chroma is upsampled with lanczos, honoring
_ChromaLocation. -
DolbyVisionRPUmetadata applies whateversrc_cspis, as in vs-placebo. When the prop is present and valid:- Source peak: the RPU's source maximum replaces the props' mastering peak. Compressed DM data carries no range, so the props' value is kept.
-
Source black: the RPU's source minimum replaces the props' too, except for compressed DM data. For Dolby Vision to HDR10 (
src_csp=3, dst_csp=1), the target black is set to the source black instead. - L1 supplies the scene's CIE Y peak and average.
- L6 supplies MaxCLL/MaxFALL when either is missing from the props.
-
Errors: with
src_csp=3a missing or invalid RPU is an error. With other values an invalid RPU is ignored.
-
Partial Dolby Vision RPUs (
use_prev, without DM data, or with compressed DM data) continue the last complete RPU at or before them, in frame order. That reconstruction walks back at most 300 frames: a longer chain without a complete RPU raises an error, with peak detection on or off. -
Peak detection is deterministic. Frame
nreplays the detection over a fixed window of earlier frames (5 ×smoothing_period, at most 300 frames). The result doesn't depend on request order, seeking or thread count. Requesting framenalso fetches the earlier window frames that aren't measured yet.
-
clip:
Input clip. -
src_csp (int, default: 1):
Source color space. There is no SDR source mode.-
1: HDR10 (PQ, BT.2020) -
2: HLG (BT.2020) -
3: Dolby Vision (needs theDolbyVisionRPUframe prop)
-
-
dst_csp (int, default: 0):
Target color space.-
0: SDR (BT.1886, BT.709 primaries) -
1: HDR10 (PQ, BT.2020) -
2: HLG (BT.2020)
Dolby Vision output (
3) is not supported, as in vs-placebo. -
-
dst_prim (int, default: the target's own primaries):
Target primaries, as libplacebo'spl_color_primaries:Value Primaries Value Primaries 0unknown 9ProPhoto 1BT.601 525 10CIE 1931 2BT.601 625 11DCI-P3 3BT.709 12Display P3 4BT.470 M 13V-Gamut 5EBU 3213 14S-Gamut 6BT.2020 15Film C 7Apple 16ACES AP0 8Adobe 17ACES AP1 -
src_max, src_min (float, default: 0, range: 0..10000):
Source peak and black in nits.0takes them from the frame props or metadata. -
dst_max, dst_min (float, default: 0, range: 0..10000):
Target peak and black in nits.0uses the target's nominal values (SDR: 203 nits). -
dynamic_peak_detection (bool, default: True):
Measure each frame's brightness.- Which fields it fills: only the dynamic metadata fields the source leaves empty, field by field. Authored values win.
-
When it doesn't run:
- the target peak is at least the source transfer's nominal peak (10000 nits for PQ, so for example HDR10 →
dst_csp=1with the defaultdst_max; for HLG, the source's peak); -
metadatais1,2or3; - the source carries both HDR10+ and CIE Y metadata.
- the target peak is at least the source transfer's nominal peak (10000 nits for PQ, so for example HDR10 →
-
smoothing_period (float, default: 20, range: 0..60):
Time constant of the peak detection's smoothing, in frames.0disables smoothing.
vs-placebo accepts any value. vszip stops at 60 so that the replay window (5 periods) fits 300 frames. -
scene_threshold_low, scene_threshold_high (float, default: 1, 3, range: 0..100):
Scene-change thresholds in units of 1% PQ. Between them, the smoothing is progressively reset. Either one at0disables scene-change detection. -
percentile (float, default: 100, range: 0..100):
Brightness percentile used as the measured peak. Values strictly between 0 and 100 use a histogram percentile, which ignores a few very bright pixels. Both0and100use the true maximum. -
black_cutoff (float, default: 1, range: 0..100):
Smoothly suppresses near-black pixels, up to this PQ level in percent, in peak detection's averages. It also keeps black bars out of the measurement.0disables it. vszip only; libplacebo's default (upstream description). -
gamut_mapping (int, default: 1):
Gamut mapping function.-
0: clip -
1: perceptual -
2: softclip -
3: relative -
4: saturation -
5: absolute -
6: desaturate -
7: darken -
8: highlight (out-of-gamut colors shown as a mask) -
9: linear
-
-
tone_mapping_function (int, default: 5):
Tone mapping curve.Value Function Value Function 0clip 6reinhard 1st2094-40 7mobius 2st2094-10 8hable 3bt2390 9gamma 4bt2446a 10linear 5spline 11linearlight -
tone_mapping_function_s (string):
The same curve by name ("clip","st2094-40","st2094-10","bt2390","bt2446a","spline","reinhard","mobius","hable","gamma","linear","linearlight"). It overridestone_mapping_function. -
tone_mapping_param (float, range: 0..10):
The curve's tuning parameter. A nonzero value overrides the function's own constant.0leaves that constant unchanged; it does not set it to zero.Function Constant it sets Default st2094-40/10 knee_adaptation0.7 bt2390 knee_offset1.0 spline spline_contrast0.5 reinhard reinhard_contrast0.5 mobius, gamma linear_knee0.3 linear, linearlight exposure1.0 How the value is chosen:
- Neither argument passed: the defaults in this table apply, as in vs-placebo.
- Only the constant passed: your constant is used (the implicit default above is not applied).
-
Nonzero
tone_mapping_parampassed: it wins over an explicit constant.
-
metadata (int, default: 0):
Which source metadata selects the tone curve's input range.-
0: any (the best available) -
1: none. Source luminance metadata, including manualsrc_max/src_min, is ignored for the tone range; the transfer's nominal bounds are used. Use2to tone map from static mastering or manual source luminance. -
2: HDR10 (static mastering metadata, andsrc_max/src_min) -
3: HDR10+ (dynamic scene metadata) -
4: CIE Y (dynamic luminance metadata, also from peak detection)
-
-
use_dovi (bool, default:
src_csp == 3):
Whether to usedovi_el. Without it,dovi_elis ignored, as in vs-placebo. -
dovi_el (clip):
The Dolby Vision FEL enhancement layer, composed with the base layer when the RPU signals a FEL (a MEL changes nothing).- Format: 9..16-bit integer YUV (4:2:0, 4:2:2, 4:4:0 or 4:4:4).
- Size: the base layer's size, or half of it in either or both dimensions.
-
Frames: the same frames as
clip. -
RPU source: with an EL the
DolbyVisionRPUprops are read from this clip, as vs-placebo does.
-
show_clipping (bool, default: False):
Highlight pixels that the tone or gamut mapping clipped. -
contrast_recovery (float, default: 0, range: 0..10):
Re-adds high-frequency detail lost by tone mapping.0disables it; libplacebo's high-quality preset uses0.3. -
contrast_smoothness (float, default: 3.5, range: 1..32):
Downscale factor of the low-frequency image that contrast recovery compares against. vszip only. -
lut_size (int, default: 256, range: 2..4096):
Size of the tone curve LUT (for curves evaluated through a LUT). vszip only. -
mastering_clip (float, default: 1, range: 0..1):
Strength of the soft clip of channels above the mastering display's peak. It fades out when the measured brightness exceeds the mastering peak. vszip only. -
film_strength (float, default: 0.3, range: 0..2):
Strength of the film-like hue/saturation response in the tone stage. vszip only. -
inverse_tone_mapping (bool, default: False):
Let a supported HDR source expand toward a brighter target, instead of capping the mapping at the source's range. vszip only.- It needs an invertible curve: clip, bt2446a, spline, linear or linearlight. With the others the output still stops at the source peak.
- It does not add an SDR source mode:
src_cspstays HDR10, HLG or Dolby Vision.
-
knee_adaptation, knee_minimum, knee_maximum, knee_default, knee_offset, slope_tuning, slope_offset, spline_contrast, reinhard_contrast, linear_knee, exposure (float):
libplacebo'spl_tone_map_constants, with libplacebo's defaults and ranges. vszip only. See libplacebo's tone-mapping constants:Constant Default Range knee_adaptation0.4 0..1 knee_minimum0.1 0..0.5 knee_maximum0.8 0.5..1 knee_default0.4 0..1 knee_offset1.0 0.5..2 slope_tuning1.5 0..10 slope_offset0.2 0..1 spline_contrast0.5 0..1.5 reinhard_contrast0.5 0..1 linear_knee0.3 0..1 exposure1.0 0..10 -
gamut_expansion (bool, default: False):
Let the perceptual and saturation functions expand colors into a wider target gamut. vszip only. -
lut3d_size (int[3], default: (48, 32, 256)):
Size of the gamut-mapping 3D LUT along intensity, chroma and hue. vszip only.- Each value is
0(keep the default) or 2..1024. - The product is at most 16777216 (the LUT is 16 bytes per entry).
- Each value is
-
lut3d_tricubic (bool, default: False):
Sample the 3D LUT with a cubic B-spline instead of trilinearly. It smooths the LUT, so the output changes noticeably. vszip only.
Measured example: 1080p HDR10 → SDR on a Ryzen 7 5700X3D went from 20.1 to 9.4 fps at 1 thread. -
perceptual_deadzone, perceptual_strength, colorimetric_gamma, softclip_knee, softclip_desat (float):
libplacebo'spl_gamut_map_constants. vszip only:Constant Default Range perceptual_deadzone0.3 0..1 perceptual_strength0.8 0..1 colorimetric_gamma1.8 0..10 softclip_knee0.7 0..1 softclip_desat0.35 0..1 -
cache_frame (bool, default: True):
Speed/memory trade-off; the output is identical either way. vszip only.-
What it does. Peak detection and contrast recovery have to decode each frame to linear light before the output pass starts. With
cache_frame, that decoded frame is kept for the output pass instead of being decoded a second time. -
Speed (measured example). 3840x2160 YUV420P16 → SDR (Sol Levante profile 8.4, also as HDR10), Ryzen 7 5700X3D, 1 and 16 threads:
- with detection: 12–19% faster;
- with detection and
contrast_recovery=0.3: 14–28% faster.
-
Memory. Each frame being processed needs 12 bytes per pixel: about 25 MB at 1080p and 100 MB at 4K.
- How long it's held. The buffers are pooled and reused. The pool grows to the largest number of frames processed at once and keeps them until the filter is freed. There is no cap.
- Measured. At 4K with 16 threads, peak RAM went from 2.95 to 4.43 GiB.
-
When to set it to
False. If memory is tight. With detection off and no contrast recovery, the argument has no effect and allocates nothing.
-
What it does. Peak detection and contrast recovery have to decode each frame to linear light before the output pass starts. With
-
Not available.
-
visualize_lut(debug overlay). -
log_level(vszip has no libplacebo to log).
-
-
Extra arguments. All the remaining
pl_color_map_params/pl_peak_detect_paramsfields that change the output (listed above as "vszip only"), pluscache_frame. -
Positional layout. It differs (see Usage); pass arguments by keyword.
-
Input formats. vs-placebo takes 16-bit integer input only.
- HDR10/HLG accept 9..16-bit integer or 32-bit float.
- Dolby Vision and its EL accept 9..16-bit integer YUV; float is not supported for either.
-
Precision. vszip computes in f32 throughout and doesn't emulate the GPU's lower-precision steps:
- half-float intermediate textures (most visible on 4:2:0 chroma, with peak detection on very bright frames, and on the FEL);
- the 16-bit gamut LUT;
- output dithering (vszip rounds the 16-bit output).
On the test material the average difference was 0.2–7 16-bit codes. That is not a maximum: single pixels can differ much more. Examples are a peak-detection bias of 30–40 codes on very bright frames, and saturated pixels at a steep spot of clip gamut mapping, where vs-placebo's own output jumps by thousands of codes for a tiny input change.
-
Deterministic results. Peak detection and partial Dolby Vision RPUs are resolved in frame order. Results don't depend on request order, seeking or threads. vs-placebo updates one shared state in request order.
-
Peak detection replays a finite window (see
smoothing_period). vs-placebo's state keeps its whole history, so results agree closely but not exactly even in sequential playback. - Partial RPU chains stop at 300 frames (see Notes).
-
Peak detection replays a finite window (see
-
Compressed Dolby Vision DM data keeps the previous frame's matrices. vs-placebo decodes those frames black.
-
smoothing_periodis limited to 0..60. -
Speed (measured example). 3840x2160 YUV420P16 Dolby Vision (Sol Levante profile 8.4) → SDR, vszip on a Ryzen 7 5700X3D against vs-placebo on an RTX 3070 Ti:
Detection vszip, 16 threads vszip, 1 thread vs-placebo off ~50 fps ~6 fps ~25–29 fps on ~42 fps ~5 fps ~25–26 fps vszip scales with CPU threads. vs-placebo runs on the GPU and doesn't scale with VapourSynth threads.