zget

zget

Agentic local media capture. Download and archive media from YouTube, Instagram, TikTok, Reddit, X, Twitch, C-SPAN, and other sites yt-dlp supports. Library with metadata, dedupe, path health, CLI, and MCP for agents and pipelines.

There is no web UI. Use the CLI or MCP.

Requirements

• macOS or Linux
• Python 3.10+
• uv
• ffmpeg

Install

curl -LsSf https://astral.sh/uv/install.sh | sh
brew install ffmpeg   # macOS

git clone https://github.com/bubroz/zget.git
cd zget
uv sync

Library path

Media and library.db live under ZGET_HOME:

1. ZGET_HOME env
2. ~/.config/zget/config.json key zget_home
3. Default: ~/Downloads/zget

uv run zget config show
uv run zget config set zget_home /path/to/library

$ZGET_HOME/
  library.db
  videos/<platform>/
  thumbnails/
  exports/
  logs/

CLI

# download
uv run zget <url>
uv run zget <url> --quiet
uv run zget <url> --flat
uv run zget <url> -o /path/to/dir
uv run zget <url> --audio-only
uv run zget <url> --quality 720

# metadata only
uv run zget info <url>
uv run zget info <url> --json --compact
uv run zget --list-formats <url>
uv run zget list-channel <channel-or-playlist-url> --since 2020-01-01 --jsonl

# library
uv run zget --search "query"
uv run zget --stats
uv run zget --doctor
uv run zget --doctor --fix
uv run zget paths check
uv run zget paths rewrite --dry-run
uv run zget paths rewrite

# config
uv run zget config show
uv run zget config set flat true

C-SPAN

• c-span.org/video/?... via yt-dlp
• c-span.org/program/.../{id} via public HLS + Referer (src/zget/platforms/cspan.py)
• c-span.org/event/.../{id} via C-SPAN API → child programs (multi-segment events download each)
• If /api/events/… is WAF-blocked: open c-span.org in a browser, then --cookies-from chrome

Sidecars

Each successful download writes:

• {stem}.librarian.json — capture provenance (url, sha256, duration, C-SPAN ids)
• {stem}.nfo — Plex/Jellyfin (CLI and MCP ingest)

Path health

| Class | Meaning | |-------|---------| | healthy | File exists under ZGET_HOME | | relocatable | Stale path; file found after home or volume rename | | off-home | File exists outside ZGET_HOME (pipeline -o) | | offline volume | Unmounted /Volumes/... with no sibling match | | orphan | File missing |

--doctor --fix rewrites relocatable paths only. Use --purge-orphans only when you intend to drop missing rows.

Agents (MCP)

uv run zget-mcp

{
  "mcpServers": {
    "zget": {
      "command": "uv",
      "args": ["run", "zget-mcp"],
      "cwd": "/path/to/zget",
      "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
    }
  }
}

| Tool | Role | |------|------| | zget_download | Download URL into the library | | zget_search | Full-text search | | zget_get_video | Metadata by id | | zget_get_local_path | Filesystem path for other tools | | zget_extract_info | Metadata without download | | zget_list_formats | Formats | | zget_check_url | Already archived? | | zget_get_recent | Recent downloads | | zget_get_by_uploader | By channel |

Full contract for other repos: docs/INTEGRATION.md.

Platforms

Verified: YouTube, Instagram, X, TikTok, Reddit, Twitch, C-SPAN (program + event pages). Many more via yt-dlp.

Layout

src/zget/
  core.py           # yt-dlp download / extract
  platforms/        # adapters (C-SPAN program/event HLS)
  metadata/         # .nfo + .librarian.json sidecars
  library/          # ingest, paths, thumbnails
  cli.py            # CLI
  mcp/              # MCP (stdio)
  db/               # SQLite FTS5
  metadata/         # NFO sidecars
  ...

Dev

uv sync --extra dev
uv run pytest
uv run ruff check src

License

MIT. Built on yt-dlp.