Add timestamps class

.github/workflows/main.yml

@@ -30,6 +30,7 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
+        sudo apt update && sudo apt install ffmpeg 
         python -m pip install --upgrade pip
         pip install -r requirements-dev.txt
     - name: Typecheck with mypy

pysubs2/__init__.py

@@ -4,6 +4,7 @@
 from . import time, formats, cli, whisper
 from .exceptions import *
 from .common import Color, Alignment, VERSION
+from .timestamps import Timestamps, TimeType
 
 #: Alias for :meth:`SSAFile.load()`.
 load = SSAFile.load

pysubs2/microdvd.py

@@ -1,11 +1,12 @@
-from functools import partial
+from numbers import Real
+from typing import Union
 import re
 from .exceptions import UnknownFPSError
 from .ssaevent import SSAEvent
 from .ssastyle import SSAStyle
 from .formatbase import FormatBase
 from .substation import parse_tags
-from .time import ms_to_frames, frames_to_ms
+from .timestamps import Timestamps, TimeType
 
 #: Matches a MicroDVD line.
 MICRODVD_LINE = re.compile(r" *\{ *(\d+) *\} *\{ *(\d+) *\}(.+)")
@@ -20,8 +21,13 @@ def guess_format(cls, text):
             return "microdvd"
 
     @classmethod
-    def from_file(cls, subs, fp, format_, fps=None, **kwargs):
+    def from_file(cls, subs, fp, format_, fps:Union[None,Real,Timestamps] = None, **kwargs):
         """See :meth:`pysubs2.formats.FormatBase.from_file()`"""
+        if isinstance(fps, Real):
+            timestamps = Timestamps.from_fps(fps)
+        elif isinstance(fps, Timestamps):
+            timestamps = fps
+
         for line in fp:
             match = MICRODVD_LINE.match(line)
             if not match:
@@ -35,15 +41,19 @@ def from_file(cls, subs, fp, format_, fps=None, **kwargs):
                 # it as text of the first subtitle. In that case, we skip
                 # this auxiliary subtitle and proceed with reading.
                 try:
-                    fps = float(text)
+                    fps = float(text)  # type: ignore[assignment]
                     subs.fps = fps
+                    timestamps = Timestamps.from_fps(fps)  # type: ignore[arg-type]
                     continue
                 except ValueError:
                     raise UnknownFPSError("Framerate was not specified and "
                                           "cannot be read from "
                                           "the MicroDVD file.")
 
-            start, end = map(partial(frames_to_ms, fps=fps), (fstart, fend))
+            # I chose the format SRT, but it could be anyone.
+            # SRT simply has a precision in milliseconds which can be better.
+            start = timestamps.frames_to_ms(fstart, TimeType.START)
+            end = timestamps.frames_to_ms(fend, TimeType.END)
 
             def prepare_text(text):
                 text = text.replace("|", r"\N")
@@ -63,7 +73,7 @@ def style_replacer(match: re.Match) -> str:
             subs.append(ev)
 
     @classmethod
