videopython 0.33.5__tar.gz → 0.34.0__tar.gz

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

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

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

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

{videopython-0.33.5 → videopython-0.34.0}/src/videopython/ai/transforms.py

@@ -12,7 +12,7 @@ from tqdm import tqdm
 
 from videopython.ai.understanding.faces import FaceTracker
 from videopython.base._dimensions import floor_to_even
-from videopython.base.video import Video
+from videopython.base.video import Video, VideoMetadata
 from videopython.editing.operation import OpCategory, Operation
 
 logger = logging.getLogger(__name__)
@@ -76,6 +76,28 @@ class FaceTrackingCrop(Operation):
         # "dynamic" — placeholder until motion/look-direction framing is implemented.
         return (face_cx, face_cy - self.headroom)
 
+    def _resolved_output_dims(self, w: int, h: int) -> tuple[int, int]:
+        """Output ``(width, height)`` after the crop + resize.
+
+        Every frame is resized to this size regardless of the per-frame face
+        position, so it is a pure function of the input dimensions and
+        ``target_aspect``. Single source of truth shared by :meth:`apply` and
+        :meth:`predict_metadata` (mirrors ``Resize._resolve_dims`` /
+        ``Crop._resolve_box``), so the dry-run cannot disagree with the render.
+        """
+        target_ratio = self.target_aspect[0] / self.target_aspect[1]
+        if target_ratio < w / h:
+            out_h = floor_to_even(h)
+            out_w = floor_to_even(int(out_h * target_ratio))
+        else:
+            out_w = floor_to_even(w)
+            out_h = floor_to_even(int(out_w / target_ratio))
+        return out_w, out_h
+
+    def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata:
+        out_w, out_h = self._resolved_output_dims(meta.width, meta.height)
+        return meta.with_dimensions(out_w, out_h)
+
     def _clamp_speed(self, current: tuple[float, float], target: tuple[float, float]) -> tuple[float, float]:
         if self.max_speed is None:
             return target
@@ -135,13 +157,7 @@ class FaceTrackingCrop(Operation):
         )
 
         h, w = video.frame_shape[:2]
-        target_ratio = self.target_aspect[0] / self.target_aspect[1]
-        if target_ratio < w / h:
-            out_h = floor_to_even(h)
-            out_w = floor_to_even(int(out_h * target_ratio))
-        else:
-            out_w = floor_to_even(w)
-            out_h = floor_to_even(int(out_w / target_ratio))
+        out_w, out_h = self._resolved_output_dims(w, h)
 
         default_x = (w - out_w) // 2
         default_y = (h - out_h) // 2

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

@@ -9,6 +9,7 @@ generation helpers (``ai/understanding/image.py``).
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from enum import Enum
 from typing import TypeAlias
 
@@ -18,7 +19,7 @@ from PIL import Image, ImageDraw, ImageFont
 from videopython.base.exceptions import OutOfBoundsError
 from videopython.base.fonts import load_font
 
-__all__ = ["ImageText", "TextAlign", "AnchorPoint"]
+__all__ = ["ImageText", "TextAlign", "AnchorPoint", "TextBoxRect"]
 
 # Type aliases for clarity
 MarginType: TypeAlias = int | tuple[int, int, int, int]
@@ -79,6 +80,32 @@ class AnchorPoint(str, Enum):
         return (cls.BOTTOM_LEFT, cls.BOTTOM_CENTER, cls.BOTTOM_RIGHT)
 
 
