Advanced YouTube downloader with search support. Supports audio/video downloads and CLI usage.
---
dxz-ytdl is a Node.js package to download YouTube videos and audio easily, fetch transcripts, and search YouTube content programmatically. Powered by DanuZz and crafted with love for developers.
🌐 Visit: movanest.xyz
---
``bash`
npm install dxz-ytdl
`bash`
npm install -g dxz-ytdl
---
After installing globally, you can use dxz-ytdl directly from your terminal.
`bash`
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
search
help [command] display help for a specific command
`
---
Download audio or video from a YouTube URL.
`bash`
dxz-ytdl download
#### Options:
| Option | Description | Default |
|--------|-------------|---------|
| -f, --format | Format: mp3 or mp4 | mp3 |-q, --quality
| | Quality (see below) | 128k for mp3, 360p for mp4 |-o, --output
| | Output directory path | ./downloads |--retries
| | 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):
`bash`
dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
Download MP3 with specific quality:
`bash`
dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f mp3 -q 320k
Download MP4 video:
`bash`
dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f mp4 -q 720p
Download to custom directory:
`bash`
dxz-ytdl download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -f mp4 -q 1080p -o ./my-videos
Download with retries:
`bash`
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 YouTube videos programmatically.
`bash`
dxz-ytdl search
#### Options:
| Option | Description | Default |
|--------|-------------|---------|
| -l, --limit | Number of results to return | 10 |-t, --type
| | Type: video or playlist | video |
#### Examples:
Basic search:
`bash`
dxz-ytdl search "rick astley never gonna give you up"
Search with limit:
`bash`
dxz-ytdl search "coding tutorials" -l 5
Search for playlists:
`bash`
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
---
JavaScript:
`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:
`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)
`
---
JavaScript:
`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:
`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)
`
---
JavaScript:
`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:
`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)
`
---
JavaScript:
`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:
`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)
`
---
JavaScript:
`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:
`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)
`
---
Use the options object { path: './filename.ext' } to save files directly.
JavaScript (MP3 Save Example):
`javascript
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):
`javascript
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):
`python
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)
`
---
Search YouTube for videos or playlists.
`javascript
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
---
Download YouTube audio as MP3.
`javascript
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`javascript
// 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"
}
`
---
Download YouTube video as MP4.
`javascript
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`javascript
// 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"
}
`
---
- ✅ CLI Support - Use directly from terminal with dxz-ytdl commandnull
- ✅ Download MP3 - Multiple qualities (32kbps – 320kbps)
- ✅ Download MP4 - Multiple resolutions (144p – 1080p)
- ✅ Random Quality - Pass for automatic quality selection{ path: '...' }
- ✅ Save to File - Direct file saving with 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
---
```
dxz-ytdl/
├── bin/
│ └── cli.js # CLI entry point
├── index.js # Main module exports
├── package.json
└── README.md
---
DanuZz | Full-Stack Developer & Bot Maestro
🌍 Location: Ratnapura/Sabaragamuwa/Sri Lanka
🌱 Exploring: AI, Web3, Next.js, immersive UI/UX
🎯 Goal: Build code that inspires and captivates
---
MIT © DanuZz
---