pycaption 2.3.5__tar.gz → 2.3.6__tar.gz

{pycaption-2.3.5/pycaption.egg-info → pycaption-2.3.6}/PKG-INFO

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

{pycaption-2.3.5 → pycaption-2.3.6}/pycaption/dfxp/writer.py

@@ -93,6 +93,10 @@ class DFXPWriter(BaseWriter):
         :type langs: list[str]
         """
         for lang in langs:
+            caption_set.set_layout_info(
+                lang,
+                self._relativize_and_fit_to_screen(caption_set.get_layout_info(lang)),
+            )
             for caption in caption_set.get_captions(lang):
                 caption.layout_info = self._relativize_and_fit_to_screen(
                     caption.layout_info

{pycaption-2.3.5 → pycaption-2.3.6}/pycaption/geometry.py

@@ -13,6 +13,8 @@ from functools import total_ordering
 
 from .exceptions import CaptionReadSyntaxError, RelativizationError
 
+_UNIT_MISMATCH_MSG = "The sizes should have the same measure units."
+
 
 class UnitEnum(Enum):
     """Enumeration-like object, specifying the units of measure for length
@@ -29,6 +31,8 @@ class UnitEnum(Enum):
     PERCENT = "%"
     CELL = "c"
     PT = "pt"
+    VW = "vw"
+    VH = "vh"
 
 
 class VerticalAlignmentEnum(Enum):
@@ -55,6 +59,15 @@ class HorizontalAlignmentEnum(Enum):
     END = "end"
 
 
+class PositionAlignmentEnum(Enum):
+    """WebVTT position alignment: which edge of the cue box the position
+    percentage anchors to."""
+
+    LINE_LEFT = "line-left"
+    CENTER = "center"
+    LINE_RIGHT = "line-right"
+
+
 class WritingDirectionEnum(Enum):
     """Specifies WebVTT writing direction (vertical cue setting)."""
 
@@ -79,12 +92,12 @@ class Alignment:
         "after": VerticalAlignmentEnum.BOTTOM,
     }
 
-    def __init__(self, horizontal, vertical):
+    def __init__(self, horizontal=None, vertical=None):
         """
-        :type horizontal: HorizontalAlignmentEnum
-        :param horizontal: HorizontalAlignmentEnum member
-        :type vertical: VerticalAlignmentEnum
-        :param vertical: VerticalAlignmentEnum member
+        :type horizontal: HorizontalAlignmentEnum | None
+        :param horizontal: HorizontalAlignmentEnum member, or None
+        :type vertical: VerticalAlignmentEnum | None
+        :param vertical: VerticalAlignmentEnum member, or None
         """
         self.horizontal = horizontal
         self.vertical = vertical
@@ -92,16 +105,15 @@ class Alignment:
     def __hash__(self):
         return hash(hash(self.horizontal) * 83 + hash(self.vertical) * 89 + 97)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, Alignment):
             return NotImplemented
-        return (
-            self.horizontal == other.horizontal
-            and self.vertical == other.vertical
-        )
+        return self.horizontal == other.horizontal and self.vertical == other.vertical
 
     def __repr__(self):
-        return f"<Alignment ({self.horizontal} {self.vertical})>"
+        h = self.horizontal.value if self.horizontal else "None"
+        v = self.vertical.value if self.vertical else "None"
+        return f"<Alignment ({h} {v})>"
 
     def serialized(self):
         """Returns a tuple of the useful information regarding this object"""
@@ -121,12 +133,15 @@ class Alignment:
 
         if not horizontal_obj and not vertical_obj:
             return None
-        return cls(horizontal_obj, vertical_obj)
+        return Alignment(horizontal_obj, vertical_obj)
 
 
 class TwoDimensionalObject:
     """Adds a couple useful methods to its subclasses, nothing fancy."""
 
+    def __init__(self, first, second):
+        raise NotImplementedError
+
     @classmethod
     def from_xml_attribute(cls, attribute):
         """Instantiate the class from a value of the type "4px" or "5%"
@@ -134,11 +149,11 @@ class TwoDimensionalObject:
 
         :type attribute: str
         """
