API Reference

VSUtil. A collection of general-purpose VapourSynth functions to be reused in modules and scripts.

Functions that return a clip

vsutil.depth(clip, bitdepth, sample_type=None, *, range=None, range_in=None, dither_type=None)[source]

A bit depth converter only using vapoursynth.core.resize() and vapoursynth.Format.replace(). By default, outputs vapoursynth.FLOAT sample type for 32-bit and vapoursynth.INTEGER for anything else.

>>> src_8 = vs.core.std.BlankClip(format=vs.YUV420P8)
>>> src_10 = depth(src_8, 10)
>>> src_10.format.name
'YUV420P10'
>>> src2_10 = vs.core.std.BlankClip(format=vs.RGB30)
>>> src2_8 = depth(src2_10, 8, dither_type=Dither.RANDOM)  # override default dither behavior
>>> src2_8.format.name
'RGB24'
Parameters
  • clip (VideoNode) – Input clip.

  • bitdepth (int) – Desired bits_per_sample of output clip.

  • sample_type (Union[int, SampleType, None]) – Desired sample_type of output clip. Allows overriding default float/integer behavior. Accepts vapoursynth.SampleType enums vapoursynth.INTEGER and vapoursynth.FLOAT or their values, 0 and 1 respectively.

  • range (Union[int, Range, None]) – Output pixel range (defaults to input clip’s range). See Range.

  • range_in (Union[int, Range, None]) – Input pixel range (defaults to input clip’s range). See Range.

  • dither_type (Union[Dither, str, None]) –

    Dithering algorithm. Allows overriding default dithering behavior. See Dither.

    Defaults to Dither.ERROR_DIFFUSION, or Floyd-Steinberg error diffusion, when downsampling, converting between ranges, or upsampling full range input. Defaults to Dither.NONE, or round to nearest, otherwise. See _should_dither() comments for more information.

Return type

VideoNode

Returns

Converted clip with desired bit depth and sample type. ColorFamily will be same as input.

vsutil.frame2clip(frame, *, enforce_cache=True)[source]

Converts a VapourSynth frame to a clip.

Parameters
  • frame (VideoFrame) – The frame to convert.

  • enforce_cache – Forcibly add a cache, even if the vapoursynth module has this feature disabled.

Return type

VideoNode

Returns

A one-frame clip that yields the frame passed to the function.

vsutil.get_y(clip)[source]

Helper to get the luma plane of a clip.

If passed a single-plane vapoursynth.GRAY clip, plane() will assume it to be the luma plane itself and returns the clip (no-op).

Parameters

clip (VideoNode) – Input clip.

Return type

VideoNode

Returns

Luma plane of the input clip. Will return the input clip if it is a single-plane grayscale clip.

vsutil.insert_clip(clip, insert, start_frame)[source]

Convenience method to insert a shorter clip into a longer one.

The insert clip cannot go beyond the last frame of the source clip or an exception is raised. The insert clip frames replace the clip frames, unlike a normal splice-in.

Parameters
  • clip (VideoNode) – Longer clip to insert shorter clip into.

  • insert (VideoNode) – Insert clip.

  • start_frame (int) – First frame of the longer clip to replace.

Return type

VideoNode

Returns

Longer clip with frames replaced by the shorter clip.

vsutil.join(planes, family=vapoursynth.YUV)[source]

Joins the supplied list of planes into a three-plane VideoNode (defaults to YUV).

>>> planes = [Y, U, V]
>>> clip = join(planes)
Parameters
  • planes (List[VideoNode]) – List of 3 one-plane vapoursynth.GRAY clips to merge.

  • family (ColorFamily) – Output color family. Must be a three-plane color family.

Return type

VideoNode

Returns

Three-plane clip of the supplied planes.

vsutil.plane(clip, planeno)[source]

Extracts the plane with the given index from the input clip.

If given a one-plane clip and planeno=0, returns clip (no-op).

>>> src = vs.core.std.BlankClip(format=vs.YUV420P8)
>>> V = plane(src, 2)
Parameters
  • clip (VideoNode) – The clip to extract the plane from.

  • planeno (int) – The index of which plane to extract.

Return type

VideoNode

Returns

A grayscale clip that only contains the given plane.

vsutil.split(clip)[source]

Returns a list of planes (VideoNodes) from the given input clip.

>>> src = vs.core.std.BlankClip(format=vs.RGB27)
>>> R, G, B  = split(src)
Parameters

clip (VideoNode) – Input clip.

Return type

List[VideoNode]

Returns

List of planes from the input clip.

Miscellanious non-VapourSynth functions

vsutil.fallback(value, fallback_value)[source]

Utility function that returns a value or a fallback if the value is None.

>>> fallback(5, 6)
5
>>> fallback(None, 6)
6
Parameters
  • value (Optional[~T]) – Argument that can be None.

  • fallback_value (~T) – Fallback value that is returned if value is None.

Return type

~T

Returns

The input value or fallback_value if value is None.

vsutil.iterate(base, function, count)[source]

