painfacenet 0.1.0__tar.gz

painfacenet-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: painfacenet
+Version: 0.1.0
+Summary: Open-source Python framework for facial pain estimation via Action Units (research only)
+Author: Shariff Naveed
+License: MIT
+Project-URL: Homepage, https://github.com/shariff-bit/PainFace
+Project-URL: Repository, https://github.com/shariff-bit/PainFace
+Keywords: pain,facial,action units,AU,computer vision,research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: requires-python
+
+# PainFace
+
+Open-source Python framework for facial pain estimation via Action Units (AUs).
+
+**Research tool only — not a medical device.**
+
+## Install
+
+```bash
+pip install painface
+```
+
+## Quick Start
+
+```python
+from painface import PainFace
+
+pf = PainFace()
+
+# Load an image
+record = pf.load_image("face.jpg")
+
+# Load a video and sample frames
+meta   = pf.load_video("patient_video.mp4")
+frames = pf.sample_frames(meta, target_fps=5)
+
+print(f"Got {len(frames)} frames")
+```
+
+## Current Version (v0.1.0)
+- Image loading
+- Video loading & frame sampling
+
+More modules coming: face detection, landmarks, AU estimation, pain scoring.

painfacenet-0.1.0/README.md

@@ -0,0 +1,34 @@
+# PainFace
+
+Open-source Python framework for facial pain estimation via Action Units (AUs).
+
+**Research tool only — not a medical device.**
+
+## Install
+
+```bash
+pip install painface
+```
+
+## Quick Start
+
+```python
+from painface import PainFace
+
+pf = PainFace()
+
+# Load an image
+record = pf.load_image("face.jpg")
+
+# Load a video and sample frames
+meta   = pf.load_video("patient_video.mp4")
+frames = pf.sample_frames(meta, target_fps=5)
+
+print(f"Got {len(frames)} frames")
+```
+
+## Current Version (v0.1.0)
+- Image loading
+- Video loading & frame sampling
+
+More modules coming: face detection, landmarks, AU estimation, pain scoring.

painfacenet-0.1.0/painface/__init__.py

