videopython 0.39.0__tar.gz → 0.41.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.39.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.39.0 → videopython-0.41.0}/pyproject.toml

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

{videopython-0.39.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.39.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,8 +91,9 @@ 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"
 
 
 @dataclass
@@ -113,6 +102,9 @@ class PlanError:
 
     ``location`` is a path into the plan (e.g. ``'segments[1].operations[0]'``);
     the remaining fields are populated when meaningful for the ``code``.
+    ``detail`` carries a short human-readable cause when the code alone is not
+    actionable (e.g. *why* an op forces the eager fallback) -- prose meant for
+    LLM refine-loop feedback, not for branching.
     """
 
     code: PlanErrorCode
@@ -122,6 +114,7 @@ class PlanError:
     value: float | None = None
     limit: float | None = None
     predicted_duration: float | None = None
+    detail: str | None = None
 
 
 @dataclass

{videopython-0.39.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.39.0 → videopython-0.41.0}/src/videopython/editing/__init__.py

@@ -1,3 +1,4 @@
+from ._ass import AnchorPoint
 from .effects import (
     Blur,
     ChromaticAberration,
@@ -22,6 +23,7 @@ from .effects import (
     Zoom,
 )
 from .operation import FilterCtx, OpCategory, Operation, TimeRange
+from .streaming import OpStreamability, StreamabilityReport, StreamingClass
 from .transcription_overlay import SubtitleRegion, SubtitleStyle, TranscriptionOverlay
 from .transforms import (
     Crop,
@@ -82,4 +84,10 @@ __all__ = [
     # Plan runner
     "VideoEdit",
     "SegmentConfig",
+    # Subtitle placement
+    "AnchorPoint",
+    # Streamability report
+    "StreamabilityReport",
+    "OpStreamability",
+    "StreamingClass",
 ]

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.39.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