yta-video-frame-time 0.0.6__tar.gz → 0.0.14__tar.gz

{yta_video_frame_time-0.0.6 → yta_video_frame_time-0.0.14}/PKG-INFO

@@ -1,7 +1,8 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: yta-video-frame-time
-Version: 0.0.6
+Version: 0.0.14
 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.6 → yta_video_frame_time-0.0.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "yta-video-frame-time"
-version = "0.0.6"
+version = "0.0.14"
 description = "Youtube Autonomous Video Frame Time Module"
 authors = [
     {name = "danialcala94",email = "danielalcalavalera@gmail.com"}
@@ -17,6 +17,7 @@ packages = [{include = "yta_video_frame_time", from = "src"}]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.5"
+yta_testing = ">=0.0.1"
 
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]

yta_video_frame_time-0.0.14/src/yta_video_frame_time/decorators.py

@@ -0,0 +1,52 @@
+"""
+TODO: I think this module should not be here, or maybe
+yes, but I need this decorator.
+"""
+from functools import wraps
+
+
+def parameter_to_time_interval(
+    param_name: str
+):
+    """
+    Force the parameter with the given `param_name` to
+    be a `TimeInterval` instance.
+
+    Values accepted:
+    - `TimeInterval` instance
+    - `tuple[float, float]` that will be `(start, end)`
+    """
+    def decorator(
+        func
+    ):
+        @wraps(func)
+        def wrapper(
+            *args,
+            **kwargs
+        ):
+            from inspect import signature
+            from yta_validation import PythonValidator
+            from yta_video_frame_time.interval import TimeInterval
+
+            sig = signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            value = bound.arguments[param_name]
+
+            if PythonValidator.is_instance_of(value, TimeInterval):
+                pass
+            elif (
+                PythonValidator.is_tuple(value) and
+                len(value) == 2
+            ):
+                value = TimeInterval(*value)
+                bound.arguments[param_name] = value
+            else:
+                raise Exception(f'The "{param_name}" parameter must be a TimeInterval or a tuple[float, float].')
+
+            return func(*bound.args, **bound.kwargs)
+        
+        return wrapper
+    
+    return decorator

yta_video_frame_time-0.0.14/src/yta_video_frame_time/interval.py

