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

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

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

{yta_video_frame_time-0.0.6 → yta_video_frame_time-0.0.8}/pyproject.toml

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

{yta_video_frame_time-0.0.6 → yta_video_frame_time-0.0.8}/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,8 +337,47 @@ 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(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,
@@ -367,6 +421,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 +431,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 +452,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 +462,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 +502,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,8 +525,55 @@ 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((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
+        )
+    
+    """
+    This about the pts is not 100% sure as it
+    is only a value to display the frames but
+    not accurate and depends on the encoder.
+
+    Maybe we don't want all this functionality
+    but only the one that is 100% sure its
+    working properly.
+    """
 
     def truncated(
         self,
@@ -475,6 +585,8 @@ class _Pts:
         This means that if 't' is in a
         [start, end) range, we will obtain the
         'start' value always.
+
+        (!) This is valid only for video
         """
         return round_pts(
             pts = pts,
@@ -495,6 +607,8 @@ class _Pts:
         the 'start' or the 'end' value according
         to which one is closer to the that 't'
         value provided.
+
+        (!) This is valid only for video.
         """
         return round_pts(
             pts = pts,
@@ -503,7 +617,7 @@ class _Pts:
             do_truncate = False
         )
     
-    def next(
+    def next_video(
         self,
         pts: int,
         n: int = 1,
@@ -517,6 +631,11 @@ class _Pts:
 
         Useful when you need the next value for a
         range in an iteration or similar.
+
+        (!) This is valid only for video.
+
+        The formula:
+        - `pts + n * ticks_per_frame`
         """
         pts = (
             self.truncated(pts)
@@ -526,7 +645,32 @@ class _Pts:
 
         return pts + n * get_ticks_per_frame(self._t_handler.fps, self._t_handler.time_base)
     
-    def previous(
+    def next_audio(
+        self,
+        pts: int,
+        samples_per_frame: int,
+        n: int = 1
+    ) -> int:
+        """
+        Get the value that is 'n' times ahead of
+        the 'pts' value provided according to the
+        number of 'samples_per_frame' each frame
+        has.
+
+        TODO: Are we sure that the number of 
+        samples per frame is always the same (?)
+
+        Useful when you need the next value for a
+        range in an iteration or similar.
+
+        (!) This is valid only for audio.
+
+        The formula:
+        - `pts + (n * samples_per_frame)`
+        """
+        return pts + (n * samples_per_frame)
+    
+    def previous_video(
         self,
         pts: int,
         n: int = 1,
@@ -545,6 +689,11 @@ class _Pts:
         Be careful, if the 'truncated' value is 0
         this will give you an unexpected negative
         value.
+
+        (!) This is valid only for video.
+
+        The formula:
+        - `pts - n * ticks_per_frame`
         """
         pts = (
             self.truncated(pts)
@@ -553,6 +702,31 @@ class _Pts:
         )
 
         return pts - n * get_ticks_per_frame(self._t_handler.fps, self._t_handler.time_base)
+    
+    def previous_audio(
+        self,
+        pts: int,
+        samples_per_frame: int,
+        n: int = 1
+    ) -> int:
+        """
+        Get the value that is 'n' times before
+        the 'pts' value provided according to the
+        number of 'samples_per_frame' each frame
+        has.
+
+        TODO: Are we sure that the number of 
+        samples per frame is always the same (?)
+
+        Useful when you need the next value for a
+        range in an iteration or similar.
+
+        (!) This is valid only for audio.
+
+        The formula:
+        - `pts - (n * samples_per_frame)`
+        """
+        return pts - (n * samples_per_frame)
 
 class THandler:
     """
@@ -651,6 +825,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 +846,20 @@ def frame_pts_to_t(
     - `pts * time_base`
     """
     return parse_fraction(pts * time_base)
+
+def get_audio_frame_duration(
+    samples: int,
+    fps: Fraction
+) -> Fraction:
+    """
+    Get the audio frame duration by giving the
+    number of '.samples' and also the rate (that
+    we call 'fps').
+
+    This is useful when trying to guess the next
+    pts or t.
+    """
+    return Fraction(samples / fps)
     
 def get_ticks_per_frame(
     fps: Union[float, int, Fraction],
@@ -680,6 +870,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)`
     """