Skip to content
phexussPublic

About

Desktop music player for Windows, macOS and Linux: Deezer and SoundCloud search, YouTube playback and downloads via yt-dlp from your own IP, synced lyrics, playlists, cloud library. Electron + NestJS.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

EXØS

A music player for the desktop that finds, streams and downloads tracks from several sources on your own computer.

Electron React NestJS License

EXØS desktop: home

Status

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).

What is EXØS

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.

EXØS on the desktop

EXØS desktop: full-window player with lyrics EXØS desktop: a playlist imported from Spotify

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, .srt or .txt file, 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.

The Android app (on hold)

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

Tech Stack

Desktop app — desktop

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.

Android app — apps/mobile (on hold)

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)

Backend — apps/api

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

Landing Page — apps/web

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.

Infrastructure

Component Technology
Database Neon (serverless Postgres)
Cache Upstash (serverless Redis)
Email Resend
Builds EAS Build
Monorepo pnpm workspaces · Turborepo
Linting Biome

Architecture

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"]
Loading

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.

Getting Started

Prerequisites

  • Node.js 20+
  • pnpm 10+
  • Android SDK (only for the on-hold mobile app)
  • yt-dlp installed on the server

Install

git clone https://github.com/phexuss/exos.git
cd exos
pnpm install

Run the desktop app

cd desktop
npm ci
npm start        # builds and opens the app
npm run dev      # UI only, in the browser with example data

Run the mobile app (on hold)

cp apps/mobile/.env.example apps/mobile/.env
cd apps/mobile
npx expo start

Run the API

cp .env.production.example apps/api/.env
cd apps/api
pnpm dev

Environment Variables

Mobile (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

Project Structure

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

Built by phexuss

About

Desktop music player for Windows, macOS and Linux: Deezer and SoundCloud search, YouTube playback and downloads via yt-dlp from your own IP, synced lyrics, playlists, cloud library. Electron + NestJS.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages