Nebula Music：面向 Subsonic 的自托管音乐播放器，新增本地 AI DJ

A polished, self-hosted music player for Subsonic and OpenSubsonic libraries — in your browser or the desktop app.

Stream from Navidrome, Gonic, Airsonic, and other compatible servers through a responsive interface built for desktop, mobile, Windows, and macOS.

Features · AI DJ · Desktop App · Screenshots · Quick Start · Docker · Contributing

Screenshots

Nebula 3.0 in Demo Mode, with dark and light themes, the floating playback dock, the Now Playing sidebar, and the full-screen player. These screenshots use the demo library only.

Desktop App (Windows & macOS)

Nebula is also distributed as a native desktop app built with Electron, on Windows and macOS. It includes everything in the web player plus:

• A custom frameless title bar with native window controls and a system tray
• Automatic updates delivered from GitHub Releases, with an in-app Restart & Install banner and a tray/menu-bar notification when a new version is ready
• Windows taskbar integration: playback progress, thumbnail transport buttons (previous, play/pause, next), and global media keys
• A native always-on-top mini-player window
• Secure credential storage through the OS credential vault (Windows DPAPI)
• The Nebula logo as the app, taskbar, and menu-bar icon

Windows

Download v3.0.0 (Nebula-3.0.0-setup.exe) or its unsigned .appx package. Windows builds are unsigned and may show SmartScreen warnings. Keep Stable selected in Settings → Updates to receive stable releases; choose Beta to opt into prereleases.

macOS

The macOS edition is distributed as a .dmg installer and adds the native features of the platform:

• Native macOS traffic lights with a hidden-inset title bar and a drag-to-move window chrome
• A native application menu (About, Settings ⌘,, Edit shortcuts, Playback controls) and a Dock menu
• A menu-bar status item whose icon adapts to dark/light appearance, with quick controls (Show Nebula, Play/Pause, Next, Previous, Mini Player, Quit)
• Now Playing in Control Center and on the lock screen, plus keyboard media keys via the system Media Session
• Notification Center banners when an update is downloaded
• A floating panel mini-player that stays above other apps and is hidden from Cmd-Tab

Download the Apple Silicon v3.0.0 DMG or ZIP. macOS builds are unsigned and not notarized, and Gatekeeper may block first launch. Updates check for a new version and open the GitHub release for manual DMG installation. AI DJ is disabled and hidden on macOS and in the web player.

Features

Playback

• Shared app-wide audio engine with queue, repeat, seek, volume, and Media Session controls
• Per-track playback speed and pitch controls with pitch-correction support
• Resilient Subsonic streaming with bounded URL caching and stalled-stream recovery
• Automatic transcoding rules for browser-sensitive formats such as ALAC and M4A
• Internet radio playback for direct streams and HLS playlists

Listening Experience

• Web Audio visualizers including Bars, Wave, Circle, Mirror, and Spectrum
• Expandable full-screen player, desktop sidebar player, floating mini-player, mobile player bar, and a native desktop mini-player window
• Structured and synchronized lyrics with fallback lyric providers
• AutoEq headphone calibration profile search and application
• Configurable keyboard shortcuts and an immersive Zen mode

Library and Discovery

• Browse artists, albums, songs, playlists, favorites, and genres
• Spotlight-style search across artists, albums, and tracks
• Featured albums, random mixes, recent releases, and most-played statistics
• Persistent sorting and filtering by genre, year, and library metadata
• Demo mode for exploring the interface without connecting a server

Local AI DJ (Windows experimental)

1. Open Settings → AI DJ and select Download DJ models. The optional 2.01 GB download comes from pinned upstream Hugging Face sources and is verified before use. Models are excluded from the installer and stay in the app's data folder across app updates. Cancel, retry and repair are available.
2. Open Discover → AI DJ and select Start AI DJ. Opening the view alone does not start playback. Connect your Subsonic library for your own music.
3. Choose Familiar, Balanced or Discover, four or five tracks per set, Michael or Heart, and speech between sets or over lowered music in Settings.

