videopython 0.40.0__tar.gz → 0.41.0__tar.gz

{videopython-0.40.0 → videopython-0.41.0}/PKG-INFO

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

{videopython-0.40.0 → videopython-0.41.0}/pyproject.toml

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

{videopython-0.40.0 → videopython-0.41.0}/src/videopython/base/__init__.py

@@ -14,19 +14,16 @@ from .draw_detections import DetectionStyle, class_color, draw_detections
 from .exceptions import (
     AudioError,
     AudioLoadError,
-    OutOfBoundsError,
     PlanError,
     PlanErrorCode,
     PlanRepair,
     PlanValidationError,
-    TextRenderError,
     TransformError,
     VideoError,
     VideoLoadError,
     VideoMetadataError,
     VideoPythonError,
 )
-from .image_text import AnchorPoint, ImageText, TextAlign
 from .transcription import Transcription, TranscriptionSegment, TranscriptionWord
 from .video import FrameIterator, Video, VideoMetadata
 
@@ -43,17 +40,11 @@ __all__ = [
     "AudioError",
     "AudioLoadError",
     "TransformError",
-    "TextRenderError",
-    "OutOfBoundsError",
     # Structured plan validation / repair
     "PlanError",
     "PlanErrorCode",
     "PlanValidationError",
     "PlanRepair",
-    # Text rendering primitives
-    "ImageText",
-    "TextAlign",
-    "AnchorPoint",
     # Detection overlay renderer (AI-free)
     "draw_detections",
     "DetectionStyle",

{videopython-0.40.0 → videopython-0.41.0}/src/videopython/base/exceptions.py

@@ -66,18 +66,6 @@ class TransformError(VideoPythonError):
     pass
 
 
-class TextRenderError(VideoPythonError):
-    """Base exception for text rendering errors."""
-
-    pass
-
-
-class OutOfBoundsError(TextRenderError):
-    """Raised when text would be rendered outside image bounds."""
-
-    pass
-
-
 class PlanErrorCode(str, Enum):
     """Machine-readable failure classes raised while validating a ``VideoEdit``.
 
@@ -103,7 +91,6 @@ class PlanErrorCode(str, Enum):
     # Assembly / structural.
     UNKNOWN_OP = "unknown_op"
     CONCAT_MISMATCH = "concat_mismatch"
-    SUBTITLE_UNFITTABLE = "subtitle_unfittable"
     POST_OP_REQUIRES_CONTEXT = "post_op_requires_context"
     # Streaming strictness (opt-in via strict_streaming).
     STREAMING_FALLBACK = "streaming_fallback"

{videopython-0.40.0 → videopython-0.41.0}/src/videopython/base/fonts/__init__.py

@@ -12,10 +12,18 @@ unreadable font:
 from __future__ import annotations
 
 from importlib.resources import as_file, files
+from pathlib import Path
 
 from PIL import ImageFont
 
-__all__ = ["BUNDLED_FONTS", "DEFAULT_FONT_FILENAME", "FONT_NAMES", "load_font"]
+__all__ = [
+    "BUNDLED_FONTS",
+    "BUNDLED_FONT_FAMILIES",
+    "DEFAULT_FONT_FILENAME",
+    "FONT_NAMES",
+    "bundled_fonts_dir",
+    "load_font",
+]
 
 DEFAULT_FONT_FILENAME = "DejaVuSans.ttf"
 
@@ -31,6 +39,29 @@ BUNDLED_FONTS: dict[str, str] = {
 
 FONT_NAMES: list[str] = sorted(BUNDLED_FONTS)
 
+# Registered NAME (or None for the default) -> (family name, is-bold-face),
+# exactly as declared in each file's name table. Renderers that match fonts by
+# family name -- libass via the ffmpeg ``subtitles=`` filter's ``fontsdir`` --
+# need these, not the filenames. Verified against the bundled .ttf files
+# (PIL ``ImageFont.getname()``); a test pins them.
+BUNDLED_FONT_FAMILIES: dict[str | None, tuple[str, bool]] = {
+    None: ("DejaVu Sans", False),
+    "poppins-bold": ("Poppins", True),
+    "lato-bold": ("Lato", True),
+    "anton": ("Anton", False),
+    "bebas-neue": ("Bebas Neue", False),
+}
+
+
+def bundled_fonts_dir() -> Path:
+    """Filesystem directory holding the bundled .ttf files.
+
+    For ffmpeg/libass ``fontsdir`` wiring, which needs a real directory path.
+    Standard (non-zip) installs ship the package unpacked, so the resources
+    root is a plain directory.
+    """
+    return Path(str(files(__package__)))
+
 
 def _try_truetype(path: str, font_size: int) -> ImageFont.FreeTypeFont | None:
     try:

{videopython-0.40.0 → videopython-0.41.0}/src/videopython/editing/__init__.py

@@ -1,3 +1,4 @@
+from ._ass import AnchorPoint
 from .effects import (
     Blur,
     ChromaticAberration,
@@ -83,6 +84,8 @@ __all__ = [
     # Plan runner
     "VideoEdit",
     "SegmentConfig",
+    # Subtitle placement
+    "AnchorPoint",
     # Streamability report
     "StreamabilityReport",
     "OpStreamability",

videopython-0.41.0/src/videopython/editing/_ass.py

@@ -0,0 +1,254 @@
+"""ASS (Advanced SubStation Alpha) generation for libass subtitle burn-in.
+
+Compiles a segment-local, word-level :class:`Transcription` plus the resolved
+``add_subtitles`` look into an ``.ass`` document that ffmpeg's ``subtitles=``
+filter (libass) renders natively at decode time -- zero per-frame Python.
+
+The word-level highlight (active word in the highlight color, enlarged by the
+size multiplier) cannot be expressed with ASS karaoke ``\\k`` tags -- those are
+two-state (upcoming vs spoken-and-active) while this look is three-state
+(active word only). Instead each cue is emitted as a sequence of word-state
+``Dialogue`` events tiling the cue's time range: one event per active-word
+interval with inline ``\\1c``/``\\fscx``/``\\fscy`` overrides on that word, and
+plain events for the gaps between words. Event boundaries are rounded to ASS's
+centisecond precision *before* deriving the intervals, so adjacent events tile
+exactly (no double-draw overlap, no blank gaps).
+
+Placement uses ``{\\an..\\pos(x,y)}`` on every event -- the exact box-anchor
+semantics of the Python renderer (a box anchored at a normalized position) --
+rather than margin arithmetic; ``MarginL/R`` are still set so libass wraps at
+the same ``box_width`` the Python renderer uses.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from videopython.base.transcription import Transcription
+
+__all__ = ["AnchorPoint", "AssLook", "build_ass", "escape_filter_value"]
+
+RGBColor = tuple[int, int, int]
+RGBAColor = tuple[int, int, int, int]
+
+
+class AnchorPoint(str, Enum):
+    """Which point of the subtitle box sits at the configured position."""
+
+    TOP_LEFT = "top-left"
+    TOP_CENTER = "top-center"
+    TOP_RIGHT = "top-right"
+    CENTER_LEFT = "center-left"
+    CENTER = "center"
+    CENTER_RIGHT = "center-right"
+    BOTTOM_LEFT = "bottom-left"
+    BOTTOM_CENTER = "bottom-center"
+    BOTTOM_RIGHT = "bottom-right"
+
+
+# AnchorPoint -> ASS \an numpad code (7-8-9 top, 4-5-6 middle, 1-2-3 bottom).
+_ANCHOR_TO_AN: dict[AnchorPoint, int] = {
+    AnchorPoint.TOP_LEFT: 7,
+    AnchorPoint.TOP_CENTER: 8,
+    AnchorPoint.TOP_RIGHT: 9,
+    AnchorPoint.CENTER_LEFT: 4,
+    AnchorPoint.CENTER: 5,
+    AnchorPoint.CENTER_RIGHT: 6,
+    AnchorPoint.BOTTOM_LEFT: 1,
+    AnchorPoint.BOTTOM_CENTER: 2,
+    AnchorPoint.BOTTOM_RIGHT: 3,
+}
+
+
+@dataclass(frozen=True)
+class AssLook:
+    """The resolved ``add_subtitles`` look, expressed in ASS terms.
+
+    ``font_family`` is the family name inside the font file (libass matches by
+    name table, not filename); ``bold`` selects the bold face. ``background``
+    of ``None`` means no box (BorderStyle 1); otherwise the RGBA box uses
+    libass's BorderStyle 4 (whole-event background, burn-in only) with
+    ``background_padding`` as the box padding.
+    """
+
+    font_family: str
+    bold: bool
+    font_px: int
+    text_color: RGBColor
+    highlight_color: RGBColor
+    outline_px: int
+    background: RGBAColor | None
+    background_padding: int
+    highlight_size_multiplier: float
+    position: tuple[float, float]
+    anchor: AnchorPoint
+    box_width: float
+
+
+def _ass_time(seconds: float) -> str:
+    """``H:MM:SS.cc`` -- ASS timestamps are centisecond-precision only."""
+    cs = max(0, round(seconds * 100))
+    hours, rem = divmod(cs, 360_000)
+    minutes, rem = divmod(rem, 6_000)
+    secs, centis = divmod(rem, 100)
+    return f"{hours}:{minutes:02d}:{secs:02d}.{centis:02d}"
+
+
+def _ass_color(rgb: RGBColor, opacity: int = 255) -> str:
+    """RGB + opacity (0-255, 255=opaque) -> ``&HAABBGGRR`` (ASS alpha: 00=opaque)."""
+    r, g, b = rgb
+    alpha = 255 - max(0, min(255, opacity))
+    return f"&H{alpha:02X}{b:02X}{g:02X}{r:02X}"
+
+
+def _ass_color_tag(rgb: RGBColor) -> str:
+    """RGB -> the inline override form ``&HBBGGRR&`` (no alpha, trailing ``&``)."""
+    r, g, b = rgb
+    return f"&H{b:02X}{g:02X}{r:02X}&"
+
+
+def _escape_text(text: str) -> str:
+    """Neutralize ASS markup in transcribed text.
+
+    ``{``/``}`` delimit override blocks and ``\\`` introduces escapes/breaks;
+    ASS has no escape sequence for them, so they are substituted.
+    """
+    return text.replace("\\", "/").replace("{", "(").replace("}", ")").replace("\n", " ")
+
+
+def escape_filter_value(value: str) -> str:
+    """Quote a string for use as an ffmpeg filter option value.
+
+    Escapes the option-value level metacharacters (``\\``, ``'``, ``:``) and
+    wraps the result in single quotes so the filtergraph-level separators
+    (``,``, ``;``, ``[``, ``]``) pass through untouched.
+    """
+    escaped = value.replace("\\", "\\\\").replace("'", "\\'").replace(":", "\\:")
+    return f"'{escaped}'"
+
+
+def _word_state_intervals(
+    start: float, end: float, word_spans: list[tuple[float, float]]
+) -> list[tuple[int, int, int | None]]:
+    """Tile ``[start, end)`` into centisecond intervals keyed by active word.
+
+    Returns ``(start_cs, end_cs, highlight_index)`` tuples; ``None`` means no
+    word is active (the gap before/between/after words). Boundaries are
+    rounded to centiseconds first and durations derived from the rounded
+    boundaries, so rounding error cannot accumulate into overlaps or gaps.
+    Zero-length intervals are dropped.
+    """
+    cue_start = round(start * 100)
+    cue_end = round(end * 100)
+    intervals: list[tuple[int, int, int | None]] = []
+    cursor = cue_start
+    for i, (w_start, w_end) in enumerate(word_spans):
+        if cursor >= cue_end:
+            break
+        ws = min(cue_end, max(cursor, round(w_start * 100)))
+        we = min(cue_end, round(w_end * 100))
+        if ws > cursor:
+            intervals.append((cursor, ws, None))
+            cursor = ws
+        if we > cursor:
+            intervals.append((cursor, we, i))
+            cursor = we
+    if cue_end > cursor:
+        intervals.append((cursor, cue_end, None))
+    return intervals
+
+
+def build_ass(
+    transcription: Transcription,
+    *,
+    width: int,
+    height: int,
+    look: AssLook,
+    window: tuple[float | None, float | None] | None = None,
+) -> str:
+    """Compile a segment-local transcription into a complete ASS document.
+
+    ``transcription`` must already be on the timeline of the frames the
+    ``subtitles=`` filter will see (the plan builder re-bases context onto the
+    cut segment, and the ``-ss``-before-``-i`` decode resets PTS to zero, so
+    segment-local is exactly right). ``window`` clips events to the effect's
+    active range -- the ``subtitles`` filter has no timeline (``enable=``)
+    support, so windowing happens here, at compile time.
+
+    ``PlayResX/Y`` are set to the frame size entering the filter, so one
+    script pixel is one video pixel and ``font_px`` carries over 1:1.
+    """
+    win_start = window[0] if window is not None else None
+    win_stop = window[1] if window is not None else None
+
+    primary = _ass_color(look.text_color)
+    outline_colour = _ass_color((0, 0, 0))
+    if look.background is not None:
+        border_style = 4  # libass extension: whole-event background box (burn-in only)
+        back_colour = _ass_color(look.background[:3], look.background[3])
+        shadow = look.background_padding  # BorderStyle 4 reads box padding from Shadow
+    else:
+        border_style = 1
+        back_colour = _ass_color((0, 0, 0))
+        shadow = 0
+
+    an = _ANCHOR_TO_AN[look.anchor]
+    pos_x = look.position[0] * width
+    pos_y = look.position[1] * height
+    # Margins do not place positioned events, but they still define the wrap
+    # width (PlayResX - MarginL - MarginR), which is how box_width carries over.
+    margin_h = max(0, round((1.0 - look.box_width) / 2.0 * width))
+
+    lines = [
+        "[Script Info]",
+        "ScriptType: v4.00+",
+        f"PlayResX: {width}",
+        f"PlayResY: {height}",
+        "ScaledBorderAndShadow: yes",
+        "WrapStyle: 0",
+        "",
+        "[V4+ Styles]",
+        (
+            "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, "
+            "Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, "
+            "Shadow, Alignment, MarginL, MarginR, MarginV, Encoding"
+        ),
+        (
+            f"Style: Default,{look.font_family},{look.font_px},{primary},{primary},{outline_colour},"
+            f"{back_colour},{-1 if look.bold else 0},0,0,0,100,100,0,0,{border_style},{look.outline_px},"
+            f"{shadow},{an},{margin_h},{margin_h},0,1"
+        ),
+        "",
+        "[Events]",
+        "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+    ]
+
+    scale = round(look.highlight_size_multiplier * 100)
+    highlight = _ass_color_tag(look.highlight_color)
+    placement = f"\\an{an}\\pos({pos_x:.1f},{pos_y:.1f})"
+
+    for segment in transcription.segments:
+        words = [_escape_text(w.word) for w in segment.words]
+        if not any(w.strip() for w in words):
+            continue
+        start, end = segment.start, segment.end
+        if win_start is not None:
+            start = max(start, win_start)
+        if win_stop is not None:
+            end = min(end, win_stop)
+        if end <= start:
+            continue
+        spans = [(w.start, w.end) for w in segment.words]
+        for start_cs, end_cs, hl in _word_state_intervals(start, end, spans):
+            if hl is None:
+                text = " ".join(words)
+            else:
+                marked = f"{{\\1c{highlight}\\fscx{scale}\\fscy{scale}}}{words[hl]}{{\\r}}"
+                text = " ".join([*words[:hl], marked, *words[hl + 1 :]])
+            lines.append(
+                f"Dialogue: 0,{_ass_time(start_cs / 100)},{_ass_time(end_cs / 100)},Default,,0,0,0,,"
+                f"{{{placement}}}{text}"
+            )
+
+    return "\n".join(lines) + "\n"

{videopython-0.40.0 → videopython-0.41.0}/src/videopython/editing/operation.py

@@ -31,8 +31,9 @@ Subclass contract::
 from __future__ import annotations
 
 import copy
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
+from pathlib import Path
 from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Literal, NamedTuple, Union, get_args, get_origin
 
 import numpy as np
@@ -99,11 +100,23 @@ class BoundedTimeField(NamedTuple):
 
 @dataclass(frozen=True)
 class FilterCtx:
-    """Current pipeline state (post-prior-ops) when compiling to ffmpeg."""
+    """Current pipeline state (post-prior-ops) when compiling to ffmpeg.
+
+    ``context`` carries the resolved, segment-local runtime context (the same
+    re-based values ``streaming_init`` receives) so a context-consuming op can
+    compile itself into the filter chain (e.g. ``add_subtitles`` consuming the
+    transcription to write an ``.ass`` file). Empty when no context applies.
+
+    ``owned_files`` collects temp files a compilation creates (the ``.ass``
+    file a ``subtitles=`` entry references); the plan runner deletes them once
+    streaming finishes or the plan is abandoned.
+    """
 
     width: int
     height: int
     fps: float
+    context: dict[str, Any] = field(default_factory=dict)
+    owned_files: list[Path] = field(default_factory=list)
 
 
 LLM_HIDDEN_KEY = "llm_hidden"
@@ -391,6 +404,20 @@ class Effect(Operation):
         description="Time window for the effect in seconds. Omit to apply across the full duration.",
     )
 
+    @property
+    def compiles_to_filter(self) -> bool:
+        """Whether this effect joins the decode filter chain instead of scheduling per-frame Python.
+
+        When True, the streaming plan builder calls :meth:`to_ffmpeg_filter`
+        (with the segment's resolved context on the :class:`FilterCtx`) and, if
+        it compiles, appends the result to the vf chain at this op's plan
+        position -- the Filter class of the streaming contract. Instance-level
+        rather than a ClassVar because it may depend on field values (e.g.
+        ``add_subtitles``'s ``renderer``). False by default: effects normally
+        stream via ``streaming_init``/``process_frame``.
+        """
+        return False
+
     def apply(self, video: Video, **context: Any) -> Video:
         from videopython.base.video import Video as _Video
 

{videopython-0.40.0 → videopython-0.41.0}/src/videopython/editing/streaming.py

@@ -122,12 +122,22 @@ def analyze_streamability(
     entries: list[OpStreamability] = []
     for i, ops in enumerate(segment_operations):
         seen_effect = False
+        seen_encode_filter = False
         for j, op in enumerate(ops):
             location = f"segments[{i}].operations[{j}]"
             if isinstance(op, Effect):
-                if op.streamable:
-                    entries.append(OpStreamability(location, op.op, StreamingClass.FRAME_EFFECT))
-                else:
+                if op.streamable and op.compiles_to_filter:
+                    # Filter-class effect (add_subtitles): joins the decode
+                    # filter chain at this plan position -- or the encode
+                    # chain when frame effects precede it -- so it streams in
+                    # plan order either way and does not block later
+                    # transforms the way a scheduled frame effect does. The
+                    # builder mirrors this exactly.
+                    entries.append(OpStreamability(location, op.op, StreamingClass.FILTER))
+                    if seen_effect:
+                        seen_encode_filter = True
+                    continue
+                if not op.streamable:
                     entries.append(
                         OpStreamability(
                             location,
@@ -136,6 +146,21 @@ def analyze_streamability(
                             reason="effect has no streaming implementation (streamable=False)",
                         )
                     )
+                elif seen_encode_filter:
+                    entries.append(
+                        OpStreamability(
+                            location,
+                            op.op,
+                            StreamingClass.EAGER,
+                            reason=(
+                                "frame effect follows burned-in subtitles (an encode-stage filter) in "
+                                "plan order; the filter runs after every frame effect, so plan order "
+                                "cannot be preserved -- move the effect before the subtitles to stream"
+                            ),
+                        )
+                    )
+                else:
+                    entries.append(OpStreamability(location, op.op, StreamingClass.FRAME_EFFECT))
                 seen_effect = True
             elif op.requires:
                 entries.append(
@@ -198,6 +223,18 @@ def analyze_streamability(
                     ),
                 )
             )
+        elif isinstance(op, Effect) and op.streamable and op.compiles_to_filter:
+            entries.append(
+                OpStreamability(
+                    location,
+                    op.op,
+                    StreamingClass.EAGER,
+                    reason=(
+                        "filter-class post-operations cannot fold into the segment schedule -- "
+                        "move the op into the segment to stream"
+                    ),
+                )
+            )
         elif isinstance(op, Effect) and op.streamable:
             entries.append(OpStreamability(location, op.op, StreamingClass.FRAME_EFFECT))
         elif isinstance(op, Effect):
@@ -240,7 +277,17 @@ class EffectScheduleEntry:
 
 @dataclass
 class StreamingSegmentPlan:
-    """Describes how to stream-process one video segment."""
+    """Describes how to stream-process one video segment.
+
+    ``vf_filters`` run at decode time, before every scheduled effect;
+    ``post_vf_filters`` run at encode time (``FrameEncoder``'s ``-vf``),
+    after every scheduled effect -- where a filter-class op that follows
+    frame effects in plan order lands (e.g. ``[fade, add_subtitles]``).
+
+    ``owned_temp_files`` are compile-time artifacts referenced by the filter
+    chains (e.g. the ``.ass`` file behind a ``subtitles=`` entry); the runner
+    deletes them once streaming finishes or the plan is abandoned.
+    """
 
     source_path: Path
     start_second: float
@@ -250,6 +297,8 @@ class StreamingSegmentPlan:
     output_height: int
     vf_filters: list[str] = field(default_factory=list)
     effect_schedule: list[EffectScheduleEntry] = field(default_factory=list)
+    post_vf_filters: list[str] = field(default_factory=list)
+    owned_temp_files: list[Path] = field(default_factory=list)
 
 
 class FrameEncoder:
@@ -268,6 +317,7 @@ class FrameEncoder:
         format: str = "mp4",
         preset: str = "medium",
         crf: int = 23,
+        vf_filters: list[str] | None = None,
     ):
         self._output_path = output_path
         self._width = width
@@ -277,6 +327,7 @@ class FrameEncoder:
         self._format = format
         self._preset = preset
         self._crf = crf
+        self._vf_filters = vf_filters or []
         self._stack: ExitStack | None = None
         self._process: subprocess.Popen[bytes] | None = None
 
@@ -302,6 +353,12 @@ class FrameEncoder:
         if self._audio_path is not None:
             cmd.extend(["-i", str(self._audio_path)])
 
+        if self._vf_filters:
+            # Encode-stage filters: run after every per-frame effect (frames
+            # arrive via stdin already processed). The rawvideo pipe's PTS
+            # start at zero, so time-based filters (subtitles=) see the same
+            # segment-local timeline the decode side uses.
+            cmd.extend(["-vf", ",".join(self._vf_filters)])
         cmd.extend(
             [
                 "-c:v",
@@ -424,6 +481,7 @@ def stream_segment(
                 format=format,
                 preset=preset,
                 crf=crf,
+                vf_filters=plan.post_vf_filters,
             ) as encoder:
                 logger.info("Streaming frames...")
                 frame_count = 0