+@dataclass(frozen=True)
+class TextBoxRect:
+    """Resolved geometry of a wrapped text box, without rendering it.
+
+    Returned by :meth:`ImageText.measure_text_box` — the single source of
+    truth for box measure/wrap/anchor/bounds, shared by the renderer
+    (:meth:`ImageText.write_text_box`) and dry-run validators so they can
+    never disagree on whether text fits.
+
+    For a non-degenerate box ``(x, y)`` is the anchor-adjusted top-left
+    corner and ``width``/``height`` span the wrapped lines. For a degenerate
+    box (whitespace-only text → no renderable lines) ``height == 0``,
+    ``(x, y)`` is the *unadjusted* insertion point, and ``fits`` is ``True``;
+    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.
+    """
+
+    x: float
+    y: float
+    width: int | float
+    height: int
+    fits: bool
+    lines: tuple[str, ...]
+
+
 class ImageText:
     def __init__(
         self,
@@ -566,6 +593,97 @@ class ImageText:
         lines = [" ".join(line) for line in split_lines]
         return lines
 
+    def available_region(self, margin: MarginType = 0) -> tuple[int, int, int, int]:
+        """The drawable area inside ``margin`` as ``(left, top, width, height)``.
+
+        Single source of truth for margin-inset geometry: used by
+        :meth:`measure_text_box` and by callers that need to clamp a box
+        within the margins without re-deriving the margin math.
+        """
+        margin_top, margin_right, margin_bottom, margin_left = self._process_margin(margin)
+        available_width = self.image_size[1] - margin_left - margin_right
+        available_height = self.image_size[0] - margin_top - margin_bottom
+        return margin_left, margin_top, available_width, available_height
+
+    def measure_text_box(
+        self,
+        text: str,
+        font_filename: str | None,
+        xy: PositionType,
+        box_width: int | float | None = None,
+        font_size: int = 11,
+        anchor: AnchorPoint = AnchorPoint.TOP_LEFT,
+        margin: MarginType = 0,
+    ) -> 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.
+
+        Returns:
+            A :class:`TextBoxRect`. ``fits`` is ``False`` when the box would
+            fall outside the image bounds (the condition that makes
+            :meth:`write_text_box` raise :class:`OutOfBoundsError`).
+
+        Raises:
+            ValueError: If ``text`` is empty, ``font_size`` is not positive,
+                or an absolute ``box_width`` is not positive.
+        """
+        if not text:
+            raise ValueError("Text cannot be empty")
+
+        if font_size <= 0:
+            raise ValueError("Font size must be positive")
+
+        # Process margins to determine available area (shared with callers
+        # that clamp boxes inside the margins -- see ``available_region``).
+        margin_left, margin_top, available_width, available_height = self.available_region(margin)
+
+        # Handle relative box width
+        if box_width is None:
+            box_width = available_width
+        elif isinstance(box_width, float) and 0 < box_width <= 1:
+            box_width = int(available_width * box_width)
+        elif isinstance(box_width, int) and box_width <= 0:
+            raise ValueError("Box width must be positive")
+
+        # 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
+        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)
+        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))
+
+        # Final position calculation based on anchor point
+        if anchor in AnchorPoint.center_anchors():
+            x_pos -= box_width // 2
+        elif anchor in AnchorPoint.right_anchors():
+            x_pos -= box_width
+
+        if anchor in AnchorPoint.middle_anchors():
+            y_pos -= lines_height // 2
+        elif anchor in AnchorPoint.bottom_anchors():
+            y_pos -= lines_height
+
+        fits = not (
+            x_pos < 0
+            or y_pos < 0
+            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))
+
     def write_text_box(
         self,
         text: str,
@@ -643,49 +761,24 @@ class ImageText:
         if highlight_word_index is not None and highlight_color is None:
             highlight_color = text_color
 
-        # Process margins to determine available area
-        margin_top, margin_right, margin_bottom, margin_left = self._process_margin(margin)
-        available_width = self.image_size[1] - margin_left - margin_right
-        available_height = self.image_size[0] - margin_top - margin_bottom
-
-        # Handle relative box width
-        if box_width is None:
-            box_width = available_width
-        elif isinstance(box_width, float) and 0 < box_width <= 1:
-            box_width = int(available_width * box_width)
-        elif isinstance(box_width, int) and box_width <= 0:
-            raise ValueError("Box width must be positive")
-
-        # 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
-        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])
-        if lines_height == 0:
-            # If we have no valid lines or zero height, return the position
-            return (int(x_pos), int(y_pos))
-
-        # Final position calculation based on anchor point
-        if anchor in AnchorPoint.center_anchors():
-            x_pos -= box_width // 2
-        elif anchor in AnchorPoint.right_anchors():
-            x_pos -= box_width
-
-        if anchor in AnchorPoint.middle_anchors():
-            y_pos -= lines_height // 2
-        elif anchor in AnchorPoint.bottom_anchors():
-            y_pos -= lines_height
-
-        # Verify box will fit within bounds
-        if (
-            x_pos < 0
-            or y_pos < 0
-            or x_pos + box_width > self.image_size[1]
-            or y_pos + lines_height > self.image_size[0]
-        ):
+        # Measure (single source of truth for box geometry), then render.
+        rect = self.measure_text_box(
+            text=text,
+            font_filename=font_filename,
+            xy=xy,
+            box_width=box_width,
+            font_size=font_size,
+            anchor=anchor,
+            margin=margin,
+        )
+        lines = list(rect.lines)
+        if rect.height == 0:
+            # No renderable lines (e.g. whitespace-only text); nothing to draw.
+            return (int(rect.x), int(rect.y))
+        box_width = rect.width
+        x_pos, y_pos = rect.x, rect.y
+        lines_height = rect.height
+        if not rect.fits:
             raise OutOfBoundsError(
                 f"Text box with size ({box_width}x{lines_height}) at position ({x_pos}, {y_pos}) is out of bounds!"
             )

{videopython-0.33.5 → videopython-0.34.0}/src/videopython/editing/__init__.py

@@ -21,7 +21,7 @@ from .effects import (
     Zoom,
 )
 from .operation import FilterCtx, OpCategory, Operation, TimeRange
-from .transcription_overlay import TranscriptionOverlay
+from .transcription_overlay import SubtitleRegion, SubtitleStyle, TranscriptionOverlay
 from .transforms import (
     Crop,
     CropMode,
@@ -65,6 +65,8 @@ __all__ = [
     "VolumeAdjust",
     "TextOverlay",
     "TranscriptionOverlay",
+    "SubtitleStyle",
+    "SubtitleRegion",
     "Shake",
     "PunchIn",
     "Flash",

videopython-0.34.0/src/videopython/editing/transcription_overlay.py

@@ -0,0 +1,516 @@
+"""Subtitle overlay effect.
+
+``TranscriptionOverlay`` is an :class:`Effect` that renders animated
+word-by-word subtitles onto a :class:`Video` using a word-level
+:class:`Transcription`. Rendering is delegated to ``ImageText`` from
+the sibling module.
+
+The public surface is intentionally small and *resolution-independent*:
+pick a ``style`` preset, a ``region``, and a ``font_scale`` (fraction of
+frame height). The legacy absolute fields (``font_size``, explicit colors,
+``position``/``anchor``/``box_width``/``margin``) remain as optional advanced
+overrides for back-compat -- left unset they are derived from the presets, so
+an authored plan cannot encode a resolution-specific value that overflows the
+real (post-transform) frame.
+
+Fit safety is layered:
+
+* one routine (:meth:`_resolve_layout`) decides the final font size for both
+  the dry-run and the render, so they can never disagree;
+* it auto-shrinks the font within a legible band and clamps the box inside
+  the frame (graceful render fit);
+* only a cue that cannot fit even at the minimum legible size is an error,
+  and that error is raised by :meth:`predict_metadata` at
+  ``VideoEdit.validate()`` time -- before any frame/GPU work -- never
+  mid-render.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, ClassVar, Literal
+
+import numpy as np
+from PIL import Image
+from pydantic import Field
+from tqdm import tqdm
+
+from videopython.base.image_text import AnchorPoint, ImageText, TextAlign
+from videopython.base.transcription import Transcription, TranscriptionSegment
+from videopython.base.video import Video, VideoMetadata
+from videopython.editing.operation import Effect
+
+__all__ = ["TranscriptionOverlay", "SubtitleStyle", "SubtitleRegion"]
+
+logger = logging.getLogger(__name__)
+
+# Sentinel for ``background_color``: ``None`` already means "no background",
+# so it cannot double as "derive from the style preset".
+_AUTO: Literal["auto"] = "auto"
+
+RGBColor = tuple[int, int, int]
+RGBAColor = tuple[int, int, int, int]
+
+
+class SubtitleStyle(str, Enum):
+    """Named look bundling colors / border / background / highlight.
+
+    Lets a caller express intent ("boxed", "outline", ...) instead of a
+    dozen individual numbers. ``BOXED`` reproduces the historical defaults
+    exactly, so upgrading without changing fields is visually a no-op except
+    for the now resolution-relative font size.
+    """
+
+    BOXED = "boxed"
+    OUTLINE = "outline"
+    CLEAN = "clean"
+    KARAOKE = "karaoke"
+
+
+class SubtitleRegion(str, Enum):
+    """Vertical safe-area band the subtitle box is centered in."""
+
+    TOP = "top"
+    CENTER = "center"
+    BOTTOM = "bottom"
+
+
+@dataclass(frozen=True)
+class _StyleParams:
+    text_color: RGBColor
+    highlight_color: RGBColor
+    border: int
+    background_color: RGBAColor | None
+    background_padding: int
+    highlight_size_multiplier: float
+
+
+_STYLE_PRESETS: dict[SubtitleStyle, _StyleParams] = {
+    # Exactly the pre-redesign defaults.
+    SubtitleStyle.BOXED: _StyleParams((255, 235, 59), (76, 175, 80), 2, (0, 0, 0, 100), 15, 1.2),
+    SubtitleStyle.OUTLINE: _StyleParams((255, 255, 255), (255, 235, 59), 4, None, 0, 1.15),
+    SubtitleStyle.CLEAN: _StyleParams((255, 255, 255), (76, 175, 80), 2, None, 0, 1.1),
+    SubtitleStyle.KARAOKE: _StyleParams((255, 255, 255), (255, 90, 95), 3, (0, 0, 0, 120), 18, 1.25),
+}
+
+# region -> normalized (x, y) center of the box; anchor stays CENTER so the
+# box is centered on this point. Chosen to sit inside a conventional safe area.
+_REGION_POSITION: dict[SubtitleRegion, tuple[float, float]] = {
+    SubtitleRegion.TOP: (0.5, 0.18),
+    SubtitleRegion.CENTER: (0.5, 0.5),
+    SubtitleRegion.BOTTOM: (0.5, 0.82),
+}
+
+
+@dataclass(frozen=True)
+class _CueBox:
+    """Absolute, frame-clamped placement of one cue's text box."""
+
+    x: int
+    y: int
+    box_w: int
+    height: int
+    fits: bool
+
+
+@dataclass(frozen=True)
+class _ResolvedConfig:
+    """Every override-or-preset field resolved to a concrete value once.
+
+    Deterministic from the model fields, so the dry-run and the render
+    derive identical geometry and look (parity).
+    """
+
+    position: tuple[float, float]
+    anchor: AnchorPoint
+    box_width: float
+    text_align: TextAlign
+    margin: int | tuple[int, int, int, int]
+    style: _StyleParams
+
+
+@dataclass(frozen=True)
+class _SubtitleLayout:
+    """Outcome of resolving the overlay against a concrete frame size.
+
+    ``segments`` are post-transform cues (``chunk`` + ``capitalize``) and
+    ``config`` is the resolved geometry/look -- both shared by render and
+    dry-run so they measure and draw identical boxes. ``font_px`` is the
+    single font size both paths use. ``fits`` is False with a populated
+    ``error`` only when a cue cannot fit even at the minimum legible size.
+    """
+
+    segments: list[TranscriptionSegment]
+    config: _ResolvedConfig
+    font_px: int
+    fits: bool
+    error: str | None
+
+
+class TranscriptionOverlay(Effect):
+    """Renders animated word-by-word subtitles with the current word highlighted.
+
+    Each word lights up in the highlight color as it is spoken, based on
+    transcription timestamps. Requires a word-level transcription, which the
+    runner supplies via the ``requires=("transcription",)`` declaration.
+
+    Geometry is resolution-relative by default (``font_scale``/``region``), so
+    a plan validated by ``VideoEdit.validate()`` that passes will also render;
+    a plan that cannot fit fails fast in :meth:`predict_metadata` instead of
+    crashing mid-render after expensive upstream ops.
+    """
+
+    op: Literal["add_subtitles"] = "add_subtitles"
+    streamable: ClassVar[bool] = False
+    requires: ClassVar[tuple[str, ...]] = ("transcription",)
+
+    # ---- primary, resolution-independent surface ----
+    style: SubtitleStyle = Field(
+        SubtitleStyle.BOXED,
+        description='Look preset bundling colors/border/background/highlight: "boxed", "outline", "clean", "karaoke".',
+    )
+    region: SubtitleRegion = Field(
+        SubtitleRegion.BOTTOM,
+        description='Vertical placement band: "top", "center", or "bottom" of the frame.',
+    )
+    font_scale: float = Field(
+        0.055,
+        gt=0.0,
+        le=0.5,
+        description=(
+            "Base font height as a fraction of frame height (resolution-independent; the recommended "
+            "way to size subtitles). Auto-shrinks toward `min_font_scale` if a cue would overflow."
+        ),
+    )
+    min_font_scale: float = Field(
+        0.030,
+        gt=0.0,
+        le=0.5,
+        description=(
+            "Lower bound for auto-fit shrinking, as a fraction of frame height. A cue that cannot fit "
+            "even at this size is a validation error rather than an illegible render."
+        ),
+    )
+    max_words_per_cue: int | None = Field(
+        5,
+        ge=1,
+        description=(
+            "Maximum words shown on screen at once. Each transcription segment is re-chunked into "
+            "cues of at most this many words, without bridging the silence gaps between segments, so "
+            "subtitles stay readable and don't linger over pauses. None preserves the source "
+            "transcription's segmentation."
+        ),
+    )
+    capitalize: bool = Field(
+        True,
+        description=(
+            "Capitalize the first letter of each sentence (first word, and words after '.', '!', '?'). "
+            "Fixes lowercase sentence starts from word-level speech-to-text. Set False to render text "
+            "exactly as transcribed."
+        ),
+    )
+    font_filename: str | None = Field(
+        None,
+        description="Path to a .ttf font file for rendering subtitle text, or None for the bundled default font.",
+    )
+    highlight_bold_font: str | None = Field(
+        None, description="Path to a bold .ttf font for the highlighted word, or None to use the regular font."
+    )
+
+    # ---- advanced overrides: None => derive from style/region/font_scale ----
+    font_size: int | None = Field(
+        None,
+        ge=1,
+        description=(
+            "Advanced override: absolute base font size in pixels. Leave None to derive from "
+            "`font_scale` (recommended -- resolution-independent and overflow-safe)."
+        ),
+    )
+    font_border_size: int | None = Field(
+        None, ge=0, description="Advanced override for outline thickness in px. None takes it from `style`."
+    )
+    text_color: RGBColor | None = Field(
+        None, description="Advanced override for default text color [R, G, B] (0-255). None takes it from `style`."
+    )
+    background_color: RGBAColor | None | Literal["auto"] = Field(
+        _AUTO,
+        description=(
+            'Advanced override for the box background [R, G, B, A] (0-255). "auto" takes it from `style`; '
+            "null explicitly disables the background."
+        ),
+    )
+    background_padding: int | None = Field(
+        None, ge=0, description="Advanced override: px between text and background edge. None takes it from `style`."
+    )
+    highlight_color: RGBColor | None = Field(
+        None, description="Advanced override for the spoken-word color [R, G, B]. None takes it from `style`."
+    )
+    highlight_size_multiplier: float | None = Field(
+        None, gt=0, description="Advanced override: scale factor for the highlighted word. None takes it from `style`."
+    )
+    position: tuple[float, float] | None = Field(
+        None,
+        description="Advanced override: box center as normalized (x, y). None derives it from `region`.",
+    )
+    box_width: float | None = Field(
+        None,
+        gt=0.0,
+        le=1.0,
+        description="Advanced override: box width as a fraction of frame width in (0, 1]. None uses 0.6.",
+    )
+    text_align: TextAlign | None = Field(
+        None, description='Advanced override: text alignment within the box. None uses "center".'
+    )
+    anchor: AnchorPoint | None = Field(
+        None, description="Advanced override: which point of the box sits at the position. None uses center."
+    )
+    margin: int | tuple[int, int, int, int] | None = Field(
+        None,
+        description="Advanced override: space around the box in px (or [top, right, bottom, left]). None uses 20.",
+    )
+
+    # ------------------------------------------------------------- resolution
+
+    def _style_params(self) -> _StyleParams:
+        """Effective look: the ``style`` preset overlaid by any explicit overrides."""
+        p = _STYLE_PRESETS[self.style]
+        bg = p.background_color if self.background_color == _AUTO else self.background_color
+        return _StyleParams(
+            text_color=self.text_color or p.text_color,
+            highlight_color=self.highlight_color or p.highlight_color,
+            border=self.font_border_size if self.font_border_size is not None else p.border,
+            background_color=bg,
+            background_padding=(
+                self.background_padding if self.background_padding is not None else p.background_padding
+            ),
+            highlight_size_multiplier=(
+                self.highlight_size_multiplier
+                if self.highlight_size_multiplier is not None
+                else p.highlight_size_multiplier
+            ),
+        )
+
+    def _resolve_config(self) -> _ResolvedConfig:
+        """Resolve every override-or-preset field to a concrete value once."""
+        return _ResolvedConfig(
+            position=self.position if self.position is not None else _REGION_POSITION[self.region],
+            anchor=self.anchor if self.anchor is not None else AnchorPoint.CENTER,
+            box_width=self.box_width if self.box_width is not None else 0.6,
+            text_align=self.text_align if self.text_align is not None else TextAlign.CENTER,
+            margin=self.margin if self.margin is not None else 20,
+            style=self._style_params(),
+        )
+
+    def _transform(self, transcription: Transcription) -> Transcription:
+        """Apply the cue transforms render and dry-run MUST share."""
+        if self.max_words_per_cue is not None:
+            transcription = transcription.chunk_segments(self.max_words_per_cue)
+        if self.capitalize:
+            transcription = transcription.capitalize_sentences()
+        return transcription
+
+    def _place_cue(self, img_text: ImageText, text: str, font_px: int, cfg: _ResolvedConfig) -> _CueBox | None:
+        """Measure ``text`` at ``font_px`` and clamp its box inside the margins.
+
+        Returns ``None`` for a degenerate (whitespace-only) cue. ``fits`` is
+        False when the box is larger than the drawable area even after
+        clamping -- i.e. shrinking the font is the only remedy. Used by both
+        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``).
+        """
+        rect = img_text.measure_text_box(
+            text=text,
+            font_filename=self.font_filename,
+            xy=cfg.position,
+            box_width=cfg.box_width,
+            font_size=font_px,
+            anchor=cfg.anchor,
+            margin=cfg.margin,
+        )
+        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
+        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)
+
+    def _resolve_layout(self, width: int, height: int, transcription: Transcription) -> _SubtitleLayout:
+        """Single source of truth for config + font size + fit (render & dry-run)."""
+        segments = self._transform(transcription).segments
+        cues = [s for s in segments if s.text.strip()]
+        cfg = self._resolve_config()
+
+        desired = self.font_size if self.font_size is not None else max(1, round(self.font_scale * height))
+        floor = max(1, round(self.min_font_scale * height))
+        # Never search above the desired size nor below the legible floor --
+        # but if the user pinned a font_size below the floor, honor it.
+        lo = min(desired, floor)
+
+        img_text = ImageText(image_size=(height, width), background=(0, 0, 0, 0))
+
+        def first_unfit(font_px: int) -> TranscriptionSegment | None:
+            for cue in cues:
+                box = self._place_cue(img_text, cue.text, font_px, cfg)
+                if box is not None and not box.fits:
+                    return cue
+            return None
+
+        # "fits" is monotonic in font size (a larger font never fits where a
+        # smaller one didn't -- box width is font-independent and box height
+        # is non-decreasing in font size), so binary-search the largest fit.
+        if first_unfit(desired) is None:
+            return _SubtitleLayout(segments, cfg, desired, True, None)
+        offender = first_unfit(lo)
+        if offender is not None:
+            error = (
+                f"Subtitle cue {offender.text!r} cannot fit in a {width}x{height} frame even at the "
+                f"minimum font size ({lo}px, min_font_scale={self.min_font_scale}). Lower min_font_scale, "
+                f"reduce max_words_per_cue, widen box_width, or render at a larger resolution."
+            )
+            return _SubtitleLayout(segments, cfg, lo, False, error)
+        low, high = lo, desired  # invariant: fits at low, not at high
+        while high - low > 1:
+            mid = (low + high) // 2
+            if first_unfit(mid) is None:
+                low = mid
+            else:
+                high = mid
+        return _SubtitleLayout(segments, cfg, low, True, None)
+
+    # ------------------------------------------------------------- timeline
+
+    def _get_active_segment(self, transcription: Transcription, timestamp: float) -> TranscriptionSegment | None:
+        for segment in transcription.segments:
+            if segment.start <= timestamp <= segment.end:
+                return segment
+        return None
+
+    def _get_active_word_index(self, segment: TranscriptionSegment, timestamp: float) -> int | None:
+        for i, word in enumerate(segment.words):
+            if word.start <= timestamp <= word.end:
+                return i
+        return None
+
+    def _create_text_overlay(
+        self,
+        video_shape: tuple[int, int, int],
+        segment: TranscriptionSegment,
+        highlight_word_index: int | None,
+        layout: _SubtitleLayout,
+        cache: dict[tuple[str, int | None], np.ndarray],
+    ) -> np.ndarray:
+        height, width = video_shape[:2]
+        cache_key = (segment.text, highlight_word_index)
+        if cache_key in cache:
+            return cache[cache_key]
+
+        cfg = layout.config
+        img_text = ImageText(image_size=(height, width), background=(0, 0, 0, 0))
+        box = self._place_cue(img_text, segment.text, layout.font_px, cfg)
+        if box is not None:
+            sp = cfg.style
+            # Absolute, pre-clamped placement (anchor=TOP_LEFT, explicit px box,
+            # margin already applied) -- the same numbers _resolve_layout used,
+            # so a layout that validated cannot raise OutOfBoundsError here.
+            img_text.write_text_box(
+                text=segment.text,
+                font_filename=self.font_filename,
+                xy=(box.x, box.y),
+                box_width=box.box_w,
+                font_size=layout.font_px,
+                font_border_size=sp.border,
+                text_color=sp.text_color,
+                background_color=sp.background_color,
+                background_padding=sp.background_padding,
+                place=cfg.text_align,
+                anchor=AnchorPoint.TOP_LEFT,
+                margin=0,
+                words=[w.word for w in segment.words],
+                highlight_word_index=highlight_word_index,
+                highlight_color=sp.highlight_color,
+                highlight_size_multiplier=sp.highlight_size_multiplier,
+                highlight_bold_font=self.highlight_bold_font,
+            )
+
+        overlay_image = img_text.img_array
+        cache[cache_key] = overlay_image
+        return overlay_image
+
+    def apply(  # type: ignore[override]
+        self,
+        video: Video,
+        transcription: Transcription | None = None,
+    ) -> Video:
+        if transcription is None:
+            raise ValueError(
+                "TranscriptionOverlay requires transcription data. "
+                "Pass it via VideoEdit.run(context={'transcription': ...}) or directly to apply()."
+            )
+
+        height, width = video.frame_shape[:2]
+        layout = self._resolve_layout(width, height, transcription)
+        if not layout.fits:
+            # Should be unreachable when the plan went through validate(); kept
+            # as defense in depth so a direct apply() still fails clearly
+            # rather than crashing mid-render in ImageText.
+            raise ValueError(layout.error)
+
+        # Per-call memo of rendered overlays, keyed by (cue text, highlighted
+        # word). Local rather than instance state so the model stays stateless
+        # and re-entrant -- a reused instance can render differently sized
+        # videos without serving a stale-resolution overlay.
+        cache: dict[tuple[str, int | None], np.ndarray] = {}
+        transformed = Transcription(segments=layout.segments, language=transcription.language)
+
+        logger.info("Applying transcription overlay (font %dpx)...", layout.font_px)
+        new_frames = []
+        for frame_index, frame in enumerate(tqdm(video.frames, desc="Transcription overlay")):
+            timestamp = frame_index / video.fps
+            active_segment = self._get_active_segment(transformed, timestamp)
+            if active_segment is None:
+                new_frames.append(frame)
+                continue
+            highlight_word_index = self._get_active_word_index(active_segment, timestamp)
+            text_overlay = self._create_text_overlay(
+                video.frame_shape, active_segment, highlight_word_index, layout, cache
+            )
+            new_frames.append(self._apply_overlay_to_frame(frame, text_overlay))
+
+        new_video = Video.from_frames(np.array(new_frames), fps=video.fps)
+        new_video.audio = video.audio
+        return new_video
+
+    def predict_metadata(
+        self,
+        meta: VideoMetadata,
+        transcription: Transcription | None = None,
+        **_context: Any,
+    ) -> VideoMetadata:
+        """Identity for metadata (shape/count preserved) -- but fail fast here
+        if the resolved subtitles cannot fit the predicted frame.
+
+        This is the backstop that closes the validate/run gap: ``VideoEdit``
+        runs it during the dry-run, so an un-fittable plan is rejected before
+        any frame/GPU work, symmetric with the timing/dimension checks. Mirrors
+        ``SilenceRemoval``: with no ``transcription`` in the validate context
+        the layout cannot be checked, so this is a no-op identity (the same
+        conditional guarantee as time re-basing).
+        """
+        if transcription is None:
+            return meta
+        layout = self._resolve_layout(meta.width, meta.height, transcription)
+        if not layout.fits:
+            raise ValueError(layout.error)
+        return meta
+
+    def _apply_overlay_to_frame(self, frame: np.ndarray, overlay: np.ndarray) -> np.ndarray:
+        frame_pil = Image.fromarray(frame)
+        overlay_pil = Image.fromarray(overlay)
+        frame_pil.paste(overlay_pil, (0, 0), overlay_pil)
+        return np.array(frame_pil)

