Vapoursynth AutoLevels

From wiki.selur.net
Revision as of 19:35, 14 November 2026 by Selur (talk | contribs) (Remove background without information (via update-page on MediaWiki MCP Server))
Jump to navigation Jump to search

AutoLevels sets levels and gamma automatically. It measures the luma of the surrounding frames, averages the measurements and stops averaging at scene changes, so the brightness does not jump from frame to frame as with a per-frame auto gain.

Filtering → Vapoursynth → Color → Auto

AutoLevels controls in Hybrid
AutoLevels controls in Hybrid

What it does

For each frame the minimum, maximum and mean luma of the frames within Radius are averaged. The measured luma range is stretched to the output levels (Auto level), and optionally a gamma correction is added (Auto gamma or a fixed Gamma). Fade protection keeps fades to or from black from being stretched to full contrast.

Settings

Control Parameter Range Hybrid default Meaning
Radius filterRadius 0 – 60 7 Frames before and after the current one that are averaged; 0 = current frame only.
Scene change sceneChgThresh 0 – 255 20 A scene starts when min or max luma change by at least this value, or the mean by half of it; 255 = off.
2nd test (th/%) sc2th / sc2Perc 0 – 256 / 0 – 99.99 12 / 33.33 A cut is only accepted when more than this percentage of pixels differ by more than th; th = 256 switches the test off.
Auto level autolevel on/off on Stretches the measured range to the output levels.
Auto gamma autogamma on/off off Estimates the gamma from the mean luma.
Gamma gamma 0.1 – 10 1.00 Manual gamma after the stretch (without Auto gamma).
Midpoint midpoint 0.01 – 0.99 0.50 Mean brightness auto gamma aims for (about 0.4 often looks nicer). With Auto gamma.
Gammax / Gammin gammax / gammin 1 – 10 / 0.1 – 1 1.50 / 0.67 (off) Upper and lower limit of the auto gamma; without Gammin the lower limit is 1/Gammax.
Fixed input (low/high) input_low / input_high 0 – 255 off (16 / 235) Uses fixed black and white points instead of the measured ones.
Fixed output (low/high) output_low / output_high 0 – 254 / 1 – 255 off (16 / 235) Fixed output levels; without them the plugin uses 16/235 for limited-range YUV and 0/255 for RGB and full-range YUV.
Coring coring on/off off Expands 16–235 to 0–255 before the mapping and back after it. Needs limited-range input; Hybrid converts full-range YUV to limited range before the filter and back afterwards.
Ignore (low/high) ignore_low / ignore_high 0 – 0.45 0.001953 / 0.001953 Share of the darkest/brightest pixels left out of the measurement.
Border (l/r/t/b) border_l / _r / _t / _b 0 – 4096 0 Edge bands left out of the measurement (the whole picture is still processed).
Fade protection minRng on/off, 64 – 128 on, 100 Below this luma range all corrections are reduced in proportion.
Debug debug on/off off Draws the per-frame statistics into the picture.
Frame overrides frameOverrides text – Manual corrections, separated by commas or spaces: S<n> or S<a-b> forces a scene start, N forces no scene start, E leaves frames unchanged, e.g. E8400-8405,S62908,N8527-8540.

The level values are always entered on the 8-bit scale; the plugin scales them to the clip's bit depth. Low always stays below high, for the fixed input and the fixed output levels: moving one value past the other pushes the other along.

Example

Auto gamma on, everything else at the defaults, on a 10-bit YUV 4:2:0 source:

# adjusting levels and gamma using AutoLevels
clip = core.autolevels.AutoLevels(clip, autogamma=True)

How Hybrid calls it

  • AutoLevels works on integer YUV, gray and RGB with 8–16 bit; float clips are converted first.
  • Only values that differ from the defaults are written, so a filter at its defaults is just AutoLevels(clip). Gamma is only written without Auto gamma, the gamma limits only with it; fixed levels only when their check box is on. Without Fade protection Hybrid writes minRng=0.
  • The source range is read by the plugin from the frame properties; Hybrid passes no range parameter.
  • Frame overrides count the frames of the clip after cutting, at the frame rate AutoLevels sees. Invalid entries are left out and named in a script comment. In chunked encodes Hybrid moves the numbers into each chunk's own numbering.
  • AutoLevels also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

AutoLevels (plugin)

AutoLevels 1.1.0 is a port of the AviSynth plugin AutoLevels v0.12 Beta 3 (Anschütz, Battle, StainlessS), as one native plugin for VapourSynth and AviSynth+. Besides AutoLevels() it has AutoGamma(), which only changes the defaults (auto gamma on, auto level off). For RGB the luma is measured with Rec.601 weights and the curve applied to R, G and B; for YUV the chroma is scaled around neutral by the luma gain. At 8 bit the output is bit-identical to the original. Compared with the original it copies alpha, uses 0/255 as defaults for full range and needs AviSynth+ or VapourSynth R55+.

AviSynth

The same plugin is available in AviSynth+ and in Hybrid's AviSynth filters, see Avisynth AutoLevels. AviSynth's core filter Levels only does manual level changes.

Sources