Trackpull — Onboarding Guide

What Is Trackpull?

Trackpull is a self-hosted, multi-user web application for downloading music from Spotify URLs. It supports two download backends that can be used independently or together via a smart fallback system:

Monochrome — proxies audio from Tidal/Qobuz through distributed API instances. Produces high-quality lossless or MP3 files without requiring Spotify credentials.
Votify — downloads directly from Spotify using cookies-based authentication. Requires a valid cookies.txt and optionally a Widevine device certificate.
Unified — tries Monochrome first, falls back to Votify for any tracks that fail. This is the default and recommended mode.

The app is containerized with Docker and stores all state in a mounted volume. A SQLite database tracks users, jobs, and settings.

Systems at a Glance

System	Document
Docker & deployment	docker-deployment.md
Authentication & roles	authentication.md
Database schema & layer	database.md
Job management	job-management.md
File management	file-management.md
Votify download system	votify.md
Monochrome download system	monochrome.md
Unified download system	unified.md
Frontend (UI & PWA)	frontend.md

Getting Started

1. Deploy

cp .env.example .env
# Set ADMIN_USERNAME, ADMIN_PASSWORD, SECRET_KEY, PORT
docker compose up -d --build

See docker-deployment.md for all environment variables.

2. Upload credentials (admin)

cookies.txt — Netscape-format Spotify cookies (required for Votify).
device.wvd — Widevine device certificate (required for some Spotify content).

Monochrome does not require any credentials.

3. Download music

Paste one or more Spotify track, album, or playlist URLs into the Unified tab and click Download. The job will appear in the Jobs tab with live output.

Architecture Overview

Browser (index.html)
    │
    ├── POST /api/unified/download
    ├── POST /api/download          (Votify)
    └── POST /api/monochrome/download
            │
            ▼
        app.py (Flask / Gunicorn)
            │
            ├── db.py (SQLite via thread-local connections)
            │
            ├── Votify path:
            │     subprocess: votify CLI → ffmpeg (optional MP3 conversion)
            │     output dir: /downloads/{user_id}/
            │
            └── Monochrome path:
                  monochrome/api.py
                    ├── monochrome/__init__.py  (instance discovery)
                    ├── monochrome/spotify_to_ids.py  (Spotify scraping + Tidal search)
                    └── monochrome/download.py  (stream, metadata embed, MP3 conversion)
                  output dir: /downloads/{user_id}/

Key Concepts

Jobs are asynchronous. After submitting a download, the job runs in a background thread. Poll the Jobs tab for progress. Jobs survive page refreshes but in-memory state (active downloads) is lost on container restart.

Users are isolated. Each user's files live in /downloads/{user_id}/ and are not visible to other users. Admins can browse all users' files.

Settings are global (per-application, not per-user). Admins configure fallback quality, job expiry, and upload credentials.

Monochrome instances are third-party servers. If downloads fail, it may be because instances are down. The app automatically tries multiple instances and falls back to Votify.

Maintaining This Documentation

Keep these docs up to date. When you add, change, or remove a feature, update the relevant document in docs/. If you add a new system, create a new document and add it to the table above in this onboarding guide.

Guidelines:

One document per system.
Document the why and how, not just the what.
Update API endpoint tables when routes change.
Update option tables when new download parameters are added.
If a gotcha is discovered (e.g., a third-party API quirk), add it to the relevant doc.

Stale documentation is worse than no documentation — readers will trust it and waste time on outdated information.

4.4 KiB Raw Blame History