Video Analyzer

Gemini-powered video analysis for ad creatives — a web app, a desktop app, a Python CLI, and an MCP server.

Point it at a video file or a folder of videos. Each video is uploaded to Gemini (which watches the full video — audio, visuals, on-screen text, transitions) and returns a structured ad-creative analysis as markdown: scene-by-scene breakdown, full transcript, creative-structure teardown, performance signals, and an iteration brief.

New to this? Download SETUP-WITH-AI.md, attach it to any AI chat (Claude, ChatGPT, Gemini), and press Enter. The AI walks you through setup one step at a time.

Install

git clone https://github.com/thomasbrosch/video-analyzer.git
cd video-analyzer
pip install -e .

Requires Python 3.10+.

Related MCP server: Google Ads MCP Server

API key

You bring your own Gemini key; this repo never contains one. Get a free key from https://aistudio.google.com/apikey, then set it once (Windows):

setx GEMINI_API_KEY <your_key>

Open a new terminal after setx so the variable is picked up. You can also pass --api-key on the CLI or set it in the MCP server config.

CLI usage

video-analyzer "C:\path\to\some_ad.mp4"           # analyze one video
video-analyzer "C:\path\to\ads_folder\"           # analyze a whole folder
video-analyzer "C:\path\to\ads_folder\" -m pro    # use the Pro model
video-analyzer "C:\path\to\ads_folder\" -o ".\reports\"   # save markdown files
video-analyzer "C:\path\to\some_ad.mp4" -v        # verbose (upload/processing logs)
video-analyzer "C:\path\to\some_ad.mp4" --json    # machine-readable JSON output

You can also run it as a module: python -m video_analyzer <path>.

Options

Models

Desktop app (Windows)

video-analyzer-gui

Drag videos in, pick a model and report format (Markdown, Word, PDF), and paste your key once.

Web app

A browser version with the same analysis. Run it locally:

pip install -e ".[web]"
export GEMINI_API_KEY=your_key      # optional; visitors can paste their own instead
python -m video_analyzer.webapp     # http://localhost:8080

Deploy it anywhere that runs a Docker container (Render, Google Cloud Run, Railway, Fly.io):

docker build -t video-analyzer .
docker run -p 8080:8080 -e GEMINI_API_KEY=your_key video-analyzer

Set GEMINI_API_KEY as a secret environment variable on the host, never in the repo. If you host it publicly with your own key, protect your bill:

Also set a spending cap on the key in Google AI Studio / Cloud billing.

Supported formats

.mp4 .mpeg .mov .avi .flv .mpg .webm .wmv .3gp .m4v .mkv

MCP server (Claude Desktop)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "video-analyzer": {
      "command": "video-analyzer-mcp",
      "env": {
        "GEMINI_API_KEY": "<your_key>"
      }
    }
  }
}

Exposes two tools: analyze_video (file or folder) and list_videos (preview a folder).

Privacy

Videos are sent to Google's Gemini API for analysis, so don't upload footage you aren't allowed to share with Google. The web app deletes the uploaded file from the server and from Gemini storage when the analysis finishes.

How it works

Videos are uploaded via the Gemini Files API, polled until they finish processing, analyzed with generate_content, and (by default) deleted from Gemini storage afterward. Large videos take longer to process; the uploader waits up to 5 minutes.

License

MIT