muxtools.subtitle.sub

def to_track(self, *args) -> Attachment:
    return Attachment(self.file)

def manipulate_lines(self, func: Callable[[LINES], LINES | None]) -> Self:
    """
    Function to manipulate any lines.

    :param func:        Your own function you want to run on the list of lines.
                        This can return a new list or just edit the one passed into it.
    """
    super()._manipulate_lines(func)
    return self

def set_header(self, header: str | ASSHeader, value: str | int | bool | None) -> Self:
    """
    A function to add headers to the "Script Info" section of the subtitle file.
    This will validate the input for known functional headers but also allows arbitrary ones.
    If you're planning on setting multiple at the same time, use the `set_headers` function instead to avoid a lot of I/O.

    :param header:      The name of the header or a header chosen from the enum.
    :param value:       The value of the header. None will remove the header unless it's the Matrix header because None has a meaning there.
    """
    super()._set_header(header, value)
    return self

def set_headers(self, *headers: tuple[str | ASSHeader, str | int | bool | None]) -> Self:
    """
    A function to add headers to the "Script Info" section of the subtitle file.
    This will validate the input for known functional headers but also allows arbitrary ones.

    :param headers:     Any amount of tuples with the same typing as the single header function.
    """
    doc = self._read_doc()
    for header, value in headers:
        super()._set_header(header, value, doc)
    self._update_doc(doc)
    return self

def clean_styles(self) -> Self:
    """
    Deletes unused styles from the document.
    """
    doc = self._read_doc()
    used_styles = {line.style for line in doc.events if line.TYPE == "Dialogue"}
    regex = re.compile(r"\{[^}]*\\r([^\\}]+)[^}]*\}")
    for line in [line for line in doc.events if line.TYPE == "Dialogue"]:
        for match in regex.finditer(line.text):
            used_styles.add(match.group(1))
    doc.styles = [style for style in doc.styles if style.name in used_styles]
    self._update_doc(doc)
    return self

def clean_garbage(self) -> Self:
    """
    Removes the "Aegisub Project Garbage" section from the file.
    """
    doc = self._read_doc()
    doc.sections.pop("Aegisub Project Garbage", None)
    self._update_doc(doc)
    return self

def clean_extradata(self) -> Self:
    """
    Removes the "Aegisub Extradata" section from the file.
    """
    doc = self._read_doc()
    doc.sections.pop("Aegisub Extradata", None)
    self._update_doc(doc)
    return self

def clean_comments(self) -> Self:
    """
    Removes all comment lines from the file.
    """
    return self.manipulate_lines(lambda lines: list(filter(lambda line: str(line.TYPE).lower() != "comment", lines)))

