162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
# 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.)
|