agentleFS
abduznikabduznik/abduznik-skills/skills/yt-dlp-anti-bot/SKILL.md

yt-dlp-anti-bot

Skill2 starsChanged 2 months agoMITView on GitHub

When yt-dlp hits 403s, harden with impersonation + backoff.

  • Installs packages

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep per-track metadata (-metadata artist/album/track) and file naming identical to the service's output (NN - Title.mp3) so gap-fills …

    line 58

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

yt-dlp Anti-Bot Hardening (YouTube 403s)

YouTube intermittently rejects yt-dlp requests with HTTP Error 403: Forbidden. Pattern to recognize: failures hit DIFFERENT tracks each run, in bursts — that's IP throttling / bot detection, NOT a per-video block. A job can report "done" while silently skipping failed tracks (see below).

The fix stack

  1. Upgrade yt-dlp + install curl_cffi PINNED <0.16:
    pip install -U yt-dlp "curl_cffi<0.16"
    yt-dlp 2026.07+ rejects curl_cffi 0.16.x ("Only curl_cffi versions 0.5.10 and 0.10.x through 0.15.x are supported"). When curl_cffi is the wrong version, ALL impersonate targets show (unavailable) in yt-dlp --list-impersonate-targets even though import curl_cffi works fine.
  2. Pin in requirements.txt too — curl_cffi<0.16. An unpinned entry silently reinstalls the broken latest version on every container restart (services whose entrypoint runs pip install -r requirements.txt).
  3. Python API: pass the ImpersonateTarget OBJECT, not a string:
    from yt_dlp.networking.impersonate import ImpersonateTarget
    ydl_opts = {'impersonate': ImpersonateTarget.from_str('chrome')}
    A raw string {'impersonate': 'chrome'} raises AssertionError: '' — an EMPTY message, so the job fails at info-fetch with a blank error. The CLI converts strings for you; the YoutubeDL() API does not.
  4. Stale process trap: upgrading/downgrading curl_cffi while a service runs does NOT fix the running worker — it imported yt-dlp before the change. CLI tests pass but the service still errors. Always restart the container after version changes.

Verifying the fix

# targets usable?
yt-dlp --list-impersonate-targets
# single-track test — real googlevideo URL = fingerprint works
yt-dlp --impersonate chrome -f bestaudio --get-url "<url>"

Residual throttling → rotate + backoff

Some tracks still 403 even with impersonation. Gap-fill strategy (download ONLY missing tracks, don't re-run whole playlists):

  • Rotate impersonation targets per attempt: chrome, chrome-136, chrome-133, safari-18.0, safari-17.2
  • Rotate player clients: android,web, web, tv,web, android_vr,web
  • Exponential backoff: 'retry_sleep_functions': {'http': lambda n: 25 * (2 ** min(n, 4))}
  • 60-90s sleeps between attempts; up to 8-12 attempts per track
  • Keep per-track metadata (-metadata artist/album/track) and file naming identical to the service's output (NN - Title.mp3) so gap-fills blend in

Pitfalls

  • "Job done" ≠ all tracks downloaded: services report Complete! N tracks processed when the LOOP finishes, not when all succeeded. Always verify disk file count against playlist track count.
  • docker exec -d swallows output redirects: docker exec -d <c> python3 x.py > /tmp/x.log writes the log on the HOST (often 0 bytes). Use docker exec -d <c> sh -c "python3 -u x.py > /tmp/x.log 2>&1" — and python3 -u for unbuffered output.
  • Block-buffered stdout: service app stdout to docker logs lags; use jobs.json / event stores as source of truth for job state.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.