simple-video-utils 0.0.1__py3-none-any.whl

simple_video_utils/__init__.py

@@ -0,0 +1 @@
+"""Simple video utilities for frame extraction and metadata."""

simple_video_utils/frames.py

@@ -0,0 +1,95 @@
+import io
+from collections.abc import Generator
+from typing import BinaryIO
+
+import av
+import numpy as np
+
+from simple_video_utils.metadata import VideoMetadata, _open_container, video_metadata_from_bytes
+
+
+def _generate_frames(
+    container: av.container.InputContainer,
+    start_frame: int = 0,
+    end_frame: int | None = None,
+) -> Generator[np.ndarray, None, None]:
+    """
+    Generate RGB frames from a container.
+
+    Args:
+        container: Open PyAV container.
+        start_frame: First frame index to yield (0-based).
+        end_frame: Last frame index to yield (inclusive), or None for all.
+
+    Yields:
+        RGB numpy arrays (H, W, 3).
+    """
+    frame_index = 0
+    for frame in container.decode(video=0):
+        if frame_index < start_frame:
+            frame_index += 1
+            continue
+
+        if end_frame is not None and frame_index > end_frame:
+            break
+
+        yield frame.to_ndarray(format='rgb24')
+        frame_index += 1
+
+def read_frames_exact(
+    src: str,
+    start_frame: int,
+    end_frame: int | None = None,
+) -> Generator[np.ndarray, None, None]:
+    """
+    Return frames [start_frame, end_frame] inclusive as RGB np.ndarrays.
+    If end_frame is None, reads from start_frame to the end of the video.
+    Uses PyAV for efficient frame extraction.
+    """
+    if end_frame is not None:
+        assert end_frame >= start_frame >= 0, "invalid frame range"
+    else:
+        assert start_frame >= 0, "start_frame must be non-negative"
+
+    with _open_container(src) as container:
+        stream = container.streams.video[0]
+
+        # Seek to approximate start position if not starting from beginning
+        if start_frame > 0:
+            fps = float(stream.average_rate) if stream.average_rate else 30.0
+            seek_time_sec = max(0, (start_frame - 30) / fps)
+            # Convert seconds to stream time_base units
+            seek_timestamp = int(seek_time_sec / float(stream.time_base))
+            container.seek(seek_timestamp, stream=stream)
+
+        yield from _generate_frames(container, start_frame, end_frame)
+
+
+def read_frames_from_stream(
+    stream: BinaryIO,
+    skip_frames: int = 0,
+) -> tuple[VideoMetadata, Generator[np.ndarray, None, None]]:
+    """
+    Read frames from a video stream (file-like object).
+
+    Args:
+        stream: A file-like object containing video data (e.g., uploaded file).
+        skip_frames: Number of initial frames to skip (for resume support).
+
+    Returns:
+        A tuple of (VideoMetadata, frame_generator).
+        The generator yields np.ndarray frames in RGB format (H, W, 3).
+
+    Note:
+        PyAV handles format detection and seeking automatically.
+        Works with MP4, WebM, and other formats.
+    """
+    video_data = stream.read()
+    meta = video_metadata_from_bytes(video_data)
+
+    def frame_generator() -> Generator[np.ndarray, None, None]:
+        """Generator that yields frames from the video data."""
+        with _open_container(io.BytesIO(video_data)) as container:
+            yield from _generate_frames(container, start_frame=skip_frames)
+
+    return meta, frame_generator()

simple_video_utils/metadata.py

@@ -0,0 +1,60 @@
+import io
+from contextlib import contextmanager
+from functools import lru_cache
+from typing import NamedTuple
+
+import av
+
+
+class VideoMetadata(NamedTuple):
+    width: int
+    height: int
+    fps: float
+    nb_frames: int | None
+    time_base: str | None
+
+
+@contextmanager
+def _open_container(source: str | io.BytesIO):
+    """Context manager for safely opening and closing PyAV containers."""
+    container = None
+    try:
+        container = av.open(source)
+        yield container
+    except Exception as e:
+        msg = "Failed to open video"
+        raise RuntimeError(msg) from e
+    finally:
+        if container:
+            container.close()
+
+
+def _get_metadata_from_container(container: av.container.InputContainer) -> VideoMetadata:
+    """Extract metadata from an open PyAV container."""
+    stream = container.streams.video[0]
+    fps = float(stream.average_rate) if stream.average_rate else 0.0
+    nb_frames = stream.frames if stream.frames > 0 else None
+    time_base = str(stream.time_base) if stream.time_base else None
+
+    return VideoMetadata(
+        width=stream.width,
+        height=stream.height,
+        fps=fps,
+        nb_frames=nb_frames,
+        time_base=time_base,
+    )
+
+
+
+
+def video_metadata_from_bytes(data: bytes) -> VideoMetadata:
+    """Return key video stream metadata from video bytes."""
+    with _open_container(io.BytesIO(data)) as container:
+        return _get_metadata_from_container(container)
+
+
+@lru_cache(maxsize=8)
+def video_metadata(url_or_path: str) -> VideoMetadata:
+    """Return key video stream metadata."""
+    with _open_container(url_or_path) as container:
+        return _get_metadata_from_container(container)

