distant-frames 0.1.0__tar.gz → 0.3.1__tar.gz

{distant_frames-0.1.0 → distant_frames-0.3.1}/.github/workflows/publish.yml

@@ -2,8 +2,8 @@ name: Publish to PyPI
 
 on:
   push:
-    tags:
-      - 'v*.*.*'
+    branches:
+      - main
 
 jobs:
   build-and-publish:

{distant_frames-0.1.0 → distant_frames-0.3.1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: distant-frames
-Version: 0.1.0
+Version: 0.3.1
 Summary: Smart video frame extraction tool
 Project-URL: Homepage, https://github.com/yubraaj11/distant-frames
 Project-URL: Repository, https://github.com/yubraaj11/distant-frames
 Project-URL: Issues, https://github.com/yubraaj11/distant-frames/issues
+Project-URL: ReleaseNotes, https://github.com/yubraaj11/distant-frames/blob/main/RELEASE_NOTES.md
 Author-email: Yubraj Sigdel <yubrajsigdel1@gmail.com>
 License: GPL-3.0-or-later
 License-File: LICENSE
@@ -18,8 +19,15 @@ Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Requires-Dist: opencv-python>=4.10.0
+Requires-Dist: typer>=0.9.0
 Description-Content-Type: text/markdown
 
+![PyPI - Version](https://img.shields.io/pypi/v/distant-frames)
+![PyPI - Status](https://img.shields.io/pypi/status/distant-frames)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/distant-frames)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/distant-frames)
+![GitHub License](https://img.shields.io/github/license/yubraaj11/distant-frames)
+
 # Distant Frames
 
 **Distant Frames** is a smart video frame extraction tool designed to capture distinct visual moments from video files. Instead of simply saving every Nth frame, it analyzes the visual similarity between consecutive potential frames and only saves those that are sufficiently different.
@@ -30,6 +38,8 @@ Description-Content-Type: text/markdown
 - **Histogram Correlation**: Uses HSV color space histogram comparison for robust similarity detection.
 - **Configurable Threshold**: Fine-tune the sensitivity of frame dropping to suit your specific video content.
 - **Efficient Processing**: Seeks directly to target timestamps (`CAP_PROP_POS_FRAMES`) for faster processing than frame-by-frame reading.
+- **Custom Start Time**: Begin extraction from any point in the video using a timestamp in seconds.
+- **Open Eyes Filter**: Optionally keep only frames where at least one face with both eyes open is detected, using local Haar cascade classifiers.
 
 ## 🛠️ Prerequisites
 
@@ -50,9 +60,9 @@ or
 uv add distant-frames
 ```
 
-### From Source (Development)
+### From Source (Local)
 
-For development or to use the latest unreleased features:
+Clone the repo and run directly without installing the package:
 
 1. **Clone the repository:**
    ```bash
@@ -60,18 +70,28 @@ For development or to use the latest unreleased features:
    cd distant-frames
    ```
 
-2. **Install Dependencies:**
+2. **Install dependencies:**
    ```bash
    uv sync --frozen
    ```
 
+3. **Run via `main.py`:**
+   ```bash
+   uv run main.py path/to/video.mp4 -o output_dir -t 0.75
+   ```
+
 ## 💻 Usage
 
-### Basic Command
-Run the script by providing the path to your video file:
+### Installed package
+
+```bash
+distant-frames path/to/video.mp4 -o path/to/output -t 0.75
+```
+
+### Cloned repo (no install)
 
 ```bash
-uv run distant_frames/cli.py path/to/your/video.mp4
+uv run main.py path/to/video.mp4 -o path/to/output -t 0.75
 ```
 
 ### Options
@@ -79,34 +99,47 @@ uv run distant_frames/cli.py path/to/your/video.mp4
 | Argument | Description | Default |
 |----------|-------------|---------|
 | `video_path` | Path to the input video file (Required). | N/A |
-| `--output` | Directory to save the extracted frames. | `extracted_frames` |
-| `--threshold` | Similarity threshold (0.0 to 1.0). Frames with similarity **higher** than this value compared to the last saved frame will be **dropped**. | `0.65` |
+| `--output`, `-o` | Directory to save the extracted frames. | `extracted_frames` |
+| `--threshold`, `-t` | Similarity score threshold (0.0 to 1.0). Frames with a score **higher** than this value are discarded. | `0.65` |
+| `--start`, `-s` | Timestamp in seconds to begin extraction from. | `0.0` |
+| `--open-eyes` | When set, only saves frames where at least one face with both eyes open is detected. | Off |
 
 ### Examples
 
 **Extract frames with default settings:**
 ```bash
-uv run distant_frames/cli.py my_vacation.mp4
+distant-frames my_vacation.mp4
+```
+
+**Save to a custom folder with a stricter similarity check:**
+```bash
+distant-frames my_vacation.mp4 -o best_shots -t 0.95
+```
+
+**Start extraction from a specific timestamp (e.g. 1 minute 30 seconds in):**
+```bash
+distant-frames interview.mp4 -s 90
 ```
 
-**Save to a custom folder with a stricter similarity check (fewer frames):**
+**Only keep frames where a person's eyes are open:**
 ```bash
-uv run distant_frames/cli.py my_vacation.mp4 --output best_shots --threshold 0.95
+distant-frames interview.mp4 --open-eyes -o key_frames
 ```
 
-**Save more frames (looser similarity check):**
+**Combine all options:**
 ```bash
-uv run distant_frames/cli.py my_vacation.mp4 --output all_shots --threshold 0.6
+distant-frames interview.mp4 -s 90 -t 0.80 --open-eyes -o key_frames
 ```
 
 ## 🔍 How It Works
 
-1. **Sampling**: The script checks one frame every second (based on the video's FPS).
+1. **Sampling**: The script checks one frame every second (based on the video's FPS), starting from `--start` if provided.
 2. **Comparison**: It compares the current candidate frame against the **last successfully saved frame**.
 3. **Algorithm**: It converts frames to HSV color space and calculates Normalized Histogram Correlation.
 4. **Decision**:
-   - If similarity < `threshold`: **SAVE** (The scene has changed).
+   - If similarity < `threshold`: candidate for saving.
    - If similarity >= `threshold`: **SKIP** (The scene is too similar).
+5. **Open Eyes Filter** *(optional)*: If `--open-eyes` is set, a candidate frame is only saved if a face with two open eyes is detected using Haar cascade classifiers.
 
 ## 🧪 Testing
 

distant_frames-0.3.1/README.md

@@ -0,0 +1,129 @@
+![PyPI - Version](https://img.shields.io/pypi/v/distant-frames)
+![PyPI - Status](https://img.shields.io/pypi/status/distant-frames)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/distant-frames)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/distant-frames)
+![GitHub License](https://img.shields.io/github/license/yubraaj11/distant-frames)
+
+# Distant Frames
+
+**Distant Frames** is a smart video frame extraction tool designed to capture distinct visual moments from video files. Instead of simply saving every Nth frame, it analyzes the visual similarity between consecutive potential frames and only saves those that are sufficiently different.
+
+## 🚀 Features
+
+- **Smart Deduplication**: Avoids saving redundant frames where the scene hasn't changed.
+- **Histogram Correlation**: Uses HSV color space histogram comparison for robust similarity detection.
+- **Configurable Threshold**: Fine-tune the sensitivity of frame dropping to suit your specific video content.
+- **Efficient Processing**: Seeks directly to target timestamps (`CAP_PROP_POS_FRAMES`) for faster processing than frame-by-frame reading.
+- **Custom Start Time**: Begin extraction from any point in the video using a timestamp in seconds.
+- **Open Eyes Filter**: Optionally keep only frames where at least one face with both eyes open is detected, using local Haar cascade classifiers.
+
+## 🛠️ Prerequisites
+
+- **Python**: 3.12 or higher
+- **Dependencies**: `opencv-python`
+
+## 📦 Installation
+
+### From PyPI (Recommended)
+
+Install the latest stable release using pip:
+
+```bash
+pip install distant-frames
+
+or 
+
+uv add distant-frames
+```
+
+### From Source (Local)
+
+Clone the repo and run directly without installing the package:
+
+1. **Clone the repository:**
+   ```bash
+   git clone git@github.com:yubraaj11/distant-frames.git
+   cd distant-frames
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   uv sync --frozen
+   ```
+
+3. **Run via `main.py`:**
+   ```bash
+   uv run main.py path/to/video.mp4 -o output_dir -t 0.75
+   ```
+
+## 💻 Usage
+
+### Installed package
+
+```bash
+distant-frames path/to/video.mp4 -o path/to/output -t 0.75
+```
+
+### Cloned repo (no install)
+
+```bash
+uv run main.py path/to/video.mp4 -o path/to/output -t 0.75
+```
+
+### Options
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `video_path` | Path to the input video file (Required). | N/A |
+| `--output`, `-o` | Directory to save the extracted frames. | `extracted_frames` |
+| `--threshold`, `-t` | Similarity score threshold (0.0 to 1.0). Frames with a score **higher** than this value are discarded. | `0.65` |
+| `--start`, `-s` | Timestamp in seconds to begin extraction from. | `0.0` |
+| `--open-eyes` | When set, only saves frames where at least one face with both eyes open is detected. | Off |
+
+### Examples
+
+**Extract frames with default settings:**
+```bash
+distant-frames my_vacation.mp4
+```
+
+**Save to a custom folder with a stricter similarity check:**
+```bash
+distant-frames my_vacation.mp4 -o best_shots -t 0.95
+```
+
+**Start extraction from a specific timestamp (e.g. 1 minute 30 seconds in):**
+```bash
+distant-frames interview.mp4 -s 90
+```
+
+**Only keep frames where a person's eyes are open:**
+```bash
+distant-frames interview.mp4 --open-eyes -o key_frames
+```
+
+**Combine all options:**
+```bash
+distant-frames interview.mp4 -s 90 -t 0.80 --open-eyes -o key_frames
+```
+
+## 🔍 How It Works
+
+1. **Sampling**: The script checks one frame every second (based on the video's FPS), starting from `--start` if provided.
+2. **Comparison**: It compares the current candidate frame against the **last successfully saved frame**.
+3. **Algorithm**: It converts frames to HSV color space and calculates Normalized Histogram Correlation.
+4. **Decision**:
+   - If similarity < `threshold`: candidate for saving.
+   - If similarity >= `threshold`: **SKIP** (The scene is too similar).
+5. **Open Eyes Filter** *(optional)*: If `--open-eyes` is set, a candidate frame is only saved if a face with two open eyes is detected using Haar cascade classifiers.
+
+## 🧪 Testing
+
+You can generate a test video to verify the functionality:
+
+```bash
+uv run generate_test_video.py
+uv run main.py test_video.mp4
+```
+
+This will create a `test_video.mp4` with known scene changes and then extract frames from it, demonstrating the deduplication logic.

distant_frames-0.3.1/RELEASE_NOTES.md

@@ -0,0 +1,126 @@
+# Release Notes
+
+## Version 0.3.1
+
+### Fix
+
+- **Local entry point**: Added `main.py` at the repo root so users who clone the repository can run the tool directly with `uv run main.py` without installing the package.
+
+---
+
+## Version 0.3.0
+
+### New Features
+
+- **Start timestamp** (`--start` / `-s`): Begin extraction from any point in the video by passing a timestamp in seconds. The video duration is validated upfront, and the startup log now shows duration and the effective start time.
+
+- **Open-eyes filter** (`--open-eyes`): When enabled, only frames where at least one face with both eyes open is detected are saved. Detection uses a two-stage Haar cascade pipeline (face → eye ROI) and runs only on frames that have already passed the similarity check, so it adds no overhead on skipped frames.
+
+- **Local Haar cascade classifiers**: Cascade XML files are now loaded from the project-local `haarcascade_classifiers/` directory (`haarcascade_frontalface_default.xml` and `haarcascade_eye.xml`) instead of the OpenCV bundle. No new dependencies are required.
+
+### Usage Examples
+
+**Start from 90 seconds in:**
+```bash
+distant-frames interview.mp4 -s 90
+```
+
+**Only keep frames with open eyes:**
+```bash
+distant-frames interview.mp4 --open-eyes -o key_frames
+```
+
+**Combine all options:**
+```bash
+distant-frames interview.mp4 -s 90 -t 0.80 --open-eyes -o key_frames
+```
+
+---
+
+## Version 0.2.1
+
+### Updated File Name
+
+- **Concise Filenames**: Extracted frames now use a shortened 8-character UUID (e.g., `_frame_a1b2c3d4.jpg`) instead of the full 32-character UUID. This ensures uniqueness while keeping filenames cleaner and easier to manage.
+
+## Version 0.2.0 
+
+### 🎨 Enhanced CLI Interface
+
+We've completely redesigned the command-line interface using **Typer** for a significantly improved user experience!
+
+#### ✨ New Features
+
+- **Rich Terminal Output**: Beautiful, formatted help text with tables and color-coded sections
+- **Short Option Flags**: Added convenient shortcuts:
+  - `-o` for `--output`
+  - `-t` for `--threshold`
+- **Automatic Validation**: Built-in input validation with helpful error messages
+  - File existence checking before processing
+  - Threshold range validation (0.0-1.0)
+  - Readable file verification
+
+#### 🔧 Improvements
+
+- **Better Help Messages**: Clear, comprehensive help text with detailed parameter descriptions
+- **Type Safety**: Full type hints for all CLI parameters with automatic validation
+- **Enhanced Error Handling**: User-friendly error messages with suggestions and proper formatting
+- **Cleaner Code**: More maintainable and declarative CLI implementation
+
+#### 📦 Dependencies
+
+- Added `typer>=0.9.0` for improved CLI functionality
+
+#### 🎯 Usage Examples
+
+**Basic usage:**
+```bash
+distant-frames video.mp4
+```
+
+**With custom output directory:**
+```bash
+distant-frames video.mp4 -o my_frames
+```
+
+**With custom threshold:**
+```bash
+distant-frames video.mp4 -t 0.8
+```
+
+**Combined options:**
+```bash
+distant-frames video.mp4 -o output_frames -t 0.7
+```
+
+**View help:**
+```bash
+distant-frames --help
+```
+
+#### 🐛 Bug Fixes
+
+- Improved error messages when video file is not found
+- Better validation for threshold parameter values
+
+#### ⚠️ Breaking Changes
+
+None - the CLI interface remains backward compatible with existing usage patterns.
+
+---
+
+## Version 0.1.2
+
+### Features
+
+- Smart frame extraction with similarity-based deduplication
+- Fallback mechanism for gradual scene changes
+- Verbose logging for debugging
+- HSV-based histogram comparison for robust similarity detection
+
+### Core Functionality
+
+- Extract frames at 1-second intervals
+- Skip similar frames based on configurable threshold
+- Automatic output directory creation
+- Detailed frame-by-frame logging

distant_frames-0.3.1/distant_frames/cli.py

@@ -0,0 +1,64 @@
+import typer
+from pathlib import Path
+from typing_extensions import Annotated
+from distant_frames.core import extract_frames
+
+app = typer.Typer(
+    help="Smart video frame extraction tool with similarity-based deduplication.",
+    add_completion=False,
+)
+
+@app.command()
+def main(
+    video_path: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to the input video file",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        )
+    ],
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output", "-o",
+            help="Output directory for extracted frames"
+        )
+    ] = "extracted_frames",
+    threshold: Annotated[
+        float,
+        typer.Option(
+            "--threshold", "-t",
+            min=0.0,
+            max=1.0,
+            help="Similarity threshold (0.0-1.0). Higher values mean stricter deduplication (fewer frames saved)."
+        )
+    ] = 0.75,
+    start_time: Annotated[
+        float,
+        typer.Option(
+            "--start", "-s",
+            min=0.0,
+            help="Start extraction from this timestamp (in seconds). Defaults to 0 (beginning of video)."
+        )
+    ] = 0.0,
+    open_eyes_only: Annotated[
+        bool,
+        typer.Option(
+            "--open-eyes",
+            help="Only save frames where at least one face with both eyes open is detected."
+        )
+    ] = False,
+):
+    """
+    Extract distinct frames from a video file based on visual similarity.
+
+    The tool samples the video at 1-second intervals and compares consecutive frames.
+    Frames that are too similar to previously saved frames are automatically skipped.
+    """
+    extract_frames(str(video_path), output, threshold, start_time, open_eyes_only)
+
+if __name__ == "__main__":
+    app()

distant_frames-0.3.1/distant_frames/core.py

@@ -0,0 +1,192 @@
+import cv2
+import os
+from pathlib import Path
+import uuid
+
+_CASCADES_DIR = Path(__file__).parent / "haarcascade_classifiers"
+
+def _load_eye_cascades():
+    """Load and return (face_cascade, eye_cascade) from the local haarcascade_classifiers/ directory."""
+    face_path = str(_CASCADES_DIR / "haarcascade_frontalface_default.xml")
+    eye_path = str(_CASCADES_DIR / "haarcascade_eye.xml")
+    face_cascade = cv2.CascadeClassifier(face_path)
+    eye_cascade = cv2.CascadeClassifier(eye_path)
+    if face_cascade.empty() or eye_cascade.empty():
+        raise RuntimeError(
+            f"Failed to load Haar cascade classifiers from {_CASCADES_DIR}. "
+            "Ensure haarcascade_frontalface_default.xml and haarcascade_eye.xml exist there."
+        )
+    return face_cascade, eye_cascade
+
+def has_open_eyes(frame, face_cascade, eye_cascade):
+    """Return True if at least one face with two detected (open) eyes is found in the frame."""
+    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))
+    for (x, y, w, h) in faces:
+        roi = gray[y:y + h, x:x + w]
+        eyes = eye_cascade.detectMultiScale(roi, scaleFactor=1.1, minNeighbors=5)
+        if len(eyes) >= 2:
+            return True
+    return False
+
+def calculate_similarity(frame1, frame2):
+    """Calculates similarity between two frames using Histogram Correlation.
+
+    Converts frames to HSV color space and compares their normalized histograms.
+    This method is generally robust to lighting changes.
+
+    Args:
+        frame1: The first video frame (BGR image/numpy array).
+        frame2: The second video frame (BGR image/numpy array).
+
+    Returns:
+        float: A similarity score between 0.0 (distinct) and 1.0 (identical).
+    """
+    # Convert to HSV for better color handling, or Gray if color doesn't matter much.
+    # HSV is generally more robust to lighting changes than BGR.
+    hsv1 = cv2.cvtColor(frame1, cv2.COLOR_BGR2HSV)
+    hsv2 = cv2.cvtColor(frame2, cv2.COLOR_BGR2HSV)
+
+    # Calculate histograms
+    # Channels 0 and 1 (Hue and Saturation) are usually enough
+    hist1 = cv2.calcHist([hsv1], [0, 1], None, [180, 256], [0, 180, 0, 256])
+    hist2 = cv2.calcHist([hsv2], [0, 1], None, [180, 256], [0, 180, 0, 256])
+
+    # Normalize histograms
+    cv2.normalize(hist1, hist1, 0, 1, cv2.NORM_MINMAX)
+    cv2.normalize(hist2, hist2, 0, 1, cv2.NORM_MINMAX)
+
+    # Compare histograms
+    similarity = cv2.compareHist(hist1, hist2, cv2.HISTCMP_CORREL)
+    return similarity
+
+def extract_frames(video_path, output_folder, threshold=0.65, start_time=0.0, open_eyes_only=False):
+    """Extracts distinct frames from a video file based on visual similarity.
+
+    The function samples the video at 1-second intervals starting from
+    `start_time`. It compares the current frame with the last saved frame.
+    If the similarity score is below the specified threshold, the frame is
+    considered distinct and saved.
+
+    If a frame is skipped (similar to the last saved frame), the next comparison
+    will be performed against the *previous* saved frame (if available) to ensure
+    robustness against gradual changes or local similarities.
+
+    Args:
+        video_path (str): Path to the input video file.
+        output_folder (str): Directory where extracted frames will be saved.
+            The directory will be created if it does not exist.
+        threshold (float, optional): Similarity threshold (0.0 to 1.0).
+            Frames with similarity higher than this value regarding the last
+            saved frame will be dropped. Defaults to 0.65.
+        start_time (float, optional): Timestamp in seconds from which to begin
+            extraction. Defaults to 0.0 (beginning of video).
+        open_eyes_only (bool, optional): When True, only frames where at least
+            one face with two open eyes is detected are saved. Uses OpenCV
+            Haar cascade classifiers. Defaults to False.
+
+    Returns:
+        None
+    """
+    if not os.path.exists(video_path):
+        print(f"Error: Video file not found at {video_path}")
+        return
+
+    if not os.path.exists(output_folder):
+        os.makedirs(output_folder)
+
+    face_cascade, eye_cascade = (_load_eye_cascades() if open_eyes_only else (None, None))
+
+    video_file_name = Path(video_path).stem
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        print("Error: Could not open video.")
+        return
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    if fps == 0:
+        print("Error: Could not retrieve FPS.")
+        return
+
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    duration = total_frames / fps
+    if start_time >= duration:
+        print(f"Error: start_time ({start_time:.1f}s) is beyond the video duration ({duration:.1f}s).")
+        cap.release()
+        return
+
+    print(f"Video FPS: {fps} | Duration: {duration:.1f}s | Starting at: {start_time:.1f}s")
+
+    # We want to check frames every 1 second
+    frame_interval = int(fps)
+
+    current_frame_idx = int(start_time * fps)
+    saved_count = 0
+    last_saved_frame = None
+    last_saved_timestamp = None
+    skip_reference_frame = None
+    skip_reference_timestamp = None
+
+    while True:
+        # Set position to the next second
+        # Note: Setting pos_frames is faster than reading every frame
+        cap.set(cv2.CAP_PROP_POS_FRAMES, current_frame_idx)
+        
+        ret, frame = cap.read()
+        if not ret:
+            break
+
+        timestamp = current_frame_idx / fps
+        should_save = False
+
+        if last_saved_frame is None:
+            should_save = True
+            similarity = 0.0 # No previous frame
+            print(f"[{timestamp:.1f}s] First frame → SAVE")
+        else:
+            # Determine reference frame
+            # If we have a skip reference (from previous skip), use that
+            # Otherwise use the last saved frame
+            if skip_reference_frame is not None:
+                reference_frame = skip_reference_frame
+                ref_timestamp = skip_reference_timestamp
+                ref_label = "skip_ref"
+            else:
+                reference_frame = last_saved_frame
+                ref_timestamp = last_saved_timestamp
+                ref_label = "last"
+
+            similarity = calculate_similarity(reference_frame, frame)
+            
+            if similarity < threshold:
+                should_save = True
+                print(f"[{timestamp:.1f}s] vs {ref_label}@{ref_timestamp:.1f}s | sim={similarity:.3f} → SAVE")
+                # Clear skip reference when we save
+                skip_reference_frame = None
+                skip_reference_timestamp = None
+            else:
+                print(f"[{timestamp:.1f}s] vs {ref_label}@{ref_timestamp:.1f}s | sim={similarity:.3f} → SKIP")
+                # When we skip, set the skip reference to the last saved frame
+                # so next comparison uses this same reference
+                skip_reference_frame = last_saved_frame
+                skip_reference_timestamp = last_saved_timestamp
+
+        if should_save and open_eyes_only:
+            if not has_open_eyes(frame, face_cascade, eye_cascade):
+                print(f"[{timestamp:.1f}s] Open-eyes check failed → SKIP")
+                should_save = False
+
+        if should_save:
+            output_filename = os.path.join(output_folder, f"{video_file_name}_frame_{uuid.uuid4().hex[:8]}.jpg")
+            cv2.imwrite(output_filename, frame)
+            
+            # Update last saved frame
+            last_saved_frame = frame
+            last_saved_timestamp = timestamp
+            
+            saved_count += 1
+
+        current_frame_idx += frame_interval
+
+    cap.release()
+    print(f"Done. Extracted {saved_count} frames.")