A music player for the desktop that finds, streams and downloads tracks from several sources on your own computer.
| App | State |
|---|---|
Desktop (desktop/) |
In active development. This is where the work goes now; new releases come out often. |
Android (apps/mobile) |
On hold, half-working. Development is paused for now, with no date to pick it back up. Builds install and parts work, but playback and downloads are unreliable. |
Server (apps/api) |
Running; serves both apps (search, lyrics, recommendations, accounts). |
EXØS is a music player that aggregates tracks from Deezer and SoundCloud, gets full audio through yt-dlp, and keeps it locally for offline playback, with synced lyrics, recommendations and an account that syncs your library. The desktop app is the main one: there the computer itself is the player. An Android app exists too but is on hold.
The phone app asks the EXØS server for audio. The desktop app turns that around: it is a local player. A computer can run yt-dlp, ffmpeg and a JavaScript runtime by itself, so it does. Audio is found, streamed and downloaded on your machine, from your own IP, and never passes through the server. The server is left with what it is good at: search, lyrics, recommendations and your account.
- Your computer does the work. The engine installs its own yt-dlp, Deno and ffmpeg in one click, keeps yt-dlp up to date, and plays SoundCloud straight from its API.
- Files you own. Downloads land in a plain music folder as Opus, M4A or MP3 (128, 192 or 320 kbit/s) and open in any player.
- Search that remembers. Recent searches and the tracks you played from results wait on the search page, one click to go back, a cross to forget. Next to them, your artists: the ones you actually listen to, download and keep in playlists, with photos.
- SoundCloud artists are artists too. Click an uploader's name anywhere and get their page: avatar, followers, popular tracks and everything they uploaded, the same way Deezer artists work.
- Your playlists, wherever they were. Make playlists here, or bring one over by link from Spotify or SoundCloud. Drag tracks in, drag them into order.
- Sound you can bend. Sped up, slowed + reverb, live on any track. A volume curve that is quiet at 1% the way a mixer is.
- Sound tuned by you. A 10-band equalizer (32 Hz to 16 kHz, ±12 dB) with presets, on its own page next to the effects. Volume normalization brings quiet and loud tracks to one level, measured while the track plays, so nothing is scanned ahead. Crossfade blends one track into the next over 1 to 12 seconds. Each is one switch.
- Keeps playing when closed. Closing the window hides it to the tray, like Spotify; the tray menu has play/pause, next, previous and quit.
- A home page about you. "Mix for you" deals Last.fm picks from what you played in turn with your artists' top tracks, next to "Like …" for your latest track and a shelf of your artists.
- Lyrics you can fix. Synced line by line when they exist, plain when they do not. Wrong version or nothing found? The pencil in the lyrics panel opens an editor: paste your own text or LRC, drop in an
.lrc,.srtor.txtfile, pick another entry from LRCLIB right in the app, or turn plain text into synced lyrics by pressing Space as each line starts. Your lyrics win over the found ones for that track. - One library in the cloud. Sign up right in the app. Everything you download is listed in your account, from the phone too; whatever is missing on this computer downloads again in one click.
- Feels native. Draws at your monitor's refresh rate, keeps what it has seen on disk, preloads what you are about to click.
- Windows, macOS and Linux · English and Russian · the same account as the phone app.
Download: the latest desktop-v… release on the Releases page. Builds are not signed yet: on Windows choose More info → Run anyway, on macOS right-click → Open.
Development of the phone app is paused and it is only partly working. What it was built to do:
- Multi-source search — query Deezer and SoundCloud catalogs from a single search bar
- Full track downloads — audio fetched via yt-dlp through a ticket-based queue system
- Offline playback — downloaded tracks play instantly with no internet required
- Synchronized lyrics — timed lyrics fetched from LRCLIB API, even for SoundCloud tracks if they're somewhat popular
- Recommendations — "Because you listened to…" powered by Last.fm similar tracks
- Cloud library sync — backed-up downloads and play history synced to your account
- Playlists — create local playlists, bulk-add tracks, manage your library
- Dynamic accent color — player UI tinted with the dominant album cover color
- Offline mode — full app access without an account (no sync, no profile)
- i18n — English and Russian
| Layer | Technology |
|---|---|
| Shell | Electron · Windows, macOS, Linux; engine in a utility process |
| UI | React 18 · Vite · Zustand · Motion · Lucide (tokens shared with mobile) |
| Audio | yt-dlp + Deno + ffmpeg running on the user's own computer |
Search, lyrics, account and library sync use the API; audio is fetched by yt-dlp locally, from the user's IP. See desktop/README.md.
| Layer | Technology |
|---|---|
| Framework | React Native 0.81 · Expo SDK 54 (New Architecture) |
| Navigation | Expo Router (file-based) |
| State | Zustand |
| Audio | react-native-track-player |
| UI | Custom components · Solar Icons · Jost font family |
| Animations | react-native-reanimated |
| Lists | @shopify/flash-list |
| Storage | expo-sqlite (local DB) · expo-secure-store (tokens) · AsyncStorage (settings) |
| Layer | Technology |
|---|---|
| Framework | NestJS |
| Database | PostgreSQL (Neon) |
| Cache | Redis (Upstash) |
| Auth | JWT access/refresh tokens · email verification via Resend |
| Download | yt-dlp with concurrency limits and ticket queue |
| APIs | Deezer · SoundCloud · Last.fm · LRCLIB |
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| UI | Tailwind CSS 4 · shadcn/ui · Radix UI |
| Animations | Motion (Framer Motion) |
| Icons | Lucide React |
| i18n | next-intl |
Note: The landing page is a standalone marketing site with no integration to the mobile app or API. It serves as a promotional page only — authentication, music playback, and all app features live in the apps.
| Component | Technology |
|---|---|
| Database | Neon (serverless Postgres) |
| Cache | Upstash (serverless Redis) |
| Resend | |
| Builds | EAS Build |
| Monorepo | pnpm workspaces · Turborepo |
| Linting | Biome |
graph LR
subgraph Client
M["Mobile App<br/>(Expo · React Native)"]
M_ST["Zustand · SQLite<br/>Track Player"]
end
M --- M_ST
M <-->|HTTPS| API
subgraph API["NestJS API"]
AUTH["Auth<br/>JWT + Resend"]
SEARCH["Search<br/>Deezer · SoundCloud"]
DL["Download<br/>yt-dlp · ticket queue"]
SYNC["Library Sync"]
end
AUTH <--> PG["PostgreSQL<br/>(Neon)"]
SYNC <--> PG
AUTH <--> REDIS["Redis<br/>(Upstash)"]
DL <--> REDIS
SEARCH --> LASTFM["Last.fm<br/>recommendations"]
SEARCH --> DEEZER["Deezer API"]
SEARCH --> SC["SoundCloud API"]
DL --> YT["YouTube<br/>(via yt-dlp)"]
DL --> LRCLIB["LRCLIB<br/>synced lyrics"]
Download flow: Client requests download → API creates a ticket → yt-dlp searches YouTube by track name → audio is transcoded and returned → client saves to device storage and syncs metadata to cloud.
- Node.js 20+
- pnpm 10+
- Android SDK (only for the on-hold mobile app)
- yt-dlp installed on the server
git clone https://github.com/phexuss/exos.git
cd exos
pnpm installcd desktop
npm ci
npm start # builds and opens the app
npm run dev # UI only, in the browser with example datacp apps/mobile/.env.example apps/mobile/.env
cd apps/mobile
npx expo startcp .env.production.example apps/api/.env
cd apps/api
pnpm devMobile (apps/mobile/.env):
EXPO_PUBLIC_API_URL=http://localhost:3000/api
API (apps/api/.env):
DATABASE_URL=postgresql://...
REDIS_URL=rediss://...
YTDLP_PATH=/usr/bin/yt-dlp
JWT_ACCESS_SECRET=...
JWT_REFRESH_SECRET=...
LASTFM_API_KEY=...
RESEND_API_KEY=...
# optional, enables Spotify import
SPOTIFY_CLIENT_ID=...
SPOTIFY_CLIENT_SECRET=...
SPOTIFY_REDIRECT_URI=https://<api-host>/api/spotify/callback
exos/
├── apps/
│ ├── api/ # NestJS backend
│ ├── mobile/ # React Native (Expo) app, on hold
│ └── web/ # Landing page (Next.js)
├── desktop/ # Electron desktop app (own package-lock, npm)
├── turbo.json # Turborepo config
├── biome.json # Linter/formatter
└── pnpm-workspace.yaml