# YouTube Downloader Feature

## Overview
The YouTube Downloader feature allows users to download YouTube videos and audio files in various formats. Users can paste a YouTube URL, select their preferred format (video or audio), and download the transcoded file.

## Usage

### User Flow
1. User pastes a YouTube URL into the input field
2. User clicks "Get Info" to fetch video metadata (title, thumbnail, duration)
3. User selects format type (Video or Audio)
4. User selects specific format (MP4, WebM, MKV, AVI for video; MP3, WAV, M4A, Opus for audio)
5. User clicks "Download" to start the download process
6. Once complete, user receives a download link

### API Endpoints

#### GET Video Information
**Endpoint**: `POST /api/info`

**Request Body**:
```json
{
  "url": "https://www.youtube.com/watch?v=..."
}
```

**Response**:
```json
{
  "success": true,
  "videoInfo": {
    "title": "Video Title",
    "duration": 120,
    "thumbnail": "https://...",
    "formats": [...]
  }
}
```

#### Download Video/Audio
**Endpoint**: `POST /api/download`

**Request Body**:
```json
{
  "url": "https://www.youtube.com/watch?v=...",
  "format": "mp4",
  "formatType": "video"
}
```

**Response**:
```json
{
  "success": true,
  "downloadUrl": "/downloads/1234567890-abc123.mp4",
  "filename": "Video Title.mp4",
  "videoInfo": {...}
}
```

## Technical Details

### Dependencies
- **yt-dlp**: Python-based YouTube downloader (must be installed system-wide)
- **ffmpeg**: Required for audio format conversion (MP3, WAV)

### Implementation

#### Server-Side Processing
- Downloads are processed server-side using `yt-dlp`
- Files are temporarily stored in `/downloads` directory
- Completed files are moved to `/public/downloads` for serving
- Files are named with timestamp and random ID to avoid conflicts

#### Format Handling
- **Video formats**: MP4, WebM, MKV, AVI
- **Audio formats**: MP3, WAV, M4A, Opus
- MP3 and WAV require audio extraction and conversion via yt-dlp
- Other formats use direct format selection from available streams

#### File Storage
- Temporary storage: `downloads/` (excluded from git)
- Public storage: `public/downloads/` (served statically)
- Files are not automatically cleaned up (consider adding cleanup job)

### Code Structure
- **Types**: `lib/types.ts` - Centralized type definitions
- **YouTube Logic**: `lib/youtube.ts` - Core download and info functions
- **API Routes**: 
  - `app/api/info/route.ts` - Video information endpoint
  - `app/api/download/route.ts` - Download endpoint
- **UI**: `app/page.tsx` - Main user interface

## Configuration

### Environment Variables

Create a `.env.local` file in the project root:

```bash
# Required if yt-dlp is not in PATH
YT_DLP_PATH=/path/to/yt-dlp
```

- **`YT_DLP_PATH`**: Full path to yt-dlp executable if not in system PATH
  - Required if yt-dlp is not installed via package manager
  - Example: `YT_DLP_PATH=/Users/jeff/Desktop/yt-dlp_macos`

Future environment variables:
- `MAX_FILE_SIZE`: Maximum file size limit
- `CLEANUP_INTERVAL`: How often to clean up old files
- `ALLOWED_DOMAINS`: Restrict to specific video platforms

### System Requirements
- Python 3.6+ (for yt-dlp)
- yt-dlp installed: `pip install yt-dlp` or `brew install yt-dlp`
- ffmpeg installed: `brew install ffmpeg` (for audio conversion)

## Examples

### Download MP4 Video
```typescript
const response = await fetch('/api/download', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    format: 'mp4',
    formatType: 'video'
  })
});
```

### Download MP3 Audio
```typescript
const response = await fetch('/api/download', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    format: 'mp3',
    formatType: 'audio'
  })
});
```

## Limitations
- Requires yt-dlp and ffmpeg to be installed on the server
- No automatic file cleanup (files accumulate in public/downloads)
- No file size limits or rate limiting
- No user authentication or download history

## Future Improvements
- Add file cleanup job for old downloads
- Add download progress tracking
- Add download history for users
- Add file size limits and validation
- Add support for playlists
- Add video quality selection (720p, 1080p, etc.)