lvsfunc.util

Helper functions for module functions and wrapper. Some of these may also be useful for regular scripting or other modules.

`lvsfunc.util.allow_variable`([width, height, ...])	Decorator allowing a variable-res and/or variable-format clip to be passed to a function that otherwise would not be able to accept it.
`lvsfunc.util.check_variable`(clip, function)	Check for variable format and a variable resolution, and return an error if found.
`lvsfunc.util.chroma_injector`(func)	Decorator allowing injection of reference chroma into a function which would normally only receive luma, such as an upscaler passed to `lvsfunc.scale.descale()`.
`lvsfunc.util.clamp_values`(x, max_val, min_val)	Forcibly clamps the given value x to a max and/or min value.
`lvsfunc.util.colored_clips`(amount[, ...])	Returns a list of BlankClips with unique colors in sequential or random order.
`lvsfunc.util.force_mod`(x[, mod])	Force output to fit a specific MOD.
`lvsfunc.util.frames_since_bookmark`(clip, ...)	Displays frames since last bookmark to create easily reusable scenefiltering.
`lvsfunc.util.get_coefs`(curve)	Returns transfer coefs.
`lvsfunc.util.get_matrix`(clip[, return_matrix])	Helper function to get the matrix for a clip.
`lvsfunc.util.get_matrix_curve`(matrix)	Returns a matrix curve based on a given matrix.
`lvsfunc.util.get_neutral_value`(clip[, chroma])	Taken from vsutil.
`lvsfunc.util.get_prop`(frame, key, t)	Gets FrameProp `prop` from frame `frame` with expected type `t` to satisfy the type checker.
`lvsfunc.util.load_bookmarks`(bookmark_path)	VSEdit bookmark loader.
`lvsfunc.util.normalize_ranges`(clip, ranges)	Normalize `Range`(s) to a list of inclusive positive integer ranges.
`lvsfunc.util.padder`(clip[, left, right, ...])	Pads out the pixels on the side by the given amount of pixels.
`lvsfunc.util.pick_removegrain`(clip)	Returns rgvs.RemoveGrain if the clip is 16 bit or lower, else rgsf.RemoveGrain.
`lvsfunc.util.pick_repair`(clip)	Returns rgvs.Repair if the clip is 16 bit or lower, else rgsf.Repair.
`lvsfunc.util.quick_resample`(clip, function)	A function to quickly resample to 32/16/8 bit and back to the original depth in a one-liner.
`lvsfunc.util.replace_ranges`(clip_a, clip_b, ...)	A replacement for ReplaceFramesSimple that uses ints and tuples rather than a string.
`lvsfunc.util.scale_peak`(value, peak)	Full-range scale function that scales a value from [0, 255] to [0, peak]
`lvsfunc.util.scale_thresh`(thresh, clip[, assume])	Scale binarization thresholds from float to int.

lvsfunc.util.allow_variable(width=None, height=None, format=None)

Decorator allowing a variable-res and/or variable-format clip to be passed to a function that otherwise would not be able to accept it. Implemented by FrameEvaling and resizing the clip to each frame. Does not work when the function needs to return a different format unless an output format is specified. As such, this decorator must be called as a function when used (e.g. @allow_variable() or @allow_variable(format=vs.GRAY16)). If the provided clip is variable format, no output format is required to be specified.

Parameters

width (Optional[int]) – Output clip width
height (Optional[int]) – Output clip height
format (Optional[int]) – Output clip format

Return type

Callable[[Callable[..., VideoNode]], Callable[..., VideoNode]]

Returns

Function decorator for the given output format.

lvsfunc.util.check_variable(clip, function)

Check for variable format and a variable resolution, and return an error if found.

Return type: None

lvsfunc.util.chroma_injector(func)

Decorator allowing injection of reference chroma into a function which would normally only receive luma, such as an upscaler passed to lvsfunc.scale.descale(). The chroma is resampled to the input clip’s width, height, and pixel format, shuffled to YUV444PX, then passed to the function. Luma is then extracted from the function result and returned. The first argument of the function is assumed to be the luma source. This works with variable resolution and may work with variable format, however the latter is wholly untested and likely a bad idea in every conceivable use case.

Parameters: func (TypeVar(F, bound= Callable[..., VideoNode])) – Function to call with injected chroma
Return type: TypeVar(F, bound= Callable[..., VideoNode])
Returns: Decorated function

lvsfunc.util.clamp_values(x, max_val, min_val)

