convert

ExtrapolatingVideoTimestamps

Bases: VideoTimestamps

Simple class extending VideoTimestamps to add back extrapolation for frames past the video.

This works by getting the average framerate from the existing timestamps and assuming CFR from then on.

Source code in muxtools/utils/convert.py

class ExtrapolatingVideoTimestamps(VideoTimestamps):
    """
    Simple class extending VideoTimestamps to add back extrapolation for frames past the video.\n
    This works by getting the average framerate from the existing timestamps and assuming CFR from then on.
    """

    backing_fps_timestamps: FPSTimestamps

    def __init__(
        self,
        pts_list: list[int],
        time_scale: Fraction,
        normalize: bool = True,
        rounding_method: RoundingMethod = RoundingMethod.ROUND,
    ):
        super().__init__(pts_list, time_scale, normalize)

        # https://github.com/TypesettingTools/Aegisub/blob/a63edfe8bbf146c89744a3441907541ba7d8ed25/libaegisub/common/vfr.cpp#L154
        fps = Fraction((len(self.pts_list) - 1) * time_scale, self.pts_list[-1] - self.pts_list[0])
        self.backing_fps_timestamps = FPSTimestamps(rounding_method, time_scale, fps, self.first_timestamps)

    def _time_to_frame(
        self,
        time: Fraction,
        time_type: TimeType,
    ) -> int:
        if time > self.timestamps[-1]:
            return self.backing_fps_timestamps._time_to_frame(time, time_type)

        return super()._time_to_frame(time, time_type)

    def _frame_to_time(
        self,
        frame: int,
    ) -> Fraction:
        if frame > self.nbr_frames:
            return self.backing_fps_timestamps._frame_to_time(frame)

        return super()._frame_to_time(frame)

format_timedelta(time, precision=3)

Formats a timedelta to hh:mm:ss.s[*precision] and pads with 0 if there aren't more numbers to work with. Mostly to be used for ogm/xml files.

Parameters:

Name	Type	Description	Default
time	timedelta	The timedelta	required
precision	int	3 = milliseconds, 6 = microseconds, 9 = nanoseconds	3

Returns:

Type	Description
str	The formatted string

Source code in muxtools/utils/convert.py

def format_timedelta(time: timedelta, precision: int = 3) -> str:
    """
    Formats a timedelta to hh:mm:ss.s[*precision] and pads with 0 if there aren't more numbers to work with.
    Mostly to be used for ogm/xml files.

    :param time:        The timedelta
    :param precision:   3 = milliseconds, 6 = microseconds, 9 = nanoseconds

    :return:            The formatted string
    """
    dec = Decimal(time.total_seconds())
    pattern = "." + "".join(["0"] * (precision - 1)) + "1"
    rounded = float(dec.quantize(Decimal(pattern), rounding=ROUND_HALF_DOWN))
    s = trunc(rounded)
    m = s // 60
    s %= 60
    h = m // 60
    m %= 60
    return f"{h:02d}:{m:02d}:{s:02d}.{str(rounded).split('.')[1].ljust(precision, '0')}"

get_timemeta_from_video(video_file, index=0, out_file=None, metadata=None, caller=None)

Parse timestamps from an existing video file using ffprobe.

They're saved as a custom meta file in the current workdir and named based on the input.

Also automatically reused (with a debug log) if already exists.

Parameters:

Name	Type	Description	Default
video_file	PathLike	Input video. Path or String.	required
index	int	Relative video track index.	0
out_file	PathLike | None	Output file. If None given, the above behavior applies.	None
caller	Any | None	Caller used for the logging	None

Returns:

Type	Description
VideoMeta	Videometa object

Source code in muxtools/utils/convert.py

