Retreivr

Self-hosted media acquisition that stays deterministic, tidy, and boring in the best way.

Follow us on X: https://x.com/sudoStacks

---

What Is Retreivr?

Retreivr is a self-hosted download engine for building and maintaining a clean local media archive.

It takes your intent (URL, playlist, search, or Spotify sync), resolves targets, downloads media, applies canonical naming/metadata rules, and writes predictable files to disk.

Retreivr is not a streaming server. It is the acquisition layer.

Why People Use It

• Deterministic downloads (idempotent and repeatable)
• Clean filesystem structure (no random naming chaos)
• MusicBrainz-first metadata authority for music workflows
• Unified queue + scheduler + watcher flows
• Web UI and API for control and automation
• Used for intentional media consumption... avoid getting sucked into the algorithms
• Optional Telegram summaries

0.9.6 Highlights

• Runtime release workflow for versioned GHCR publishing
• Minimal runtime bundle zip assets for simplified Docker deployment
• Music matching robustness improvements across discovery/scoring/retry paths

---

Quick Start (Local Workstation)

Option A) Docker Compose (Manual)

1) Prepare files

cp docker/docker-compose.yml.example docker/docker-compose.yml
cp .env.example .env

2) Start Retreivr

docker compose -f docker/docker-compose.yml up -d

3) Open Web UI

http://localhost:8090

Default mapping is 8090:8000 (host:container).

4) Initial setup in UI

• Open Config page
• Add your playlist/search settings
• Set destination folders (under /downloads in container)
• Optional: configure Spotify OAuth and Telegram

---

Canonical Docker Mounts

Use these container paths for predictable behavior:

• /downloads media output
• /data runtime DB/temp
• /config config.json
• /logs logs
• /tokens auth/cookies

---

Local Run (No Docker)

Requirements:

• Python 3.11.x
• ffmpeg on PATH

Run:

python3.11 scripts/archiver.py --config data/config/config.json

Run API/UI locally:

python3.11 -m uvicorn api.main:app --host 127.0.0.1 --port 8000

Then open:

http://localhost:8000

---

Useful Endpoints

• GET /api/status
• GET /api/metrics
• POST /api/run
• GET /api/download_jobs
• POST /api/import/playlist
• GET /docs (OpenAPI)

---

Upgrade Notes

If you are upgrading to 0.9.6, pull latest image and restart:

docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml up -d

Your mounted /data, /downloads, /config, and /tokens persist.

---

Scope Boundaries

Retreivr does:

• Acquire media reliably
• Normalize metadata and output structure
• Keep playlist/sync ingestion deterministic

Retreivr does not:

• Stream media
• Replace Plex/Jellyfin players
• Bypass DRM/protected content

License

Retreivr is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See the LICENSE file for full details.