-    def to_file(cls, subs, fp, format_, fps=None, write_fps_declaration=True, apply_styles=True, **kwargs):
+    def to_file(cls, subs, fp, format_, fps:Union[None,Real,Timestamps] = None, write_fps_declaration=True, apply_styles=True, **kwargs):
         """
         See :meth:`pysubs2.formats.FormatBase.to_file()`
 
@@ -80,7 +90,10 @@ def to_file(cls, subs, fp, format_, fps=None, write_fps_declaration=True, apply_
 
         if fps is None:
             raise UnknownFPSError("Framerate must be specified when writing MicroDVD.")
-        to_frames = partial(ms_to_frames, fps=fps)
+        elif isinstance(fps, Real):
+            timestamps = Timestamps.from_fps(fps)
+        elif isinstance(fps, Timestamps):
+            timestamps = fps
 
         def is_entirely_italic(line: SSAEvent) -> bool:
             style = subs.styles.get(line.style, SSAStyle.DEFAULT_STYLE)
@@ -104,7 +117,8 @@ def is_entirely_italic(line: SSAEvent) -> bool:
             if apply_styles and is_entirely_italic(line):
                 text = "{Y:i}" + text
 
-            start, end = map(to_frames, (line.start, line.end))
+            start = timestamps.ms_to_frames(line.start, TimeType.START)
+            end = timestamps.ms_to_frames(line.end, TimeType.END)
 
             # XXX warn on underflow?
             if start < 0: start = 0

pysubs2/ssaevent.py

@@ -1,10 +1,12 @@
+import dataclasses
 import re
 import warnings
-from typing import Optional, Dict, Any, ClassVar
-import dataclasses
+from numbers import Real
+from typing import Optional, Dict, Any, ClassVar, Union
 
 from .common import IntOrFloat
 from .time import ms_to_str, make_time
+from .timestamps import Timestamps, TimeType
 
 
 @dataclasses.dataclass(repr=False, eq=False, order=False)
@@ -106,16 +108,35 @@ def plaintext(self, text: str):
         self.text = text.replace("\n", r"\N")
 
     def shift(self, h: IntOrFloat=0, m: IntOrFloat=0, s: IntOrFloat=0, ms: IntOrFloat=0,
-              frames: Optional[int]=None, fps: Optional[float]=None):
+              frames: Optional[int]=None, fps: Optional[Union[Real,Timestamps]]=None):
         """
         Shift start and end times.
 
         See :meth:`SSAFile.shift()` for full description.
 
         """
-        delta = make_time(h=h, m=m, s=s, ms=ms, frames=frames, fps=fps)
-        self.start += delta
-        self.end += delta
+        if frames is not None:
+            if fps is None:
+                raise ValueError("Both fps and frames must be specified")
+            if isinstance(fps, Real):
+                timestamps = Timestamps.from_fps(fps)
+            elif isinstance(fps, Timestamps):
+                timestamps = fps
+            else:
+                raise TypeError("Unexpected type for fps")
+
+            start_frame = timestamps.ms_to_frames(self.start, TimeType.START)
+            end_frame = timestamps.ms_to_frames(self.end, TimeType.END)
+
+            start_frame += frames
+            end_frame += frames
+
+            self.start = timestamps.frames_to_ms(start_frame, TimeType.START)
+            self.end = timestamps.frames_to_ms(end_frame, TimeType.END)
+        else:
+            delta = make_time(h=h, m=m, s=s, ms=ms)
+            self.start += delta
+            self.end += delta
 
     def copy(self) -> "SSAEvent":
         """Return a copy of the SSAEvent."""

pysubs2/ssafile.py

@@ -2,16 +2,19 @@
 import io
 from io import open
 from itertools import chain
+from numbers import Real
 import os.path
 import logging
-from typing import Optional, List, Dict, Iterable, Any, overload, Iterator
+from typing import Optional, List, Dict, Iterable, Any, Union, overload, Iterator
+
 
 from .common import IntOrFloat
 from .formats import autodetect_format, get_format_class, get_format_identifier
 from .substation import is_valid_field_content
 from .ssaevent import SSAEvent
 from .ssastyle import SSAStyle
 from .time import make_time, ms_to_str
+from .timestamps import Timestamps
 
 
 class SSAFile(MutableSequence):
@@ -245,7 +248,7 @@ def to_file(self, fp: io.TextIOBase, format_: str, fps: Optional[float]=None, **
     # ------------------------------------------------------------------------
 
     def shift(self, h: IntOrFloat=0, m: IntOrFloat=0, s: IntOrFloat=0, ms: IntOrFloat=0,
-              frames: Optional[int]=None, fps: Optional[float]=None):
+              frames: Optional[int]=None, fps: Optional[Union[Real,Timestamps]]=None):
         """
         Shift all subtitles by constant time amount.
 
