🔧 Installation

npm install dxz-ytdl

Global Installation (for CLI usage)

npm install -g dxz-ytdl

🖥️ CLI Usage

After installing globally, you can use dxz-ytdl directly from your terminal.

Show Help

dxz-ytdl --help

Output:

Usage: dxz-ytdl [options] [command]

Advanced YouTube downloader CLI with search

Options:
  -V, --version       output the version number
  -h, --help          display help for command

Commands:
  download <url>      Download audio/video from YouTube URL
  search <query>      Search YouTube videos
  help [command]      display help for a specific command

📥 Download Command

Download audio or video from a YouTube URL.

dxz-ytdl download <url> [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | -f, --format <type> | Format: mp3 or mp4 | mp3 | | -q, --quality <quality> | Quality (see below) | 128k for mp3, 360p for mp4 | | -o, --output <path> | Output directory path | ./downloads | | --retries <num> | Max retries for download | 3 |

Quality Options:

| Format | Available Qualities | |--------|---------------------| | mp3 | 32k, 64k, 128k, 192k, 256k, 320k, best | | mp4 | 144p, 240p, 360p, 480p, 720p, 1080p, best |

Examples:

Download MP3 (default quality 128k):

dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Download MP3 with specific quality:

dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f mp3 -q 320k

Download MP4 video:

dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f mp4 -q 720p

Download to custom directory:

dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f mp4 -q 1080p -o ./my-videos

Download with retries:

dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f mp3 -q best --retries 5

Sample Output:

Starting download for: https://www.youtube.com/watch?v=dQw4w9WgXcQ
Title: Rick Astley - Never Gonna Give You Up
Author: Rick Astley
Preparing mp3 download at 128k quality to ./downloads/Rick_Astley___Never_Gonna_Give_You_Up.mp3...
Duration: 212s
Filesize: 3.45 MB
Saved to: ./downloads/Rick_Astley___Never_Gonna_Give_You_Up.mp3
Download completed successfully!

🔍 Search Command

Search YouTube videos programmatically.

dxz-ytdl search <query> [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | -l, --limit <num> | Number of results to return | 10 | | -t, --type <type> | Type: video or playlist | video |

Examples:

Basic search:

dxz-ytdl search "rick astley never gonna give you up"

Search with limit:

dxz-ytdl search "coding tutorials" -l 5

Search for playlists:

dxz-ytdl search "lo-fi music" -t playlist -l 3

Sample Output:

Search Results:
1. Rick Astley - Never Gonna Give You Up by Rick Astley (212s) - https://www.youtube.com/watch?v=dQw4w9WgXcQ
2. Rick Astley - Together Forever by Rick Astley (205s) - https://www.youtube.com/watch?v=yPYZpwSpKmA
3. Rick Astley - Whenever You Need Somebody by Rick Astley (197s) - https://www.youtube.com/watch?v=BeyEGebJ1l4

📺 Programmatic Usage Examples

1️⃣ YouTube Search

JavaScript:

const { search } = require('dxz-ytdl');

console.log('=== Testing Search ===');
search('rick astley never gonna give you up', { limit: 5 })
  .then(results => {
    console.log('Search Results:', results);
    console.log('First result title:', results[0].title);
    console.log('First result URL:', results[0].url);
  })
  .catch(err => console.error('Search Error:', err.message));

Python:

import subprocess, json

command = 'node -e "const { search } = require(\'dxz-ytdl\'); search(\'coding tutorial\', { limit: 5 }).then(r => console.log(JSON.stringify(r)))"'
result = subprocess.getoutput(command)
data = json.loads(result)
print(data)

2️⃣ Download YouTube Audio (MP3) with Random Quality (Default)

JavaScript:

const { ytmp3 } = require('dxz-ytdl');

console.log('=== Testing ytmp3 with random quality (passing null) ===');
ytmp3('https://www.youtube.com/watch?v=dQw4w9WgXcQ', null)
  .then(result => {
    console.log('Random MP3 Result (quality:', result.quality, '):');
    console.log('Title:', result.title);
    console.log('Download URL:', result.downloadUrl);
  })
  .catch(err => console.error('Random MP3 Error:', err.message));

Python:

import subprocess, json

command = 'node -e "const { ytmp3 } = require(\'dxz-ytdl\'); ytmp3(\'https://www.youtube.com/watch?v=dQw4w9WgXcQ\', null).then(r => console.log(JSON.stringify(r)))"'
result = subprocess.getoutput(command)
data = json.loads(result)
print(data)

3️⃣ Download YouTube Audio (MP3) with Specific Quality

JavaScript:

const { ytmp3 } = require('dxz-ytdl');

console.log('=== Testing ytmp3 with explicit quality (128k) ===');
ytmp3('https://www.youtube.com/watch?v=dQw4w9WgXcQ', '128k')
  .then(result => {
    console.log('Title:', result.title);
    console.log('Author:', result.author);
    console.log('Format:', result.format);
    console.log('Quality:', result.quality);
    console.log('Download URL:', result.downloadUrl);
  })
  .catch(err => console.error('Explicit MP3 Error:', err.message));

Python:

import subprocess, json

command = 'node -e "const { ytmp3 } = require(\'dxz-ytdl\'); ytmp3(\'https://www.youtube.com/watch?v=dQw4w9WgXcQ\', \'128k\').then(r => console.log(JSON.stringify(r)))"'
result = subprocess.getoutput(command)
data = json.loads(result)
print(data)

4️⃣ Download YouTube Video (MP4) with Random Quality (Default)

JavaScript:

const { ytmp4 } = require('dxz-ytdl');

console.log('=== Testing ytmp4 with random quality (passing null) ===');
ytmp4('https://www.youtube.com/watch?v=dQw4w9WgXcQ', null)
  .then(result => {
    console.log('Random MP4 Result (quality:', result.quality, '):');
    console.log('Title:', result.title);
    console.log('Download URL:', result.downloadUrl);
  })
  .catch(err => console.error('Random MP4 Error:', err.message));

Python:

import subprocess, json

command = 'node -e "const { ytmp4 } = require(\'dxz-ytdl\'); ytmp4(\'https://www.youtube.com/watch?v=dQw4w9WgXcQ\', null).then(r => console.log(JSON.stringify(r)))"'
result = subprocess.getoutput(command)
data = json.loads(result)
print(data)

5️⃣ Download YouTube Video (MP4) with Specific Resolution

JavaScript:

const { ytmp4 } = require('dxz-ytdl');

console.log('=== Testing ytmp4 with explicit quality (360p) ===');
ytmp4('https://www.youtube.com/watch?v=dQw4w9WgXcQ', '360p')
  .then(result => {
    console.log('Title:', result.title);
    console.log('Author:', result.author);
    console.log('Format:', result.format);
    console.log('Quality:', result.quality);
    console.log('Download URL:', result.downloadUrl);
  })
  .catch(err => console.error('Explicit MP4 Error:', err.message));

Python:

import subprocess, json

command = 'node -e "const { ytmp4 } = require(\'dxz-ytdl\'); ytmp4(\'https://www.youtube.com/watch?v=dQw4w9WgXcQ\', \'360p\').then(r => console.log(JSON.stringify(r)))"'
result = subprocess.getoutput(command)
data = json.loads(result)
print(data)

6️⃣ Saving Files to Disk

Use the options object { path: './filename.ext' } to save files directly.

JavaScript (MP3 Save Example):

const { ytmp3 } = require('dxz-ytdl');
const path = require('path');

const savePath = path.join(__dirname, 'test_audio.mp3');
ytmp3('https://www.youtube.com/watch?v=dQw4w9WgXcQ', '128k', { path: savePath })
  .then(result => {
    console.log('Title:', result.title);
    console.log('Author:', result.author);
    console.log('Format:', result.format);
    console.log('Quality:', result.quality);
    console.log('Saved to:', result.savedTo);
  })
  .catch(err => console.error('Save Error:', err.message));

JavaScript (MP4 Save Example):

const { ytmp4 } = require('dxz-ytdl');
const path = require('path');

const savePath = path.join(__dirname, 'test_video.mp4');
ytmp4('https://www.youtube.com/watch?v=dQw4w9WgXcQ', '360p', { path: savePath })
  .then(result => {
    console.log('Title:', result.title);
    console.log('Author:', result.author);
    console.log('Format:', result.format);
    console.log('Quality:', result.quality);
    console.log('Saved to:', result.savedTo);
  })
  .catch(err => console.error('Save Error:', err.message));

Python (MP3 Save Example):

import subprocess, json

command = 'node -e "const { ytmp3 } = require(\'dxz-ytdl\'); ytmp3(\'https://www.youtube.com/watch?v=dQw4w9WgXcQ\', \'128k\', { path: \'./audio.mp3\' }).then(r => console.log(JSON.stringify(r)))"'
result = subprocess.getoutput(command)
data = json.loads(result)
print(data)

📋 API Reference

search(query, options)

Search YouTube for videos or playlists.

const { search } = require('dxz-ytdl');

const results = await search('query', { limit: 10, type: 'video' });

Options: | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | limit | number | Max results to return | 10 | | type | string | 'video' or 'playlist' | 'video' |

Returns: Array<Object>

[
  {
    title: "Video Title",
    url: "https://www.youtube.com/watch?v=...",
    author: "Channel Name",
    duration: 212,
    // ... other metadata
  }
]

ytmp3(url, quality, options)

Download YouTube audio as MP3.

const { ytmp3 } = require('dxz-ytdl');

// Without saving (returns download URL)
const result = await ytmp3('https://youtube.com/watch?v=VIDEO_ID', '128k');

// With saving to file
const result = await ytmp3('https://youtube.com/watch?v=VIDEO_ID', '128k', { path: './audio.mp3' });

Parameters: | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | url | string | YouTube video URL | Required | | quality | string\|null | Audio quality (32k, 64k, 128k, 192k, 256k, 320k, best) | Random if null | | options.path | string | File path to save | undefined | | options.retries | number | Max download retries | 3 |

Returns: Object

// Without save path:
{
  title: "Video Title",
  author: "Channel Name",
  format: "mp3",
  quality: "128k",
  duration: 212,
  downloadUrl: "https://..."
}

// With save path:
{
  title: "Video Title",
  author: "Channel Name",
  format: "mp3",
  quality: "128k",
  duration: 212,
  savedTo: "./audio.mp3"
}

ytmp4(url, quality, options)

Download YouTube video as MP4.

const { ytmp4 } = require('dxz-ytdl');

// Without saving (returns download URL)
const result = await ytmp4('https://youtube.com/watch?v=VIDEO_ID', '360p');

// With saving to file
const result = await ytmp4('https://youtube.com/watch?v=VIDEO_ID', '720p', { path: './video.mp4' });

Parameters: | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | url | string | YouTube video URL | Required | | quality | string\|null | Video quality (144p, 240p, 360p, 480p, 720p, 1080p, best) | Random if null | | options.path | string | File path to save | undefined | | options.retries | number | Max download retries | 3 |

Returns: Object

// Without save path:
{
  title: "Video Title",
  author: "Channel Name",
  format: "mp4",
  quality: "360p",
  duration: 212,
  downloadUrl: "https://..."
}

// With save path:
{
  title: "Video Title",
  author: "Channel Name",
  format: "mp4",
  quality: "360p",
  duration: 212,
  filesize: 15728640,
  savedTo: "./video.mp4"
}

⚡ Features

• ✅ CLI Support - Use directly from terminal with dxz-ytdl command
• ✅ Download MP3 - Multiple qualities (32kbps – 320kbps)
• ✅ Download MP4 - Multiple resolutions (144p – 1080p)
• ✅ Random Quality - Pass null for automatic quality selection
• ✅ Save to File - Direct file saving with { path: '...' } option
• ✅ Get Download URL - Get URL without saving for custom handling
• ✅ YouTube Search - Search videos and playlists programmatically
• ✅ Retry Support - Configurable retries for failed downloads
• ✅ Cross-Platform - Works on Windows, macOS, and Linux

📦 Package Structure

dxz-ytdl/
├── bin/
│   └── cli.js          # CLI entry point
├── index.js            # Main module exports
├── package.json
└── README.md

🛠️ Developed By

📄 License

MIT © DanuZz