downlink/docs/youtube-downloader.md

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:

{
  "url": "https://www.youtube.com/watch?v=..."
}

Response:

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

Download Video/Audio

Endpoint: POST /api/download

Request Body:

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

Response:

{
  "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:

# 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

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

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.)