yta-video-frame-time 0.0.7__tar.gz → 0.0.13__tar.gz

{yta_video_frame_time-0.0.7 → yta_video_frame_time-0.0.13}/PKG-INFO

@@ -1,7 +1,8 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: yta-video-frame-time
-Version: 0.0.7
+Version: 0.0.13
 Summary: Youtube Autonomous Video Frame Time Module
+License-File: LICENSE
 Author: danialcala94
 Author-email: danielalcalavalera@gmail.com
 Requires-Python: ==3.9

{yta_video_frame_time-0.0.7 → yta_video_frame_time-0.0.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "yta-video-frame-time"
-version = "0.0.7"
+version = "0.0.13"
 description = "Youtube Autonomous Video Frame Time Module"
 authors = [
     {name = "danialcala94",email = "danielalcalavalera@gmail.com"}

yta_video_frame_time-0.0.13/src/yta_video_frame_time/interval.py

@@ -0,0 +1,569 @@
+from yta_validation.parameter import ParameterValidator
+from quicktions import Fraction
+from typing import Union
+
+
+"""
+Tengo un elemento con una duración concreta, por lo que
+el rango es [0, duration):
+- Recortar solo por el principio => 2 segmentos
+- Recortar solo por el final => 2 segmentos
+- Recortar en medio => 3 segmentos
+"""
+Number = Union[int, float, Fraction]
+"""
+Custom type to represent numbers.
+"""
+
+"""
+TODO: Maybe we can add the possibility of having an
+`fps` value when initializing it to be able to force
+the time interval values to be multiple of `1/fps`.
+But this, if implemented, should be `TimeIntervalFPS`
+or similar, and inheritance from this one but forcing
+the values to be transformed according to that `1/fps`.
+"""
+class TimeInterval:
+    """
+    Class to represent a time interval, which is a tuple
+    of time moments representing the time range 
+    `[start, end)`.
+    """
+
+    @property
+    def start_base(
+        self
+    ) -> float:
+        """
+        The `start` of the interval but always as 0.
+        """
+        return 0
+    
+    @property
+    def end_base(
+        self
+    ) -> float:
+        """
+        The `end` of the interval but adapted to a `start=0`.
+        """
+        return self.end - self.start
+    
+    @property
+    def duration(
+        self
+    ) -> float:
+        """
+        The `duration` of the time interval.
+        """
+        return self.end - self.start
+    
+    @property
+    def copy(
+        self
+    ) -> 'TimeInterval':
+        """
+        A copy of this instance.
+        """
+        return TimeInterval(
+            start = self.start,
+            end = self.end
+        )
+    
+    @property
+    def as_tuple(
+        self
+    ) -> tuple[float, float]:
+        """
+        The time interval but as a `(start, end)` tuple.
+        """
+        return (self.start, self.end)
+
+    def __init__(
+        self,
+        start: Number,
+        end: Number,
+    ):
+        """
+        Provide the interval as it actually is, with the `start`
+        and `end`. These values will be adjusted to an internal
+        interval starting on 0.
+
+        The `end` value must be greater than the `start` value.
+        """
+        if start > end:
+            raise Exception('The `start` value provided is greater than the `end` value provided.')
+        
+        if start == end:
+            raise Exception('The `start` value provided is exactly the `end` value provided.')
+
+        self.start: float = start
+        """
+        The original `start` of the time segment.
+        """
+        self.end: float = end
+        """
+        The original `end` of the time segment.
+        """
+
+    def _validate_t(
+        self,
+        t: Number,
+        do_include_start: bool = False,
+        do_include_end: bool = False
+    ) -> None:
+        """
+        Validate that the provided `t` value is between the `start`
+        and the `end` parameters provided, including them or not
+        according to the boolean parameters provided.
+        """
+        ParameterValidator.validate_mandatory_number_between(
+            name = 't',
+            value = t,
+            lower_limit = self.start,
+            upper_limit = self.end,
+            do_include_lower_limit = do_include_start,
+            do_include_upper_limit = do_include_end
+        )
+
+    def _cut(
+        self,
+        start: Number,
+        end: Number
+    ) -> tuple[Union['TimeInterval', None], Union['TimeInterval', None], Union['TimeInterval', None]]:
+        """
+        *For internal use only*
+
+        Cut a segment with the given `start` and `end` time moments.
+
+        This method will return a tuple of 3 elements including the
+        segments created by cutting this time interval. The tuple 
+        will include all the segments at the begining and the rest
+        will be None.
+
+        Examples below:
+        - A time interval of `[2, 5)` cut with `start=3` and `end=4`
+        will generate `((2, 3), (3, 4), (4, 5))`.
+        - A time interval of `[2, 5)` cut with `start=2` and `end=4`
+        will generate `((2, 4), (4, 5), None)`.
+        - A time interval of `[2, 5)` cut with `start=4` and `end=5`
+        will generate `((2, 4), (4, 5), None)`.
+        - A time interval of `[2, 5)` cut with `start=2` and `end=5`
+        will generate `((2, 5), None, None)`.
+
+        As you can see, the result could be the same in different
+        situations, but it's up to you (and the specific method in
+        which you are calling to this one) to choose the tuple you
+        want to return.
+
+        (!) This will not modify the original instance.
+        """
+        self._validate_t(start, do_include_start = True)
+        self._validate_t(end, do_include_end = True)
+
+        return (
+            (
+                self.copy,
+                None,
+                None
+            )
+            if (
+                start == self.start and
+                end == self.end
+            ) else
+            (
+                TimeInterval(
+                    start = self.start,
+                    end = end
+                ),
+                TimeInterval(
+                    start = end,
+                    end = self.end
+                ),
+                None
+            )
+            if start == self.start else
+            (
+                TimeInterval(
+                    start = self.start,
+                    end = start
+                ),
+                TimeInterval(
+                    start = start,
+                    end = self.end
+                ),
+                None
+            )
+            if end == self.end else
+            (
+                TimeInterval(
+                    start = self.start,
+                    end = start
+                ),
+                TimeInterval(
+                    start = start,
+                    end = end
+                ),
+                TimeInterval(
+                    start = end,
+                    end = self.end
+                )
+            )
+        )
+
+    def cut_from_start_to(
+        self,
+        t: Number,
+        do_get_cut: bool = False
+    ) -> Union['TimeInterval', None]:
+        """
+        Cut the interval from the start to the `t` value
+        provided. The return will be the segment cut if 
+        `do_get_cut` is False, or the remaining part if
+        True.
+
+        (!) This will not modify the original instance.
+        """
+        intervals = self._cut(
+            start = self.start,
+            end = t
+        )
+
+        return (
+            intervals[0]
+            if (
+                len(intervals) == 1 or
+                do_get_cut
+            ) else
+            intervals[1]
+        )
+    
+    def cut_to_end_from(
+        self,
+        t: Number,
+        do_get_cut: bool = False
+    ) -> Union['TimeInterval', None]:
+        """
+        Cut the interval from the start to the `t` value
+        provided. The return will be the segment cut if 
+        `do_get_cut` is False, or the remaining part if
+        True.
+
+        (!) This will not modify the original instance.
+        """
+        intervals = self._cut(
+            start = t,
+            end = self.end
+        )
+
+        return (
+            intervals[0]
+            if (
+                len(intervals) == 1 or
+                not do_get_cut
+            ) else
+            intervals[1]
+        )
+    
+    def cut_from_to(
+        self,
+        from_t: Number,
+        to_t: Number,
+        # do_get_cut: bool = False
+    ) -> Union['TimeInterval', None]:
+        """
+        Cut the interval from the `from_t` value provided
+        to the `to_t` value given. The return will be the
+        segment cut.
+
+        (!) This will not modify the original instance.
+
+        TODO: By now we are only getting the cut
+        """
+        intervals = self._cut(
+            start = from_t,
+            end = to_t
+        )
+        
+        return (
+            intervals[0]
+            if (
+                len(intervals) == 1 or
+                (
+                    len(intervals) == 2 and
+                    from_t == self.start
+                )
+            ) else
+            intervals[1]
+        )
+    
+    def is_t_included(
+        self,
+        t: float,
+        do_include_end: bool = False
+    ) -> bool:
+        """
+        Check if the `t` time moment provided is included in
+        this time interval, including the `end` only if the
+        `do_include_end` parameter is set as `True`.
+        """
+        return TimeIntervalUtils.a_includes_t(
+            t = t,
+            time_interval_a = self,
+            do_include_end = do_include_end
+        )
+    
+    def is_adjacent_to(
+        self,
+        time_interval: 'TimeInterval'
+    ) -> bool:
+        """
+        Check if the `time_interval` provided is adjacent
+        to this time interval, which means that the `end`
+        of one interval is also the `start` of the other
+        one.
+
+        (!) Giving the time intervals inverted will
+        provide the same result.
+
+        Example below:
+        - `a=[2, 5)` and `b=[5, 7)` => `True`
+        - `a=[5, 7)` and `b=[2, 5)` => `True`
+        - `a=[2, 5)` and `b=[3, 4)` => `False`
+        - `a=[2, 5)` and `b=[6, 8)` => `False`
+        """
+        return TimeIntervalUtils.a_is_adjacent_to_b(
+            time_interval_a = self,
+            time_interval_b = time_interval
+        )
+    
+    def do_contains_a(
+        self,
+        time_interval: 'TimeInterval'
+    ) -> bool:
+        """
+        Check if this time interval includes the `time_interval`
+        provided or not, which means that the `time_interval`
+        provided is fully contained (included) in this one.
+        """
+        return TimeIntervalUtils.a_contains_b(
+            time_interval_a = self,
+            time_interval_b = time_interval
+        )
+    
+    def is_contained_in(
+        self,
+        time_interval: 'TimeInterval'
+    ) -> bool:
+        """
+        Check if this time interval is fully contained in
+        the `time_interval` provided, which is a synonim
+        of being fully overlapped by that `time_interval`.
+        """
+        return TimeIntervalUtils.a_is_contained_in_b(
+            time_interval_a = self,
+            time_interval_b = time_interval
+        )
+    
+    def do_intersects_with(
+        self,
+        time_interval: 'TimeInterval'
+    ) -> bool:
+        """
+        Check if this time interval intersects with the one
+        provided as `time_interval`, which means that they
+        have at least a part in common.
+        """
+        return TimeIntervalUtils.a_intersects_with_b(
+            time_interval_a = self,
+            time_interval_b = time_interval
+        )
+    
+    def get_intersection_with_a(
+        self,
+        time_interval: 'TimeInterval'
+    ) -> Union['TimeInterval', None]:
+        """
+        Get the time interval that intersects this one and the
+        one provided as `time_interval`. The result can be `None`
+        if there is no intersection in between both.
+        """
+        return TimeIntervalUtils.get_intersection_of_a_and_b(
+            time_interval_a = self,
+            time_interval_b = time_interval
+        )
+    
+    
+class TimeIntervalUtils:
+    """
+    Static class to wrap the utils related to time intervals.
+    """
+
+    @staticmethod
+    def a_includes_t(
+        t: float,
+        time_interval_a: 'TimeInterval',
+        do_include_end: bool = False
+    ) -> bool:
+        """
+        Check if the `t` time moment provided is included in
+        the `time_interval_a` given. The `time_interval_a.end`
+        is excluded unless the `do_include_end` parameter is
+        set as `True`.
+
+        A time interval is `[start, end)`, thats why the end is
+        excluded by default.
+        """
+        return (
+            time_interval_a.start <= t <= time_interval_a.end
+            if do_include_end else
+            time_interval_a.start <= t < time_interval_a.end
+        )
+    
+    @staticmethod
+    def a_is_adjacent_to_b(
+        time_interval_a: 'TimeInterval',
+        time_interval_b: 'TimeInterval',
+    ) -> bool:
+        """
+        Check if the `time_interval_a` provided and the
+        also given `time_interval_b` are adjacent, which
+        means that the `end` of one interval is also the
+        `start` of the other one.
+
+        (!) Giving the time intervals inverted will
+        provide the same result.
+
+        Examples below:
+        - `a=[2, 5)` and `b=[5, 7)` => `True`
+        - `a=[5, 7)` and `b=[2, 5)` => `True`
+        - `a=[2, 5)` and `b=[3, 4)` => `False`
+        - `a=[2, 5)` and `b=[6, 8)` => `False`
+        """
+        return (
+            TimeIntervalUtils.a_is_inmediately_before_b(time_interval_a, time_interval_b) or
+            TimeIntervalUtils.a_is_inmediately_after_b(time_interval_a, time_interval_b)
+        )
+    
+    @staticmethod
+    def a_is_inmediately_before_b(
+        time_interval_a: 'TimeInterval',
+        time_interval_b: 'TimeInterval',
+    ) -> bool:
+        """
+        Check if the `time_interval_a` provided is inmediately
+        before the also given `time_interval_b`, which means
+        that the `end` of the first one is also the `start` of
+        the second one.
+
+        Examples below:
+        - `a=[2, 5)` and `b=[5, 7)` => `True`
+        - `a=[5, 7)` and `b=[2, 5)` => `False`
+        - `a=[2, 5)` and `b=[3, 4)` => `False`
+        - `a=[2, 5)` and `b=[6, 8)` => `False`
+        """
+        return time_interval_a.end == time_interval_b.start
+    
+    @staticmethod
+    def a_is_inmediately_after_b(
+        time_interval_a: 'TimeInterval',
+        time_interval_b: 'TimeInterval',
+    ) -> bool:
+        """
+        Check if the `time_interval_a` provided is inmediately
+        after the also given `time_interval_b`, which means
+        that the `start` of the first one is also the `end` of
+        the second one.
+
+        Examples below:
+        - `a=[2, 5)` and `b=[5, 7)` => `False`
+        - `a=[5, 7)` and `b=[2, 5)` => `True`
+        - `a=[2, 5)` and `b=[3, 4)` => `False`
+        - `a=[2, 5)` and `b=[6, 8)` => `False`
+        """
+        return time_interval_a.start == time_interval_b.end
+    
+    @staticmethod
+    def a_contains_b(
+        time_interval_a: 'TimeInterval',
+        time_interval_b: 'TimeInterval'
+    ) -> bool:
+        """
+        Check if the `time_interval_a` time interval provided
+        includes the `time_interval_b` or not, which means that
+        the `time_interval_b` is fully contained in the first
+        one.
+
+        Examples below:
+        - `a=[2, 5)` and `b=[3, 4)` => `True`
+        - `a=[2, 5)` and `b=[2, 4)` => `True`
+        - `a=[2, 5)` and `b=[3, 6)` => `False`
+        - `a=[2, 5)` and `b=[6, 8)` => `False`
+        """
+        return (
+            time_interval_a.start <= time_interval_b.start and
+            time_interval_a.end >= time_interval_b.end
+        )
+    
+    @staticmethod
+    def a_is_contained_in_b(
+        time_interval_a: 'TimeInterval',
+        time_interval_b: 'TimeInterval',
+    ) -> bool:
+        """
+        Check if the `time_interval_a` provided is fully
+        contained into the also provided `time_interval_b`.
+
+        Examples below:
+        - `a=[2, 5)` and `b=[1, 6)` => `True`
+        - `a=[2, 5)` and `b=[0, 9)` => `True`
+        - `a=[2, 5)` and `b=[2, 4)` => `False`
+        - `a=[2, 5)` and `b=[4, 8)` => `False`
+        - `a=[2, 5)` and `b=[7, 8)` => `False`
+        """
+        return TimeIntervalUtils.a_contains_b(
+            time_interval_a = time_interval_b,
+            time_interval_b = time_interval_a
+        )
+    
+    @staticmethod
+    def a_intersects_with_b(
+        time_interval_a: 'TimeInterval',
+        time_interval_b: 'TimeInterval',
+    ) -> bool:
+        """
+        Check if the `time_interval_a` and the `time_interval_b`
+        provided has at least a part in common.
+
+        Examples below:
+        - `a=[2, 5)` and `b=[4, 6)` => `True`
+        - `a=[2, 5)` and `b=[1, 3)` => `True`
+        - `a=[2, 5)` and `b=[5, 6)` => `False`
+        - `a=[2, 5)` and `b=[7, 8)` => `False`
+        - `a=[2, 5)` and `b=[1, 2)` => `False`
+        """
+        return (
+            time_interval_b.start < time_interval_a.end and
+            time_interval_a.start < time_interval_b.end
+        )
+    
+    @staticmethod
+    def get_intersection_of_a_and_b(
+        time_interval_a: 'TimeInterval',
+        time_interval_b: 'TimeInterval'
+    ) -> Union['TimeInterval', None]:
+        """
+        Get the time interval that intersects the two time
+        intervals provided, that can be `None` if there is no
+        intersection in between both.
+        """
+        return (
+            None
+            if not TimeIntervalUtils.a_intersects_with_b(
+                time_interval_a = time_interval_a,
+                time_interval_b = time_interval_b
+            ) else
+            TimeInterval(
+                start = max(time_interval_a.start, time_interval_b.start),
+                end = min(time_interval_a.end, time_interval_b.end)
+            )
+        )

{yta_video_frame_time-0.0.7 → yta_video_frame_time-0.0.13}/src/yta_video_frame_time/t_fraction.py

@@ -238,6 +238,8 @@ def round_pts(
     and 'time_base', but here is an easier
     example using the time moments.
 
+    (!) This is valid only for video.
+
     Examples below, with `time_base = 1/5`:
     - `t = 0.25` => `0.2` (truncated or rounded)
     - `t = 0.35` => `0.2` (truncated)
@@ -256,8 +258,6 @@ def round_pts(
     
     return int(frame_index * ticks_per_frame)
 
-# TODO: Create a 'round_pts'
-
 """
 When we are working with the 't' time
 moment we need to use the fps, and when
@@ -306,6 +306,18 @@ class _T:
         The formula:
         - `pts * time_base`
         """
+        t = Fraction(pts * self._t_handler.time_base)
+
+        return (
+            self._t_handler.t.truncated(t)
+            if do_truncate is True else
+            self._t_handler.t.rounded(t)
+            if do_truncate is False else
+            t # if None
+        )
+
+        # TODO: Remove this below in the next
+        # commit
         pts = (
             self._t_handler.pts.truncated(pts)
             if do_truncate is True else
@@ -342,7 +354,7 @@ class _T:
         variation.
 
         The formula:
-        - `int(t * fps)`
+        - `int(round(t * fps))`
         """
         t = (
             self.truncated(t)
@@ -370,7 +382,7 @@ class _T:
     def truncated(
         self,
         t: Union[int, float, Fraction]
-    ):
+    ) -> Fraction:
         """
         Get the 't' value provided but truncated.
 
@@ -380,10 +392,26 @@ class _T:
         """
         return round_t(t, Fraction(1, self._t_handler.fps), do_truncate = True)
     
+    def is_truncated(
+        self,
+        t: Union[int, float, Fraction]
+    ) -> bool:
+        """
+        Check if the `t` value provided is the truncated
+        value, which means that the `t` provided is the 
+        `start` from the `[start, end)` range defined by
+        the fps.
+        """
+        return check_values_are_same(
+            value_a = t,
+            value_b = self.truncated(t),
+            tolerance = 0.000001
+        )
+    
     def rounded(
         self,
         t: Union[int, float, Fraction]
-    ):
+    ) -> Fraction:
         """
         Get the 't' value provided but rounded.
 
@@ -530,7 +558,7 @@ class _Pts:
         variation.
 
         The formula:
-        - `int((pts * time_base) * fps)`
+        - `int(round((pts * time_base) * fps))`
         """
         return self._t_handler.t.to_index(
             self.to_t(pts, do_truncate = None),
@@ -552,12 +580,31 @@ class _Pts:
             t = self._t_handler.t.from_index(index),
             do_truncate = True
         )
+    
+    """
+    These 2 methods below are here because they
+    seem to work for videos, but I think they
+    could work not if the video has dynamic frame
+    rate or in some other situations, thats why
+    this is here as a reminder.
+
+    I found one video that had audio_fps=44100
+    and time_base=256/11025, so it was impossible
+    to make a conversion using this formula with
+    the audio. With video seems to be ok, but...
+
+    Use these methods below at your own risk.
+    """
 
     def truncated(
         self,
         pts: int
     ):
         """
+        (!) This is valid only for video and/or 
+        could work not properly. Use it at your
+        own risk.
+
         Get the 'pts' value provided but truncated.
 
         This means that if 't' is in a
@@ -576,6 +623,10 @@ class _Pts:
         pts: int
     ) -> int:
         """
+        (!) This is valid only for video and/or 
+        could work not properly. Use it at your
+        own risk.
+
         Get the 'pts' value provided but rounded.
 
         This means that if 't' is in a
@@ -598,6 +649,10 @@ class _Pts:
         do_truncate: bool = True
     ) -> int:
         """
+        (!) This is valid only for video and/or 
+        could work not properly. Use it at your
+        own risk.
+
         Get the value that is 'n' times ahead of
         the 'pts' value provided (truncated or
         rounded according to the 'do_truncate'
@@ -624,6 +679,10 @@ class _Pts:
         do_truncate: bool = True
     ) -> int:
         """
+        (!) This is valid only for video and/or 
+        could work not properly. Use it at your
+        own risk.
+
         Get the value that is 'n' times before
         the 't' property of this instance 
         (truncated or rounded according to the
@@ -647,7 +706,7 @@ class _Pts:
         )
 
         return pts - n * get_ticks_per_frame(self._t_handler.fps, self._t_handler.time_base)
-
+    
 class THandler:
     """
     Class to simplify the way we work with
@@ -715,9 +774,9 @@ def frame_t_to_index(
     also provided 'fps'.
 
     The formula:
-    - `int(t * fps)`
+    - `int(round(t * fps))`
     """
-    return int(parse_fraction(t) * fps)
+    return int(round(t * fps))
 
 def frame_index_to_t(
     index: int,
@@ -745,6 +804,8 @@ def frame_t_to_pts(
     moment provided, based on the also provided
     'fps' and 'time_base'.
 
+    (!) This is valid only for videos.
+
     The formula:
     - `frame_index * ticks_per_frame`
     """
@@ -764,6 +825,23 @@ def frame_pts_to_t(
     - `pts * time_base`
     """
     return parse_fraction(pts * time_base)
+
+def get_audio_frame_duration(
+    samples: int,
+    audio_fps: Fraction
+) -> Fraction:
+    """
+    Get the audio frame duration by giving the
+    number of '.samples' and also the rate (that
+    we call 'audio_fps').
+
+    This is useful when trying to guess the next
+    pts or t.
+
+    The formula:
+    - `samples / audio_fps`
+    """
+    return Fraction(samples / audio_fps)
     
 def get_ticks_per_frame(
     fps: Union[float, int, Fraction],
@@ -820,3 +898,17 @@ def parse_fraction(
 
     return fraction
     
+def check_values_are_same(
+    value_a: Union[Fraction, float],
+    value_b: Union[Fraction, float],
+    tolerance: float = 1e-6
+) -> bool:
+    """
+    Check that the `value_a` and the `value_b` are the same
+    by applying the `tolerance` value, that is 0.000001 by
+    default.
+
+    For example, `0.016666666666666666` is the same value as
+    `1/60` with `tolerance=0.000001`.
+    """
+    return abs(float(value_a) - float(value_b)) < tolerance