dlp-tools

A modern TypeScript wrapper for yt-dlp that includes automatic binary management and a fluent API to download videos and audio from YouTube and many other platforms.

Features

• Full TypeScript wrapper for yt-dlp
• Automatic binary management (yt-dlp and FFmpeg)
• Fluent and strongly typed API with autocompletion
• Video and audio downloads in multiple formats
• Real-time streaming with Node.js pipes
• Progress callbacks for download monitoring
• Detailed video/playlist info extraction
• Cross-platform support (Windows, macOS, Linux)

📦 Installation

npm install dlp-tools

Basic Usage

Import

import { Ytdlp } from 'dlp-tools';

Initial Setup

const ytdlp = new Ytdlp({
  binary: {
    outputDir: './bin',                        // Directory for binaries
    ffmpegPath: './bin/ffmpeg.exe',           // FFmpeg path (optional)
    ytdlpPath: './bin/yt-dlp.exe',           // yt-dlp path (optional)
    autoDownload: true,                      // Automatically download binaries
  },
});

Usage Examples

1. Get Video Info

// Basic video info
const info = await ytdlp.getInfo('https://www.youtube.com/watch?v=VIDEO_ID');
console.log(info.title);
console.log(info.duration);
console.log(info.formats);

// Playlist info
const playlistInfo = await ytdlp.getInfo('https://www.youtube.com/playlist?list=PLAYLIST_ID', {
  dumpSingleJson: true,  // A single JSON for the entire playlist
});

// Flat playlist (only IDs and URLs)
const flatPlaylist = await ytdlp.getInfo('https://www.youtube.com/playlist?list=PLAYLIST_ID', {
  flatPlaylist: true,    // Simplified list
});

2. Download Videos

Simple Download

const outputPath = await ytdlp.download('https://www.youtube.com/watch?v=VIDEO_ID', {
  format: {
    filter: 'mergevideo',
    quality: {
      video: '720p',
      audio: 'medium',
    },
    type: 'mp4',
  },
  output: './downloads/%(title)s.%(ext)s',
});

console.log('Video downloaded to:', outputPath);

Download with Progress Callbacks

await ytdlp.download('https://www.youtube.com/watch?v=VIDEO_ID', {
  format: {
    filter: 'mergevideo',
    quality: {
      video: '1080p',
      audio: 'highest',
    },
    type: 'mp4',
  },
  
  // Progress callback
  onProgress: (progress) => {
    console.log(`Downloading: ${progress.percent_str} - ${progress.speed_str}`);
    console.log(` ETA: ${progress.eta_str} - File: ${progress.filename}`);
  },
  
  // Error callback
  onError: (error) => {
    console.error('Error during download:', error.message);
  },
  
  // Completion callback
  onEnd: () => {
    console.log('Download completed!');
  },
});

Audio-Only Download

await ytdlp.download('https://www.youtube.com/watch?v=VIDEO_ID', {
  format: {
    filter: 'audioonly',
    quality: 'highest',
    type: 'mp3',
  },
  output: './music/%(title)s.%(ext)s',
});

Video-Only Download (no audio)

await ytdlp.download('https://www.youtube.com/watch?v=VIDEO_ID', {
  format: {
    filter: 'videoonly',
    quality: '1080p',
    type: 'mp4',
  },
});

3. Real-Time Streaming

import { createWriteStream } from 'fs';

// Create destination stream
const outputStream = createWriteStream('video.mp4');

// Start streaming
const streamResponse = ytdlp.stream('https://www.youtube.com/watch?v=VIDEO_ID', {
  format: {
    filter: 'mergevideo',
    quality: {
      video: '720p',
      audio: 'medium',
    },
    type: 'mp4',
  },
});

// Method 1: Asynchronous pipe
await streamResponse.pipe(outputStream);

// Method 2: Synchronous pipe
streamResponse.pipeSync(outputStream);

// Method 3: Work with the promise directly
await streamResponse.promise;

4. Playlist Download

// Download full playlist
await ytdlp.download('https://www.youtube.com/playlist?list=PLAYLIST_ID', {
  format: {
    filter: 'mergevideo',
    quality: {
      video: '720p',
      audio: 'medium',
    },
    type: 'mp4',
    playlist: {
      items: ['1-5'],           // Only the first 5 videos
      titleFilter: {
        match: '.*tutorial.*',  // Only videos containing "tutorial" in the title
      },
    },
  },
  output: './playlist/%(playlist_index)s - %(title)s.%(ext)s',
});

5. Custom Command Execution

// Execute a custom yt-dlp command
const result = await ytdlp.exec('https://www.youtube.com/watch?v=VIDEO_ID', {
  listFormats: true,          // --list-formats
  cookies: './cookies.txt',   // --cookies
  noWarnings: true,           // --no-warnings
});

console.log(result);

7. Re-descarga de Binarios

// Re-descargar todos los binarios
await ytdlp.redownloadBinaries();

// Re-descargar solo FFmpeg
await ytdlp.redownloadBinaries({
  ffmpeg: true,
  ytdlp: false
});

// Re-descargar solo yt-dlp
await ytdlp.redownloadBinaries({
  ffmpeg: false,
  ytdlp: true
});

Configuración Avanzada

Format Options

type FormatOptions = {
  // Available filters
  filter: 'videoonly' | 'audioonly' | 'mergevideo' | 'audioandvideo' | 'subtitle';
  
  // Video quality options
  quality: '2160p' | '1440p' | '1080p' | '720p' | '480p' | '360p' | '240p' | '144p' | 'highest' | 'lowest';
  
  // Audio quality options
  quality: 'highest' | 'high' | 'medium' | 'low' | 'lowest';
  
  // Output formats
  type: 'mp4' | 'webm' | 'mkv' | 'mp3' | 'aac' | 'flac' | 'opus' | 'wav';
};

Binary Configuration

const ytdlp = new Ytdlp({
  binary: {
    outputDir: './bin',                    // Directory to store binaries
    ytdlpPath: '/custom/path/yt-dlp',     // Custom yt-dlp path
    ffmpegPath: '/custom/path/ffmpeg',    // Custom FFmpeg path
    autoDownload: false,                  // Disable automatic download
  },
});

Cookies and Authentication

await ytdlp.download(url, {
  cookies: './cookies.txt',              // Cookies file
  cookiesFromBrowser: 'chrome',          // Use browser cookies
  username: 'user',                      // Username for login-required sites
  password: 'password',                  // Password
});

Network Options

await ytdlp.download(url, {
  proxy: 'http://proxy:8080',           // Use a proxy
  socketTimeout: 30,                    // Timeout in seconds
  throttledRate: '50K',                 // Limit download speed
  fileAccessRetries: 3,                 // Retry on failure
});

Progress Interface

interface VideoProgress {
  id: string;                    // Video ID
  filename: string;              // File name
  status: 'downloading' | 'finished';  // Current status
  downloaded: number;            // Bytes downloaded
  downloaded_str: string;        // Readable downloaded size
  total: number;                 // Total bytes
  total_str: string;             // Readable total size
  speed: number;                 // Bytes per second
  speed_str: string;             // Readable speed
  eta: number;                   // Estimated time (seconds)
  eta_str: string;               // Readable ETA
  percent: number;               // Completion percentage (0–100)
  percent_str: string;           // Readable percentage
}

NPM Scripts

# Development
npm run dev

# Build
npm run build

# Run after build
npm start

# Prepare for publishing
npm run prepublishOnly

📚 Additional Resources

• yt-dlp Documentation
• Supported Sites List
• FFmpeg Documentation