chunder

Chunder

Spew out videos from YouTube straight to your disk.

chunder is a fast, zero-fuss YouTube downloader for your terminal. Written in Go, ships as a single binary, shows you a live progress bar while it works.

      _                     _
  ___| |__  _   _ _ __   __| | ___ _ __
 / __| '_ \| | | | '_ \ / _` |/ _ \ '__|
| (__| | | | |_| | | | | (_| |  __/ |
 \___|_| |_|\__,_|_| |_|\__,_|\___|_|

Features

• 📺 chunder watch — play videos INSIDE your terminal. No window, no browser: frames render as true-color half-block text at ~2 pixels per cell, with synced audio, pause, and seeking. Yes, really.
• ✨ A TUI that doesn't look like 1998 — animated download experience built on Bubble Tea + Lip Gloss: gradient progress bar, live speed sparkline, step checklist, styled video cards, adaptive light/dark colors
• ⚡ Single static binary — no Python, no runtime, just chunder
• 🎚️ Quality selection — best, worst, or any resolution (1080p, 720p, 480p, …)
• 📚 Playlist downloads — paste a playlist link and chunder queues every video with a live queue view, numbered files, and a folder named after the playlist (--limit, --reverse)
• 🔎 chunder search — YouTube search in your terminal. No API key, no browser: an interactive result browser with thumbnail previews rendered as terminal art. Enter downloads, w watches in the terminal, a grabs audio
• ✂️ Clip extraction — --from 1:23 --to 2:45 grabs just a segment, transferring only those bytes (no full download, no re-encode)
• 💬 Subtitles — --subs en saves captions as .srt; --embed-subs muxes them into the mp4 as a proper subtitle track
• 🧭 Helpful when you're lost — missing arguments and typos get ready-to-paste suggestions, not parser errors
• 🎵 Audio-only mode — rip audio to .m4a with --audio-only, or straight to .mp3 with --format mp3
• 📊 Live progress — bytes, speed, ETA, and a real-time speed graph
• 📁 Output control — pick the folder and filename; never silently overwrites
• 🔍 Format inspector — chunder info <url> lists every available stream
• 🤖 Script-friendly — automatically switches to plain line output when piped
• ⚙️ Config file + env vars — set your defaults once (Viper-powered)
• 🐚 Shell completions — bash, zsh, fish, powershell via chunder completion

What it looks like

 chunder   youtube downloader

╭──────────────────────────────────────────────────────────────╮
│  Rick Astley - Never Gonna Give You Up (Official Video)      │
│  Rick Astley • 3m33s • 1.8B views                            │
│                                                              │
│   480p   VIDEO+AUDIO   FFMPEG                                │
╰──────────────────────────────────────────────────────────────╯

  ✓ Fetch video metadata
  ⠸ Download video
      ███████████████████████░░░░░░░░░░░░░░░░░  62%
      8.3 MiB / 13.5 MiB  •  3.2 MiB/s  •  eta 2s
      ▁▂▃▅▆▇█▆▅▇█▇▆▅▆▇██▇▆▅▆▇█
  ○ Download audio
  ○ Mux with ffmpeg

press q to cancel

Install

Homebrew (macOS / Linux)

brew install chunder-cli/tap/chunder

Prebuilt binaries

Grab the archive for your platform from the latest release, then:

tar xzf chunder_*_darwin_arm64.tar.gz   # unzip on Windows
sudo mv chunder /usr/local/bin/

Binaries are published for macOS (Apple Silicon & Intel), Linux (x86-64 & ARM64), and Windows, with SHA-256 checksums.

From source

Requires Go 1.26+:

go install github.com/chunder-cli/chunder@latest

Or clone and build:

git clone https://github.com/chunder-cli/chunder.git
cd chunder
make build

ffmpeg (optional, recommended)

YouTube serves resolutions above 720p as separate video and audio streams. chunder uses ffmpeg to combine them — without it, downloads fall back to the best single-file quality (usually 720p).

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

Usage

# Download at best available quality
chunder https://youtu.be/dQw4w9WgXcQ

# Pick a quality and a destination folder
chunder download https://youtu.be/dQw4w9WgXcQ -q 720p -o ~/Videos

# Audio only
chunder download https://youtu.be/dQw4w9WgXcQ --audio-only

# Straight to mp3 (implies --audio-only)
chunder download https://youtu.be/dQw4w9WgXcQ --format mp3

# Custom filename (extension added automatically)
chunder download https://youtu.be/dQw4w9WgXcQ -f "never-gonna"

# See every available format first
chunder info https://youtu.be/dQw4w9WgXcQ

# Watch it INSIDE the terminal (space = pause, ←/→ = seek, q = quit)
chunder watch https://youtu.be/dQw4w9WgXcQ

# Cut a clip — only the segment's bytes are downloaded
chunder download <url> --from 1:23 --to 2:45
chunder download <url> --from 43 --to 58 --format mp3   # audio clip as mp3

# Subtitles: save as .srt, or embed straight into the mp4
chunder download <url> --subs en
chunder download <url> --embed-subs

# Download a whole playlist (files numbered, folder named after the playlist)
chunder https://www.youtube.com/playlist?list=PLxxxxxxx
chunder download <playlist-url> --limit 10 --reverse --audio-only

# Search YouTube, browse results with thumbnail previews, act on one
chunder search lofi hip hop radio

Watching videos in the terminal

chunder watch decodes the stream with ffmpeg and paints every frame directly into your terminal using the half-block trick: the ▀ character with separate foreground and background colors gives two pixels per cell, so a 200×56 terminal becomes a 200×112 true-color display. Audio plays through ffplay (bundled with ffmpeg) and stays in sync via wall-clock frame pacing.

chunder watch <url>              # play with audio
chunder watch <url> --no-audio   # silent
chunder watch <url> --fps 15     # gentler on slow terminals
chunder watch <url> --mpv        # hand off to mpv instead

Best enjoyed maximized in a fast, true-color terminal (iTerm2, Kitty, WezTerm, Ghostty). It's a party trick — a glorious one.

Flags

Configuration

Set persistent defaults in ~/.config/chunder/config.yaml:

output: ~/Videos
quality: 1080p

Or with environment variables:

export CHUNDER_OUTPUT=~/Videos
export CHUNDER_QUALITY=720p

Precedence: flags > env vars > config file > defaults.

How quality selection works

1. chunder asks YouTube for every available stream.
2. If your target quality exists as a single file with audio, it downloads that directly.
3. If it only exists as a separate video stream (typically >720p and some 480p), chunder downloads video + audio separately and losslessly muxes them with ffmpeg (-c copy, no re-encoding).
4. If ffmpeg is missing, it warns and falls back to the best single-file quality.

Roadmap

• Watch videos inside the terminal — chunder watch 📺
• Playlist downloads — with a live queue view 📚
• chunder search — interactive results with thumbnail-art previews 🔎
• Subtitles / captions — --subs en, --embed-subs 💬
• --format mp3 audio conversion 🎵
• Clip extraction — --from 1:23 --to 2:45 ✂️
• Thumbnail + metadata embedding
• Batch file input (chunder -i list.txt)
• Resume interrupted downloads
• chunder library — browse everything you've downloaded
• Self-update (chunder upgrade)
• TikTok / Instagram / X support

Built with

• Cobra — command routing, flags, completions
• Viper — config file + env var management
• Bubble Tea — the TUI framework (Elm architecture)
• Lip Gloss + Bubbles — styling, gradients, progress, spinners
• kkdai/youtube — YouTube stream extraction in pure Go

Development

make build   # build ./chunder with version info
make test    # run tests
make lint    # go vet

Legal

chunder is a tool. Downloading videos may violate YouTube's Terms of Service and/or copyright law depending on the content and your jurisdiction. Only download videos you have the right to download. The authors take no responsibility for how you use it.

License

MIT