Skip to navigation
Overview

How It Works

Architecture

Three surfaces — the CLI, the Streamlit webapp, and the HTTP API — all drive the same engine.

User or agent CLI Streamlit :8501 HTTP API :8000 core.main yaml, .env, prompts downloaders sources transcription and cache LLM, Whisper, Cobalt chunking and JEV visual mode summaries

Pipeline

The default transcript path runs in two stages.

1. Acquire the transcript

Cache first, then the downloader fallback chain, then captions or Whisper.

alt [hit] [miss] main(config) get_cached_transcript() transcript _fetch_transcript() download_audio() temp path captions or Whisper transcript transcript put_cached_transcript() transcript Caller core.main transcript cache handlers DownloadManager transcription

2. Chunk, filter, summarize

opt [JEV enabled] par [each chunk] extract_and_clean_chunks() timestamped chunks prefilter_chunks() SystemOne scores keep or exclude selected passages process_chunk() chunk summary summaries format with timestamps core.main api.py jev.py LLM

Download Pipeline

The app uses a fallback downloader chain:

  1. yt-dlp — YouTube, Instagram, TikTok, Twitter/X, Reddit, Facebook
  2. YouTube (pytubefix) — fallback if yt-dlp fails
  3. Cobalt — fallback for other HTTP video URLs

If a downloader does not support a URL or fails, the next one is tried automatically.

Key Files

FilePurpose
summarizer.yamlProvider settings and defaults. Generate with python -m summarizer --init-config.
.envAPI keys matched by URL keyword or conventional env var names
summarizer/prompts.jsonSummary style templates

Processing Paths

  • Transcript path (default): downloads audio/video, transcribes with Whisper or captions, caches the complete transcript, optionally selects passages with JEV, 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 Visual Mode for provider setup and Transcription for Whisper options.

Notes

Tip: If YouTube captions are unavailable, the tool automatically falls back to audio download + Whisper transcription.

Tip: Transcripts are cached in memory by default. Re-summarizing the same source with a different style, provider, or JEV selection skips transcription entirely. Disable with cache-transcript: false in summarizer.yaml.

  • Cloud Whisper uses Groq Cloud API and requires a Groq API key.
  • The Docker image does not include Local Whisper and is aimed at lightweight VPS deployment.