Utility function that executes a given function a given number of times.

>>> def double(x):
...     return x * 2
...
>>> iterate(5, double, 2)
20
Parameters
  • base (~T) – Initial value.

  • function (Callable[[Union[~T, ~R]], ~R]) – Function to execute.

  • count (int) – Number of times to execute function.

Return type

Union[~T, ~R]

Returns

function’s output after repeating count number of times.

Decorators

vsutil.disallow_variable_format(function)[source]

Function decorator that raises an exception if the input clip has a variable format.

Decorated function’s first parameter must be of type vapoursynth.VideoNode and is the only parameter checked.

Return type

~F

vsutil.disallow_variable_resolution(function)[source]

Function decorator that raises an exception if the input clip has a variable resolution.

Decorated function’s first parameter must be of type vapoursynth.VideoNode and is the only parameter checked.

Return type

~F

Clip information and helper functions

Helpers to inspect a clip/frame

vsutil.get_depth(clip)[source]

Returns the bit depth of a VideoNode as an integer.

>>> src = vs.core.std.BlankClip(format=vs.YUV420P10)
>>> get_depth(src)
10
Parameters

clip (VideoNode) – Input clip.

Return type

int

Returns

Bit depth of the input clip.

vsutil.get_plane_size(frame, planeno)[source]

Calculates the dimensions (width, height) of the desired plane.

>>> src = vs.core.std.BlankClip(width=1920, height=1080, format=vs.YUV420P8)
>>> get_plane_size(src, 0)
(1920, 1080)
>>> get_plane_size(src, 1)
(960, 540)
Parameters
  • frame (Union[VideoFrame, VideoNode]) – Can be a clip or frame.

  • planeno (int) – The desired plane’s index.

Return type

Tuple[int, int]

Returns

Tuple of width and height of the desired plane.

vsutil.get_subsampling(clip)[source]

Returns the subsampling of a VideoNode in human-readable format. Returns None for formats without subsampling.

>>> src1 = vs.core.std.BlankClip(format=vs.YUV420P8)
>>> get_subsampling(src1)
'420'
>>> src_rgb = vs.core.std.BlankClip(format=vs.RGB30)
>>> get_subsampling(src_rgb) is None
True
Parameters

clip (VideoNode) – Input clip.

Return type

Optional[str]

Returns

Subsampling of the input clip as a string (i.e. '420') or None.

vsutil.is_image(filename)[source]

Returns True if the filename refers to an image.

Parameters

filename (str) – String representing a path to a file.

Return type

bool

Returns

True if the filename is a path to an image file, otherwise False.


Mathematical helpers

vsutil.get_w(height, aspect_ratio=1.7777777777777777, *, only_even=True)[source]

Calculates the width for a clip with the given height and aspect ratio.

>>> get_w(720)
1280
>>> get_w(480)
854
Parameters
  • height (int) – Input height.

  • aspect_ratio (float) – Aspect ratio for the calculation. (Default: 16/9)

  • only_even (bool) – Will return the nearest even integer. True by default because it imitates the math behind most standard resolutions (e.g. 854x480).

Return type

int

Returns

Calculated width based on input height.

vsutil.scale_value(value, input_depth, output_depth, range_in=0, range=None, scale_offsets=False, chroma=False)[source]

Scales a given numeric value between bit depths, sample types, and/or ranges.

>>> scale_value(16, 8, 32, range_in=Range.LIMITED)
0.0730593607305936
>>> scale_value(16, 8, 32, range_in=Range.LIMITED, scale_offsets=True)
0.0
>>> scale_value(16, 8, 32, range_in=Range.LIMITED, scale_offsets=True, chroma=True)
-0.5
Parameters
  • value (Union[int, float]) – Numeric value to be scaled.

  • input_depth (int) – Bit depth of the value parameter. Use 32 for float sample type.

  • output_depth (int) – Bit depth to scale the input value to.

  • range_in (Union[int, Range]) – Pixel range of the input value. No clamping is performed. See Range.

  • range (Union[int, Range, None]) – Pixel range of the output value. No clamping is performed. See Range.

  • scale_offsets (bool) – Whether or not to apply YUV offsets to float chroma and/or TV range integer values. (When scaling a TV range value of 16 to float, setting this to True will return 0.0 rather than 0.073059...)

  • chroma (bool) – Whether or not to treat values as chroma instead of luma.

Return type

Union[int, float]

Returns

Scaled numeric value.

Enums

class vsutil.Dither[source]

Enum for zimg_dither_type_e.

ERROR_DIFFUSION = 'error_diffusion'

Floyd-Steinberg error diffusion.

NONE = 'none'

Round to nearest.

ORDERED = 'ordered'

Bayer patterned dither.

RANDOM = 'random'

Pseudo-random noise of magnitude 0.5.

class vsutil.Range[source]

Enum for zimg_pixel_range_e.

FULL = 1

Full (PC) dynamic range, 0-255 in 8 bits.

LIMITED = 0

Studio (TV) legal range, 16-235 in 8 bits.