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, ...])

Allow a variable-res and/or variable-format clip to be passed to a function.

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)

Inject reference chroma.

lvsfunc.util.colored_clips(amount[, ...])

Return a list of BlankClips with unique colors in sequential or random order.

lvsfunc.util.frames_since_bookmark(clip, ...)

Display frames since last bookmark to create easily reusable scenefiltering.

lvsfunc.util.load_bookmarks(bookmark_path)

Load VSEdit bookmarks.

lvsfunc.util.match_clip(clip, ref[, ...])

Try matching the given clip's format with the reference clip's.

lvsfunc.util.normalize_ranges(clip, ranges)

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

lvsfunc.util.padder(clip[, left, right, ...])

Pad out the pixels on the side by the given amount of pixels.

lvsfunc.util.quick_resample(clip, function)

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, ...)

Remaps frame indices in a clip using 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)

Allow a variable-res and/or variable-format clip to be passed to a function.

This is a function decorator. That means it must be called above a function. For example:

@allow_variable()
def function(clip: vs.VideoNode) -> vs.VideoNode:
    ...

This can be used on functions 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.

Raises
Return type

TypeGuard[_VideoNode]

lvsfunc.util.chroma_injector(func)

Inject reference chroma.

This is a function decorator. That means it must be called above a function. For example:

@chroma_injector()
def function(clip: vs.VideoNode) -> vs.VideoNode:
    ...

This can be used to inject 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 (VNodeCallable) – Function to call with injected chroma.

Return type

VNodeCallable

Returns

Decorated function.

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

Return 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.

Parameters
  • amount (int) – Number of 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.

Raises
  • ValueErroramount is less than 2.

  • ValueErrormax_hue is not between 0–360.

lvsfunc.util.frames_since_bookmark(clip, bookmarks)

Display 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) – Clip to process.

  • bookmarks (list[int]) – A list of bookmarks.

Return type

VideoNode

Returns

Clip with bookmarked frames.

lvsfunc.util.load_bookmarks(bookmark_path)

Load VSEdit bookmarks.

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 lvsfunc.types.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 lvsfunc.types.Range, or a list of lvsfunc.types.Range(s).

Return type

list[tuple[int, int]]

Returns

List of inclusive positive ranges.

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

Pad 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.

Dependencies:

Parameters
  • clip (VideoNode) – Clip to process.

  • 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.

Raises

ValueError – A non-even resolution is passed on a YUV420 clip.

lvsfunc.util.quick_resample(clip, function)

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) – Clip to process.

  • 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, exclusive=False, use_plugin=True)

Remaps frame indices in a clip using ints and tuples rather than a string.

Frame ranges are inclusive. This behaviour can be changed by setting exclusive=True.

If you’re trying to splice in clips, it’s recommended you use vsutil.insert_clip instead.

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

Alias for this function is lvsfunc.rfs.

Dependencies:

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

  • exclusive (bool) – Use exclusive ranges (Default: False).

  • use_plugin (bool) – Use the ReplaceFramesSimple plugin for the rfs call (Default: True).

Return type

VideoNode

Returns

Clip with ranges from clip_a replaced with clip_b.

Raises

ValueError – A string is passed instead of a list of ranges.

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).

Raises

ValueError – Thresholds are negative.