# yt-dlp-wrapper

A TypeScript wrapper library for [yt-dlp](https://github.com/yt-dlp/yt-dlp), a powerful command-line video downloader.

[![NPM Version](https://img.shields.io/npm/v/yt-dlp-wrapper.svg)](https://www.npmjs.com/package/yt-dlp-wrapper)
[![License](https://img.shields.io/npm/l/yt-dlp-wrapper.svg)](https://github.com/yourusername/yt-dlp-wrapper/blob/main/LICENSE)

## Features

- 🔄 **Full TypeScript support** with comprehensive type definitions
- 🧩 **Modular architecture** for easy integration into your projects
- 🔍 **Zod validation** for reliable input/output handling
- 📊 **Structured logging** with TSLog
- 🛠️ **Command-line interface** built with yargs
- ⚡ **Promise-based API** for easy async operations
- 🔧 **Highly configurable** with sensible defaults
- 🔄 **Progress tracking** for downloads
- 💼 **Error handling** with clear error messages
- 🎵 **Audio extraction** with MP3 conversion support

## Prerequisites

Before using this library, ensure you have:

1. **Node.js** (v14 or higher)
2. **yt-dlp** installed on your system:
   - **Linux/macOS**: `brew install yt-dlp` or `pip install yt-dlp`
   - **Windows**: Download from [yt-dlp GitHub releases](https://github.com/yt-dlp/yt-dlp/releases)
3. **ffmpeg** (required for MP3 conversion):
   - **Linux/macOS**: `brew install ffmpeg` or `apt install ffmpeg`
   - **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)

## Installation

```bash
# Using npm
npm install yt-dlp-wrapper

# Using yarn
yarn add yt-dlp-wrapper

# Using pnpm
pnpm add yt-dlp-wrapper
```

## CLI Usage

The library includes a command-line interface for common operations:

### Download a video

```bash
# Basic download
npx yt-dlp-wrapper download https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Download with specific format
npx yt-dlp-wrapper download https://www.tiktok.com/@businessblurb/video/7479849082844892458 -f "best[height<=720]"

# Download to specific directory
npx yt-dlp-wrapper download https://youtu.be/dQw4w9WgXcQ --output-dir "./downloads"

# Download as MP3 audio only
npx yt-dlp-wrapper download https://youtu.be/dQw4w9WgXcQ --mp3
```

### Get video information

```bash
# Basic info
npx yt-dlp-wrapper info https://www.youtube.com/watch?v=dQw4w9WgXcQ

# With JSON output
npx yt-dlp-wrapper info https://www.tiktok.com/@businessblurb/video/7479849082844892458 --dump-json
```

### List available formats

```bash
npx yt-dlp-wrapper formats https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

### Help

```bash
# General help
npx yt-dlp-wrapper --help

# Command-specific help
npx yt-dlp-wrapper download --help
```

## API Usage

### Basic Usage

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

// Create a new instance with default options
const ytdlp = new YtDlp();

// Download a video
async function downloadVideo() {
  try {
    const filePath = await ytdlp.downloadVideo('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
    console.log(`Video downloaded to: ${filePath}`);
  } catch (error) {
    console.error('Download failed:', error);
  }
}

downloadVideo();
```

### Download with Options

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

const ytdlp = new YtDlp();

async function downloadWithOptions() {
  try {
    const filePath = await ytdlp.downloadVideo('https://www.tiktok.com/@businessblurb/video/7479849082844892458', {
      format: 'bestvideo[height<=720]+bestaudio/best[height<=720]',
      format: 'bestvideo[height<=720]+bestaudio/best[height<=720]',
      outputDir: './downloads',
      filename: 'tiktok-video.mp4',
      subtitles: true,
      audioOnly: false,
      // Add any other options as needed
    
    console.log(`Video downloaded to: ${filePath}`);
  } catch (error) {
    console.error('Download failed:', error);
  }
}

downloadWithOptions();
```

### Get Video Information

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

const ytdlp = new YtDlp();

async function getVideoInfo() {
  try {
    const info = await ytdlp.getVideoInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
    console.log('Video title:', info.title);
    console.log('Duration:', info.duration);
    console.log('Uploader:', info.uploader);
    // Access other properties as needed
  } catch (error) {
    console.error('Failed to get video info:', error);
  }
}

getVideoInfo();
```

### List Available Formats

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

const ytdlp = new YtDlp();

async function listFormats() {
  try {
    const formats = await ytdlp.listFormats('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
    
    // Display all formats
    formats.forEach(format => {
      console.log(`Format ID: ${format.formatId}`);
      console.log(`Resolution: ${format.resolution}`);
      console.log(`Extension: ${format.extension}`);
      console.log(`File size: ${format.filesize}`);
      console.log('---');
    });
  } catch (error) {
    console.error('Failed to list formats:', error);
  }
}

listFormats();
```

### Custom Configuration

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

// Create a new instance with custom options
const ytdlp = new YtDlp({
  executablePath: '/usr/local/bin/yt-dlp',  // Custom path to yt-dlp executable
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
  verbose: true,
  // Add other global options as needed
});

// Use as normal
ytdlp.downloadVideo('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
  .then(filePath => console.log(`Video downloaded to: ${filePath}`))
  .catch(error => console.error('Download failed:', error));
```

## MP3 Downloads

The library supports extracting audio from videos and converting to MP3 format. This functionality requires ffmpeg to be installed on your system.

### MP3 Downloads via CLI

```bash
# Basic MP3 download
npx yt-dlp-wrapper download https://www.youtube.com/watch?v=dQw4w9WgXcQ --mp3

# MP3 download with specific output directory
npx yt-dlp-wrapper download https://youtu.be/dQw4w9WgXcQ --mp3 --output-dir "./music"

# MP3 download with custom filename
npx yt-dlp-wrapper download https://youtu.be/dQw4w9WgXcQ --mp3 --filename "my-song.mp3"
```

### MP3 Downloads via API

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

const ytdlp = new YtDlp();

async function downloadAsMp3() {
  try {
    const filePath = await ytdlp.downloadVideo('https://www.youtube.com/watch?v=dQw4w9WgXcQ', {
      audioOnly: true,
      audioFormat: 'mp3',
      outputDir: './music',
      filename: 'audio-track.mp3'
    });
    
    console.log(`Audio downloaded to: ${filePath}`);
  } catch (error) {
    console.error('Audio download failed:', error);
  }
}

downloadAsMp3();
```

### Notes on MP3 Conversion

- MP3 conversion requires ffmpeg to be installed on your system
- If ffmpeg is not found, an error message will be shown
- The audio quality defaults to the best available
- Progress for both download and conversion will be displayed

## Advanced Examples

### Download Playlist

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

const ytdlp = new YtDlp();

async function downloadPlaylist() {
  try {
    const result = await ytdlp.downloadVideo('https://www.youtube.com/playlist?list=PLexamplelistID', {
      outputDir: './playlists',
      playlistItems: '1-5',  // Only download the first 5 videos
      limit: 5,
      format: 'best[height<=480]'  // Lower quality to save space
    });
    
    console.log(`Playlist downloaded to: ${result}`);
  } catch (error) {
    console.error('Playlist download failed:', error);
  }
}

downloadPlaylist();
```

### Progress Tracking

```typescript
import { YtDlp } from 'yt-dlp-wrapper';

const ytdlp = new YtDlp();

async function downloadWithProgress() {
  try {
    const filePath = await ytdlp.downloadVideo('https://www.youtube.com/watch?v=dQw4w9WgXcQ', {
      onProgress: (progress) => {
        console.log(`Download progress: ${progress.percent}%`);
        console.log(`Speed: ${progress.speed}`);
        console.log(`ETA: ${progress.eta}`);
      }
    });
    
    console.log(`Video downloaded to: ${filePath}`);
  } catch (error) {
    console.error('Download failed:', error);
  }
}

downloadWithProgress();
```

## Error Handling

The library provides detailed error information:

```typescript
import { YtDlp, YtDlpError } from 'yt-dlp-wrapper';

const ytdlp = new YtDlp();

async function handleErrors() {
  try {
    await ytdlp.downloadVideo('https://invalid-url.com/video');
  } catch (error) {
    if (error instanceof YtDlpError) {
      console.error(`YtDlp Error: ${error.message}`);
      console.error(`Error Code: ${error.code}`);
      console.error(`Command: ${error.command}`);
    } else {
      console.error('Unknown error:', error);
    }
  }
}

handleErrors();
```

## API Reference

### YtDlp Class

#### Constructor

```typescript
new YtDlp(options?: YtDlpOptions)
```

**YtDlpOptions:**

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| executablePath | string | Path to yt-dlp executable | 'yt-dlp' |
| userAgent | string | User agent to use for requests | Default browser UA |
| verbose | boolean | Enable verbose output | false |
| quiet | boolean | Suppress output | false |

#### Methods

**downloadVideo(url, options?)**  
Downloads a video from the given URL.

**getVideoInfo(url, options?)**  
Gets information about a video.

**listFormats(url, options?)**  
Lists available formats for a video.

**checkInstallation()**  
Verifies that yt-dlp is installed and working.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - The amazing tool this library wraps
- All the contributors to the open-source libraries used in this project