VideoTimestamps 0.0.1__py3-none-any.whl

VideoTimestamps-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 moi15moi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

VideoTimestamps-0.0.1.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.1
+Name: VideoTimestamps
+Version: 0.0.1
+Summary: Get video timestamps.
+Author-email: moi15moi <moi15moismokerlolilol@gmail.com>
+License: MIT
+Project-URL: Source, https://github.com/moi15moi/VideoTimestamps/
+Project-URL: Tracker, https://github.com/moi15moi/VideoTimestamps/issues/
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: coverage >=7.0.0 ; extra == 'dev'
+Requires-Dist: mypy >=1.0.0 ; extra == 'dev'
+Requires-Dist: pillow >=10.0.0 ; extra == 'dev'
+Requires-Dist: pytest >=8.0.0 ; extra == 'dev'
+
+# VideoTimestamps
+[![VideoTimestamps - Version](https://img.shields.io/pypi/v/videotimestamps.svg)](https://pypi.org/project/VideoTimestamps)
+[![VideoTimestamps - Python Version](https://img.shields.io/pypi/pyversions/videotimestamps.svg)](https://pypi.org/project/VideoTimestamps)
+[![VideoTimestamps - Coverage](https://img.shields.io/codecov/c/github/moi15moi/VideoTimestamps)](https://app.codecov.io/github/moi15moi/VideoTimestamps)
+[![VideoTimestamps - mypy](https://img.shields.io/badge/mypy-checked-blue)](https://github.com/moi15moi/VideoTimestamps/actions?query=branch:main)
+
+This tool allows to recover the timestamps of each frame in a video in milliseconds.
+It also help to convert a frame to a time in milliseconds and vice-versa.
+
+## Installation
+```
+pip install VideoTimestamps
+```
+
+## Dependencies
+-  [MKVToolNix v82.0 or more](https://mkvtoolnix.download/downloads.html)
+-  [ffprobe](https://ffmpeg.org/download.html)
+
+## How to use it?
+See the [example file](./examples/get_timestamps.py).

VideoTimestamps-0.0.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+video_timestamps/__init__.py,sha256=AP8zE8hBx8JJ0MSKoJDAR35la5frctq8pZhIz_XvoaI,170
+video_timestamps/_version.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+video_timestamps/abc_video_parser.py,sha256=9jp4oRx-0GQw3iNOlU4X7zqVA91Ctcc0DNr--aKACkA,1110
+video_timestamps/rounding_method.py,sha256=N9vrIuUi-zt_FOBj2B6s9rZ7cEly7crq9NoCQDJeWxc,495
+video_timestamps/time_type.py,sha256=8g5FHK81-7BCOzfzL2US8wBkUzYUg35jHAs2zohEyI0,1739
+video_timestamps/timestamps.py,sha256=Y8EY9Gu7G7RMfQXalpkQ3Kx_HfG8T1oKhi2Gp_eEai0,9374
+video_timestamps/timestamps_factory.py,sha256=a4_HK3iNie2V8J8WQ-mTIh_TN1QbkAwXmeDE4-D8EFg,6264
+video_timestamps/timestamps_file_parser.py,sha256=PwLES5rsGEpRdwcz46VI4t1Bmc22O6XwVv6uwdDUZHc,9032
+video_timestamps/ffprobe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+video_timestamps/ffprobe/ffprobe.py,sha256=xIhR-_qTY0yyiyOYpVOP-Bf9i0y4AykuNk_iTExCQ3M,4927
+video_timestamps/ffprobe/timestamps.py,sha256=vUitcCpoJ6dc-3rapZ3HIzg8YpQC7R3ihskGkcHduEo,995
+video_timestamps/mkvtoolnix/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+video_timestamps/mkvtoolnix/exit_code.py,sha256=J1Vwkpsbdh9TtDGrzVAAgIlqJ7dX3X4IQuKIDgVv3kM,245
+video_timestamps/mkvtoolnix/mkvextract.py,sha256=egnmla3fkFlWl3YNZzj0dBrcUTeRFVkbOz0OBOxfrKo,2341
+video_timestamps/mkvtoolnix/mkvmerge.py,sha256=arPuDKwPkGUlZGcfkCq-tnbhr2XlirGReSe5YvDpYCQ,2270
+video_timestamps/mkvtoolnix/timestamps.py,sha256=aDJMunNpS_kKDymannTj3wcW5GxSgQ6Ku62dhVE99aI,2312
+video_timestamps/mkvtoolnix/utils.py,sha256=oqr5HRqwwMCRZi0EsUrFazJOCIBALx9Tx9ZyIykaLS8,4571
+VideoTimestamps-0.0.1.dist-info/LICENSE,sha256=u7kVQN3qvSSfxekKWXoKKqxNqpwWYQI6CL_400ISUoU,1065
+VideoTimestamps-0.0.1.dist-info/METADATA,sha256=rt7LUsFUxgO3MSFxGEMx4c6kYQSwm6AfERCX07E8Ets,2112
+VideoTimestamps-0.0.1.dist-info/WHEEL,sha256=Wyh-_nZ0DJYolHNn1_hMa4lM7uDedD_RGVwbmTjyItk,91
+VideoTimestamps-0.0.1.dist-info/top_level.txt,sha256=3tv2UWakWMhmArLdqFycgcuDlcqQbaS4w3RE25yPbdM,17
+VideoTimestamps-0.0.1.dist-info/RECORD,,

VideoTimestamps-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (71.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

VideoTimestamps-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+video_timestamps

video_timestamps/__init__.py

@@ -0,0 +1,8 @@
+# Packages
+
+# Files
+from ._version import __version__
+from .rounding_method import *
+from .time_type import *
+from .timestamps import *
+from .timestamps_factory import *

video_timestamps/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

video_timestamps/abc_video_parser.py

@@ -0,0 +1,32 @@
+from .rounding_method import RoundingMethod
+from .timestamps import Timestamps
+from abc import ABC, abstractmethod
+from fractions import Fraction
+from pathlib import Path
+
+
+class ABCVideoParser(ABC):
+
+    @staticmethod
+    @abstractmethod
+    def is_available() -> bool:
+        """
+        Returns:
+            If the video parser is available.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def get_timestamps(video_path: Path, index: int, normalize: bool, rounding_method: RoundingMethod) -> tuple[Timestamps, Fraction]:
+        """Create timestamps based on the ``video_path`` provided.
+
+        Parameters:
+            video_path (Path): A video path.
+            index (int): Index of the video stream.
+            normalize (bool): If True, it will shift the timestamps to make them start from 0. If false, the option does nothing.
+            rounding_method (RoundingMethod): A rounding method. See the comment in Timestamps class about FLOOR vs ROUND.
+        Returns:
+            A tuple containing a Timestamps instance and the time_base of the video.
+        """
+        pass

video_timestamps/ffprobe/ffprobe.py

@@ -0,0 +1,140 @@
+from ..rounding_method import RoundingMethod
+import json
+import sys
+from fractions import Fraction
+from subprocess import CompletedProcess, run
+from pathlib import Path
+from shutil import which
+from typing import Any
+
+__all__ = ["FFprobe"]
+
+
+class FFprobe:
+    """
+    This class is a collection of static methods that will help
+    the user to interact with FFprobe.
+    """
+
+    PROGRAM_NAME = "ffprobe"
+
+    @staticmethod
+    def is_ffprobe_installed() -> bool:
+        """
+        Checks if the `ffprobe` program is installed and available in the system's PATH.
+
+        Returns:
+            True if `ffprobe` is installed, False otherwise.
+        """
+        return which("ffprobe") is not None
+
+    @staticmethod
+    def verify_if_ffprobe_is_installed() -> None:
+        """
+        Verifies if the `mkvextract` program is installed. Raises an error if not found.
+
+        Raises:
+            Exception: If `mkvextract` is not found in the system's PATH.
+        """
+        if not FFprobe.is_ffprobe_installed():
+            raise Exception("ffprobe is not in the environment variable.")
+
+
+    @staticmethod
+    def verify_if_command_fails(cmd_output: CompletedProcess[str]) -> None:
+        """Checks the result of a command execution and raises an error or warning based on the exit code.
+
+        Parameters:
+            cmd_output (CompletedProcess): The result of the command execution.
+
+        Raises:
+            OSError: If the command reported an error.
+        """
+
+        if cmd_output.returncode != 0:
+            raise OSError(f"{FFprobe.PROGRAM_NAME} reported an error: '{cmd_output.stderr}'.")
+
+
+    @staticmethod
+    def run_command(cmd: list[Any]) -> CompletedProcess[str]:
+        """Runs a command and verifies if it fails.
+
+        Parameters:
+            cmd (List[Any]): The command to be run, including its arguments.
+
+        Returns:
+            The result of the command execution.
+        """
+
+        FFprobe.verify_if_ffprobe_is_installed()
+        output = run(cmd, capture_output=True, text=True, encoding="utf-8")
+        FFprobe.verify_if_command_fails(output)
+
+        return output
+
+
+    @staticmethod
+    def get_timestamps(video_path: Path, index: int, rounding_method: RoundingMethod) -> tuple[list[int], Fraction, Fraction, Fraction]:
+        """
+
+        Parameters:
+            video_path (Path): A video path.
+            index (int): Index of the video stream.
+            rounding_method (RoundingMethod): A rounding method. See the comment in Timestamps class about FLOOR vs ROUND.
+        Returns:
+            A tuple containing these 3 informations:
+                1. A list of each timestamps rounded to milliseconds
+                2. The time_base
+                3. The first timestamps not rounded
+                4. The last timestamps not rounded
+        """
+
+        cmd = [
+            FFprobe.PROGRAM_NAME,
+            "-hide_banner",
+            "-select_streams",
+            str(index),
+            "-show_entries",
+            # Technically, we should use frame=pts_time,dts_time instead of packet=pts_time,dts_time
+            # But, using frame make the execution really slow
+            # I tried to ask [here](https://ffmpeg.org/pipermail/ffmpeg-user/2024-July/058509.html) if I could use a heuristic
+            # to know when I need to switch to frame, but I never got an answer.
+            "packet=pts_time,dts_time:stream=codec_type,time_base", #todo
+            video_path,
+            "-print_format",
+            "json",
+        ]
+        ffprobe_output = FFprobe.run_command(cmd)
+
+        ffprobe_output_dict = json.loads(ffprobe_output.stdout)
+
+        if len(ffprobe_output_dict["streams"]) == 0:
+            raise ValueError(f"The index {index} is not in the file {video_path}.")
+
+        if ffprobe_output_dict["streams"][0]["codec_type"] != "video":
+            raise ValueError(
+                f'The index {index} is not a video stream. It is an "{ffprobe_output_dict["streams"][0]["codec_type"]}" stream.'
+            )
+
+        time_base = Fraction(ffprobe_output_dict["streams"][0]["time_base"])
+
+        timestamps = []
+        lowest_timestamp: Fraction = None # type: ignore
+        highest_timestamp: Fraction = None # type: ignore
+
+        for packet in ffprobe_output_dict["packets"]:
+            timestamp = Fraction(
+                # Sometimes, pts_time isn't available.
+                # If it is the case, fallback to dts_time
+                packet.get("pts_time", packet.get("dts_time"))
+            ) * Fraction(1000)
+            if highest_timestamp is None or highest_timestamp < timestamp:
+                highest_timestamp = timestamp
+            if lowest_timestamp is None or lowest_timestamp > timestamp:
+                lowest_timestamp = timestamp
+
+
+            timestamps.append(rounding_method(timestamp))
+        timestamps.sort()
+
+        return timestamps, time_base, lowest_timestamp, highest_timestamp

video_timestamps/ffprobe/timestamps.py

@@ -0,0 +1,29 @@
+from .ffprobe import FFprobe
+from ..timestamps import Timestamps
+from ..abc_video_parser import ABCVideoParser
+from ..rounding_method import RoundingMethod
+from fractions import Fraction
+from pathlib import Path
+
+
+class FFprobeTimestamps(ABCVideoParser):
+
+    @staticmethod
+    def is_available() -> bool:
+        return FFprobe.is_ffprobe_installed()
+
+    @staticmethod
+    def get_timestamps(video_path: Path, index: int, normalize: bool, rounding_method: RoundingMethod) -> tuple[Timestamps, Fraction]:
+        timestamps_list, time_base, first_frame_time, last_frame_time = FFprobe.get_timestamps(video_path, index, rounding_method)
+
+        fpms = Fraction(len(timestamps_list) - 1) / (last_frame_time - first_frame_time)
+
+        timestamps = Timestamps(
+            rounding_method=rounding_method,
+            timestamps=timestamps_list,
+            normalize=normalize,
+            fpms=fpms,
+            last_frame_time=last_frame_time,
+        )
+
+        return timestamps, time_base

video_timestamps/mkvtoolnix/exit_code.py

@@ -0,0 +1,11 @@
+from enum import IntEnum
+
+__all__ = ["ExitCode"]
+
+
+class ExitCode(IntEnum):
+    # From https://mkvtoolnix.download/doc/mkvpropedit.html#d4e1266
+    # All the MKVToolNix programs use this enumeration
+    SUCCESS = 0
+    WARNING = 1
+    ERROR = 2

video_timestamps/mkvtoolnix/mkvextract.py

@@ -0,0 +1,73 @@
+from .utils import MKVUtils
+from tempfile import TemporaryDirectory
+from pathlib import Path
+
+__all__ = ["MKVExtract"]
+
+
+class MKVExtract:
+    """
+    This class is a collection of static methods that will help
+    the user to interact with mkvextract.
+    """
+
+    PROGRAM_NAME = "mkvextract"
+    PROGRAM_PATH = MKVUtils.get_program_path(PROGRAM_NAME)
+
+    @staticmethod
+    def is_mkv_extract_installed() -> bool:
+        """
+        Checks if the `mkvextract` program is installed and available in the system's PATH.
+
+        Returns:
+            True if `mkvextract` is installed, False otherwise.
+        """
+        return MKVExtract.PROGRAM_PATH is not None
+
+
+    @staticmethod
+    def verify_if_mkvextract_installed() -> None:
+        """
+        Verifies if the `mkvextract` program is installed. Raises an error if not found.
+
+        Raises:
+            Exception: If `mkvextract` is not found in the system's PATH.
+        """
+        if not MKVExtract.is_mkv_extract_installed():
+            raise Exception(
+                f'{MKVExtract.PROGRAM_NAME} is isn\'t found. You need to correct your environnements variable or correctly install the program'
+            )
+
+
+    @staticmethod
+    def get_timestamps_file_content(mkv_file_path: Path, index: int) -> str:
+        """Extracts the timestamps from an MKV file for a specific track index.
+
+        Parameters:
+            mkv_file_path (Path): The path to the MKV file.
+            index (int): Index of the video stream.
+
+        Returns:
+            The content of the timestamps file.
+        """
+
+        MKVExtract.verify_if_mkvextract_installed()
+        MKVUtils.verify_if_file_mkv(mkv_file_path)
+
+        with TemporaryDirectory() as tmpdirname:
+            timestamps_file_path = Path(tmpdirname, "temp timestamps.txt")
+            cmd = [
+                MKVExtract.PROGRAM_PATH,
+                mkv_file_path,
+                "timestamps_v2",
+                f"{index}:{timestamps_file_path}",
+            ]
+
+            MKVUtils.run_command(MKVExtract.PROGRAM_NAME, cmd)
+            with open(timestamps_file_path, "r", encoding="utf-8") as file:
+                lines = file.readlines()
+
+            # Ignore the last line due to this issue: https://gitlab.com/mbunkus/mkvtoolnix/-/issues/3075
+            content = "".join(lines[:-1])
+
+        return content

video_timestamps/mkvtoolnix/mkvmerge.py

@@ -0,0 +1,79 @@
+from .utils import MKVUtils
+import json
+from pathlib import Path
+from typing import Any
+
+__all__ = ["MKVMerge"]
+
+
+class MKVMerge:
+    """
+    This class is a collection of static methods that will help
+    the user to interact with mkvmerge.
+    """
+
+    PROGRAM_NAME = "mkvmerge"
+    PROGRAM_PATH = MKVUtils.get_program_path(PROGRAM_NAME)
+
+    @staticmethod
+    def is_mkv_merge_installed() -> bool:
+        """
+        Checks if the `mkvmerge` program is installed and available in the system's PATH.
+
+        Returns:
+            True if `mkvmerge` is installed, False otherwise.
+        """
+        return MKVMerge.PROGRAM_PATH is not None
+
+
+    @staticmethod
+    def verify_if_mkvmerge_installed() -> None:
+        """
+        Verifies if the `mkvmerge` program is installed. Raises an error if not found.
+
+        Raises:
+            Exception: If `mkvmerge` is not found in the system's PATH.
+        """
+        if not MKVMerge.is_mkv_merge_installed():
+            raise Exception(f'{MKVMerge.PROGRAM_NAME} is isn\'t found. You need to correct your environnements variable or correctly install the program')
+
+
+    @staticmethod
+    def get_version() -> tuple[int, int]:
+        """Retrieves the version of `mkvmerge`.
+
+        Equivalent to running: `mkvmerge --version`
+
+        Returns:
+            The major and minor version numbers of `mkvmerge`.
+        """
+        MKVMerge.verify_if_mkvmerge_installed()
+
+        return MKVUtils.get_version(MKVMerge.PROGRAM_NAME, MKVMerge.PROGRAM_PATH) # type: ignore
+
+
+    @staticmethod
+    def get_mkv_info(mkv_file_path: Path) -> Any:
+        """Retrieves information about an MKV file in JSON format.
+
+        Equivalent to running: `mkvmerge FILE.mkv -J`
+
+        Parameters:
+            mkv_file_path (Path): The path to the MKV file.
+
+        Returns:
+            The information about the MKV file in JSON format.
+        """
+        MKVMerge.verify_if_mkvmerge_installed()
+        MKVUtils.verify_if_file_mkv(mkv_file_path)
+
+        cmd = [
+            MKVMerge.PROGRAM_PATH,
+            mkv_file_path,
+            "-J",
+        ]
+
+        mkvmerge_output = MKVUtils.run_command(MKVMerge.PROGRAM_NAME, cmd)
+        mkvmerge_output_dict = json.loads(mkvmerge_output.stdout)
+
+        return mkvmerge_output_dict

video_timestamps/mkvtoolnix/timestamps.py

@@ -0,0 +1,52 @@
+from .mkvextract import MKVExtract
+from .mkvmerge import MKVMerge
+from ..timestamps import Timestamps
+from ..abc_video_parser import ABCVideoParser
+from ..rounding_method import RoundingMethod
+from fractions import Fraction
+from pathlib import Path
+
+
+class MKVToolNixTimestamps(ABCVideoParser):
+
+    @staticmethod
+    def is_available() -> bool:
+        return MKVExtract.is_mkv_extract_installed() and MKVMerge.is_mkv_merge_installed()
+
+
+    @staticmethod
+    def get_timestamps(video_path: Path, index: int, normalize: bool, rounding_method: RoundingMethod) -> tuple[Timestamps, Fraction]:
+        mkvmerge_version = MKVMerge.get_version()
+        if mkvmerge_version < (82, 0):
+            # We need the version 82.0 for the timestamp_scale properties: https://help.mkvtoolnix.download/t/how-to-get-timestamp-scale-information-without-using-mkvinfo/299/3
+            raise OSError(f"You need at least the version 82.0 of mkvmerge. You have the version {mkvmerge_version[0]}.{mkvmerge_version[1]}")
+
+        mkv_info = MKVMerge.get_mkv_info(video_path)
+
+        is_index_in_video = False
+        for track in mkv_info["tracks"]:
+            if track["id"] == index:
+                if track["type"] != "video":
+                    raise ValueError(f'The index {index} is not a video stream. It is an "{track["type"]}" stream.')
+                is_index_in_video = True
+                break
+
+        if not is_index_in_video:
+            raise ValueError(f"The index {index} is not in the file {video_path}.")
+
+        timestamp_scale = mkv_info["container"]["properties"]["timestamp_scale"]
+        # Technically, time_base = TimestampScale * TrackTimestampScale / 10^9
+        # but mkvmerge doesn't report the TrackTimestampScale.
+        # Even the MKVToolNix author suggested me to ignore the TrackTimestampScale [here](https://help.mkvtoolnix.download/t/how-to-get-timestamp-scale-information-without-using-mkvinfo/299/6?u=moi15moi)
+        time_base = Fraction(timestamp_scale, 10**9)
+
+        content = MKVExtract.get_timestamps_file_content(video_path, index)
+
+        from ..timestamps_factory import TimestampsFactory
+        timestamps = TimestampsFactory.from_timestamps_file(
+            content,
+            normalize,
+            rounding_method
+        )
+
+        return timestamps, time_base