def get_timemeta_from_video(
    video_file: PathLike, index: int = 0, out_file: PathLike | None = None, metadata: ParsedFile | None = None, caller: Any | None = None
) -> VideoMeta:
    """
    Parse timestamps from an existing video file using ffprobe.\n
    They're saved as a custom meta file in the current workdir and named based on the input.

    Also automatically reused (with a debug log) if already exists.

    :param video_file:      Input video. Path or String.
    :param index:           Relative video track index.
    :param out_file:        Output file. If None given, the above behavior applies.
    :param caller:          Caller used for the logging

    :return:                Videometa object
    """
    video_file = ensure_path_exists(video_file, get_timemeta_from_video)
    assert get_executable("ffprobe")

    if not out_file:
        out_file = get_workdir() / f"{video_file.stem}_{index}_meta.json"

    if not metadata:
        metadata = ParsedFile.from_file(video_file, caller, False)

    out_file = ensure_path(out_file, get_timemeta_from_video)
    if not out_file.exists() or out_file.stat().st_size < 1:
        info(f"Generating timestamps for track {index} in '{video_file.name}'...", caller)
        video_tracks = metadata.find_tracks(type=TrackType.VIDEO, relative_id=index, error_if_empty=True, caller=caller or get_timemeta_from_video)
        timestamps = VideoTimestamps.from_video_file(video_file, video_tracks[0].index)
        meta = VideoMeta(timestamps.pts_list, timestamps.fps, timestamps.time_scale, str(video_file.resolve()))
        with open(out_file, "w", encoding="utf-8") as f:
            f.write(meta.to_json())
    else:
        meta = VideoMeta.from_json(out_file)
        debug(f"Reusing existing timestamps for '{video_file.name}'", caller)
    return meta

resolve_timesource_and_scale(timesource=None, timescale=None, rounding_method=RoundingMethod.ROUND, allow_warn=True, fetch_from_setup=False, caller=None)

Instantiates a timestamps class from various inputs.

Parameters:

Name	Type	Description	Default
timesource	PathLike | Fraction | float | list[int] | VideoMeta | ABCTimestamps | tuple[Path | str, int] | None	The source of timestamps/timecodes. For actual timestamps, this can be a timestamps (v1/v2/v4) file, a muxtools VideoMeta json file, a video file or a list of integers. For FPS based timestamps, this can be a Fraction object, a float or even a string representing a fraction. Like '24000/1001'. (None will also fallback to this and print a warning)	None
timescale	TimeScale | Fraction | int | None	Unit of time (in seconds) in terms of which frame timestamps are represented. While you can pass an int, the needed type is always a Fraction and will be converted via Fraction(your_int). If None falls back to a generic Matroska timescale.	None
rounding_method	RoundingMethod	The rounding method used to round/floor the PTS (Presentation Time Stamp).	ROUND
allow_warn	bool	Allow this function to print warnings. If you know what you're doing feel free to disable this for your own use.	True
fetch_from_setup	bool	Whether or not this function should fallback to the sub defaults from the current Setup.	False
caller	Any | None	Caller used for the logging	None

Returns:

Type	Description
ABCTimestamps	Instantiated timestamps object from the videotimestamps library

Source code in muxtools/utils/convert.py