@@ -0,0 +1,951 @@
+"""
+TODO: This module is general so we should send it
+to another library related to time intervals and
+not specifically video frame times... Move it.
+"""
+from yta_video_frame_time.decorators import parameter_to_time_interval
+from yta_validation.parameter import ParameterValidator
+from quicktions import Fraction
+from typing import Union
+
+
+Number = Union[int, float, Fraction]
+"""
+Custom type to represent numbers.
+"""
+TimeIntervalType = Union['TimeInterval', tuple[float, float]]
+"""
+The type we accept as time interval, that could be a
+tuple we transform into a time interval.
+"""
+
+"""
+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 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)
+    
+    @property
+    def cutter(
+        self
+    ) -> 'TimeIntervalCutter':
+        """
+        Shortcut to the static class `TimeIntervalCutter` that
+        is capable of cutting time intervals.
+        """
+        return TimeIntervalCutter
+
+    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]]:
+        """
+        Cut a segment from the given `start` to the also provided
+        `end` time moments of this time interval instance.
+
+        This method will return a tuple of 3 elements including the
+        segments created by cutting this time interval in the order
+        they were generated, but also having the 4th element always
+        as the index of the one specifically requested by the user.
+        The tuple will include all the segments at the begining and
+        the rest will be None (unless the 4th one, which is the
+        index).
+
+        Examples below:
+        - A time interval of `[2, 5)` cut with `start=3` and `end=4`
+        will generate `((2, 3), (3, 4), (4, 5), 1)`.
+        - A time interval of `[2, 5)` cut with `start=2` and `end=4`
+        will generate `((2, 4), (4, 5), None, 0)`.
+        - A time interval of `[2, 5)` cut with `start=4` and `end=5`
+        will generate `((2, 4), (4, 5), None, 1)`.
+        - A time interval of `[2, 5)` cut with `start=2` and `end=5`
+        will generate `((2, 5), None, None, 0)`.
+
+        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.
+        """
+        return self.cutter.from_to(
+            time_interval = self,
+            start = start,
+            end = end
+        )
+    
+    def cutted(
+        self,
+        start: Number,
+        end: Number
+    ) -> 'TimeInterval':
+        """
+        Get this time interval instance but cutted from the `start`
+        to the `end` time moments provided.
+
+        (!) This method doesn't modify the original instance but
+        returns a new one.
+        """
+        tuples = self.cut(
+            start = start,
+            end = end
+        )
+
+        return tuples[tuples[3]]
+    
+    def trim_start(
+        self,
+        t_variation: Number,
+        limit: Union[Number, None] = None
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Get a tuple containing the 2 new `TimeInterval` instances
+        generated by trimming this one's start the amount of seconds
+        provided as the `t_variation` parameter. The first tuple is
+        the remaining, and the second one is the new time interval
+        requested by the user.
+
+        This method will raise an exception if the new `start` value
+        becomes a value over the time interval `end` value or the
+        `limit`, that must be greater than the `start` and lower
+        than the time interval `end` value.
+
+        The `t_variation` must be a positive value, the amount of
+        seconds to be trimmed.
+        """
+        return self.cutter.trim_start(
+            time_interval = self,
+            t_variation = t_variation,
+            limit = limit
+        )
+    
+    def trimmed_start(
+        self,
+        t_variation: Number,
+        limit: Union[Number, None] = None
+    ) -> 'TimeInterval':
+        """
+        Get this time interval instance but trimmed from the `start`
+        the `t_variation` amount of seconds provided.
+
+        (!) This method doesn't modify the original instance but
+        returns a new one.
+        """
+        return self.trim_start(
+            t_variation = t_variation,
+            limit = limit
+        )[1]
+    
+    def trim_end(
+        self,
+        t_variation: Number,
+        limit: Union[Number, None] = None
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Get a tuple containing the 2 new `TimeInterval` instances
+        generated by trimming this one's end the amount of seconds
+        provided as the `t_variation` parameter. The first tuple is
+        the one requested by the user, and the second one is the
+        remaining.
+
+        This method will raise an exception if the new `end` value
+        becomes a value under the time interval `start` value or
+        the `limit`, that must be greater than the `start` and lower
+        than the time interval `end` value.
+
+        The `t_variation` must be a positive value, the amount of
+        seconds to be trimmed.
+        """
+        return self.cutter.trim_end(
+            time_interval = self,
+            t_variation = t_variation,
+            limit = limit
+        )
+    
+    def trimmed_end(
+        self,
+        t_variation: Number,
+        limit: Union[Number, None] = None
+    ) -> 'TimeInterval':
+        """
+        Get this time interval instance but trimmed from the `end`
+        the `t_variation` amount of seconds provided.
+
+        (!) This method doesn't modify the original instance but
+        returns a new one.
+        """
+        return self.trim_end(
+            t_variation = t_variation,
+            limit = limit
+        )[0]
+    
+    def split(
+        self,
+        t: Number
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Split the time interval at the provided `t` time moment
+        and get the 2 new time intervals as a result (as a tuple).
+
+        This method will raise an exception if the `t` value 
+        provided is a limit value (or above).
+
+        Examples below:
+        - A time interval of `[2, 5)` cut with `t=3` will generate
+        `((2, 3), (3, 5))`.
+        - A time interval of `[2, 5)` cut with `t=4` will generate
+        `((2, 4), (4, 5))`.
+        - A time interval of `[2, 5)` cut with `t>=5` will raise
+        exception.
+        - A time interval of `[2, 5)` cut with `t<=2` will raise
+        exception.
+        """
+        return self.cutter.split(
+            time_interval = self,
+            t = t
+        )
+    
+    def splitted_left(
+        self,
+        t: Number
+    ) -> 'TimeInterval':
+        """
+        Split this time interval instance by the `t` time moment
+        provided and obtain the time interval from the left side,
+        which goes from this time interval `start` time moment to
+        the `t` provided.
+        """
+        return self.split(t)[0]
+    
+    def splitted_right(
+        self,
+        t: Number
+    ) -> 'TimeInterval':
+        """
+        Split this time interval instance by the `t` time moment
+        provided and obtain the time interval from the right side,
+        which goes from the `t` provided to the time interval `end`
+        time moment.
+        """
+        return self.split(t)[1]
+
+    # Other methods below
+    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)
+            )
+        )
+
+class TimeIntervalCutter:
+    """
+    Class to wrap the functionality related to cutting
+    time intervals.
+    """
+
+    """
+    TODO: Methods I have to implement:
+    trim_end → recorta la parte final
+    trim_start → recorta la parte inicial
+    cut_segment → elimina un tramo [a, b)
+    split_at → divide en dos en un punto dado
+    """
+
+    @staticmethod
+    @parameter_to_time_interval('time_interval')
+    def trim_end_to(
+        time_interval: TimeIntervalType,
+        t: Number
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Get a tuple containing the 2 new `TimeInterval` instances
+        generated by trimming the `time_interval` end to the `t`
+        time moment provided. The first tuple is the requested by
+        the user, and the second one is the remaining.
+
+        The `t` time moment provided must be a value between the
+        `start` and `end` of the `time_interval` provided.
+        """
+        time_interval._validate_t(t)
+
+        return (
+            TimeInterval(
+                start = time_interval.start,
+                end = t
+            ),
+            TimeInterval(
+                start = t,
+                end = time_interval.end
+            )
+        )
+    
+    @staticmethod
+    @parameter_to_time_interval('time_interval')
+    def trim_end(
+        time_interval: TimeIntervalType,
+        t_variation: Number,
+        limit: Union[Number, None] = None,
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Get a tuple containing the 2 new `TimeInterval` instances
+        generated by trimming the `time_interval` end the amount
+        of seconds provided as the `t_variation` parameter. The
+        first tuple is the requested by the user, and the second one
+        is the remaining.
+
+        This method will raise an exception if the new `end` value
+        becomes a value under the time interval `start` value or
+        the `limit`, that must be greater than the `start` and lower
+        than the time interval `end` value.
+
+        The `t_variation` must be a positive value, the amount of
+        seconds to be trimmed.
+        """
+        ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
+        ParameterValidator.validate_number_between('limit', limit, time_interval.start, time_interval.end, False, False)
+
+        new_end = time_interval.end - t_variation
+        limit = (
+            time_interval.start
+            if limit is None else
+            limit
+        )
+
+        if new_end <= time_interval.start:
+            raise Exception('The "t_variation" value provided makes the new end value be lower than the "start" value.')
+        
+        if new_end <= limit:
+            raise Exception('The "t_variation" value provided makes the new end value be lower than the "limit" value provided.')
+        
+        return (
+            TimeInterval(
+                start = time_interval.start,
+                end = new_end
+            ),
+            TimeInterval(
+                start = new_end,
+                end = time_interval.end
+            )
+        )
+    
+    @staticmethod
+    @parameter_to_time_interval('time_interval')
+    def trim_start_to(
+        time_interval: TimeIntervalType,
+        t: Number
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Get a tuple containing the 2 new `TimeInterval` instances
+        generated by trimming the `time_interval` start to the `t`
+        time moment provided. The first tuple is the remaining, and
+        the second one is the requested by the user.
+
+        The `t` time moment provided must be a value between the
+        `start` and `end` of the `time_interval` provided.
+        """
+        time_interval._validate_t(t)
+
+        return (
+            TimeInterval(
+                start = time_interval.start,
+                end = t
+            ),
+            TimeInterval(
+                start = t,
+                end = time_interval.end
+            )
+        )
+    
+    @staticmethod
+    @parameter_to_time_interval('time_interval')
+    def trim_start(
+        time_interval: TimeIntervalType,
+        t_variation: Number,
+        limit: Union[Number, None] = None,
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Get a tuple containing the 2 new `TimeInterval` instances
+        generated by trimming the `time_interval` start the amount
+        of seconds provided as the `t_variation` parameter. The
+        first tuple is the remaining, and the second one is the
+        new time interval requested by the user.
+
+        This method will raise an exception if the new `end` value
+        becomes a value under the time interval `start` value or
+        the `limit`, that must be greater than the `start` and lower
+        than the time interval `end` value.
+
+        The `t_variation` must be a positive value, the amount of
+        seconds to be trimmed.
+        """
+        ParameterValidator.validate_mandatory_positive_number('t_variation', t_variation, do_include_zero = False)
+        ParameterValidator.validate_number_between('limit', limit, time_interval.start, time_interval.end, False, False)
+
+        new_start = time_interval.start + t_variation
+        limit = (
+            time_interval.end
+            if limit is None else
+            limit
+        )
+
+        if new_start >= time_interval.end:
+            raise Exception('The "t_variation" value provided makes the new end value be lower than the "end" value.')
+        
+        if new_start >= limit:
+            raise Exception('The "t_variation" value provided makes the new end value be greater than the "limit" value provided.')
+        
+        return (
+            TimeInterval(
+                start = time_interval.start,
+                end = new_start
+            ),
+            TimeInterval(
+                start = new_start,
+                end = time_interval.end
+            )
+        )
+    
+    @staticmethod
+    @parameter_to_time_interval('time_interval')
+    def from_to(
+        time_interval: 'TimeInterval',
+        start: Number,
+        end: Number
+    ) -> tuple[Union['TimeInterval', None], Union['TimeInterval', None], Union['TimeInterval', None], int]:
+        """
+        Cut a segment from the given `start` to the also provided
+        `end` time moments of the `time_interval` passed as
+        parameter.
+
+        This method will return a tuple of 3 elements including the
+        segments created by cutting this time interval in the order
+        they were generated, but also having the 4th element always
+        as the index of the one specifically requested by the user.
+        The tuple will include all the segments at the begining and
+        the rest will be None (unless the 4th one, which is the
+        index).
+
+        Examples below:
+        - A time interval of `[2, 5)` cut with `start=3` and `end=4`
+        will generate `((2, 3), (3, 4), (4, 5), 1)`.
+        - A time interval of `[2, 5)` cut with `start=2` and `end=4`
+        will generate `((2, 4), (4, 5), None, 0)`.
+        - A time interval of `[2, 5)` cut with `start=4` and `end=5`
+        will generate `((2, 4), (4, 5), None, 1)`.
+        - A time interval of `[2, 5)` cut with `start=2` and `end=5`
+        will generate `((2, 5), None, None, 0)`.
+
+        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.
+        """
+        time_interval._validate_t(start, do_include_start = True)
+        time_interval._validate_t(end, do_include_end = True)
+
+        return (
+            # TODO: What about this case, should we raise except (?)
+            (
+                time_interval.copy,
+                None,
+                None,
+                0
+            )
+            if (
+                start == time_interval.start and
+                end == time_interval.end
+            ) else
+            (
+                TimeInterval(
+                    start = time_interval.start,
+                    end = end
+                ),
+                TimeInterval(
+                    start = end,
+                    end = time_interval.end
+                ),
+                None,
+                0
+            )
+            if start == time_interval.start else
+            (
+                TimeInterval(
+                    start = time_interval.start,
+                    end = start
+                ),
+                TimeInterval(
+                    start = start,
+                    end = time_interval.end
+                ),
+                None,
+                1
+            )
+            if end == time_interval.end else
+            (
+                TimeInterval(
+                    start = time_interval.start,
+                    end = start
+                ),
+                TimeInterval(
+                    start = start,
+                    end = end
+                ),
+                TimeInterval(
+                    start = end,
+                    end = time_interval.end
+                ),
+                1
+            )
+        )
+    
+    @staticmethod
+    @parameter_to_time_interval('time_interval')
+    def split(
+        time_interval: 'TimeInterval',
+        t: Number,
+    ) -> tuple['TimeInterval', 'TimeInterval']:
+        """
+        Split the interval at the provided `t` time moment and
+        get the 2 new time intervals as a result (as a tuple).
+
+        This method will raise an exception if the `t` value 
+        provided is a limit value (or above).
+
+        Examples below:
+        - A time interval of `[2, 5)` cut with `t=3` will generate
+        `((2, 3), (3, 5))`.
+        - A time interval of `[2, 5)` cut with `t=4` will generate
+        `((2, 4), (4, 5))`.
+        - A time interval of `[2, 5)` cut with `t>=5` will raise
+        exception.
+        - A time interval of `[2, 5)` cut with `t<=2` will raise
+        exception.
+        """
+        if (
+            t <= time_interval.start or
+            t >= time_interval.end
+        ):
+            raise Exception('The "t" value provided is not a valid value as it is a limit (or more than a limit).')
+        
+        return (
+            TimeInterval(
+                start = time_interval.start,
+                end = t
+            ),
+            TimeInterval(
+                start = t,
+                end = time_interval.end
+            )
+        )
+        
+# # TODO: This method is interesting if we don't want only to
+# # trim but also to extend, so we can use the limits.
+# @staticmethod
+# def trim_end(
+#     time_interval: TimeIntervalType,
+#     t_variation: Number,
+#     lower_limit: Number = 0.0,
+#     upper_limit: Union[Number, None] = None,
+#     do_include_lower_limit: bool = True,
+#     do_include_upper_limit: bool = True
+# ) -> Union['TimeInterval', 'TimeInterval']:
+#     """
+#     Get a tuple containing the 2 new `TimeInterval` instances
+#     generated by trimming the `time_interval` provided from
+#     the `end` and at the `t` time moment provided. The first
+#     value is the remaining, and the second one is the requested
+#     by the user.
+
+#     This will raise an exception if the new `end` becomes a
+#     value under the `lower_limit` provided, above the 
+#     `upper_limit` given (if given) or even below the time
+#     interval `start` value. The limits will be included or not
+#     according to the boolean parameters.
+#     """
+#     new_end = time_interval.end + t_variation
+
+#     if new_end <= time_interval.start:
+#         raise Exception('The "t_variation" value provided makes the new end value be lower than the "start" value.')
+
+#     is_under_lower_limit = (
+#         new_end < lower_limit
+#         if do_include_lower_limit else
+#         new_end <= lower_limit
+#     )
+
+#     is_over_upper_limit = (
+#         upper_limit is None and
+#         (
+#             new_end > upper_limit
+#             if do_include_upper_limit else
+#             new_end >= upper_limit
+#         )
+#     )
+    
+#     if (
+#         is_under_lower_limit or
+#         is_over_upper_limit
+#     ):
+#         raise Exception('The "t_variation" value provided makes the new end value be out of the limits.')
+    
+#     return (
+#         TimeInterval(
+#             start = time_interval.start,
+#             end = new_end
+#         ),
+#         TimeInterval(
+#             start = new_end,
+#             end = time_interval.end
+#         )
+    #     )
+

{yta_video_frame_time-0.0.6 → yta_video_frame_time-0.0.14}/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
@@ -302,7 +302,22 @@ class _T:
         None, we will not make any conversion
         and the value received could be useless
         because it is in the middle of a range.
+
+        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
@@ -322,13 +337,52 @@ class _T:
         Transform the given 't' to a 'pts' value
         truncating, rounding or applying no 
         variation.
+
+        The formula:
+        - `int(t / time_base)`
         """
         return self._t_handler.pts.from_t(t, do_truncate)
+    
+    def to_index(
+        self,
+        t: Union[int, float, Fraction],
+        do_truncate: Union[bool, None] = True
+    ) -> int:
+        """
+        Transform the given 't' to a index value
+        truncating, rounding or applying no
+        variation.
+
+        The formula:
+        - `int(round(t * fps))`
+        """
+        t = (
+            self.truncated(t)
+            if do_truncate is True else
+            self.rounded(t)
+            if do_truncate is False else
+            t
+        )
+
+        return frame_t_to_index(t, self.fps)
+    
+    def from_index(
+        self,
+        index: int
+    ) -> Fraction:
+        """
+        Transform the given index to a 't' time
+        moment value.
+
+        The formula:
+        - `frame_index * (1 / fps)`
+        """
+        return frame_index_to_t(index, self.fps)
 
     def truncated(
         self,
         t: Union[int, float, Fraction]
-    ):
+    ) -> Fraction:
         """
         Get the 't' value provided but truncated.
 
@@ -338,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.
 
@@ -367,6 +437,9 @@ class _T:
 
         Useful when you need the next value for a
         range in an iteration or similar.
+
+        The formula:
+        - `t + n * (1 / fps)`
         """
         t = (
             self.truncated(t)
@@ -374,7 +447,7 @@ class _T:
             self.rounded(t)
         )
 
-        return t + n * self._t_handler.time_base
+        return t + n * (1 / self._t_handler.fps)
     
     def previous(
         self,
@@ -395,6 +468,9 @@ class _T:
         Be careful, if the 'truncated' value is 0
         this will give you an unexpected negative
         value.
+
+        The formula:
+        - `t - n * (1 / fps)`
         """
         t = (
             self.truncated(t)
@@ -402,7 +478,7 @@ class _T:
             self.rounded(t)
         )
 
-        return t - n * self._t_handler.time_base
+        return t - n * (1 / self._t_handler.fps)
     
 class _Pts:
     """
@@ -442,6 +518,9 @@ class _Pts:
         None, we will not make any conversion
         and the value received could be useless
         because it is in the middle of a range.
+
+        The formula:
+        - `int(t / time_base)`
         """
         t = (
             self._t_handler.t.truncated(t)
@@ -462,14 +541,70 @@ class _Pts:
         Transform the given 'pts' to a 't' value
         truncating, rounding or applying no 
         variation.
+
+        The formula:
+        - `pts * time_base`
         """
         return self._t_handler.t.from_pts(pts, do_truncate)
+    
+    def to_index(
+        self,
+        pts: int,
+        do_truncate: Union[bool, None] = True
+    ) -> int:
+        """
+        Transform the given 'pts' to a index value
+        truncating, rounding or applying no
+        variation.
+
+        The formula:
+        - `int(round((pts * time_base) * fps))`
+        """
+        return self._t_handler.t.to_index(
+            self.to_t(pts, do_truncate = None),
+            do_truncate = do_truncate
+        )
+    
+    def from_index(
+        self,
+        index: int
+    ) -> Fraction:
+        """
+        Transform the given index to a 't' time
+        moment value.
+
+        The formula:
+        - `int((frame_index * (1 / fps)) * time_base)`
+        """
+        return self.from_t(
+            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
@@ -488,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
@@ -510,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'
@@ -517,6 +660,9 @@ class _Pts:
 
         Useful when you need the next value for a
         range in an iteration or similar.
+
+        The formula:
+        - `pts + n * ticks_per_frame`
         """
         pts = (
             self.truncated(pts)
@@ -533,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
@@ -545,6 +695,9 @@ class _Pts:
         Be careful, if the 'truncated' value is 0
         this will give you an unexpected negative
         value.
+
+        The formula:
+        - `pts - n * ticks_per_frame`
         """
         pts = (
             self.truncated(pts)
@@ -553,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
@@ -621,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,
@@ -651,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`
     """
@@ -670,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],
@@ -680,6 +852,9 @@ def get_ticks_per_frame(
     tick is the minimum amount of time we
     spend from one frame to the next.
 
+    (!) This is only valid for video
+    apparently.
+
     The formula:
     - `1 / (fps * time_base)`
     """
@@ -723,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