color ¶

def apply(self, clip: vs.VideoNode) -> vs.VideoNode:
    """
    Applies the property to the VideoNode.
    """
    return clip.std.SetFrameProp(self.prop_key, self.value)

@classmethod
def ensure_presence(cls, clip: vs.VideoNode, value: Any, func: FuncExcept | None = None) -> vs.VideoNode:
    """
    Ensure the presence of the property in the VideoNode.
    """
    enum_value = cls.from_param_or_video(value, clip, True, func)

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

@staticmethod
def ensure_presences(
    clip: vs.VideoNode, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> vs.VideoNode:
    """
    Ensure the presence of multiple PropEnums at once.
    """
    return clip.std.SetFrameProps(
        **{
            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
            )
        },
    )

@classmethod
def from_param_or_video(
    cls,
    value: Any,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Get the enum member from a value that can be casted to this prop value or grab it from frame properties.

    If `strict=False`, gather the heuristics using the clip's size or format.

    Args:
        value: Value to cast.
        src: Clip to get prop from.
        strict: Be strict about the frame properties. Default: False.
        func_except: Function returned for custom error handling.
    """
    prop = cls.from_param_with_fallback(value, None)

    # Delay the `from_video` call here to avoid unnecessary frame rendering
    if prop is None:
        return cls.from_video(src, strict, func_except)

    return prop

@classmethod
def from_param_with_fallback[T](cls, value: Any, fallback: T | None = None) -> Self | T | None:
    """
    Attempts to obtain an enum member from a parameter value, returning a fallback if the value cannot be converted
    or represents an unspecified enum member.

    Args:
        value: The input value to convert into an enum member.
        fallback: The value to return if the input cannot be converted. Defaults to `None`.

    Returns:
        The corresponding enum member if conversion succeeds, otherwise the provided `fallback` value.
    """
    with suppress(NotFoundEnumValueError, CustomValueError):
        # Will raise a NotFoundEnumValueError if the value can't be casted
        casted = cls.from_param(value)

        # If unspecified, fallbacks to `fallback` value
        if casted.is_unspecified():
            raise CustomValueError

        return casted

    return fallback

@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> ColorRange:
    """
    Guess the color range from the frame resolution.
    """
    from ..utils import get_var_infos

    fmt, _, _ = get_var_infos(frame)

    if fmt.color_family == vs.RGB:
        return cls.FULL

    return cls.LIMITED

@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> ColorRange:
    """
    Try to obtain the color range of a clip from the frame props or fallback to clip's resolution
    if the prop is undefined, strict=False and src is a clip.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the frame props. Sets the ColorRange as MISSING if prop is not there.
        func: Function returned for custom error handling.

    Returns:
        ColorRange object.

    Raises:
        UndefinedColorRangeError: If the color range is undefined or can not be determined from the frameprops.
    """
    return _base_from_video(cls, src, UndefinedColorRangeError, strict, func)

def is_full(self) -> bool:
    """
    Check if ColorRange is full.
    """
    return not self.value

def is_limited(self) -> bool:
    """
    Check if ColorRange is limited.
    """
    return bool(self.value)

def is_unspecified(self) -> bool:
    """
    Whether the value is unspecified.
    """
    return False

@cachedproperty
def pretty_string(self) -> str:
    """
    Get a pretty, displayable string of the enum member.
    """
    return self._pretty_string

@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """
    return f"_{cls.__name__}"

@cachedproperty
def string(self) -> str:
    """
    Get the string representation used in resize plugin/encoders.
    """
    return self._string

def apply(self, clip: vs.VideoNode) -> vs.VideoNode:
    """
    Applies the property to the VideoNode.
    """
    return clip.std.SetFrameProp(self.prop_key, self.value)

@classmethod
def ensure_presence(cls, clip: vs.VideoNode, value: Any, func: FuncExcept | None = None) -> vs.VideoNode:
    """
    Ensure the presence of the property in the VideoNode.
    """
    enum_value = cls.from_param_or_video(value, clip, True, func)

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

@staticmethod
def ensure_presences(
    clip: vs.VideoNode, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> vs.VideoNode:
    """
    Ensure the presence of multiple PropEnums at once.
    """
    return clip.std.SetFrameProps(
        **{
            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
            )
        },
    )

@classmethod
def from_param_or_video(
    cls,
    value: Any,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Get the enum member from a value that can be casted to this prop value or grab it from frame properties.

    If `strict=False`, gather the heuristics using the clip's size or format.

    Args:
        value: Value to cast.
        src: Clip to get prop from.
        strict: Be strict about the frame properties. Default: False.
        func_except: Function returned for custom error handling.
    """
    prop = cls.from_param_with_fallback(value, None)

    # Delay the `from_video` call here to avoid unnecessary frame rendering
    if prop is None:
        return cls.from_video(src, strict, func_except)

    return prop

@classmethod
def from_param_with_fallback[T](cls, value: Any, fallback: T | None = None) -> Self | T | None:
    """
    Attempts to obtain an enum member from a parameter value, returning a fallback if the value cannot be converted
    or represents an unspecified enum member.

    Args:
        value: The input value to convert into an enum member.
        fallback: The value to return if the input cannot be converted. Defaults to `None`.

    Returns:
        The corresponding enum member if conversion succeeds, otherwise the provided `fallback` value.
    """
    with suppress(NotFoundEnumValueError, CustomValueError):
        # Will raise a NotFoundEnumValueError if the value can't be casted
        casted = cls.from_param(value)

        # If unspecified, fallbacks to `fallback` value
        if casted.is_unspecified():
            raise CustomValueError

        return casted

    return fallback

@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> Matrix:
    """
    Guess the matrix based on the clip's resolution.

    Args:
        frame: Input clip or frame.

    Returns:
        Matrix object.
    """
    from ..utils import get_var_infos

    fmt, width, height = get_var_infos(frame)

    if fmt.color_family == vs.RGB:
        return Matrix.RGB

    if (width, height) <= (1024, 576):
        return Matrix.ST170_M if height <= 486 else Matrix.BT470_BG

    return Matrix.BT709

@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> Matrix:
    """
    Try to obtain the matrix of a clip from the frame props or fallback to clip's resolution
    if the prop is undefined, strict=False and src is a clip.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the frame props. Will ALWAYS error with Matrix.UNKNOWN.
        func: Function returned for custom error handling.

    Returns:
        Matrix object.

    Raises:
        UndefinedMatrixError: If the matrix is undefined or can not be determined from the frameprops.
    """
    return _base_from_video(cls, src, UndefinedMatrixError, strict, func)

def is_unspecified(self) -> bool:
    """
    Check if the matrix is Matrix.UNSPECIFIED.
    """
    return self is Matrix.UNSPECIFIED

@cachedproperty
def pretty_string(self) -> str:
    """
    Get a pretty, displayable string of the enum member.
    """
    return self._pretty_string

@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """
    return f"_{cls.__name__}"

@cachedproperty
def string(self) -> str:
    """
    Get the string representation used in resize plugin/encoders.
    """
    return self._string

def apply(self, clip: vs.VideoNode) -> vs.VideoNode:
    """
    Applies the property to the VideoNode.
    """
    return clip.std.SetFrameProp(self.prop_key, self.value)

@classmethod
def ensure_presence(cls, clip: vs.VideoNode, value: Any, func: FuncExcept | None = None) -> vs.VideoNode:
    """
    Ensure the presence of the property in the VideoNode.
    """
    enum_value = cls.from_param_or_video(value, clip, True, func)

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

@staticmethod
def ensure_presences(
    clip: vs.VideoNode, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> vs.VideoNode:
    """
    Ensure the presence of multiple PropEnums at once.
    """
    return clip.std.SetFrameProps(
        **{
            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
            )
        },
    )

@classmethod
def from_param_or_video(
    cls,
    value: Any,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Get the enum member from a value that can be casted to this prop value or grab it from frame properties.

    If `strict=False`, gather the heuristics using the clip's size or format.

    Args:
        value: Value to cast.
        src: Clip to get prop from.
        strict: Be strict about the frame properties. Default: False.
        func_except: Function returned for custom error handling.
    """
    prop = cls.from_param_with_fallback(value, None)

    # Delay the `from_video` call here to avoid unnecessary frame rendering
    if prop is None:
        return cls.from_video(src, strict, func_except)

    return prop

@classmethod
def from_param_with_fallback[T](cls, value: Any, fallback: T | None = None) -> Self | T | None:
    """
    Attempts to obtain an enum member from a parameter value, returning a fallback if the value cannot be converted
    or represents an unspecified enum member.

    Args:
        value: The input value to convert into an enum member.
        fallback: The value to return if the input cannot be converted. Defaults to `None`.

    Returns:
        The corresponding enum member if conversion succeeds, otherwise the provided `fallback` value.
    """
    with suppress(NotFoundEnumValueError, CustomValueError):
        # Will raise a NotFoundEnumValueError if the value can't be casted
        casted = cls.from_param(value)

        # If unspecified, fallbacks to `fallback` value
        if casted.is_unspecified():
            raise CustomValueError

        return casted

    return fallback

@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> Primaries:
    """
    Guess the primaries based on the clip's resolution.

    Args:
        frame: Input clip or frame.

    Returns:
        Primaries object.
    """
    from ..utils import get_var_infos

    fmt, width, height = get_var_infos(frame)

    if fmt.color_family == vs.RGB:
        return Primaries.BT709

    if (width, height) <= (1024, 576):
        return Primaries.ST170_M if height <= 486 else Primaries.BT470_BG

    return Primaries.BT709

@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> Primaries:
    """
    Try to obtain the primaries of a clip from the frame props or fallback to clip's resolution
    if the prop is undefined, strict=False and src is a clip.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the frame props. Will ALWAYS error with Primaries.UNKNOWN.
        func: Function returned for custom error handling.

    Returns:
        Primaries object.

    Raises:
        UndefinedPrimariesError: If the primaries are undefined or can not be determined from the frameprops.
    """
    return _base_from_video(cls, src, UndefinedPrimariesError, strict, func)

def is_unspecified(self) -> bool:
    """
    Check if the primaries are Primaries.UNSPECIFIED.
    """
    return self is Primaries.UNSPECIFIED

@cachedproperty
def pretty_string(self) -> str:
    """
    Get a pretty, displayable string of the enum member.
    """
    return self._pretty_string

@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """
    return f"_{cls.__name__}"

@cachedproperty
def string(self) -> str:
    """
    Get the string representation used in resize plugin/encoders.
    """
    return self._string

def apply(self, clip: vs.VideoNode) -> vs.VideoNode:
    """
    Applies the property to the VideoNode.
    """
    return clip.std.SetFrameProp(self.prop_key, self.value)

@classmethod
def ensure_presence(cls, clip: vs.VideoNode, value: Any, func: FuncExcept | None = None) -> vs.VideoNode:
    """
    Ensure the presence of the property in the VideoNode.
    """
    enum_value = cls.from_param_or_video(value, clip, True, func)

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

@staticmethod
def ensure_presences(
    clip: vs.VideoNode, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> vs.VideoNode:
    """
    Ensure the presence of multiple PropEnums at once.
    """
    return clip.std.SetFrameProps(
        **{
            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
            )
        },
    )

@classmethod
def from_param_or_video(
    cls,
    value: Any,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Get the enum member from a value that can be casted to this prop value or grab it from frame properties.

    If `strict=False`, gather the heuristics using the clip's size or format.

    Args:
        value: Value to cast.
        src: Clip to get prop from.
        strict: Be strict about the frame properties. Default: False.
        func_except: Function returned for custom error handling.
    """
    prop = cls.from_param_with_fallback(value, None)

    # Delay the `from_video` call here to avoid unnecessary frame rendering
    if prop is None:
        return cls.from_video(src, strict, func_except)

    return prop

@classmethod
def from_param_with_fallback[T](cls, value: Any, fallback: T | None = None) -> Self | T | None:
    """
    Attempts to obtain an enum member from a parameter value, returning a fallback if the value cannot be converted
    or represents an unspecified enum member.

    Args:
        value: The input value to convert into an enum member.
        fallback: The value to return if the input cannot be converted. Defaults to `None`.

    Returns:
        The corresponding enum member if conversion succeeds, otherwise the provided `fallback` value.
    """
    with suppress(NotFoundEnumValueError, CustomValueError):
        # Will raise a NotFoundEnumValueError if the value can't be casted
        casted = cls.from_param(value)

        # If unspecified, fallbacks to `fallback` value
        if casted.is_unspecified():
            raise CustomValueError

        return casted

    return fallback

@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> Transfer:
    """
    Guess the transfer based on the clip's resolution.

    Args:
        frame: Input clip or frame.

    Returns:
        Transfer object.
    """
    from ..utils import get_var_infos

    fmt, width, height = get_var_infos(frame)

    if fmt.color_family == vs.RGB:
        return Transfer.IEC_61966_2_1

    return Transfer.BT601 if (width, height) <= (1024, 576) else Transfer.BT709