999 Vault — JuiceWRLD API Desktop Client

999 Vault is an independent Electron desktop client for JuiceWRLDAPI.com. It provides a responsive archive browser, audio and video playback, endless shuffle, live radio, and resumable downloads powered by the live Juice WRLD API.

The repository name is juicewrld-api-vault. The installed desktop application keeps the shorter product name 999 Vault.

Looking for the phone app? 999 Vault for Android is the native companion, with the same account, synced likes and playlists, archive playback, downloads, Listen, radio, and mobile-first player experience.

Independent project: 999 Vault is not affiliated with, endorsed by, sponsored by, or operated by the JuiceWRLD API team.

Credits

Special thanks to the team at JuiceWRLDAPI.com for maintaining the archive, metadata, media endpoints, and public API that make this client possible.

All music, artwork, names, and trademarks belong to their respective artists, creators, and rights holders. This project does not claim ownership of archive content.

Run the desktop app

Node.js 22.12 or newer is recommended for the current Electron release.

npm ci
npm start

On Windows you can also launch 999-vault.cmd.

Desktop features

• Complete live file index with folder navigation and archive-wide search.
• Canonical song Catalog with composable era and Released, Unreleased, Unsurfaced, and Sessions filters.
• Dedicated lyric search across the Songs API, with readable full-song lyric sheets and archive metadata.
• Audio, lossless, artwork, and video filters.
• Recursive type filters that include matching files in nested Library folders.
• Individual file, current-page, multi-select, directory, and bulk downloads.
• One-click full-collection setup that queues a server-side Compilation ZIP, downloads it with stage progress, validates and extracts it into the local library, then removes the temporary archive.
• Resumable .part files, configurable parallel transfers, cancellation, progress, and error reporting.
• Built-in reading for .txt, .md, .nfo, .log, .json, .csv, .cue, and .lrc files without saving them first.
• Built-in modal video player for MOV, MP4, WebM, and MKV files in the Library.
• Built-in modal image viewer for JPG, PNG, WebP, GIF, SVG, AVIF, and other archive artwork.
• Bulk presets for the organized Compilation, every audio file, Original Files, or cover art.
• Strict “best available” selection: a matching WAV/FLAC replaces its MP3/M4A/AAC/OGG/CAF counterpart, including when the lossless source is in another archive folder.
• Compact JPG, rendered image, or full PSD/TIF artwork choices, so source art is never added to a large download unexpectedly.
• Persistent audio queue with play/pause, seeking, volume, previous/next, shuffle, repeat-all, and repeat-one.
• Queue, selected track, playback position, shuffle, and repeat state restore after restarting the app.
• My Music view with recursively indexed downloaded songs, durable favorites, and custom playlists.
• Optional Discord-linked 999 Vault account for cross-device canonical likes, cloud playlists, and listening events.
• Wrapped dashboard for truthful all-time, 30-day, and 7-day plays, listening time, top songs, eras, and status share.
• Endless shuffle that discovers tracks from every playable song in the archive, keeps recent tracks ready, and supports full-session back and forward navigation.
• Eight-track asynchronous look-ahead in Listen mode, alongside the eight most recent cached tracks, for fast skipping in either direction.
• Seamless playback across the queue, Listen, and 999 FM.
• Persistent 10-band Web Audio equalizer with quality presets, smooth gain changes, bypass, and automatic anti-clipping headroom.
• Discord Rich Presence enabled by default with track, artist, playback time, and live cover artwork.
• System tray support keeps playback and downloads running when the window is closed, with a Settings option to restore normal close behavior.
• Embedded artwork display and one-click cover extraction.
• Live 9 9 9 FM playback, station status, listener count, queue preview, and random-track discovery.
• Responsive navigation and player layouts for full-size and compact windows.
• In-app Credits page acknowledging JuiceWRLDAPI.com and clearly stating the project’s independent status.

The renderer uses Electron context isolation and has no Node.js access. API calls, filesystem dialogs, downloads, and folder access run in the main process through a small preload bridge.

Downloads default to Downloads\999 Vault. Change the location, concurrency, and folder-preservation behavior from the Settings page.

Discord Rich Presence

Rich Presence is enabled by default and can be disabled in Settings. Discord must be running on the same computer. Track cover art is supplied through the public JuiceWRLDAPI.com cover-art endpoint; no Discord login token is requested or stored by 999 Vault.

The public 999 Vault Discord Application ID is bundled with the app. Development builds can override it with VAULT_DISCORD_CLIENT_ID.

999 Vault account service

Account sign-in uses the 999 Vault-owned staging Worker by default. VAULT_ACCOUNT_API_BASE can override it for another owned deployment. There is no fallback to JuiceWRLDAPI or the reference project. The app remains fully usable signed out.

• VAULT_ACCOUNT_API_BASE: exact owned HTTPS API origin.
• VAULT_ACCOUNT_AUTHORIZE_ORIGINS: comma-separated exact HTTPS origins allowed for the browser authorization URL.
• VAULT_ACCOUNT_ALLOW_LOOPBACK=1: development/test only; permits an explicit loopback HTTP origin.

The desktop public client uses vault999://auth/callback, PKCE S256, one-use tickets, rotating 999 Vault sessions, and Electron safeStorage. Discord secrets and Discord access tokens belong only on the owned backend. See docs/account-api-contract.md for the required API and docs/data-migrations.md for local/cloud coexistence rules.

The Worker/D1 backend lives in api/ with its schema migration and deployment instructions in api/README.md.

Build a Windows installer

npm run dist

The NSIS installer is written to release. To verify the packaged application without creating an installer:

npm run pack

ZIP Jobs API tester

The standalone diagnostic CLI prints the complete HTTP status, response headers, and body from each ZIP endpoint. It can start and watch a background job, inspect or cancel an existing job, and compare that flow with the immediate ZIP stream endpoint.

npm run zip:test -- start --watch "Compilation/song1.mp3" "Compilation/song2.mp3"
npm run zip:test -- status JOB_ID
npm run zip:test -- cancel JOB_ID
npm run zip:test -- direct --out selection.zip "Compilation/Folder"

Use --dry-run to inspect a request without sending it. Run npm run zip:test -- --help for timeout, polling, output, and alternate-base-URL options.

Verification

npm run check
npm test

The test suite also covers catalog validation/normalization, PKCE callback handling, encrypted session persistence, queued cloud mutations, listening-credit anti-cheat rules, set-union history merging, and Wrapped aggregation.