def resolve_timesource_and_scale(
    timesource: PathLike | Fraction | float | list[int] | VideoMeta | ABCTimestamps | tuple[Path | str, int] | None = None,
    timescale: TimeScale | Fraction | int | None = None,
    rounding_method: RoundingMethod = RoundingMethod.ROUND,
    allow_warn: bool = True,
    fetch_from_setup: bool = False,
    caller: Any | None = None,
) -> ABCTimestamps:
    """
    Instantiates a timestamps class from various inputs.

    :param timesource:          The source of timestamps/timecodes.\n
                                For actual timestamps, this can be a timestamps (v1/v2/v4) file, a muxtools VideoMeta json file, a video file or a list of integers.\n
                                For FPS based timestamps, this can be a Fraction object, a float or even a string representing a fraction.\n
                                Like `'24000/1001'`. (`None` will also fallback to this and print a warning)

    :param timescale:           Unit of time (in seconds) in terms of which frame timestamps are represented.\n
                                While you can pass an int, the needed type is always a Fraction and will be converted via `Fraction(your_int)`.\n
                                If `None` falls back to a generic Matroska timescale.

    :param rounding_method:     The rounding method used to round/floor the PTS (Presentation Time Stamp).
    :param allow_warn:          Allow this function to print warnings. If you know what you're doing feel free to disable this for your own use.
    :param fetch_from_setup:    Whether or not this function should fallback to the sub defaults from the current Setup.
    :param caller:              Caller used for the logging

    :return:                    Instantiated timestamps object from the videotimestamps library
    """
    if fetch_from_setup:
        if timesource is None and (setup_timesource := get_setup_attr("sub_timesource", None)) is not None:
            if not isinstance(setup_timesource, TimeSourceT):
                raise error("Invalid timesource type in Setup!", caller)
            debug("Using default timesource from setup.", caller)
            timesource = setup_timesource
        if timescale is None and (setup_timescale := get_setup_attr("sub_timescale", None)) is not None:
            if not isinstance(setup_timescale, TimeScaleT):
                raise error("Invalid timescale type in Setup!", caller)
            debug("Using default timescale from setup.", caller)
            timescale = setup_timescale

    if timesource is None:
        if allow_warn:
            warn("No timesource was given, generating timestamps for FPS (24000/1001).", caller)
        timescale = _check_timescale(timescale)
        return FPSTimestamps(rounding_method, timescale, Fraction(24000, 1001))

    if isinstance(timesource, VideoMeta):
        return ExtrapolatingVideoTimestamps(timesource.pts, timesource.timescale, rounding_method=rounding_method)

    if isinstance(timesource, ABCTimestamps):
        return timesource

    if isinstance(timesource, Path) or isinstance(timesource, str) or (isinstance(timesource, tuple) and isinstance(timesource[1], int)):
        timesource_path = timesource if not isinstance(timesource, tuple) else timesource[0]
        timesource_index = 0 if not isinstance(timesource, tuple) else timesource[1]
        if isinstance(timesource_path, Path) or os.path.isfile(timesource_path):
            timesource = ensure_path(timesource_path, caller)
            return _handle_file_timesource(timesource, timesource_index, timescale, rounding_method, allow_warn, fetch_from_setup, caller)

    elif isinstance(timesource, list) and isinstance(timesource[0], int):
        timescale = _check_timescale(timescale)
        return ExtrapolatingVideoTimestamps(timesource, timescale, rounding_method=rounding_method)

    if isinstance(timesource, float) or isinstance(timesource, str) or isinstance(timesource, Fraction):
        fps = Fraction(timesource)
        timescale = _check_timescale(timescale)
        return FPSTimestamps(rounding_method, timescale, fps)

    raise crit("Invalid timesource passed!", caller)

sizeof_fmt(num, unit='B')

Human readable file size.

Parameters:

Name	Type	Description	Default
num		File size in bytes/bits	required
unit		Unit to use (change to "b" for bits)	'B'

Returns:

Type	Description
	Formatted size

Source code in muxtools/utils/convert.py

def sizeof_fmt(num, unit="B"):
    """
    Human readable file size.

    :param num:        File size in bytes/bits
    :param unit:       Unit to use (change to "b" for bits)

    :return:           Formatted size
    """
    for prefix in ("", "Ki", "Mi", "Gi", "Ti", "Pi", "Ei", "Zi", "Yi", "Ri"):
        if abs(num) < 1024.0:
            return f"{num:3.1f} {prefix}{unit}"
        num /= 1024.0
    return f"{num:.1f}Qi{unit}"

timedelta_from_formatted(formatted)

Parses a string with the format of hh:mm:ss.sss Mostly to be used for ogm/xml files.

Parameters:

Name	Type	Description	Default
formatted	str	The timestamp string	required

Returns:

Type	Description
timedelta	The parsed timedelta

Source code in muxtools/utils/convert.py

def timedelta_from_formatted(formatted: str) -> timedelta:
    """
    Parses a string with the format of hh:mm:ss.sss
    Mostly to be used for ogm/xml files.

    :param formatted:       The timestamp string

    :return:                The parsed timedelta
    """
    # 00:05:25.534...
    split = formatted.split(":")
    seconds = Decimal(split[0]) * Decimal(3600)
    seconds = seconds + (Decimal(split[1]) * Decimal(60))
    seconds = seconds + (Decimal(split[2]))
    return timedelta(seconds=seconds.__float__())