videotomp3transcriptor/docs/YOUTUBE_COOKIES.md

YouTube Cookies Setup Guide

Why Do I Need Cookies?

YouTube has anti-bot protections that may block yt-dlp requests. Using cookies from your browser allows yt-dlp to authenticate as if you're logged in, bypassing these restrictions.

Quick Start

Option 1: Automatic Extraction (Recommended)

Run the helper script:

bash scripts/extract-cookies.sh

Follow the prompts to extract cookies from Chrome or Firefox.

Option 2: Using yt-dlp Directly

# For Chrome/Chromium
yt-dlp --cookies-from-browser chrome --cookies youtube-cookies.txt 'https://www.youtube.com'

# For Firefox
yt-dlp --cookies-from-browser firefox --cookies youtube-cookies.txt 'https://www.youtube.com'

# For Edge
yt-dlp --cookies-from-browser edge --cookies youtube-cookies.txt 'https://www.youtube.com'

Option 3: Browser Extension

1. Install a cookies export extension:

   • Chrome/Edge: Get cookies.txt LOCALLY
   • Firefox: cookies.txt

2. Go to youtube.com and log in

3. Click the extension icon and export cookies

4. Save the file as youtube-cookies.txt in your project directory

Configuration

After extracting cookies, update your .env file:

YOUTUBE_COOKIES_PATH=/home/debian/videotomp3transcriptor/youtube-cookies.txt

Or use a relative path:

YOUTUBE_COOKIES_PATH=./youtube-cookies.txt

Verifying It Works

Test with a video:

curl -X POST http://localhost:3001/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

If it works without cookies errors, you're good to go!

Security Notes

⚠️ IMPORTANT:

1. Never commit cookies to git: The .gitignore file should already exclude youtube-cookies.txt
2. Keep cookies secure: They provide access to your YouTube account
3. Cookies expire: You may need to re-export them periodically (typically every few weeks/months)
4. Don't share cookies: Treat them like passwords

Troubleshooting

"Sign in to confirm you're not a bot"

This usually means:

• Cookies are not being used
• Cookies have expired
• Cookies file path is incorrect

Solutions:

1. Check the path in .env is correct and absolute
2. Re-export fresh cookies
3. Verify the cookies file exists: ls -la youtube-cookies.txt
4. Check logs: pm2 logs toMP3-api

"HTTP Error 403: Forbidden"

YouTube is blocking your IP or the video is region-restricted.

Solutions:

1. Try with fresh cookies
2. Use a VPN if region-restricted
3. Wait a bit if rate-limited

Cookies Not Working

1. Make sure you're logged into YouTube in the browser before extracting
2. Try extracting from a different browser
3. Verify the cookies file format (should be Netscape format)
4. Check file permissions: chmod 600 youtube-cookies.txt

Cookie File Format

The cookies file should be in Netscape format and look like this:

# Netscape HTTP Cookie File
.youtube.com	TRUE	/	TRUE	1234567890	CONSENT	YES+
.youtube.com	TRUE	/	FALSE	1234567890	VISITOR_INFO1_LIVE	xxxxx

Without Cookies

The API will still work for many videos without cookies, but you may encounter:

• "Sign in to confirm you're not a bot" errors
• Rate limiting
• Blocked downloads for certain videos

For best results, always use cookies!

Additional Resources

• yt-dlp Cookie Documentation
• Browser Cookie Extraction