simple-video-utils 0.0.1__tar.gz

simple_video_utils-0.0.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,76 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "simple-video-utils"
+description = "Shared utilities for processing videos for sign language."
+version = "v0.0.1"
+authors = [
+    { name = "Amit Moryossef", email = "amit@sign.mt" },
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "av",
+    "numpy",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "pytest",
+    "pytest-xdist", # For parallel test execution
+]
+
+[tool.setuptools]
+packages = [
+    "simple_video_utils",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E", # pycodestyle errors
+    "W", # pycodestyle warnings
+    "F", # pyflakes
+    "C90", # mccabe complexity
+    "I", # isort
+    "N", # pep8-naming
+    "UP", # pyupgrade
+    "B", # flake8-bugbear
+    "PT", # flake8-pytest-style
+    "W605", # invalid escape sequence
+    "BLE", # flake8-blind-except
+    "TRY", # tryceratops
+]
+
+[tool.pytest.ini_options]
+addopts = "-v"
+testpaths = [
+    "simple_video_utils",
+    "tests",
+]

simple_video_utils-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simple_video_utils-0.0.1/simple_video_utils/__init__.py

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

simple_video_utils-0.0.1/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-0.0.1/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/simple_video_utils.egg-info/PKG-INFO

@@ -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/simple_video_utils.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+simple_video_utils/__init__.py
+simple_video_utils/frames.py
+simple_video_utils/metadata.py
+simple_video_utils.egg-info/PKG-INFO
+simple_video_utils.egg-info/SOURCES.txt
+simple_video_utils.egg-info/dependency_links.txt
+simple_video_utils.egg-info/requires.txt
+simple_video_utils.egg-info/top_level.txt
+tests/test_frames.py
+tests/test_metadata.py

simple_video_utils-0.0.1/simple_video_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

simple_video_utils-0.0.1/simple_video_utils.egg-info/requires.txt

@@ -0,0 +1,7 @@
+av
+numpy
+
+[dev]
+ruff
+pytest
+pytest-xdist

simple_video_utils-0.0.1/simple_video_utils.egg-info/top_level.txt

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

simple_video_utils-0.0.1/tests/test_frames.py

