downlink/docs/configuration.md

Configuration Guide

Environment Variables

Downlink uses environment variables for configuration. Create a .env.local file in the project root (this file is gitignored and won't be committed).

Required Configuration

YT_DLP_PATH

Required if yt-dlp is not in your system PATH

Full path to the yt-dlp executable.

YT_DLP_PATH=/Users/jeff/Desktop/yt-dlp_macos

When to set this:

• yt-dlp is not installed via package manager (brew, pip, etc.)
• yt-dlp is in a custom location
• You're using a standalone yt-dlp binary

How to find your yt-dlp path:

# If installed via brew
which yt-dlp
# Output: /opt/homebrew/bin/yt-dlp

# If installed via pip
which yt-dlp
# Output: /usr/local/bin/yt-dlp

# If using standalone binary
# Use the full path to the binary file

Optional Configuration

FFMPEG_PATH

Optional - For custom ffmpeg location

Full path to the ffmpeg executable. Passed to yt-dlp via --ffmpeg-location flag. Only needed if ffmpeg is not in your system PATH.

FFMPEG_PATH=/usr/local/bin/ffmpeg

When to set this:

• ffmpeg is not installed via package manager
• ffmpeg is in a custom location (e.g., Docker, Coolify deployments)
• You're using a standalone ffmpeg binary

Configuration Examples

Example 1: yt-dlp in Custom Location

# .env.local
YT_DLP_PATH=/Users/jeff/Desktop/yt-dlp_macos

Example 2: yt-dlp Installed via Homebrew

# .env.local
# Can be left empty if yt-dlp is in PATH
# Or explicitly set:
YT_DLP_PATH=/opt/homebrew/bin/yt-dlp

Example 3: yt-dlp Installed via pip

# .env.local
YT_DLP_PATH=/usr/local/bin/yt-dlp

Environment File Setup

1. Copy the example file:

   cp .env.example .env.local
   

2. Edit .env.local with your configuration:

   YT_DLP_PATH=/path/to/your/yt-dlp
   

3. Restart the development server:

   npm run dev
   

Troubleshooting

yt-dlp not found error

If you see yt-dlp: command not found:

1. Check if yt-dlp exists:

   which yt-dlp
   

2. If it returns nothing, set YT_DLP_PATH:

   # Find where yt-dlp is located
   find /usr -name yt-dlp 2>/dev/null
   find ~ -name yt-dlp 2>/dev/null
   
   # Or if you downloaded it manually, use that path
   

3. Add to .env.local:

   YT_DLP_PATH=/full/path/to/yt-dlp
   

4. Verify the path is correct:

   ls -la "$YT_DLP_PATH"
   # Should show the yt-dlp executable
   

Path with spaces

If your path contains spaces, use quotes in the environment variable:

YT_DLP_PATH="/Users/jeff/My Apps/yt-dlp_macos"

Executable permissions

Ensure yt-dlp has execute permissions:

chmod +x /path/to/yt-dlp

Production Configuration

For production deployments:

1. Set environment variables in your hosting platform (Vercel, Railway, etc.)
2. Ensure yt-dlp is installed on the server
3. Set YT_DLP_PATH if yt-dlp is not in the default PATH

Vercel Example

# In Vercel dashboard → Settings → Environment Variables
YT_DLP_PATH=/usr/local/bin/yt-dlp

Docker Example

# In Dockerfile
ENV YT_DLP_PATH=/usr/local/bin/yt-dlp

Next.js Environment Variables

Next.js automatically loads .env.local files. Variables prefixed with NEXT_PUBLIC_ are exposed to the browser, but YT_DLP_PATH should remain server-side only (no prefix).

Security Notes

• Never commit .env.local to version control (already in .gitignore)
• Keep yt-dlp paths secure
• Use absolute paths for reliability
• Test configuration after changes