Skip to navigation
Integrations

Cobalt

Cobalt is a self-hosted media downloader that runs as a separate container alongside summarize. It fetches video and audio from platforms that yt-dlp cannot handle, or situations where yt-dlp fails due to rate limits, geo-restrictions, or missing cookies.

When to Use Cobalt

Generic HTTP video URLs

Cobalt handles direct video links from sites not covered by yt-dlp extractors.

yt-dlp failures

When yt-dlp returns rate-limit errors, geo-blocks, or login-required messages, Cobalt may succeed via its own extraction pipeline.

Anonymous fetching

Some platforms block anonymous yt-dlp requests but allow Cobalt’s embed-based or API-based fetching.

No cookie setup

If you do not want to manage per-platform cookie files, Cobalt can often download public content without them.

Tip: For YouTube, Instagram, TikTok, Twitter/X, Reddit, and Facebook, yt-dlp is the primary downloader. It is faster, requires no extra container, and supports per-platform cookie authentication. Cobalt is only used as a fallback when yt-dlp fails or does not recognize the URL.

Downloader Classes

Each downloader implements the same BaseDownloader interface, and DownloadManager tries them in order. Download failures are AudioProcessingError; a URL no downloader claims raises UnsupportedSourceError.

BaseDownloader + supports(url) + download_audio() + download_video() CobaltDownloader + base_url YtdlpDownloader YouTubeDownloader DownloadManager AudioProcessingError UnsupportedSourceError SummarizerError tries in order combined failure no match

Where Cobalt Fits in the Chain

Every download walks the same fallback chain, and Cobalt is the last resort before the app gives up.

no yes ok AudioProcessingError yes errors recorded nobody claimed the URL URL next downloader supports it? any left? download audio or video return temp path record the error AudioProcessingError UnsupportedSourceError

When yt-dlp Is Better

Use CasePreferred ToolReason
Instagram, TikTok, X, Reddit, Facebookyt-dlpNative extractors, cookie auth, no container overhead
Generic HTTP video linksCobaltBroader URL support
yt-dlp rate-limited / blockedCobaltAlternative extraction pipeline
YouTubeyt-dlpDefault clients and JS challenge solving; pytubefix is the fallback

Running Cobalt

Standalone

docker compose -f docker-compose.cobalt.yml up -d

This starts Cobalt on http://localhost:9000. The summarize app automatically points to this URL via the COBALT_BASE_URL environment variable.

With Proxy

If Cobalt needs to connect through a proxy (for geo-unblocking or CDN access):

  1. Copy the template:

    cp cobalt.proxy.env.example cobalt.proxy.env

  2. Fill in your proxy credentials:

    HTTP_PROXY=http://username:password@proxy-host:port/
    HTTPS_PROXY=http://username:password@proxy-host:port/
    NO_PROXY=localhost,127.0.0.1,cobalt,summarizer

  3. Start with the proxy overlay:

    docker compose -f docker-compose.cobalt.yml -f docker-compose.proxy.yml up -d

Full Stack (Summarize + Cobalt)

# Full stack, no proxy
docker compose up -d
# Full stack, with proxy
docker compose -f docker-compose.yml -f docker-compose.proxy.yml up -d

Docker Compose Reference

FilePurpose
docker-compose.ymlSummarize + Cobalt together
docker-compose.cobalt.ymlCobalt only
docker-compose.proxy.ymlAdds cobalt.proxy.env to the Cobalt service
cobalt.proxy.env.exampleProxy env template
cobalt.proxy.envYour local, ignored secrets file

Configuration

The summarize app talks to Cobalt through the --cobalt-url flag or the COBALT_BASE_URL environment variable:

python -m summarizer --source "URL" --cobalt-url "http://localhost:9000"

In Docker, this is set automatically:

environment:
  - COBALT_BASE_URL=http://cobalt:9000