JSPM

dlp-tools

1.0.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q21451F
  • License MIT

TypeScript wrapper for yt-dlp with binary management and fluent API

Package Exports

  • dlp-tools
  • dlp-tools/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (dlp-tools) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

dlp-tools

npm version License: MIT

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