yt-dlp-typescript-wrapper/README.md

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

# 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

```bash
npm i yt-dlp-typescript-wrapper
```

## Quick Start

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
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

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

### Download Audio

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

### YouTube Shorts

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

### DownloadResult

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

### ShortsInfo

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

### DownloadProgress

```typescript
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:

```typescript
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

```bash
brew install yt-dlp
```

### Windows

```bash
pip install yt-dlp
```

### Linux

```bash
sudo pip install yt-dlp
```

## Configuration

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

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

## License

MIT

## Author

Nick