Skip to content

generic

Classes:

  • ChromaLocation

    Chroma sample position in YUV formats.

  • FieldBased

    Whether the frame is composed of two independent fields (interlaced) and their order if so.

Attributes:

ChromaLocationLike module-attribute

ChromaLocationLike: TypeAlias = int | ChromaLocation | ChromaLocation

Type alias for values that can be used to initialize a ChromaLocation.

ChromaLocationT module-attribute

ChromaLocationT = ChromaLocationLike

Deprecated alias of ChromaLocationLike

FieldBasedLike module-attribute

FieldBasedLike: TypeAlias = int | FieldBased | FieldBased

Type alias for values that can be used to initialize a FieldBased.

FieldBasedT module-attribute

FieldBasedT = FieldBasedLike

Deprecated alias of FieldBasedT = FieldBasedLike

ChromaLocation

Bases: PropEnum

Chroma sample position in YUV formats.

Methods:

  • apply

    Applies the property to the VideoNode.

  • ensure_presence

    Ensure the presence of the property in the VideoNode.

  • ensure_presences

    Ensure the presence of multiple PropEnums at once.

  • from_param

    Determine the ChromaLocation through a parameter.

  • from_param_or_video
  • from_res

    Guess the chroma location based on the clip's resolution.

  • from_video

    Obtain the chroma location of a clip from the frame properties.

  • get_offsets

    Get (left,top) shift for chroma relative to luma.

  • is_unknown

    Whether the value represents an unknown value.

  • is_valid

    Check if the given value is a valid int value of this enum.

  • prop_key

    The key used in props to store the enum.

Attributes:

BOTTOM class-attribute instance-attribute

BOTTOM = 5

BOTTOM_LEFT class-attribute instance-attribute

BOTTOM_LEFT = 4

CENTER class-attribute instance-attribute

CENTER = 1

LEFT class-attribute instance-attribute

LEFT = 0

TOP class-attribute instance-attribute

TOP = 3

TOP_LEFT class-attribute instance-attribute

TOP_LEFT = 2

pretty_string property

pretty_string: str

Get a pretty, displayable string of the enum member.

string property

string: str

Get the string representation used in resize plugin/encoders.

apply

apply(clip: VideoNodeT) -> VideoNodeT

Applies the property to the VideoNode.

Source code in vstools/enums/base.py
105
106
107
108
109
110
def apply(self, clip: VideoNodeT) -> VideoNodeT:
    """
    Applies the property to the VideoNode.
    """

    return vs.core.std.SetFrameProp(clip, self.prop_key, self.value)

ensure_presence classmethod

ensure_presence(
    clip: VideoNodeT,
    value: int | Self | None,
    /,
    func: FuncExcept | None = None,
) -> VideoNodeT

Ensure the presence of the property in the VideoNode.

Source code in vstools/enums/base.py
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
@classmethod
def ensure_presence(
    cls, clip: VideoNodeT, value: int | Self | None, /, func: FuncExcept | None = None
) -> VideoNodeT:
    """
    Ensure the presence of the property in the VideoNode.
    """

    enum_value = cls.from_param_or_video(value, clip, True, func)

    return vs.core.std.SetFrameProp(clip, enum_value.prop_key, enum_value.value)

ensure_presences staticmethod

ensure_presences(
    clip: VideoNodeT,
    prop_enums: Iterable[type[PropEnum] | PropEnum],
    func: FuncExcept | None = None,
) -> VideoNodeT

Ensure the presence of multiple PropEnums at once.

