videopython 0.31.0__tar.gz → 0.31.1__tar.gz

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

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

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

{videopython-0.31.0 → videopython-0.31.1}/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.1}/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.1}/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.1/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.1/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.0 → videopython-0.31.1}/src/videopython/base/audio/audio.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import io
-import json
 import subprocess
 import wave
 from dataclasses import dataclass
@@ -10,7 +9,8 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
-from videopython.base.exceptions import AudioLoadError
+from videopython.base import _ffmpeg
+from videopython.base.exceptions import AudioLoadError, FFmpegProbeError
 
 if TYPE_CHECKING:
     from videopython.base.audio.analysis import AudioLevels, AudioSegment, AudioSegmentType, SilentSegment
@@ -71,39 +71,21 @@ class Audio:
     @staticmethod
     def _get_ffmpeg_info(file_path: Path) -> dict:
         """Get audio metadata using ffprobe"""
-        cmd = [
-            "ffprobe",
-            "-v",
-            "quiet",
-            "-print_format",
-            "json",
-            "-show_format",
-            "-show_streams",
-            str(file_path),
-        ]
-
         try:
-            output = subprocess.check_output(cmd)
-            info = json.loads(output.decode())
-
-            # Find the audio stream
-            audio_stream = None
-            for stream in info["streams"]:
-                if stream["codec_type"] == "audio":
-                    audio_stream = stream
-                    break
-
-            if audio_stream is None:
-                raise AudioLoadError("No audio stream found")
-
-            return {
-                "sample_rate": int(audio_stream["sample_rate"]),
-                "channels": int(audio_stream["channels"]),
-                "duration": float(info["format"]["duration"]),
-                "bit_depth": int(audio_stream.get("bits_per_sample", 16)),
-            }
-        except subprocess.CalledProcessError as e:
-            raise AudioLoadError(f"Error getting audio info: {e}")
+            info = _ffmpeg.probe(file_path)
+        except FFmpegProbeError as e:
+            raise AudioLoadError(f"Error getting audio info: {e}") from e
+
+        audio_stream = next((s for s in info["streams"] if s["codec_type"] == "audio"), None)
+        if audio_stream is None:
+            raise AudioLoadError("No audio stream found")
+
+        return {
+            "sample_rate": int(audio_stream["sample_rate"]),
+            "channels": int(audio_stream["channels"]),
+            "duration": float(info["format"]["duration"]),
+            "bit_depth": int(audio_stream.get("bits_per_sample", 16)),
+        }
 
     @classmethod
     def create_silent(

{videopython-0.31.0 → videopython-0.31.1}/src/videopython/base/exceptions.py

@@ -7,6 +7,24 @@ class VideoPythonError(Exception):
     pass
 
 
+class FFmpegError(VideoPythonError):
+    """Base exception for ffmpeg/ffprobe subprocess failures."""
+
+    pass
+
+
+class FFmpegProbeError(FFmpegError):
+    """Raised when an ffprobe invocation or its JSON output fails."""
+
+    pass
+
+
+class FFmpegRunError(FFmpegError):
+    """Raised when a blocking ffmpeg run returns a non-zero exit code."""
+
+    pass
+
+
 class VideoError(VideoPythonError):
     """Base exception for video-related errors."""
 

{videopython-0.31.0 → videopython-0.31.1}/src/videopython/base/streaming.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import logging
 import subprocess
 import tempfile
+from contextlib import ExitStack
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import get_args
@@ -17,6 +18,8 @@ from typing import get_args
 import numpy as np
 from tqdm import tqdm
 
+from videopython.base import _ffmpeg
+from videopython.base._dimensions import require_even
 from videopython.base.audio import Audio
 from videopython.base.effects import Effect
 from videopython.base.video import ALLOWED_VIDEO_FORMATS, ALLOWED_VIDEO_PRESETS, FrameIterator
@@ -72,6 +75,7 @@ class FrameEncoder:
         self._format = format
         self._preset = preset
         self._crf = crf
+        self._stack: ExitStack | None = None
         self._process: subprocess.Popen | None = None
 
     def _build_command(self) -> list[str]:
@@ -121,18 +125,9 @@ class FrameEncoder:
         return cmd
 
     def __enter__(self) -> FrameEncoder:
-        if self._width % 2 != 0 or self._height % 2 != 0:
-            raise ValueError(
-                f"libx264 with yuv420p requires even dimensions, got {self._width}x{self._height}. "
-                "Resize or crop to even dimensions before encoding."
-            )
-        cmd = self._build_command()
-        self._process = subprocess.Popen(
-            cmd,
-            stdin=subprocess.PIPE,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.PIPE,
-        )
+        require_even(self._width, self._height)
+        self._stack = ExitStack()
+        self._process = self._stack.enter_context(_ffmpeg.popen_encode(self._build_command()))
         return self
 
     def write_frame(self, frame: np.ndarray) -> None:
@@ -141,21 +136,13 @@ class FrameEncoder:
             raise RuntimeError("FrameEncoder not started -- use as context manager")
         self._process.stdin.write(frame.tobytes())
 
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
-        if self._process is None:
-            return
-        try:
-            if self._process.stdin and not self._process.stdin.closed:
-                self._process.stdin.close()
-            stderr = self._process.stderr.read() if self._process.stderr else b""
-            returncode = self._process.wait(timeout=30)
-            if returncode != 0 and exc_type is None:
-                raise RuntimeError(f"FFmpeg encoder failed (code {returncode}): {stderr.decode(errors='ignore')}")
-        except subprocess.TimeoutExpired:
-            self._process.kill()
-            self._process.wait()
-        finally:
-            self._process = None
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool | None:  # type: ignore[no-untyped-def]
+        stack = self._stack
+        self._stack = None
+        self._process = None
+        if stack is None:
+            return None
+        return stack.__exit__(exc_type, exc_val, exc_tb)
 
 
 def stream_segment(
@@ -238,7 +225,7 @@ def stream_segment(
                     frame_count += 1
 
         return output_path
-    except (OSError, RuntimeError, ValueError, subprocess.CalledProcessError):
+    except Exception:
         if output_path.exists():
             output_path.unlink()
         raise
@@ -259,25 +246,24 @@ def concat_files(segment_files: list[Path], output_path: Path) -> Path:
         list_path = Path(f.name)
 
     try:
-        cmd = [
-            "ffmpeg",
-            "-y",
-            "-hide_banner",
-            "-loglevel",
-            "error",
-            "-f",
-            "concat",
-            "-safe",
-            "0",
-            "-i",
-            str(list_path),
-            "-c",
-            "copy",
-            str(output_path),
-        ]
-        result = subprocess.run(cmd, capture_output=True)
-        if result.returncode != 0:
-            raise RuntimeError(f"FFmpeg concat failed: {result.stderr.decode(errors='ignore')}")
+        _ffmpeg.run(
+            [
+                "ffmpeg",
+                "-y",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-f",
+                "concat",
+                "-safe",
+                "0",
+                "-i",
+                str(list_path),
+                "-c",
+                "copy",
+                str(output_path),
+            ]
+        )
         return output_path
     finally:
         list_path.unlink(missing_ok=True)

{videopython-0.31.0 → videopython-0.31.1}/src/videopython/base/transforms.py

@@ -16,8 +16,9 @@ import numpy as np
 from pydantic import Field, model_validator
 from tqdm import tqdm
 
+from videopython.base._dimensions import floor_to_even, round_to_even
 from videopython.base.operation import FilterCtx, OpCategory, Operation
-from videopython.base.video import Video, _round_dimension_to_even
+from videopython.base.video import Video
 
 if TYPE_CHECKING:
     from videopython.base.text.transcription import Transcription
@@ -120,8 +121,8 @@ class Resize(Operation):
             new_h = self.height
             new_w = round(src_w * (self.height / src_h))
         if self.round_to_even:
-            new_w = _round_dimension_to_even(new_w)
-            new_h = _round_dimension_to_even(new_h)
+            new_w = round_to_even(new_w)
+            new_h = round_to_even(new_h)
         return new_w, new_h
 
     def apply(self, video: Video) -> Video:
@@ -250,10 +251,10 @@ class Crop(Operation):
         if cw > meta.width or ch > meta.height:
             raise ValueError(f"Crop {cw}x{ch} exceeds source {meta.width}x{meta.height}")
         if self.mode == CropMode.CENTER:
-            # Mirror apply()'s `mid - cw//2 : mid + cw//2` slice, which produces
-            # 2 * (cw // 2) pixels — i.e. odd targets get rounded down to even.
-            cw = (cw // 2) * 2
-            ch = (ch // 2) * 2
+            # Mirror apply()'s `mid - cw//2 : mid + cw//2` slice, which
+            # produces 2 * (cw // 2) pixels — odd targets round down.
+            cw = floor_to_even(cw)
+            ch = floor_to_even(ch)
         return meta.with_dimensions(cw, ch)
 
     def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None:

{videopython-0.31.0 → videopython-0.31.1}/src/videopython/base/video.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-import json
-import subprocess
 import tempfile
 import uuid
 import warnings
@@ -12,8 +10,16 @@ from typing import Generator, 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, VideoLoadError, VideoMetadataError
+from videopython.base.exceptions import (
+    AudioLoadError,
+    FFmpegProbeError,
+    FFmpegRunError,
+    VideoLoadError,
+    VideoMetadataError,
+)
 
 __all__ = [
     "Video",
@@ -34,11 +40,6 @@ FRAME_BUFFER_MULTIPLIER = 1.1  # 10% buffer for frame rate estimation errors
 FRAME_BUFFER_PADDING = 10  # Additional fixed frame padding
 
 
-def _round_dimension_to_even(value: int | float) -> int:
-    """Round a dimension to the nearest even integer (minimum 2)."""
-    return max(2, int(round(float(value) / 2.0) * 2))
-
-
 @dataclass
 class VideoMetadata:
     """Class to store video metadata."""
@@ -66,28 +67,20 @@ class VideoMetadata:
     @staticmethod
     def _run_ffprobe(video_path: str | Path) -> dict:
         """Run ffprobe and return parsed JSON output."""
-        cmd = [
-            "ffprobe",
-            "-v",
-            "error",
-            "-select_streams",
-            "v:0",
-            "-show_entries",
-            "stream=width,height,r_frame_rate,nb_frames",
-            "-show_entries",
-            "format=duration",
-            "-print_format",
-            "json",
-            str(video_path),
-        ]
-
         try:
-            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
-            return json.loads(result.stdout)
-        except subprocess.CalledProcessError as e:
-            raise VideoMetadataError(f"FFprobe error: {e.stderr}")
-        except json.JSONDecodeError as e:
-            raise VideoMetadataError(f"Error parsing FFprobe output: {e}")
+            return _ffmpeg.probe(
+                video_path,
+                extra_args=[
+                    "-select_streams",
+                    "v:0",
+                    "-show_entries",
+                    "stream=width,height,r_frame_rate,nb_frames",
+                    "-show_entries",
+                    "format=duration",
+                ],
+            )
+        except FFmpegProbeError as e:
+            raise VideoMetadataError(str(e)) from e
 
     @classmethod
     def from_path(cls, video_path: str | Path) -> VideoMetadata:
@@ -238,7 +231,7 @@ class FrameIterator:
         self.metadata = VideoMetadata.from_path(path)
         self.start_second = start_second if start_second is not None else 0.0
         self.end_second = end_second
-        self._process: subprocess.Popen | None = None
+        self._iter: Generator[tuple[int, np.ndarray], None, None] | None = None
 
         # Build -vf filter chain
         self._vf_filters = list(vf_filters) if vf_filters else []
@@ -287,52 +280,30 @@ class FrameIterator:
         Frame indices are absolute indices in the original video,
         accounting for any start_second offset.
         """
-        cmd = self._build_ffmpeg_command()
+        self._iter = self._iter_frames()
+        return self._iter
 
-        self._process = subprocess.Popen(
-            cmd,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            bufsize=self._frame_size * 2,
-        )
-
-        # Calculate starting frame index based on start_second
-        start_frame = int(self.start_second * self.output_fps)
-        frame_idx = start_frame
-
-        try:
+    def _iter_frames(self) -> Generator[tuple[int, np.ndarray], None, None]:
+        cmd = self._build_ffmpeg_command()
+        with _ffmpeg.popen_decode(cmd, bufsize=self._frame_size * 2) as proc:
+            frame_idx = int(self.start_second * self.output_fps)
             while True:
-                raw_frame = self._process.stdout.read(self._frame_size)  # type: ignore
+                raw_frame = proc.stdout.read(self._frame_size)  # type: ignore[union-attr]
                 if len(raw_frame) != self._frame_size:
                     break
-
-                frame = np.frombuffer(raw_frame, dtype=np.uint8).copy()
-                frame = frame.reshape(self.output_height, self.output_width, 3)
-
+                frame = (
+                    np.frombuffer(raw_frame, dtype=np.uint8).copy().reshape(self.output_height, self.output_width, 3)
+                )
                 yield frame_idx, frame
                 frame_idx += 1
-        finally:
-            self._cleanup()
-
-    def _cleanup(self) -> None:
-        """Clean up ffmpeg process."""
-        if self._process is not None:
-            if self._process.poll() is None:
-                self._process.terminate()
-                try:
-                    self._process.wait(timeout=5)
-                except subprocess.TimeoutExpired:
-                    self._process.kill()
-                    self._process.wait()
-            if self._process.stdout:
-                self._process.stdout.close()
-            self._process = None
 
     def __enter__(self) -> "FrameIterator":
         return self
 
     def __exit__(self, *args: object) -> None:
-        self._cleanup()
+        if self._iter is not None:
+            self._iter.close()
+            self._iter = None
 
 
 def extract_frames_at_indices(
@@ -388,40 +359,28 @@ def extract_frames_at_indices(
         "pipe:1",
     ]
 
-    process = subprocess.Popen(
-        cmd,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.DEVNULL,
-        bufsize=10**8,
-    )
-
     frame_size = metadata.width * metadata.height * 3
 
-    try:
+    with _ffmpeg.popen_decode(cmd, bufsize=10**8) as process:
         raw_data, _ = process.communicate()
 
-        actual_frames = len(raw_data) // frame_size
-        if actual_frames == 0:
-            return np.empty((0, metadata.height, metadata.width, 3), dtype=np.uint8)
-
-        # Truncate to complete frames only
-        raw_data = raw_data[: actual_frames * frame_size]
+    actual_frames = len(raw_data) // frame_size
+    if actual_frames == 0:
+        return np.empty((0, metadata.height, metadata.width, 3), dtype=np.uint8)
 
-        frames = np.frombuffer(raw_data, dtype=np.uint8).copy()
-        frames = frames.reshape(-1, metadata.height, metadata.width, 3)
+    # Truncate to complete frames only
+    raw_data = raw_data[: actual_frames * frame_size]
 
-        # Reorder to match original frame_indices order if needed
-        if unique_sorted_indices != frame_indices:
-            index_map = {idx: i for i, idx in enumerate(unique_sorted_indices)}
-            reorder = [index_map[idx] for idx in frame_indices if idx in index_map]
-            frames = frames[reorder]
+    frames = np.frombuffer(raw_data, dtype=np.uint8).copy()
+    frames = frames.reshape(-1, metadata.height, metadata.width, 3)
 
-        return frames
+    # Reorder to match original frame_indices order if needed
+    if unique_sorted_indices != frame_indices:
+        index_map = {idx: i for i, idx in enumerate(unique_sorted_indices)}
+        reorder = [index_map[idx] for idx in frame_indices if idx in index_map]
+        frames = frames[reorder]
 
-    finally:
-        if process.poll() is None:
-            process.terminate()
-            process.wait()
+    return frames
 
 
 def extract_frames_at_times(
@@ -546,14 +505,6 @@ class Video:
                 ]
             )
 
-            # Start FFmpeg process with stderr redirected to avoid deadlock
-            process = subprocess.Popen(
-                ffmpeg_cmd,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.DEVNULL,  # Redirect stderr to avoid deadlock
-                bufsize=10**8,  # Use large buffer for efficient I/O
-            )
-
             # Calculate frame size in bytes
             frame_size = out_width * out_height * 3  # 3 bytes per pixel for RGB
 
@@ -574,59 +525,35 @@ class Video:
             frames = np.empty((estimated_frames, out_height, out_width, 3), dtype=np.uint8)
             frames_read = 0
 
-            try:
+            with _ffmpeg.popen_decode(ffmpeg_cmd, bufsize=10**8) as process:
                 while frames_read < estimated_frames:
-                    # Calculate remaining frames to read
                     remaining_frames = estimated_frames - frames_read
                     batch_size = min(read_batch_size, remaining_frames)
 
-                    # Read batch of data
-                    batch_data = process.stdout.read(frame_size * batch_size)  # type: ignore
-
+                    batch_data = process.stdout.read(frame_size * batch_size)  # type: ignore[union-attr]
                     if not batch_data:
                         break
 
-                    # Convert to numpy array
                     batch_frames = np.frombuffer(batch_data, dtype=np.uint8)
-
-                    # Calculate how many complete frames we got
                     complete_frames = len(batch_frames) // (out_height * out_width * 3)
-
                     if complete_frames == 0:
                         break
 
-                    # Only keep complete frames
                     complete_data = batch_frames[: complete_frames * out_height * out_width * 3]
                     batch_frames_array = complete_data.reshape(complete_frames, out_height, out_width, 3)
 
-                    # Check if we have room in pre-allocated array
                     if frames_read + complete_frames > estimated_frames:
-                        # Need to expand array - this should be rare with our buffer
+                        # Pre-allocation undershoot — rare with the buffer.
                         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
 
-                    # Store batch in pre-allocated array
                     end_idx = frames_read + complete_frames
                     frames[frames_read:end_idx] = batch_frames_array
                     frames_read += complete_frames
 
-            finally:
-                # Ensure process is properly terminated
-                if process.poll() is None:
-                    process.terminate()
-                    try:
-                        process.wait(timeout=5)
-                    except subprocess.TimeoutExpired:
-                        process.kill()
-                        process.wait()
-
-                # Clean up pipes
-                if process.stdout:
-                    process.stdout.close()
-
             # Check if FFmpeg had an error (non-zero return code)
             if process.returncode not in (0, None) and frames_read == 0:
                 raise ValueError(f"FFmpeg failed to process video (return code: {process.returncode})")
@@ -645,7 +572,7 @@ class Video:
                     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, subprocess.CalledProcessError):
+            except (AudioLoadError, FileNotFoundError):
                 warnings.warn(f"No audio found for `{path}`, adding silent track.")
                 # Create silent audio based on actual frames read
                 segment_duration = frames_read / out_fps
@@ -655,8 +582,8 @@ class Video:
 
         except VideoMetadataError:
             raise
-        except subprocess.CalledProcessError as e:
-            raise VideoLoadError(f"FFmpeg failed: {e}")
+        except FFmpegRunError as e:
+            raise VideoLoadError(f"FFmpeg failed: {e}") from e
         except (OSError, IOError) as e:
             raise VideoLoadError(f"I/O error: {e}")
 
@@ -743,12 +670,7 @@ class Video:
             )
 
         frame_height, frame_width = self.frame_shape[:2]
-        if frame_width % 2 != 0 or frame_height % 2 != 0:
-            raise ValueError(
-                "Current save pipeline uses libx264 with yuv420p, which requires even frame dimensions. "
-                f"Got {frame_width}x{frame_height}. "
-                "Resize, crop, or pad to an even width and height before saving."
-            )
+        require_even(frame_width, frame_height)
 
         if filename is None:
             filename = Path(f"{uuid.uuid4()}.{format}")
@@ -808,43 +730,22 @@ class Video:
                 str(filename),
             ]
 
-            process = subprocess.Popen(
-                ffmpeg_command,
-                stdin=subprocess.PIPE,
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.PIPE,
-            )
-
-            try:
-                if process.stdin is None:
-                    raise RuntimeError("Failed to open FFmpeg stdin pipe for video data")
-
+            with _ffmpeg.popen_encode(ffmpeg_command) as process:
                 frames = self.frames
                 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)
-                    process.stdin.close()
+                    process.stdin.write(buffer)  # type: ignore[union-attr]
                 except BrokenPipeError as e:
+                    # ffmpeg has already died; surface its stderr for diagnostics.
                     stderr = process.stderr.read() if process.stderr is not None else b""
-                    returncode = process.wait()
-                    raise RuntimeError(
-                        f"FFmpeg terminated while receiving video data (code {returncode}): "
-                        f"{stderr.decode(errors='ignore')}"
+                    raise FFmpegRunError(
+                        f"ffmpeg terminated while receiving video data: {stderr.decode(errors='replace')}"
                     ) from e
 
-                stderr = process.stderr.read() if process.stderr is not None else b""
-                returncode = process.wait()
-
-                if returncode != 0:
-                    raise RuntimeError(f"FFmpeg failed with code {returncode}: {stderr.decode(errors='ignore')}")
-
-                return filename
-            finally:
-                if process.poll() is None:
-                    process.kill()
+            return filename
 
     def add_audio(self, audio: Audio, overlay: bool = True) -> Video:
         """Add audio to video, returning a new Video instance.