downlink/docs/setup.md

Setup Guide

Prerequisites

System Requirements

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

Installing Dependencies

macOS

# Install yt-dlp
brew install yt-dlp

# Install ffmpeg
brew install ffmpeg

Linux (Ubuntu/Debian)

# Install yt-dlp
pip3 install yt-dlp

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

Windows

# Install yt-dlp
pip install yt-dlp

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

Installation

1. Clone the repository

   git clone <repository-url>
   cd Downlink
   

2. Install npm dependencies

   npm install
   

3. Verify yt-dlp installation

   yt-dlp --version
   

4. Verify ffmpeg installation

   ffmpeg -version
   

Running the Application

Development Mode

npm run dev

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

Production Build

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

# 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
• Read Transcoding Documentation
• Check Agent Instructions for contributing guidelines