Source code in vstools/enums/base.py
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@staticmethod
def ensure_presences(
    clip: VideoNodeT, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> VideoNodeT:
    """
    Ensure the presence of multiple PropEnums at once.
    """

    return vs.core.std.SetFrameProps(
        clip,
        **{
            value.prop_key: value.value
            for value in (
                prop_enum if isinstance(prop_enum, PropEnum) else prop_enum.from_video(clip, True, func)
                for prop_enum in prop_enums
            )
        },
    )

from_param classmethod

from_param(value: None, func_except: FuncExcept | None = None) -> None
from_param(
    value: ChromaLocationLike, func_except: FuncExcept | None = None
) -> Self
from_param(
    value: ChromaLocationLike | None, func_except: FuncExcept | None = None
) -> Self | None
from_param(value: Any, func_except: Any = None) -> Self | None

Determine the ChromaLocation through a parameter.

Parameters:

  • value

    (Any) –

    Value or ChromaLocation object.

  • func_except

    (Any, default: None ) –

    Function returned for custom error handling. This should only be set by VS package developers.

Returns:

  • Self | None

    ChromaLocation object or None.

Source code in vstools/enums/generic.py
59
60
61
62
63
64
65
66
67
68
69
70
71
@classmethod
def from_param(cls, value: Any, func_except: Any = None) -> Self | None:
    """
    Determine the ChromaLocation through a parameter.

    Args:
        value: Value or ChromaLocation object.
        func_except: Function returned for custom error handling. This should only be set by VS package
            developers.

    Returns:
        ChromaLocation object or None.
    """

from_param_or_video classmethod

from_param_or_video(
    value: ChromaLocation | None,
    src: VideoNode | VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> ChromaLocation
Source code in vstools/enums/generic.py
73
74
75
76
77
78
79
80
@classmethod
def from_param_or_video(
    cls,
    value: ChromaLocation | None,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> ChromaLocation: ...

from_res classmethod

from_res(frame: VideoNode | VideoFrame) -> ChromaLocation

Guess the chroma location based on the clip's resolution.

Parameters:

  • frame

    (VideoNode | VideoFrame) –

    Input clip or frame.

Returns:

Source code in vstools/enums/generic.py
82
83
84
85
86
87
88
89
90
91
92
93
94
@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> ChromaLocation:
    """
    Guess the chroma location based on the clip's resolution.

    Args:
        frame: Input clip or frame.

    Returns:
        ChromaLocation object.
    """

    return ChromaLocation.LEFT

from_video classmethod

from_video(
    src: VideoNode | VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func: FuncExcept | None = None,
) -> ChromaLocation

Obtain the chroma location of a clip from the frame properties.

Parameters:

  • src

    (VideoNode | VideoFrame | Mapping[str, Any]) –

    Input clip, frame, or props.

  • strict

    (bool, default: False ) –

    Be strict about the properties. The result may NOT be an unknown value.

Returns:

Raises:

Source code in vstools/enums/generic.py
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> ChromaLocation:
    """
    Obtain the chroma location of a clip from the frame properties.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the properties. The result may NOT be an unknown value.

    Returns:
        ChromaLocation object.

    Raises:
        UndefinedChromaLocationError: Chroma location is undefined.
        UndefinedChromaLocationError: Chroma location can not be determined from the frame properties.
    """

    return _base_from_video(cls, src, UndefinedChromaLocationError, strict, func)

get_offsets

get_offsets(
    src: int | VideoFormatLike | HoldsVideoFormat,
) -> tuple[float, float]

Get (left,top) shift for chroma relative to luma.

This is only useful if you MUST use a pre-specified chroma location and shift the chroma yourself.

Source code in vstools/enums/generic.py
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def get_offsets(self, src: int | VideoFormatLike | HoldsVideoFormat) -> tuple[float, float]:
    """
    Get (left,top) shift for chroma relative to luma.

    This is only useful if you MUST use a pre-specified chroma location and shift the chroma yourself.
    """
    from ..utils import get_video_format

    fmt = get_video_format(src)

    off_left = off_top = 0.0

    if self in {ChromaLocation.LEFT, ChromaLocation.TOP_LEFT, ChromaLocation.BOTTOM_LEFT}:
        off_left = 0.5 - 2 ** (fmt.subsampling_w - 1)

    if self in {ChromaLocation.TOP, ChromaLocation.TOP_LEFT}:
        off_top = 0.5 - 2 ** (fmt.subsampling_h - 1)
    elif self in {ChromaLocation.BOTTOM, ChromaLocation.BOTTOM_LEFT}:
        off_top = 2 ** (fmt.subsampling_h - 1) - 0.5

    return off_left, off_top

is_unknown classmethod

is_unknown(value: int | Self) -> bool

Whether the value represents an unknown value.

Source code in vstools/enums/base.py
21
22
23
24
25
26
27
@classmethod
def is_unknown(cls, value: int | Self) -> bool:
    """
    Whether the value represents an unknown value.
    """

    return False

is_valid classmethod

is_valid(value: int) -> bool

Check if the given value is a valid int value of this enum.

Source code in vstools/enums/base.py
148
149
150
151
152
153
@classmethod
def is_valid(cls, value: int) -> bool:
    """
    Check if the given value is a valid int value of this enum.
    """
    return int(value) in map(int, cls.__members__.values())

prop_key classmethod

prop_key() -> str

The key used in props to store the enum.

Source code in vstools/enums/base.py
29
30
31
32
33
34
35
36
@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """

    return f"_{cls.__name__}"

FieldBased

Bases: PropEnum

Whether the frame is composed of two independent fields (interlaced) and their order if so.

Methods:

  • apply

    Applies the property to the VideoNode.

  • ensure_presence
  • ensure_presences

    Ensure the presence of multiple PropEnums at once.

  • from_param

    Determine the type of field through a parameter.

  • from_param_or_video
  • from_res

    Guess the Field order from the frame resolution.

  • from_video

    Obtain the Field order of a clip from the frame properties.

  • is_unknown

    Whether the value represents an unknown value.

  • is_valid

    Check if the given value is a valid int value of this enum.

  • prop_key

    The key used in props to store the enum.

Attributes:

  • BFF

    The frame is interlaced and the field order is bottom field first.

  • PROGRESSIVE

    The frame is progressive.

  • TFF

    The frame is interlaced and the field order is top field first.

  • field (int) –

    Check what field the enum signifies.

  • inverted_field (FieldBased) –

    Get the inverted field order.

  • is_inter (bool) –

    Check whether the value belongs to an interlaced value.

  • is_tff (bool) –

    Check whether the value is Top-Field-First.

  • pretty_string (str) –
  • string (str) –

    Get the string representation used in resize plugin/encoders.

BFF class-attribute instance-attribute

BFF = 1

The frame is interlaced and the field order is bottom field first.

PROGRESSIVE class-attribute instance-attribute

PROGRESSIVE = 0

The frame is progressive.

TFF class-attribute instance-attribute

TFF = 2

The frame is interlaced and the field order is top field first.

field property

field: int

Check what field the enum signifies.

Raises:

inverted_field property

inverted_field: FieldBased

Get the inverted field order.

Raises:

is_inter property

is_inter: bool

Check whether the value belongs to an interlaced value.

is_tff property

is_tff: bool

Check whether the value is Top-Field-First.

pretty_string property

pretty_string: str

string property

string: str

Get the string representation used in resize plugin/encoders.

apply

apply(clip: VideoNodeT) -> VideoNodeT

Applies the property to the VideoNode.

Source code in vstools/enums/base.py
105
106
107
108
109
110
def apply(self, clip: VideoNodeT) -> VideoNodeT:
    """
    Applies the property to the VideoNode.
    """

    return vs.core.std.SetFrameProp(clip, self.prop_key, self.value)

ensure_presence classmethod

ensure_presence(
    clip: VideoNodeT,
    tff: FieldBasedLike | bool | None,
    func: FuncExcept | None = None,
) -> VideoNodeT
Source code in vstools/enums/generic.py
215
216
217
218
219
220
221
@classmethod
def ensure_presence(
    cls, clip: VideoNodeT, tff: FieldBasedLike | bool | None, func: FuncExcept | None = None
) -> VideoNodeT:
    field_based = cls.from_param_or_video(tff, clip, True, func)

    return vs.core.std.SetFieldBased(clip, field_based.value)

ensure_presences staticmethod

ensure_presences(
    clip: VideoNodeT,
    prop_enums: Iterable[type[PropEnum] | PropEnum],
    func: FuncExcept | None = None,
) -> VideoNodeT

Ensure the presence of multiple PropEnums at once.

Source code in vstools/enums/base.py
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@staticmethod
def ensure_presences(
    clip: VideoNodeT, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> VideoNodeT:
    """
    Ensure the presence of multiple PropEnums at once.
    """

    return vs.core.std.SetFrameProps(
        clip,
        **{
            value.prop_key: value.value
            for value in (
                prop_enum if isinstance(prop_enum, PropEnum) else prop_enum.from_video(clip, True, func)
                for prop_enum in prop_enums
            )
        },
    )

from_param classmethod

from_param(value: None, func_except: FuncExcept | None = None) -> None
from_param(
    value: FieldBasedLike | bool, func_except: FuncExcept | None = None
) -> Self
from_param(
    value: FieldBasedLike | bool | None, func_except: FuncExcept | None = None
) -> Self | None
from_param(
    value: FieldBasedLike | bool | None, func_except: FuncExcept | None = None
) -> Self | None

Determine the type of field through a parameter.

Parameters:

  • value

    (FieldBasedLike | bool | None) –

    Value or FieldBased object. If it's bool, it specifies whether it's TFF or BFF.

  • func_except

    (FuncExcept | None, default: None ) –

    Function returned for custom error handling. This should only be set by VS package developers.

Returns:

  • Self | None

    FieldBased object or None.

Source code in vstools/enums/generic.py
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
@classmethod
def from_param(cls, value: FieldBasedLike | bool | None, func_except: FuncExcept | None = None) -> Self | None:
    """
    Determine the type of field through a parameter.

    Args:
        value: Value or FieldBased object. If it's bool, it specifies whether it's TFF or BFF.
        func_except: Function returned for custom error handling. This should only be set by VS package
            developers.

    Returns:
        FieldBased object or None.
    """
    if isinstance(value, bool):
        return cls(1 + value)

    return super().from_param(value)

from_param_or_video classmethod

from_param_or_video(
    value: FieldBasedLike | bool | None,
    src: VideoNode | VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> FieldBased
Source code in vstools/enums/generic.py
206
207
208
209
210
211
212
213
@classmethod
def from_param_or_video(
    cls,
    value: FieldBasedLike | bool | None,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> FieldBased: ...

from_res classmethod

from_res(frame: VideoNode | VideoFrame) -> FieldBased

Guess the Field order from the frame resolution.

Source code in vstools/enums/generic.py
223
224
225
226
227
228
229
@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> FieldBased:
    """
    Guess the Field order from the frame resolution.
    """

    return cls.PROGRESSIVE

from_video classmethod

from_video(
    src: VideoNode | VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func: FuncExcept | None = None,
) -> FieldBased

Obtain the Field order of a clip from the frame properties.

Parameters:

  • src

    (VideoNode | VideoFrame | Mapping[str, Any]) –

    Input clip, frame, or props.

  • strict

    (bool, default: False ) –

    Be strict about the properties. Will ALWAYS error if the FieldBased is missing.

Returns:

Raises:

Source code in vstools/enums/generic.py
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> FieldBased:
    """
    Obtain the Field order of a clip from the frame properties.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the properties. Will ALWAYS error if the FieldBased is missing.

    Returns:
        FieldBased object.

    Raises:
        UndefinedFieldBasedError: Field order is undefined.
        UndefinedFieldBasedError: Field order can not be determined from the frame properties.
    """

    return _base_from_video(cls, src, UndefinedFieldBasedError, strict, func)

is_unknown classmethod

is_unknown(value: int | Self) -> bool

Whether the value represents an unknown value.

Source code in vstools/enums/base.py
21
22
23
24
25
26
27
@classmethod
def is_unknown(cls, value: int | Self) -> bool:
    """
    Whether the value represents an unknown value.
    """

    return False

is_valid classmethod

is_valid(value: int) -> bool

Check if the given value is a valid int value of this enum.

Source code in vstools/enums/base.py
148
149
150
151
152
153
@classmethod
def is_valid(cls, value: int) -> bool:
    """
    Check if the given value is a valid int value of this enum.
    """
    return int(value) in map(int, cls.__members__.values())

prop_key classmethod

prop_key() -> str

The key used in props to store the enum.

Source code in vstools/enums/base.py
29
30
31
32
33
34
35
36
@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """

    return f"_{cls.__name__}"