Accept non-padded timestamps in WebVTT cue timings (#99)

* Accept non-padded timestamps in WebVTT cue timings

Closes #44

* Skip out of range VTT timestamps and tighten strict cue timings

Author: glut23

docs/source/usage.rst

@@ -461,12 +461,20 @@ are part of the cue text, and a line containing ``-->`` starts a new
 block when it is not the timings line of the current one. Cues without
 text are kept as captions with empty text.
 
+Timestamps with fields shorter than the specification requires, such as
+``0:0:13.540`` in Microsoft Teams transcripts or ``0:1:5.2``, are accepted
+and the captions are saved in the standard ``00:00:13.540`` and
+``00:01:05.200`` format. The fraction of a second is padded on the right,
+so ``.2`` is read as 200 milliseconds.
+
 By default the parser ignores blocks it cannot parse, so a cue with
-malformed timings such as ``00:00:00.-004 --> 00:00:04.300`` is skipped.
+malformed timings such as ``00:00:00.-004 --> 00:00:04.300`` or out of
+range ones such as ``00:00:61.000 --> 00:00:62.000`` is skipped.
 To validate the content, pass ``strict=True`` to ``read``,
 ``from_buffer`` or ``from_string`` and a ``MalformedCaptionError`` is
-raised instead. Strict parsing also raises the error when a cue is not
-separated from the previous cue, comment or style by an empty line:
+raised instead. Strict parsing also raises the error for timestamps that
+are not in the WebVTT format and when a cue is not separated from the
+previous cue, comment or style by an empty line:
 
 .. code-block:: python
 

tests/samples/non_padded_timestamps.vtt

@@ -0,0 +1,13 @@
+WEBVTT
+
+6e2b1f0c-0d3a-4c1e-9a7b-2f5d8e1c4a90/12-0
+0:0:0.0 --> 0:0:3.540
+<v Jane Doe>Good morning everyone.</v>
+
+6e2b1f0c-0d3a-4c1e-9a7b-2f5d8e1c4a90/17-0
+0:0:3.540 --> 0:0:7.23
+<v John Smith>Morning, let's get started.</v>
+
+6e2b1f0c-0d3a-4c1e-9a7b-2f5d8e1c4a90/25-0
+0:1:5.2 --> 1:2:7.950
+<v Jane Doe>Thanks for joining.</v>

tests/test_models.py

@@ -31,6 +31,15 @@ def test_from_string_single_digits(self):
         self.assertEqual(timestamp.seconds, 7)
         self.assertEqual(timestamp.milliseconds, 670)
 
+    def test_from_string_short_fraction(self):
+        timestamp = Timestamp.from_string('0:1:5.2')
+        self.assertEqual(timestamp.hours, 0)
+        self.assertEqual(timestamp.minutes, 1)
+        self.assertEqual(timestamp.seconds, 5)
+        self.assertEqual(timestamp.milliseconds, 200)
+        self.assertEqual(str(timestamp), '00:01:05.200')
+        self.assertEqual(Timestamp.from_string('00:12.54').milliseconds, 540)
+
     def test_from_string_missing_hours(self):
         timestamp = Timestamp.from_string('24:11.670')
         self.assertEqual(timestamp.hours, 0)

tests/test_vtt.py

@@ -72,6 +72,48 @@ def test_is_valid(self):
                 vtt.WebVTTCueBlock.is_valid([timings, 'Caption #1'])
                 )
 
