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:

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

Or install all provider integrations:

pip install "videoframer[all]"

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

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

Quick start

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:

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

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