@@ -0,0 +1,325 @@
+from io import BytesIO
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from simple_video_utils.frames import read_frames_exact, read_frames_from_stream
+from simple_video_utils.metadata import video_metadata
+
+
+class TestReadFramesExact:
+    """Tests for the read_frames_exact function using example.mp4."""
+
+    @pytest.fixture
+    def video_path(self):
+        """Path to the example video file."""
+        return str(Path(__file__).parent / "assets" / "example.mp4")
+
+    def test_invalid_frame_range_negative_start(self):
+        """Test that negative start frame raises AssertionError."""
+        with pytest.raises(AssertionError, match="invalid frame range"):
+            list(read_frames_exact("example.mp4", -1, 5))
+
+    def test_invalid_frame_range_end_before_start(self):
+        """Test that end_frame < start_frame raises AssertionError."""
+        with pytest.raises(AssertionError, match="invalid frame range"):
+            list(read_frames_exact("example.mp4", 10, 5))
+
+    def test_read_single_frame(self, video_path):
+        """Test reading a single frame from example.mp4."""
+        frames = list(read_frames_exact(video_path, 0, 0))
+
+        assert len(frames) == 1
+        frame = frames[0]
+
+        # Check frame properties
+        assert isinstance(frame, np.ndarray)
+        assert frame.dtype == np.uint8
+        assert len(frame.shape) == 3
+        assert frame.shape[2] == 3  # RGB channels
+
+        # Check that frame contains actual image data (not all zeros)
+        assert np.sum(frame) > 0
+
+    def test_read_multiple_frames(self, video_path):
+        """Test reading multiple consecutive frames."""
+        frames = list(read_frames_exact(video_path, 0, 2))
+
+        assert len(frames) == 3  # frames 0, 1, 2 (inclusive)
+
+        for frame in frames:
+            assert isinstance(frame, np.ndarray)
+            assert frame.dtype == np.uint8
+            assert len(frame.shape) == 3
+            assert frame.shape[2] == 3
+
+    def test_frame_range_consistency(self, video_path):
+        """Test that reading the same frame multiple times gives consistent results."""
+        frame1 = list(read_frames_exact(video_path, 5, 5))[0]
+        frame2 = list(read_frames_exact(video_path, 5, 5))[0]
+
+        np.testing.assert_array_equal(frame1, frame2)
+
+    def test_sequential_vs_range_reading(self, video_path):
+        """Test that reading frames individually vs as range gives same results."""
+        # Read frames 1, 2, 3 as a range
+        range_frames = list(read_frames_exact(video_path, 1, 3))
+
+        # Read each frame individually
+        individual_frames = [
+            list(read_frames_exact(video_path, 1, 1))[0],
+            list(read_frames_exact(video_path, 2, 2))[0],
+            list(read_frames_exact(video_path, 3, 3))[0],
+        ]
+
+        assert len(range_frames) == len(individual_frames) == 3
+
+        for range_frame, individual_frame in zip(range_frames, individual_frames, strict=False):
+            np.testing.assert_array_equal(range_frame, individual_frame)
+
+    def test_frames_are_different(self, video_path):
+        """Test that consecutive frames are actually different (video has motion)."""
+        frames = list(read_frames_exact(video_path, 0, 10))
+
+        if len(frames) >= 2:
+            # Check that not all frames are identical
+            differences = []
+            for i in range(len(frames) - 1):
+                diff = np.sum(np.abs(frames[i].astype(np.int16) - frames[i + 1].astype(np.int16)))
+                differences.append(diff)
+
+            # At least some frames should be different
+            assert max(differences) > 0, "All consecutive frames are identical"
+
+    def test_large_frame_range(self, video_path):
+        """Test reading a larger range of frames."""
+        # Get video metadata first to know how many frames we have
+        meta = video_metadata(video_path)
+        max_frames = meta.nb_frames or 30  # Default to 30 if unknown
+
+        if max_frames and max_frames > 10:
+            end_frame = min(max_frames - 1, 20)  # Read up to frame 20 or video end
+            frames = list(read_frames_exact(video_path, 0, end_frame))
+
+            expected_count = end_frame + 1
+            assert len(frames) == expected_count
+
+            # All frames should have same dimensions
+            shapes = [frame.shape for frame in frames]
+            assert all(shape == shapes[0] for shape in shapes)
+
+    def test_end_frame_none_from_start(self, video_path):
+        """Test reading from start to end of video with end_frame=None."""
+        # Read entire video from start
+        frames_all = list(read_frames_exact(video_path, 0, None))
+
+        # Read first few frames with explicit end_frame
+        frames_partial = list(read_frames_exact(video_path, 0, 5))
+
+        # All frames should be valid
+        assert len(frames_all) > 0
+        assert len(frames_all) >= len(frames_partial)
+
+        # First frames should match
+        for i in range(min(len(frames_all), len(frames_partial))):
+            np.testing.assert_array_equal(frames_all[i], frames_partial[i])
+
+    def test_end_frame_none_from_middle(self, video_path):
+        """Test reading from middle to end of video with end_frame=None."""
+        start_frame = 5
+
+        # Read from middle to end with end_frame=None
+        frames_to_end = list(read_frames_exact(video_path, start_frame, None))
+
+        # Should get some frames
+        assert len(frames_to_end) > 0
+
+        # Each frame should be valid
+        for frame in frames_to_end:
+            assert isinstance(frame, np.ndarray)
+            assert frame.dtype == np.uint8
+            assert len(frame.shape) == 3
+            assert frame.shape[2] == 3
+
+    def test_start_frame_zero_no_seeking(self, video_path):
+        """Test that start_frame=0 optimization works correctly."""
+        # These should produce identical results
+        frames_with_end = list(read_frames_exact(video_path, 0, 5))
+        frames_without_end = list(read_frames_exact(video_path, 0, None))[:6]  # Take first 6 frames
+
+        # Compare first 6 frames
+        assert len(frames_with_end) == 6  # frames 0-5 inclusive
+        assert len(frames_without_end) >= 6
+
+        for i in range(6):
+            np.testing.assert_array_equal(frames_with_end[i], frames_without_end[i])
+
+    def test_end_frame_none_consistency(self, video_path):
+        """Test that end_frame=None gives consistent results."""
+        # Read twice with end_frame=None
+        frames1 = list(read_frames_exact(video_path, 0, None))
+        frames2 = list(read_frames_exact(video_path, 0, None))
+
+        # Should get same number of frames
+        assert len(frames1) == len(frames2)
+
+        # Frames should be identical
+        for f1, f2 in zip(frames1, frames2, strict=False):
+            np.testing.assert_array_equal(f1, f2)
+
+    def test_end_frame_none_vs_explicit_end(self, video_path):
+        """Test end_frame=None vs explicit end_frame for entire video."""
+        # Get video metadata to find total frames
+        meta = video_metadata(video_path)
+        total_frames = meta.nb_frames
+
+        if total_frames and total_frames > 10:
+            # Read with end_frame=None
+            frames_none = list(read_frames_exact(video_path, 0, None))
+
+            # Read with explicit end_frame (assuming we know total frames)
+            frames_explicit = list(read_frames_exact(video_path, 0, total_frames - 1))
+
+            # Should get same number of frames (or close due to container metadata)
+            # Allow small difference due to potential metadata inaccuracy
+            assert abs(len(frames_none) - len(frames_explicit)) <= 1
+
+            # First several frames should match
+            min_len = min(len(frames_none), len(frames_explicit))
+            for i in range(min(min_len, 10)):  # Compare first 10 frames
+                np.testing.assert_array_equal(frames_none[i], frames_explicit[i])
+
+    def test_bad_color_space_video(self):
+        """Test reading frames from a video with unusual color space metadata."""
+        strange_video = str(Path(__file__).parent / "assets" / "bad_colorspace.mp4")
+
+        # Test reading frames (ffmpeg 8.0+ handles this video correctly)
+        frames = list(read_frames_exact(strange_video, 0))
+        assert len(frames) == 182
+
+    def test_webm_file(self):
+        """Test reading frames from a WebM file."""
+        webm_video = str(Path(__file__).parent / "assets" / "example.webm")
+
+        # Test reading frames
+        frames = list(read_frames_exact(webm_video, 0))
+        assert len(frames) == 67
+
+    def test_remote_video_url(self):
+        """Test reading frames from a remote video URL."""
+        remote_url = "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerMeltdowns.mp4"
+
+        # Test reading first frame
+        frames = list(read_frames_exact(remote_url, 0, 0))
+        assert len(frames) == 1
+
+        frame = frames[0]
+        assert isinstance(frame, np.ndarray)
+        assert frame.dtype == np.uint8
+        assert len(frame.shape) == 3
+        assert frame.shape[2] == 3
+        assert np.sum(frame) > 0
+
+        # Test reading multiple frames
+        frames_multi = list(read_frames_exact(remote_url, 0, 2))
+        assert len(frames_multi) == 3
+
+
+class TestReadFramesFromStream:
+    """Tests for streaming video input via read_frames_from_stream."""
+
+    @pytest.fixture
+    def video_path(self):
+        """Path to the example video file."""
+        return str(Path(__file__).parent / "assets" / "example.mp4")
+
+    @pytest.fixture
+    def video_bytes(self, video_path):
+        """Load example video as bytes."""
+        return Path(video_path).read_bytes()
+
+    def test_read_frames_from_stream_basic(self, video_bytes):
+        """Test reading frames from a BytesIO stream."""
+        stream = BytesIO(video_bytes)
+        meta, frames_gen = read_frames_from_stream(stream)
+
+        # Check metadata
+        assert meta.width > 0
+        assert meta.height > 0
+        assert meta.fps > 0
+
+        # Read first frame
+        frame = next(frames_gen)
+        assert isinstance(frame, np.ndarray)
+        assert frame.dtype == np.uint8
+        assert frame.shape == (meta.height, meta.width, 3)
+        assert np.sum(frame) > 0
+
+    def test_read_frames_from_stream_all_frames(self, video_bytes, video_path):
+        """Test that stream reading produces same frames as file reading."""
+        stream = BytesIO(video_bytes)
+        meta, frames_gen = read_frames_from_stream(stream)
+
+        stream_frames = list(frames_gen)
+        file_frames = list(read_frames_exact(video_path, 0, None))
+
+        # Same number of frames
+        assert len(stream_frames) == len(file_frames)
+
+        # Frames should be identical
+        for i, (stream_frame, file_frame) in enumerate(zip(stream_frames, file_frames, strict=False)):
+            np.testing.assert_array_equal(
+                stream_frame,
+                file_frame,
+                err_msg=f"Frame {i} differs between stream and file reading",
+            )
+
+    def test_read_frames_from_stream_skip_frames(self, video_bytes, video_path):
+        """Test skipping initial frames from stream."""
+        skip = 5
+
+        stream = BytesIO(video_bytes)
+        _, frames_gen = read_frames_from_stream(stream, skip_frames=skip)
+        stream_frames = list(frames_gen)
+
+        # Compare with file-based reading starting at frame 5
+        file_frames = list(read_frames_exact(video_path, skip, None))
+
+        assert len(stream_frames) == len(file_frames)
+
+        for i, (stream_frame, file_frame) in enumerate(zip(stream_frames, file_frames, strict=False)):
+            np.testing.assert_array_equal(
+                stream_frame,
+                file_frame,
+                err_msg=f"Frame {i} (skipped {skip}) differs",
+            )
+
+    def test_read_frames_from_stream_metadata_matches(self, video_bytes, video_path):
+        """Test that returned metadata matches expected values."""
+        stream = BytesIO(video_bytes)
+        meta_stream, _ = read_frames_from_stream(stream)
+        meta_file = video_metadata(video_path)
+
+        assert meta_stream.width == meta_file.width
+        assert meta_stream.height == meta_file.height
+        assert meta_stream.fps == meta_file.fps
+
+    def test_read_frames_from_stream_webm(self):
+        """Test reading frames from a WebM stream."""
+        video_path = Path(__file__).parent / "assets" / "example.webm"
+        video_bytes = video_path.read_bytes()
+
+        stream = BytesIO(video_bytes)
+        meta, frames_gen = read_frames_from_stream(stream)
+
+        assert meta.width > 0
+        assert meta.height > 0
+        assert meta.fps > 0
+
+        frames = list(frames_gen)
+        assert len(frames) == 67  # Same as test_webm_file
+
+
+if __name__ == "__main__":
+    pytest.main([__file__])

