avd — agent-video-downloader

yt-dlp for cloud AI agents. One command downloads videos from TikTok, Instagram, Douyin, Rednote (Xiaohongshu), Reddit, X.com — no browser, no cookies, no login. Built for Claude / Cursor / Cline / GLM / GPT agents that need video bytes in task workflows.

---

Quickstart — one command for AI agents

pip install agent-video-downloader
avd agent-setup
avd download 'https://www.tiktok.com/@scout2015/video/6718335390845095173'

avd agent-setup auto-installs ffmpeg, all Python deps, and the XHS-Downloader repo (for Rednote). It's idempotent — safe to re-run anytime.

For the full agent usage guide:

avd agent-instructions

---

Why

yt-dlp is broken from datacenter IPs for TikTok, Twitter, Reddit, Instagram, Douyin. Cloud CLI agents (Claude Code, GLM CLI, Cursor, Cline) that need to download videos for tasks (transcription, OCR, content analysis, archival) have no reliable path. avd fixes that with direct-API fallback chains that work from cloud IPs without login.

All six platforms download real video bytes (verified live 2026-10-03 from a Hong Kong datacenter IP):

Platform	Method	Sample download
TikTok	TikWM mirror API	2.0 MB / 10.5 s
Twitter/X	api.fxtwitter.com → video.twimg.com	156 MB / 74.8 s 4K
Reddit	rapidsave.com + v.redd.it CMAF + ffmpeg mux	6.1 MB / 16.1 s
Instagram	yt-dlp + facebookexternalhit/1.1 UA	8.4 MB / 77.3 s
Douyin	api.douyin.wtf public demo (zero-config)	3.6 MB / 27.6 s
Rednote (XHS)	XHS-Downloader (curl_cffi chrome146)	8.4 MB / 720p

---

Commands

Command	Purpose
avd agent-setup	One-command bootstrap — installs ffmpeg, deps, XHS-Downloader
avd agent-instructions	Print step-by-step usage guide for AI agents
avd download <url>	Download one URL
avd batch <file>	Batch download (one URL per line, # comments OK)
avd verify <path>	Verify a downloaded file's integrity
avd test --smoke	End-to-end self-test on one URL per platform
avd jobs	List recent jobs
avd dlq	List dead-letter queue entries
avd replay <dlq_id>	Replay a failed job
avd mcp	Start MCP server (stdio JSON-RPC 2.0)
avd supported	Show supported platforms
avd agents	Show agent versions

---

Install

From PyPI (recommended)

pip install agent-video-downloader
avd agent-setup

From source (development)

git clone https://github.com/hamza140202/agent-video-downloader
cd agent-video-downloader
pip install -e .[dev]
avd agent-setup

System requirements

• Python 3.10+ (tested on 3.10, 3.11, 3.12, 3.13)
• ffmpeg / ffprobe (auto-installed by avd agent-setup on Debian/Ubuntu; manual on other systems)
• git (for cloning XHS-Downloader on first Rednote download)

---

Configuration (env vars)

Var	Default	Description
AVD_DOWNLOAD_DIR	./download	Default download destination
AVD_LOG_LEVEL	INFO	DEBUG/INFO/WARNING/ERROR
AVD_REDDIT_CLIENT_ID	—	Reddit OAuth (only needed if rapidsave.com fails)
AVD_REDDIT_CLIENT_SECRET	—	same
AVD_REDDIT_USERNAME	—	throwaway Reddit username
AVD_REDDIT_PASSWORD	—	throwaway Reddit password
AVD_DOUYIN_DTK_URL	—	self-hosted Evil0ctal DTK (optional — defaults to public demo)
AVD_XHS_DOWNLOADER_PATH	~/XHS-Downloader	override XHS-Downloader clone path
AVD_PROXY	—	SOCKS5/HTTP proxy URL for all requests

---

Architecture (4 plain-Python agents, no LLM in runtime loop)

URL → Orchestrator → [TikTok|Twitter|Reddit|Instagram|Rednote|Douyin] extractors (fallback chain)
                     → Verifier (6-layer: size, magic bytes, ffprobe, duration, streams, moov)
                     → Truth Agent (cross-check vs source platform: oEmbed / syndication / RSS / OG)
                     → verified MP4 + manifest

• Orchestrator — owns the extractor registry, drives the fallback chain, persists job state to SQLite
• Verifier — 6-layer integrity check (size + magic bytes + ffprobe + duration + streams + moov atom)
• Truth Agent — cross-references downloaded metadata against source platform
• Tester — runs end-to-end on tests/sample_urls.json

Per-platform fallback chains (slot-based state machine, ytagent doctrine):

• TikTok: TikWM → embed/v2 → tiklydown → oEmbed
• Twitter/X: fxtwitter → syndication → unrollnow → vxtwitter
• Reddit: rapidsave.com/info + v.redd.it CMAF direct + ffmpeg mux → rapidsave server-side mux → yt-dlp+OAuth → RSS image
• Instagram: yt-dlp+facebookexternalhit UA → embed/captioned+fb-UA → embed+android-UA → embed+ios-UA → ddinstagram mirror
• Douyin: api.douyin.wtf demo → self-hosted DTK sidecar → yt-dlp
• Rednote: XHS-Downloader (curl_cffi) → curl_cffi direct → yt-dlp

Full design: docs/architecture.md · Full research: docs/research-report.md

---

Documentation

• CLAUDE.md — project memory (read first if modifying)
• AGENTS.md — agent contracts + perfection prompting rules
• TECHSTACK.md — every dependency, every version, why
• PHASES.md — development phases with exit criteria
• PLAN.md — concrete execution plan with task IDs
• SKILLS.md — per-agent skill spec sheets
• docs/research-report.md — live-verified endpoint research per platform
• docs/architecture.md — system design with ASCII diagram
• docs/endpoint-matrix.md — living endpoint table

---

License

MIT. See LICENSE.

Repo

• Primary: https://github.com/hamza140202/agent-video-downloader
• Issues: file on GitHub with the metadata.extractor_chain and metadata.slots_tried from your run's manifest attached