videopython-0.33.5/src/videopython/editing/transcription_overlay.py

@@ -1,186 +0,0 @@
-"""Subtitle overlay effect.
-
-``TranscriptionOverlay`` is an :class:`Effect` that renders animated
-word-by-word subtitles onto a :class:`Video` using a word-level
-:class:`Transcription`. Rendering is delegated to ``ImageText`` from
-the sibling module.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import ClassVar, Literal
-
-import numpy as np
-from PIL import Image
-from pydantic import Field, PrivateAttr
-from tqdm import tqdm
-
-from videopython.base.image_text import AnchorPoint, ImageText, TextAlign
-from videopython.base.transcription import Transcription, TranscriptionSegment
-from videopython.base.video import Video
-from videopython.editing.operation import Effect
-
-__all__ = ["TranscriptionOverlay"]
-
-logger = logging.getLogger(__name__)
-
-
-class TranscriptionOverlay(Effect):
-    """Renders animated word-by-word subtitles with the current word highlighted.
-
-    Each word lights up in the highlight color as it is spoken, based on
-    transcription timestamps. Requires a word-level transcription, which the
-    runner supplies via the ``requires=("transcription",)`` declaration.
-    """
-
-    op: Literal["add_subtitles"] = "add_subtitles"
-    streamable: ClassVar[bool] = False
-    requires: ClassVar[tuple[str, ...]] = ("transcription",)
-
-    font_filename: str | None = Field(
-        None,
-        description="Path to a .ttf font file for rendering subtitle text, or None for the bundled default font.",
-    )
-    font_size: int = Field(40, ge=1, description="Base font size in pixels.")
-    font_border_size: int = Field(
-        2, ge=0, description="Outline thickness around each character in pixels. 0 = no outline."
-    )
-    text_color: tuple[int, int, int] = Field((255, 235, 59), description="Default text color as [R, G, B], each 0-255.")
-    background_color: tuple[int, int, int, int] | None = Field(
-        (0, 0, 0, 100),
-        description="Subtitle box background as [R, G, B, A] (0-255), or None to disable the background.",
-    )
-    background_padding: int = Field(15, ge=0, description="Pixels of space between text and background edge.")
-    position: tuple[float, float] = Field(
-        (0.5, 0.7),
-        description="Text box center as normalized (x, y). (0, 0) = top-left, (1, 1) = bottom-right.",
-    )
-    box_width: float = Field(
-        0.6, gt=0.0, le=1.0, description="Width of the text box as a fraction of frame width, in (0, 1]."
-    )
-    text_align: TextAlign = Field(
-        TextAlign.CENTER, description='Text alignment within the box: "left", "right", or "center".'
-    )
-    anchor: AnchorPoint = Field(
-        AnchorPoint.CENTER, description="Which point of the text box sits at the position coordinate."
-    )
-    margin: int | tuple[int, int, int, int] = Field(
-        20,
-        description="Space around the text box in pixels, or a [top, right, bottom, left] tuple of per-side values.",
-    )
-    highlight_color: tuple[int, int, int] = Field(
-        (76, 175, 80), description="Color for the currently spoken word as [R, G, B]."
-    )
-    highlight_size_multiplier: float = Field(
-        1.2, gt=0, description="Scale factor for the highlighted word. 1.0 = same size, 1.2 = 20% larger."
-    )
-    highlight_bold_font: str | None = Field(
-        None, description="Path to a bold .ttf font for the highlighted word, or None to use the regular font."
-    )
-    max_words_per_cue: int | None = Field(
-        5,
-        ge=1,
-        description=(
-            "Maximum words shown on screen at once. Each transcription segment is re-chunked into "
-            "cues of at most this many words, without bridging the silence gaps between segments, so "
-            "subtitles stay readable and don't linger over pauses. None preserves the source "
-            "transcription's segmentation."
-        ),
-    )
-    capitalize: bool = Field(
-        True,
-        description=(
-            "Capitalize the first letter of each sentence (first word, and words after '.', '!', '?'). "
-            "Fixes lowercase sentence starts from word-level speech-to-text. Set False to render text "
-            "exactly as transcribed."
-        ),
-    )
-
-    _overlay_cache: dict[tuple[str, int | None], np.ndarray] = PrivateAttr(default_factory=dict)
-
-    def _get_active_segment(self, transcription: Transcription, timestamp: float) -> TranscriptionSegment | None:
-        for segment in transcription.segments:
-            if segment.start <= timestamp <= segment.end:
-                return segment
-        return None
-
-    def _get_active_word_index(self, segment: TranscriptionSegment, timestamp: float) -> int | None:
-        for i, word in enumerate(segment.words):
-            if word.start <= timestamp <= word.end:
-                return i
-        return None
-
-    def _create_text_overlay(
-        self,
-        video_shape: tuple[int, int, int],
-        segment: TranscriptionSegment,
-        highlight_word_index: int | None,
-    ) -> np.ndarray:
-        height, width = video_shape[:2]
-        cache_key = (segment.text, highlight_word_index)
-        if cache_key in self._overlay_cache:
-            return self._overlay_cache[cache_key]
-
-        img_text = ImageText(image_size=(height, width), background=(0, 0, 0, 0))
-        img_text.write_text_box(
-            text=segment.text,
-            font_filename=self.font_filename,
-            xy=self.position,
-            box_width=self.box_width,
-            font_size=self.font_size,
-            font_border_size=self.font_border_size,
-            text_color=self.text_color,
-            background_color=self.background_color,
-            background_padding=self.background_padding,
-            place=self.text_align,
-            anchor=self.anchor,
-            margin=self.margin,
-            words=[w.word for w in segment.words],
-            highlight_word_index=highlight_word_index,
-            highlight_color=self.highlight_color,
-            highlight_size_multiplier=self.highlight_size_multiplier,
-            highlight_bold_font=self.highlight_bold_font,
-        )
-
-        overlay_image = img_text.img_array
-        self._overlay_cache[cache_key] = overlay_image
-        return overlay_image
-
-    def apply(  # type: ignore[override]
-        self,
-        video: Video,
-        transcription: Transcription | None = None,
-    ) -> Video:
-        if transcription is None:
-            raise ValueError(
-                "TranscriptionOverlay requires transcription data. "
-                "Pass it via VideoEdit.run(context={'transcription': ...}) or directly to apply()."
-            )
-
-        if self.max_words_per_cue is not None:
-            transcription = transcription.chunk_segments(self.max_words_per_cue)
-        if self.capitalize:
-            transcription = transcription.capitalize_sentences()
-
-        logger.info("Applying transcription overlay...")
-        new_frames = []
-        for frame_index, frame in enumerate(tqdm(video.frames, desc="Transcription overlay")):
-            timestamp = frame_index / video.fps
-            active_segment = self._get_active_segment(transcription, timestamp)
-            if active_segment is None:
-                new_frames.append(frame)
-                continue
-            highlight_word_index = self._get_active_word_index(active_segment, timestamp)
-            text_overlay = self._create_text_overlay(video.frame_shape, active_segment, highlight_word_index)
-            new_frames.append(self._apply_overlay_to_frame(frame, text_overlay))
-
-        new_video = Video.from_frames(np.array(new_frames), fps=video.fps)
-        new_video.audio = video.audio
-        return new_video
-
-    def _apply_overlay_to_frame(self, frame: np.ndarray, overlay: np.ndarray) -> np.ndarray:
-        frame_pil = Image.fromarray(frame)
-        overlay_pil = Image.fromarray(overlay)
-        frame_pil.paste(overlay_pil, (0, 0), overlay_pil)
-        return np.array(frame_pil)