🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
DemoInstallSign in
Socket

sharp-frames

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

sharp-frames

Extract, score, and select the best frames from a video or image directory

0.1.3
PyPI
Maintainers
1

Sharp Frames Python

Extracts frames from a video or processes images from a directory, scores them for sharpness, and selects the best frames based on various methods. This script is using the same selection methods as found in the Sharp Frames application by Reflct. For the full version, go to Sharp Frames, or join our Discord for access to the beta windows version.

Requirements

  • Python 3.6 or higher
  • OpenCV (opencv-python) - Installed automatically with pip
  • NumPy - Installed automatically with pip
  • tqdm (for progress visualization) - Installed automatically with pip
  • FFmpeg (required only for video input, must be installed and in your system PATH)
  • FFprobe (optional, recommended for video input to determine duration, must be in PATH)

Installation

Install via pip

pip install sharp-frames

Or use pipx for an isolated installation:

pipx install sharp-frames

Important: FFmpeg must be installed separately for video processing. The pip/pipx installation does NOT include FFmpeg.

  • Windows: Download from FFmpeg website and add ffmpeg.exe to your PATH.
  • macOS (with Homebrew): brew install ffmpeg
  • Linux (Debian/Ubuntu): sudo apt update && sudo apt install ffmpeg

Usage

sharp-frames --interactive  # Interactive mode
sharp-frames <input_path> <output_directory> [options]  # With arguments

Arguments

  • <input_path>: Path to the input video file or a directory containing image files (.jpg, .jpeg, .png).
  • <output_directory>: Directory to save selected frames/images (will be created if it doesn't exist).

Options

  • --fps <int>: Frames per second to extract (video input only, default: 10).
  • --format <jpg|png>: Output image format for saved files (default: jpg).
  • --width <int>: Width to resize output images (height will be adjusted proportionally, 0 for no resizing, default: 0).
  • --force-overwrite: Overwrite existing files in the output directory without confirmation.
  • --interactive: Run in interactive mode, prompting for all options.

Selection Method Options:

  • --selection-method <best-n|batched|outlier-removal>: Choose the frame selection algorithm (default: best-n).

    • For best-n (default): Selects a target number of frames (--num-frames) aiming for the sharpest images while maintaining a minimum distance (--min-buffer) between selections. It uses a two-pass approach to balance sharpness and distribution across the source material.

      • --num-frames <int>: Number of frames/images to select (default: 300).
      • --min-buffer <int>: Minimum frame index gap between selected items (default: 3).
    • For batched: Divides the frames/images into batches of a specified size (--batch-size) and selects the single sharpest frame from each batch. A buffer (--batch-buffer) can be added to skip frames between batches.

      • --batch-size <int>: Number of frames/images in each analysis batch (default: 5). The best frame from each batch is selected.
      • --batch-buffer <int>: Number of frames/images to skip between batches (default: 2).
    • For outlier-removal: Analyzes each frame's sharpness relative to its neighbors within a window (--outlier-window-size). Frames significantly less sharp than their neighbors (controlled by --outlier-sensitivity) are considered outliers and are not selected. This method keeps all frames except those identified as outliers.

      • --outlier-window-size <int>: Number of neighboring frames to compare against (default: 15, must be odd).
      • --outlier-sensitivity <int>: How aggressively to remove outliers (0-100, higher means more removal, default: 50).

Cancelling the Process

  • You can safely cancel the process at any time by pressing Ctrl+C.
  • The script will attempt to clean up temporary files (if any were created).

Examples

Basic video usage (best-n)

sharp-frames my_video.mp4 ./selected_video_frames

(Extracts 10fps, selects 300 best frames with buffer 3)

Directory usage (best-n)

sharp-frames ./image_folder ./selected_dir_images --num-frames 50 --min-buffer 1

(Processes images in ./image_folder, selects the best 50 with buffer 1)

Video usage (batched)

sharp-frames my_video.mp4 ./selected_batched --selection-method batched --batch-size 10 --batch-buffer 2

(Selects the best frame from batches of 10, skipping 2 frames between batches)

Video usage with resizing

sharp-frames my_video.mp4 ./resized_frames --width 800

(Extracts frames at 10fps, resizes to 800px width while maintaining aspect ratio, selects 300 best frames)

Directory usage (outlier removal)

sharp-frames ./image_folder ./selected_outliers --selection-method outlier-removal --outlier-sensitivity 75

(Processes images, removing frames considered outliers with 75% sensitivity)

Interactive mode

sharp-frames --interactive

(Prompts for input path, output path, and all relevant options)

Features

  • Flexible Input: Process video files or directories of images.
  • Multiple Selection Methods: Choose between best-n, batched, or outlier-removal algorithms.
  • Image Resizing: Resize output images to a custom width while maintaining aspect ratio.
  • Interactive Mode: Easy-to-use prompts for configuration without CLI arguments.
  • Progress Visualization: Real-time progress bars for dependencies, extraction (video), sharpness calculation, selection, and saving.
  • Parallel Processing: Utilizes multiple CPU cores for faster sharpness calculation.
  • Memory Efficiency: Handles large numbers of frames/images effectively.
  • Interruptible: Can be safely cancelled using Ctrl+C.
  • Cross-Platform: Designed to work on Windows, macOS, and Linux (with dependencies installed).

How it works

  • Setup: Checks dependencies, prepares the output directory.
  • Input Loading:
    • Video: Uses FFmpeg to extract frames at the specified fps into a temporary directory.
    • Directory: Scans the input directory for supported image files.
  • Sharpness Calculation: Calculates sharpness scores (Laplacian variance) for all frames/images in parallel.
  • Frame Selection: Selects frames based on the chosen selection-method and its parameters.
  • Output: Copies selected frames/images to the output directory with informative filenames. Saves a metadata JSON file summarizing the process.

Output

  • Selected frames/images saved to the output directory.
  • Metadata file (selected_metadata.json) with information about the input, selection parameters, and a list of selected items including their original index and sharpness score.

Keywords

video

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts