yt-down

YouTube downloader — CLI tool and Node.js package. Powered by yt-dlp.

Features

• Download single videos or full playlists
• Choose video quality (4K / 1080p / 720p / 480p / 360p)
• Choose video format (MP4 / MKV / WebM)
• Audio-only download (MP3 / AAC / FLAC / WAV / Opus / M4A)
• Split video by chapters (removes the original after splitting)
• Playlist range selection (e.g. videos 1–5 only)
• Skips already-downloaded videos via a per-directory archive
• Resumes gracefully past unavailable or geo-blocked playlist items
• No maximum video duration

Requirements

• Node.js 18+
• ffmpeg — required for merging streams and chapter splitting

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

yt-dlp is downloaded automatically on first run via yt-dlp-exec.

CLI

Install

npm install -g yt-down

Usage

yt-down                          # interactive — prompts for URL and options
yt-down <url>                    # URL as argument, prompts for the rest

Interactive prompts

Paste a YouTube URL:   <url>
Audio only?            Yes / No
  → Video quality:     best / 4K / 1080p / 720p / 480p / 360p
  → Video format:      MP4 / MKV / WebM
  → Audio format:      MP3 / AAC / FLAC / WAV / Opus / M4A
Split by chapters?     Yes / No   (shown only when the video has chapters)
Output directory:      ~/Downloads (default)

For playlists an extra prompt appears:

Playlist: "Series Name" (12 videos). Download all?   Yes / No
  → Which videos? (e.g. 1-5 or 1,3,7)

Node.js API

import { download, getVideoInfo, getPlaylistInfo } from 'yt-down'

getVideoInfo(url)

const info = await getVideoInfo(url)

if (info.isPlaylist) {
  console.log(info.title, info.count)   // playlist title + video count
} else {
  console.log(info.title, info.chapters) // video title + chapter list
}

download(url, options)

await download(url, {
  outputDir: '/tmp/videos',
  quality: '1080p',          // 'best' | '4K' | '1080p' | '720p' | '480p' | '360p'
  videoFormat: 'mp4',        // 'mp4' | 'mkv' | 'webm'
  audioOnly: false,
  audioFormat: 'mp3',        // 'mp3' | 'aac' | 'flac' | 'wav' | 'opus' | 'm4a'
  splitChapters: false,
  playlistItems: '1-5',      // null = all
  onProgress({ percent, speed, eta }) {
    console.log(`${percent}% at ${speed}`)
  },
})

Express integration

import express from 'express'
import { createInfoHandler, createExpressHandler } from 'yt-down'

const app = express()
app.use(express.json())

// GET /info?url=<youtube-url>
app.get('/info', createInfoHandler())

// POST /download  { url, quality, videoFormat, audioOnly, audioFormat, playlistItems }
// Streams the file directly to the browser as a download.
app.post('/download', createExpressHandler())

Development

npm run build   # compile TypeScript → dist/
npm run dev     # run CLI directly with tsx (no build step)
npm start       # run compiled CLI

License

MIT