@derimalec/ytdl-to-mp3

YouTube Downloader v2.0

A powerful Node.js library to download YouTube videos and convert them to various formats

🚀 What's New in v2.0

• 📹 Video Downloads: Download YouTube videos in 6 formats: MP4, FLV, AVI, MOV, MKV, 3GP
• 🎵 Multiple Audio Formats: Support for 5 audio formats: MP3, WAV, AAC, FLAC, OGG
• 🎯 Enhanced Quality Control: Smart quality validation and better selection options
• 📁 Auto Directory Creation: Automatically creates output directories if they don't exist

📦 Installation

npm install @derimalec/ytdl-to-mp3

🎯 Quick Start

import { ytDownloader } from "@derimalec/ytdl-to-mp3";

// Download video as MP4 (most compatible)
const videoResult = await ytDownloader.download("https://www.youtube.com/watch?v=VIDEO_ID", "./downloads/", {
  outputFormat: "video",
  videoFormat: "mp4",
  quality: "highest"
});

// Convert to high-quality MP3 audio
const audioResult = await ytDownloader.download("https://www.youtube.com/watch?v=VIDEO_ID", "./downloads/", {
  outputFormat: "audio",
  audioFormat: "mp3",
  audioBitrate: 320
});

📚 API Reference

Main Download Method

download(url: string, outputPath: string, options: DownloadOptions): Promise<{ path: string }>

DownloadOptions

interface DownloadOptions {
  quality?: Quality;           // "lowest" | "highest" | "highestaudio" | "lowestaudio" | "highestvideo" | "lowestvideo"
  outputFormat: OutputFormat;  // "audio" | "video"
  videoFormat?: VideoFormat;   // "mp4" | "flv" | "avi" | "mov" | "mkv" | "3gp"
  audioFormat?: AudioFormat;   // "mp3" | "wav" | "aac" | "flac" | "ogg"
  audioBitrate?: number;       // Audio bitrate (default: 128)
}

📊 Supported Formats

🎥 Video Formats

Format	Video Codec	Audio Codec	Best For	File Size
MP4	H.264	AAC	General use, web, mobile	Medium
FLV	H.264	AAC	Flash legacy, web streaming	Medium
AVI	H.264	AAC	Universal compatibility	Large
MOV	H.264	AAC	Apple devices, macOS/iOS	Medium
MKV	H.264	AAC	High quality, open source	Large
3GP	H.264	AAC	Mobile devices, low bandwidth	Very Small

🎵 Audio Formats

Format	Codec	Quality	Compression	Best For
MP3	MPEG-1 Layer III	Lossy	Good	Universal compatibility
WAV	PCM	Lossless	None	Professional audio
AAC	Advanced Audio Coding	Lossy	Better than MP3	Modern devices, Apple
FLAC	Free Lossless	Lossless	~50%	Audiophile quality
OGG	Vorbis	Lossy	Excellent	Open source projects

🎥 Video Download Examples

import { ytDownloader } from "@derimalec/ytdl-to-mp3";

// High quality MP4 download (recommended)
const mp4Result = await ytDownloader.download("https://www.youtube.com/watch?v=VIDEO_ID", "./downloads/", {
  outputFormat: "video",
  videoFormat: "mp4",
  quality: "highest"
});

// AVI for universal compatibility
const aviResult = await ytDownloader.download("https://www.youtube.com/watch?v=VIDEO_ID", "./downloads/", {
  outputFormat: "video",
  videoFormat: "avi",
  quality: "highest"
});

// MOV for Apple devices
const movResult = await ytDownloader.download("https://www.youtube.com/watch?v=VIDEO_ID", "./downloads/", {
  outputFormat: "video",
  videoFormat: "mov",
  quality: "highest"
});

// 3GP for mobile/low bandwidth
const gp3Result = await ytDownloader.download("https://www.youtube.com/watch?v=VIDEO_ID", "./downloads/", {
  outputFormat: "video",
  videoFormat: "3gp",
  quality: "lowest"
});

🎵 Audio Conversion Examples

// High quality MP3 conversion (most popular)
const mp3Result = await ytDownloader.download(url, "./downloads/", {
  outputFormat: "audio",
  audioFormat: "mp3",
  audioBitrate: 320,
  quality: "highestaudio"
});

// FLAC for audiophile quality (lossless)
const flacResult = await ytDownloader.download(url, "./downloads/", {
  outputFormat: "audio",
  audioFormat: "flac",
  audioBitrate: 320
});

// WAV for professional use (uncompressed)
const wavResult = await ytDownloader.download(url, "./downloads/", {
  outputFormat: "audio",
  audioFormat: "wav",
  audioBitrate: 192
});

// AAC for modern devices
const aacResult = await ytDownloader.download(url, "./downloads/", {
  outputFormat: "audio",
  audioFormat: "aac",
  audioBitrate: 256
});

// OGG for open source projects
const oggResult = await ytDownloader.download(url, "./downloads/", {
  outputFormat: "audio",
  audioFormat: "ogg",
  audioBitrate: 256
});

🔄 Backward Compatibility

Your existing v1.x code will continue to work:

// This still works from v1.x
const { path } = await ytDownloader.download(
  "https://www.youtube.com/watch?v=VIDEO_ID",
  "./downloads/",
  "highestaudio"
);

// Or use the dedicated method
const result = await ytDownloader.downloadAudio(
  "https://www.youtube.com/watch?v=VIDEO_ID",
  "./downloads/",
  "highestaudio"
);

🎯 Quality Validation

v2.0 includes smart quality validation:

// ✅ Valid combinations
{ outputFormat: "audio", quality: "highestaudio" }   // Works
{ outputFormat: "audio", quality: "lowestaudio" }    // Works
{ outputFormat: "video", quality: "highest" }        // Works
{ outputFormat: "video", quality: "highestvideo" }   // Works

// ❌ Invalid combinations (will throw errors)
{ outputFormat: "audio", quality: "highestvideo" }   // Error!
{ outputFormat: "video", quality: "highestaudio" }   // Error!

🛠 Custom Implementation

You can also create your own downloader class:

import { Downloader } from "@derimalec/ytdl-to-mp3";

class MyCustomDownloader extends Downloader {
  // Add your custom methods here
}

const customDownloader = new MyCustomDownloader();

⚙️ Requirements

• Node.js 14+
• FFmpeg (automatically installed via @ffmpeg-installer/ffmpeg)

📁 File Output

• 📁 Auto-creates output directories if they don't exist
• 🏷️ Auto-names files using the YouTube video title
• 🧹 Sanitizes filenames to remove unsafe characters (<>:"/\|?*)
• 📎 Auto-adds appropriate file extensions
• 💾 Saves to: {outputPath}/{sanitized_title}.{extension}

📊 Progress Tracking

v2.0 includes real-time progress tracking:

🎥 Starting video download: Song_Title.mp4
📥 Downloading: 45% | Time: 00:01:23
✅ Video download completed: downloads/Song_Title.mp4

🚀 Performance Tips

• MP4 - Best balance of quality, compatibility, and speed
• 3GP - Fastest downloads, smallest files for mobile
• FLAC - Best audio quality but larger files
• MP3 320kbps - Best audio quality/size balance

📝 License

ISC

🤝 Contributing

Feel free to submit issues and pull requests on GitHub!

---