pycaption 2.2.24__tar.gz → 2.2.26__tar.gz

{pycaption-2.2.24/pycaption.egg-info → pycaption-2.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycaption
-Version: 2.2.24
+Version: 2.2.26
 Summary: Closed caption converter
 Author: Joe Norton
 Author-email: joey@nortoncrew.com

{pycaption-2.2.24 → pycaption-2.2.26}/pycaption/geometry.py

@@ -213,9 +213,15 @@ class Stretch(TwoDimensionalObject):
 
 
 class Region:
-    """Represents the spatial coordinates of a rectangle
-
-    Don't instantiate by hand. use Region.from_points or Region.from_extent
+    """Represents the spatial coordinates of a rectangle.
+
+    NOTE: This class is currently dead code — not imported or used anywhere in
+    the codebase. It also contains known bugs (align_from_origin returns
+    inconsistent types, add_extent method does not exist on Point). We left it
+    here because it may serve as a starting point if we ever need geometric
+    rectangle operations beyond what Layout class provides (e.g. region
+    intersection or point-in-region checks).
+    If we'll ever need it, fix the bugs first.
     """
 
     @classmethod
@@ -846,7 +852,7 @@ class Layout:
                 found_absolute_unit = False
                 if bottom_right.x.unit != UnitEnum.PERCENT:
                     found_absolute_unit = True
-                elif bottom_right.x.unit != UnitEnum.PERCENT:
+                elif bottom_right.y.unit != UnitEnum.PERCENT:
                     found_absolute_unit = True
 
                 if found_absolute_unit:

{pycaption-2.2.24 → pycaption-2.2.26}/pycaption/scc/__init__.py

@@ -335,8 +335,7 @@ class SCCReader(BaseReader):
                 # Look ahead for the next command, skipping the duplicate
                 # that SCC uses for error-correction (same word repeated).
                 next_idx = idx + 1
-                if (next_idx < len(word_list)
-                        and word_list[next_idx].strip() == word):
+                if next_idx < len(word_list) and word_list[next_idx].strip() == word:
                     next_idx += 1
                 next_command = (
                     word_list[next_idx] if next_idx < len(word_list) else None
@@ -496,10 +495,11 @@ class SCCReader(BaseReader):
             edm_time = self.time_translator.get_time()
             if self.pop_ons_queue:
                 self._pop_on(end=edm_time)
-            if self.buffer_dict.active_key in ("paint", "roll") \
-                    and not self.buffer.is_empty():
-                self.caption_stash.create_and_store(
-                    self.buffer, self.time, edm_time)
+            if (
+                self.buffer_dict.active_key in ("paint", "roll")
+                and not self.buffer.is_empty()
+            ):
+                self.caption_stash.create_and_store(self.buffer, self.time, edm_time)
                 self.buffer = self.node_creator_factory.new_creator()
                 self.node_creator_factory.position_tracker.reset_for_new_caption()
                 self.time = edm_time
@@ -563,9 +563,17 @@ class SCCReader(BaseReader):
         self.caption_stash.create_and_store(pop_on_cue.buffer, pop_on_cue.start, end)
 
 
+SCC_TOKENS_PER_CAPTION_MAX = 80
+
+_SCC_PREFIX = ["94ae", "94ae", "9420", "9420"]
+_SCC_SUFFIX = ["942c", "942c", "942f", "942f"]
+_SCC_OVERHEAD = len(_SCC_PREFIX) + len(_SCC_SUFFIX)
+
+
 class SCCWriter(BaseWriter):
-    def __init__(self, *args, **kw):
+    def __init__(self, *args, drop_frame=False, **kw):
         super().__init__(*args, **kw)
+        self.drop_frame = drop_frame
 
     def write(self, caption_set):
         output = HEADER + "\n\n"
@@ -589,24 +597,64 @@ class SCCWriter(BaseWriter):
         # Advance start times so as to have time to write to the pop-on
         # buffer; possibly remove the previous clear-screen command
         for index, (code, start, end) in enumerate(codes):
-            code_words = len(code) / 5 + 8
+            code_words = len(code.split()) + _SCC_OVERHEAD
             code_time_microseconds = code_words * MICROSECONDS_PER_CODEWORD
             code_start = start - code_time_microseconds
-            if index > 0:
-                previous_code, previous_start, previous_end = codes[index - 1]
-                if code_start < previous_start:
-                    code_start = previous_start
-                if previous_end + 3 * MICROSECONDS_PER_CODEWORD >= code_start:
+            if code_start < 0:
+                code_start = 0
+            if index == 0:
+                codes[index] = (code, code_start, end)
+                continue
+            previous_code, previous_start, previous_end = codes[index - 1]
+            if code_start <= previous_start + MICROSECONDS_PER_CODEWORD:
+                prev_words = len(previous_code.split()) + _SCC_OVERHEAD
+                code_start = max(
+                    code_start,
+                    previous_start + prev_words * MICROSECONDS_PER_CODEWORD,
+                )
+                codes[index] = (code, code_start, end)
+                codes[index - 1] = (previous_code, previous_start, None)
+            else:
+                if (
+                    previous_end is not None
+                    and previous_end + 3 * MICROSECONDS_PER_CODEWORD >= code_start
+                ):
                     codes[index - 1] = (previous_code, previous_start, None)
-            codes[index] = (code, code_start, end)
+                codes[index] = (code, code_start, end)
 
         # PASS 3:
-        # Write captions.
+        # Deduplicate timestamps — ensure monotonically increasing frame values
+        last_emitted_frame = -1
+        for index, (code, start, end) in enumerate(codes):
+            cur_frame = self._microseconds_to_frame(start)
+            if cur_frame <= last_emitted_frame:
+                while self._microseconds_to_frame(start) <= last_emitted_frame:
+                    start += MICROSECONDS_PER_CODEWORD
+                codes[index] = (code, start, end)
+            last_emitted_frame = self._microseconds_to_frame(start)
+
+        # PASS 4:
+        # Write captions, splitting if > SCC_TOKENS_PER_CAPTION_MAX tokens.
+        max_payload = SCC_TOKENS_PER_CAPTION_MAX - _SCC_OVERHEAD
         for code, start, end in codes:
-            output += f"{self._format_timestamp(start)}\t"
-            output += "94ae 94ae 9420 9420 "
-            output += code
-            output += "942c 942c 942f 942f\n\n"
+            code_tokens = code.split()
+            if len(code_tokens) + _SCC_OVERHEAD <= SCC_TOKENS_PER_CAPTION_MAX:
+                output += f"{self._format_timestamp(start)}\t"
+                output += "94ae 94ae 9420 9420 "
+                output += code
+                output += "942c 942c 942f 942f\n\n"
+            else:
+                offset = 0
+                while offset < len(code_tokens):
+                    chunk = code_tokens[offset : offset + max_payload]
+                    line = _SCC_PREFIX + chunk + _SCC_SUFFIX
+                    output += (
+                        f"{self._format_timestamp(start)}\t" + " ".join(line) + "\n\n"
+                    )
+                    offset += max_payload
+                    if offset < len(code_tokens):
+                        start += MICROSECONDS_PER_CODEWORD
+
             if end is not None:
                 output += f"{self._format_timestamp(end)}\t942c 942c\n\n"
 
@@ -668,10 +716,20 @@ class SCCWriter(BaseWriter):
             code = self._maybe_align(code)
         return code
 
+    def _format_timestamp(self, microseconds):
+        if self.drop_frame:
+            return self._format_timestamp_df(microseconds)
+        return self._format_timestamp_ndf(microseconds)
+
+    def _microseconds_to_frame(self, microseconds):
+        if self.drop_frame:
+            return math.floor(microseconds * 30 / 1_000_000 * 1000 / 1001 + 1e-9)
+        seconds_float = microseconds / 1_000_000.0 * 1000.0 / 1001.0
+        return math.floor(seconds_float * 30)
+
     @staticmethod
-    def _format_timestamp(microseconds):
-        seconds_float = microseconds / 1000.0 / 1000.0
-        # Convert to non-drop-frame timecode
+    def _format_timestamp_ndf(microseconds):
+        seconds_float = microseconds / 1_000_000.0
         seconds_float *= 1000.0 / 1001.0
         hours = math.floor(seconds_float / 3600)
         seconds_float -= hours * 3600
@@ -682,6 +740,26 @@ class SCCWriter(BaseWriter):
         frames = math.floor(seconds_float * 30)
         return f"{hours:02}:{minutes:02}:{seconds:02}:{frames:02}"
 
+    @staticmethod
+    def _format_timestamp_df(microseconds):
+        total_frames = math.floor(microseconds * 30 / 1_000_000 * 1000 / 1001 + 1e-9)
+        fps = 30
+        frames_per_10min = 17982  # 10*60*30 - 2*9
+        d = total_frames // frames_per_10min
+        m = total_frames % frames_per_10min
+        if m < 2:
+            tc_frames = total_frames + 18 * d
+        else:
+            tc_frames = total_frames + 18 * d + 2 * ((m - 2) // 1798)
+
+        hours = tc_frames // (fps * 60 * 60)
+        rem = tc_frames % (fps * 60 * 60)
+        minutes = rem // (fps * 60)
+        rem = rem % (fps * 60)
+        seconds = rem // fps
+        frames = rem % fps
+        return f"{hours:02}:{minutes:02}:{seconds:02};{frames:02}"
+
 
 class _SccTimeTranslator:
     """Converts SCC time to microseconds, keeping track of frames passed"""

{pycaption-2.2.24 → pycaption-2.2.26}/pycaption/scc/specialized_collections.py

@@ -26,6 +26,9 @@ from .constants import (
 
 PopOnCue = collections.namedtuple("PopOnCue", "buffer, start, end")
 
+# First two hex chars of SCC codes that produce punctuation ['.', '!', '?', ',']
+_PUNCTUATION_PREFIXES = frozenset(["ae", "a1", "bf", "2c"])
+
 
 class PreCaption:
     """
@@ -444,8 +447,7 @@ class InstructionNodeCreator:
         #  handle mid-row codes that follows a text node
         #  don't add space if the next command adds one of
         #  ['.', '!', '?', ',']
-        punctuation = ["ae", "a1", "bf", "2c"]
-        next_is_punctuation = next_command and next_command[:2] in punctuation
+        next_is_punctuation = next_command and next_command[:2] in _PUNCTUATION_PREFIXES
         prev_text_node = self.get_previous_text_node()
         prev_node_is_break = prev_text_node is not None and any(
             x.is_explicit_break()
@@ -501,9 +503,9 @@ class InstructionNodeCreator:
         if len(collection) == 0:
             return False
         for element in collection[::-1]:
-            if element._type == 0:
+            if element._type == _InstructionNode.TEXT:
                 return False
-            elif element._type == 1:
+            elif element._type == _InstructionNode.BREAK:
                 return True
         return False
 
@@ -782,6 +784,8 @@ def _format_italics(collection):
 
 
 def _remove_spaces_at_end_of_the_line(collection):
+    if not collection:
+        return collection
     for idx, node in enumerate(collection):
         if (
             idx > 0
@@ -826,7 +830,7 @@ def _remove_noop_on_off_italics(collection):
     return new_collection
 
 
-def _remove_noon_off_on_italics(collection):
+def _remove_noop_off_on_italics(collection):
     """Removes pairs of off-on italics nodes, that don't surround any other
     node
 
@@ -867,7 +871,7 @@ def _remove_noop_italics(collection):
     """
     new_collection = _remove_noop_on_off_italics(collection)
 
-    new_collection = _remove_noon_off_on_italics(new_collection)
+    new_collection = _remove_noop_off_on_italics(new_collection)
 
     return new_collection
 

{pycaption-2.2.24 → pycaption-2.2.26}/pycaption/webvtt.py

@@ -10,7 +10,7 @@ from .exceptions import (
     CaptionReadSyntaxError,
     InvalidInputError,
 )
-from .geometry import HorizontalAlignmentEnum, Layout
+from .geometry import HorizontalAlignmentEnum, Layout, Point, Size, Stretch, UnitEnum
 
 # A WebVTT timing line has both start/end times and layout related settings
 # (referred to as 'cue settings' in the documentation)
@@ -21,6 +21,19 @@ VOICE_SPAN_PATTERN = re.compile("<v(\\.\\w+)* ([^>]*)>")
 OTHER_SPAN_PATTERN = re.compile(
     r"</?([cibuv]|ruby|rt|lang|(\d+):(\d{2})(:\d{2})?\.(\d{3})).*?>"
 )  # These WebVTT tags are stripped off the cues on conversion
+REGION_SETTING_PATTERN = re.compile(r"^([\w]+):(.+)$")
+"""  
+Matches a setting name (word chars) followed by colon and a value:
+id:region1
+width:50%
+"""
+REGION_ANCHOR_PATTERN = re.compile(r"^(\d+(?:\.\d+)?)%,(\d+(?:\.\d+)?)%$")
+"""
+Matches two percentage values (integer or decimal) separated by a comma:
+0%,0%
+100%,100%
+"""
+LINE_HEIGHT_VH = 5.33
 
 WEBVTT_VERSION_OF = {
     HorizontalAlignmentEnum.LEFT: "left",
@@ -69,6 +82,8 @@ class WebVTTReader(BaseReader):
         return caption_set
 
     def _parse(self, lines):
+        # State machine: cycles through waiting-for-timing → collecting-text
+        # → emit-caption-on-blank-line, repeat.
         captions = CaptionList()
         start = None
         end = None
@@ -76,8 +91,13 @@ class WebVTTReader(BaseReader):
         layout_info = None
         found_timing = False
 
+        # Parse REGION blocks from the header area before processing cues
+        self._regions = self._parse_regions(lines)
+
         for i, line in enumerate(lines):
             if "-->" in line:
+                # Timing line found (e.g. "00:00:01.000 --> 00:00:03.000")
+                # marks the start of a new cue
                 found_timing = True
                 timing_line = i
                 last_start_time = captions[-1].start if captions else 0
@@ -91,6 +111,8 @@ class WebVTTReader(BaseReader):
                     raise type(e)(new_msg).with_traceback(tb) from None
 
             elif "" == line:
+                # Blank line = block separator in WebVTT.
+                # If we were collecting a cue, finalize and store it.
                 if found_timing and nodes:
                     found_timing = False
                     caption = Caption(start, end, nodes, layout_info=layout_info)
@@ -98,24 +120,23 @@ class WebVTTReader(BaseReader):
                     nodes = []
             else:
                 if found_timing:
+                    # We're inside a cue — this line is cue text.
+                    # Add a line break between multi-line cue text.
                     if nodes:
                         nodes.append(CaptionNode.create_break())
                     nodes.append(CaptionNode.create_text(self._decode(line)))
                 else:
-                    # it's a comment or some metadata; ignore it
+                    # Outside a cue: cue identifiers, NOTE blocks,
+                    # or other metadata — skip silently.
                     pass
 
-        # Add a last caption if there are remaining nodes
+        # File may not end with a blank line — emit any remaining cue
         if nodes:
             caption = Caption(start, end, nodes, layout_info=layout_info)
             captions.append(caption)
 
         return captions
 
-    def _remove_styles(self, line):
-        partial_result = VOICE_SPAN_PATTERN.sub("\\2: ", line)
-        return OTHER_SPAN_PATTERN.sub("", partial_result)
-
     def _validate_timings(self, start, end, last_start_time):
         if start is None:
             raise CaptionReadSyntaxError("Invalid cue start timestamp.")
@@ -147,7 +168,18 @@ class WebVTTReader(BaseReader):
 
         layout_info = None
         if cue_settings:
-            layout_info = Layout(webvtt_positioning=cue_settings)
+            region_id = self._extract_region_id(cue_settings)
+            if region_id and region_id in self._regions:
+                layout_info = self._regions[region_id]
+                layout_info = Layout(
+                    origin=layout_info.origin,
+                    extent=layout_info.extent,
+                    padding=layout_info.padding,
+                    alignment=layout_info.alignment,
+                    webvtt_positioning=cue_settings,
+                )
+            else:
+                layout_info = Layout(webvtt_positioning=cue_settings)
 
         return start, end, layout_info
 
@@ -189,12 +221,138 @@ class WebVTTReader(BaseReader):
         s = s.replace("&amp;", "&")
         return s
 
+    def _parse_regions(self, lines):
+        """Parse REGION blocks from the file header area.
+
+        A WebVTT region defines a named rectangular area on screen where cues
+        can be rendered. Regions appear before any cues with the syntax:
+
+            REGION
+            id:subtitle_area
+            width:50%
+            lines:3
+            regionanchor:0%,100%
+            viewportanchor:10%,90%
+            scroll:up
+
+        Supported settings:
+            id             - unique identifier (required)
+            width          - region width as percentage (default: 100%)
+            lines          - visible line count (default: 3)
+            regionanchor   - anchor point within region as x%,y% (default: 0%,100%)
+            viewportanchor - anchor point on viewport as x%,y% (default: 0%,100%)
+            scroll         - scroll behavior, only "up" is valid (default: none)
+
+        :returns: dict mapping region id -> Layout
+        """
+        regions = {}
+        i = 0
+        while i < len(lines):
+            line = lines[i].strip()
+            if line == "REGION" or line.startswith(("REGION\t", "REGION ")):
+                i += 1
+                settings = {}
+                seen_keys = set()
+                # Read settings until a blank line (block separator in WebVTT)
+                while i < len(lines) and lines[i].strip() != "":
+                    # Match key:value pair (e.g. "width:50%")
+                    m = REGION_SETTING_PATTERN.match(lines[i].strip())
+                    if m:
+                        key, value = m.group(1), m.group(2)
+                        if key in seen_keys:
+                            i += 1
+                            continue
+                        seen_keys.add(key)
+                        settings[key] = value
+                    i += 1
+                # Skip regions without id (spec requires it; cues can't reference them)
+                if "id" in settings:
+                    region_id = settings["id"]
+                    # First definition wins; duplicates are ignored (RULE-REG-009)
+                    if region_id not in regions:
+                        regions[region_id] = self._region_to_layout(settings)
+            elif "-->" in line:
+                # REGIONs only appear before cues; stop scanning once cues begin
+                break
+            else:
+                i += 1
+        return regions
+
+    def _region_to_layout(self, settings):
+        """Convert parsed region settings dict into a Layout with origin/extent.
+
+        Uses W3C TTML-WebVTT mapping formulas:
+            origin_x = viewportanchor_x - (regionanchor_x / 100 * width)
+            origin_y = viewportanchor_y - (regionanchor_y / 100 * height)
+            height = lines * 5.33
+        """
+        # Spec defaults per W3C WebVTT §6
+        width = 100.0
+        lines = 3
+        regionanchor_x, regionanchor_y = 0.0, 100.0
+        viewportanchor_x, viewportanchor_y = 0.0, 100.0
+        # Parse each setting, falling back to defaults on invalid values
+        if "width" in settings:
+            try:
+                width = float(settings["width"].rstrip("%"))
+            except ValueError:
+                pass
+
+        if "lines" in settings:
+            try:
+                lines = int(settings["lines"])
+            except ValueError:
+                pass
+
+        # regionanchor: which point inside the region is "pinned"
+        # e.g. 0%,100% means the bottom-left corner of the region
+        if "regionanchor" in settings:
+            m = REGION_ANCHOR_PATTERN.match(settings["regionanchor"])
+            if m:
+                regionanchor_x = float(m.group(1))
+                regionanchor_y = float(m.group(2))
+
+        # viewportanchor: where on the screen that pin is placed
+        # e.g. 10%,90% means 10% from left, 90% from top
+        if "viewportanchor" in settings:
+            m = REGION_ANCHOR_PATTERN.match(settings["viewportanchor"])
+            if m:
+                viewportanchor_x = float(m.group(1))
+                viewportanchor_y = float(m.group(2))
+
+        # Calculate the top-left corner (origin) of the region box.
+        # Each line is ~5.33% of viewport height (LINE_HEIGHT_VH).
+        height = lines * LINE_HEIGHT_VH
+        # The origin is where the viewport anchor is, offset back by how far
+        # the region anchor is into the box (as a fraction of box dimensions).
+        origin_x = viewportanchor_x - (regionanchor_x / 100.0 * width)
+        origin_y = viewportanchor_y - (regionanchor_y / 100.0 * height)
+
+        origin = Point(
+            Size(origin_x, UnitEnum.PERCENT),
+            Size(origin_y, UnitEnum.PERCENT),
+        )
+        extent = Stretch(
+            Size(width, UnitEnum.PERCENT),
+            Size(height, UnitEnum.PERCENT),
+        )
+
+        return Layout(
+            origin=origin,
+            extent=extent
+        )
+
+    @staticmethod
+    def _extract_region_id(cue_settings):
+        """Extract region id from cue settings string, if present."""
+        for setting in cue_settings.split():
+            if setting.startswith("region:"):
+                return setting[7:]
+        return None
+
 
 class WebVTTWriter(BaseWriter):
     HEADER = "WEBVTT\n\n"
-    global_layout = None
-    video_width = None
-    video_height = None
 
     def write(self, caption_set, lang=None):
         """
@@ -347,8 +505,7 @@ class WebVTTWriter(BaseWriter):
                 # Since there is no padding in WebVTT, the left padding is
                 # added to the total left offset (if it is defined and not
                 # relative),
-                if left_offset:
-                    left_offset += layout.padding.start
+                left_offset += layout.padding.start
                 # and removed from the total cue width
                 if cue_width:
                     cue_width -= layout.padding.start

{pycaption-2.2.24 → pycaption-2.2.26/pycaption.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycaption
-Version: 2.2.24
+Version: 2.2.26
 Summary: Closed caption converter
 Author: Joe Norton
 Author-email: joey@nortoncrew.com

{pycaption-2.2.24 → pycaption-2.2.26}/pycaption.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ tests/test_sami_conversion.py
 tests/test_scc.py
 tests/test_scc_conversion.py
 tests/test_scc_translator.py
+tests/test_scc_writer.py
 tests/test_srt.py
 tests/test_srt_conversion.py
 tests/test_webvtt.py

{pycaption-2.2.24 → pycaption-2.2.26}/setup.py

@@ -20,7 +20,7 @@ transcript_dependencies = ["nltk==3.9.4"]
 
 setup(
     name="pycaption",
-    version="2.2.24",
+    version="2.2.26",
     description="Closed caption converter",
     long_description=open(README_PATH).read(),
     author="Joe Norton",

{pycaption-2.2.24 → pycaption-2.2.26}/tests/test_scc.py

@@ -696,10 +696,10 @@ class TestInterpretableNodeCreator:
         node_creator.interpret_command("9429")
         self.check_closing_italics_closing_on_style_change(node_creator)
 
-    def test_remove_noon_off_on_italics(self):
+    def test_remove_noop_off_on_italics(self):
         from pycaption.scc.specialized_collections import (
             _InstructionNode,
-            _remove_noon_off_on_italics,
+            _remove_noop_off_on_italics,
         )
 
         position_tracker = DefaultProvidingPositionTracker().default
@@ -719,7 +719,7 @@ class TestInterpretableNodeCreator:
         assert node_creator._collection[-2].sets_italics_off()
         assert node_creator._collection[-1].sets_italics_on()
 
-        new_collection = _remove_noon_off_on_italics(node_creator._collection)
+        new_collection = _remove_noop_off_on_italics(node_creator._collection)
 
         #  should eliminate italic tags, keep only the text node
         assert len(new_collection) == 1
@@ -739,7 +739,7 @@ class TestInterpretableNodeCreator:
         assert node_creator._collection[-2].is_text_node()
         assert node_creator._collection[-1].sets_italics_on()
 
-        new_collection = _remove_noon_off_on_italics(node_creator._collection)
+        new_collection = _remove_noop_off_on_italics(node_creator._collection)
         # should not eliminate any node
         assert new_collection[-3].sets_italics_off()
         assert new_collection[-2].is_text_node()

pycaption-2.2.26/tests/test_scc_writer.py

@@ -0,0 +1,255 @@
+import re
+
+
+from pycaption import SCCReader, SCCWriter, SRTReader, WebVTTReader
+
+
+class TestSCCWriterTimestampFormatting:
+    def test_ndf_timestamp_uses_colons(self):
+        assert SCCWriter._format_timestamp_ndf(0) == "00:00:00:00"
+        assert ";" not in SCCWriter._format_timestamp_ndf(1_000_000)
+
+    def test_ndf_known_values(self):
+        assert SCCWriter._format_timestamp_ndf(0) == "00:00:00:00"
+        # 1 second of real time at 29.97fps NDF
+        # 1_000_000 us * 1000/1001 = 999.000999 coded seconds → 29 frames
+        assert SCCWriter._format_timestamp_ndf(1_000_000) == "00:00:00:29"
+        # 60 seconds real → 59.94 coded seconds → 59s + 28 frames
+        assert SCCWriter._format_timestamp_ndf(60_000_000) == "00:00:59:28"
+
+    def test_df_timestamp_uses_semicolons(self):
+        result = SCCWriter._format_timestamp_df(1_000_000)
+        assert ";" in result
+
+    def test_df_known_values(self):
+        assert SCCWriter._format_timestamp_df(0) == "00:00:00;00"
+        # 10 minutes of real time should map to exactly 10:00;00 in DF
+        ten_minutes_us = 10 * 60 * 1_000_000
+        assert SCCWriter._format_timestamp_df(ten_minutes_us) == "00:10:00;00"
+
+    def test_df_frame_skip_at_minute_boundary(self):
+        # Real frame 1800 is the first frame of minute 1 in DF.
+        # Minute 0 has 1800 frames (0..1799), no drops.
+        # Minute 1 starts at real frame 1800, displayed as 00:01:00;02
+        # (frames ;00 and ;01 are dropped at non-10th minutes).
+        us_for_frame_1800 = round(1800 * 1001 / 1000 / 30 * 1_000_000)
+        result = SCCWriter._format_timestamp_df(us_for_frame_1800)
+        assert result == "00:01:00;02"
+
+    def test_df_no_frame_skip_at_10_minute_boundary(self):
+        # At 10-minute boundaries, no frames are dropped
+        twenty_minutes_us = 20 * 60 * 1_000_000
+        result = SCCWriter._format_timestamp_df(twenty_minutes_us)
+        assert result == "00:20:00;00"
+
+
+class TestSCCWriterDropFrameFlag:
+    def _make_simple_captions(self):
+        srt = (
+            "1\n"
+            "00:00:01,000 --> 00:00:03,000\n"
+            "Hello world\n\n"
+            "2\n"
+            "00:00:05,000 --> 00:00:07,000\n"
+            "Second line\n"
+        )
+        return SRTReader().read(srt)
+
+    def test_drop_frame_false_is_default(self):
+        writer = SCCWriter()
+        assert writer.drop_frame is False
+
+    def test_drop_frame_false_uses_colons(self):
+        captions = self._make_simple_captions()
+        output = SCCWriter(drop_frame=False).write(captions)
+        timestamps = re.findall(r"\d{2}:\d{2}:\d{2}[:;]\d{2}", output)
+        for ts in timestamps:
+            assert ";" not in ts
+
+    def test_drop_frame_true_uses_semicolons(self):
+        captions = self._make_simple_captions()
+        output = SCCWriter(drop_frame=True).write(captions)
+        timestamps = re.findall(r"\d{2}:\d{2}:\d{2}[:;]\d{2}", output)
+        assert len(timestamps) > 0
+        for ts in timestamps:
+            assert ";" in ts
+
+    def test_drop_frame_false_preserves_existing_behavior(self):
+        captions = self._make_simple_captions()
+        output_default = SCCWriter().write(captions)
+        output_explicit = SCCWriter(drop_frame=False).write(captions)
+        assert output_default == output_explicit
+
+
+class TestSCCWriterTimestampOrdering:
+    def test_timestamps_monotonically_increasing_ndf(self):
+        vtt_input = (
+            "WEBVTT\n\n"
+            "0\n00:00:01.529 --> 00:00:03.640\n"
+            "When it comes to finding the one,\n\n"
+            "1\n00:00:03.730 --> 00:00:07.239\n"
+            "I always say that if they can love you at your messiest,\n\n"
+            "2\n00:00:07.570 --> 00:00:09.319\n"
+            "calm you at your moodiest,\n\n"
+            "3\n00:00:09.529 --> 00:00:11.680\n"
+            "and laugh with you at your quirkiest,\n\n"
+            "4\n00:00:11.930 --> 00:00:13.760\n"
+            "you've probably found your person.\n"
+        )
+        captions = WebVTTReader().read(vtt_input)
+        output = SCCWriter(drop_frame=False).write(captions)
+        timestamps = re.findall(r"(\d{2}:\d{2}:\d{2}:\d{2})", output)
+        for i in range(1, len(timestamps)):
+            assert (
+                timestamps[i] >= timestamps[i - 1]
+            ), f"NDF timestamps out of order: {timestamps[i - 1]} > {timestamps[i]}"
+
+    def test_timestamps_monotonically_increasing_df(self):
+        vtt_input = (
+            "WEBVTT\n\n"
+            "0\n00:00:01.529 --> 00:00:03.640\n"
+            "When it comes to finding the one,\n\n"
+            "1\n00:00:03.730 --> 00:00:07.239\n"
+            "I always say that if they can love you at your messiest,\n\n"
+            "2\n00:00:07.570 --> 00:00:09.319\n"
+            "calm you at your moodiest,\n\n"
+            "3\n00:00:09.529 --> 00:00:11.680\n"
+            "and laugh with you at your quirkiest,\n\n"
+            "4\n00:00:11.930 --> 00:00:13.760\n"
+            "you've probably found your person.\n"
+        )
+        captions = WebVTTReader().read(vtt_input)
+        output = SCCWriter(drop_frame=True).write(captions)
+        timestamps = re.findall(r"(\d{2}:\d{2}:\d{2};\d{2})", output)
+        for i in range(1, len(timestamps)):
+            assert (
+                timestamps[i] >= timestamps[i - 1]
+            ), f"DF timestamps out of order: {timestamps[i - 1]} > {timestamps[i]}"
+
+    def test_rapid_short_captions_stay_ordered(self):
+        """Short text followed by long text should not cause timestamp inversion."""
+        vtt_input = (
+            "WEBVTT\n\n"
+            "0\n00:00:02.200 --> 00:00:02.359\nyou know,\n\n"
+            "1\n00:00:02.400 --> 00:00:03.760\n"
+            "the way he kind of looked at me.\n\n"
+            "2\n00:00:04.700 --> 00:00:05.169\nAnd I said,\n\n"
+            "3\n00:00:05.210 --> 00:00:05.520\noh\n"
+        )
+        captions = WebVTTReader().read(vtt_input)
+        for df in (True, False):
+            output = SCCWriter(drop_frame=df).write(captions)
+            sep = ";" if df else ":"
+            pattern = r"\d{2}:\d{2}:\d{2}" + re.escape(sep) + r"\d{2}"
+            timestamps = re.findall(pattern, output)
+            for i in range(1, len(timestamps)):
+                assert (
+                    timestamps[i] >= timestamps[i - 1]
+                ), f"drop_frame={df}: {timestamps[i - 1]} > {timestamps[i]}"
+
+
+class TestSCCWriterFirstCueBackshift:
+    def test_first_cue_start_is_shifted_back(self):
+        srt = "1\n" "00:00:10,000 --> 00:00:12,000\n" "Hello world\n"
+        captions = SRTReader().read(srt)
+        output = SCCWriter(drop_frame=False).write(captions)
+        timestamps = re.findall(r"(\d{2}:\d{2}:\d{2}:\d{2})", output)
+        # The first timestamp should be earlier than 00:00:09:29
+        # (10s real time -> ~9:29 NDF, minus backshift)
+        assert timestamps[0] < "00:00:09:29"
+
+    def test_first_cue_at_zero_does_not_go_negative(self):
+        srt = "1\n" "00:00:00,100 --> 00:00:02,000\n" "Hello\n"
+        captions = SRTReader().read(srt)
+        output = SCCWriter(drop_frame=False).write(captions)
+        timestamps = re.findall(r"(\d{2}:\d{2}:\d{2}:\d{2})", output)
+        assert timestamps[0] == "00:00:00:00"
+
+
+class TestSCCWriterOverlappingCues:
+    def test_overlapping_cues_suppress_clear_screen(self):
+        """When cues are very close together, the clear-screen (942c) for
+        the previous cue should be suppressed."""
+        srt = (
+            "1\n00:00:01,000 --> 00:00:01,900\nFirst\n\n"
+            "2\n00:00:02,000 --> 00:00:03,000\nSecond\n"
+        )
+        captions = SRTReader().read(srt)
+        output = SCCWriter(drop_frame=False).write(captions)
+        # Count standalone 942c lines (clear-screen commands between captions)
+        clear_lines = [
+            line
+            for line in output.split("\n")
+            if line.strip().endswith("942c 942c") and "94ae" not in line
+        ]
+        # With tight cues, the first cue's clear should be suppressed
+        # (only the last cue gets a clear-screen at its end time)
+        assert len(clear_lines) <= 1
+
+
+class TestSCCWriterSplitLongCaption:
+    def test_split_caption_exceeding_80_tokens(self):
+        """A caption that would exceed 80 SCC tokens should be split."""
+        # Create a very long caption that will produce many code tokens
+        long_text = "A" * 32 + "\n" + "B" * 32 + "\n" + "C" * 32 + "\n" + "D" * 32
+        srt = "1\n" "00:00:05,000 --> 00:00:10,000\n" f"{long_text}\n"
+        captions = SRTReader().read(srt)
+        output = SCCWriter(drop_frame=False).write(captions)
+        # Each output line (non-empty, non-header) should have <= 80 tokens
+        for line in output.split("\n"):
+            line = line.strip()
+            if not line or line == "Scenarist_SCC V1.0":
+                continue
+            # Line format: "HH:MM:SS:FF\t<tokens>"
+            parts = line.split("\t")
+            if len(parts) == 2:
+                tokens = parts[1].split()
+                assert len(tokens) <= SCC_TOKENS_PER_CAPTION_MAX, (
+                    f"Line has {len(tokens)} tokens, "
+                    f"exceeds {SCC_TOKENS_PER_CAPTION_MAX}"
+                )
+
+
+class TestSCCWriterRoundTrip:
+    def test_srt_to_scc_roundtrip_ndf(self):
+        srt = (
+            "1\n00:00:01,000 --> 00:00:03,000\nHello world\n\n"
+            "2\n00:00:05,000 --> 00:00:07,000\nGoodbye world\n"
+        )
+        captions = SRTReader().read(srt)
+        scc_output = SCCWriter(drop_frame=False).write(captions)
+        # Should be readable by SCCReader
+        result = SCCReader().read(scc_output)
+        assert not result.is_empty()
+        assert len(result.get_captions("en-US")) == 2
+
+    def test_srt_to_scc_roundtrip_df(self):
+        srt = (
+            "1\n00:00:01,000 --> 00:00:03,000\nHello world\n\n"
+            "2\n00:00:05,000 --> 00:00:07,000\nGoodbye world\n"
+        )
+        captions = SRTReader().read(srt)
+        scc_output = SCCWriter(drop_frame=True).write(captions)
+        # SCCReader already supports semicolon (DF) timestamps
+        result = SCCReader().read(scc_output)
+        assert not result.is_empty()
+        assert len(result.get_captions("en-US")) == 2
+
+    def test_webvtt_to_scc_roundtrip_df(self):
+        vtt_input = (
+            "WEBVTT\n\n"
+            "0\n00:00:01.529 --> 00:00:03.640\n"
+            "When it comes to finding the one,\n\n"
+            "1\n00:00:03.730 --> 00:00:07.239\n"
+            "I always say that if they can love you\n\n"
+            "2\n00:00:07.570 --> 00:00:09.319\n"
+            "calm you at your moodiest,\n"
+        )
+        captions = WebVTTReader().read(vtt_input)
+        scc_output = SCCWriter(drop_frame=True).write(captions)
+        result = SCCReader().read(scc_output)
+        assert not result.is_empty()
+        assert len(result.get_captions("en-US")) == 3
+
+
+from pycaption.scc import SCC_TOKENS_PER_CAPTION_MAX  # noqa: E402

{pycaption-2.2.24 → pycaption-2.2.26}/tests/test_webvtt.py

@@ -66,7 +66,7 @@ class TestWebVTTReader(ReaderTestingMixIn):
         assert cue.end == 18737000
 
     def test_webvtt_cue_components_removed_from_text(self):
-        result = self.reader._remove_styles(
+        result = self.reader._decode(
             "<c vIntro><b>Wikipedia</b> is a great adventure. <i>It may have "
             "its shortcomings</i>, but it is<u> the largest</u> collective "
             "knowledge construction endevour</c> <ruby>base text <rt>"
@@ -88,8 +88,7 @@ class TestWebVTTReader(ReaderTestingMixIn):
         # todo: same assert w/ different arguments -> this can be parametrized;
         with pytest.raises(CaptionReadError):
             WebVTTReader(ignore_timing_errors=False).read(
-                "\n" "00:00:20.000 --> 00:00:10.000\n" 
-                "foo bar baz"
+                "\n" "00:00:20.000 --> 00:00:10.000\n" "foo bar baz"
             )
 
         with pytest.raises(CaptionReadError):
@@ -111,15 +110,13 @@ class TestWebVTTReader(ReaderTestingMixIn):
         # Even if timing errors are ignored, this has to raise an exception
         with pytest.raises(CaptionReadSyntaxError):
             WebVTTReader().read(
-                "\nNOTE invalid cue stamp\n"
-                "00:00:20.000 --> \nfoo bar baz\n"
+                "\nNOTE invalid cue stamp\n" "00:00:20.000 --> \nfoo bar baz\n"
             )
 
         # And this too
         with pytest.raises(CaptionReadSyntaxError):
             WebVTTReader().read(
-                "\n00:00:20,000 --> 00:00:22,000\n" 
-                "Note the comma instead of point.\n"
+                "\n00:00:20,000 --> 00:00:22,000\n" "Note the comma instead of point.\n"
             )
 
         # todo: at this point it can be split into 2 separate tests
@@ -147,8 +144,7 @@ class TestWebVTTReader(ReaderTestingMixIn):
     def test_invalid_files(self):
         with pytest.raises(CaptionReadError):
             WebVTTReader(ignore_timing_errors=False).read(
-                "00:00:20.000 --> 00:00:10.000\n" 
-                "Start time is greater than end time."
+                "00:00:20.000 --> 00:00:10.000\n" "Start time is greater than end time."
             )
 
         with pytest.raises(CaptionReadError):
@@ -181,9 +177,7 @@ class TestWebVTTWriter:
         assert sample_webvtt_double_br == results
 
     def test_break_node_positioning_is_ignored(
-        self,
-        webvtt_from_dfxp_with_conflicting_align,
-        dfxp_style_region_align_conflict
+        self, webvtt_from_dfxp_with_conflicting_align, dfxp_style_region_align_conflict
     ):
         caption_set = DFXPReader().read(dfxp_style_region_align_conflict)
         results = WebVTTWriter().write(caption_set)
@@ -202,3 +196,183 @@ class TestWebVTTWriter:
         assert sample_webvtt_multi_lang_de == results
         results = WebVTTWriter().write(caption_set, "en-US")
         assert sample_webvtt_multi_lang_en == results
+
+
+class TestWebVTTRegionParsing:
+    def setup_method(self):
+        self.reader = WebVTTReader()
+
+    def test_region_block_parsed_into_layout(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:subtitle_area\n"
+            "width:50%\n"
+            "lines:3\n"
+            "regionanchor:0%,100%\n"
+            "viewportanchor:10%,90%\n"
+            "scroll:up\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:subtitle_area\n"
+            "Hello world\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        assert cue.layout_info is not None
+        assert cue.layout_info.origin is not None
+        assert cue.layout_info.extent is not None
+
+    def test_region_origin_calculation(self):
+        """origin_x = viewportanchor_x - (regionanchor_x / 100 * width)
+        origin_y = viewportanchor_y - (regionanchor_y / 100 * height)
+        height = lines * 5.33
+        """
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:box\n"
+            "width:50%\n"
+            "lines:3\n"
+            "regionanchor:0%,100%\n"
+            "viewportanchor:10%,90%\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:box\n"
+            "Test\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        layout = cue.layout_info
+        # origin_x = 10 - (0/100 * 50) = 10.0
+        assert layout.origin.x.value == pytest.approx(10.0)
+        # height = 3 * 5.33 = 15.99
+        # origin_y = 90 - (100/100 * 15.99) = 74.01
+        assert layout.origin.y.value == pytest.approx(74.01)
+        # extent = width=50%, height=15.99%
+        assert layout.extent.horizontal.value == pytest.approx(50.0)
+        assert layout.extent.vertical.value == pytest.approx(15.99)
+
+    def test_region_defaults(self):
+        """width=100%, lines=3, regionanchor=0%,100%, viewportanchor=0%,100%"""
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:minimal\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:minimal\n"
+            "Test\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        layout = cue.layout_info
+        # width=100, lines=3, height=15.99
+        # regionanchor=0,100 viewportanchor=0,100
+        # origin_x = 0 - (0/100 * 100) = 0
+        # origin_y = 100 - (100/100 * 15.99) = 84.01
+        assert layout.origin.x.value == pytest.approx(0.0)
+        assert layout.origin.y.value == pytest.approx(84.01)
+        assert layout.extent.horizontal.value == pytest.approx(100.0)
+        assert layout.extent.vertical.value == pytest.approx(15.99)
+
+    def test_region_webvtt_positioning_passthrough(self):
+        """VTT->VTT round-trip: cue settings string preserved."""
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:r1\n"
+            "width:50%\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:r1\n"
+            "Hello\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        assert cue.layout_info.webvtt_positioning == "region:r1"
+
+    def test_invalid_region_reference_ignored(self):
+        vtt = (
+            "WEBVTT\n\n" "00:00:01.000 --> 00:00:03.000 region:nonexistent\n" "Hello\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        # Falls back to raw positioning passthrough
+        assert cue.layout_info.webvtt_positioning == "region:nonexistent"
+        assert cue.layout_info.origin is None
+
+    def test_duplicate_region_id_first_wins(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:dup\n"
+            "width:40%\n\n"
+            "REGION\n"
+            "id:dup\n"
+            "width:80%\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:dup\n"
+            "Test\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        assert cue.layout_info.extent.horizontal.value == pytest.approx(40.0)
+
+    def test_multiple_regions(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:top\n"
+            "width:100%\n"
+            "lines:2\n"
+            "viewportanchor:0%,10%\n"
+            "regionanchor:0%,0%\n\n"
+            "REGION\n"
+            "id:bottom\n"
+            "width:100%\n"
+            "lines:2\n"
+            "viewportanchor:0%,90%\n"
+            "regionanchor:0%,0%\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:top\n"
+            "Top caption\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:bottom\n"
+            "Bottom caption\n"
+        )
+        captions = self.reader.read(vtt)
+        cues = captions.get_captions("en-US")
+        # top: origin_y = 10 - (0/100 * 10.66) = 10.0
+        assert cues[0].layout_info.origin.y.value == pytest.approx(10.0)
+        # bottom: origin_y = 90 - (0/100 * 10.66) = 90.0
+        assert cues[1].layout_info.origin.y.value == pytest.approx(90.0)
+
+    def test_region_without_id_ignored(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "width:50%\n"
+            "lines:3\n\n"
+            "00:00:01.000 --> 00:00:03.000\n"
+            "No region reference\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        assert cue.layout_info is None
+
+    def test_duplicate_setting_in_region_first_wins(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:r1\n"
+            "width:40%\n"
+            "width:80%\n\n"
+            "00:00:01.000 --> 00:00:03.000 region:r1\n"
+            "Test\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        assert cue.layout_info.extent.horizontal.value == pytest.approx(40.0)
+
+    def test_cue_without_region_unaffected(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "REGION\n"
+            "id:r1\n"
+            "width:50%\n\n"
+            "00:00:01.000 --> 00:00:03.000\n"
+            "No region\n"
+        )
+        captions = self.reader.read(vtt)
+        cue = captions.get_captions("en-US")[0]
+        assert cue.layout_info is None