yta-video-frame-time 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

yta_video_frame_time/t_fraction.py

@@ -15,7 +15,11 @@ from yta_validation import PythonValidator
 from quicktions import Fraction
 from typing import Union
 
+import math
 
+
+# TODO: This T class has to be removed
+# and replaced by the THandler
 class T:
     """
     Class to simplify the way we work with a
@@ -149,16 +153,9 @@ class T:
         return T(pts * time_base, time_base)
     
 
-# TODO: Careful with this below
-"""
-To obtain the pts step, or frame duration in
-ticks, you need to apply 2 formulas that are
-different according to if the frame is video
-or audio:
-- Audio: .samples
-- Video: int(round((1 / .fps) / .time_base))
-"""
-    
+# TODO: This below is interesting, above
+# is old...
+
 def get_ts(
     start: Union[int, float, Fraction],
     end: Union[int, float, Fraction],
@@ -173,21 +170,21 @@ def get_ts(
     [start, end) because the last frame is the
     start of another time range.
     """
-    start = T.from_fps(start, fps).truncated
-    end = T.from_fps(end, fps).truncated
+    thandler = THandler(fps)
+
+    start = thandler.t.truncated(start)
+    end = thandler.t.truncated(end)
 
-    time_base = fps_to_time_base(fps)
-    
     return [
-        start + i * time_base
-        for i in range((end - start) // time_base)
+        start + i * thandler.time_base
+        for i in range((end - start) // thandler.time_base)
     ]
 
 def round_t(
     t: Union[int, float, Fraction],
     time_base = Fraction(1, 60),
     do_truncate: bool = True
-):
+) -> Fraction:
     """
     Round the given 't' time moment to the most
     near multiple of the given 'time_base' (or
@@ -216,19 +213,610 @@ def round_t(
         round(steps) # round(float(steps))
     )
 
-    return snapped_steps * time_base
+    return parse_fraction(snapped_steps * time_base)
+
+def round_pts(
+    pts: int,
+    fps: Union[int, float, Fraction] = 60,
+    time_base = Fraction(1, 60),
+    do_truncate: bool = True
+) -> int:
+    """
+    Round the given 'pts' presentation
+    timestamp to the most near index 
+    corresponding pts value (or the previous
+    one always if 'do_truncate' is True).
+
+    This method is very useful to truncate 
+    'pts' values in order to get the frames or
+    samples for the specific and exact time 
+    moments according to their fps or sample
+    rate (that should be passed as the
+    'time_base' parameter).
+
+    Pts value is calculated based on the 'fps'
+    and 'time_base', but here is an easier
+    example using the time moments.
+
+    Examples below, with `time_base = 1/5`:
+    - `t = 0.25` => `0.2` (truncated or rounded)
+    - `t = 0.35` => `0.2` (truncated)
+    - `t = 0.45` => `0.4` (truncated or rounded)
+    - `t = 0.55` => `0.6` (rounded)
+    """
+    ticks_per_frame = get_ticks_per_frame(fps, time_base)
+
+    frame_index = pts / ticks_per_frame
+
+    frame_index = (
+        math.floor(frame_index)
+        if do_truncate else
+        round(frame_index)
+    )
+    
+    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
+we are working with the 'pts' we need 
+to use the 'time_base'.
+"""
+
+class _T:
+    """
+    Internal class to be used by the THandler
+    as a shortcut to the functionality 
+    related with 't' values.
+    """
+
+    def __init__(
+        self,
+        t_handler: 'THandler'
+    ):
+        self._t_handler: THandler = t_handler
+        """
+        Instance of the parent THandler to
+        access to its properties.
+        """
+
+    def from_pts(
+        self,
+        pts: int,
+        do_truncate: Union[bool, None] = True
+    ) -> Fraction:
+        """
+        Get the 't' time moment for the frame
+        defined by the 'pts' presentation
+        timestamp.
+
+        If 't' is in a [start, end) range, we
+        will obtain the 'start' value if 't'
+        value is closer to it than to the 'end
+        value.
+
+        If 'do_truncate' is True, we will
+        always receive the 'start' value. If
+        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`
+        """
+        pts = (
+            self._t_handler.pts.truncated(pts)
+            if do_truncate is True else
+            self._t_handler.pts.rounded(pts)
+            if do_truncate is False else
+            pts # if None
+        )
+
+        return Fraction(pts * self._t_handler.time_base)
+    
+    def to_pts(
+        self,
+        t: Union[int, float, Fraction],
+        do_truncate: Union[bool, None] = True
+    ) -> int:
+        """
+        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(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]
+    ):
+        """
+        Get the 't' value provided but truncated.
+
+        This means that if 't' is in a
+        [start, end) range, we will obtain the
+        'start' value always.
+        """
+        return round_t(t, Fraction(1, self._t_handler.fps), do_truncate = True)
+    
+    def rounded(
+        self,
+        t: Union[int, float, Fraction]
+    ):
+        """
+        Get the 't' value provided but rounded.
+
+        This means that if 't' is in a
+        [start, end) range, we will obtain
+        the 'start' or the 'end' value according
+        to which one is closer to the that 't'
+        value provided.
+        """
+        return round_t(t, Fraction(1, self._t_handler.fps), do_truncate = False)
+    
+    def next(
+        self,
+        t: Union[int, float, Fraction],
+        n: int = 1,
+        do_truncate: bool = True
+    ) -> Fraction:
+        """
+        Get the value that is 'n' times ahead of
+        the 't' property of this instance 
+        (truncated or rounded according to the
+        'do_truncate' parameter provided).
+
+        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)
+            if do_truncate else
+            self.rounded(t)
+        )
+
+        return t + n * (1 / self._t_handler.fps)
+    
+    def previous(
+        self,
+        t: Union[int, float, Fraction],
+        n: int = 1,
+        do_truncate: bool = True
+    ) -> Fraction:
+        """
+        Get the value that is 'n' times before
+        the 't' property of this instance 
+        (truncated or rounded according to the
+        'do_truncate' parameter provided).
+
+        Useful when you need the previous value to
+        check if the current is the next one or
+        similar.
+
+        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)
+            if do_truncate else
+            self.rounded(t)
+        )
+
+        return t - n * (1 / self._t_handler.fps)
+    
+class _Pts:
+    """
+    Internal class to be used by the THandler
+    as a shortcut to the functionality 
+    related with 'pts' values.
+    """
+
+    def __init__(
+        self,
+        t_handler: 'THandler'
+    ):
+        self._t_handler: THandler = t_handler
+        """
+        Instance of the parent THandler to
+        access to its properties.
+        """
+
+    def from_t(
+        self,
+        t: Union[int, float, Fraction],
+        do_truncate: Union[bool, None] = True
+    ) -> int:
+        """
+        Get the pts (the amount of accumulated
+        ticks, also called presentation timestamp),
+        for the frame defined by the 't' time
+        moment provided.
+
+        If 't' is in a [start, end) range, we
+        will obtain the 'start' value if 't'
+        value is closer to it than to the 'end
+        value.
+
+        If 'do_truncate' is True, we will
+        always receive the 'start' value. If
+        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)
+            if do_truncate is True else
+            self._t_handler.t.rounded(t)
+            if do_truncate is False else
+            t # if None
+        )
+
+        return int(t / self._t_handler.time_base)
+    
+    def to_t(
+        self,
+        pts: int,
+        do_truncate: Union[bool, None] = True
+    ) -> Fraction:
+        """
+        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((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
+        )
+
+    def truncated(
+        self,
+        pts: int
+    ):
+        """
+        Get the 'pts' value provided but truncated.
+
+        This means that if 't' is in a
+        [start, end) range, we will obtain the
+        'start' value always.
+        """
+        return round_pts(
+            pts = pts,
+            fps = self._t_handler.fps,
+            time_base = self._t_handler.time_base,
+            do_truncate = True
+        )
+    
+    def rounded(
+        self,
+        pts: int
+    ) -> int:
+        """
+        Get the 'pts' value provided but rounded.
+
+        This means that if 't' is in a
+        [start, end) range, we will obtain
+        the 'start' or the 'end' value according
+        to which one is closer to the that 't'
+        value provided.
+        """
+        return round_pts(
+            pts = pts,
+            fps = self._t_handler.fps,
+            time_base = self._t_handler.time_base,
+            do_truncate = False
+        )
+    
+    def next(
+        self,
+        pts: int,
+        n: int = 1,
+        do_truncate: bool = True
+    ) -> int:
+        """
+        Get the value that is 'n' times ahead of
+        the 'pts' value provided (truncated or
+        rounded according to the 'do_truncate'
+        parameter provided).
+
+        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)
+            if do_truncate else
+            self.rounded(pts)
+        )
+
+        return pts + n * get_ticks_per_frame(self._t_handler.fps, self._t_handler.time_base)
+    
+    def previous(
+        self,
+        pts: int,
+        n: int = 1,
+        do_truncate: bool = True
+    ) -> int:
+        """
+        Get the value that is 'n' times before
+        the 't' property of this instance 
+        (truncated or rounded according to the
+        'do_truncate' parameter provided).
+
+        Useful when you need the previous value to
+        check if the current is the next one or
+        similar.
+
+        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)
+            if do_truncate else
+            self.rounded(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
+    pyav frames time moments, indexes and
+    pts values.
+
+    This is an example of what a video has:
+    - `fps = 60`
+    - `time_base = 1 / 15360`
+    - `tick = fps * time_base = 256`
+
+    So, considering this above:
+    - Frame #1: `pts[0] = 256 * 0 = 0`
+    - Frame #2: `pts[1] = 256 * 1 = 256`
+    - Frame #16: `pts[15] = 256 * 15 = 3840`
+    """
+
+    def __init__(
+        self,
+        fps: Union[int, float, Fraction],
+        time_base: Union[Fraction, None] = None
+    ):
+        """
+        If the 'time_base' provided is None it will
+        be automatically `1/fps`.
+        """
+        ParameterValidator.validate_mandatory_positive_number('fps', fps, do_include_zero = False)
+        ParameterValidator.validate_instance_of('time_base', time_base, 'Fraction')
+
+        self.fps: Fraction = parse_fraction(fps)
+        """
+        The frames per second.
+        """
+        self.time_base: Fraction = (
+            time_base
+            if time_base is not None else
+            fps_to_time_base(self.fps)
+        )
+        """
+        The time base.
+        """
+        self.t: _T = _T(self)
+        """
+        Shortcut to the instance that handles
+        the 't' related functionality.
+        """
+        self.pts: _Pts = _Pts(self)
+        """
+        Shortcut to the instance that handles
+        the 'pts' related functionality.
+        """
+
+# TODO: I think I should create a THandler
+# that receives 'fps' and 'time_base' and
+# then, by passing a 't' value, we can 
+# calculate everything we need, so we
+# simplify all these processes
+def frame_t_to_index(
+    t: Union[float, int, Fraction],
+    fps: Union[float, int, Fraction]
+) -> int:
+    """
+    Get the index of the frame with the 
+    given 't' time moment, based on the
+    also provided 'fps'.
+
+    The formula:
+    - `int(t * fps)`
+    """
+    return int(parse_fraction(t) * fps)
+
+def frame_index_to_t(
+    index: int,
+    fps: Union[float, int, Fraction] 
+):
+    """
+    Get the 't' time moment for the frame
+    with the given 'index', based on the
+    also provided 'fps'.
+
+    The formula:
+    - `frame_index * (1 / fps)`
+    """
+    return index * parse_fraction(1, parse_fraction(fps))
+
+def frame_t_to_pts(
+    t: Union[float, int, Fraction],
+    fps: Union[float, int, Fraction],
+    time_base: Fraction
+):
+    """
+    Get the pts (the amount of accumulated
+    ticks, also called presentation timestamp),
+    for the frame defined by the 't' time
+    moment provided, based on the also provided
+    'fps' and 'time_base'.
+
+    The formula:
+    - `frame_index * ticks_per_frame`
+    """
+    return frame_t_to_index(t, fps) * get_ticks_per_frame(fps, time_base)
+
+def frame_pts_to_t(
+    pts: int,
+    time_base: Fraction 
+) -> Fraction:
+    """
+    Get the 't' time moment of the frame with
+    the given 'pts' (the amount of accumulated
+    ticks, also called presentation timestamp),
+    based on the also provided 'time_base'.
+
+    The formula:
+    - `pts * time_base`
+    """
+    return parse_fraction(pts * time_base)
+    
+def get_ticks_per_frame(
+    fps: Union[float, int, Fraction],
+    time_base: Fraction
+) -> int:
+    """
+    Get the amount of ticks per frame. A
+    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)`
+    """
+    return int(Fraction(1, 1) / (fps * time_base))
+
+def fps_to_frame_duration(
+    fps: Union[float, int, Fraction]
+) -> Fraction:
+    """
+    Get the frame duration based on the 'fps'
+    provided.
+
+    The formula:
+    - `1 / fps`
+    """
+    return Fraction(1, parse_fraction(fps))
 
 def fps_to_time_base(
-    fps: Union[int, float, Fraction]
+    fps: Union[float, int, Fraction]
 ) -> Fraction:
     """
-    Get the pyav time base from the given
-    'fps'.
+    Get the time base based on the given 'fps',
+    that will be basically `1/fps`. This is a
+    bit useless, just when we don't want to
+    think too much to use a time base and we
+    want to use the fps.
+
+    The formula:
+    - `1 / fps`
     """