The DJ learns from account-scoped listening time, likes, skips and play counts. Balanced aims for about 60% familiar and 40% less-played related tracks, adapting to your library. It greets once and speaks after 4 or 5 completed tracks; skips do not advance that counter. Commentary uses verified track metadata and short phrases, with no invented artist trivia.

Text and speech inference run locally using SmolLM3-3B Q4_K_M and Kokoro-82M quantized ONNX. No API key, Python, Ollama or external inference service is needed. Once downloaded, the models work offline; music still requires access to your server. Preference learning stays on this device. Settings can reset the DJ's learning without removing likes or existing play counts.

Players show a small AI DJ label and the normal music queue. During speech, the main cover becomes a purple orb that responds to voice audio. Next skips speech; pause freezes it. Reduced motion or unavailable WebGPU uses a static cover. The Discover cover keeps moving while visible, including idle or paused sessions. Optional transcription appears only in Discover. Stop DJ keeps queued music playing; Return to previous queue restores your earlier queue and position.

Slower hardware may miss an interlude; music continues immediately. Automated model checks used a 32 GB Ryzen 7 9800X3D. A 16 GB reference machine and long real-server listening remain experimental-feature acceptance items. See behavior, resource security and validation, model notices and shadercn/XorDev visualization notices.

Platform

• Subsonic API 1.16.1 with fallback negotiation through API 1.14.0
• OpenSubsonic extension discovery and structured lyrics v2 support
• ID3-first album and starred endpoints with legacy server fallbacks
• Password token/salt authentication and optional OpenSubsonic API-key authentication
• Responsive light and dark themes with system-preference detection
• IndexedDB caching for API responses, settings, credentials, and local play statistics
• Docker, Vercel, and static-hosting deployment options for the web player
• Native Windows desktop app (Electron) with automatic updates, tray, taskbar controls, media keys, and OS credential vault; macOS edition with traffic lights, app/Dock menus, a menu-bar status item, Now Playing and media keys, and a panel mini-player
• Optional authenticated localhost bridge for the Nebula Music Stream Deck plugin

Stream Deck

Nebula can expose the currently open browser player to the Nebula Music plugin for Stream Deck and Stream Deck+. Install the plugin from its latest release. In Settings → Stream Deck, enable the bridge, use the same local port as the plugin, and enter the six-digit code shown by Stream Deck.

The bridge connects only to IPv4 loopback, is disabled by default, and stores its pairing token in this browser's IndexedDB. It sends playback metadata, playlist summaries, and compressed cover-art pixels; it never sends Subsonic credentials, the complete queue, or authenticated artwork URLs. Use Revoke pairing to remove the pairing from Stream Deck and delete the saved browser token after confirmation. The bridge also exposes Nebula's playback-rate, pitch, and pitch-correction controls to compatible Stream Deck+ plugin versions.

Compatibility

Nebula Music supports servers implementing the Subsonic API or compatible OpenSubsonic extensions, including:

• Navidrome
• Gonic
• Airsonic
• Other Subsonic-compatible servers

The music server must be reachable from the browser running Nebula. HTTPS and correct CORS configuration are strongly recommended.

Quick Start

Desktop (Windows & macOS)

Download and run the Nebula 3.0 Windows installer or macOS DMG. Nebula checks GitHub Releases for app updates. AI DJ is optional and needs the model download described above. To run the desktop app from source:

npm install
npm run start:electron   # builds the renderer + main process and launches Electron

Web (local development)

Prerequisites

• Node.js 22.22.2+, 24.15.0+, or 26+; use Node.js 24 LTS for development and CI
• npm
• A reachable Subsonic-compatible server, unless using demo mode

Local Development

git clone https://github.com/lilremark/Nebula-Music.git
cd Nebula-Music
npm install
npm run dev

Open http://localhost:3000. No environment variables are required.

Choose one of the supported authentication methods:

• Password: Enter the server URL, username, and password. Nebula stores the generated token and salt instead of the raw password.
• API key: Enter the server URL and OpenSubsonic API key. Nebula omits the username and legacy token parameters as required by the extension.

