Overview

Summarize

Local-first multi-source video summarization (YouTube, social, drives, files) with any OpenAI-compatible LLM, optional vision path, and NotebookLM-style workflows.

sample

Not steipete/summarize — This is a self-hosted video pipeline with transcript cache, Cobalt fallback, Streamlit workspace, and an agent skill. Steipete’s project is a generic URL clipper.

Bring your own API keys. All configuration lives in summarizer.yaml and .env.

More background on this project: martino.im/Summarize.

11+ Platforms

YouTube, Instagram, TikTok, Twitter/X, Reddit, Facebook, Google Drive, Dropbox, local files

Any LLM

OpenAI, Groq, Gemini, Ollama, OpenRouter, NVIDIA, Perplexity, LiteLLM, and any OpenAI-compatible endpoint

Two Modes

Audio transcription + text summary, or visual mode sending video directly to vision-capable models

Summary Styles

Q&A, distillation, fact-checking, tutorials, Mermaid diagrams, essays, and more. Add your own instantly by editing summarizer/prompts.json.

Web UI

Streamlit interface with history, Mermaid rendering, themes, and one-click share

Docker Ready

Full-stack Compose with optional Cobalt and proxy support

Requirements

  • Python 3.7+
  • ffmpeg (must be on PATH)
  • At least one LLM API key in .env
  • Cobalt fallback downloader for URLs that yt-dlp cannot handle (included in Docker Compose). See Cobalt.

Quick Start

Install in an isolated environment (pipx recommended) so other Python tools cannot break summarizer. See Installation for venv, Docker, and development setup.

You need any OpenAI-compatible API key in .env (for example Groq GROQ_API_KEY is free-tier friendly; OPENAI_API_KEY works with --provider openai).

$pipx install martino-summarize
$summarizer --init-config
$echo "GROQ_API_KEY=your_key_here" > .env
$summarizer --source "https://www.youtube.com/watch?v=arj7oStGLkU"

The summary is saved to summaries/watch_YYYYMMDD_HHMMSS.md.

For the HTTP API or all extras:

$pipx install "martino-summarize[server]"   # HTTP API
$pipx install "martino-summarize[all]"      # server + whisper + litellm

Quick Start (Docker)

$git clone https://github.com/martinopiaggi/summarize.git
$cd summarize
$cp summarizer.docker.yaml summarizer.yaml   # Docker-optimized defaults
$echo "GROQ_API_KEY=your_key_here" > .env     # or OPENAI_API_KEY, etc.
$docker compose up -d

Open http://localhost:8501, paste a URL, and summarize. Summaries and transcript cache persist under ./summaries/.

Or pull the pre-built image:

$docker pull ghcr.io/martinopiaggi/summarize:latest

docker-compose.yml mounts .env, summarizer.yaml, and ./summaries/. Use docker-compose.gui-only.yml for a lighter YouTube-only setup, or docker-compose.named-volume.yml for a Docker-managed volume. Cobalt runs as a sidecar for TikTok, Instagram, and other yt-dlp fallbacks.

Pick Your Interface

InterfaceCommand
Streamlit GUIdocker compose up -d → http://localhost:8501
CLIsummarizer --source <source>
HTTP APIpipx install "martino-summarize[server]" then summarizer serve → http://localhost:8000/docs
Dockerdocker compose up -d
Agent Skill.agent/skills/summarize/SKILL.md
Raycastextensions/raycast-summarize/

See the HTTP API guide for endpoint details, request examples, and CORS configuration.

Two Processing Paths

  • Transcript path (default): downloads audio/video, transcribes with Whisper or captions, caches the transcript, then summarizes with an LLM.
  • Visual path (--visual): sends the video directly to a vision-capable model, skipping transcription. Uses the same prompts, provider config, and .env keys as the transcript path. Supports base64 chunks (default) and url passthrough for YouTube.

See How It Works for the full pipeline diagram and Visual Mode for provider setup.

Common Issues

  • pydantic / pydantic-core mismatch on serve: environment problem, not a summarizer bug — reinstall with pipx install "martino-summarize[server]" or see Errors and Troubleshooting
  • yt-dlp / platform errors: ensure Cobalt is running (docker compose includes it) or set COBALT_BASE_URL
  • Missing API key: add the provider key to .env (see summarizer.example.yaml for provider names)
  • No config file: run summarizer --init-config or pass --base-url and --model with --no-config
  • Removed audio-speed key: use speed in YAML instead (see Configuration)

Full guide: Errors and Troubleshooting