Metadata-Version: 2.4
Name: zapdos-py
Version: 0.2.3
Summary: A CLI tool for indexing video files with programmatic access
Author-email: Tri Nguyen <tri@zapdoslabs.com>
License-Expression: MIT
Keywords: cli,indexing,video,sdk,keyframes
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: av>=15.0.0
Requires-Dist: jsonlines>=4.0.0
Requires-Dist: opencv-python>=4.12.0.88
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# Zapdos-Py

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

## Installation

To install zapdos-py, you can use pip:

```bash
pip install zapdos-py
```

Or if you're using uv:

```bash
uv pip install zapdos-py
```

## Usage

### Command Line Interface

After installation, you can use the zapdos-py command:

```bash
zapdos-py <video_file_path> [--interval <seconds>] [--api-key <api_key>]
```

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

You can also set your API key as an environment variable:

```bash
export ZAPDOS_API_KEY=your_api_key_here
zapdos-py <video_file_path> [--interval <seconds>]
```

### Programmatic Usage

You can also use zapdos-py programmatically in your Python code using the client-based approach:

```python
from zapdos import Client

# Create a client with your API key
client = Client(api_key="your_api_key_here")

# Index a video file
try:
    result = client.index("path/to/your/video.mp4", interval_sec=30)
    print(f"Indexed {len(result['items'])} frames")
except FileNotFoundError as e:
    print(f"Error: {e}")
except ValueError as e:
    print(f"Error: {e}")
```

#### With Progress Callback

You can also provide a callback function to receive progress updates during the indexing process:

```python
from zapdos import Client

def progress_callback(event_data):
    """Callback function to handle progress updates."""
    event_type = event_data.get("event")
    if event_type == "uploaded":
        print(f"Uploaded frame {event_data.get('file_id')}")
    elif event_type == "done-indexing":
        print("Indexing completed successfully!")
    elif event_type == "error":
        print(f"Error: {event_data.get('message')}")

# Create a client with your API key
client = Client(api_key="your_api_key_here")

# Index a video file with progress updates
try:
    result = client.index(
        "path/to/your/video.mp4", 
        interval_sec=30,
        progress_callback=progress_callback
    )
    print(f"Indexed {len(result['items'])} frames")
except FileNotFoundError as e:
    print(f"Error: {e}")
except ValueError as e:
    print(f"Error: {e}")
```

## Example

### CLI Usage
```bash
# Extract frames every 30 seconds (default)
zapdos-py ./video.mp4

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

# With API key
zapdos-py ./video.mp4 --api-key your_api_key_here
```

### Programmatic Usage
```python
from zapdos import Client
from pathlib import Path

# Create a client with your API key
client = Client(api_key="your_api_key_here")

# Index a video file
video_path = Path("video.mp4")
try:
    result = client.index(video_path, interval_sec=30)
    print(f"Indexed {len(result['items'])} frames")
    for item in result['items']:
        print(f"  - {item}")
except FileNotFoundError as e:
    print(f"Error: {e}")
except ValueError as e:
    print(f"Error: {e}")
```

## Supported Video Formats

Zapdos-Py 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:
   ```bash
   uv pip install --editable .
   ```
4. Run the CLI tool:
   ```bash
   zapdos-py <video_file_path>
   ```

## Testing

There are several ways to run the tests:

### Using pytest (recommended):
```bash
pytest tests/
```

### Using unittest directly:
```bash
python -m unittest tests.test_cli
```

### Running the video indexer test:
```bash
python tests/test_video_indexer.py
```

## License

This project is licensed under the MIT License.
