CAT. NO. SG-001 · SELF-HOSTED · AGPL-3.0

Stellar Grooves

A self-hosted music library where playlists are queries you can share. Curators publish the query — subscribers run it on their own library.

Try the live demo View on GitHub

Live demo: demo / GrooveDemo1 — already filled in.

Stellar Grooves library overview
Smart playlist editor with live match count
★ Curate · don't distribute / Query > Upload / Your files, your rules / Smart playlists. Shared as code. / ★ Rock · Metal · Everything in between / Open source forever /
★ Curate · don't distribute / Query > Upload / Your files, your rules / Smart playlists. Shared as code. / ★ Rock · Metal · Everything in between / Open source forever /
// THE BIG IDEA

Curate by query,
not by upload.

Curators pour years into figuring out what to play. Stellar Grooves lets them share that taste as code. A query — written in a focused DSL — is published as a link. Subscribers run that query against their own library, and only ever see tracks they themselves own.

From the desk of the curator
A Query, A Recipe.
SG · DSL v1
~ live preview ~
> genre:hard_rock rating:>=4 lastPlayed:>1y
> sort:random limit:25
curator's library
2,847
tracks scanned
your library
1,103
tracks scanned
overlap on this query
25
matches in your collection
1
CURATOR WRITES

Compose the query.

Use the DSL — fields like genre, rating, tag, lastPlayed. Mix with AND / OR. Live match-count as you type.

2
CURATOR PUBLISHES

Share the link.

A token URL like /shared/smart-playlists/…. Subscribers paste, fork, or follow. No audio attached. The recipe is what travels.

3
SUBSCRIBERS RUN

On their own library.

The query executes against their tracks. They see only what they own. Same recipe, different ingredients — every subscriber gets a personal playlist.

Side B · Sample Queries
A1 — LOST FAVORITES
rating:>=4 lastPlayed:>1y sort:random limit:25

Tracks you rated highly and haven't played in a year.

B2 — ONE-HIT WONDERS
artist:count(==1) sort:random limit:50

Artists you only own a single track from. Surprises every time.

C3 — FRIDAY NIGHT
@hard-rock-bangers OR @thrash-classics rating:>=4 limit:40

Compose phrases. Reuse them anywhere with @phrase-name.

Your audio never leaves your server. The recipe is what travels.

Side A / B · Feature Index

Built for
actual curators.

Spring Boot under the hood, MongoDB at the back, vanilla JS at the front. No Electron, no telemetry, no upsell.

A1

Library & Playback

  • Recursive directory scan for .mp3, .flac, .m4a (and any extension you add); SHA-256 dedup; symlink-safe
  • Crossfade & gapless playback with dual audio elements; 3-second fade between tracks
  • "Up Next" queue persisted across tabs and devices via WebSocket (STOMP/SockJS)
  • On-the-fly FLAC/M4A → MP3 transcoding via ffmpeg; HTTP Range for seeking large files
  • Media Session integration — lock-screen controls, OS-level progress, scheduled scans by cron
A2

Smart Playlists & Curation

  • A focused query DSL — fields, ranges, time windows, AND/OR/parens, sort, limit
  • Reusable @phrase fragments that compose other phrases (with cycle detection)
  • Live preview & match-count on any query, saved or unsaved
  • Subscribe by link, fork to your own editor, materialize a snapshot for export
  • Listening Rediscovery — pre-built queries surface forgotten favorites
A3

Organization & Search

  • MongoDB text index across title (3×), artist (2×), album (1×) with relevance scoring
  • Free-form tags with bulk operations across up to 1,000 files at once
  • Drag-drop playlist reorder; sort by title/artist/album/genre/rating/year
  • Browse by artist, album, genre; album grid view with cover-art thumbnails
  • Cover art from embedded tags, sidecar folder images, manual upload, or opt-in online fetch (MusicBrainz + iTunes)
  • Virtual scrolling kicks in at 250+ tracks — 10,000-track libraries stay smooth