-        horizontal, vertical = attribute.split(" ")
-        horizontal = Size.from_string(horizontal)
-        vertical = Size.from_string(vertical)
+        first, second = attribute.split(" ")
+        first = Size.from_string(first)
+        second = Size.from_string(second)
 
-        return cls(horizontal, vertical)
+        return cls(first, second)
 
 
 class Stretch(TwoDimensionalObject):
@@ -178,13 +193,10 @@ class Stretch(TwoDimensionalObject):
             None if not self.vertical else self.vertical.serialized(),
         )
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, Stretch):
             return NotImplemented
-        return (
-            self.horizontal == other.horizontal
-            and self.vertical == other.vertical
-        )
+        return self.horizontal == other.horizontal and self.vertical == other.vertical
 
     def __hash__(self):
         return hash(hash(self.horizontal) * 59 + hash(self.vertical) * 61 + 67)
@@ -200,9 +212,8 @@ class Stretch(TwoDimensionalObject):
 
     def is_relative(self):
         """Return True if all dimensions are expressed as percentages."""
-        return (
-            (not self.horizontal or self.horizontal.is_relative())
-            and (not self.vertical or self.vertical.is_relative())
+        return (not self.horizontal or self.horizontal.is_relative()) and (
+            not self.vertical or self.vertical.is_relative()
         )
 
     def as_percentage_of(self, video_width, video_height):
@@ -240,9 +251,8 @@ class Point(TwoDimensionalObject):
 
     def is_relative(self):
         """Return True if all dimensions are expressed as percentages."""
-        return (
-            (not self.x or self.x.is_relative())
-            and (not self.y or self.y.is_relative())
+        return (not self.x or self.x.is_relative()) and (
+            not self.y or self.y.is_relative()
         )
 
     def as_percentage_of(self, video_width, video_height):
@@ -282,7 +292,7 @@ class Point(TwoDimensionalObject):
             None if not self.y else self.y.serialized(),
         )
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, Point):
             return NotImplemented
         return self.x == other.x and self.y == other.y
@@ -322,7 +332,7 @@ class Size:
         if self.unit == other.unit:
             return Size(self.value - other.value, self.unit)
         else:
-            raise ValueError("The sizes should have the same measure units.")
+            raise ValueError(_UNIT_MISMATCH_MSG)
 
     def __abs__(self):
         return Size(abs(self.value), self.unit)
@@ -331,14 +341,14 @@ class Size:
         if not isinstance(other, Size):
             return NotImplemented
         if self.unit != other.unit:
-            raise ValueError("The sizes should have the same measure units.")
+            raise ValueError(_UNIT_MISMATCH_MSG)
         return self.value < other.value
 
     def __add__(self, other):
         if self.unit == other.unit:
             return Size(self.value + other.value, self.unit)
         else:
-            raise ValueError("The sizes should have the same measure units.")
+            raise ValueError(_UNIT_MISMATCH_MSG)
 
     def is_relative(self):
         """
@@ -357,6 +367,9 @@ class Size:
         if unit == UnitEnum.PERCENT:
             return self  # Nothing to do here
 
+        if unit in (UnitEnum.VW, UnitEnum.VH):
+            return Size(value, UnitEnum.PERCENT)
+
         # The input must be valid so that any conversion can be done
         if not (video_width or video_height):
             raise RelativizationError(
@@ -401,7 +414,7 @@ class Size:
         :rtype: Size
         """
         size_pattern = re.compile(
-            r"^(((?P<value>\d+(\.\d+)?)(?P<unit>"
+            r"^(((?P<value>-?\d+(\.\d+)?)(?P<unit>"
             rf"{'|'.join([unit.value for unit in UnitEnum])}))|0)$"
         )
         match = size_pattern.search(string)
@@ -416,7 +429,6 @@ class Size:
             value = match.group("value")
             return cls(value, UnitEnum(unit))
         else:
-            # If the unit is missing, the only accepted alternative is zero
             return cls(match.group(0), UnitEnum.PIXEL)
 
     def __repr__(self):
@@ -438,7 +450,7 @@ class Size:
         """Returns the "useful" values of this object"""
         return self.value, self.unit
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, Size):
             return NotImplemented
         return self.value == other.value and self.unit == other.unit
