Aurora SpotiRip desktop and web app
- 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
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# Building the Windows installer
|
||||
|
||||
## 1. Install the tools (once)
|
||||
|
||||
Open **PowerShell** and run:
|
||||
|
||||
```powershell
|
||||
winget install Git.Git OpenJS.NodeJS.LTS Python.Python.3.12
|
||||
```
|
||||
|
||||
Close PowerShell, open a new one, then:
|
||||
|
||||
```powershell
|
||||
npm install -g pnpm
|
||||
```
|
||||
|
||||
## 2. Get the code
|
||||
|
||||
```powershell
|
||||
cd $HOME
|
||||
git clone <your repository URL> aurora-spotirip
|
||||
cd aurora-spotirip
|
||||
```
|
||||
|
||||
To update an existing copy later: `git pull`.
|
||||
|
||||
## 3. Create the castLabs signing account (once)
|
||||
|
||||
Spotify only plays inside apps signed by castLabs on Windows. The account is free.
|
||||
|
||||
```powershell
|
||||
py -3 -m venv venv
|
||||
venv\Scripts\python.exe -m pip install castlabs-evs
|
||||
venv\Scripts\python.exe -m castlabs_evs.account signup
|
||||
```
|
||||
|
||||
Follow the prompts and confirm the e-mail they send. On later builds the script signs you in again automatically (`castlabs_evs.account reauth`).
|
||||
|
||||
## 4. Build
|
||||
|
||||
```powershell
|
||||
pnpm dist:win
|
||||
```
|
||||
|
||||
The first build takes a while (it downloads Python packages, ffmpeg and castLabs Electron). The installer ends up in `release\Aurora SpotiRip Setup <version>.exe`.
|
||||
|
||||
## 5. Install and set up
|
||||
|
||||
1. Run the installer. Windows shows **"Windows protected your PC"** because the installer is not code-signed: click **More info → Run anyway**.
|
||||
2. Create `%APPDATA%\Aurora SpotiRip\env.json` with the Spotify keys:
|
||||
|
||||
```json
|
||||
{
|
||||
"SPOTIFY_CLIENT_ID": "...",
|
||||
"SPOTIFY_CLIENT_SECRET": "...",
|
||||
"AUDD_API_TOKEN": ""
|
||||
}
|
||||
```
|
||||
|
||||
3. In the Spotify Developer Dashboard, add the Windows user's Spotify account under **User Management**. In-app playback needs Spotify Premium.
|
||||
4. Start Aurora SpotiRip and click **Connect Spotify**.
|
||||
|
||||
The redirect URI `http://127.0.0.1:43117/spotify/callback` is the same on every computer, so nothing else changes in the dashboard.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Songs play on another device instead of the PC:** the castLabs signing step did not run; rebuild after `venv\Scripts\python.exe -m castlabs_evs.account reauth`.
|
||||
- **Antivirus removes `spotify_downloader.exe`:** some antivirus programs flag PyInstaller programs by mistake. Restore it and add an exception for the Aurora SpotiRip install folder.
|
||||
@@ -0,0 +1 @@
|
||||
Flat Web 2.0 music application: dark charcoal surfaces, strong content hierarchy, album-art focus, compact navigation, thin gray separators, small-radius controls, and restrained cyan/violet accents pulled from the SpotiRip logo. Avoid glassmorphism, decorative gradients, glowing borders, oversized cards, huge hero copy, and floating SaaS-style pills. Favor a classic desktop music-library feel inspired by mature web music players: left navigation, top search/import controls, album and playlist areas, dense track lists, and a persistent player. Use Outfit for headings/branding, Plus Jakarta Sans for UI copy, and JetBrains Mono only for paths/durations/status.
|
||||
@@ -0,0 +1,32 @@
|
||||
Aurora SpotiRip production status
|
||||
|
||||
Completed
|
||||
- Spotify authorization-code OAuth with CSRF state validation and refresh-token support.
|
||||
- Production callback route at /spotify/callback.
|
||||
- Current-account connection/disconnection state.
|
||||
- Current user's owned/collaborative playlist picker.
|
||||
- Spotify playlist URL parsing and February-2026 /playlists/{id}/items API support.
|
||||
- Real playlist metadata, artwork, tracks, pagination, filtering, and Spotify attribution links.
|
||||
- Web Playback SDK device setup plus play/pause/previous/next/seek/volume and live now-playing metadata.
|
||||
- AudD music recognition using short browser-generated fingerprint snippets instead of full-file uploads.
|
||||
- Editable/manual metadata fallback for recognition misses.
|
||||
- ID3 title, artist, album, year, track and artwork writing.
|
||||
- Safe duplicate filename handling; originals are never overwritten.
|
||||
- Persistent File System Access API output-directory handle in IndexedDB with download fallback.
|
||||
- Local audio conversion to MP3 using Mediabunny + @mediabunny/mp3-encoder.
|
||||
- Standalone /convert workflow with 128/192/256/320 kbps options.
|
||||
- /settings defaults for filename templates, bitrate, artwork, and automatic match selection.
|
||||
- Flat Web 2.0 visual redesign and dead-control cleanup.
|
||||
- Typecheck clean.
|
||||
- Server-side spotdl downloads: single tracks as MP3, playlists as a zip named after the playlist, sent to the visitor's browser and deleted from the server afterwards.
|
||||
- Browser-tested WAV → MP3 conversion and ID3 metadata round-trip.
|
||||
- AudD backend connectivity tested; unrecognized audio returns a clean no-match result.
|
||||
|
||||
Remaining before launch
|
||||
- Final responsive/browser smoke test on all routes after the mobile redesign.
|
||||
- Final server/browser log review.
|
||||
- Real Spotify OAuth/playback verification after the self-hosted production server is live.
|
||||
- Deploy the app on the self-hosted server (see docs/self-hosting.md).
|
||||
- Configure the self-hosted runtime with SPOTIRIP_BASE_URL, SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET and AUDD_API_TOKEN.
|
||||
- Keep Spotify redirect URI set to https://spotirip.auroradragon.dev/spotify/callback.
|
||||
- Replace the open download access (SPOTIRIP_DOWNLOAD_USERS="*") with site logins once user accounts exist.
|
||||
@@ -0,0 +1,72 @@
|
||||
Aurora SpotiRip self-host deployment
|
||||
|
||||
Production URL
|
||||
- https://spotirip.auroradragon.dev
|
||||
|
||||
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`, or `venv/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)
|
||||
1. python3 -m venv venv
|
||||
2. venv/bin/pip install spotdl
|
||||
3. pnpm install
|
||||
4. Fill in env.json (see below).
|
||||
5. pnpm vite build
|
||||
6. pnpm tsx server.ts (listens on http://localhost:3333)
|
||||
|
||||
env.json
|
||||
- SPOTIRIP_BASE_URL=https://spotirip.auroradragon.dev
|
||||
- SPOTIFY_CLIENT_ID=<Spotify Developer Dashboard client id>
|
||||
- SPOTIFY_CLIENT_SECRET=<Spotify Developer Dashboard client secret>
|
||||
- AUDD_API_TOKEN=<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;` or `proxy_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
|
||||
1. Open https://spotirip.auroradragon.dev.
|
||||
2. Connect Spotify and approve the requested scopes.
|
||||
3. Verify the callback returns to /spotify/callback and then to the home page.
|
||||
4. Load a playlist; download one track (MP3) and the whole playlist (zip).
|
||||
5. Test playlist import, My Spotify, Web Playback SDK playback, album/artist browsing and lyrics.
|
||||
6. Test Identify with a real local music file.
|
||||
7. Test Convert, Analyzer, Local Library scan and organizer.
|
||||
8. Confirm mobile bottom navigation and compact player on a phone.
|
||||
Reference in New Issue
Block a user