def autoswapper(
    self,
    allowed_styles: list[str] | None = DEFAULT_DIALOGUE_STYLES,
    print_swaps: bool = False,
    inline_marker: str = "*",
    line_marker: str = "***",
    inline_tag_markers: str | None = None,
    exact_names: bool = True,
) -> Self:
    r"""
    autoswapper allows replacing text in the script with a different text.
    Useful for creating honorific tracks.

    Assuming the markers are as default:

    - `{*}abc{*def}` becomes `{*}def{*abc}` (AB Swap)
    - `abc{**def}` becomes `abc{*}def{*}` (Show Word)
    - `abc{*}def{*}` becomes `abc{**def}` (Hide Word)

    Note: AB Swap and Hide Word will remove `{}` from the swapped text, to ensure the comment isn't broken.

    You can also comment in or out entire lines by using the line marker in either the `effect` or `name` field.
    - A dialogue line with effect or name set to `***` will be commented.
    - A comment line with effect or name set to `***` will be set to a dialogue.


    `inline_tag_markers` can be used to swap ASS tags as well. Keep in mind that "\" and "/" will be swapped, so override tags aren't applied.

    Assuming the markers are as default, except inline_tag_markers = `[]`:
    - `{*}{\i1}abc{*[/b1]def}` becomes `{*}{\b1}def{*[/i1]abc}` (AB Swap)
    - `abc{**[/b1]def}` becomes `abc{*}{\b1}def{*}` (Show Word)
    - `abc{*}{\b1}def{*}` becomes `abc{**[/b1]def}` (Hide Word)


    :param allowed_styles:          List of allowed styles to do the swapping on (case insensitive)
                                    Will run on every line if passed `None`
    :param print_swaps:             Prints the swaps
    :param inline_marker:           Marker to use for inline swaps.
                                    Should be one character. Default `*`
    :param line_marker:             Marker to use for full-line swaps. Default `***`
    :param inline_tag_markers:      Two characters that will be replaced with `{}` respectively in the inline swaps.
                                    Defaults to `None`, which will just remove the `{}` from the swapped text.
    :param exact_names:             Match style names in full instead of substring matching as mentioned above. (still case-insensitive)

    :return:                        This SubTrack
    """
    if not isinstance(inline_marker, str) or not inline_marker.strip():
        warn("Given invalid inline marker. Using default '*'.", self)
        inline_marker = "*"

    if not isinstance(line_marker, str) or not line_marker.strip():
        warn("Given invalid line marker. Using default '***'.", self)
        line_marker = "***"

    if inline_tag_markers:
        if len(inline_tag_markers) != 2 or inline_tag_markers[0] == inline_tag_markers[1] or any([m in "{}" for m in inline_tag_markers]):
            warn("Given invalid inline comment markers. Using default 'None'.", self)
            inline_tag_markers = None

    marker = re.escape(inline_marker)

    ab_swap_regex = re.compile(rf"{{{marker}}}(.*?){{{marker}([^}}]+)}}")
    show_word_regex = re.compile(rf"{{{marker}{marker}([^}}]+)}}")
    hide_word_regex = re.compile(rf"{{{marker}}}(.*?){{{marker} *}}")

    backslash = "\\"  # This is to ensure support for previous python versions that don't allow backslashes in f-strings.

    def _do_autoswap(lines: LINES):
        from rich.markup import escape as log_escape

        for i, line in enumerate(lines):
            if not allowed_styles or name_matches_style(str(line.style), allowed_styles, exact_names):
                to_swap: dict = {}
                # {*}This will be replaced{*With this}
                for match in re.finditer(ab_swap_regex, line.text):
                    if inline_tag_markers:
                        to_swap.update(
                            {
                                f"{match.group(0)}": f"{{{inline_marker}}}{match.group(2).replace(inline_tag_markers[0], '{').replace(inline_tag_markers[1], '}').replace('/', backslash)}{{{inline_marker}{match.group(1).replace('{', inline_tag_markers[0]).replace('}', inline_tag_markers[1]).replace(backslash, '/')}}}"
                            }
                        )
                    else:
                        to_swap.update(
                            {
                                f"{match.group(0)}": f"{{{inline_marker}}}{match.group(2)}{{{inline_marker}{match.group(1).replace('{', '').replace('}', '')}}}"
                            }
                        )

                # This sentence is no longer{** incomplete}
                for match in re.finditer(show_word_regex, line.text):
                    if inline_tag_markers:
                        to_swap.update(
                            {
                                f"{match.group(0)}": f"{{{inline_marker}}}{match.group(1).replace(inline_tag_markers[0], '{').replace(inline_tag_markers[1], '}').replace('/', backslash)}{{{inline_marker}}}"
                            }
                        )
                    else:
                        to_swap.update({f"{match.group(0)}": f"{{{inline_marker}}}{match.group(1)}{{{inline_marker}}}"})

                # This sentence is no longer{*} complete{*}
                for match in re.finditer(hide_word_regex, line.text):
                    if inline_tag_markers:
                        to_swap.update(
                            {
                                f"{match.group(0)}": f"{{{inline_marker * 2}{match.group(1).replace('{', inline_tag_markers[0]).replace('}', inline_tag_markers[1]).replace(backslash, '/')}}}"
                            }
                        )
                    else:
                        to_swap.update({f"{match.group(0)}": f"{{{inline_marker * 2}{match.group(1).replace('{', '').replace('}', '')}}}"})

                for key, val in to_swap.items():
                    if print_swaps:
                        info(f'autoswapper: Swapped "{log_escape(key)}" for "{log_escape(val)}" on line {i}', self)
                    line.text = line.text.replace(key, val)

                if line.effect.strip() == line_marker or line.name.strip() == line_marker:
                    if isinstance(line, Comment):
                        line.TYPE = "Dialogue"
                        if print_swaps:
                            info(f'autoswapper: Uncommented Line {i} - "{log_escape(cast(_Line, line).text)}"', self)
                    elif isinstance(line, Dialogue):
                        line.TYPE = "Comment"
                        if print_swaps:
                            info(f'autoswapper: Commented Line {i} - "{log_escape(cast(_Line, line).text)}"', self)

    self.manipulate_lines(_do_autoswap)
    return self