Forcibly clamps the given value x to a max and/or min value.

Return type: float

lvsfunc.util.colored_clips(amount, max_hue=300, rand=True, seed=None, **kwargs)

Returns a list of BlankClips with unique colors in sequential or random order. The colors will be evenly spaced by hue in the HSL colorspace.

Useful maybe for comparison functions or just for getting multiple uniquely colored BlankClips for testing purposes.

Will always return a pure red clip in the list as this is the RGB equivalent of the lowest HSL hue possible (0).

Written by Dave <orangechannel@pm.me>.

Parameters

amount (int) – Number of vapoursynth.VideoNodes to return
max_hue (int) – Maximum hue (0 < hue <= 360) in degrees to generate colors from (uses the HSL color model). Setting this higher than 315 will result in the clip colors looping back towards red and is not recommended for visually distinct colors. If the amount of clips is higher than the max_hue expect there to be identical or visually similar colored clips returned (Default: 300)
rand (bool) – Randomizes order of the returned list (Default: True)
seed (Union[bytearray, bytes, float, str, None]) – Bytes-like object passed to random.seed which allows for consistent randomized order of the resulting clips (Default: None)
kwargs (Any) – Arguments passed to vapoursynth.core.std.BlankClip (Default: keep=1)

Return type

List[VideoNode]

Returns

List of uniquely colored clips in sequential or random order.

lvsfunc.util.force_mod(x, mod=4)

Force output to fit a specific MOD. Minimum returned value will always be mod².

Return type: int

lvsfunc.util.frames_since_bookmark(clip, bookmarks)

Displays frames since last bookmark to create easily reusable scenefiltering. Can be used in tandem with lvsfunc.misc.load_bookmarks() to import VSEdit bookmarks.

Parameters

clip (VideoNode) – Input clip
bookmarks (List[int]) – A list of bookmarks

Return type

VideoNode

Returns

Clip with bookmarked frames

lvsfunc.util.get_coefs(curve)

Returns transfer coefs.

Return type: Coefs

lvsfunc.util.get_matrix(clip, return_matrix=False)

Helper function to get the matrix for a clip.

Parameters

clip (VideoNode) – Input clip
return_matrix (bool) – Returns a Matrix instead of an int. Set to False by default for backwards compatibility.

Return type

Matrix | int

Returns

Value representing a matrix

lvsfunc.util.get_matrix_curve(matrix)

Returns a matrix curve based on a given matrix.

Return type: Literal[vapoursynth.TransferCharacteristics.TRANSFER_IEC_61966_2_1, vapoursynth.TransferCharacteristics.TRANSFER_BT709, vapoursynth.TransferCharacteristics.TRANSFER_BT601, vapoursynth.TransferCharacteristics.TRANSFER_ST240_M, vapoursynth.TransferCharacteristics.TRANSFER_BT2020_10, vapoursynth.TransferCharacteristics.TRANSFER_BT2020_12]

lvsfunc.util.get_neutral_value(clip, chroma=False)

Taken from vsutil. This isn’t in any new versions yet, so mypy complains. Will remove once vsutil does another version bump.

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 or chroma plane value

Return type

float

Returns

Neutral value.

lvsfunc.util.get_prop(frame, key, t)

Gets FrameProp prop from frame frame with expected type t to satisfy the type checker.

Parameters

frame (VideoFrame) – Frame containing props
key (str) – Prop to get
t (Type[TypeVar(T, bound= Union[int, Sequence[int], float, Sequence[float], str, Sequence[str], VideoNode, Sequence[VideoNode], VideoFrame, Sequence[VideoFrame], Callable[..., Any], Sequence[Callable[..., Any]]])]) – Type of prop

Return type

TypeVar(T, bound= Union[int, Sequence[int], float, Sequence[float], str, Sequence[str], VideoNode, Sequence[VideoNode], VideoFrame, Sequence[VideoFrame], Callable[..., Any], Sequence[Callable[..., Any]]])

Returns

frame.prop[key]

lvsfunc.util.load_bookmarks(bookmark_path)

VSEdit bookmark loader.

load_bookmarks(os.path.basename(__file__)+”.bookmarks”) will load the VSEdit bookmarks for the current Vapoursynth script.

Parameters: bookmark_path (str) – Path to bookmarks file
Return type: List[int]
Returns: A list of bookmarked frames

lvsfunc.util.normalize_ranges(clip, ranges)