Production Build

npm run typecheck
npm run build
npm run preview

The production bundle is written to dist/.

Docker

The published image is available from Docker Hub as lilremark/nebula-music. It serves Nebula through an unprivileged NGINX 1.30.3 container. The Compose setup uses a read-only filesystem, drops Linux capabilities, and includes a health check.

Pull and run the latest release:

docker pull lilremark/nebula-music:latest
docker run -d \
  --name nebula-music \
  --restart unless-stopped \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=16m \
  --security-opt no-new-privileges \
  --cap-drop ALL \
  -p 8080:8080 \
  lilremark/nebula-music:latest

Open http://localhost:8080.

To stop the container:

docker stop nebula-music
docker rm nebula-music

Using the included Compose configuration:

docker compose -f docker/docker-compose.yml up -d
docker compose -f docker/docker-compose.yml down

Compose uses latest by default. Set NEBULA_VERSION=2.3.0 to pin the current release. See docker/README.md for local-build commands and additional deployment details.

Configuration and Storage

Nebula is a client-side application. Server details and preferences are entered in the UI and stored in the browser.

To reset the application completely, clear the site data for the Nebula origin in your browser.

Keyboard Shortcuts

Shortcuts can be changed in Settings.

Architecture

Nebula-Music/
├── components/          Reusable UI, navigation, radio, and player components
├── constants/           Equalizer presets and shared constants
├── context/             Global store and theme state
├── docker/              Docker, Compose, and Nginx configuration
├── hooks/               Adaptive color, artist image, and waveform hooks
├── public/              Static browser assets and audio worklets
├── services/            Subsonic API, AutoEq, and IndexedDB services
├── screenshots/         README product screenshots
├── views/               Home, browse, library, radio, search, and settings views
├── App.tsx              Application shell and view routing
├── index.tsx            React bootstrap
└── index.css            Global styles and theme variables

Data Flow

flowchart LR
    UI["React views and components"] --> Store["Context store"]
    Store --> API["Subsonic service"]
    Store --> Audio["HTMLAudioElement and Web Audio API"]
    API --> Server["Subsonic/OpenSubsonic server"]
    API <--> Cache["IndexedDB cache"]
    Audio --> Session["Media Session API"]
    Audio --> Visualizer["AnalyserNode visualizers"]

Loading

The global store coordinates library requests, cached responses, playback state, and UI updates. A shared HTMLAudioElement handles playback while a lazily created Web Audio graph powers analysis, visualizers, pitch processing, and equalization.

Scripts

Deployment

Vercel

1. Import this repository into Vercel.
2. Select the Vite framework preset.
3. Use npm run build as the build command.
4. Use dist as the output directory.

Other Static Hosts

Build the project with npm run build, then deploy the generated dist/ directory to Netlify, Cloudflare Pages, Amazon S3, or another static host.

Because Nebula connects directly from the browser, the deployed origin must be permitted by the music server's CORS policy.

Troubleshooting

Nebula cannot connect to my server

• Verify that the URL includes https:// or http://.
• Confirm the server is reachable from the same browser and network.
• Check the server's CORS configuration.
• Avoid mixed content: an HTTPS deployment cannot call an HTTP music server.
• Confirm the selected password or API-key authentication mode is supported by the server.

Audio plays but seeking does not work

• Confirm the server supports byte-range requests and returns appropriate Content-Length and Accept-Ranges headers.
• Enable server-side transcoding for formats the browser cannot seek reliably.

Settings or themes do not persist

• Ensure the browser is not blocking IndexedDB or local storage.
• Clear the site's stored data after changing between demo and live-server credentials.

Changelog

v3.0.0 — October 9, 2026

Highlights since v2.4.6, the previous stable release:

