yt-dlp-typescript-wrapper

TypeScript OOP wrapper for youtube-dl-exec with advanced YouTube Shorts support.

Features

• 🎯 OOP Architecture - Clean, maintainable code with TypeScript
• 📦 Modular Design - Separate classes for different functionalities
• 🎬 YouTube Shorts Support - Advanced Shorts downloading with multiple fallback methods
• 🔧 Configurable - Flexible configuration management
• 📊 Progress Tracking - Real-time download progress callbacks
• 🛡️ Error Handling - Comprehensive error handling and recovery
• 📝 TypeScript - Full TypeScript support with type definitions

Installation

npm i yt-dlp-typescript-wrapper

Quick Start

import { YtDlpManager, createYtDlpManager } from 'yt-dlp-typescript-wrapper'

// Create manager instance
const manager = createYtDlpManager()

// Download video
const result = await manager.downloadVideo(
	'https://youtube.com/watch?v=VIDEO_ID'
)

// Get Shorts from channel
const shorts = await manager.getChannelShorts('@kinoshorts', 5)

API Reference

YtDlpManager

Main class that combines video and shorts downloading functionality.

Methods

Video Downloading

// Get video information
const info = await manager.getVideoInfo(url: string): Promise<VideoInfo>

// Download video
const result = await manager.downloadVideo(url: string, options?: DownloadOptions): Promise<DownloadResult>

// Download video with specific quality
const result = await manager.downloadVideoWithQuality(url: string, quality: string, outputPath?: string): Promise<DownloadResult>

// Download audio only
const result = await manager.downloadAudio(url: string, outputPath?: string): Promise<DownloadResult>

// Download with custom options
const result = await manager.downloadWithCustomOptions(url: string, customOptions: Record<string, any>, outputPath?: string): Promise<DownloadResult>

Shorts Downloading

// Get Shorts URLs from channel
const urls = await manager.getChannelShorts(channelHandle: string, limit?: number): Promise<string[]>

// Get Shorts information from channel
const info = await manager.getChannelShortsInfo(channelHandle: string, limit?: number): Promise<ShortsInfo[]>

// Download all Shorts from channel
const results = await manager.downloadChannelShorts(channelHandle: string, options?: ChannelShortsOptions): Promise<DownloadResult[]>

// Alternative method for problematic channels
const urls = await manager.getChannelShortsAlternative(channelHandle: string, limit?: number): Promise<string[]>

Configuration

// Set progress callback
manager.setProgressCallback((progress: DownloadProgress) => {
	console.log(`Progress: ${progress.progress}%`)
})

// Get configuration
const config = manager.getConfig(): Record<string, any>

// Update configuration
manager.updateConfig(newConfig: Partial<Record<string, any>>): void

// Check yt-dlp availability
const available = await manager.checkYtDlpAvailability(): Promise<boolean>

// Get yt-dlp version
const version = await manager.getYtDlpVersion(): Promise<string>

Examples

Basic Video Download

import { createYtDlpManager } from 'yt-dlp-typescript-wrapper'

const manager = createYtDlpManager()

// Download video in best quality
const result = await manager.downloadVideo(
	'https://youtube.com/watch?v=VIDEO_ID'
)

if (result.success) {
	console.log('Video downloaded successfully!')
} else {
	console.error('Download failed:', result.error)
}

Download with Quality

// Download in 720p quality
const result = await manager.downloadVideoWithQuality(
	'https://youtube.com/watch?v=VIDEO_ID',
	'720p',
	'./downloads'
)

Download Audio

// Download audio only
const result = await manager.downloadAudio(
	'https://youtube.com/watch?v=VIDEO_ID',
	'./downloads/audio'
)

YouTube Shorts

// Get Shorts from channel
const shortsUrls = await manager.getChannelShorts('@kinoshorts', 10)

// Get Shorts information
const shortsInfo = await manager.getChannelShortsInfo('@kinoshorts', 5)

// Download all Shorts from channel
const results = await manager.downloadChannelShorts('@kinoshorts', {
	limit: 10,
	quality: '720p',
	output: './downloads/shorts'
})

Progress Tracking

// Set progress callback
manager.setProgressCallback(progress => {
	switch (progress.status) {
		case 'pending':
			console.log('Starting download...')
			break
		case 'downloading':
			console.log(`Downloading: ${progress.progress}%`)
			break
		case 'completed':
			console.log('Download completed!')
			break
		case 'failed':
			console.error('Download failed:', progress.error)
			break
	}
})

// Download with progress tracking
await manager.downloadVideo('https://youtube.com/watch?v=VIDEO_ID')

Configuration

// Update configuration
manager.updateConfig({
	downloadPath: './my-downloads',
	defaultOptions: {
		noCheckCertificates: true,
		noWarnings: true
	}
})

// Get current configuration
const config = manager.getConfig()
console.log('Current config:', config)

Types

VideoInfo

interface VideoInfo {
	title: string
	duration: number
	view_count: number
	uploader: string
	upload_date: string
	description?: string
	thumbnail?: string
	url: string
}

DownloadResult

interface DownloadResult {
	index: number
	url: string
	success: boolean
	result?: string
	error?: string
}

ShortsInfo

interface ShortsInfo {
	index: number
	url: string
	title: string
	duration: number
	viewCount: number
	uploadDate: string
	thumbnail?: string
}

DownloadProgress

interface DownloadProgress {
	status: 'pending' | 'downloading' | 'completed' | 'failed'
	progress?: number
	currentFile?: string
	totalFiles?: number
	currentIndex?: number
	error?: string
}

Error Handling

The library provides custom error classes for better error handling:

import {
	YtDlpError,
	VideoInfoError,
	VideoDownloadError,
	AudioDownloadError,
	ShortsRetrievalError,
	ShortsDownloadError,
	ConfigurationError,
	YtDlpNotAvailableError,
	InvalidUrlError,
	InvalidChannelError,
	NetworkError,
	FileAccessError
} from 'yt-dlp-typescript-wrapper'

try {
	const manager = createYtDlpManager()
	const info = await manager.getVideoInfo(
		'https://youtube.com/watch?v=VIDEO_ID'
	)
} catch (error) {
	if (error instanceof VideoInfoError) {
		console.error('Failed to get video info:', error.message)
		console.error('URL:', error.url)
	} else if (error instanceof YtDlpNotAvailableError) {
		console.error('yt-dlp is not available')
	} else if (error instanceof InvalidUrlError) {
		console.error('Invalid URL provided')
	} else {
		console.error('Unknown error:', error)
	}
}

Available Error Classes

• YtDlpError - Base error class for all library errors
• VideoInfoError - Error when getting video information
• VideoDownloadError - Error when downloading video
• AudioDownloadError - Error when downloading audio
• ShortsRetrievalError - Error when retrieving shorts from channel
• ShortsDownloadError - Error when downloading shorts
• ConfigurationError - Error with configuration
• YtDlpNotAvailableError - Error when yt-dlp is not available
• InvalidUrlError - Error when URL is invalid
• InvalidChannelError - Error when channel is invalid
• NetworkError - Network-related errors
• FileAccessError - File system access errors

Requirements

• Node.js 16+
• yt-dlp or youtube-dl installed
• TypeScript 5.0+

Installation of yt-dlp

macOS

brew install yt-dlp

Windows

pip install yt-dlp

Linux

sudo pip install yt-dlp

Configuration

Set the YT_DL_BIN_PATH environment variable to point to your yt-dlp installation:

export YT_DL_BIN_PATH=/usr/local/bin/yt-dlp

License

MIT

Author

Nick