Everything you need to know about Stellar Grooves — from a quick scan to crossfade, playlists, and PWA install.
/home/user/Music or C:\Users\You\Music)..mp3, .flac, and .m4a files and pulls title, artist, album, year, genre, and cover art from the embedded tags.The main room has two panels. The left sidebar holds your Up Next queue, playlists, and the scan form. The right panel is your library with Artists, Albums, and Tracks views. Stat cards at the top jump you to filtered views — click Duplicates to review dupes, Albums for the grid.
When a track starts, the 1015 jukebox materializes at the top of the page with live cover art, a spinning platter, bubble tubes, and dual audio elements for crossfade. Controls include:
Click the sparkle button to enable crossfade. The last 3 seconds of each track fade smoothly into the next using two audio elements — no gap, no click.
Add tracks to Up Next with the + button on each row. Queued tracks play before the regular library order resumes. The queue syncs to the server so it persists across sessions and devices.
On supported devices, track metadata and album art appear on your lock screen and in system media notifications. Play, pause, skip, and seek without opening the app.
The search box runs a full-text search across title, artist, and album. Combine it with the artist, album, and genre dropdowns — all filters stack with AND logic.
Switch between three views via breadcrumb navigation:
Rate any track 1–5 stars using the star widget. Click the same star again to clear it. Sort the track list by rating to surface your favorites.
Tracks are auto-classified during scanning. If one shows as Other, click the genre label to reclassify. Your correction is remembered — future scans for that artist will use your chosen genre.
Use row checkboxes (or the select-all toggle) to pick multiple tracks. A bulk action bar appears with options to delete selected tracks or add them to a playlist.
Click the Duplicates stat card to review duplicate tracks (matched by title + artist). You can also detect exact file copies via hash-based duplicate detection. Compare side by side and delete the ones you don't want.
Deleted tracks go to a 30-day trash instead of being permanently removed. Restore from trash if you change your mind, or empty it to free up space.
Create a playlist from the sidebar by typing a name and hitting the + button. Add tracks with the + on each row, or select multiple tracks and use the bulk Add to Playlist action.
Open a playlist and drag-drop tracks to reorder. You can also sort by title, artist, album, genre, rating, or year using the column headers.
Click the share button on any playlist to generate a read-only public link. Anyone with the link can view (but not modify) the playlist. Revoke the link at any time to make it private again.
Export playlists as M3U (for use in other players) or JSON (for backup).
A smart playlist is a saved query. You write a short expression describing the tracks you want — by genre, rating, year, tag, play history — and the results refresh every time you open it. Materialize a smart playlist to take a snapshot of the current results as a static playlist you can reorder or export.
Every predicate is field:value. Whitespace between predicates means AND; use OR between alternatives; prefix with - to negate; wrap in ( ) to group.
genre:heavy_metal — one of classic_rock, hard_rock, hair_metal, heavy_metal, thrash_metal, other.artist:"Black Sabbath" — quotes are required when the value contains spaces.album:"Master of Puppets", title:"War Pigs" — exact, case-insensitive match.year:1986, year:1980..1989, year:>=1990 — integer, range, or comparator.rating:4, rating:3..5, rating:>=4, rating:0 (unrated).tag:favorites — any user-assigned tag.playCount:0, playCount:>=10.lastPlayed:>6mo, lastPlayed:<30d — durations: d, w, mo, y.Add sort: and limit: anywhere in the query.
sort:rating:desc — fields: rating, year, playCount, lastPlayed, artist, album, title. Directions: asc, desc.sort:random limit:20 — random requires a limit:.limit:100 — caps the result size. Without a limit, results are capped at the server's hard ceiling (default 5000); responses include a truncated flag when that cap clips them.Worked examples — paste any of these into the query box.
(genre:heavy_metal OR genre:thrash_metal) rating:>=4 sort:rating:desc limit:100
rating:>=4 lastPlayed:>6mo sort:lastPlayed:asc limit:50
playCount:0 year:>=2020 sort:random limit:30
year:1980..1989 sort:random limit:40
tag:favorites lastPlayed:>30d sort:rating:desc limit:50
artist:"Iron Maiden" OR artist:"Judas Priest" sort:year:asc
rating:0 playCount:<5 sort:random limit:25
genre:heavy_metal -playCount:>=20 sort:rating:desc limit:50
Preview executes your query live and shows the matching tracks — useful while you're iterating. Save stores the query under a name so it shows up in your sidebar. Materialize takes a snapshot of the current results and writes them to a static playlist — handy when you want a frozen ordering you can reorder and share.
Open Listening History from the sidebar for a reverse-chronological feed of every play, with completion status and listened duration. Plays are recorded when a track hits 50% listened or plays to the end — seeks don't count.
The Top Tracks tab ranks the tracks you've played most. Top Artists aggregates plays by artist; click an artist to drill into their albums.
Each tab supports a window: All Time, Last 7 Days, Last 30 Days, or Last Year. Pair with smart-playlist queries like lastPlayed:>6mo to surface rediscovery candidates, or playCount:0 to find unheard tracks.
The scanner walks your music directory recursively looking for .mp3, .flac, and .m4a. For each file it extracts metadata from the embedded tags and computes a SHA-256 hash for duplicate detection.
Files already imported (by path or by title + artist match) are skipped automatically. Cover art is extracted and stored separately, subject to a per-user storage quota.
During a scan, a live counter shows files imported, skipped, or errored. You can keep using the app while a scan runs.
Set up automatic scanning on a schedule. In the Scan Directory panel, configure a cron expression and path. The system checks every 60 seconds and triggers scans when due — great for keeping your library in sync with a folder that gets new music regularly.
To keep the server happy there's a 60-second cooldown between scans. The timer is shown in the scan panel.
Export your full library metadata as JSON or CSV from the library view. Includes all track metadata (title, artist, album, genre, rating, year) but not the audio files themselves.
Create a complete backup as a single JSON file: tracks, playlists, ratings, genre corrections, and file hashes. Restore it on any Stellar Grooves instance to bring your library metadata and playlists back.
Individual playlists export as M3U (compatible with most players) or JSON.
Look for the install icon in the browser address bar, or open the browser menu and select Install Stellar Grooves. The app opens in its own window — no browser chrome — with its own taskbar/dock icon.
In Chrome, tap the three-dot menu and select Add to Home screen or Install app. Stellar Grooves appears as a standalone app on your home screen and in the app drawer.
In Safari, tap the Share button, then Add to Home Screen. Launches full-screen.
Shortcuts are active when the player is visible and no input field is focused.
| Space | Play / Pause |
| → Right Arrow | Seek forward 5 seconds |
| ← Left Arrow | Seek backward 5 seconds |
| ↑ Up Arrow | Volume up |
| ↓ Down Arrow | Volume down |
Users with the Admin role can open the Control Room from the navbar. It shows system-wide stats (total users, files, playlists) and a paginated user management table.
Admins see all registered users with their file counts. Deleting a user permanently removes their account and associated data (tracks, playlists, cover art, queue, genre corrections).
An initial admin can be created on first startup by setting the ADMIN_PASSWORD environment variable. See project documentation for details.