@@ -0,0 +1,11 @@
+"""
+PainFace — Open-source Python framework for facial pain estimation.
+Research tool only. Not a medical device.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Shariff"
+
+from painface.core import PainFace
+
+__all__ = ["PainFace"]

painfacenet-0.1.0/painface/aus/__init__.py

@@ -0,0 +1 @@
+# painface.aus

painfacenet-0.1.0/painface/core.py

@@ -0,0 +1,72 @@
+"""
+painface.core
+-------------
+PainFace — the main class.
+
+This is the "manager" of the whole pipeline.
+Eventually it will call face detection, landmarks, AUs, and pain estimation.
+Right now (Phase 1) it only handles loading images and videos.
+"""
+
+from painface.io.loader import load_image, load_video, sample_frames, FrameRecord, VideoMeta
+from typing import List, Optional
+
+
+class PainFace:
+    """
+    Main entry point for the PainFace pipeline.
+
+    Usage
+    -----
+    >>> pf = PainFace()
+    >>> record = pf.load_image("face.jpg")
+    >>> meta   = pf.load_video("video.mp4")
+    >>> frames = pf.sample_frames(meta, target_fps=5)
+    """
+
+    def __init__(self, target_fps: float = 5.0):
+        """
+        Parameters
+        ----------
+        target_fps : default frame rate used when sampling videos (default 5)
+        """
+        self.target_fps = target_fps
+        print(f"[PainFace] Ready. Default sampling rate: {target_fps} fps")
+
+    def load_image(self, path: str) -> FrameRecord:
+        """Load a single image. Returns a FrameRecord."""
+        record = load_image(path)
+        print(f"[PainFace] Loaded image: {record.image.shape[1]}x{record.image.shape[0]} px  ←  {path}")
+        return record
+
+    def load_video(self, path: str) -> VideoMeta:
+        """Load video metadata (does not read frames yet)."""
+        meta = load_video(path)
+        print(
+            f"[PainFace] Loaded video: {meta.width}x{meta.height}  |  "
+            f"{meta.fps:.1f} fps  |  {meta.duration_seconds:.1f}s  |  "
+            f"{meta.total_frames} frames  ←  {path}"
+        )
+        return meta
+
+    def sample_frames(
+        self,
+        video: VideoMeta,
+        target_fps: Optional[float] = None,
+        start_sec: Optional[float] = None,
+        end_sec: Optional[float] = None,
+    ) -> List[FrameRecord]:
+        """
+        Extract frames from a video at the target rate.
+
+        Parameters
+        ----------
+        video      : VideoMeta from load_video()
+        target_fps : frames per second to extract (uses instance default if None)
+        start_sec  : start time in seconds
+        end_sec    : end time in seconds
+        """
+        fps = target_fps or self.target_fps
+        frames = sample_frames(video, target_fps=fps, start_sec=start_sec, end_sec=end_sec)
+        print(f"[PainFace] Sampled {len(frames)} frames at {fps} fps")
+        return frames

painfacenet-0.1.0/painface/detection/__init__.py

@@ -0,0 +1 @@
+# painface.detection

painfacenet-0.1.0/painface/features/__init__.py

@@ -0,0 +1 @@
+# painface.features

painfacenet-0.1.0/painface/io/__init__.py

@@ -0,0 +1,3 @@
+from painface.io.loader import load_image, load_video, sample_frames
+
+__all__ = ["load_image", "load_video", "sample_frames"]

painfacenet-0.1.0/painface/io/loader.py

@@ -0,0 +1,220 @@
+"""
+painface.io.loader
+------------------
+Handles loading images and videos into a standard format
+that the rest of the PainFace pipeline can work with.
+
+Think of this as the "intake desk" — everything that comes
+into the system goes through here first.
+"""
+
+import os
+import numpy as np
+import cv2
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+# ── Data structures ────────────────────────────────────────────────────────────
+
+@dataclass
+class FrameRecord:
+    """
+    One frame of data moving through the pipeline.
+
+    frame_index : which frame number this is (0, 1, 2, ...)
+    timestamp   : time in seconds from the start of the video
+    image       : the actual pixel data as a NumPy array (H x W x 3, BGR)
+    source_path : where the original file came from
+    """
+    frame_index: int
+    timestamp: float          # seconds
+    image: np.ndarray         # H x W x 3, uint8, BGR
+    source_path: str = ""
+
+
+@dataclass
+class VideoMeta:
+    """
+    Basic information about a video file — before we process any frames.
+    """
+    path: str
+    total_frames: int
+    fps: float                # frames per second in the original file
+    width: int
+    height: int
+    duration_seconds: float
+
+
+# ── Image loader ───────────────────────────────────────────────────────────────
+
+def load_image(path: str) -> FrameRecord:
+    """
+    Load a single image file (JPG, PNG, etc.) and return a FrameRecord.
+
+    Parameters
+    ----------
+    path : str
+        Full path to the image file.
+
+    Returns
+    -------
+    FrameRecord
+        frame_index=0, timestamp=0.0, image as BGR NumPy array.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    ValueError
+        If the file cannot be read as an image.
+
+    Example
+    -------
+    >>> record = load_image("/path/to/face.jpg")
+    >>> record.image.shape   # (height, width, 3)
+    """
+    path = str(path)
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Image not found: {path}")
+
+    image = cv2.imread(path)
+    if image is None:
+        raise ValueError(f"Could not read image (unsupported format?): {path}")
+
+    return FrameRecord(
+        frame_index=0,
+        timestamp=0.0,
+        image=image,
+        source_path=path,
+    )
+
+
+# ── Video meta ─────────────────────────────────────────────────────────────────
+
+def load_video(path: str) -> VideoMeta:
+    """
+    Open a video file and return metadata without loading any frames yet.
+    Actual frames are pulled lazily by sample_frames().
+
+    Parameters
+    ----------
+    path : str
+        Full path to the video file (mp4, avi, mov, …).
+
+    Returns
+    -------
+    VideoMeta
+        fps, dimensions, duration, total frame count.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    ValueError
+        If OpenCV cannot open it.
+    """
+    path = str(path)
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Video not found: {path}")
+
+    cap = cv2.VideoCapture(path)
+    if not cap.isOpened():
+        raise ValueError(f"Could not open video: {path}")
+
+    fps           = cap.get(cv2.CAP_PROP_FPS) or 25.0
+    total_frames  = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    width         = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    height        = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    duration      = total_frames / fps if fps > 0 else 0.0
+    cap.release()
+
+    return VideoMeta(
+        path=path,
+        total_frames=total_frames,
+        fps=fps,
+        width=width,
+        height=height,
+        duration_seconds=duration,
+    )
+
+
+# ── Frame sampler ──────────────────────────────────────────────────────────────
+
+def sample_frames(
+    video: VideoMeta,
+    target_fps: float = 5.0,
+    start_sec: Optional[float] = None,
+    end_sec: Optional[float] = None,
+) -> List[FrameRecord]:
+    """
+    Extract frames from a video at a chosen rate.
+
+    Why not use every frame?
+    ------------------------
+    A typical video is 25-30 fps. Processing all frames is slow and mostly
+    redundant — a face doesn't change meaningfully between frame 1 and frame 2
+    at 30 fps. Sampling at 5 fps gives us one frame every 0.2 seconds, which
+    is plenty for pain analysis.
+
+    Parameters
+    ----------
+    video      : VideoMeta returned by load_video()
+    target_fps : how many frames per second to extract (default 5)
+    start_sec  : start time in seconds (None = beginning)
+    end_sec    : end time in seconds (None = end of video)
+
+    Returns
+    -------
+    List[FrameRecord]
+        One FrameRecord per sampled frame, in order.
+
+    Example
+    -------
+    >>> meta   = load_video("patient_video.mp4")
+    >>> frames = sample_frames(meta, target_fps=5)
+    >>> len(frames)
+    # roughly duration_seconds * 5
+    """
+    if target_fps <= 0:
+        raise ValueError("target_fps must be positive")
+
+    src_fps    = video.fps
+    # How many source frames to skip between each sample
+    # e.g. src_fps=30, target_fps=5  →  step=6  (take every 6th frame)
+    step       = max(1, round(src_fps / target_fps))
+
+    start_sec  = start_sec or 0.0
+    end_sec    = end_sec   or video.duration_seconds
+
+    start_frame = max(0, int(start_sec * src_fps))
+    end_frame   = min(video.total_frames, int(end_sec * src_fps))
+
+    cap = cv2.VideoCapture(video.path)
+    if not cap.isOpened():
+        raise ValueError(f"Could not open video for reading: {video.path}")
+
+    records: List[FrameRecord] = []
+    frame_idx = 0
+
+    cap.set(cv2.CAP_PROP_POS_FRAMES, start_frame)
+
+    for src_idx in range(start_frame, end_frame):
+        ret, frame = cap.read()
+        if not ret:
+            break
+
+        # Only keep this frame if it falls on our sampling interval
+        if (src_idx - start_frame) % step == 0:
+            timestamp = src_idx / src_fps
+            records.append(FrameRecord(
+                frame_index=frame_idx,
+                timestamp=round(timestamp, 4),
+                image=frame.copy(),
+                source_path=video.path,
+            ))
+            frame_idx += 1
+
+    cap.release()
+    return records

painfacenet-0.1.0/painface/landmarks/__init__.py

@@ -0,0 +1 @@
+# painface.landmarks

painfacenet-0.1.0/painface/pain/__init__.py

@@ -0,0 +1 @@
+# painface.pain

painfacenet-0.1.0/painface/utils/__init__.py

@@ -0,0 +1 @@
+# painface.utils

painfacenet-0.1.0/painfacenet.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: painfacenet
+Version: 0.1.0
+Summary: Open-source Python framework for facial pain estimation via Action Units (research only)
+Author: Shariff Naveed
+License: MIT
+Project-URL: Homepage, https://github.com/shariff-bit/PainFace
+Project-URL: Repository, https://github.com/shariff-bit/PainFace
+Keywords: pain,facial,action units,AU,computer vision,research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: requires-python
+
+# PainFace
+
+Open-source Python framework for facial pain estimation via Action Units (AUs).
+
+**Research tool only — not a medical device.**
+
+## Install
+
+```bash
+pip install painface
+```
+
+## Quick Start
+
+```python
+from painface import PainFace
+
+pf = PainFace()
+
+# Load an image
+record = pf.load_image("face.jpg")
+
+# Load a video and sample frames
+meta   = pf.load_video("patient_video.mp4")
+frames = pf.sample_frames(meta, target_fps=5)
+
+print(f"Got {len(frames)} frames")
+```
+
+## Current Version (v0.1.0)
+- Image loading
+- Video loading & frame sampling
+
+More modules coming: face detection, landmarks, AU estimation, pain scoring.

painfacenet-0.1.0/painfacenet.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+setup.py
+painface/__init__.py
+painface/core.py
+painface/aus/__init__.py
+painface/detection/__init__.py
+painface/features/__init__.py
+painface/io/__init__.py
+painface/io/loader.py
+painface/landmarks/__init__.py
+painface/pain/__init__.py
+painface/utils/__init__.py
+painfacenet.egg-info/PKG-INFO
+painfacenet.egg-info/SOURCES.txt
+painfacenet.egg-info/dependency_links.txt
+painfacenet.egg-info/requires.txt
+painfacenet.egg-info/top_level.txt
+tests/test_io.py

painfacenet-0.1.0/painfacenet.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

painfacenet-0.1.0/painfacenet.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy>=1.24
+opencv-python-headless>=4.8
+pandas>=2.0
+
+[dev]
+pytest>=7.0
+build
+twine

painfacenet-0.1.0/painfacenet.egg-info/top_level.txt

@@ -0,0 +1 @@
+painface

painfacenet-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "painfacenet"
+version = "0.1.0"
+description = "Open-source Python framework for facial pain estimation via Action Units (research only)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Shariff Naveed" }
+]
+keywords = ["pain", "facial", "action units", "AU", "computer vision", "research"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.24",
+    "opencv-python-headless>=4.8",
+    "pandas>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/shariff-bit/PainFace"
+Repository = "https://github.com/shariff-bit/PainFace"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["painface*"]

painfacenet-0.1.0/setup.cfg

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

painfacenet-0.1.0/setup.py

@@ -0,0 +1,18 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="painfacenet",
+    version="0.1.0",
+    description="Open-source Python framework for facial pain estimation (research only)",
+    author="Shariff",
+    packages=find_packages(),
+    python_requires=">=3.11",
+    install_requires=[
+        "numpy",
+        "opencv-python",
+        "pandas",
+        "torch",
+        "scikit-learn",
+        "matplotlib",
+    ],
+)

painfacenet-0.1.0/tests/test_io.py

@@ -0,0 +1,174 @@
+"""
+Tests for painface.io — image and video loading.
+
+Run with:
+    cd /Users/mohammednaveedshariff/Shariff/Research/PainFace
+    python -m pytest tests/test_io.py -v
+"""
+
+import pytest
+import numpy as np
+import cv2
+import os
+import tempfile
+from painface.io.loader import load_image, load_video, sample_frames, FrameRecord, VideoMeta
+
+
+# ── Helpers to create test files ───────────────────────────────────────────────
+
+def make_test_image(path: str, width=320, height=240):
+    """Write a small solid-colour JPG to disk."""
+    img = np.zeros((height, width, 3), dtype=np.uint8)
+    img[:] = (100, 150, 200)   # a blue-ish colour
+    cv2.imwrite(path, img)
+
+
+def make_test_video(path: str, n_frames=30, fps=15, width=320, height=240):
+    """Write a short synthetic MP4 to disk."""
+    fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+    out = cv2.VideoWriter(path, fourcc, fps, (width, height))
+    for i in range(n_frames):
+        frame = np.full((height, width, 3), i * 8 % 255, dtype=np.uint8)
+        out.write(frame)
+    out.release()
+
+
+# ── Image tests ────────────────────────────────────────────────────────────────
+
+class TestLoadImage:
+
+    def test_returns_frame_record(self, tmp_path):
+        img_path = str(tmp_path / "test.jpg")
+        make_test_image(img_path)
+        record = load_image(img_path)
+        assert isinstance(record, FrameRecord)
+
+    def test_correct_shape(self, tmp_path):
+        img_path = str(tmp_path / "test.jpg")
+        make_test_image(img_path, width=320, height=240)
+        record = load_image(img_path)
+        assert record.image.shape == (240, 320, 3)
+
+    def test_frame_index_is_zero(self, tmp_path):
+        img_path = str(tmp_path / "test.jpg")
+        make_test_image(img_path)
+        record = load_image(img_path)
+        assert record.frame_index == 0
+
+    def test_timestamp_is_zero(self, tmp_path):
+        img_path = str(tmp_path / "test.jpg")
+        make_test_image(img_path)
+        record = load_image(img_path)
+        assert record.timestamp == 0.0
+
+    def test_source_path_stored(self, tmp_path):
+        img_path = str(tmp_path / "test.jpg")
+        make_test_image(img_path)
+        record = load_image(img_path)
+        assert record.source_path == img_path
+
+    def test_missing_file_raises(self):
+        with pytest.raises(FileNotFoundError):
+            load_image("/this/does/not/exist.jpg")
+
+    def test_invalid_file_raises(self, tmp_path):
+        bad = str(tmp_path / "fake.jpg")
+        with open(bad, "w") as f:
+            f.write("this is not an image")
+        with pytest.raises(ValueError):
+            load_image(bad)
+
+
+# ── Video meta tests ───────────────────────────────────────────────────────────
+
+class TestLoadVideo:
+
+    def test_returns_video_meta(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15)
+        meta = load_video(vid_path)
+        assert isinstance(meta, VideoMeta)
+
+    def test_fps_correct(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15)
+        meta = load_video(vid_path)
+        assert abs(meta.fps - 15.0) < 1.0   # allow small codec rounding
+
+    def test_dimensions_correct(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15, width=320, height=240)
+        meta = load_video(vid_path)
+        assert meta.width == 320
+        assert meta.height == 240
+
+    def test_duration_reasonable(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15)
+        meta = load_video(vid_path)
+        # 30 frames at 15 fps = 2 seconds
+        assert abs(meta.duration_seconds - 2.0) < 0.5
+
+    def test_missing_file_raises(self):
+        with pytest.raises(FileNotFoundError):
+            load_video("/no/such/video.mp4")
+
+
+# ── Frame sampler tests ────────────────────────────────────────────────────────
+
+class TestSampleFrames:
+
+    def test_returns_list_of_frame_records(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15)
+        meta = load_video(vid_path)
+        frames = sample_frames(meta, target_fps=5)
+        assert isinstance(frames, list)
+        assert all(isinstance(f, FrameRecord) for f in frames)
+
+    def test_fewer_frames_than_original(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15)
+        meta = load_video(vid_path)
+        frames = sample_frames(meta, target_fps=5)
+        # At 5fps from a 15fps video we expect roughly 1/3 the frames
+        assert len(frames) < meta.total_frames
+
+    def test_frame_indices_are_sequential(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15)
+        meta = load_video(vid_path)
+        frames = sample_frames(meta, target_fps=5)
+        indices = [f.frame_index for f in frames]
+        assert indices == list(range(len(frames)))
+
+    def test_timestamps_are_increasing(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15)
+        meta = load_video(vid_path)
+        frames = sample_frames(meta, target_fps=5)
+        timestamps = [f.timestamp for f in frames]
+        assert all(t2 >= t1 for t1, t2 in zip(timestamps, timestamps[1:]))
+
+    def test_each_frame_has_correct_shape(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=30, fps=15, width=320, height=240)
+        meta = load_video(vid_path)
+        frames = sample_frames(meta, target_fps=5)
+        for f in frames:
+            assert f.image.shape == (240, 320, 3)
+
+    def test_invalid_fps_raises(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=10, fps=15)
+        meta = load_video(vid_path)
+        with pytest.raises(ValueError):
+            sample_frames(meta, target_fps=0)
+
+    def test_start_end_sec_respected(self, tmp_path):
+        vid_path = str(tmp_path / "test.mp4")
+        make_test_video(vid_path, n_frames=60, fps=15)
+        meta = load_video(vid_path)
+        full   = sample_frames(meta, target_fps=5)
+        clipped = sample_frames(meta, target_fps=5, start_sec=0.0, end_sec=1.0)
+        assert len(clipped) < len(full)