videopython 0.34.0__tar.gz → 0.34.1__tar.gz

{videopython-0.34.0 → videopython-0.34.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.34.0
+Version: 0.34.1
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/

{videopython-0.34.0 → videopython-0.34.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.34.0"
+version = "0.34.1"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },

{videopython-0.34.0 → videopython-0.34.1}/src/videopython/base/image_text.py

@@ -96,6 +96,17 @@ class TextBoxRect:
     callers short-circuit such boxes (nothing to draw). ``width`` mirrors the
     resolved ``box_width`` and may be a float when an absolute >1 value was
     passed, matching legacy behaviour.
+
+    ``content_width`` is the widest a rendered line actually gets -- worst
+    case over the animated highlight when ``highlight_size_multiplier > 1``.
+
+    There are two independent notions of "fitting" here. ``fits`` is
+    box-vs-image *only* -- the legacy contract that gates
+    :meth:`write_text_box`'s ``OutOfBoundsError`` -- and does **not** imply
+    the content fits the box: legacy callers intentionally overflow the box
+    while staying inside the image. A caller that needs the content inside
+    the box (subtitles, where the box is frame-clamped) must additionally
+    check ``content_width <= width`` itself.
     """
 
     x: float
@@ -104,6 +115,27 @@ class TextBoxRect:
     height: int
     fits: bool
     lines: tuple[str, ...]
+    content_width: int = 0
+
+
+@dataclass(frozen=True)
+class _WordPlacement:
+    """One word's resolved font/size and pixel offset within a highlighted line.
+
+    ``dx``/``dy`` are offsets from the line's left/top. Produced once by
+    :meth:`ImageText._layout_highlighted_line` and consumed by both the
+    measurer and the renderer, so the box reserved by ``measure_text_box``
+    and the pixels drawn by ``write_text_box`` cannot disagree.
+    """
+
+    word: str
+    font_filename: str | None
+    font_size: int
+    width: int
+    height: int
+    dx: int
+    dy: int
+    is_highlighted: bool
 
 
 class ImageText:
@@ -614,16 +646,22 @@ class ImageText:
         font_size: int = 11,
         anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
         margin: MarginType = 0,
+        highlight_size_multiplier: float = 1.0,
+        highlight_bold_font: str | None = None,
     ) -> TextBoxRect:
         """Measure where a wrapped text box would land, without drawing it.
 
         Pure: resolves margins/box-width/position, wraps the text, applies the
         anchor, and bounds-checks against the image — the exact math
-        :meth:`write_text_box` used to do inline. Highlighting and per-line
-        alignment (``place``) do not change the box envelope, so they are not
-        parameters here; this intentionally preserves the pre-existing
-        behaviour that an enlarged highlighted word is *not* accounted for in
-        the fit check.
+        :meth:`write_text_box` used to do inline.
+
+        ``highlight_size_multiplier > 1`` makes the measurement worst-case for
+        an *animated* highlight (any word may be the enlarged one over the
+        cue's lifetime): wrapping reserves room so even an enlarged word keeps
+        its line within ``box_width``, and ``height`` uses each line's tallest
+        possible highlighted variant. With the default ``1.0`` the result is
+        byte-identical to the plain base-font measurement, so existing callers
+        and ``place`` (alignment) are unaffected.
 
         Returns:
             A :class:`TextBoxRect`. ``fits`` is ``False`` when the box would
@@ -655,15 +693,32 @@ class ImageText:
         # Calculate initial position based on margin and anchor before splitting text
         x_pos, y_pos = self._convert_position(xy, margin_top, margin_left, available_width, available_height)
 
-        # Split text into lines that fit within box_width
+        # Wrap at the real box width (same as the renderer).
         lines = self._split_lines_by_width(text, font_filename, font_size, int(box_width))
 
-        # Calculate total height of all lines
-        lines_height = sum(self.get_text_dimensions(font_filename, font_size, line)[1] for line in lines)
+        # Per-line extent. With an animated highlight any word may be the
+        # enlarged one over the cue's lifetime, so each line contributes the
+        # widest/tallest variant it could ever render as.
+        # ``_highlighted_line_max_extent`` derives that envelope from the same
+        # per-word geometry the renderer uses (single source of truth).
+        hl_mult = max(1.0, highlight_size_multiplier)
+        content_width = 0
+        lines_height = 0
+        for line in lines:
+            if hl_mult > 1.0:
+                line_w, line_h = self._highlighted_line_max_extent(
+                    line, font_filename, font_size, hl_mult, highlight_bold_font
+                )
+            else:
+                line_w, line_h = self.get_text_dimensions(font_filename, font_size, line)
+            content_width = max(content_width, line_w)
+            lines_height += line_h
         if lines_height == 0:
             # No renderable lines (e.g. whitespace-only text); position is the
             # unadjusted insertion point and the box trivially "fits".
-            return TextBoxRect(x=x_pos, y=y_pos, width=box_width, height=0, fits=True, lines=tuple(lines))
+            return TextBoxRect(
+                x=x_pos, y=y_pos, width=box_width, height=0, fits=True, lines=tuple(lines), content_width=0
+            )
 
         # Final position calculation based on anchor point
         if anchor in AnchorPoint.center_anchors():
@@ -682,7 +737,15 @@ class ImageText:
             or x_pos + box_width > self.image_size[1]
             or y_pos + lines_height > self.image_size[0]
         )
-        return TextBoxRect(x=x_pos, y=y_pos, width=box_width, height=lines_height, fits=fits, lines=tuple(lines))
+        return TextBoxRect(
+            x=x_pos,
+            y=y_pos,
+            width=box_width,
+            height=lines_height,
+            fits=fits,
+            lines=tuple(lines),
+            content_width=content_width,
+        )
 
     def write_text_box(
         self,
@@ -761,7 +824,11 @@ class ImageText:
         if highlight_word_index is not None and highlight_color is None:
             highlight_color = text_color
 
-        # Measure (single source of truth for box geometry), then render.
+        # Measure (single source of truth for box geometry), then render. When
+        # a word will be highlighted, measure worst-case so the box reserves
+        # room for the enlarged word -- otherwise stay byte-identical to the
+        # plain base-font measurement.
+        measure_mult = highlight_size_multiplier if highlight_word_index is not None else 1.0
         rect = self.measure_text_box(
             text=text,
             font_filename=font_filename,
@@ -770,6 +837,8 @@ class ImageText:
             font_size=font_size,
             anchor=anchor,
             margin=margin,
+            highlight_size_multiplier=measure_mult,
+            highlight_bold_font=highlight_bold_font,
         )
         lines = list(rect.lines)
         if rect.height == 0:
@@ -783,56 +852,53 @@ class ImageText:
                 f"Text box with size ({box_width}x{lines_height}) at position ({x_pos}, {y_pos}) is out of bounds!"
             )
 
-        # Write lines
+        # Write lines. The line that holds the highlighted word is positioned
+        # and advanced by its *true* (enlarged) extent via the shared
+        # ``_highlighted_line_size`` -- the same numbers ``measure_text_box``
+        # reserved -- so an enlarged word can never push the line out of the
+        # box (hence out of the frame) regardless of alignment.
         current_text_height = y_pos
         word_index_offset = 0  # Track global word index across lines
         for line in lines:
-            line_dimensions = self.get_text_dimensions(font_filename, font_size, line)
+            line_words = line.split()
+            hl_local_index = -1
+            if highlight_word_index is not None:
+                line_end_word_index = word_index_offset + len(line_words) - 1
+                if word_index_offset <= highlight_word_index <= line_end_word_index:
+                    hl_local_index = highlight_word_index - word_index_offset
 
-            # Calculate horizontal position based on alignment
+            if hl_local_index >= 0:
+                line_w, line_h = self._highlighted_line_size(
+                    line, font_filename, font_size, hl_local_index, highlight_size_multiplier, highlight_bold_font
+                )
+            else:
+                line_w, line_h = self.get_text_dimensions(font_filename, font_size, line)
+
+            # Calculate horizontal position based on alignment (true line width)
             if place == TextAlign.LEFT:
                 x_left = x_pos
             elif place == TextAlign.RIGHT:
-                x_left = x_pos + box_width - line_dimensions[0]
+                x_left = x_pos + box_width - line_w
             elif place == TextAlign.CENTER:
-                x_left = int(x_pos + ((box_width - line_dimensions[0]) / 2))
+                x_left = int(x_pos + ((box_width - line_w) / 2))
             else:
                 valid_places = [e.value for e in TextAlign]
                 raise ValueError(f"Place '{place}' is not supported. Must be one of: {', '.join(valid_places)}")
 
-            # Check if highlighting is needed for this line
-            if highlight_word_index is not None:
-                line_words = line.split()
-                line_start_word_index = word_index_offset
-                line_end_word_index = word_index_offset + len(line_words) - 1
-
-                # Check if the highlighted word is in this line
-                if line_start_word_index <= highlight_word_index <= line_end_word_index:
-                    self._write_line_with_highlight(
-                        line=line,
-                        font_filename=font_filename,
-                        font_size=font_size,
-                        font_border_size=font_border_size,
-                        text_color=text_color,
-                        highlight_color=highlight_color or (255, 255, 255),
-                        highlight_size_multiplier=highlight_size_multiplier,
-                        highlight_word_local_index=highlight_word_index - line_start_word_index,
-                        highlight_bold_font=highlight_bold_font,
-                        x_left=int(x_left),
-                        y_top=int(current_text_height),
-                    )
-                else:
-                    # Write normal line without highlighting
-                    self.write_text(
-                        text=line,
-                        font_filename=font_filename,
-                        xy=(x_left, current_text_height),
-                        font_size=font_size,
-                        font_border_size=font_border_size,
-                        color=text_color,
-                    )
-
-                word_index_offset += len(line_words)
+            if hl_local_index >= 0:
+                self._write_line_with_highlight(
+                    line=line,
+                    font_filename=font_filename,
+                    font_size=font_size,
+                    font_border_size=font_border_size,
+                    text_color=text_color,
+                    highlight_color=highlight_color or (255, 255, 255),
+                    highlight_size_multiplier=highlight_size_multiplier,
+                    highlight_word_local_index=hl_local_index,
+                    highlight_bold_font=highlight_bold_font,
+                    x_left=int(x_left),
+                    y_top=int(current_text_height),
+                )
             else:
                 # Write normal line without highlighting
                 self.write_text(
@@ -844,8 +910,9 @@ class ImageText:
                     color=text_color,
                 )
 
-            # Increment vertical position for next line
-            current_text_height += line_dimensions[1]
+            word_index_offset += len(line_words)
+            # Increment vertical position for next line (true line height)
+            current_text_height += line_h
 
         # Add background color for the text if specified
         if background_color is not None:
@@ -921,6 +988,148 @@ class ImageText:
 
         return (int(x_pos + box_width), int(current_text_height))
 
+    def _highlight_font(
+        self,
+        font_filename: str | None,
+        font_size: int,
+        highlight_size_multiplier: float,
+        highlight_bold_font: str | None,
+    ) -> tuple[str | None, int, int, int]:
+        """Resolve the enlarged-word basics once.
+
+        Returns ``(font_file, font_size, baseline_offset, space_width)`` -- the
+        single definition of the highlight constants, shared by the per-word
+        layout (render / exact-size path) and the worst-case extent (measure
+        path) so those paths cannot drift apart on the fundamentals.
+        """
+        hl_font_size = int(font_size * highlight_size_multiplier)
+        hl_font_file = highlight_bold_font if highlight_bold_font is not None else font_filename
+        baseline_offset = self._get_font_baseline_offset(font_filename, font_size, hl_font_file, hl_font_size)
+        space_width = self.get_text_dimensions(font_filename, font_size, " ")[0]
+        return hl_font_file, hl_font_size, baseline_offset, space_width
+
+    def _layout_highlighted_line(
+        self,
+        line: str,
+        font_filename: str | None,
+        font_size: int,
+        highlight_word_local_index: int,
+        highlight_size_multiplier: float,
+        highlight_bold_font: str | None,
+    ) -> list[_WordPlacement]:
+        """Per-word placement for ``line`` with one word enlarged.
+
+        The single source of truth for the highlighted-line advance (enlarged
+        font size, bold-font swap, base-size inter-word space, baseline
+        offset). Both :meth:`_highlighted_line_size` (measuring the line that
+        actually owns the highlight) and :meth:`_write_line_with_highlight`
+        (rendering it) consume this list, so the reserved box and the drawn
+        pixels agree by construction.
+
+        Reached only for the line that owns the highlighted word, so
+        ``highlight_word_local_index`` is in range; degenerate inputs are
+        handled by the callers' own guards.
+        """
+        words = line.split()
+        hl_font_file, hl_font_size, baseline_offset, space_width = self._highlight_font(
+            font_filename, font_size, highlight_size_multiplier, highlight_bold_font
+        )
+        placements: list[_WordPlacement] = []
+        dx = 0
+        for i, word in enumerate(words):
+            is_hl = i == highlight_word_local_index
+            wf = hl_font_file if is_hl else font_filename
+            ws = hl_font_size if is_hl else font_size
+            w, h = self.get_text_dimensions(wf, ws, word)
+            placements.append(
+                _WordPlacement(
+                    word=word,
+                    font_filename=wf,
+                    font_size=ws,
+                    width=w,
+                    height=h,
+                    dx=dx,
+                    dy=baseline_offset if is_hl else 0,
+                    is_highlighted=is_hl,
+                )
+            )
+            dx += w
+            if i < len(words) - 1:
+                dx += space_width
+        return placements
+
+    def _highlighted_line_size(
+        self,
+        line: str,
+        font_filename: str | None,
+        font_size: int,
+        highlight_word_local_index: int,
+        highlight_size_multiplier: float,
+        highlight_bold_font: str | None,
+    ) -> tuple[int, int]:
+        """Rendered (width, height) of ``line`` with one *specific* word enlarged.
+
+        A reduction of the shared :meth:`_layout_highlighted_line`, so it is
+        exact w.r.t. the renderer by construction. Used to position/advance
+        the line that owns the highlighted word. ``highlight_word_local_index``
+        out of range falls back to the plain line size -- exactly what the
+        renderer's own guard ends up drawing.
+        """
+        words = line.split()
+        if not words:
+            return (0, 0)
+        if not (0 <= highlight_word_local_index < len(words)):
+            return self.get_text_dimensions(font_filename, font_size, line)
+        placements = self._layout_highlighted_line(
+            line, font_filename, font_size, highlight_word_local_index, highlight_size_multiplier, highlight_bold_font
+        )
+        width = max(p.dx + p.width for p in placements)
+        # ``min(0, ...)`` / ``max(0, ...)`` stay defensive for a *shrinking*
+        # highlight (multiplier < 1 -> negative baseline offset, the word
+        # rides above the line). The subtitle measure path clamps the
+        # multiplier to >= 1 so there ``top`` is always 0, but
+        # ``write_text_box`` forwards the raw multiplier, so keep the floor.
+        top = min([0, *(p.dy for p in placements)])
+        bottom = max([0, *(p.dy + p.height for p in placements)])
+        return (width, bottom - top)
+
+    def _highlighted_line_max_extent(
+        self,
+        line: str,
+        font_filename: str | None,
+        font_size: int,
+        highlight_size_multiplier: float,
+        highlight_bold_font: str | None,
+    ) -> tuple[int, int]:
+        """Worst-case (width, height) over *any* word being the enlarged one.
+
+        Equal to ``max`` of :meth:`_highlighted_line_size` across every word
+        position -- the envelope an animated highlight needs -- but in a
+        single O(words) pass instead of O(words^2): only *which* word is
+        enlarged varies, so the base metrics are shared and the extremes are
+        closed-form. Uses the same :meth:`_highlight_font` constants as the
+        layout, so this envelope can never under-reserve what the renderer
+        draws (it over-reserves only in the safe direction).
+        """
+        words = line.split()
+        if not words:
+            return self.get_text_dimensions(font_filename, font_size, line)
+        hl_font_file, hl_font_size, baseline_offset, space_width = self._highlight_font(
+            font_filename, font_size, highlight_size_multiplier, highlight_bold_font
+        )
+        base = [self.get_text_dimensions(font_filename, font_size, w) for w in words]
+        enlarged = [self.get_text_dimensions(hl_font_file, hl_font_size, w) for w in words]
+        # width_k = (sum of base widths + spaces) - base_w[k] + enlarged_w[k];
+        # the worst k just maximizes the (enlarged - base) swap.
+        base_total = sum(w for w, _ in base) + space_width * (len(words) - 1)
+        width = base_total + max(ew - bw for (bw, _), (ew, _) in zip(base, enlarged))
+        # Non-highlighted words sit at dy=0, the enlarged one at
+        # dy=baseline_offset; the worst line is the tallest base word vs. the
+        # tallest enlarged word lifted by the baseline offset.
+        top = min(0, baseline_offset)
+        bottom = max([0, *(h for _, h in base), baseline_offset + max(h for _, h in enlarged)])
+        return (width, bottom - top)
+
     def _write_line_with_highlight(
         self,
         line: str,
@@ -936,7 +1145,11 @@ class ImageText:
         y_top: int,
     ) -> None:
         """
-        Write a line of text with one word highlighted using word-by-word rendering with baseline alignment.
+        Write a line of text with one word highlighted, word-by-word with baseline alignment.
+
+        Draws the placements from the shared :meth:`_layout_highlighted_line`,
+        so every pixel lands exactly where :meth:`measure_text_box` reserved
+        room for it (measurement and rendering use the same geometry).
 
         Args:
             line: The text line to render
@@ -951,58 +1164,22 @@ class ImageText:
             x_left: Left x position for the line
             y_top: Top y position for the line
         """
-        # Split line into words
         words = line.split()
         if highlight_word_local_index >= len(words):
-            return  # Safety check
-
-        # Calculate highlighted font size and determine font files
-        highlight_font_size = int(font_size * highlight_size_multiplier)
-        highlight_font_file = highlight_bold_font if highlight_bold_font is not None else font_filename
+            return  # Safety check: nothing to draw (matches the measure fallback)
 
-        # Calculate baseline offset for highlighted words (using the appropriate font files)
-        baseline_offset = self._get_font_baseline_offset(
-            font_filename, font_size, highlight_font_file, highlight_font_size
-        )
-
-        # Render words one by one with proper spacing
-        current_x = x_left
-
-        for i, word in enumerate(words):
-            # Determine if this is the highlighted word
-            is_highlighted = i == highlight_word_local_index
-
-            # Choose font file, size, and color based on highlighting
-            word_font_file = highlight_font_file if is_highlighted else font_filename
-            word_font_size = highlight_font_size if is_highlighted else font_size
-            word_color = highlight_color if is_highlighted else text_color
-
-            # Calculate y position with baseline alignment
-            word_y = y_top
-            if is_highlighted:
-                word_y += baseline_offset
-
-            # Render the word
+        for p in self._layout_highlighted_line(
+            line, font_filename, font_size, highlight_word_local_index, highlight_size_multiplier, highlight_bold_font
+        ):
             self.write_text(
-                text=word,
-                font_filename=word_font_file,
-                xy=(current_x, word_y),
-                font_size=word_font_size,
+                text=p.word,
+                font_filename=p.font_filename,
+                xy=(x_left + p.dx, y_top + p.dy),
+                font_size=p.font_size,
                 font_border_size=font_border_size,
-                color=word_color,
+                color=highlight_color if p.is_highlighted else text_color,
             )
 
-            # Calculate the width of this word for spacing
-            word_width = self.get_text_dimensions(word_font_file, word_font_size, word)[0]
-
-            # Update current_x for next word (add word width plus space)
-            current_x += word_width
-
-            # Add space between words (except after the last word)
-            if i < len(words) - 1:
-                space_width = self.get_text_dimensions(font_filename, font_size, " ")[0]
-                current_x += space_width
-
     def _find_smallest_bounding_rect(self, mask: np.ndarray) -> tuple[int, int, int, int]:
         """
         Find the smallest bounding rectangle containing non-zero values in the mask.

{videopython-0.34.0 → videopython-0.34.1}/src/videopython/editing/transcription_overlay.py

@@ -320,6 +320,11 @@ class TranscriptionOverlay(Effect):
         the fit search and the renderer, so they never diverge. Margin math
         comes from ``ImageText.available_region`` (one source of truth with
         ``measure_text_box``).
+
+        The highlight multiplier is threaded in so the measurement is
+        worst-case for the animated word enlargement: a cue that fits at base
+        size but overflows once a word is highlighted is rejected here (and
+        auto-shrunk by ``_resolve_layout``) instead of crashing mid-render.
         """
         rect = img_text.measure_text_box(
             text=text,
@@ -329,13 +334,19 @@ class TranscriptionOverlay(Effect):
             font_size=font_px,
             anchor=cfg.anchor,
             margin=cfg.margin,
+            highlight_size_multiplier=cfg.style.highlight_size_multiplier,
+            highlight_bold_font=self.highlight_bold_font,
         )
         if rect.height == 0:
             return None
         box_w = int(rect.width)
         box_h = rect.height
         left, top, avail_w, avail_h = img_text.available_region(cfg.margin)
-        fits = box_w <= avail_w and box_h <= avail_h
+        # The box must fit the drawable area, AND the worst-case rendered line
+        # (incl. the enlarged highlighted word, or an unbreakable long word)
+        # must fit the box -- else the centered line spills off-frame at draw
+        # time. Failing this shrinks the font in ``_resolve_layout``.
+        fits = box_w <= avail_w and box_h <= avail_h and rect.content_width <= box_w
         x = min(max(int(round(rect.x)), left), left + avail_w - box_w)
         y = min(max(int(round(rect.y)), top), top + avail_h - box_h)
         return _CueBox(x=x, y=y, box_w=box_w, height=box_h, fits=fits)