Skip to content

other

Classes:

  • Dar

    A Fraction representing the Display Aspect Ratio.

  • Direction

    Enum to simplify the direction argument.

  • Region

    StrEnum signifying an analog television region.

  • Resolution

    Tuple representing a resolution.

  • Sar

    A Fraction representing the Sample Aspect Ratio.

  • SceneChangeMode

    Enum for various scene change modes.

Dar

Bases: _Xar

A Fraction representing the Display Aspect Ratio.

This represents the dimensions of the physical display used to view the image. For more information, see https://en.wikipedia.org/wiki/Display_aspect_ratio.

Methods:

  • from_clip

    Get the DAR from the specified clip and SAR.

  • from_param

    Get the Xar from a Xar, a boolean, a float or a None object.

  • from_res

    Get the DAR from the specified dimensions and SAR.

  • to_sar

    Convert the DAR to a SAR object.

from_clip classmethod

from_clip(clip: VideoNode, sar: bool = True) -> Self

Get the DAR from the specified clip and SAR.

Parameters:

  • clip

    (VideoNode) –

    Clip or frame that holds the frame properties.

  • sar

    (bool, default: True ) –

    Whether to use SAR metadata.

Returns:

  • Self

    A DAR object created using the specified clip and SAR.

Source code
110
111
112
113
114
115
116
117
118
119
120
121
@classmethod
def from_clip(cls, clip: vs.VideoNode, sar: bool = True) -> Self:
    """
    Get the DAR from the specified clip and SAR.

    :param clip:     Clip or frame that holds the frame properties.
    :param sar:      Whether to use SAR metadata.

    :return:         A DAR object created using the specified clip and SAR.
    """

    return cls.from_res(clip.width, clip.height, Sar.from_clip(clip) if sar else None)

from_param classmethod

from_param(
    value: Self | bool | float | None, fallback: Self | float
) -> Self | None

Get the Xar from a Xar, a boolean, a float or a None object.

Parameters:

  • value

    (Self | bool | float | None) –

    Value identifier.

  • fallback

    (Self | float) –

    Fallback value.

Returns:

  • Self | None

    Xar object or None.

Source code
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
def from_param(cls, value: Self | bool | float | None, fallback: Self | float) -> Self | None:
    """
    Get the Xar from a Xar, a boolean, a float or a None object.

    :param value:       Value identifier.
    :param fallback:    Fallback value.
    :return:            Xar object or None.
    """
    if value is False:
        return cls(fallback)

    if value is True:
        return None

    if isinstance(value, cls):
        return value

    if value is not None:
        return cls.from_float(float(value))

    return None

from_res classmethod

from_res(width: int, height: int, sar: Sar | None = None) -> Self

Get the DAR from the specified dimensions and SAR.

Parameters:

  • width

    (int) –

    The width of the image.

  • height

    (int) –

    The height of the image.

  • sar

    (Sar | None, default: None ) –

    The SAR object. Optional.

Returns:

  • Self

    A DAR object created using the specified dimensions and SAR.

Source code
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
@classmethod
def from_res(cls, width: int, height: int, sar: Sar | None = None) -> Self:
    """
    Get the DAR from the specified dimensions and SAR.

    :param width:      The width of the image.
    :param height:     The height of the image.
    :param sar:        The SAR object. Optional.

    :return:           A DAR object created using the specified dimensions and SAR.
    """

    dar = Fraction(width, height)

    if sar:
        if sar.denominator > sar.numerator:
            dar /= sar
        else:
            dar *= sar

    return cls(dar)

to_sar

Convert the DAR to a SAR object.

Parameters:

  • active_area

    (int | Fraction) –

    The active image area. For more information, see Sar.from_ar.

  • height

    (int) –

    The height of the image.

Returns:

  • Sar

    A SAR object created using the DAR.

Source code
123
124
125
126
127
128
129
130
131
132
133
134
135
def to_sar(self, active_area: int | Fraction, height: int) -> Sar:
    """
    Convert the DAR to a SAR object.

    :param active_area:     The active image area. For more information, see ``Sar.from_ar``.
    :param height:          The height of the image.

    :return:                A SAR object created using the DAR.
    """

    assert isinstance(active_area, int | Fraction)

    return Sar.from_ar(active_area, height, self)

Direction

Bases: CustomIntEnum

Enum to simplify the direction argument.

Attributes:

DOWN class-attribute instance-attribute

DOWN = 5