simple_video_utils-0.0.1/tests/test_metadata.py

@@ -0,0 +1,81 @@
+from pathlib import Path
+
+import pytest
+
+from simple_video_utils.metadata import video_metadata, video_metadata_from_bytes
+
+
+class TestVideoMetadata:
+    """Tests for video metadata extraction functions."""
+
+    @pytest.fixture
+    def video_path(self):
+        """Path to the example video file."""
+        return str(Path(__file__).parent / "assets" / "example.mp4")
+
+    @pytest.fixture
+    def video_bytes(self, video_path):
+        """Load example video as bytes."""
+        return Path(video_path).read_bytes()
+
+    def test_video_metadata(self, video_path):
+        """Test that we can read video metadata."""
+        meta = video_metadata(video_path)
+
+        assert meta.width > 0
+        assert meta.height > 0
+        assert meta.fps > 0
+        assert isinstance(meta.width, int)
+        assert isinstance(meta.height, int)
+        assert isinstance(meta.fps, float)
+
+    def test_video_metadata_from_bytes(self, video_bytes):
+        """Test metadata extraction from video bytes."""
+        meta = video_metadata_from_bytes(video_bytes)
+
+        assert meta.width > 0
+        assert meta.height > 0
+        assert meta.fps > 0
+        assert isinstance(meta.width, int)
+        assert isinstance(meta.height, int)
+        assert isinstance(meta.fps, float)
+
+    def test_video_metadata_from_bytes_matches_file(self, video_bytes, video_path):
+        """Test that bytes-based metadata matches file-based metadata."""
+        meta_bytes = video_metadata_from_bytes(video_bytes)
+        meta_file = video_metadata(video_path)
+
+        assert meta_bytes.width == meta_file.width
+        assert meta_bytes.height == meta_file.height
+        assert meta_bytes.fps == meta_file.fps
+
+    def test_bad_color_space_video(self):
+        """Test metadata extraction from a video with unusual color space."""
+        strange_video = str(Path(__file__).parent / "assets" / "bad_colorspace.mp4")
+
+        meta = video_metadata(strange_video)
+        assert meta.width > 0
+        assert meta.height > 0
+        assert meta.fps > 0
+
+    def test_webm_file(self):
+        """Test metadata extraction from WebM file."""
+        webm_video = str(Path(__file__).parent / "assets" / "example.webm")
+
+        meta = video_metadata(webm_video)
+        assert meta.width > 0
+        assert meta.height > 0
+        assert meta.fps > 0
+
+    def test_remote_video_url(self):
+        """Test metadata extraction from a remote video URL."""
+        remote_url = "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerMeltdowns.mp4"
+
+        meta = video_metadata(remote_url)
+        assert meta.width > 0
+        assert meta.height > 0
+        assert meta.fps > 0
+
+
+if __name__ == "__main__":
+    pytest.main([__file__])