# 🎬 Media Vault - Setup & Installation Guide

## Quick Start (5 minutes)

### 1️⃣ Install Dependencies

**Windows:**
```bash
npm install
pip install yt-dlp
```

**macOS/Linux:**
```bash
npm install
pip3 install yt-dlp
```

### 2️⃣ Start the Server

```bash
npm start
```

You should see:
```
============================================================
🎬 MEDIA VAULT - Download Server Started
============================================================

🌐 Server: http://localhost:3000
📁 Downloads: /path/to/your/downloads

✓ Ready to download from Facebook, Twitter, Instagram, TikTok, YouTube, etc.
============================================================
```

### 3️⃣ Open in Browser

Open **http://localhost:3000** in your browser and start downloading!

---

## 📋 System Requirements

### Required
- **Node.js** 16+ ([download](https://nodejs.org/))
- **Python** 3.8+ (for yt-dlp)
- **npm** (comes with Node.js)

### Optional but Recommended
- **FFmpeg** (for audio/video processing)
  - Windows: `choco install ffmpeg` or download from [ffmpeg.org](https://ffmpeg.org/download.html)
  - macOS: `brew install ffmpeg`
  - Linux: `sudo apt install ffmpeg`

---

## 🔧 Installation Steps (Detailed)

### Step 1: Check Prerequisites

**Check Node.js:**
```bash
node --version
npm --version
```

Should output something like:
```
v18.12.0
9.2.0
```

**Check Python:**
```bash
python --version
# or
python3 --version
```

Should output `Python 3.8+`

### Step 2: Create Project Folder

```bash
mkdir media-vault
cd media-vault
```

### Step 3: Copy Files

Copy these files into the `media-vault` folder:
- `package.json`
- `server.js`
- `social-media-downloader.html`

Your folder structure should look like:
```
media-vault/
├── package.json
├── server.js
├── social-media-downloader.html
└── downloads/  (created automatically)
```

### Step 4: Install Node Dependencies

```bash
npm install
```

This installs:
- `express` - Web server framework
- `cors` - Cross-origin requests support

### Step 5: Install yt-dlp

**Windows:**
```bash
pip install yt-dlp --upgrade
```

**macOS/Linux:**
```bash
pip3 install yt-dlp --upgrade
```

**Verify installation:**
```bash
yt-dlp --version
```

### Step 6: (Optional) Install FFmpeg

**Windows (with Chocolatey):**
```bash
choco install ffmpeg
```

**Windows (Manual):**
1. Download from [ffmpeg.org](https://ffmpeg.org/download.html)
2. Extract to a folder
3. Add to system PATH

**macOS:**
```bash
brew install ffmpeg
```

**Linux (Ubuntu/Debian):**
```bash
sudo apt update
sudo apt install ffmpeg
```

---

## 🚀 Running the Server

### Development Mode (with auto-reload)
Requires Node 18+:
```bash
npm run dev
```

### Production Mode
```bash
npm start
```

### Running in Background

**Windows (PowerShell):**
```bash
Start-Process powershell -ArgumentList "npm start"
```

**macOS/Linux:**
```bash
nohup npm start > server.log 2>&1 &
```

Or use `screen`:
```bash
screen -S media-vault npm start
# Press Ctrl+A then D to detach
# screen -r media-vault  (to reattach)
```

---

## 🌐 Access the App

Once the server is running:

- **Local:** http://localhost:3000
- **Mobile (same network):** http://your-ip:3000
  - Find your IP: `ipconfig getifaddr en0` (macOS) or `ipconfig` (Windows)

---

## 📁 Downloaded Files

Files are saved to: `downloads/` folder in your project directory

Structure:
```
downloads/
├── facebook/
│   ├── video-name.mp4
│   └── reel-name.mp4
├── instagram/
├── tiktok/
├── twitter/
├── youtube/
├── other/
└── (any custom paths you specify)
```

---

## 🔍 API Reference

### Download Media
**POST** `/api/download`

**Request:**
```json
{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "platform": "youtube",
  "savePath": "/custom/path"  // optional
}
```

**Response (Success):**
```json
{
  "success": true,
  "filePath": "/path/to/downloads/video-title.mp4",
  "fileName": "video-title.mp4",
  "downloadDir": "/path/to/downloads",
  "filesDownloaded": ["video-title.mp4"],
  "message": "Successfully downloaded 1 file(s)"
}
```

**Response (Error):**
```json
{
  "success": false,
  "error": "yt-dlp is not installed. Run: pip install yt-dlp"
}
```

### List Files
**GET** `/api/files?platform=facebook`

Returns list of downloaded files for a platform.

### Download File
**GET** `/api/download-file?filepath=/path/to/file`

Downloads a previously downloaded file.

### System Info
**GET** `/api/system-info`

Returns:
```json
{
  "platform": "darwin",
  "nodeVersion": "v18.12.0",
  "downloadDir": "/path/to/downloads",
  "ytdlpVersion": "2024.01.15",
  "availableMemory": "8192 MB"
}
```

### Health Check
**GET** `/api/health`

Quick check if server is running.

---

## ⚙️ Configuration

### Change Port

Edit `server.js` and change:
```javascript
const PORT = process.env.PORT || 3000;
```

Or set environment variable:

**Windows (PowerShell):**
```bash
$env:PORT=8080
npm start
```

**macOS/Linux:**
```bash
PORT=8080 npm start
```

### Change Download Directory

Edit `server.js`:
```javascript
const DOWNLOAD_DIR = path.join(process.cwd(), 'downloads');
```

Or use custom path via API.

---

## 🐛 Troubleshooting

### "yt-dlp is not installed"

**Solution:**
```bash
pip install yt-dlp --upgrade
# or
pip3 install yt-dlp --upgrade
```

Verify:
```bash
yt-dlp --version
```

### "Cannot find module 'express'"

**Solution:**
```bash
npm install
```

### "EADDRINUSE: address already in use :::3000"

Port 3000 is already in use. Either:

1. Kill the process:
```bash
lsof -ti:3000 | xargs kill -9  # macOS/Linux
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process  # Windows
```

2. Use a different port:
```bash
PORT=3001 npm start
```

### Download starts but doesn't complete

1. **Increase timeout:** Edit `server.js`:
```javascript
timeout: 1200000  // 20 minutes
```

2. **Lower quality:** The app defaults to "best". For slower connections:
```javascript
const command = `yt-dlp -f "worst" ...`;
```

### Videos are geo-blocked or private

yt-dlp may need cookies or authentication for:
- Private videos
- Age-restricted content
- Region-locked content

Some platforms require login. Check [yt-dlp documentation](https://github.com/yt-dlp/yt-dlp).

### File path issues (Windows)

Use forward slashes or escaped backslashes:
```
✓ Correct:   C:/Users/Downloads
✓ Correct:   C:\\Users\\Downloads
✗ Wrong:     C:\Users\Downloads
```

---

## 🔒 Security Notes

⚠️ **Important for production:**

1. **Don't expose to the internet without authentication** (unless behind a reverse proxy)
2. **Validate file paths** to prevent directory traversal attacks
3. **Rate limit requests** in production
4. **Use HTTPS** when possible
5. **Sanitize user input** (already done in the code)

To add authentication, install `express-basic-auth`:
```bash
npm install express-basic-auth
```

Then add:
```javascript
const basicAuth = require('express-basic-auth');
app.use(basicAuth({
    users: { 'admin': 'password' },
    challenge: true
}));
```

---

## 📊 Performance Tips

1. **Use FFmpeg** for better audio/video processing
2. **SSD recommended** for faster downloads
3. **Avoid large files** on slow connections
4. **Monitor disk space** - downloads can be large
5. **Run on decent hardware** for smooth operation

---

## 🎯 Supported Platforms

✅ YouTube & YouTube Music  
✅ Facebook & Facebook Watch  
✅ Instagram (Posts, Reels, Stories)  
✅ TikTok  
✅ Twitter/X  
✅ Twitch  
✅ Reddit  
✅ Snapchat  
✅ Pinterest  
✅ Vimeo  
✅ Dailymotion  
✅ And 1000+ more...

yt-dlp supports almost any platform. Check [supported sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md).

---

## 📚 Useful Resources

- **yt-dlp GitHub:** https://github.com/yt-dlp/yt-dlp
- **Express Documentation:** https://expressjs.com/
- **Node.js Guide:** https://nodejs.org/en/docs/
- **FFmpeg Guide:** https://ffmpeg.org/documentation.html

---

## 💡 Advanced Usage

### Command Line Download (without UI)

```bash
yt-dlp "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -o "downloads/%(title)s.%(ext)s"
```

### Custom yt-dlp Options

Edit `server.js` and modify the command:

```javascript
// For audio only (MP3):
const command = `yt-dlp -f "bestaudio" -x --audio-format mp3 -o "${outputPath}" "${cleanUrl}"`;

// For video only (no audio):
const command = `yt-dlp -f "bestvideo" -o "${outputPath}" "${cleanUrl}"`;

// Specific resolution:
const command = `yt-dlp -f "best[height<=720]" -o "${outputPath}" "${cleanUrl}"`;
```

---

## 🤝 Support

If you encounter issues:

1. Check this guide first
2. Check [yt-dlp docs](https://github.com/yt-dlp/yt-dlp)
3. Check Node.js error messages
4. Verify all dependencies are installed correctly

---

**Enjoy downloading! 🎉**