HORIZONTAL class-attribute instance-attribute

HORIZONTAL = 0

LEFT class-attribute instance-attribute

LEFT = 2

RIGHT class-attribute instance-attribute

RIGHT = 3

UP class-attribute instance-attribute

UP = 4

VERTICAL class-attribute instance-attribute

VERTICAL = 1

is_axis property

is_axis: bool

Whether the Direction represents an axis (horizontal/vertical).

is_way property

is_way: bool

Whether the Direction is one of the 4 arrow directions.

string property

string: str

A string representation of the Direction.

Region

Bases: CustomStrEnum

StrEnum signifying an analog television region.

Methods:

Attributes:

  • FILM

    True 24fps content.

  • NTSC

    The first American standard for analog television broadcast was developed by

  • NTSC_FILM

    NTSC 23.976fps content.

  • NTSCi

    Interlaced NTSC.

  • PAL

    Phase Alternating Line (PAL) colour encoding system.

  • PALi

    Interlaced PAL.

  • UNKNOWN

    Unknown region.

  • framerate (Fraction) –

    Obtain the Region's framerate.

FILM class-attribute instance-attribute

FILM = 'FILM'

True 24fps content.

NTSC class-attribute instance-attribute

NTSC = 'NTSC'

The first American standard for analog television broadcast was developed by National Television System Committee (NTSC) in 1941.

For more information see this <https://en.wikipedia.org/wiki/NTSC>_.

NTSC_FILM class-attribute instance-attribute

NTSC_FILM = 'NTSC (FILM)'

NTSC 23.976fps content.

NTSCi class-attribute instance-attribute

NTSCi = 'NTSCi'

Interlaced NTSC.

PAL class-attribute instance-attribute

PAL = 'PAL'

Phase Alternating Line (PAL) colour encoding system.

For more information see this <https://en.wikipedia.org/wiki/PAL>_.

PALi class-attribute instance-attribute

PALi = 'PALi'

Interlaced PAL.

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

Unknown region.

framerate property

framerate: Fraction

Obtain the Region's framerate.

from_framerate classmethod

from_framerate(framerate: float | Fraction, strict: bool = False) -> Self

Determine the Region using a given framerate.

Source code
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
@classmethod
def from_framerate(cls, framerate: float | Fraction, strict: bool = False) -> Self:
    """Determine the Region using a given framerate."""

    key = Fraction(framerate)

    if strict:
        return cls(_framerate_region_map[key])

    if key not in _framerate_region_map:
        diffs = [(k, abs(float(key) - float(v))) for k, v in _region_framerate_map.items()]

        diffs.sort(key=lambda x: x[1])

        return cls(diffs[0][0])

    return cls(_framerate_region_map[key])

Resolution

Bases: NamedTuple

Tuple representing a resolution.

Methods:

  • from_video

    Create a Resolution object using a given clip's dimensions.

  • transpose

    Flip the Resolution matrix over its diagonal.

Attributes:

height instance-attribute

height: int

width instance-attribute

width: int

from_video classmethod

from_video(clip: VideoNode) -> Self

Create a Resolution object using a given clip's dimensions.

Source code
263
264
265
266
267
268
269
270
271
@classmethod
def from_video(cls, clip: vs.VideoNode) -> Self:
    """Create a Resolution object using a given clip's dimensions."""

    from ..functions import check_variable_resolution

    assert check_variable_resolution(clip, cls.from_video)

    return cls(clip.width, clip.height)

transpose

transpose() -> Self

Flip the Resolution matrix over its diagonal.

Source code
273
274
275
276
def transpose(self) -> Self:
    """Flip the Resolution matrix over its diagonal."""

    return self.__class__(self.height, self.width)

Sar

Bases: _Xar

A Fraction representing the Sample Aspect Ratio.

This represents the aspect ratio of the pixels or samples of an image. It may also be known as the Pixel Aspect Ratio in certain scenarios. For more information, see https://en.wikipedia.org/wiki/Pixel_aspect_ratio.

Methods:

  • apply

    Apply the SAR values as _SARNum and _SARDen frame properties to a clip.

  • from_ar

    Calculate the SAR using a DAR object & active area. See Dar.to_sar for more information.

  • from_clip

    Get the SAR from the clip's frame properties.

  • from_param

    Get the Xar from a Xar, a boolean, a float or a None object.

apply

apply(clip: VideoNodeT) -> VideoNodeT