+    def test_is_valid_non_padded_timestamps(self):
+        lines = ['0:0:13.540 --> 0:0:17.85', 'Caption #1']
+        self.assertTrue(vtt.WebVTTCueBlock.is_valid(lines))
+        self.assertFalse(vtt.WebVTTCueBlock.is_valid(lines, strict=True))
+        self.assertTrue(
+            vtt.WebVTTCueBlock.is_valid(
+                ['00:13.540 --> 00:00:17.850', 'Caption #1'],
+                strict=True
+                )
+            )
+
+    def test_is_valid_strict_hours(self):
+        for timings in (
+                '0:00:13.540 --> 00:00:17.850',
+                '00:00:13.540 --> 0:00:17.850'
+                ):
+            self.assertTrue(vtt.WebVTTCueBlock.is_valid([timings]))
+            self.assertFalse(
+                vtt.WebVTTCueBlock.is_valid([timings], strict=True)
+                )
+        self.assertTrue(
+            vtt.WebVTTCueBlock.is_valid(
+                ['100:00:13.540 --> 100:00:17.850'],
+                strict=True
+                )
+            )
+
+    def test_is_valid_strict_end_timestamp_boundary(self):
+        for timings in (
+                '00:00:13.540 --> 00:00:17.8505',
+                '00:00:13.540 --> 00:00:17.850abc'
+                ):
+            self.assertFalse(
+                vtt.WebVTTCueBlock.is_valid([timings], strict=True)
+                )
+        self.assertTrue(
+            vtt.WebVTTCueBlock.is_valid(
+                ['00:00:13.540 --> 00:00:17.850 align:start'],
+                strict=True
+                )
+            )
+
     def test_from_lines(self):
         cue_block = vtt.WebVTTCueBlock.from_lines(textwrap.dedent('''
             identifier
@@ -587,6 +629,68 @@ def test_parse_ignores_malformed_cue_block(self):
         self.assertEqual(len(output.captions), 1)
         self.assertEqual(output.captions[0].text, 'Caption text #2')
 
+    def test_parse_non_padded_timestamps(self):
+        output = vtt.parse(
+            textwrap.dedent('''
+            WEBVTT
+
+            0:0:0.0 --> 0:0:3.540
+            Caption text #1
+
+            0:0:3.540 --> 0:1:5.2
+            Caption text #2
+            ''').strip().split('\n')
+            )
+        self.assertEqual(len(output.captions), 2)
+        self.assertEqual(output.captions[0].start, '00:00:00.000')
+        self.assertEqual(output.captions[0].end, '00:00:03.540')
+        self.assertEqual(output.captions[1].start, '00:00:03.540')
+        self.assertEqual(output.captions[1].end, '00:01:05.200')
+
+    def test_parse_strict_non_padded_timestamps(self):
+        with self.assertRaises(MalformedCaptionError) as cm:
+            vtt.parse(
+                textwrap.dedent('''
+                WEBVTT
+
+                00:00:00.000 --> 00:00:03.540
+                Caption text #1
+
+                0:0:3.540 --> 0:0:7.230
+                Caption text #2
+                ''').strip().split('\n'),
+                strict=True
+                )
+        self.assertIn('0:0:3.540 --> 0:0:7.230', str(cm.exception))
+
+    def test_parse_ignores_out_of_range_timestamp(self):
+        output = vtt.parse(
+            textwrap.dedent('''
+            WEBVTT
+
+            00:00:61.000 --> 00:00:62.000
+            Caption text #1
+
+            00:00:04.300 --> 00:00:07.000
+            Caption text #2
+            ''').strip().split('\n')
+            )
+        self.assertEqual(len(output.captions), 1)
+        self.assertEqual(output.captions[0].text, 'Caption text #2')
+
+    def test_parse_strict_out_of_range_timestamp(self):
+        with self.assertRaises(MalformedCaptionError) as cm:
+            vtt.parse(
+                textwrap.dedent('''
+                WEBVTT
+
+                00:00:61.000 --> 00:00:62.000
+                Caption text #1
+                ''').strip().split('\n'),
+                strict=True
+                )
+        self.assertIn('00:00:61.000', str(cm.exception))
+
     def test_parse_strict_malformed_cue_block(self):
         with self.assertRaises(MalformedCaptionError) as cm:
             vtt.parse(

tests/test_webvtt.py

@@ -753,6 +753,32 @@ def test_parse_valid_file_strict(self):
         vtt = webvtt.read(PATH_TO_SAMPLES / 'sample.vtt', strict=True)
         self.assertEqual(len(vtt.captions), 16)
 
+    def test_parse_non_padded_timestamps(self):
+        """https://github.com/glut23/webvtt-py/issues/44"""
+        vtt = webvtt.read(PATH_TO_SAMPLES / 'non_padded_timestamps.vtt')
+        self.assertEqual(len(vtt.captions), 3)
+        self.assertEqual(
+            [(caption.start, caption.end) for caption in vtt.captions],
+            [('00:00:00.000', '00:00:03.540'),
+             ('00:00:03.540', '00:00:07.230'),
+             ('00:01:05.200', '01:02:07.950')]
+            )
+        self.assertEqual(vtt.captions[1].voice, 'John Smith')
+        self.assertEqual(vtt.captions[1].text, "Morning, let's get started.")
+        self.assertEqual(vtt.captions[2].end_in_seconds, 3727)
+        self.assertIn(
+            '00:01:05.200 --> 01:02:07.950\n<v Jane Doe>Thanks for joining.',
+            vtt.content
+            )
+
+    def test_parse_non_padded_timestamps_strict(self):
+        self.assertRaises(
+            MalformedCaptionError,
+            webvtt.read,
+            PATH_TO_SAMPLES / 'non_padded_timestamps.vtt',
+            strict=True
+            )
+
     def test_parse_get_caption_data(self):
         vtt = webvtt.read(PATH_TO_SAMPLES / 'one_caption.vtt')
         self.assertEqual(vtt.captions[0].start_in_seconds, 0)

webvtt/models.py

@@ -9,7 +9,7 @@
 class Timestamp:
     """Representation of a timestamp."""
 
-    PATTERN = re.compile(r'(?:(\d{1,}):)?(\d{1,2}):(\d{1,2})\.(\d{3})')
+    PATTERN = re.compile(r'(?:(\d{1,}):)?(\d{1,2}):(\d{1,2})\.(\d{1,3})')
 
     def __init__(
             self,
@@ -73,6 +73,10 @@ def from_string(cls, value: str) -> 'Timestamp':
         """
         Return a `Timestamp` instance from a string value.
 
+        The fields can be shorter than the WebVTT format requires, as in
+        ``0:1:5.2``, and the fraction of a second is padded on the right so
+        ``.2`` is read as 200 milliseconds.
+
         :param value: the timestamp in ``[hh:]mm:ss.mmm`` format
         :returns: a `Timestamp` instance
 
@@ -88,7 +92,7 @@ def from_string(cls, value: str) -> 'Timestamp':
         hours = int(match.group(1) or 0)
         minutes = int(match.group(2))
         seconds = int(match.group(3))
-        milliseconds = int(match.group(4))
+        milliseconds = int(match.group(4).ljust(3, '0'))
 
         if minutes > 59 or seconds > 59:
             raise MalformedCaptionError(f'Invalid timestamp {value!r}')

webvtt/vtt.py

@@ -7,6 +7,9 @@
 from .errors import MalformedFileError, MalformedCaptionError
 from .models import Caption, Style
 
+TIMESTAMP = r'(?:\d+:)?\d{1,2}:\d{1,2}\.\d{1,3}'
+STRICT_TIMESTAMP = r'(?:\d{2,}:)?\d{2}:\d{2}\.\d{3}'
+
 
 @dataclass
 class ParserOutput:
@@ -41,9 +44,10 @@ class WebVTTCueBlock:
     """Representation of a cue timing block."""
 
     CUE_TIMINGS_PATTERN = re.compile(
-        r'\s*((?:\d+:)?\d{2}:\d{2}\.\d{3})'
-        r'\s*-->\s*'
-        r'((?:\d+:)?\d{2}:\d{2}\.\d{3})'
+        rf'\s*({TIMESTAMP})\s*-->\s*({TIMESTAMP})'
+        )
+    STRICT_CUE_TIMINGS_PATTERN = re.compile(
+        rf'\s*({STRICT_TIMESTAMP})\s*-->\s*({STRICT_TIMESTAMP})(?=\s|$)'
         )
 
     def __init__(
@@ -68,24 +72,33 @@ def __init__(
     @classmethod
     def is_valid(
             cls,
-            lines: typing.Sequence[str]
+            lines: typing.Sequence[str],
+            strict: bool = False
             ) -> bool:
         """
         Validate the lines for a match of a cue time block.
 
+        Timestamps with fields shorter than the WebVTT format requires, as
+        in ``0:0:13.540``, are accepted unless strict.
+
         :param lines: the lines to be validated
+        :param strict: only accept timestamps in the WebVTT format
         :returns: true for a matching cue time block
         """
+        pattern = (
+            cls.STRICT_CUE_TIMINGS_PATTERN if strict
+            else cls.CUE_TIMINGS_PATTERN
+            )
         return bool(
             (
               len(lines) >= 1 and
-              re.match(cls.CUE_TIMINGS_PATTERN, lines[0]) and
+              re.match(pattern, lines[0]) and
               (len(lines) < 2 or "-->" not in lines[1])
               ) or
             (
               len(lines) >= 2 and
               "-->" not in lines[0] and
-              re.match(cls.CUE_TIMINGS_PATTERN, lines[1]) and
+              re.match(pattern, lines[1]) and
               (len(lines) < 3 or "-->" not in lines[2])
               )
         )
@@ -356,7 +369,7 @@ def parse_items(
     comments: typing.List[WebVTTCommentBlock] = []
 
     for block_lines in iter_blocks_of_lines(lines, strict):
-        item = parse_item(block_lines)
+        item = parse_item(block_lines, strict)
         if item:
             item.comments = [comment.text for comment in comments]
             comments = []
@@ -380,21 +393,32 @@ def parse_items(
 
 
 def parse_item(
-        lines: typing.Sequence[str]
+        lines: typing.Sequence[str],
+        strict: bool = False
         ) -> typing.Union[Caption, Style, None]:
     """
     Parse an item from lines of text.
 
     :param lines: lines of text
+    :param strict: only accept cue timestamps in the WebVTT format and
+        raise an error for cues with an invalid timestamp
     :returns: An item (Caption or Style) if found, otherwise None
+
+    :raises MalformedCaptionError: if strict and a cue has an invalid
+        timestamp
     """
-    if WebVTTCueBlock.is_valid(lines):
+    if WebVTTCueBlock.is_valid(lines, strict):
         cue_block = WebVTTCueBlock.from_lines(lines)
-        return Caption(cue_block.start,
-                       cue_block.end,
-                       cue_block.payload,
-                       cue_block.identifier
-                       )
+        try:
+            return Caption(cue_block.start,
+                           cue_block.end,
+                           cue_block.payload,
+                           cue_block.identifier
+                           )
+        except MalformedCaptionError:
+            if strict:
+                raise
+            return None
 
     if WebVTTStyleBlock.is_valid(lines):
         return Style(WebVTTStyleBlock.from_lines(lines).text)