Correction of FrameUtility V3

.github/workflows/ci.yml

@@ -65,11 +65,11 @@ jobs:
         if: matrix.os == 'ubuntu-latest'
         run: |
           sudo apt-get update
-          sudo apt-get install libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-3.0 python3-gi python3-gi-cairo
+          sudo apt-get install libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-3.0 python3-gi python3-gi-cairo ffmpeg
       - name: Install platform-specific requirements (macOS) # Note: brew is very slow sometimes. TODO: speedup brew by using caching.
         if: matrix.os == 'macos-latest'
-        run: brew install python py3cairo pygobject3 pango
-
+        run: brew install python py3cairo pygobject3 pango ffmpeg
+    
       - name: Install fonts (non-Windows)
         if: matrix.os != 'windows-latest'
         run: |

docs/Proof algorithm - ms_to_frames.md

@@ -0,0 +1,55 @@
+# ms_to_frames
+To convert an frame to an ms, here is the formula: $$ms = frame * {1 \over fps} * 1000$$
+But depending on what the user want, he may need to floor the result or round it (see docs of timestamps.py for more information)
+Important to note, $frame \in \mathbb{N}$. This means we need to take the **integer** between the 2 bounds of the inequations that are detailed below.
+
+## Explanation for rounding method
+$$ms = \text{round}(frame * {1 \over fps} * 1000)$$
+
+Important to note, here the rounding method round up, so, if it encounter $round(x.5)$, it will become $x + 1$
+
+From the previous equation, we can deduce this:
+$$ms - 0.5 \le frame * {1 \over fps} * 1000 < ms + 0.5$$
+
+And from the previous inequation, we can isolate $frame$ like this:
+$$(ms - 0.5) * fps * {1 \over 1000} \le frame < (ms + 0.5) * fps * {1 \over 1000}$$
+
+Algorithm:
+```py
+# We use the upper bound
+upper_bound = (ms + 0.5) * fps * 1/1000
+# Then, we trunc the result
+trunc_frame = int(upper_bound)
+
+# If the upper_bound equals to the trunc_frame, this means that we don't respect the inequation because it is "greater than", not "greater than or equals".
+# So if it happens, this means we need to return the previous frame
+if upper_bound == trunc_frame:
+    return trunc_frame - 1
+else:
+    return trunc_frame
+```
+
+
+## Explanation for floor method
+$$ms = \lfloor frame * {1 \over fps} * 1000 \rfloor$$
+
+From the previous equation, we can deduce this:
+$$ms \le frame * {1 \over fps} * 1000 < ms + 1$$
+
+And from the previous inequation, we can isolate $frame$ like this:
+$$ms * fps * {1 \over 1000} \le frame < (ms + 1) * fps * {1 \over 1000}$$
+
+Algorithm:
+```py
+# We use the upper bound
+upper_bound = (ms + 1) * fps * 1/1000
+# Then, we trunc the result
+trunc_frame = int(upper_bound)
+
+# If the upper_bound equals to the trunc_frame, this means that we don't respect the inequation because it is "greater than", not "greater than or equals".
+# So if it happens, this means we need to return the previous frame
+if upper_bound == trunc_frame:
+    return trunc_frame - 1
+else:
+    return trunc_frame
+```

examples/2 - Beginner/2 - Utilities.py

@@ -13,12 +13,16 @@
 As exercise, you can try to transform it into an horizontal one :)
 """
 
+from fractions import Fraction
 from pyonfx import *
 import random
 
 io = Ass("in.ass")
 meta, styles, lines = io.get_data()
 
+# Let's load the timestamps
+timestamps_list = Timestamps.from_fps(Fraction(24000, 1001))
+
 
 def romaji(line, l):
     for syl in Utils.all_non_empty(line.syls):
@@ -44,7 +48,9 @@ def romaji(line, l):
         # Main Effect
         # Let's create a FrameUtility object and set up a radius for the random positions
         FU = FrameUtility(
-            line.start_time + syl.start_time, line.start_time + syl.end_time
+            line.start_time + syl.start_time,
+            line.start_time + syl.end_time,
+            timestamps_list,
         )
         radius = 2
 

examples/2 - Beginner/3 - Variants.py

@@ -16,6 +16,7 @@
 It could look like much code for such a simple effect, but it's needed and an easy method with much potential for extensions.
 """
 
+from fractions import Fraction
 from pyonfx import *
 import random
 import math
@@ -27,6 +28,9 @@
 star = Shape.star(5, 4, 10)
 CU = ColorUtility(lines)
 
+# Let's load the timestamps
+timestamps_list = Timestamps.from_fps(Fraction(24000, 1001))
+
 
 def romaji(line, l):
     # Setting up a delay, we will use it as duration time of the leadin and leadout effects
@@ -107,7 +111,9 @@ def romaji(line, l):
         # Jump-in to the first syl
         jump_height = 18
         if syl.i == 0:
-            FU = FrameUtility(line.start_time - line.leadin / 2, line.start_time)
+            FU = FrameUtility(
+                line.start_time - line.leadin / 2, line.start_time, timestamps_list
+            )
             for s, e, i, n in FU:
                 l.start_time = s
                 l.end_time = e
@@ -133,7 +139,9 @@ def romaji(line, l):
             else syl.width
         )
         FU = FrameUtility(
-            line.start_time + syl.start_time, line.start_time + syl.end_time
+            line.start_time + syl.start_time,
+            line.start_time + syl.end_time,
+            timestamps_list,
         )
         for s, e, i, n in FU:
             l.start_time = s

examples/3 - Advanced/1 - WIP.py

@@ -1,9 +1,13 @@
+from fractions import Fraction
 from pyonfx import *
 import random
 
 io = Ass("in.ass")
 meta, styles, lines = io.get_data()
 
+# Let's load the timestamps
+timestamps_list = Timestamps.from_fps(Fraction(24000, 1001))
+
 circle = Shape.ellipse(20, 20)
 
 
@@ -29,7 +33,9 @@ def romaji(line, l):
         l.layer = 1
 
         FU = FrameUtility(
-            line.start_time + syl.start_time, line.start_time + syl.end_time
+            line.start_time + syl.start_time,
+            line.start_time + syl.end_time,
+            timestamps_list,
         )
         rand = random.uniform(-10, 10)
 

pyonfx/__init__.py

@@ -2,8 +2,9 @@
 
 from .font_utility import Font
 from .ass_core import Ass, Meta, Style, Line, Word, Syllable, Char
-from .convert import Convert, ColorModel
+from .convert import Convert, ColorModel, TimeType
 from .shape import Shape
+from .timestamps import RoundingMethod, Timestamps
 from .utils import Utils, FrameUtility, ColorUtility
 
 __version__ = "0.9.13"