Metadata-Version: 2.4
Name: videoframer
Version: 1.0.1
Summary: Analyze videos with multimodal AI, one frame at a time.
Author: Lex Alexander
License-Expression: MIT
Project-URL: Homepage, https://github.com/cacheflow/pyvideoframer
Project-URL: Documentation, https://github.com/cacheflow/pyvideoframer#readme
Project-URL: Repository, https://github.com/cacheflow/pyvideoframer
Project-URL: Issues, https://github.com/cacheflow/pyvideoframer/issues
Keywords: video-analysis,multimodal-ai,frame-extraction,ffmpeg,computer-vision
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: openai
Requires-Dist: openai<3,>=2; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic<1,>=0.50; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai<2,>=1; extra == "gemini"
Provides-Extra: all
Requires-Dist: openai<3,>=2; extra == "all"
Requires-Dist: anthropic<1,>=0.50; extra == "all"
Requires-Dist: google-genai<2,>=1; extra == "all"
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: mypy<2,>=1; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Dynamic: license-file

# Videoframer for Python

Analyze video with multimodal AI, one frame at a time.

Videoframer extracts chronologically ordered JPEG frames from a local video,
groups them into batches, and sends them to OpenAI, Anthropic, or Gemini.

## Requirements

- Python 3.10 or newer
- FFmpeg available on your system `PATH`
- An API key for the selected model provider

## Installation

Install support for one provider:

```bash
pip install "videoframer[openai]"
pip install "videoframer[anthropic]"
pip install "videoframer[gemini]"
```

Or install all provider integrations:

```bash
pip install "videoframer[all]"
```

FFmpeg is a system dependency and is not installed by `pip`. For example:

```bash
brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Debian or Ubuntu
```

## Quick start

```python
import os

from videoframer import Videoframer, VideoframerOptions

videoframer = Videoframer(
    VideoframerOptions(
        video_path="./videos/demo.mp4",
        frames_directory="./tmp/frames",
        provider="openai",
        api_key=os.environ["OPENAI_API_KEY"],
        model="gpt-5.6",
        prompt=(
            "Analyze these frames as one continuous video. "
            "Summarize important actions chronologically."
        ),
        frame_rate=1,
        batch_size=5,
        max_frames=20,
    )
)

videoframer.on("progress", print)

analysis = videoframer.analyze()

for batch in analysis.results:
    print(batch.output_text)
```

`frames_directory` is a parent directory. Each analysis gets a private,
uniquely named `videoframer-*` subdirectory so concurrent instances cannot
overwrite one another's frames. Set `keep_frames=True` to retain that run
directory after analysis. Set `max_frames="all"`, `0`, or `-1` to analyze every
extracted frame.

Lifecycle event payloads are JSON strings. The `started`, `progress`, and
`completed` events can be parsed with `json.loads`; the `error` event receives
the original exception.

## Command line

Installing the package provides both `videoframer` and
`python -m videoframer`:

```bash
export OPENAI_API_KEY="..."
videoframer ./videos/demo.mp4 \
  --provider openai \
  --model gpt-5.6 \
  --max-frames 20 \
  --progress
```

Use `ANTHROPIC_API_KEY` for Anthropic and `GEMINI_API_KEY` for Gemini. Analysis
JSON is written to standard output; `--progress` writes lifecycle JSON to
standard error.

Video frames are sent to the selected third-party model provider. Review that
provider's data handling and retention terms before analyzing sensitive video.

## Development

```bash
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run python -m build
```

## License

MIT