def unfuck_cr(
    self,
    default_style: str = "Default",
    keep_flashback: bool = True,
    dialogue_styles: list[str] | None = ["main", "default", "narrator", "narration", "bottomcenter"],
    top_styles: list[str] | None = ["top"],
    italics_styles: list[str] | None = ["italics", "internal"],
    alt_style: str = "Alt",
    alt_styles: list[str] | None = None,
    exact_names: bool = False,
    custom_replacements: dict[str, str] | dict[str, tuple[str, int, int]] = CCC_REPLACEMENTS_REDUCED_MARGINS,
) -> Self:
    """
    Removes any top/positional and italics styles and replaces them with tags.

    Style names are case-insensitive and use substring matching.
    i.e. if `top_styles=["top"]`, `"MainTop"` or `"main_top"` would both be considered top styles.

    :param default_style:       The default style that everything will be set to
    :param keep_flashback:      If not it will set the flashback styles to default_style
    :param dialogue_styles:     Styles that will be set to default_style
    :param top_styles:          Styles that will be set to default_style and an8 added to tags
    :param italics_styles:      Styles that will be set to default_style and i1 added to tags
    :param alt_style:           The default alt/overlap style that lines will be set to
    :param alt_styles:          Possible identifiers for styles that should be set to the alt_style
    :param exact_names:         Match style names in full instead of substring matching as mentioned above. (still case-insensitive)

    :param custom_replacements: Other styles to replace with Default and where custom tags might want to be prepended.\n
                                If any of these get matched then the other operations will be skipped.\n
                                Defaults to the positional Styles (with custom margins) that the annoying CCC subs from Crunchyroll have.\n
                                Keep in mind that the margins of the restyle presets might not look great for these positional styles.\n
                                The tuple value option stands for (TagsToPrepend, MarginL, MarginR).
    """

    def name_matches(name: str, other: str) -> bool:
        if exact_names:
            return name.casefold() == other.casefold()
        else:
            return name.casefold() in other.casefold()

    def get_default(line: _Line, allow_default: bool = True) -> str:
        placeholder = default_style
        is_default = True
        if alt_styles:
            for s in alt_styles:
                if name_matches(s, line.style):
                    placeholder = alt_style
                    is_default = False
        if "flashback" in line.style.lower():
            return placeholder if not keep_flashback else "Flashback"

        if is_default:
            return placeholder if allow_default else line.style

        return placeholder

    def _func(lines: LINES):
        for line in lines:
            custom_match = False
            if custom_replacements and bool(match := next(filter(lambda x: name_matches(x, line.style), custom_replacements.keys()), None)):
                custom_match = True
                line.style = get_default(line)
                value = custom_replacements[match]  # type: ignore # fuck off mypy
                line.text = f"{{{value if isinstance(value, str) else value[0]}}}{line.text}"
                if not isinstance(value, str):
                    line.margin_l = value[1]
                    line.margin_r = value[2]

            if custom_match:
                continue

            add_italics_tag = italics_styles and bool([s for s in italics_styles if name_matches(s, line.style)])
            add_top_tag = top_styles and bool([s for s in top_styles if name_matches(s, line.style)])

            if any([add_italics_tag, add_top_tag]):
                line.style = get_default(line)
                tags = "" if not add_italics_tag else R"\i1"
                tags = tags if not add_top_tag else tags + R"\an8"
                line.text = f"{{{tags}}}{line.text}"

            line.style = get_default(line, False)

            if dialogue_styles:
                for s in dialogue_styles:
                    if s.casefold() in line.style.casefold():
                        line.style = default_style

    return self.manipulate_lines(_func).clean_styles()

def shift_0(
    self,
    timesource: TimeSourceT = None,
    timescale: TimeScaleT = None,
    allowed_styles: list[str] | None = DEFAULT_DIALOGUE_STYLES,
) -> Self:
    """
    Does the famous shift by 0 frames to fix frame timing issues.
    (It's basically just converting time to frame and back)

    This does not currently exactly reproduce the aegisub behaviour but it should have the same effect.

    :param timesource:      The source of timestamps/timecodes. For details check the docstring on the type.
    :param timescale:       Unit of time (in seconds) in terms of which frame timestamps are represented.\n
                            For details check the docstring on the type.
    :param allowed_styles:  A list of style names this is run on (case-insensitive).
                            Runs on every line if None.
    """
    resolved_ts = resolve_timesource_and_scale(timesource, timescale, fetch_from_setup=True, caller=self)

    def _func(lines: LINES):
        for line in lines:
            if not allowed_styles or line.style.casefold() in {style.casefold() for style in allowed_styles}:
                result = self._shift_line_by_frames(line, 0, resolved_ts, OutOfBoundsMode.ERROR)
                line = result.line

    return self.manipulate_lines(_func)