simple_video_utils-0.0.1.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: simple-video-utils
+Version: 0.0.1
+Summary: Shared utilities for processing videos for sign language.
+Author-email: Amit Moryossef <amit@sign.mt>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: av
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Dynamic: license-file
+
+# Simple Video Utils
+
+Lightweight utilities for extracting frames and metadata from videos. Built for sign language processing workflows.
+
+![Python](https://img.shields.io/badge/python-3.10+-blue)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+## Goal
+
+Provide simple, efficient tools for video processing in sign language research and applications. 
+Uses PyAV for fast frame extraction with support for multiple formats (MP4, WebM) and remote URLs.
+
+## Installation
+
+```bash
+pip install simple-video-utils
+```
+
+## Usage
+
+### Extract Video Metadata
+
+```python
+from simple_video_utils.metadata import video_metadata
+
+meta = video_metadata("video.mp4")
+print(f"{meta.width}x{meta.height} @ {meta.fps} fps")
+# Output: VideoMetadata(width=1920, height=1080, fps=30.0, nb_frames=450, time_base='1/15360')
+```
+
+### Read Frames from File
+
+```python
+from simple_video_utils.frames import read_frames_exact
+
+# Read specific frame range (inclusive)
+frames = list(read_frames_exact("video.mp4", start_frame=0, end_frame=10))
+# Returns 11 frames as numpy arrays (H, W, 3) in RGB format
+
+# Read from frame to end of video
+frames = list(read_frames_exact("video.mp4", start_frame=5, end_frame=None))
+```
+
+### Read Frames from Stream
+
+```python
+from simple_video_utils.frames import read_frames_from_stream
+
+# Useful for uploaded files or in-memory video data
+with open("video.mp4", "rb") as f:
+    meta, frames_gen = read_frames_from_stream(f)
+    for frame in frames_gen:
+        # Process each frame (numpy array)
+        pass
+```
+
+### Remote Videos
+
+```python
+from simple_video_utils.metadata import video_metadata
+from simple_video_utils.frames import read_frames_exact
+
+# Works with remote URLs
+url = "https://example.com/video.mp4"
+meta = video_metadata(url)
+frames = list(read_frames_exact(url, 0, 5))
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+ruff check .
+```
+

simple_video_utils-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+simple_video_utils/__init__.py,sha256=LRnmuFyziKNpM_Mf2x4UarAiZsOKGunmMDf98WTm1SY,64
+simple_video_utils/frames.py,sha256=VkX-OHGrOc_oJDI7j8xIarVu2jHWdSYEouFgk4PfsJE,3115
+simple_video_utils/metadata.py,sha256=1JALf1AligxFwfArgGjgoFFtrrQTMKsnzY2yH3oeQVk,1672
+simple_video_utils-0.0.1.dist-info/licenses/LICENSE,sha256=-85p81jfHERhmQnds40xOFt4q3cTlX0GFbSUuJU1jxI,1061
+simple_video_utils-0.0.1.dist-info/METADATA,sha256=IIfZpWWdej-F_xb9jKf7TTQadTWlLv6Xahlg_HeOYI8,2378
+simple_video_utils-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+simple_video_utils-0.0.1.dist-info/top_level.txt,sha256=9aYY6Qrg3bqG-QZsunQV8-_qXabGWK26Ub7JC8Eyyys,19
+simple_video_utils-0.0.1.dist-info/RECORD,,

simple_video_utils-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simple_video_utils-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 sign
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_video_utils-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_video_utils