• Redesigned dark and light interfaces, collapsible navigation, and sticky album/playlist headers.
• Floating playback dock, responsive Now Playing sidebar, smooth layout switching, and refreshed native mini player.
• Detailed stereo waveforms, artwork-colored progress, and shared speed/pitch controls.
• Up to 12 Quick Picks and paginated Top 50 / For You rotation on Home.
• Refined search, library controls, and keyboard-accessible Settings sections.
• Experimental local AI DJ with optional model downloads on Windows; hidden and disabled on web/macOS.
• More reliable long queues and crossfades, consistent AutoEQ preamp, updated dependencies, and stronger account isolation.
• Windows x64 and macOS Apple Silicon downloads, Stable/Beta update channels, and reliable taskbar playback controls.

Full 3.0 release notes

v2.5.0-beta.26 — October 5, 2026

• Smoother bottom/sidebar player switching and closing, with coordinated content resizing.
• Continuous playback, keyboard focus transfer and reduced-motion support during switches.
• Rounded, contained search focus highlights and a visible close button in compact layouts.

v2.5.0-beta.25 — October 4, 2026

• AI DJ Discover now shares the Album and Playlist header, actions and track-row styling.
• Its cover keeps moving while visible, including idle and paused sessions, and responds to speech.
• Compact layouts, live reduced-motion preferences and static visualization fallbacks remain supported.

v2.5.0-beta.23 — October 3, 2026

• Added local AI DJ in Discover with personalized sets, two English voices, 4/5-track cadence, two interlude styles and optional transcription.
• Added verified optional model downloads in Settings, keeping models out of the installer.
• Added the speech-reactive purple cover to every player and DJ session gradients.
• Kept content visible with both sidebars open, separated Home slideshow controls from album actions, and simplified the top bar.
• Updated the beta screenshots and documented model setup and system requirements.

v2.4.6 - August 19, 2026

• Added a dedicated Windows title bar with the Nebula wordmark and window controls above the app, matching the macOS layout.
• Moved the window controls out of the top bar into the new title strip in the main window and the full-screen player, and tightened their hover highlights so they fit within the strip.
• The navigation drawer now clears the new Windows title bar instead of overlapping it.

v2.4.5 - August 16, 2026

• Fixed Stream Deck pairing on the Windows desktop app: the bridge handshake now again sends a valid loopback origin the plugin accepts, so the plugin connects and pairs reliably.

v2.4.4 - August 16, 2026

• Fixed playback hanging after the app was minimized or hidden for a long time (or after the PC woke from sleep) by keeping the playback pipeline alive while the window is in the background.
• Reduced idle CPU and smoothed animations: the now-playing panel, mini-player, cover flow, and visualizer no longer re-render every frame while paused or hidden.
• Stopped constant Windows taskbar churn — thumbnail buttons and the taskbar progress bar now update only when they actually change.
• Re-syncs tray, media-key, and mini-player state after waking from sleep.

v2.4.3 - August 12, 2026

• Fixed the auto-update check failing with net::ERR_HTTP2_SERVER_REFUSED_STREAM by forcing update requests over HTTP/1.1, which GitHub serves reliably.

v2.4.2 - August 12, 2026

• Reworked the always-on-top mini-player: it now shows the current album art, progress, and transport controls, plus an "Up Next" list of the next five queued tracks with their cover art.
• Clicking an "Up Next" row jumps playback to that track in the queue.
• Fixed a Windows taskbar issue where a second, overlapping Nebula icon appeared by registering the app's AppUserModelID so all windows share one taskbar entry.

v2.4.1 - August 12, 2026

• Fixed desktop playback stalling after a few tracks — media now loads directly from your server instead of the proxy, so streams and cover art no longer exhaust their connection pool.
• Opening a related album under "More by" now returns to the top of the album page, showing the album art, info, and tracklist (web, Windows, and macOS).
• Waveform previews fall back gracefully on servers that do not send CORS headers, matching the web build.

v2.4.0 - August 11, 2026

• Added a native macOS arm64 edition with a dedicated title strip, traffic lights, app menu, Dock menu, menu-bar controls, media keys, and Notification Center updates.
• Added live Now Playing metadata and sanitized cover art to the macOS Playback menu.
• Added reproducible Windows and macOS release artifacts with platform-specific GitHub update feeds.
• Kept automatic Windows updates and added safe update checks with manual GitHub downloads for unsigned macOS builds.