@@ -447,7 +459,6 @@ class Size:
         return hash(hash(self.value) * 41 + hash(self.unit) * 43 + 47)
 
 
-
 class Padding:
     """Represents padding information. Consists of 4 Size objects, representing
     padding from (in this order): before (up), after (down), start (left) and
@@ -518,11 +529,11 @@ class Padding:
             None if not self.end else self.end.serialized(),
         )
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Padding):
+            return NotImplemented
         return (
-            other
-            and type(self) == type(other)
-            and self.before == other.before
+            self.before == other.before
             and self.after == other.after
             and self.start == other.start
             and self.end == other.end
@@ -597,6 +608,7 @@ class Layout:
         alignment=None,
         webvtt_positioning=None,
         writing_direction=None,
+        position_alignment=None,
         inherit_from=None,
     ):
         """
@@ -622,6 +634,10 @@ class Layout:
         :type writing_direction: WritingDirectionEnum
         :param writing_direction: WebVTT vertical writing direction (rl or lr).
 
+        :type position_alignment: PositionAlignmentEnum
+        :param position_alignment: Which edge of the cue box the position
+            percentage anchors to (line-left, center, or line-right).
+
         :type inherit_from: Layout
         :param inherit_from: A Layout with the positioning parameters to be
             used if not specified by the positioning arguments,
@@ -633,6 +649,7 @@ class Layout:
         self.alignment = alignment
         self.webvtt_positioning = webvtt_positioning
         self.writing_direction = writing_direction
+        self.position_alignment = position_alignment
 
         if inherit_from:
             for attr_name in [
@@ -641,20 +658,24 @@ class Layout:
                 "padding",
                 "alignment",
                 "writing_direction",
+                "position_alignment",
             ]:
                 attr = getattr(self, attr_name)
                 if not attr:
                     setattr(self, attr_name, getattr(inherit_from, attr_name))
 
     def __bool__(self):
-        return any((
-            self.origin,
-            self.extent,
-            self.padding,
-            self.alignment,
-            self.webvtt_positioning,
-            self.writing_direction,
-        ))
+        return any(
+            (
+                self.origin,
+                self.extent,
+                self.padding,
+                self.alignment,
+                self.webvtt_positioning,
+                self.writing_direction,
+                self.position_alignment,
+            )
+        )
 
     def __repr__(self):
         return (
@@ -670,16 +691,19 @@ class Layout:
             None if not self.padding else self.padding.serialized(),
             None if not self.alignment else self.alignment.serialized(),
             self.writing_direction,
+            self.position_alignment,
         )
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Layout):
+            return NotImplemented
         return (
-            type(self) == type(other)
-            and self.origin == other.origin
+            self.origin == other.origin
             and self.extent == other.extent
             and self.padding == other.padding
             and self.alignment == other.alignment
             and self.writing_direction == other.writing_direction
+            and self.position_alignment == other.position_alignment
         )
 
     def __hash__(self):
@@ -689,6 +713,7 @@ class Layout:
             + hash(self.padding) * 13
             + hash(self.alignment) * 5
             + hash(self.writing_direction) * 19
+            + hash(self.position_alignment) * 23
             + 17
         )
 
@@ -709,6 +734,7 @@ class Layout:
         params = {
             "alignment": self.alignment,
             "writing_direction": self.writing_direction,
+            "position_alignment": self.position_alignment,
         }
         for attr_name in ["origin", "extent", "padding"]:
             attr = getattr(self, attr_name)
@@ -723,34 +749,77 @@ class Layout:
         technically valid but contain inconsistent settings that may cause
         long captions to be cut out of the screen.
 
