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

{distant_frames-0.2.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.2.0 → distant_frames-0.3.1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: distant-frames
-Version: 0.2.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
@@ -21,6 +22,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.
@@ -31,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
 
@@ -51,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
@@ -61,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
@@ -80,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.2.0 → distant_frames-0.3.1}/RELEASE_NOTES.md

@@ -1,6 +1,49 @@
 # Release Notes
 
-## Version 0.2.0 (Upcoming)
+## 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
 

{distant_frames-0.2.0 → distant_frames-0.3.1}/distant_frames/cli.py

@@ -35,15 +35,30 @@ def main(
             max=1.0,
             help="Similarity threshold (0.0-1.0). Higher values mean stricter deduplication (fewer frames saved)."
         )
-    ] = 0.65,
+    ] = 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)
+    extract_frames(str(video_path), output, threshold, start_time, open_eyes_only)
 
 if __name__ == "__main__":
     app()

{distant_frames-0.2.0 → distant_frames-0.3.1}/distant_frames/core.py

@@ -1,5 +1,33 @@
 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.
@@ -32,13 +60,14 @@ def calculate_similarity(frame1, frame2):
     similarity = cv2.compareHist(hist1, hist2, cv2.HISTCMP_CORREL)
     return similarity
 
-def extract_frames(video_path, output_folder, threshold=0.65):
+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. 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.
-    
+    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.
@@ -49,8 +78,12 @@ def extract_frames(video_path, output_folder, threshold=0.65):
             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. Higher values mean stricter
-            deduplication (fewer frames saved). Defaults to 0.65.
+            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
@@ -62,7 +95,10 @@ def extract_frames(video_path, output_folder, threshold=0.65):
     if not os.path.exists(output_folder):
         os.makedirs(output_folder)
 
-    cap = cv2.VideoCapture(video_path)
+    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
@@ -72,12 +108,19 @@ def extract_frames(video_path, output_folder, threshold=0.65):
         print("Error: Could not retrieve FPS.")
         return
 
-    print(f"Video FPS: {fps}")
-    
+    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 = 0
+
+    current_frame_idx = int(start_time * fps)
     saved_count = 0
     last_saved_frame = None
     last_saved_timestamp = None
@@ -128,8 +171,13 @@ def extract_frames(video_path, output_folder, threshold=0.65):
                 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"frame_{timestamp:.2f}.jpg")
+            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