ReClip Headless

A lean, self-hosted media downloader for video and audio links.

This fork is optimised for headless use so agents can fetch metadata or download media without needing a browser.

Public repo: https://github.com/0xWhiteMage/reclip-headless

Original project: https://github.com/averygan/reclip Credit to the original ReClip repository and its author for the base project this fork builds on.

What it does

• Download videos from 1000+ supported sites via yt-dlp
• Fetch metadata first with an info command
• Download as video or audio
• Keep output files in a configurable download folder
• Run either locally with Python or in Docker

Quick start

Headless local use

python3 -m pip install -r requirements.txt
python cli.py info "https://..."
python cli.py download "https://..." --format video
python cli.py download "https://..." --format audio

Custom download folder

RECLIP_DOWNLOAD_DIR=/path/to/downloads \
python cli.py download "https://..."

Docker

docker build -t reclip-headless .
docker run --rm -it reclip-headless info "https://..."
docker run --rm -it reclip-headless download "https://..." --format video

Mount a persistent download folder if needed:

docker run --rm -it \
  -e RECLIP_DOWNLOAD_DIR=/downloads \
  -v "$PWD/downloads:/downloads" \
  reclip-headless download "https://..."

Files to know

• cli.py — headless command entrypoint
• headless.py — shared download and metadata logic
• app.py — thin Flask web wrapper
• reclip.sh — convenience launcher
• Dockerfile — headless container image
• .github/workflows/ci.yml — basic syntax and import checks

Notes for AI agents

• Prefer the CLI path for simple link handling
• Keep the repo lean and reusable
• Use RECLIP_DOWNLOAD_DIR when you need predictable output paths
• The local persistent copy lives at /volume1/Hermes/home/.hermes/resources/reclip-headless

Development checks

python -m compileall -q .
python -c "import cli, app, headless; print('imports-ok')"