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=[])[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.