-    return (
-        Fraction(1, fps)
-        if NumberValidator.is_int(fps) else
-        Fraction(1, 1) / fps
-        if PythonValidator.is_instance_of(fps, 'Fraction') else
-        Fraction(1, 1) / Fraction.from_float(fps).limit_denominator(1000000) # if float
-    )
+    return Fraction(1, parse_fraction(fps))
+    
+def parse_fraction(
+    value: Union[float, int, Fraction]
+) -> Fraction:
+    """
+    Parse the provided 'value' as a Fraction
+    and limits its denominator.
+    """
+    fraction = Fraction(value)#.limit_denominator(100_000)
+
+    return fraction
+    

{yta_video_frame_time-0.0.5.dist-info → yta_video_frame_time-0.0.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: yta-video-frame-time
-Version: 0.0.5
+Version: 0.0.7
 Summary: Youtube Autonomous Video Frame Time Module
 Author: danialcala94
 Author-email: danielalcalavalera@gmail.com

yta_video_frame_time-0.0.7.dist-info/RECORD

@@ -0,0 +1,6 @@
+yta_video_frame_time/__init__.py,sha256=-YOa7lOKdiA3FwDEHHU1tHobnmhjFpTaVLfJQLZqoMI,22252
+yta_video_frame_time/t_fraction.py,sha256=hsCNZajG98XGnWYI0T6wSfBnAK3vf7ZiFI_GZHO8yRI,22254
+yta_video_frame_time-0.0.7.dist-info/LICENSE,sha256=6kbiFSfobTZ7beWiKnHpN902HgBx-Jzgcme0SvKqhKY,1091
+yta_video_frame_time-0.0.7.dist-info/METADATA,sha256=ooHYnwkytyyjpKRKLKakXhDJJD-HAmpXxvWuaXfVrZo,515
+yta_video_frame_time-0.0.7.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+yta_video_frame_time-0.0.7.dist-info/RECORD,,

yta_video_frame_time-0.0.5.dist-info/RECORD

@@ -1,6 +0,0 @@
-yta_video_frame_time/__init__.py,sha256=-YOa7lOKdiA3FwDEHHU1tHobnmhjFpTaVLfJQLZqoMI,22252
-yta_video_frame_time/t_fraction.py,sha256=JR2GNDjk06I2YFKTVJpNQ2hxlEwUF3QG02Ba2sEDrj0,6639
-yta_video_frame_time-0.0.5.dist-info/LICENSE,sha256=6kbiFSfobTZ7beWiKnHpN902HgBx-Jzgcme0SvKqhKY,1091
-yta_video_frame_time-0.0.5.dist-info/METADATA,sha256=Lh-jnjYVJh5mmLYq0ngkgMP1u9L_ta23nMQrfgNkZKQ,515
-yta_video_frame_time-0.0.5.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-yta_video_frame_time-0.0.5.dist-info/RECORD,,