claude-home/media-tools/troubleshooting.md

Media Tools Troubleshooting

Common Issues

Playwright Issues

"playwright not installed" Error

ERROR: playwright not installed. Run: pip install playwright && playwright install chromium

Solution:

pip install playwright
playwright install chromium

Browser Launch Fails

Error: Executable doesn't exist at /home/user/.cache/ms-playwright/chromium-xxx/chrome-linux/chrome

Solution:

playwright install chromium

Timeout Errors

TimeoutError: Timeout 30000ms exceeded

Causes:

• Slow network connection
• Site is blocking automated access
• Page structure has changed

Solutions:

1. Increase timeout in script
2. Try without --headless flag
3. Check if site is up manually

---

yt-dlp Issues

"yt-dlp not found" Error

yt-dlp not found. Install with: pip install yt-dlp

Solution:

pip install yt-dlp

Download Fails for Specific Host

ERROR: Unsupported URL: https://somehost.com/...

Solution:

# Update yt-dlp to latest version
pip install -U yt-dlp

If still failing, the host may be unsupported. Check yt-dlp supported sites.

Slow Downloads

Causes:

• Video host throttling
• Network issues

Solutions:

• Downloads are typically limited by the source server
• Try at different times of day

---

Scraping Issues

No Episodes Found

No episodes found!

Causes:

• Site structure has changed
• Page requires authentication
• Cloudflare protection triggered

Solutions:

1. Run without --headless to see what's happening
2. Check if the URL is correct and accessible manually
3. Site may have updated their HTML structure - check selectors in script

Video URL Not Found

No video URL found for episode X

Causes:

• Video is on an unsupported host
• Page uses non-standard embedding method
• Anti-bot protection on video player

Solutions:

1. Run with --verbose to see what URLs are being tried
2. Open episode manually and check Network tab for video requests
3. May need to add new iframe selectors for the specific host

403 Forbidden on Site

Cause: Site is blocking automated requests

Solutions:

1. Ensure you're NOT using --headless
2. Increase random delays
3. Clear browser cache/cookies (restart script)
4. Try from a different IP

---

Resume Issues

Resume Not Working

# Should skip downloaded episodes but re-downloads them

Check:

1. Ensure download_state.json exists in output directory
2. Verify the --resume flag is being used
3. Check that episode numbers match between runs

Corrupt State File

JSONDecodeError: ...

Solution:

# Delete the state file to start fresh
rm /path/to/season/download_state.json

---

Debug Mode

Run with verbose output:

python pokeflix_scraper.py --url "..." --output ~/Pokemon/ --verbose

Run dry-run to test URL extraction:

python pokeflix_scraper.py --url "..." --dry-run --verbose

Watch the browser (non-headless):

python pokeflix_scraper.py --url "..." --output ~/Pokemon/
# (headless is off by default)

---

Manual Workarounds

If Automated Extraction Fails

1. Browser DevTools method:

   • Open episode in browser
   • F12 → Network tab → filter "m3u8" or "mp4"
   • Play video, copy the stream URL
   • Download manually: yt-dlp "URL"

2. Check iframe manually:

   • Right-click video player → Inspect
   • Find <iframe> element
   • Copy src attribute
   • Use that URL with yt-dlp

Known Video Hosts

These hosts are typically supported by yt-dlp:

• Streamtape
• Vidoza
• Mp4upload
• Doodstream
• Filemoon
• Voe.sx

If the video is on an unsupported host, check if there's an alternative server/quality option on the episode page.