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 sequence of planes into a single VideoNode (defaults to YUV).

>>> planes = [Y, U, V]
>>> clip_YUV = join(planes)
>>> plane = core.std.BlankClip(format=vs.GRAY8)
>>> clip_GRAY = join([plane], family=vs.GRAY)

Parameters

planes (Sequence[VideoNode]) – Sequence of one-plane vapoursynth.GRAY clips to merge.
family (ColorFamily) – Output color family.

Return type

VideoNode

Returns

Merged 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)
>>> src2 = vs.core.std.BlankClip(format=vs.GRAY8)
>>> split(src2)
[<vapoursynth.VideoNode object>]  # always returns a list, even if single plane

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[TypeVar(T)]) – Argument that can be None.
fallback_value (TypeVar(T)) – Fallback value that is returned if value is None.

Return type

TypeVar(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 (TypeVar(T)) – Initial value.
function (Callable[[Union[TypeVar(T), TypeVar(R)]], TypeVar(R)]) – Function to execute.
count (int) – Number of times to execute function.

Return type

Union[TypeVar(T), TypeVar(R)]

Returns

function’s output after repeating count number of times.

vsutil.resolve_enum(enum, value, var_name, fn=None)[source]¶

Attempts to evaluate value in enum if value is not None, otherwise returns None.

>>> def my_fn(family: Optional[int]):
...     return resolve_enum(vs.ColorFamily, family, 'family', my_fn)
>>> my_fn(None)
None
>>> my_fn(3)
<ColorFamily.YUV: 3>
>>> my_fn(9)
ValueError: my_fn: family must be in <vapoursynth.UNDEFINED: 0>, <vapoursynth.GRAY: 1>, ...

Parameters

enum (Type[TypeVar(E, bound= Enum)]) – Enumeration, i.e. vapoursynth.ColorFamily.
value (Any) – Value to check. Can be None.
var_name (str) – User-provided parameter name that needs to be checked.
fn (Optional[Callable]) – Function that should be causing the exception (used for error message only).

Return type

Optional[TypeVar(E, bound= Enum)]

Returns

The enum member or None.

Decorators¶

vsutil.disallow_variable_format(*, only_first: bool = 'False') → Callable[[vsutil.func.F], vsutil.func.F][source]¶

vsutil.disallow_variable_format(function: F | None = None, /) → vsutil.func.F

Function decorator that raises an exception if input clips have variable format. :type function: F | None :param function: Function to wrap. :type only_first: bool :param only_first: Whether to check only the first argument or not.

Return type: Callable[[F], F] | F
Returns: Wrapped function.

vsutil.disallow_variable_resolution(*, only_first: bool = 'False') → Callable[[vsutil.func.F], vsutil.func.F][source]¶

vsutil.disallow_variable_resolution(function: F | None = None, /) → vsutil.func.F

Function decorator that raises an exception if input clips have variable resolution. :type function: F | None :param function: Function to wrap. :type only_first: bool :param only_first: Whether to check only the first argument or not.

Return type: Callable[[F], F] | F
Returns: Wrapped function.

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_lowest_value(clip, chroma=False)[source]¶

Returns the lowest possible value for the combination of the plane type and bit depth/type of the clip as float.

Parameters

clip (VideoNode) – Input clip.
chroma (bool) – Whether to get luma (default) or chroma plane value.

Return type

float

Returns

Lowest possible value.

vsutil.get_neutral_value(clip, chroma=False)[source]¶

Returns the neutral value for the combination of the plane type and bit depth/type of the clip as float.

Parameters

clip (VideoNode) – Input clip.
chroma (bool) – Whether to get luma (default) or chroma plane value.

Return type

float

Returns

Neutral value.

vsutil.get_peak_value(clip, chroma=False)[source]¶

Returns the highest possible value for the combination of the plane type and bit depth/type of the clip as float.

Parameters

clip (VideoNode) – Input clip.
chroma (bool) – Whether to get luma (default) or chroma plane value.

Return type

float

Returns

Highest possible value.

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(value)[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(value)[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.

Other¶

vsutil.EXPR_VARS: str = 'xyzabcdefghijklmnopqrstuvw'¶

This constant contains a list of all variables that can appear inside an expr-string ordered by assignment. So the first clip will have the name EXPR_VARS[0], the second one will have the name EXPR_VARS[1], and so on.

This can be used to automatically generate expr-strings.