@@ -262,10 +265,8 @@ def shift(self, h: IntOrFloat=0, m: IntOrFloat=0, s: IntOrFloat=0, ms: IntOrFloa
             ValueError: Invalid fps or missing number of frames.
 
         """
-        delta = make_time(h=h, m=m, s=s, ms=ms, frames=frames, fps=fps)
         for line in self:
-            line.start += delta
-            line.end += delta
+            line.shift(h=h, m=m, s=s, ms=ms, frames=frames, fps=fps)
 
     def transform_framerate(self, in_fps: float, out_fps: float):
         """

pysubs2/time.py

@@ -1,7 +1,9 @@
 from collections import namedtuple
+from numbers import Real
 import re
-from typing import Optional, List, Tuple, Sequence
+from typing import Optional, Tuple, Sequence, Union, cast
 from pysubs2.common import IntOrFloat
+from .timestamps import Timestamps, TimeType
 
 #: Pattern that matches both SubStation and SubRip timestamps.
 TIMESTAMP = re.compile(r"(\d{1,2}):(\d{1,2}):(\d{1,2})[.,](\d{1,3})")
@@ -13,7 +15,7 @@
 
 
 def make_time(h: IntOrFloat=0, m: IntOrFloat=0, s: IntOrFloat=0, ms: IntOrFloat=0,
-              frames: Optional[int]=None, fps: Optional[float]=None):
+              frames: Optional[int]=None, fps: Optional[Union[Real,Timestamps]]=None, time_type: Optional[TimeType] = None):
     """
     Convert time to milliseconds.
 
@@ -30,10 +32,15 @@ def make_time(h: IntOrFloat=0, m: IntOrFloat=0, s: IntOrFloat=0, ms: IntOrFloat=
         2000
 
     """
-    if frames is None and fps is None:
+    if frames is None and fps is None and time_type is None:
         return times_to_ms(h, m, s, ms)
-    elif frames is not None and fps is not None:
-        return frames_to_ms(frames, fps)
+    elif frames is not None and fps is not None and time_type is not None:
+        if isinstance(fps, Real):
+            timestamps = Timestamps.from_fps(fps)
+        elif isinstance(fps, Timestamps):
+            timestamps = fps
+
+        return timestamps.frames_to_ms(frames, time_type)
     else:
         raise ValueError("Both fps and frames must be specified")
 
@@ -85,43 +92,37 @@ def times_to_ms(h: IntOrFloat=0, m: IntOrFloat=0, s: IntOrFloat=0, ms: IntOrFloa
 def frames_to_ms(frames: int, fps: float) -> int:
     """
     Convert frame-based duration to milliseconds.
-    
+
     Arguments:
         frames: Number of frames (should be int).
         fps: Framerate (must be a positive number, eg. 23.976).
-    
+
     Returns:
         Number of milliseconds (rounded to int).
-        
+
     Raises:
         ValueError: fps was negative or zero.
-
-    """
-    if fps <= 0:
-        raise ValueError(f"Framerate must be a positive number ({fps}).")
 
-    return int(round(frames * (1000 / fps)))
+    """
+    return Timestamps.from_fps(cast(Real, fps)).frames_to_ms(frames)
 
 
 def ms_to_frames(ms: IntOrFloat, fps: float) -> int:
     """
     Convert milliseconds to number of frames.
-    
+
     Arguments:
         ms: Number of milliseconds (may be int, float or other numeric class).
         fps: Framerate (must be a positive number, eg. 23.976).
-    
+
     Returns:
         Number of frames (int).
-        
+
     Raises:
         ValueError: fps was negative or zero.
-
-    """
-    if fps <= 0:
-        raise ValueError(f"Framerate must be a positive number ({fps}).")
 
-    return int(round((ms / 1000) * fps))
+    """
+    return Timestamps.from_fps(cast(Real, fps)).ms_to_frames(int(ms))
 
 
 def ms_to_times(ms: IntOrFloat) -> Tuple[int, int, int, int]: