videopython 0.38.0__tar.gz → 0.40.0__tar.gz

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

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

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

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

{videopython-0.38.0 → videopython-0.40.0}/src/videopython/ai/effects.py

@@ -9,7 +9,7 @@ AI-free renderer in :mod:`videopython.base.draw_detections`.
 
 from __future__ import annotations
 
-from typing import ClassVar, Literal
+from typing import Any, ClassVar, Literal
 
 import numpy as np
 from pydantic import Field, PrivateAttr
@@ -97,7 +97,7 @@ class ObjectDetectionOverlay(Effect):
                 backend=self.backend,
             )
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._last = []
         self._init_detector()
 

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

@@ -105,6 +105,8 @@ class PlanErrorCode(str, Enum):
     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 +115,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 +127,7 @@ class PlanError:
     value: float | None = None
     limit: float | None = None
     predicted_duration: float | None = None
+    detail: str | None = None
 
 
 @dataclass

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

@@ -22,6 +22,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 +83,8 @@ __all__ = [
     # Plan runner
     "VideoEdit",
     "SegmentConfig",
+    # Streamability report
+    "StreamabilityReport",
+    "OpStreamability",
+    "StreamingClass",
 ]

{videopython-0.38.0 → videopython-0.40.0}/src/videopython/editing/effects.py

@@ -109,7 +109,7 @@ class FullImageOverlay(Effect):
         img_pil.paste(overlay_pil, (0, 0), overlay_pil)
         return np.array(img_pil)
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._load_overlay()
         self._stream_total = total_frames
         self._stream_fade_frames = round(self.fade_time * fps) if self.fade_time > 0 else 0
@@ -121,7 +121,7 @@ class FullImageOverlay(Effect):
         fade_alpha = 1.0 if dist_from_end >= self._stream_fade_frames else dist_from_end / self._stream_fade_frames
         return self._overlay_frame(frame, fade_alpha)
 
-    def _apply(self, video: Video) -> Video:
+    def _apply(self, video: Video, **_context: Any) -> Video:
         overlay = self._load_overlay()
         if video.frame_shape != overlay[:, :, :3].shape:
             raise ValueError(f"Mismatch of overlay shape `{overlay.shape}` with video shape: `{video.frame_shape}`!")
@@ -181,7 +181,7 @@ class Blur(Effect):
             ratios = np.linspace(1.0, 1 / n_frames, n_frames)
         return base_sigma * np.sqrt(np.maximum(1, np.round(ratios * self.iterations)))
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_sigmas = self._compute_sigmas(total_frames)
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -215,7 +215,7 @@ class Zoom(Effect):
             crop_w, crop_h = crop_w[::-1], crop_h[::-1]
         return np.stack([crop_w, crop_h], axis=1)
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_crops = self._crop_sizes(total_frames, width, height)
         self._stream_width = width
         self._stream_height = height
@@ -317,7 +317,7 @@ class Vignette(Effect):
         mask = 1.0 - np.clip(distance - 0.5, 0, 1) * 2 * self.strength
         return mask.astype(np.float32)
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         if self._mask is None or self._mask.shape != (height, width):
             self._mask = self._create_mask(height, width)
         self._stream_mask_3d = self._mask[:, :, np.newaxis]
@@ -326,7 +326,7 @@ class Vignette(Effect):
         assert self._stream_mask_3d is not None
         return (frame.astype(np.float32) * self._stream_mask_3d).astype(np.uint8)
 
-    def _apply(self, video: Video) -> Video:
+    def _apply(self, video: Video, **_context: Any) -> Video:
         logger.info("Applying vignette effect...")
         height, width = video.frame_shape[:2]
         if self._mask is None or self._mask.shape != (height, width):
@@ -404,7 +404,7 @@ class KenBurns(Effect):
             regions[i] = (x, y, crop_w, crop_h)
         return regions
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_regions = self._precompute_regions(total_frames, width, height)
         self._stream_target_w = width
         self._stream_target_h = height
@@ -461,7 +461,7 @@ class Fade(Effect):
             alpha[-ramp:] = np.minimum(alpha[-ramp:], _compute_curve(t, self.curve))
         return alpha
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_alpha = self._fade_envelope(total_frames, fps)
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -649,7 +649,7 @@ class _AnchoredOverlay(Effect):
         rgb = region[:, :, :3].astype(np.float32)
         return alpha, rgb, (dst_y, dst_x, paste_h, paste_w)
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         params = self._blend_params(width, height)
         if params is None:
             self._stream_noop = True
