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()
andvapoursynth.Format.replace()
. By default, outputsvapoursynth.FLOAT
sample type for 32-bit andvapoursynth.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. Acceptsvapoursynth.SampleType
enumsvapoursynth.INTEGER
andvapoursynth.FLOAT
or their values,0
and1
respectively.range (
Union
[int
,Range
,None
]) – Output pixel range (defaults to input clip’s range). SeeRange
.range_in (
Union
[int
,Range
,None
]) – Input pixel range (defaults to input clip’s range). SeeRange
.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 toDither.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-planevapoursynth.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.
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 beNone
.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¶
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'
) orNone
.
-
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, otherwiseFalse
.
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. Use32
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. SeeRange
.range (
Union
[int
,Range
,None
]) – Pixel range of the output value. No clamping is performed. SeeRange
.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 of16
to float, setting this toTrue
will return0.0
rather than0.073059...
)chroma (
bool
) – Whether or not to treat values as chroma instead of luma.
- Return type
Union
[int
,float
]- Returns
Scaled numeric value.
Enums¶
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.