+        When position_alignment is set, the origin is first adjusted so that
+        origin.x represents the true left edge of the cue box (the W3C spec
+        allows the position to anchor to center or right edge).
+
         ATTENTION: This must be called on relativized objects (such as the one
         returned by as_percentage_of). All units are presumed to be percentages.
         """
         if not self.origin:
             return self
 
-        diff_horizontal = Size(90 - self.origin.x.value, UnitEnum.PERCENT)
-        diff_vertical = Size(95 - self.origin.y.value, UnitEnum.PERCENT)
+        if (
+            self.origin.x.unit != UnitEnum.PERCENT
+            or self.origin.y.unit != UnitEnum.PERCENT
+        ):
+            return self
+
+        origin = self._resolve_position_alignment()
+
+        if origin.x.value >= 90 or origin.y.value >= 95:
+            return self
+
+        diff_horizontal = Size(90 - origin.x.value, UnitEnum.PERCENT)
+        diff_vertical = Size(95 - origin.y.value, UnitEnum.PERCENT)
 
         if not self.extent:
             new_extent = Stretch(diff_horizontal, diff_vertical)
         else:
-            new_extent = self._corrected_extent(diff_horizontal, diff_vertical)
+            new_extent = self._corrected_extent_from(
+                origin, diff_horizontal, diff_vertical
+            )
 
         return Layout(
-            origin=self.origin,
+            origin=origin,
             extent=new_extent,
             padding=self.padding,
             alignment=self.alignment,
             writing_direction=self.writing_direction,
         )
 
-    def _corrected_extent(self, diff_horizontal, diff_vertical):
+    def _resolve_position_alignment(self):
+        """Adjust origin.x based on position_alignment and extent width.
+
+        The VTT reader always stores the ``position`` setting in origin.x
+        and ``size`` in extent.horizontal, regardless of writing direction.
+        This method adjusts origin.x so it represents the true left edge
+        of the cue box.
+
+        Returns a new Point (or self.origin unchanged for LINE_LEFT/None).
+        """
+        if not self.position_alignment or not self.extent:
+            return self.origin
+
+        width = self.extent.horizontal.value
+
+        if self.position_alignment == PositionAlignmentEnum.CENTER:
+            adjusted_x = max(0, self.origin.x.value - width / 2)
+        elif self.position_alignment == PositionAlignmentEnum.LINE_RIGHT:
+            adjusted_x = max(0, self.origin.x.value - width)
+        else:
+            return self.origin
+
+        return Point(Size(adjusted_x, UnitEnum.PERCENT), self.origin.y)
+
+    def _corrected_extent_from(self, origin, diff_horizontal, diff_vertical):
         """Return extent clamped so origin + extent doesn't exceed the screen."""
-        bottom_right = self.origin.add_stretch(self.extent)
+        bottom_right = origin.add_stretch(self.extent)
 
