# Setup Guide

## Prerequisites

### System Requirements
- Node.js 18+ and npm
- Python 3.6+ (for yt-dlp)
- ffmpeg (for audio conversion)

### Installing Dependencies

#### macOS
```bash
# Install yt-dlp
brew install yt-dlp

# Install ffmpeg
brew install ffmpeg
```

#### Linux (Ubuntu/Debian)
```bash
# Install yt-dlp
pip3 install yt-dlp

# Install ffmpeg
sudo apt-get update
sudo apt-get install ffmpeg
```

#### Windows
```bash
# Install yt-dlp
pip install yt-dlp

# Install ffmpeg
# Download from https://ffmpeg.org/download.html
# Add to PATH
```

## Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd Downlink
   ```

2. **Install npm dependencies**
   ```bash
   npm install
   ```

3. **Verify yt-dlp installation**
   ```bash
   yt-dlp --version
   ```

4. **Verify ffmpeg installation**
   ```bash
   ffmpeg -version
   ```

## Running the Application

### Development Mode
```bash
npm run dev
```

The application will be available at `http://localhost:3000`

### Production Build
```bash
npm run build
npm start
```

## Directory Structure

```
Downlink/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   │   ├── download/      # Download endpoint
│   │   └── info/          # Video info endpoint
│   ├── page.tsx           # Main page
│   └── layout.tsx         # Root layout
├── components/            # React components
│   └── ui/                # shadcn/ui components
├── lib/                   # Utility functions
│   ├── types.ts           # TypeScript types
│   └── youtube.ts         # YouTube download logic
├── docs/                  # Documentation
├── downloads/             # Temporary download storage (gitignored)
└── public/
    └── downloads/        # Served download files (gitignored)
```

## Environment Variables

Create a `.env.local` file in the project root (copy from `.env.example`):

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

# Optional: FFmpeg path (if not in PATH)
# FFMPEG_PATH=/path/to/ffmpeg
```

### Available Variables

- **`YT_DLP_PATH`** (optional): Full path to yt-dlp executable if not in PATH
  - Example: `YT_DLP_PATH=/Users/jeff/Desktop/yt-dlp_macos`
  - Example: `YT_DLP_PATH=/opt/homebrew/bin/yt-dlp`
  - If not set, the system will look for `yt-dlp` in PATH

- **`FFMPEG_PATH`** (optional): Full path to ffmpeg executable if not in PATH
  - Currently not used but reserved for future use

### Future Environment Variables
- `MAX_FILE_SIZE`: Maximum file size limit
- `CLEANUP_INTERVAL`: File cleanup interval
- `ALLOWED_DOMAINS`: Allowed video domains

## Troubleshooting

### yt-dlp not found
- Ensure yt-dlp is installed and in your PATH
- Try: `which yt-dlp` to verify installation
- Reinstall if needed: `pip3 install --upgrade yt-dlp`

### ffmpeg not found
- Ensure ffmpeg is installed and in your PATH
- Try: `which ffmpeg` to verify installation
- Audio conversion (MP3, WAV) will fail without ffmpeg

### Download fails
- Check YouTube URL format
- Verify internet connection
- Check server logs for detailed error messages
- Ensure sufficient disk space in downloads directory

### Port already in use
- Change port: `npm run dev -- -p 3001`
- Or kill process using port 3000

## Next Steps

- Read [YouTube Downloader Documentation](./youtube-downloader.md)
- Read [Transcoding Documentation](./transcoding.md)
- Check [Agent Instructions](./AGENTS.md) for contributing guidelines