Apply the SAR values as _SARNum and _SARDen frame properties to a clip.

Source code
180
181
182
183
def apply(self, clip: VideoNodeT) -> VideoNodeT:
    """Apply the SAR values as _SARNum and _SARDen frame properties to a clip."""

    return vs.core.std.SetFrameProps(clip, _SARNum=self.numerator, _SARDen=self.denominator)

from_ar classmethod

from_ar(active_area: int | Fraction, height: int, dar: Dar) -> Self

Calculate the SAR using a DAR object & active area. See Dar.to_sar for more information.

For a list of known standards, refer to the following tables: <https://docs.google.com/spreadsheets/d/1pzVHFusLCI7kys2GzK9BTk3w7G8zcLxgHs3DMsurF7g>_

Parameters:

  • active_area

    (int | Fraction) –

    The active image area.

  • height

    (int) –

    The height of the image.

  • dar

    (Dar) –

    The DAR object.

Returns:

  • Self

    A SAR object created using DAR and active image area information.

Source code
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
@classmethod
def from_ar(cls, active_area: int | Fraction, height: int, dar: Dar) -> Self:
    """
    Calculate the SAR using a DAR object & active area. See ``Dar.to_sar`` for more information.

    For a list of known standards, refer to the following tables:
    `<https://docs.google.com/spreadsheets/d/1pzVHFusLCI7kys2GzK9BTk3w7G8zcLxgHs3DMsurF7g>`_

    :param active_area:     The active image area.
    :param height:          The height of the image.
    :param dar:             The DAR object.

    :return:                A SAR object created using DAR and active image area information.
    """

    assert isinstance(active_area, int | Fraction)

    return cls(dar / (Fraction(active_area) / height))

from_clip classmethod

from_clip(clip: HoldsPropValueT) -> Self

Get the SAR from the clip's frame properties.

Parameters:

Returns:

  • Self

    A SAR object of the SAR properties from the given clip.

Source code
147
148
149
150
151
152
153
154
155
156
157
158
159
@classmethod
def from_clip(cls, clip: HoldsPropValueT) -> Self:
    """
    Get the SAR from the clip's frame properties.

    :param clip:        Clip or frame that holds the frame properties.

    :return:            A SAR object of the SAR properties from the given clip.
    """

    from ..utils import get_prop

    return cls(get_prop(clip, '_SARNum', int, None, 1), get_prop(clip, '_SARDen', int, None, 1))

from_param classmethod

from_param(
    value: Self | bool | float | None, fallback: Self | float
) -> Self | None

Get the Xar from a Xar, a boolean, a float or a None object.

Parameters:

  • value

    (Self | bool | float | None) –

    Value identifier.

  • fallback

    (Self | float) –

    Fallback value.

Returns:

  • Self | None

    Xar object or None.

Source code
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
def from_param(cls, value: Self | bool | float | None, fallback: Self | float) -> Self | None:
    """
    Get the Xar from a Xar, a boolean, a float or a None object.

    :param value:       Value identifier.
    :param fallback:    Fallback value.
    :return:            Xar object or None.
    """
    if value is False:
        return cls(fallback)

    if value is True:
        return None

    if isinstance(value, cls):
        return value

    if value is not None:
        return cls.from_float(float(value))

    return None

SceneChangeMode

Bases: CustomIntEnum

Enum for various scene change modes.

Methods:

Attributes:

SCXVID class-attribute instance-attribute

SCXVID = 2

Get the scene changes using the vapoursynth-scxvid plugin https://github.com/dubhater/vapoursynth-scxvid.

WWXD class-attribute instance-attribute

WWXD = 1

Get the scene changes using the vapoursynth-wwxd plugin https://github.com/dubhater/vapoursynth-wwxd.

WWXD_SCXVID_INTERSECTION class-attribute instance-attribute

WWXD_SCXVID_INTERSECTION = 0

Only get the scene changes if both wwxd and scxvid mark a frame as being a scene change.

WWXD_SCXVID_UNION class-attribute instance-attribute

WWXD_SCXVID_UNION = 3

Get every scene change detected by both wwxd or scxvid.

is_SCXVID property

is_SCXVID: bool

Check whether a mode that uses scxvid is used.

is_WWXD property

is_WWXD: bool

Check whether a mode that uses wwxd is used.

prop_keys property

prop_keys: Iterator[str]

check_cb

