videopython 0.31.0__tar.gz → 0.31.3__tar.gz

{videopython-0.31.0 → videopython-0.31.3}/PKG-INFO

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

{videopython-0.31.0 → videopython-0.31.3}/pyproject.toml

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

{videopython-0.31.0 → videopython-0.31.3}/src/videopython/ai/dubbing/remux.py

@@ -4,13 +4,15 @@ from __future__ import annotations
 
 import io
 import logging
-import subprocess
 import wave
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import numpy as np
 
+from videopython.base import _ffmpeg
+from videopython.base.exceptions import FFmpegRunError
+
 if TYPE_CHECKING:
     from videopython.base.audio import Audio
 
@@ -95,9 +97,10 @@ def replace_audio_stream(
     ]
 
     logger.info("replace_audio_stream: %s + %s -> %s", video_path, audio_path, output_path)
-    result = subprocess.run(cmd, capture_output=True)
-    if result.returncode != 0:
-        raise RemuxError(f"ffmpeg failed (exit {result.returncode}): {result.stderr.decode(errors='replace')}")
+    try:
+        _ffmpeg.run(cmd)
+    except FFmpegRunError as e:
+        raise RemuxError(str(e)) from e
 
 
 def replace_audio_stream_from_audio(
@@ -175,7 +178,7 @@ def replace_audio_stream_from_audio(
         len(wav_bytes),
         output_path,
     )
-    process = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
-    _, stderr = process.communicate(wav_bytes)
-    if process.returncode != 0:
-        raise RemuxError(f"ffmpeg failed (exit {process.returncode}): {stderr.decode(errors='replace')}")
+    try:
+        _ffmpeg.run(cmd, stdin=wav_bytes)
+    except FFmpegRunError as e:
+        raise RemuxError(str(e)) from e

{videopython-0.31.0 → videopython-0.31.3}/src/videopython/ai/transforms.py

@@ -11,17 +11,13 @@ from pydantic import Field
 from tqdm import tqdm
 
 from videopython.ai.understanding.faces import FaceTracker
+from videopython.base._dimensions import floor_to_even
 from videopython.base.operation import OpCategory, Operation
 from videopython.base.video import Video
 
 logger = logging.getLogger(__name__)
 
 
-def _make_even(value: int) -> int:
-    """Round down to nearest even number for H.264 compatibility."""
-    return value - (value % 2)
-
-
 __all__ = [
     "FaceTrackingCrop",
 ]
@@ -105,17 +101,17 @@ class FaceTrackingCrop(Operation):
         frame_ratio = frame_w / frame_h
 
         if target_ratio < frame_ratio:
-            crop_h = _make_even(frame_h)
-            crop_w = _make_even(int(crop_h * target_ratio))
+            crop_h = floor_to_even(frame_h)
+            crop_w = floor_to_even(int(crop_h * target_ratio))
         else:
-            crop_w = _make_even(frame_w)
-            crop_h = _make_even(int(crop_w / target_ratio))
+            crop_w = floor_to_even(frame_w)
+            crop_h = floor_to_even(int(crop_w / target_ratio))
 
         min_face_dim = max(face_w * frame_w, face_h * frame_h)
         min_crop_dim = min_face_dim * (1 + 2 * self.padding)
         if crop_w < min_crop_dim * target_ratio:
-            crop_w = _make_even(min(int(min_crop_dim * target_ratio), frame_w))
-            crop_h = _make_even(min(int(crop_w / target_ratio), frame_h))
+            crop_w = floor_to_even(min(int(min_crop_dim * target_ratio), frame_w))
+            crop_h = floor_to_even(min(int(crop_w / target_ratio), frame_h))
 
         if center_position is None:
             center_position = self._apply_framing_offset(face_cx, face_cy, face_h)
@@ -141,11 +137,11 @@ 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 = _make_even(h)
-            out_w = _make_even(int(out_h * target_ratio))
+            out_h = floor_to_even(h)
+            out_w = floor_to_even(int(out_h * target_ratio))
         else:
-            out_w = _make_even(w)
-            out_h = _make_even(int(out_w / target_ratio))
+            out_w = floor_to_even(w)
+            out_h = floor_to_even(int(out_w / target_ratio))
 
         default_x = (w - out_w) // 2
         default_y = (h - out_h) // 2

{videopython-0.31.0 → videopython-0.31.3}/src/videopython/ai/video_analysis.py

@@ -5,7 +5,6 @@ import json
 import logging
 import math
 import re
-import subprocess
 import time
 from collections.abc import Callable, Iterator
 from concurrent.futures import ThreadPoolExecutor
@@ -26,6 +25,7 @@ from videopython.ai.understanding import (
     SemanticSceneDetector,
 )
 from videopython.ai.understanding.faces import FaceTracker
+from videopython.base import _ffmpeg
 from videopython.base.audio import Audio
 from videopython.base.description import (
     AudioClassification,
@@ -34,6 +34,7 @@ from videopython.base.description import (
     SceneBoundary,
     SceneDescription,
 )
+from videopython.base.exceptions import FFmpegProbeError
 from videopython.base.text.transcription import Transcription
 from videopython.base.video import Video, VideoMetadata, extract_frames_at_times
 
@@ -1032,21 +1033,9 @@ class VideoAnalyzer:
         if path is None:
             return {}
 
-        cmd = [
-            "ffprobe",
-            "-v",
-            "error",
-            "-show_entries",
-            "format_tags:stream_tags",
-            "-of",
-            "json",
-            str(path),
-        ]
-
         try:
-            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
-            payload = json.loads(result.stdout)
-        except (subprocess.CalledProcessError, json.JSONDecodeError, OSError):
+            payload = _ffmpeg.probe(path, extra_args=["-show_entries", "format_tags:stream_tags"])
+        except (FFmpegProbeError, OSError):
             return {}
 
         tags: dict[str, str] = {}

videopython-0.31.3/src/videopython/base/_dimensions.py

@@ -0,0 +1,41 @@
+"""Pure helpers for video dimension math.
+
+Centralises the libx264+yuv420p even-dimension constraint and the
+two "round to even" calculations that previously lived (with subtly
+different semantics) in ``base/video.py``, ``ai/transforms.py``, and
+``base/transforms.py``.
+"""
+
+from __future__ import annotations
+
+
+def round_to_even(value: int | float) -> int:
+    """Round a dimension to the nearest even integer (minimum 2).
+
+    Use this when computing a target dimension from a ratio or scale
+    factor and either direction (up or down) is acceptable.
+    """
+    return max(2, int(round(float(value) / 2.0) * 2))
+
+
+def floor_to_even(value: int | float) -> int:
+    """Round a dimension down to the next even integer (minimum 2).
+
+    Use this when the result must not exceed the source region — e.g.
+    cropping, where rounding up would read past the frame edge.
+    """
+    v = int(value)
+    return max(2, v - (v % 2))
+
+
+def require_even(width: int, height: int) -> None:
+    """Guard for libx264+yuv420p output, which rejects odd dimensions.
+
+    Raises:
+        ValueError: If either dimension is odd.
+    """
+    if width % 2 != 0 or height % 2 != 0:
+        raise ValueError(
+            "libx264 with yuv420p requires even frame dimensions. "
+            f"Got {width}x{height}. Resize, crop, or pad to even width and height before saving."
+        )

videopython-0.31.3/src/videopython/base/_ffmpeg.py

@@ -0,0 +1,152 @@
+"""Internal wrappers for ffmpeg / ffprobe subprocess calls.
+
+Centralises subprocess invocation patterns so that every call site shares
+the same flag boilerplate, JSON parsing, and failure translation. Public
+modules should keep raising their own domain exceptions (VideoLoadError,
+AudioLoadError, etc.) and call into the helpers here, mapping
+``FFmpegError`` to whichever public exception they document.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator, Sequence
+
+from videopython.base.exceptions import FFmpegProbeError, FFmpegRunError
+
+
+def run(cmd: Sequence[str], *, stdin: bytes | None = None) -> bytes:
+    """Run a blocking ffmpeg/ffprobe command and return stdout.
+
+    Centralises non-zero exit handling so callers can map a single
+    ``FFmpegRunError`` to their own domain exception.
+
+    Args:
+        cmd: Full argv, starting with ``"ffmpeg"`` or ``"ffprobe"``.
+        stdin: Optional bytes to feed to the process's stdin (used by
+            the stdin-piped remux variant).
+
+    Returns:
+        Process stdout bytes (usually empty for muxing/concat commands).
+
+    Raises:
+        FFmpegRunError: On non-zero exit or missing binary.
+    """
+    try:
+        result = subprocess.run(cmd, capture_output=True, input=stdin)
+    except FileNotFoundError as e:
+        raise FFmpegRunError(f"binary not found on PATH: {cmd[0]}") from e
+    if result.returncode != 0:
+        raise FFmpegRunError(f"ffmpeg failed (exit {result.returncode}): {result.stderr.decode(errors='replace')}")
+    return result.stdout
+
+
+def probe(path: str | Path, *, extra_args: Sequence[str] | None = None) -> dict:
+    """Run ffprobe and return the parsed JSON payload.
+
+    Args:
+        path: Path to the media file.
+        extra_args: Optional extra ffprobe flags inserted before ``-print_format``.
+            Defaults to ``("-show_streams", "-show_format")`` when omitted,
+            which mirrors the historical "everything" probe used by Audio.
+
+    Returns:
+        The decoded ffprobe JSON payload.
+
+    Raises:
+        FFmpegProbeError: On non-zero exit, JSON decode failure, or missing
+            ffprobe binary.
+    """
+    args = list(extra_args) if extra_args is not None else ["-show_streams", "-show_format"]
+    cmd = ["ffprobe", "-v", "error", *args, "-print_format", "json", str(path)]
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    except subprocess.CalledProcessError as e:
+        raise FFmpegProbeError(f"ffprobe error: {e.stderr}") from e
+    except FileNotFoundError as e:
+        raise FFmpegProbeError("ffprobe binary not found on PATH") from e
+
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as e:
+        raise FFmpegProbeError(f"Error parsing ffprobe output: {e}") from e
+
+
+def _terminate(proc: subprocess.Popen, *, timeout: float = 5) -> None:
+    """Terminate a still-running process, escalating to kill after ``timeout``."""
+    if proc.poll() is None:
+        proc.terminate()
+        try:
+            proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+
+
+@contextmanager
+def popen_decode(cmd: Sequence[str], *, bufsize: int = -1) -> Iterator[subprocess.Popen]:
+    """Context manager wrapping an ffmpeg decode process.
+
+    Yields a Popen with ``stdout=PIPE`` and ``stderr=DEVNULL``. Callers
+    read raw bytes from ``proc.stdout``. On exit, the process is
+    terminated (with kill fallback) and stdout is closed.
+
+    Args:
+        cmd: Full ffmpeg argv. The output target is typically ``pipe:1``.
+        bufsize: Forwarded to ``subprocess.Popen``. Use a large value
+            (e.g. ``10**8``) for batched reads or a frame-sized value
+            for streaming reads.
+    """
+    proc = subprocess.Popen(
+        list(cmd),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        bufsize=bufsize,
+    )
+    try:
+        yield proc
+    finally:
+        _terminate(proc)
+        if proc.stdout is not None and not proc.stdout.closed:
+            proc.stdout.close()
+
+
+@contextmanager
+def popen_encode(cmd: Sequence[str]) -> Iterator[subprocess.Popen]:
+    """Context manager wrapping an ffmpeg encode process via stdin pipe.
+
+    Yields a Popen with ``stdin=PIPE``, ``stdout=DEVNULL``, and
+    ``stderr=PIPE``. Callers write raw frames to ``proc.stdin``.
+
+    On clean exit, stdin and stderr are drained via ``communicate()``
+    and ``FFmpegRunError`` is raised if ffmpeg returns non-zero. On
+    exception exit, the process is killed and the caller's exception
+    propagates unmodified.
+    """
+    proc = subprocess.Popen(
+        list(cmd),
+        stdin=subprocess.PIPE,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+    )
+    try:
+        yield proc
+    except BaseException:
+        if proc.poll() is None:
+            proc.kill()
+            proc.wait()
+        for pipe in (proc.stdin, proc.stderr):
+            if pipe is not None and not pipe.closed:
+                try:
+                    pipe.close()
+                except Exception:
+                    pass
+        raise
+
+    _, stderr = proc.communicate()
+    if proc.returncode != 0:
+        raise FFmpegRunError(f"ffmpeg failed (exit {proc.returncode}): {stderr.decode(errors='replace')}")

videopython-0.31.3/src/videopython/base/_video_io.py

@@ -0,0 +1,289 @@
+"""Internal ffmpeg decode/encode helpers for ``Video``.
+
+Holds the subprocess-heavy bodies of ``Video.from_path`` (decode an
+ffmpeg pipe into a frame array) and ``Video.save`` (stream a frame
+array to an ffmpeg encode). Keeping these out of ``base/video.py``
+lets the data class stay focused on the in-memory frame/audio
+container.
+
+Public callers should keep using ``Video.from_path`` and
+``Video.save``; this module is internal scaffolding.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import uuid
+import warnings
+from pathlib import Path
+from typing import Literal, get_args
+
+import numpy as np
+
+from videopython.base import _ffmpeg
+from videopython.base._dimensions import require_even
+from videopython.base.audio import Audio
+from videopython.base.exceptions import (
+    AudioLoadError,
+    FFmpegRunError,
+    VideoLoadError,
+    VideoMetadataError,
+)
+
+ALLOWED_VIDEO_FORMATS = Literal["mp4", "avi", "mov", "mkv", "webm"]
+ALLOWED_VIDEO_PRESETS = Literal[
+    "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow"
+]
+
+# Pre-allocation safety margin for the decode frame array.
+FRAME_BUFFER_MULTIPLIER = 1.1
+FRAME_BUFFER_PADDING = 10
+
+
+def decode_video(
+    path: str,
+    *,
+    read_batch_size: int = 100,
+    start_second: float | None = None,
+    end_second: float | None = None,
+    fps: float | None = None,
+    width: int | None = None,
+    height: int | None = None,
+) -> tuple[np.ndarray, float, Audio]:
+    """Decode a video file into an RGB frame array plus its audio track.
+
+    Returns ``(frames, fps, audio)`` ready to feed straight into the
+    ``Video`` constructor. Silent audio is substituted when the source
+    has no usable audio stream.
+
+    Raises:
+        FileNotFoundError: If ``path`` does not exist (via VideoMetadata).
+        VideoLoadError: On ffmpeg failure or unreadable I/O.
+        VideoMetadataError: When ffprobe cannot describe the source.
+    """
+    from videopython.base.video import VideoMetadata
+
+    try:
+        metadata = VideoMetadata.from_path(path)
+
+        out_width = width if width is not None else metadata.width
+        out_height = height if height is not None else metadata.height
+        out_fps = fps if fps is not None else metadata.fps
+        total_duration = metadata.total_seconds
+
+        if start_second is not None and start_second < 0:
+            raise ValueError("start_second must be non-negative")
+        if end_second is not None and end_second > total_duration:
+            raise ValueError(f"end_second ({end_second}) exceeds video duration ({total_duration})")
+        if start_second is not None and end_second is not None and start_second >= end_second:
+            raise ValueError("start_second must be less than end_second")
+
+        if start_second is not None and end_second is not None:
+            segment_duration = end_second - start_second
+        elif end_second is not None:
+            segment_duration = end_second
+        elif start_second is not None:
+            segment_duration = total_duration - start_second
+        else:
+            segment_duration = total_duration
+
+        estimated_bytes = int(segment_duration * out_fps) * out_height * out_width * 3
+        estimated_gb = estimated_bytes / (1024**3)
+        if estimated_gb > 10:
+            warnings.warn(
+                f"Loading this video will use ~{estimated_gb:.1f}GB of RAM. "
+                f"For large videos, consider using FrameIterator for memory-efficient streaming.",
+                ResourceWarning,
+                stacklevel=2,
+            )
+
+        ffmpeg_cmd = ["ffmpeg"]
+
+        if start_second is not None:
+            ffmpeg_cmd.extend(["-ss", str(start_second)])
+
+        ffmpeg_cmd.extend(["-i", path])
+
+        if end_second is not None and start_second is not None:
+            duration = end_second - start_second
+            ffmpeg_cmd.extend(["-t", str(duration)])
+        elif end_second is not None:
+            ffmpeg_cmd.extend(["-t", str(end_second)])
+
+        vf_filters: list[str] = []
+        if width is not None or height is not None:
+            vf_filters.append(f"scale={out_width}:{out_height}")
+        if fps is not None and fps != metadata.fps:
+            vf_filters.append(f"fps={out_fps}")
+        if vf_filters:
+            ffmpeg_cmd.extend(["-vf", ",".join(vf_filters)])
+
+        ffmpeg_cmd.extend(
+            [
+                "-f",
+                "rawvideo",
+                "-pix_fmt",
+                "rgb24",
+                "-vcodec",
+                "rawvideo",
+                "-avoid_negative_ts",
+                "make_zero",
+                "-y",
+                "pipe:1",
+            ]
+        )
+
+        frame_size = out_width * out_height * 3
+        estimated_frames = int(segment_duration * out_fps * FRAME_BUFFER_MULTIPLIER) + FRAME_BUFFER_PADDING
+
+        frames = np.empty((estimated_frames, out_height, out_width, 3), dtype=np.uint8)
+        frames_read = 0
+
+        with _ffmpeg.popen_decode(ffmpeg_cmd, bufsize=10**8) as process:
+            while frames_read < estimated_frames:
+                remaining_frames = estimated_frames - frames_read
+                batch_size = min(read_batch_size, remaining_frames)
+
+                batch_data = process.stdout.read(frame_size * batch_size)  # type: ignore[union-attr]
+                if not batch_data:
+                    break
+
+                batch_frames = np.frombuffer(batch_data, dtype=np.uint8)
+                complete_frames = len(batch_frames) // (out_height * out_width * 3)
+                if complete_frames == 0:
+                    break
+
+                complete_data = batch_frames[: complete_frames * out_height * out_width * 3]
+                batch_frames_array = complete_data.reshape(complete_frames, out_height, out_width, 3)
+
+                if frames_read + complete_frames > estimated_frames:
+                    new_size = max(estimated_frames * 2, frames_read + complete_frames + 100)
+                    new_frames = np.empty((new_size, out_height, out_width, 3), dtype=np.uint8)
+                    new_frames[:frames_read] = frames[:frames_read]
+                    frames = new_frames
+                    estimated_frames = new_size
+
+                end_idx = frames_read + complete_frames
+                frames[frames_read:end_idx] = batch_frames_array
+                frames_read += complete_frames
+
+        if process.returncode not in (0, None) and frames_read == 0:
+            raise ValueError(f"FFmpeg failed to process video (return code: {process.returncode})")
+
+        if frames_read == 0:
+            raise ValueError("No frames were read from the video")
+
+        frames = frames[:frames_read]  # type: ignore
+
+        try:
+            audio = Audio.from_path(path)
+            if start_second is not None or end_second is not None:
+                audio_start = start_second if start_second is not None else 0
+                audio_end = end_second if end_second is not None else audio.metadata.duration_seconds
+                audio = audio.slice(start_seconds=audio_start, end_seconds=audio_end)
+        except (AudioLoadError, FileNotFoundError):
+            warnings.warn(f"No audio found for `{path}`, adding silent track.")
+            segment_duration = frames_read / out_fps
+            audio = Audio.create_silent(duration_seconds=round(segment_duration, 2), stereo=True, sample_rate=44100)
+
+        return frames, out_fps, audio
+
+    except VideoMetadataError:
+        raise
+    except FFmpegRunError as e:
+        raise VideoLoadError(f"FFmpeg failed: {e}") from e
+    except (OSError, IOError) as e:
+        raise VideoLoadError(f"I/O error: {e}")
+
+
+def encode_video(
+    frames: np.ndarray,
+    fps: float,
+    audio: Audio,
+    *,
+    filename: str | Path | None = None,
+    format: ALLOWED_VIDEO_FORMATS = "mp4",
+    preset: ALLOWED_VIDEO_PRESETS = "medium",
+    crf: int = 23,
+) -> Path:
+    """Encode an RGB frame array + audio track to disk via ffmpeg.
+
+    Raises:
+        ValueError: If ``format`` or ``preset`` is not in the allowed set.
+        FFmpegRunError: If ffmpeg fails to encode.
+    """
+    allowed_formats = get_args(ALLOWED_VIDEO_FORMATS)
+    if format.lower() not in allowed_formats:
+        raise ValueError(f"Unsupported format: {format}. Allowed formats are: {', '.join(allowed_formats)}")
+
+    allowed_presets = get_args(ALLOWED_VIDEO_PRESETS)
+    if preset not in allowed_presets:
+        raise ValueError(f"Unsupported preset: {preset}. Allowed presets are: {', '.join(allowed_presets)}")
+
+    frame_height, frame_width = frames.shape[1:3]
+    require_even(frame_width, frame_height)
+
+    if filename is None:
+        filename = Path(f"{uuid.uuid4()}.{format}")
+    else:
+        filename = Path(filename).with_suffix(f".{format}")
+        filename.parent.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.NamedTemporaryFile(suffix=".wav") as temp_audio:
+        audio.save(temp_audio.name, format="wav")
+
+        duration = len(frames) / fps
+
+        ffmpeg_command = [
+            "ffmpeg",
+            "-y",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-f",
+            "rawvideo",
+            "-pixel_format",
+            "rgb24",
+            "-video_size",
+            f"{frame_width}x{frame_height}",
+            "-framerate",
+            str(fps),
+            "-i",
+            "pipe:0",
+            "-i",
+            temp_audio.name,
+            "-c:v",
+            "libx264",
+            "-preset",
+            preset,
+            "-crf",
+            str(crf),
+            "-c:a",
+            "aac",
+            "-b:a",
+            "192k",
+            "-pix_fmt",
+            "yuv420p",
+            "-movflags",
+            "+faststart",
+            "-t",
+            str(duration),
+            "-vsync",
+            "cfr",
+            str(filename),
+        ]
+
+        with _ffmpeg.popen_encode(ffmpeg_command) as process:
+            if frames.dtype != np.uint8 or not frames.flags["C_CONTIGUOUS"]:
+                frames = np.ascontiguousarray(frames, dtype=np.uint8)
+
+            buffer = memoryview(frames)
+            try:
+                process.stdin.write(buffer)  # type: ignore[union-attr]
+            except BrokenPipeError as e:
+                stderr = process.stderr.read() if process.stderr is not None else b""
+                raise FFmpegRunError(
+                    f"ffmpeg terminated while receiving video data: {stderr.decode(errors='replace')}"
+                ) from e
+
+        return filename