Normalize Range(s) to a list of inclusive positive integer ranges.

Parameters

clip (VideoNode) – Reference clip used for length.
ranges (Union[int, None, Tuple[Optional[int], Optional[int]], List[Union[int, None, Tuple[Optional[int], Optional[int]]]]]) – Single Range or list of Ranges.

Return type

List[Tuple[int, int]]

Returns

List of inclusive positive ranges.

lvsfunc.util.padder(clip, left=32, right=32, top=32, bottom=32)

Pads out the pixels on the side by the given amount of pixels. For a 4:2:0 clip, the output must be an even resolution.

Parameters

clip (VideoNode) – Input clip
left (int) – Padding added to the left side of the clip
right (int) – Padding added to the right side of the clip
top (int) – Padding added to the top side of the clip
bottom (int) – Padding added to the bottom side of the clip

Return type

VideoNode

Returns

Padded clip

lvsfunc.util.pick_removegrain(clip)

Returns rgvs.RemoveGrain if the clip is 16 bit or lower, else rgsf.RemoveGrain. This is done because rgvs doesn’t work with float, but rgsf does for whatever reason.

Dependencies:

RGSF

Parameters: clip (VideoNode) – Input clip
Return type: Callable[..., VideoNode]
Returns: Appropriate RemoveGrain function for input clip’s depth

lvsfunc.util.pick_repair(clip)

Returns rgvs.Repair if the clip is 16 bit or lower, else rgsf.Repair. This is done because rgvs doesn’t work with float, but rgsf does for whatever reason.

Dependencies: rgsf

Parameters: clip (VideoNode) – Input clip
Return type: Callable[..., VideoNode]
Returns: Appropriate repair function for input clip’s depth

lvsfunc.util.quick_resample(clip, function)

A function to quickly resample to 32/16/8 bit and back to the original depth in a one-liner. Useful for filters that only work in 16 bit or lower when you’re working in float.

Parameters

clip (VideoNode) – Input clip
function (Callable[[VideoNode], VideoNode]) – Filter to run after resampling (accepts and returns clip)

Return type

VideoNode

Returns

Filtered clip in original depth

lvsfunc.util.replace_ranges(clip_a, clip_b, ranges, use_plugin=True)

A replacement for ReplaceFramesSimple that uses ints and tuples rather than a string. Frame ranges are inclusive. Optionally strings can still be used.

This function will try to call the VapourSynth-RemapFrames plugin before doing any of its own processing. This should come with a speed boost, so it’s recommended you install it.

Examples with clips black and white of equal length:

replace_ranges(black, white, [(0, 1)]): replace frames 0 and 1 with white

replace_ranges(black, white, [(None, None)]): replace the entire clip with white

replace_ranges(black, white, [(0, None)]): same as previous

replace_ranges(black, white, [(200, None)]): replace 200 until the end with white

replace_ranges(black, white, [(200, -1)]): replace 200 until the end with white, leaving 1 frame of black

Dependencies: VapourSynth-RemapFrames

Parameters

clip_a (VideoNode) – Original clip
clip_b (VideoNode) – Replacement clip
ranges (Union[int, None, Tuple[Optional[int], Optional[int]], List[Union[int, None, Tuple[Optional[int], Optional[int]]]]]) –
Ranges to replace clip_a (original clip) with clip_b (replacement clip).

Integer values in the list indicate single frames,

Tuple values indicate inclusive ranges.

Negative integer values will be wrapped around based on clip_b’s length.

None values are context dependent:
- None provided as sole value to ranges: no-op
- Single None value in list: Last frame in clip_b
- None as first value of tuple: 0
- None as second value of tuple: Last frame in clip_b
use_plugin (bool) – Use the ReplaceFramesSimple plugin for the rfs call.

Return type

VideoNode

Returns

Clip with ranges from clip_a replaced with clip_b

lvsfunc.util.scale_peak(value, peak)

Full-range scale function that scales a value from [0, 255] to [0, peak]

Return type: float

lvsfunc.util.scale_thresh(thresh, clip, assume=None)

Scale binarization thresholds from float to int.

Parameters

thresh (float) – Threshold [0, 1]. If greater than 1, assumed to be in native clip range
clip (VideoNode) – Clip to scale to
assume (Optional[int]) – Assume input is this depth when given input >1. If None, assume clip's format. (Default: None)

Return type

float

Returns

Threshold scaled to [0, 2^clip.depth - 1] (if vs.INTEGER)