cal/claude-home
1
0
Fork 0
Code Issues 6 Pull Requests 4 Actions Packages Projects Releases Wiki Activity
ad6adf7a4c
claude-home/media-tools/troubleshooting.md
Cal Corum 4b7eca8a46
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 3s
Details
docs: add YAML frontmatter to all 151 markdown files 
Adds title, description, type, domain, and tags frontmatter to every
doc for improved KB semantic search. The description field is prepended
to every search chunk, and domain/type/tags enable filtered queries.

Type values: context, guide, runbook, reference, troubleshooting
Domain values match directory structure (networking, docker, etc.)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-12 09:00:44 -05:00

4.1 KiB
Raw Blame History

title description type domain tags
Media Tools Troubleshooting Solutions for Playwright browser automation failures, yt-dlp download errors, scraping issues, and resume/state file problems in media download tools. troubleshooting media-tools
yt-dlp
playwright
scraping
debugging
video-download

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.