@@ -966,7 +966,7 @@ class Shake(Effect):
         M = np.array([[1.0, 0.0, dx], [0.0, 1.0, dy]], dtype=np.float32)
         return cv2.warpAffine(frame, M, (w, h), borderMode=cv2.BORDER_REFLECT)
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_offsets = self._compute_offsets(total_frames, fps)
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -1028,7 +1028,7 @@ class PunchIn(Effect):
         cropped = frame[y : y + crop_h, x : x + crop_w]
         return cv2.resize(cropped, (width, height), interpolation=cv2.INTER_LINEAR)
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_zooms = self._zoom_envelope(total_frames)
         self._stream_width = width
         self._stream_height = height
@@ -1091,7 +1091,7 @@ class Flash(Effect):
             alpha[:] = self.peak_alpha
         return alpha
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_alpha = self._alpha_envelope(total_frames)
         self._stream_color = np.array(self.color, dtype=np.float32)
 
@@ -1163,7 +1163,7 @@ class ChromaticAberration(Effect):
             out[:, :, 2] = cv2.remap(b, b_map_x, b_map_y, cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE)
         return out
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         if self.mode == "radial":
             self._stream_maps = self._build_radial_maps(width, height)
 
@@ -1226,7 +1226,7 @@ class Glitch(Effect):
 
         return out
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         return None
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -1266,7 +1266,7 @@ class FilmGrain(Effect):
             noise = rng.standard_normal((h, w, 3), dtype=np.float32) * amp
         return np.clip(frame.astype(np.float32) + noise, 0, 255).astype(np.uint8)
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         return None
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -1308,7 +1308,7 @@ class Sharpen(Effect):
         sharpened = cv2.addWeighted(frame, 1.0 + self.amount, blurred, -self.amount, 0)
         return sharpened
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         return None
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -1355,7 +1355,7 @@ class Pixelate(Effect):
         frame[y : y + h, x : x + w] = big
         return frame
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_region_px = self._resolve_region(width, height)
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -1410,7 +1410,7 @@ class MirrorFlip(Effect):
             out[:half, :] = out[h - half :, :][::-1, :]
         return out
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         return None
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
@@ -1470,7 +1470,7 @@ class Kaleidoscope(Effect):
             borderMode=cv2.BORDER_REFLECT,
         )
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         self._stream_map_x, self._stream_map_y = self._build_maps(width, height)
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:

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

@@ -397,12 +397,12 @@ class Effect(Operation):
         original_shape = video.video_shape
 
         if self.window is None or (self.window.start is None and self.window.stop is None):
-            result = self._apply(video)
+            result = self._apply(video, **context)
         else:
             start_s, stop_s = self._resolved_window(video.total_seconds)
             start_f = round(start_s * video.fps)
             end_f = round(stop_s * video.fps)
-            inner = self._apply(video[start_f:end_f])
+            inner = self._apply(video[start_f:end_f], **context)
             old_audio = video.audio
             result = _Video.from_frames(
                 np.r_["0,2", video.frames[:start_f], inner.frames, video.frames[end_f:]],
@@ -436,23 +436,30 @@ class Effect(Operation):
             raise ValueError(f"Effect stop ({stop_s}) must be >= start ({start_s})")
         return start_s, stop_s
 
-    def _apply(self, video: Video) -> Video:
+    def _apply(self, video: Video, **context: Any) -> Video:
         """Apply the effect to ``video`` in memory by replaying the streaming path.
 
         Runs :meth:`streaming_init` once, then :meth:`process_frame` over every
         frame in order -- the same logic streaming uses, so eager and streaming
-        cannot drift. Subclasses that need a genuinely different eager path
-        (extra validation, batched vectorisation) override this.
+        cannot drift. ``context`` carries resolved ``requires`` values through
+        to :meth:`streaming_init`, mirroring the streaming scheduler.
+        Subclasses that need a genuinely different eager path (extra
+        validation, batched vectorisation) override this.
         """
         height, width = video.frame_shape[:2]
-        self.streaming_init(len(video.frames), video.fps, width, height)
+        self.streaming_init(len(video.frames), video.fps, width, height, **context)
         for i in tqdm(range(len(video.frames)), desc=type(self).__name__):
             video.frames[i] = self.process_frame(video.frames[i], i)
         return video
 
-    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         """Hook for per-stream precomputation (per-frame alphas, sigma curves...).
 
+        ``_context`` carries resolved ``requires`` values for context-aware
+        effects (e.g. ``transcription=...`` for ``TranscriptionOverlay``),
+        already re-based onto the local timeline by the runner. Effects that
+        declare no ``requires`` are always called without context kwargs.
+
         Default: no-op. Override in subclasses that need it.
         """