KroszTube

Download YouTube videos in any quality without re-encoding, extract MP3s, fetch clean text transcripts, and stream straight to your terminal.

KroszTube is both a CLI and a typed Node.js library. It wraps yt-dlp and ffmpeg — both downloaded and managed automatically on first run, no manual setup.

npm install -g krosztube

Requires Node.js >= 20. Works on Windows, macOS and Linux.

Quick start

# Best available quality (4K/8K included), original streams, zero transcode
krosztube download "https://www.youtube.com/watch?v=..."

# Cap the quality, choose the output folder
krosztube dl "https://youtu.be/..." -Q 1080 -o ~/Videos

# MP3 at 320 kbit/s
krosztube audio "https://youtu.be/..." -b 320

# A 25-second clip, center-cropped to 9:16 for shorts/reels editing
krosztube clip "https://youtu.be/..." --from 1:20 --to 1:45 -r 9:16

# The video's script as clean text (uses YouTube captions — free, no API keys)
krosztube transcript "https://youtu.be/..." --format md -o script.md

# Stream without saving (needs mpv or VLC installed)
krosztube play "https://youtu.be/..."

# Audio-only radio mode in the terminal
krosztube play "https://youtu.be/..." --audio

Why the downloads are "non-compressed"

KroszTube never re-encodes video. It downloads YouTube's original streams and merges them with an ffmpeg stream copy — a byte-for-byte container operation:

• --container mp4 (default): original streams remuxed into an .mp4. Note: 4K+ streams are VP9/AV1; AV1-in-mp4 may not play on very old devices.
• --container original: whatever container the source streams merge into natively (.webm/.mkv) — guaranteed untouched.

Unlike format selectors that force mp4-only streams (and silently downgrade 4K to 1080p), KroszTube always grabs the true best stream for the quality you asked for.

Commands

| Command | What it does | |---|---| | krosztube download <urls...> (dl) | Download video(s)/playlists. -Q best\|2160\|…\|144, -o dir, --container mp4\|original, --batch-file list.txt, -c concurrency, --no-playlist, -f <raw yt-dlp format> | | krosztube audio <urls...> | MP3 extraction. -b 64\|128\|192\|320 | | krosztube clip <url> | Download a section only. --from/--to (seconds, mm:ss or hh:mm:ss), -r 9:16\|16:9\|original center crop | | krosztube transcript <url> | Captions → clean text. -l lang, --format txt\|md\|srt\|vtt, --timestamps, -o file | | krosztube info <url> | Title, channel, duration, views (--json for scripting) | | krosztube formats <url> | Table of every available format | | krosztube play <url> | Stream via mpv (preferred) or VLC. --audio radio mode, --ascii terminal-art mode, -p mpv\|vlc, -Q quality | | krosztube update | Update the managed yt-dlp binary — run this when downloads start failing | | krosztube doctor | Show binary paths/versions, detected players, cache dir |

Batch files: one URL per line, # comments and blank lines ignored.

Transcripts

krosztube transcript turns a video into a readable script using YouTube's own caption tracks (manual preferred, auto-generated fallback) — entirely free and local, no transcription API.

• txt — deduped, reflowed paragraphs (auto-captions' rolling repeats are removed)
• md — same, with a metadata header (title, channel, URL, duration, caption type)
• srt / vtt — subtitle files with timestamps
• --timestamps adds [mm:ss] markers to txt/md

Videos with captions disabled have no transcript source; a future version may add optional local speech-to-text.

Terminal streaming

krosztube play hands the stream to mpv (best experience — full quality, seeking, its own keybindings) or VLC as a fallback. Neither is bundled; install with winget install mpv, brew install mpv, or sudo apt install mpv.

• --audio: audio-only "radio" mode with a now-playing panel (q to quit)
• --ascii: renders the actual video as ANSI art inside your terminal (needs a truecolor terminal like Windows Terminal or iTerm2)

Library usage

import { download, downloadAudio, getTranscript, renderTranscript, getInfo } from 'krosztube';

const { files } = await download('https://youtu.be/...', {
  quality: 1080,
  container: 'mp4',
  outputDir: './videos',
  onProgress: (e) => console.log(`${e.phase} ${e.percent?.toFixed(0)}%`),
});

const transcript = await getTranscript('https://youtu.be/...', { lang: 'en' });
console.log(renderTranscript(transcript, 'md'));

Everything is typed. Errors are subclasses of KroszTubeError with a stable .code (DOWNLOAD_FAILED, VIDEO_UNAVAILABLE, TRANSCRIPT_NOT_FOUND, BINARY_FAILED, PLAYER_NOT_FOUND, INVALID_URL). Long operations accept an AbortSignal.

Binaries & cache

On first run KroszTube downloads a pinned, checksum-verified yt-dlp and a static ffmpeg build for your OS into ~/.krosztube/bin.

• KROSZTUBE_HOME — move the cache directory
• KROSZTUBE_YTDLP / KROSZTUBE_FFMPEG — use your own binaries instead

YouTube changes things regularly; when downloads start failing, krosztube update grabs the latest yt-dlp.

Exit codes

| Code | Meaning | |---|---| | 0 | success | | 1 | unexpected error | | 2 | usage error / invalid URL | | 3 | download or transcript failure | | 4 | binary provisioning failure | | 5 | video unavailable (private, removed, geo-blocked, age-gated) | | 6 | no media player found for play | | 130 | interrupted (Ctrl-C) |

Legal

Download only content you have the right to download. Respect YouTube's Terms of Service and copyright law in your jurisdiction. This tool is intended for personal backups of your own content, Creative-Commons material, and other authorized use.

Support

krosztube is free, with no accounts, ads or paywalls. If it saves you time, you can sponsor on GitHub.

Author

Created and maintained by Kroszborg. MIT licensed.