109 lines
4.4 KiB
Markdown
109 lines
4.4 KiB
Markdown
# 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](docker-deployment.md) |
|
|
| Authentication & roles | [authentication.md](authentication.md) |
|
|
| Database schema & layer | [database.md](database.md) |
|
|
| Job management | [job-management.md](job-management.md) |
|
|
| File management | [file-management.md](file-management.md) |
|
|
| Votify download system | [votify.md](votify.md) |
|
|
| Monochrome download system | [monochrome.md](monochrome.md) |
|
|
| Unified download system | [unified.md](unified.md) |
|
|
| Frontend (UI & PWA) | [frontend.md](frontend.md) |
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### 1. Deploy
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Set ADMIN_USERNAME, ADMIN_PASSWORD, SECRET_KEY, PORT
|
|
docker compose up -d --build
|
|
```
|
|
|
|
See [docker-deployment.md](docker-deployment.md) for all environment variables.
|
|
|
|
### 2. Upload credentials (admin)
|
|
|
|
Log in with your admin account, go to **Settings**, and upload:
|
|
- `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.
|