| Name | sharp-frames JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Extract, score, and select the best frames from a video or image directory |
| upload_time | 2025-08-28 19:43:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
video
frames
sharpness
image-processing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Sharp Frames Python
Extract and select the sharpest frames from videos or directories of images using advanced sharpness scoring algorithms. Features a modern text-based interface for easy configuration and powerful command-line options for automation.
## Installation
```bash
pip install sharp-frames
```
Or with pipx for isolated installation:
```bash
pipx install sharp-frames
```
**IMPORTANT: Video Processing Requirement**: Install FFmpeg separately for video input support.
- **Windows**: Download from [FFmpeg website](https://ffmpeg.org/download.html) and add to PATH
- **macOS**: `brew install ffmpeg`
- **Linux**: `sudo apt install ffmpeg`
## Quick Start
### Modern Interface (Default)
```bash
sharp-frames
```
Launches an intuitive step-by-step wizard for configuring your processing options.
### Direct Processing
```bash
sharp-frames input_video.mp4 output_folder
sharp-frames image_directory output_folder
```
## Usage Modes
### Interactive Configuration
- **Fancy UI**: `sharp-frames` (default) - Step-by-step with validation
- **Legacy**: `sharp-frames --interactive` - Terminal prompts for all options
### Direct Processing
```bash
sharp-frames <input> <output> [options]
```
**Input Types:**
- Video files: `.mp4`, `.avi`, `.mov`, `.mkv`, `.wmv`, `.flv`, `.webm`, `.m4v`, etc.
- Video directories: Processes all videos in a folder
- Image directories: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff`, `.webp`, etc.
## Selection Methods
### Best-N (Default)
Selects a target number of the sharpest frames while maintaining distribution across the source.
```bash
--selection-method best-n --num-frames 300 --min-buffer 3
```
### Batched
Divides content into batches and selects the sharpest frame from each batch.
```bash
--selection-method batched --batch-size 5 --batch-buffer 2
```
### Outlier Removal
Removes unusually blurry frames by comparing each frame to its neighbors.
```bash
--selection-method outlier-removal --outlier-window-size 15 --outlier-sensitivity 50
```
## Command Line Options
### Basic Options
- `--fps <int>`: Frame extraction rate for videos (default: 10)
- `--format <jpg|png>`: Output image format (default: jpg)
- `--width <int>`: Resize width in pixels, maintains aspect ratio (default: 0, no resize)
- `--force-overwrite`: Overwrite existing output files without confirmation
### Selection Method Parameters
- `--num-frames <int>`: Number of frames to select (best-n, default: 300)
- `--min-buffer <int>`: Minimum gap between selected frames (best-n, default: 3)
- `--batch-size <int>`: Frames per batch (batched, default: 5)
- `--batch-buffer <int>`: Frames to skip between batches (batched, default: 2)
- `--outlier-window-size <int>`: Neighbor comparison window (outlier-removal, default: 15)
- `--outlier-sensitivity <int>`: Removal aggressiveness 0-100 (outlier-removal, default: 50)
## Examples
### Video Processing
```bash
# Default settings
sharp-frames video.mp4 output_frames
# Custom frame rate and selection
sharp-frames video.mp4 output --fps 15 --num-frames 500
# Batch selection with resizing
sharp-frames video.mp4 output --selection-method batched --width 1920
# Process all videos in a directory
sharp-frames video_folder output_frames --fps 5
```
### Image Processing
```bash
# Select best images from directory
sharp-frames image_folder selected_images --num-frames 100
# Remove blurry images
sharp-frames photos selected --selection-method outlier-removal --outlier-sensitivity 75
```
## Features
- **Smart File Validation**: Automatic format detection with helpful error messages
- **Textual Interface**: Step-by-step wizard with real-time validation and help system
- **Flexible Input**: Process single videos, video directories, or image directories
- **Multiple Algorithms**: Three selection methods optimized for different use cases
- **Real-time Progress**: Live progress tracking for all processing stages
- **Parallel Processing**: Multi-core sharpness calculation for faster processing
- **Image Resizing**: Optional width-based resizing with aspect ratio preservation
- **Safe Operation**: Validates paths, permissions, and file formats before processing
- **Comprehensive Output**: Selected files plus detailed metadata JSON
## Requirements
- Python 3.7 or higher
- Dependencies installed automatically: `opencv-python`, `numpy`, `tqdm`, `textual`
- FFmpeg (for video processing only)
## How It Works
1. **Validation**: Checks input paths, file formats, and system dependencies
2. **Extraction**: Videos are extracted to frames at specified FPS using FFmpeg
3. **Analysis**: Calculates sharpness scores using Laplacian variance in parallel
4. **Selection**: Applies chosen algorithm to select the best frames/images
5. **Output**: Saves selected content with metadata including scores and parameters
## Output
- Selected frames/images with descriptive filenames
- `selected_metadata.json` with processing details, parameters, and sharpness scores
- Preserves original formats for image directory input
- Automatic output directory creation with permission validation
## Help & Support
- Press `F1` in the textual interface for context-sensitive help
- Use `Ctrl+C` to safely cancel processing at any time
- All validation errors include specific guidance for resolution
- Visit [Sharp Frames](https://sharp-frames.reflct.app) for the full desktop application
Raw data
{
"_id": null,
"home_page": null,
"name": "sharp-frames",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "video, frames, sharpness, image-processing",
"author": null,
"author_email": "\"Reflct.app\" <info@reflct.app>",
"download_url": "https://files.pythonhosted.org/packages/eb/fa/7ee8422e73b76be69a5698607fd7283f4c9d8aee3c3e394a47fcdb72813b/sharp_frames-0.3.0.tar.gz",
"platform": null,
"description": "# Sharp Frames Python\r\n\r\nExtract and select the sharpest frames from videos or directories of images using advanced sharpness scoring algorithms. Features a modern text-based interface for easy configuration and powerful command-line options for automation.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install sharp-frames\r\n```\r\n\r\nOr with pipx for isolated installation:\r\n\r\n```bash\r\npipx install sharp-frames\r\n```\r\n\r\n**IMPORTANT: Video Processing Requirement**: Install FFmpeg separately for video input support.\r\n- **Windows**: Download from [FFmpeg website](https://ffmpeg.org/download.html) and add to PATH\r\n- **macOS**: `brew install ffmpeg`\r\n- **Linux**: `sudo apt install ffmpeg`\r\n\r\n## Quick Start\r\n\r\n### Modern Interface (Default)\r\n```bash\r\nsharp-frames\r\n```\r\nLaunches an intuitive step-by-step wizard for configuring your processing options.\r\n\r\n### Direct Processing\r\n```bash\r\nsharp-frames input_video.mp4 output_folder\r\nsharp-frames image_directory output_folder\r\n```\r\n\r\n## Usage Modes\r\n\r\n### Interactive Configuration\r\n- **Fancy UI**: `sharp-frames` (default) - Step-by-step with validation\r\n- **Legacy**: `sharp-frames --interactive` - Terminal prompts for all options\r\n\r\n### Direct Processing\r\n```bash\r\nsharp-frames <input> <output> [options]\r\n```\r\n\r\n**Input Types:**\r\n- Video files: `.mp4`, `.avi`, `.mov`, `.mkv`, `.wmv`, `.flv`, `.webm`, `.m4v`, etc.\r\n- Video directories: Processes all videos in a folder\r\n- Image directories: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff`, `.webp`, etc.\r\n\r\n## Selection Methods\r\n\r\n### Best-N (Default)\r\nSelects a target number of the sharpest frames while maintaining distribution across the source.\r\n```bash\r\n--selection-method best-n --num-frames 300 --min-buffer 3\r\n```\r\n\r\n### Batched\r\nDivides content into batches and selects the sharpest frame from each batch.\r\n```bash\r\n--selection-method batched --batch-size 5 --batch-buffer 2\r\n```\r\n\r\n### Outlier Removal\r\nRemoves unusually blurry frames by comparing each frame to its neighbors.\r\n```bash\r\n--selection-method outlier-removal --outlier-window-size 15 --outlier-sensitivity 50\r\n```\r\n\r\n## Command Line Options\r\n\r\n### Basic Options\r\n- `--fps <int>`: Frame extraction rate for videos (default: 10)\r\n- `--format <jpg|png>`: Output image format (default: jpg)\r\n- `--width <int>`: Resize width in pixels, maintains aspect ratio (default: 0, no resize)\r\n- `--force-overwrite`: Overwrite existing output files without confirmation\r\n\r\n### Selection Method Parameters\r\n- `--num-frames <int>`: Number of frames to select (best-n, default: 300)\r\n- `--min-buffer <int>`: Minimum gap between selected frames (best-n, default: 3)\r\n- `--batch-size <int>`: Frames per batch (batched, default: 5)\r\n- `--batch-buffer <int>`: Frames to skip between batches (batched, default: 2)\r\n- `--outlier-window-size <int>`: Neighbor comparison window (outlier-removal, default: 15)\r\n- `--outlier-sensitivity <int>`: Removal aggressiveness 0-100 (outlier-removal, default: 50)\r\n\r\n## Examples\r\n\r\n### Video Processing\r\n```bash\r\n# Default settings\r\nsharp-frames video.mp4 output_frames\r\n\r\n# Custom frame rate and selection\r\nsharp-frames video.mp4 output --fps 15 --num-frames 500\r\n\r\n# Batch selection with resizing\r\nsharp-frames video.mp4 output --selection-method batched --width 1920\r\n\r\n# Process all videos in a directory\r\nsharp-frames video_folder output_frames --fps 5\r\n```\r\n\r\n### Image Processing\r\n```bash\r\n# Select best images from directory\r\nsharp-frames image_folder selected_images --num-frames 100\r\n\r\n# Remove blurry images\r\nsharp-frames photos selected --selection-method outlier-removal --outlier-sensitivity 75\r\n```\r\n\r\n## Features\r\n\r\n- **Smart File Validation**: Automatic format detection with helpful error messages\r\n- **Textual Interface**: Step-by-step wizard with real-time validation and help system\r\n- **Flexible Input**: Process single videos, video directories, or image directories\r\n- **Multiple Algorithms**: Three selection methods optimized for different use cases\r\n- **Real-time Progress**: Live progress tracking for all processing stages\r\n- **Parallel Processing**: Multi-core sharpness calculation for faster processing\r\n- **Image Resizing**: Optional width-based resizing with aspect ratio preservation\r\n- **Safe Operation**: Validates paths, permissions, and file formats before processing\r\n- **Comprehensive Output**: Selected files plus detailed metadata JSON\r\n\r\n## Requirements\r\n\r\n- Python 3.7 or higher\r\n- Dependencies installed automatically: `opencv-python`, `numpy`, `tqdm`, `textual`\r\n- FFmpeg (for video processing only)\r\n\r\n## How It Works\r\n\r\n1. **Validation**: Checks input paths, file formats, and system dependencies\r\n2. **Extraction**: Videos are extracted to frames at specified FPS using FFmpeg\r\n3. **Analysis**: Calculates sharpness scores using Laplacian variance in parallel\r\n4. **Selection**: Applies chosen algorithm to select the best frames/images\r\n5. **Output**: Saves selected content with metadata including scores and parameters\r\n\r\n## Output\r\n\r\n- Selected frames/images with descriptive filenames\r\n- `selected_metadata.json` with processing details, parameters, and sharpness scores\r\n- Preserves original formats for image directory input\r\n- Automatic output directory creation with permission validation\r\n\r\n## Help & Support\r\n\r\n- Press `F1` in the textual interface for context-sensitive help\r\n- Use `Ctrl+C` to safely cancel processing at any time\r\n- All validation errors include specific guidance for resolution\r\n- Visit [Sharp Frames](https://sharp-frames.reflct.app) for the full desktop application\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extract, score, and select the best frames from a video or image directory",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/reflct/sharp-frames-python/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/reflct/sharp-frames-python#readme",
"Homepage": "https://github.com/reflct/sharp-frames-python"
},
"split_keywords": [
"video",
" frames",
" sharpness",
" image-processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "92eb8aece00c72a5e37a5fdbea184ab854f579efdcc5a3fc57664adb745ff51a",
"md5": "869f9d8efa17e38029f793fe8ba18bcb",
"sha256": "ebebb1035c022762b3b0b443684891c1842b2ad8bd7e334c08e6ccd2f11fc74d"
},
"downloads": -1,
"filename": "sharp_frames-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "869f9d8efa17e38029f793fe8ba18bcb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 99694,
"upload_time": "2025-08-28T19:43:22",
"upload_time_iso_8601": "2025-08-28T19:43:22.446392Z",
"url": "https://files.pythonhosted.org/packages/92/eb/8aece00c72a5e37a5fdbea184ab854f579efdcc5a3fc57664adb745ff51a/sharp_frames-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ebfa7ee8422e73b76be69a5698607fd7283f4c9d8aee3c3e394a47fcdb72813b",
"md5": "83d68abffc6c08ad801c3664940b80a5",
"sha256": "7ba31ccfffc444547f73c8732dfc946b3b2c7331878b1908a5262e7b714589b2"
},
"downloads": -1,
"filename": "sharp_frames-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "83d68abffc6c08ad801c3664940b80a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 99964,
"upload_time": "2025-08-28T19:43:23",
"upload_time_iso_8601": "2025-08-28T19:43:23.494359Z",
"url": "https://files.pythonhosted.org/packages/eb/fa/7ee8422e73b76be69a5698607fd7283f4c9d8aee3c3e394a47fcdb72813b/sharp_frames-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 19:43:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "reflct",
"github_project": "sharp-frames-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "sharp-frames"
}
