ytdlp-nodejs

ytdlp-nodejs is a Node.js wrapper for the yt-dlp command-line tool. It allows developers to integrate video downloading, streaming, and metadata extraction into Node.js applications without manually managing child processes or parsing CLI output.

Key capabilities include:

• Downloading: Saving video/audio to disk with progress tracking.
• Streaming: Piping data directly to Node.js streams (e.g., Express responses).
• Metadata Extraction: Fetching typed video information, formats, and playlists.
• Binary Management: Automatic handling of the yt-dlp executable.
• Customization: Support for all yt-dlp features (subtitles, cookies, custom formats) and raw argument passing.

For sites supporting direct credential entry, use the username and password options. If the site requires Two-Factor Authentication (2FA), provide the code via the twofactor option.

// Username and Password
await ytdlp.downloadAsync(url, {
  username: 'your_username',
  password: 'your_password',
});

// Two-Factor Authentication
await ytdlp.downloadAsync(url, {
  username: 'your_username',
  password: 'your_password',
  twofactor: '123456', // 2FA code
});

For services like Vimeo that protect specific videos with a password, use the videoPassword option.

await ytdlp.downloadAsync(url, {
  videoPassword: 'video_password',
});

You can use specific commands that trigger interactive prompts to select options like quality or format. This is useful when you want to be guided through the selection process.

• Download Video: Prompts for video quality (e.g., 4K, 1080p) and optional extra arguments.
• Download Audio: Prompts for audio format (MP3, M4A, WAV, or Best Quality) and optional extra arguments.
• Get Video Info: Displays formatted metadata like title, uploader, duration, and views.

ytdlp download <url>
ytdlp audio <url>
ytdlp info <url>

To launch the interactive menu, run the ytdlp command without any arguments. This mode provides a guided interface for common tasks such as downloading videos/audio, retrieving video information, updating the yt-dlp binary, or downloading FFmpeg binaries.

npx ytdlp
# or if installed globally
ytdlp

To download a subset of a playlist instead of the whole thing, use the playlistItems option in the downloadAsync configuration object. Supported formats include:

• Ranges: '1-5' (first 5 videos)
• Specific indices: '1,3,5' (videos 1, 3, and 5)
• From index to end: '5-' (from video 5 to the end)

await ytdlp.downloadAsync(playlistUrl, {
  playlistItems: '1-5', // First 5 videos
  // playlistItems: '1,3,5', // Videos 1, 3, and 5
  // playlistItems: '5-',    // From video 5 to the end
});

Install the package using npm to get a type-safe Node.js wrapper for yt-dlp.

Note: FFmpeg is recommended for full functionality. You can install it manually on your system or use the built-in downloadFFmpeg() method provided by the library.

npm install ytdlp-nodejs

To download subtitle files separately from the video file, set writeSubs: true in the options object passed to downloadAsync. You can specify which languages to download using the subLangs array. By default, subtitles are saved as .vtt files.

await ytdlp.downloadAsync(url, {
  writeSubs: true,
  subLangs: ['en', 'es'], // Languages: English and Spanish
});

You can use SponsorBlock to handle crowdsourced segments (like sponsors or intros) in YouTube videos. You have two modes of operation:

1. Marking: Uses sponsorblockMark to create chapters within the video file for specific segments.
2. Removing: Uses sponsorblockRemove to physically cut segments out of the video file.

Note: Using the sponsorblockRemove mode requires FFmpeg to be installed on your system.

import { YtDlp } from 'ytdlp-nodejs';

const ytdlp = new YtDlp();

await ytdlp.downloadAsync(url, {
  // Mark segments as chapters
  sponsorblockMark: ['sponsor', 'intro', 'outro', 'selfpromo'],

  // Or remove segments entirely from the downloaded file
  sponsorblockRemove: ['sponsor', 'selfpromo'],
});

You can route your requests through a proxy using the .proxy() method in the fluent builder API or the proxy option in downloadAsync.

// Using fluent builder API
const result = await ytdlp
  .download(url)
  .proxy('http://user:pass@proxyhost:port')
  .run();

// Using downloadAsync
await ytdlp.downloadAsync(url, {
  proxy: 'http://user:pass@proxyhost:port',
});

If a specific yt-dlp flag is not explicitly supported by the ytdlp-nodejs API, you can pass it directly using the .addArgs() method in the fluent builder API or the rawArgs option in downloadAsync. This is useful for advanced filtering or specific command-line behaviors.

// Using fluent builder API
const result = await ytdlp
  .download(url)
  .format({ filter: 'mergevideo', quality: '1080p', type: 'mp4' })
  .addArgs('--match-filter', 'duration > 60')
  .run();

// Using downloadAsync
await ytdlp.downloadAsync(url, {
  rawArgs: ['--match-filter', 'duration > 60'],
});