R3ap3r
3178b8f4f7
- Spotify playlist, library, album and artist browsing with in-app playback - Song, playlist and album downloads via spotdl with YouTube and Bandcamp fallbacks - Electron desktop app (castLabs Widevine) with a permanent sidebar layout - Linux and Windows packaging scripts
3.8 KiB
3.8 KiB
Aurora SpotiRip self-host deployment
Production URL
Server requirements
- Node.js 22+ and pnpm (
npm install -g pnpm). - Python 3.10+ with the venv module (Debian/Ubuntu:
sudo apt install python3-venv). - ffmpeg (
sudo apt install ffmpeg, orvenv/bin/spotdl --download-ffmpeg). - A long-running Node process (server.ts). Downloads run as background jobs held in memory, so a serverless runtime will not work.
Setup (run inside the app folder)
- python3 -m venv venv
- venv/bin/pip install spotdl
- pnpm install
- Fill in env.json (see below).
- pnpm vite build
- pnpm tsx server.ts (listens on http://localhost:3333)
env.json
- SPOTIRIP_BASE_URL=https://spotirip.auroradragon.dev
- SPOTIFY_CLIENT_ID=
- SPOTIFY_CLIENT_SECRET=
- AUDD_API_TOKEN=
- SPOTIRIP_DOWNLOAD_USERS="*" lets every connected Spotify account download. Set a comma-separated list of Spotify user ids to restrict it. The check lives in isDownloadAllowed() (helpers/downloadJobs.tsx); swap it for site logins later.
- SPOTIRIP_PYTHON=venv/bin/python (path to the venv's Python, relative to the app folder)
- SPOTIRIP_DOWNLOADER=spotify_downloader.py (optional; path to the downloader script)
Spotify Developer Dashboard
- Website: https://spotirip.auroradragon.dev
- Redirect URI: https://spotirip.auroradragon.dev/spotify/callback
- In Development Mode Spotify only lets allow-listed accounts (max 25) sign in. Other visitors need the app to be granted Extended Quota Mode.
How downloads work
- The download button POSTs the track link(s) to /_api/spotify-download. Playlists are sent as their individual track links, so private playlists work.
- The server runs spotify_downloader.py (spotdl) into a temporary folder; the page polls /_api/spotify-download-status for progress.
- When finished, the browser is sent to /_api/spotify-download-file, which returns the MP3 (single track) or a zip named after the playlist as an attachment, then deletes the server copy.
- Audio comes from YouTube Music. Songs that fail there are retried with a regular YouTube search, then Bandcamp (FALLBACK_PROVIDERS in spotify_downloader.py). Songs that still fail are skipped and named in the server log ("could not download ...").
- yt-dlp needs a JavaScript runtime for YouTube; the server passes its own Node binary automatically.
- Unclaimed downloads are deleted after 30 minutes. Limits: 1 running download per user, 2 overall (MAX_RUNNING_JOBS in helpers/downloadJobs.tsx).
Reverse proxy
- Proxy the public domain to port 3333 (Nginx, Apache, Caddy, ...).
- Preserve Set-Cookie headers. Spotify session cookies are Secure, HttpOnly and SameSite=Lax.
- Allow large responses (playlist zips can be hundreds of MB); with Nginx set
proxy_max_temp_file_size 0;orproxy_buffering off;for /_api/spotify-download-file. - Serve the SPA with history fallback so /identify, /library, /spotify-library, /artist/:id, /album/:id and /spotify/callback resolve (server.ts already does this).
Browser requirements for local-library features
- File System Access API features work best in Chromium-based browsers over HTTPS.
- When direct folder writing is unavailable, SpotiRip falls back to normal browser downloads.
Production verification after deployment
- Open https://spotirip.auroradragon.dev.
- Connect Spotify and approve the requested scopes.
- Verify the callback returns to /spotify/callback and then to the home page.
- Load a playlist; download one track (MP3) and the whole playlist (zip).
- Test playlist import, My Spotify, Web Playback SDK playback, album/artist browsing and lyrics.
- Test Identify with a real local music file.
- Test Convert, Analyzer, Local Library scan and organizer.
- Confirm mobile bottom navigation and compact player on a phone.