Metadata-Version: 2.4
Name: video-frame-extractor-tool
Version: 0.1.0
Summary: Video Frame Extractor - Extract frames from videos using FFmpeg
Project-URL: Homepage, https://videotojpg.com
Project-URL: Documentation, https://github.com/eyeandroid/video-frame-extractor#readme
Project-URL: Repository, https://github.com/eyeandroid/video-frame-extractor
Project-URL: Issues, https://github.com/eyeandroid/video-frame-extractor/issues
Author-email: VideoToJPG <contact@videotojpg.com>
License: MIT
License-File: LICENSE
Keywords: extract frames from video,ffmpeg,frame-extraction,video frame extractor,video to image,video to jpg,video to png,video-converter,video-frame-extractor,video-processing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Video :: Conversion
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# Video Frame Extractor Tool

A command-line tool and Python library to extract frames from video files using FFmpeg.

[![PyPI version](https://badge.fury.io/py/video-frame-extractor-tool.svg)](https://pypi.org/project/video-frame-extractor-tool/)

## Features

- Extract frames at custom frame rates (e.g., 1 fps, 5 fps, or original)
- Support for multiple output formats: **JPG**, **PNG**, **WebP**
- Adjustable image quality settings
- Extract from specific time ranges
- Resize/scale output frames
- Simple CLI and Python API
- No Python dependencies (uses built-in modules only)

## Requirements

- Python 3.7+
- FFmpeg installed and available in PATH

### Installing FFmpeg

**macOS:**
```bash
brew install ffmpeg
```

**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install ffmpeg
```

**Windows:**
Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH.

## Installation

```bash
pip install video-frame-extractor-tool
```

## Quick Start

### Command Line

```bash
# Extract 1 frame per second as JPG (default)
video2frames video.mp4 -o frames/

# Extract at 5 fps as PNG
video2frames video.mp4 -o frames/ -f 5 --format png

# Extract frames from 10s to 30s
video2frames video.mp4 -o frames/ --start 10 --end 30

# Show video information
video2frames video.mp4 --info
```

### Python API

```python
from video2frames import extract_frames, get_video_info

# Get video information
info = get_video_info("video.mp4")
print(f"Resolution: {info.width}x{info.height}")
print(f"Duration: {info.duration} seconds")
print(f"FPS: {info.fps}")

# Extract frames
frames = extract_frames(
    "video.mp4",
    output_dir="frames",
    fps=2,
    format="png",
    quality=95
)
print(f"Extracted {len(frames)} frames")
```

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `video` | Path to input video file | (required) |
| `-o, --output` | Output directory | `frames` |
| `-f, --fps` | Frames per second to extract | `1` |
| `--format` | Output format: `jpg`, `png`, `webp` | `jpg` |
| `-q, --quality` | Image quality (1-100) | `90` |
| `--start` | Start time in seconds | None |
| `--end` | End time in seconds | None |
| `--prefix` | Filename prefix | `frame` |
| `--scale` | Output resolution (e.g., `-1:720`) | None |
| `--info` | Show video info and exit | False |
| `-v, --verbose` | Verbose output | False |

## Examples

### Extract at Different Frame Rates

```bash
# 1 frame per second (good for long videos)
video2frames video.mp4 -o frames/ -f 1

# 5 frames per second
video2frames video.mp4 -o frames/ -f 5

# Original frame rate (e.g., 30 fps)
video2frames video.mp4 -o frames/ -f 30
```

### Different Output Formats

```bash
# JPEG (smaller files)
video2frames video.mp4 -o frames/ --format jpg

# PNG (lossless)
video2frames video.mp4 -o frames/ --format png

# WebP (modern, good compression)
video2frames video.mp4 -o frames/ --format webp
```

### Extract Specific Time Range

```bash
# Extract from 1:00 to 2:00
video2frames video.mp4 -o frames/ --start 60 --end 120

# First 30 seconds only
video2frames video.mp4 -o frames/ --end 30
```

### Resize Output

```bash
# Resize to 720p (keep aspect ratio)
video2frames video.mp4 -o frames/ --scale -1:720

# Resize to specific dimensions
video2frames video.mp4 -o frames/ --scale 1280:720
```

### Batch Processing

```bash
# Process multiple videos
for video in *.mp4; do
    video2frames "$video" -o "${video%.mp4}_frames/"
done
```

## Python API Reference

### `extract_frames()`

```python
extract_frames(
    video_path: str,
    output_dir: str = "frames",
    fps: float = 1.0,
    format: str = "jpg",
    quality: int = 90,
    start_time: Optional[float] = None,
    end_time: Optional[float] = None,
    prefix: str = "frame",
    scale: Optional[str] = None,
    overwrite: bool = True,
    verbose: bool = False
) -> List[Path]
```

### `get_video_info()`

```python
get_video_info(video_path: str) -> Optional[VideoInfo]
```

Returns a `VideoInfo` object with:
- `width`: Video width in pixels
- `height`: Video height in pixels
- `fps`: Frame rate
- `duration`: Duration in seconds
- `total_frames`: Estimated total frames

### `check_ffmpeg()`

```python
check_ffmpeg() -> bool
```

Returns `True` if FFmpeg is available.

## License

MIT License - see [LICENSE](LICENSE) file.

## Links

- [VideoToJPG.com](https://videotojpg.com) - Online video frame extractor with sharpness detection
- [FFmpeg](https://ffmpeg.org) - The multimedia framework used by this tool