check_cb(akarin: bool | None = None) -> Callable[[VideoFrame], bool]
Source code
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
def check_cb(self, akarin: bool | None = None) -> Callable[[vs.VideoFrame], bool]:
    if akarin is None:
        akarin = hasattr(vs.core, 'akarin')

    if akarin:
        return (lambda f: bool(f[0][0, 0]))

    keys = set(self.prop_keys)
    prop_key = next(iter(keys))

    if self is SceneChangeMode.WWXD_SCXVID_UNION:
        return (lambda f: any(f.props[key] == 1 for key in keys))

    if self is SceneChangeMode.WWXD_SCXVID_INTERSECTION:
        return (lambda f: all(f.props[key] == 1 for key in keys))

    return (lambda f: f.props[prop_key] == 1)

ensure_presence

ensure_presence(
    clip: VideoNode, akarin: bool | None = None
) -> ConstantFormatVideoNode

Ensures all the frame properties necessary for scene change detection are created.

Source code
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
def ensure_presence(self, clip: vs.VideoNode, akarin: bool | None = None) -> ConstantFormatVideoNode:
    """Ensures all the frame properties necessary for scene change detection are created."""

    from ..exceptions import CustomRuntimeError
    from ..functions import check_variable_format

    assert check_variable_format(clip, self.ensure_presence)

    stats_clip = list[ConstantFormatVideoNode]()

    if self.is_SCXVID:
        if not hasattr(vs.core, 'scxvid'):
            raise CustomRuntimeError(
                'You are missing scxvid!\n\tDownload it from https://github.com/dubhater/vapoursynth-scxvid',
                self.ensure_presence
            )
        stats_clip.append(clip.scxvid.Scxvid())

    if self.is_WWXD:
        if not hasattr(vs.core, 'wwxd'):
            raise CustomRuntimeError(
                'You are missing wwxd!\n\tDownload it from https://github.com/dubhater/vapoursynth-wwxd',
                self.ensure_presence
            )
        stats_clip.append(clip.wwxd.WWXD())

    return self._prepare_akarin(clip, stats_clip, akarin)

lambda_cb

lambda_cb(
    akarin: bool | None = None,
) -> Callable[[int, VideoFrame], SentinelT | int]
Source code
369
370
371
def lambda_cb(self, akarin: bool | None = None) -> Callable[[int, vs.VideoFrame], SentinelT | int]:
    callback = self.check_cb(akarin)
    return (lambda n, f: Sentinel.check(n, callback(f)))

prepare_clip

prepare_clip(
    clip: VideoNode,
    height: int | Literal[False] = 360,
    akarin: bool | None = None,
) -> ConstantFormatVideoNode

Prepare a clip for scene change metric calculations.

The clip will always be resampled to YUV420 8bit if it's not already, as that's what the plugins support.

Parameters:

  • clip

    (VideoNode) –

    Clip to process.

  • height

    (int | Literal[False], default: 360 ) –

    Output height of the clip. Smaller frame sizes are faster to process, but may miss more scene changes or introduce more false positives. Width is automatically calculated. False means no resizing operation is performed. Default: 360.

  • akarin

    (bool | None, default: None ) –

    Use the akarin plugin for speed optimizations. None means it will check if its available, and if it is, use it. Default: None.

Returns:

  • ConstantFormatVideoNode

    A prepared clip for performing scene change metric calculations on.

Source code
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
def prepare_clip(self, clip: vs.VideoNode, height: int | Literal[False] = 360, akarin: bool | None = None) -> ConstantFormatVideoNode:
    """
    Prepare a clip for scene change metric calculations.

    The clip will always be resampled to YUV420 8bit if it's not already,
    as that's what the plugins support.

    :param clip:        Clip to process.
    :param height:      Output height of the clip. Smaller frame sizes are faster to process,
                        but may miss more scene changes or introduce more false positives.
                        Width is automatically calculated. `False` means no resizing operation is performed.
                        Default: 360.
    :param akarin:      Use the akarin plugin for speed optimizations. `None` means it will check if its available,
                        and if it is, use it. Default: None.

    :return:            A prepared clip for performing scene change metric calculations on.
    """
    from ..utils import get_w

    if height:
        clip = clip.resize.Bilinear(get_w(height, clip), height, vs.YUV420P8)
    elif not clip.format or (clip.format and clip.format.id != vs.YUV420P8):
        clip = clip.resize.Bilinear(format=vs.YUV420P8)

    return self.ensure_presence(clip, akarin)