v2.3.1 — August 8, 2026

• Fixed automatic updates — the updater now reads the published latest.yml (stable channel) and uses prerelease detection for beta.
• Replaced the tray indicator with the Nebula logo.
• Made the Home Most Played / For You section a collapsible dropdown so it no longer scrolls when stacked under Quick Picks.

v2.3.0 — August 8, 2026

• Nebula is now a native Windows desktop app with a custom frameless title bar, window controls, and a system tray.
• Added automatic updates from GitHub Releases with an in-app Restart & Install banner and a tray notification.
• Added Windows taskbar integration: playback progress, thumbnail transport buttons (previous, play/pause, next), and global media keys.
• Added a native always-on-top mini-player window and secure credential storage via the OS credential vault (Windows DPAPI).
• Reworked the sign-in screen into a split view with a looping cover-flow animation.
• Redesigned the Settings updates panel as a centered hero with phase-aware controls.
• Made full-screen player tabs and the sidebar close button clickable; pinned Zen-mode controls and refined the title marquee.
• Improved visualizer accuracy (pre-DSP sampling), aligned the waveform ticker, and smoothed mini-player progress.
• Home layout stacks Quick Picks and Most Played/For You responsively.
• Added a signed NSIS installer plus an unsigned appx package and set the Nebula logo as the app/taskbar icon.

v2.2.0 — July 24, 2026

• Added an opt-in, authenticated localhost bridge for the Nebula Music Stream Deck plugin.
• Added Stream Deck and Stream Deck+ control for now-playing artwork and metadata, playback, seeking and scrubbing, volume and mute, previous and next tracks, fixed playlists, and live playlist browsing.
• Added Stream Deck+ playback-speed, pitch, and pitch-correction controls.
• Added single-use pairing codes, token authentication, loopback-only connections, runtime protocol validation, and sanitized artwork transfer without Subsonic credentials or authenticated URLs.
• Reduced bridge update traffic and removed background command delays for responsive hardware control while Stream Deck is minimized.
• Improved full album and playlist queue replacement before playback.
• Refined Docker security, health checks, Compose deployment, and published multi-platform 2.2.0 and latest images.
• Updated the Tailwind CSS and PostCSS build chain to patched releases with a clean npm audit.

v2.1.3 — June 20, 2026

• Updated all npm dependencies, including React 19, Vite 8, Tailwind CSS 4, TypeScript 6, Motion 12, and Lucide React 1.
• Added OpenSubsonic extension discovery and API-key authentication.
• Added structured lyrics v2 and ID3-first album/starred endpoints with legacy fallbacks.
• Added Subsonic protocol fallback negotiation from API 1.16.1 through 1.14.0.
• Centralized Subsonic response and error handling.
• Updated Docker builds to Node.js 24 LTS and unprivileged NGINX 1.30, with a read-only runtime, dropped capabilities, and container health checks.
• Published multi-platform 2.1.3 and latest images to Docker Hub at lilremark/nebula-music.
• Added refreshed product screenshots and updated project documentation.

v2.1.2 — May 10, 2026

• Added AutoEq headphone calibration.
• Added production Docker and Nginx deployment files.
• Improved long-session Subsonic playback recovery.
• Refined visualizer controls and Settings layout.

See the commit history for the complete development history.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md for development requirements, validation commands, and pull-request guidance.

Security vulnerabilities must not be reported publicly. Email remark@remark.rip and follow SECURITY.md.

License

Nebula code is distributed under the MIT License. Third-party models and phonemizer use their respective licenses. The vendored shadercn renderer is MIT; its ORB-21 shader is non-commercial only with XorDev attribution. See the visualization notice.

Design system

Run npm run design-system and open http://localhost:3100 for the current-design gallery: theme tokens, live shared components, and music-player pattern references. See the design system guide for usage, ownership, and the refinement queue. Build the standalone reference with npm run design-system:build.