-        if (bottom_right.x.unit != UnitEnum.PERCENT
-                or bottom_right.y.unit != UnitEnum.PERCENT):
+        if (
+            bottom_right.x.unit != UnitEnum.PERCENT
+            or bottom_right.y.unit != UnitEnum.PERCENT
+        ):
             raise ValueError(
                 "Units must be relativized before extent "
                 "can be calculated based on origin."

{pycaption-2.3.5 → pycaption-2.3.6}/pycaption/scc/reader.py

@@ -82,12 +82,12 @@ from collections import deque
 from copy import deepcopy
 
 from pycaption.base import BaseReader, CaptionSet
-from pycaption.geometry import HorizontalAlignmentEnum
 from pycaption.exceptions import (
     CaptionLineLengthError,
     CaptionReadNoCaptions,
     CaptionReadTimingError,
 )
+from pycaption.geometry import HorizontalAlignmentEnum
 
 from .constants import (
     CHARACTERS,
@@ -107,7 +107,7 @@ from .specialized_collections import (
 )
 from .state_machines import DefaultProvidingPositionTracker
 
-
+_TIMECODE_RE = re.compile(r"\d{2}:\d{2}:\d{2}[:;](\d{1,2})")
 
 
 class SCCReader(BaseReader):
@@ -142,6 +142,7 @@ class SCCReader(BaseReader):
         self.roll_rows_expected = 0
         self.simulate_roll_up = False
 
+        self._raw_lines = []
         self.time = 0
 
     def detect(self, content):
@@ -181,8 +182,8 @@ class SCCReader(BaseReader):
 
         self.simulate_roll_up = simulate_roll_up
         self.time_translator.offset = offset * 1000000
-        # split lines
         lines = content.splitlines()
+        self._raw_lines = lines
 
         # loop through each line except the first
         for line in lines[1:]:
@@ -204,11 +205,13 @@ class SCCReader(BaseReader):
 
         Raises CaptionReadNoCaptions if no captions were parsed,
         CaptionLineLengthError if any line exceeds 32 characters,
+        CaptionReadTimingError if any timecode has frame >= 30,
         and CaptionReadTimingError if any cue is shorter than 0.05s.
         """
         if captions.is_empty():
             raise CaptionReadNoCaptions("empty caption file")
 
+        self._validate_frame_numbers()
         self._validate_line_lengths()
 
         for cap in captions.get_captions(lang):
@@ -219,6 +222,22 @@ class SCCReader(BaseReader):
                     f"must be at least 0.05 seconds."
                 )
 
+    def _validate_frame_numbers(self):
+        """Raise CaptionReadTimingError if any timecode has frames >= 30."""
+        violations = []
+        for line in self._raw_lines:
+            match = _TIMECODE_RE.match(line.strip())
+            if match:
+                frames = int(match.group(1))
+                if frames >= 30:
+                    timecode = match.group(0)
+                    violations.append(f"{timecode} (frame {frames})")
+        if violations:
+            raise CaptionReadTimingError(
+                "Frame number must be 0-29 in SCC timecodes.\n"
+                "Invalid timecodes:\n" + "\n".join(violations)
+            )
+
     def _validate_line_lengths(self):
         """Raise CaptionLineLengthError if any line exceeds 32 characters."""
         violations = [
@@ -473,9 +492,7 @@ class SCCReader(BaseReader):
     def _new_buffer(self):
         """Create a fresh InstructionNodeCreator bound to the shared
         position tracker."""
-        return InstructionNodeCreator(
-            position_tracker=self.position_tracker
-        )
+        return InstructionNodeCreator(position_tracker=self.position_tracker)
 
     def _reset_buffer(self):
         """Replace the active buffer with a fresh creator and reset position state."""
@@ -632,4 +649,3 @@ class _SccTimeTranslator:
         """
         self._time = timespec
         self._frames = 0
-

{pycaption-2.3.5 → pycaption-2.3.6}/pycaption/webvtt/constants.py

@@ -6,7 +6,7 @@ docstrings below each pattern explain what they capture and give examples.
 
 import re
 
-from ..geometry import HorizontalAlignmentEnum
+from ..geometry import HorizontalAlignmentEnum, PositionAlignmentEnum
 
 TIMING_LINE_PATTERN = re.compile(r"^(\S+)\s+-->\s+(\S+)(?:\s+(.*?))?\s*$")
 """
@@ -52,10 +52,13 @@ Matches two percentage values (integer or decimal) separated by a comma:
 0%,0%
 100%,100%
 """
-CUE_SETTING_PATTERN = re.compile(r"(position|line|size|align|vertical):([\w.%-]+)")
+CUE_SETTING_PATTERN = re.compile(
+    r"(position|line|size|align|vertical):([\w.%-]+(?:,[\w.%-]+)?)"
+)
 """
-Matches individual cue settings from the timing line:
-position:50%  line:75%  size:80%  align:center  vertical:rl
+Matches individual cue settings from the timing line, including optional
+comma-separated alignment qualifiers per W3C WebVTT spec:
+position:50%  position:50%,line-left  line:80%,center  align:center
 """
 STYLE_SELECTOR_PATTERN = re.compile(r"::cue(?:\((\.?[\w-]+)\))?\s*\{([^}]*)\}")
 """
@@ -99,6 +102,15 @@ ALIGN_SETTING_MAP = {
 """Reverse mapping from WebVTT ``align`` setting strings to internal
 HorizontalAlignmentEnum values (used by the reader)."""
 
+POSITION_ALIGN_MAP = {
+    "line-left": PositionAlignmentEnum.LINE_LEFT,
+    "center": PositionAlignmentEnum.CENTER,
+    "line-right": PositionAlignmentEnum.LINE_RIGHT,
+    "start": PositionAlignmentEnum.LINE_LEFT,
+    "end": PositionAlignmentEnum.LINE_RIGHT,
+}
+"""Maps WebVTT positionAlign qualifier strings to PositionAlignmentEnum."""
+
 
 def _is_note_start(line):
     """Return True if the line begins a WebVTT NOTE block."""