def merge(
    self,
    file: PathLike | GlobSearch | FileMixin,
    sync: None | int | str = None,
    sync2: None | str = None,
    timesource: TimeSourceT = None,
    timescale: TimeScaleT = None,
    use_actor_field: bool = False,
    no_error: bool = False,
    sort_lines: bool = False,
    shift_mode: ShiftMode = ShiftMode.FRAME,
    oob_mode: OutOfBoundsMode = OutOfBoundsMode.ERROR,
) -> Self:
    """
    Merge another subtitle file with syncing if needed.

    :param file:            The file to be merged.
    :param sync:            Can be None to not adjust timing at all, an int for a frame number or a string for a syncpoint name.
    :param sync2:           The syncpoint you want to use for the second file.
                            This is needed if you specified a frame for sync and still want to use a specific syncpoint.
    :param timesource:      The source of timestamps/timecodes. For details check the docstring on the type.
    :param timescale:       Unit of time (in seconds) in terms of which frame timestamps are represented.\n
                            For details check the docstring on the type.
    :param use_actor_field: Checks the actor field instead of effect for the names if True.
    :param no_error:        Don't error and warn instead if syncpoint not found.
    :param sort_lines:      Sort the lines by the starting timestamp.
                            This was done by default before but may cause issues with subtitles relying on implicit layering.
    :param shift_mode:      Choose what to shift by. Defaults to shifting by frames.
    :param oob_mode:        What to do with lines that are out of bounds after shifting.
    """
    resolved_ts = None
    if sync is not None or sync2 is not None and shift_mode == ShiftMode.FRAME:
        resolved_ts = resolve_timesource_and_scale(timesource, timescale, fetch_from_setup=True, caller=self)

    file = ensure_path_exists(file, self)
    mergedoc = self._read_doc(file)
    doc = self._read_doc()
    doc_name = ensure_path_exists(self.file, self).name if str(self.source).lower().endswith(".mkv") else ensure_path(self.source, self).name
    self._warn_mismatched_properties(doc, mergedoc, doc_name, file.name)

    events = []
    tomerge = []
    existing_styles = [style.name for style in doc.styles]
    target = None if not isinstance(sync, int) else sync

    # Find syncpoint in current document if sync is a string
    for line in doc.events:
        events.append(line)
        line = cast(_Line, line)
        if target is None and isinstance(sync, str):
            field = line.name if use_actor_field else line.effect
            if field.lower().strip() == sync.lower().strip() or line.text.lower().strip() == sync.lower().strip():
                if shift_mode == ShiftMode.FRAME:
                    assert resolved_ts is not None
                    target = resolved_ts.time_to_frame(int(line.start.total_seconds() * 1000), TimeType.START, 3)
                else:
                    target = line.start

    if target is None and isinstance(sync, str):
        msg = f"Syncpoint '{sync}' was not found."
        if no_error:
            warn(msg, self)
            return self
        raise error(msg, self)

    mergedoc.events = cast(list[_Line], mergedoc.events)

    # Find second syncpoint if any
    second_sync: int | timedelta | None = None
    for line in mergedoc.events:
        if not isinstance(sync, str) and not sync2:
            break
        elif not isinstance(sync, int):
            sync2 = sync2 or sync
        if not sync2:
            break
        field = line.name if use_actor_field else line.effect
        if field.lower().strip() == sync2.lower().strip() or line.text.lower().strip() == sync2.lower().strip():
            if shift_mode == ShiftMode.FRAME:
                assert resolved_ts is not None
                second_sync = resolved_ts.time_to_frame(int(line.start.total_seconds() * 1000), TimeType.START, 3)
            else:
                second_sync = line.start
            mergedoc.events.remove(line)
            break

    sorted_lines = sorted(mergedoc.events, key=lambda event: event.start)

    # Assume the first line to be the second syncpoint if none was found
    if second_sync is None and target is not None:
        for line in filter(lambda event: event.TYPE != "Comment", sorted_lines):
            if shift_mode == ShiftMode.FRAME:
                assert resolved_ts is not None
                second_sync = resolved_ts.time_to_frame(int(line.start.total_seconds() * 1000), TimeType.START, 3)
            else:
                second_sync = line.start
            break

    # Merge lines from file
    for line in sorted_lines if sort_lines else mergedoc.events:
        # Don't apply any offset if sync=None for plain merging or if target == source
        if target is None or target == second_sync:
            tomerge.append(line)
            continue

        if shift_mode == ShiftMode.FRAME:
            assert isinstance(target, int)
            assert isinstance(second_sync, int)
            assert resolved_ts is not None
            offset = target - second_sync
            line_result = self._shift_line_by_frames(line, offset, resolved_ts, oob_mode)
        else:
            assert isinstance(target, timedelta)
            assert isinstance(second_sync, timedelta)
            offset = target - second_sync
            line_result = self._shift_line_by_time(line, offset, oob_mode)

        if line_result.was_out_of_bounds:
            warn(f"Line is out of bounds: {line.start} - {line.end}:\n\t{line.text}", self)
            if oob_mode == OutOfBoundsMode.DROP_LINE:
                continue

        tomerge.append(line_result.line)

    if tomerge:
        events.extend(tomerge)
        doc.events = events
        for style in mergedoc.styles:
            if style.name in existing_styles:
                continue
            doc.styles.append(style)

    self._update_doc(doc)
    return self