B1

Admin & Security

  • Multi-user with form login + JWT (15-min access / 7-day refresh), per-user libraries
  • Account lockout after 5 failed attempts; rate-limited login & signup buckets
  • CSRF, CSP without unsafe-inline, Permissions-Policy, path-traversal prevention
  • Pluggable rate-limit store — in-memory by default, Redis for multi-instance
  • Audit logger writes a separate logs/audit.log with 90-day retention
B2

PWA & Accessibility

  • Installable on desktop and mobile via "Add to Home Screen"
  • Service worker with build-version cache invalidation; offline fallback page
  • Light & dark themes with prefers-color-scheme + manual toggle
  • ARIA labels everywhere, keyboard-navigable sorts, modal focus management
  • Keyboard shortcuts: Space, ←/→ to seek, ↑/↓ for volume
B3

Operations & Observability

  • Prometheus /actuator/prometheus + JSON /actuator/metrics
  • Correlation IDs propagated end-to-end (X-Correlation-Id) for request tracing
  • JSON logs profile (Logstash) for production aggregation
  • OpenAPI 3.0 + Swagger UI (disabled in prod by default)
  • Backup & restore as a single portable JSON file
Side C · Screen Prints

Pinned to the wall.

Six tabs from the actual app — a mix of the light “screen-print” theme and the dark jukebox mode. Both ship; toggle whenever.

The library
The library
○ Light
Sortable, filterable, virtualised
The player
The player
◐ Dark
Crossfade · queue · media keys
Rediscovery
Rediscovery
○ Light
Forgotten favourites surface
History
History
○ Light
Top tracks, top artists, time windows
Mobile PWA
Mobile PWA
○ Light
Installable. Offline-aware.
Login
Login
○ Light
Form auth · lockout · rate-limited
Side D · The lay of the land

It's not Plex. It's not Spotify. It's its own thing.

Compare
A-SIDE
Plex / Jellyfin
B-SIDE
Spotify / Apple Music
FEATURED
Stellar Grooves
Where the audio lives
Your server
Their cloud
★ Your server
What gets shared
Audio files (over your network)
Links to their catalog
★ Queries — recipes, not files
Library scope
Yours
Theirs
Yours
Plays your obscure FLACs
✓
✗
✓
Smart playlists
Per-user, local
Editorial / algorithmic
★ Composable DSL with @phrases
Subscription required
Plex Pass for some features
Always
★ Never. AGPL-3.0.
Side E · Self-Host

One command
and you're spinning.

Docker Compose runs the app and MongoDB together with hardened defaults — no-new-privileges, dropped capabilities, read-only root filesystem. Mount your music dir and go.

Prereq
Java JDK
17+
Prereq
MongoDB
6.0+
Prereq
Maven
3.6+
Prereq
ffmpeg
optional
Clone on GitHub How-to-use guide →
~/stellar-grooves — bash
# Quick start with Docker
$ git clone git@github.com:jeffrey-stellar/stellar-grooves.git
$ cd stellar-grooves
# Generate a JWT secret + boot it
$ JWT_SECRET=$(openssl rand -base64 64) docker compose up --build
→ Started on http://localhost:8089
Sign up at /signup, point a scan at your music directory, and you're set.
# or run from source (Spring Boot)
$ mvn spring-boot:run -Dspring-boot.run.profiles=dev
Spring Boot MongoDB Java 17 Vanilla JS Bootstrap 5 AGPL-3.0
Side F · Managed
● Coming soon

Rather not run a server?

Self-hosting is free and always will be. For everyone else, a managed Stellar Grooves is in the works — we run the app, you keep your music.

You bring storage
Connect your own S3, Backblaze B2, or NAS.
We run the app
No server to maintain, update, or babysit.
Your audio stays yours
Files never live on our servers. Ever.
Join the waitlist

One email when it opens · no spam