yt-direct

Zero-dependency YouTube video downloader — InnerTube API (same as yt-dlp). No external modules.

npm install yt-direct

const ytdl = require('yt-direct');
// or: import ytdl from 'yt-direct';

---

Features

• No dependencies — only Node.js built-ins
• InnerTube API — no scraper, no API key
• Quality selection — auto, 2160p, 1440p, 1080p, 720p, 480p, 360p, audio
• Format selection — mp4, webm, mkv, avi, mov, m4a, aac, flac, ogg, mp3, wav
• Merge tools — auto-detects ffmpeg, avconv, mkvmerge, gstreamer
• Streaming — pipe directly to any writable stream
• Custom headers, cookies, timeout, retries
• Download result includes statusCode + timing + speed

---

Quick Start

const video = await ytdl('https://www.youtube.com/watch?v=dQw4w9WgXcQ', {
  quality: '720p',
  format: 'mp4',
});

console.log('Title:', video.title);
const result = await video.download('./video.mp4');
console.log('Downloaded:', result.size, 'bytes in', result.time, 'ms');
console.log('Status:', result.statusCode, '| Speed:', result.speed, 'MB/s');

---

API Reference

ytdl(url, options?)

Returns a VideoResult object.

Option	Type	Default	Description
quality	string	'auto'	auto, best, 2160p, 1440p, 1080p, 720p, 480p, 360p, audio
format	string	null	Target container (see Format Support)
filter	string	'audioandvideo'	audioandvideo, videoonly, audioonly
language	string	'en'	ISO code: en, es, pt, fr, de, ja, etc
preferMp4	boolean	true	Prefer mp4 over webm at same quality
concurrency	number	1	Parallel chunks (1–12). 1 = sequential, starts instantly
timeout	number	30000	Per-request timeout in ms (5000–600000)
retries	number	3	Retry attempts on failure (0–10)
headers	object	null	Extra HTTP headers { 'X-Custom': 'value' }
cookies	string|object	null	Cookie string or { name: value } object
merge	object	null	Merge config (see Merging)
onProgress	function	null	(downloaded, total) called during download

VideoResult

Property	Type	Description
title	string	Video title
url	string	Direct stream URL
format	Format	Selected video format
audio	Format?	Audio format (if separate stream)
type	string	combined, separate, video-only, audio
stream()	ReadableStream	Get a readable stream
pipe(w)	Writable	Pipe to a writable stream
download(path?)	Promise<DownloadResult>	Download to file

DownloadResult

{
  path: '/tmp/video.mp4',
  size: 26455880,          // bytes
  statusCode: 206,          // HTTP status from CDN
  time: 3120,               // download time in ms
  speed: 8.1,               // MB/s
}

---

Download URL Only (no download)

const video = await ytdl('https://www.youtube.com/watch?v=xxx', {
  quality: '1080p',
});

console.log('Video URL:', video.url);
if (video.audio) console.log('Audio URL:', video.audio.url);

---

Streaming

const video = await ytdl(url, { quality: '720p' });
video.pipe(fs.createWriteStream('./video.mp4'));

---

Merging Audio + Video

1080p+ requires merging separate streams. yt-direct auto-detects: ffmpeg, avconv, mkvmerge, gstreamer.

const video = await ytdl(url, {
  quality: '2160p',
  format: 'mp4',
  merge: {
    tool: 'ffmpeg',          // auto-detect from PATH
    path: '/usr/bin/ffmpeg', // or specify custom path
  },
});

const result = await video.merge('./output.mp4');
console.log('Merged in', result.time, 'ms');

---

Audio-Only

const audio = await ytdl(url, { quality: 'audio', format: 'm4a' });
await audio.download('./audio.m4a');

// MP3 requires conversion:
const audio = await ytdl(url, { quality: 'audio', format: 'mp3', merge: { tool: 'ffmpeg' } });
await audio.merge('./audio.mp3');

---

Custom Headers, Cookies & Timeout

const video = await ytdl(url, {
  quality: '1080p',
  headers: { 'X-Forwarded-For': '1.2.3.4' },
  cookies: { 'CONSENT': 'YES+1' },
  timeout: 60000,
  retries: 5,
});

---

Get Video Info

const info = await ytdl.getInfo('https://youtube.com/watch?v=xxx');

console.log(info.title);
console.log(info.formats);   // [{ itag, quality, container, codec, size, type, hasUrl }]
console.log(info.combined);  // audio+video formats
console.log(info.adaptive);  // separate audio/video
console.log(info.clientUsed); // 'ANDROID' or 'ANDROID_VR'

---

Verify URL

const ok = await ytdl.verifyURL(url);
console.log(ok); // true if CDN returns 200/206

---

Error Handling

const { YouTubeError, FormatError, ValidationError, QualityError, MergeError, NetworkError } = ytdl;

try {
  await ytdl(url, { format: 'mp3' });
} catch (err) {
  if (err instanceof FormatError) {
    console.log('Requires conversion:', err.details);
  }
}

---

Format Support

Native (direct from YouTube)

Container	Extension	Video Codecs	Audio
MP4	.mp4	H.264, AV1	AAC
WebM	.webm	VP9, AV1	Opus
M4A	.m4a	—	AAC

Require Conversion (merge tool needed)

Container	Extension
MKV	.mkv
AVI	.avi
MOV	.mov
MP3	.mp3
AAC	.aac
FLAC	.flac
OGG	.ogg
WAV	.wav

---

Quality Reference

Quality	Resolution	Bitrate
4320p	7680×4320	40–80 Mbps
2160p	3840×2160	20–45 Mbps
1440p	2560×1440	10–20 Mbps
1080p	1920×1080	5–12 Mbps
720p	1280×720	2.5–6 Mbps
480p	854×480	1–3 Mbps
360p	640×360	0.5–1.5 Mbps
audio	—	32–256 Kbps

Fallback: if requested quality is unavailable, next lower tier is tried automatically.

---

Available Constants

console.log('Formats:', ytdl.FORMATS);    // ['mp4','webm','mkv',...]
console.log('Qualities:', ytdl.QUALITIES); // ['4320p','2160p',...,'auto','best','audio']
console.log('Version:', ytdl.version);

---

Requirements

• Node.js 18+