def collect_fonts(
    self,
    use_system_fonts: bool = True,
    search_current_dir: bool = True,
    additional_fonts: list[PathLike] = [],
    collect_draw_fonts: bool = True,
    error_missing: bool = False,
    use_ntfs_compliant_names: bool | None = None,
) -> list[FontFile]:
    """
    Collects fonts for current subtitle.
    Note that this places all fonts into the workdir for the episode/Setup and all fonts in it.

    :param use_system_fonts:            Parses and checks against all installed fonts
    :param search_current_dir:          Recursively checks the current work directory for fonts
    :param additional_fonts:            Can be a directory or a path to a file directly (or a list of either)
    :param collect_draw_fonts:          Whether or not to include fonts used for drawing (usually Arial)
                                        See https://github.com/libass/libass/issues/617 for details.
    :param error_missing:               Raise an error instead of just warnings when a font is missing.\n
                                        This is **deprecated** and will be removed at some point in the future.
                                        Please use `error_on_danger` in the Setup.
    :param use_ntfs_compliant_names:    Ensure that filenames will work on a NTFS (Windows) filesystem.
                                        The `None` default means it'll use them but only if you're running the script on windows.

    :return:                        A list of FontFile objects
    """

    if not isinstance(additional_fonts, list):
        additional_fonts = [additional_fonts]

    if search_current_dir:
        additional_fonts.append(os.getcwd())

    resolved_paths: list[Path] = []

    for f in additional_fonts:
        f = ensure_path_exists(f, self, True)
        if f.is_dir():
            resolved_paths.extend([file for file in f.rglob("*.[tT][tT][fF]")])
            resolved_paths.extend([file for file in f.rglob("*.[oO][tT][fF]")])
            resolved_paths.extend([file for file in f.rglob("*.[tT][tT][cC]")])
            resolved_paths.extend([file for file in f.rglob("*.[oO][tT][cC]")])
        else:
            if f.suffix.lower() not in [".ttf", ".otf", ".ttc", ".otc"]:
                raise error(f"'{f.name}' is not a font!", self)
            resolved_paths.append(f)
    from .font import collect_fonts as collect

    info(f"Collecting fonts for '{self.file.stem}'...", self)

    if error_missing:
        warn("The 'error_missing' parameter is deprecated.\nPlease use the 'error_on_danger' variable on the Setup.", self, 1)

    if use_ntfs_compliant_names is None:
        use_ntfs_compliant_names = os.name == "nt"

    return collect(self, use_system_fonts, resolved_paths, collect_draw_fonts, error_missing, use_ntfs_compliant_names)

def restyle(self, styles: Style | list[Style], clean_after: bool = True, delete_existing: bool = False, adjust_styles: bool = True) -> Self:
    """
    Add (and replace existing) styles to the subtitle file.

    :param styles:          Either a single or a list of ass Styles
    :param clean_after:     Clean unused styles after
    :param delete_existing: Delete all existing styles before adding new ones
    :param adjust_styles:   Resize the styles to match the script resolution.
                            This assumes 1080p for the actual style res as all the presets are that.
    """
    if not isinstance(styles, list):
        styles = [styles]

    styles = styles.copy()

    doc = self._read_doc()
    script_res = int(doc.info.get("PlayResY", 360))
    if script_res != 1080 and adjust_styles:
        styles = resize_preset(styles, script_res)

    if delete_existing:
        doc.styles = []

    names = [cast(str, style.name).casefold() for style in styles]
    existing = [style for style in doc.styles if style.name.casefold() not in names]
    styles.extend(existing)
    doc.styles = styles

    self._update_doc(doc)
    if clean_after:
        return self.clean_styles()
    else:
        return self