muxtools.subtitle.basesub

class _Line:
    TYPE: str
    """The type of line. Should either be `Dialogue` or `Comment`."""
    layer: int
    """An integer value in the range `[0, 2³¹-1]`. Events with a lower Layer value are placed behind events with a higher value."""
    start: timedelta
    """Start of this line as a timedelta."""
    end: timedelta
    """End of this line as a timedelta."""
    style: str
    """Style name used for this line. Must exactly match one of the styles in your subtitle file."""
    name: str
    """Usually used for what character is currently speaking. Known as `Actor` in aegisub."""
    margin_l: int
    """Left margin overriding the value in the current style."""
    margin_r: int
    """Right margin overriding the value in the current style."""
    margin_v: int
    """Vertical margin overriding the value in the current style."""
    effect: str
    """A legacy effect to be applied to the event. Can usually also be used as another freeform field."""
    text: str
    """The text displayed (or not, if this is a Comment)"""

class ShiftMode(Enum):
    FRAME = "frame"
    """Shift lines by converting everything (including the offset) to a frame."""
    TIME = "time"
    """Shift lines directly by using the offset as a timedelta.\nYou have to use this if you want to match subKT."""

class ASSHeader(IntEnum):
    """
    Basic enum class for some functional ASS headers.\n
    Check https://github.com/libass/libass/wiki/ASS-File-Format-Guide for more information on each member.

    Also contains the function to validate the input.
    """

    LayoutResX = 1
    """Video width this subtitle was originally authored on."""
    LayoutResY = 2
    """Video height this subtitle was originally authored on."""
    PlayResX = 3
    """Video width this subtitle is used on."""
    PlayResY = 4
    """Video height this subtitle is used on."""
    WrapStyle = 5
    """The default line-wrapping behaviour."""
    ScaledBorderAndShadow = 6
    """Scale border and shadow with playback resolution. Should ideally always be yes."""
    YCbCr_Matrix = 7
    """The color range and matrix this subtitle was authored for."""

    def validate_input(self, value: str | int | bool | None, caller: Any = None) -> str | int | None:
        if self in range(1, 6) and not isinstance(value, int) and value is not None:
            raise error(f"{self.name} needs to be an integer!", caller)
        if self == 5 and value not in range(3) and value is not None:
            raise error(f"The valid values for {self.name} are 0, 1 and 2.", caller)

        if self == 6 and value is not None:
            if not isinstance(value, bool) and str(value).lower() not in ["yes", "no"]:
                raise error(f"The valid values for {self.name} are 'yes', 'no' or a boolean with the same meaning.", caller)
            if str(value).lower() == "no" or value is False:
                warn(f"There's practically no good reason for {self.name} to be 'no'. Carry on if you are sure.", caller, 1)
            if isinstance(value, bool):
                return "yes" if value else "no"
            return str(value).lower()

        if self == 7 and value is not None:
            if not isinstance(value, str):
                raise error(f"{self.name} needs to be a string!", caller)
            if not value.startswith(("TV.", "PC.")):
                raise error(f"{self.name} needs to start with a range value of either 'TV' or 'PC'!", caller)
            known_matrices = ["601", "709", "240M", "FCC"]
            contains_known = False
            for matrix in known_matrices:
                if matrix in value:
                    contains_known = True
            if not contains_known:
                joined = ", ".join(known_matrices)
                warn(f"{self.name} doesn't contain a known valid matrix! ({joined})", caller, 1)

        return value

def __init__(
    self,
    file: PathLike | Sequence[PathLike] | GlobSearch,
    container_delay: int = 0,
    source: PathLike | None = None,
    tags: dict[str, str] | None = None,
    encoding: str = "utf_8_sig",
):
    super().__init__(ensure_path(file, self), container_delay, source, tags)
    self.encoding = encoding

class OutOfBoundsMode(IntEnum):
    """How lines that are below 0 after shifting/merging should be handled"""

    ERROR = 0
    """Raise an error"""
    SET_TO_ZERO = 1
    """Set both start and end to 0. Essentially disabling the line."""
    MAX_TO_ZERO = 2
    """Set the start to 0 and the end to what it would be after shifting or also 0 if also below 0."""
    DROP_LINE = 3
    """Don't include the line in the output at all."""