zapdos-py 0.2.0

A CLI tool for indexing video files with programmatic access

Zapdos

A CLI tool for indexing video files by extracting keyframes that can also be used programmatically.

Installation

To install zapdos, you can use pip:

pip install zapdos

Or if you're using uv:

uv pip install zapdos

Usage

Command Line Interface

After installation, you can use the zapdos command:

zapdos <video_file_path> [--interval <seconds>]

This command will index the specified video file by extracting keyframes at regular intervals.

Programmatic Usage

You can also use zapdos programmatically in your Python code:

from zapdos import index

# Index a video file
try:
    frame_paths = index("path/to/your/video.mp4", interval_sec=30)
    print(f"Extracted {len(frame_paths)} frames")
except FileNotFoundError as e:
    print(f"Error: {e}")
except ValueError as e:
    print(f"Error: {e}")

Example

CLI Usage

# Extract frames every 30 seconds (default)
zapdos ./video.mp4

# Extract frames every 10 seconds
zapdos ./video.mp4 --interval 10

Programmatic Usage

from zapdos import index
from pathlib import Path

# Index a video file
video_path = Path("video.mp4")
try:
    frame_paths = index(video_path, interval_sec=30)
    print(f"Extracted {len(frame_paths)} frames")
    for path in frame_paths:
        print(f"  - {path}")
except FileNotFoundError as e:
    print(f"Error: {e}")
except ValueError as e:
    print(f"Error: {e}")

Supported Video Formats

Zapdos supports the following video formats:

• MP4 (.mp4)
• AVI (.avi)
• MOV (.mov)
• MKV (.mkv)
• WMV (.wmv)
• FLV (.flv)
• WEBM (.webm)
• M4V (.m4v)
• 3GP (.3gp, .3g2)
• MPG/MPEG (.mpg, .mpeg, .m2v)

Development

To set up the project for development:

1. Clone the repository
2. Install uv if you haven't already: pip install uv
3. Install the package in development mode:

   uv pip install --editable .
   

4. Run the CLI tool:

   zapdos <video_file_path>
   

Testing

There are several ways to run the tests:

Using unittest directly:

python tests/test_cli.py

Using pytest (after installing with uv pip install pytest):

pytest tests/

License

This project is licensed under the MIT License.