Get SugarSpin Running
in Minutes

The fastest way to get SugarSpin running. The installer checks for Docker, finds your music folder, and launches everything automatically — on any machine, any CPU.

Prefer to run it manually? Pick your platform below. ↓

SugarSpin runs inside a Docker container, so Docker needs to be on the machine that will host your music. Pick your platform below.

SugarSpin lives on Docker Hub at rotrier66/sugarspin. Open a terminal (PowerShell on Windows, Terminal on Mac/Linux) and run the command for your platform.

Once the container is running, open your browser and visit:

If you're opening from a different device on the same network (like a phone or tablet), use your server's local IP address instead:

Create Your Account

On first launch you'll be prompted to create an admin account. Choose a username and password — this protects access to your music server.

Connect Your Music Library

• 1
  After logging in, click the person icon in the left sidebar to go to your Account / Settings page.
• 2
  Scroll down to the Settings tab (the gear icon). You'll see a Server Access section at the top — your full URL is listed there as a clickable link. Bookmark it!
• 3
  Below that, find the Music Library section. The path to your music folder is shown here. Click Scan Library to index your collection — SugarSpin will read all your files and build your library.
• 4
  Scanning can take a minute or two depending on how large your library is. When it's done, your albums, artists, and songs will all appear in the app.

SugarSpin has a clean sidebar navigation. Here's a quick tour of every section:

The Player Bar

When music is playing, a player bar appears at the bottom of the screen with playback controls — play/pause, skip, shuffle, repeat, and volume. Click the note icon (♪) at the bottom-right of any page to jump to the full Now Playing vinyl view.

Search

The search bar at the top searches across your entire library — albums, artists, and song titles — instantly.

Settings (⚙️)

The gear icon in the sidebar opens your Settings page. From here you can:

• →
  Server Access — your full clickable URL (great for bookmarking from any device on the network)
• →
  Music Library — rescan your library if you've added new music
• →
  Watchtower — toggle the file watcher on/off (auto-detects new music added to your folder)
• →
  Playback settings — crossfade, audio quality, and more

Account (👤)

The person icon opens your account page where you can change your password, manage session settings (including require-login), view your license key, and check for SugarSpin updates.

By default SugarSpin is only accessible on your local network. If you want to stream your music from your phone, car, or anywhere with internet, you have two great options:

SugarSpin speaks the Subsonic API, the same protocol used by Navidrome, Funkwhale, and Airsonic. That means any iPhone or Android app that supports Subsonic + CarPlay/Android Auto can stream your library to your dashboard. Browse albums on the screen, skip tracks from the steering wheel, see album art, the works.

Step 1 — Turn it on inside SugarSpin

• 1
  Open SugarSpin in your browser and click your profile / settings icon.
• 2
  Scroll down to the CarPlay & External Apps section.
• 3
  Click Generate to create a strong password.
• 4
  Click Enable & Save. Hit Copy next to the password — you'll need it in a minute.

The username defaults to sugarspin. You can change it to anything you like.

Step 2 — Pick an app for your phone

Step 3 — Connect the app to your server

Open the app you installed and add a new server. You'll need three things:

• →
  Server URL. If your phone is on your home Wi-Fi, use the local URL (e.g. http://192.168.1.50:3333). If you set up Cloudflare Tunnel or Tailscale earlier, use that public URL instead so it works on cellular too.
• →
  Username. Whatever you set in SugarSpin's CarPlay section. Default is sugarspin.
• →
  Password. The one you generated and copied in step 1.

Tap Connect / Save. The app will scan your library and show your artists, albums, and playlists.

Step 4 — Plug into your car

Plug your phone into your car (or use wireless CarPlay / Android Auto if you have it). The app should show up on your dashboard automatically. Tap it, browse your music, and play.

Sharing with family

If you have Gold, your family can use the same credentials on their phones — your spouse's iPhone, the kids' iPads, all streaming from your server simultaneously. That's what unlimited simultaneous clients means. Just give them the Server URL, username, and password.

If you own a Bluesound speaker (Node, Powernode, Pulse) or a NAD network amp (M10, M33, C-series), SugarSpin can stream straight to it. No extra app on the speaker side, no AirPlay middleman. Just pick it from the device picker and play.

Step 1 — Make sure your speaker is on the same network

The BluOS device and your SugarSpin server need to be on the same LAN/Wi-Fi. Cross-VLAN or guest-network setups won't work because the speaker has to be reachable directly from SugarSpin.

Step 2 — Open SugarSpin from your home network at least once

The first time you load SugarSpin from a device on your home Wi-Fi (using its local IP like http://192.168.x.x:3333), the server captures that as the LAN URL. This is the address it gives the speaker to fetch audio from. Without this step, cast won't work because the speaker has nothing to connect to.

Step 3 — Connect when prompted

SugarSpin auto-scans your network for BluOS devices on startup. When one is found, a toast pops up in any open SugarSpin browser tab: "Found NAD M10 on your network — Connect?" Click Connect and the speaker is added to your device picker.

• →
  The device picker is the speaker icon in the bottom-right of the play bar.
• →
  BluOS devices appear in the list with their actual name (e.g., "HDS NAD" or "Living Room Powernode").

Step 4 — Pick the speaker, play music

Click the BluOS device in the picker. Your local audio mutes and the speaker takes over. The speaker's own front-panel display shows the song title, artist, album, and cover art. Use SugarSpin's controls (play, pause, next, back, song selection) normally — they all route to the speaker.

Multi-device control

Once a speaker is cast, ANY device with SugarSpin open can control it. Start a song on your Mac, skip on your iPad, queue something from your phone. They all see the same queue and the same now-playing state. Perfect for family setups.

Switching back to your browser

Open the device picker again and click your own device (your Mac, iPad, etc.). The Bluesound speaker stops cleanly and audio resumes on the browser. One picker, both directions.

SugarSpin can show you synced lyrics for almost any song and turn the Now Playing view into a live light show. Both are turned on by default — here's how to use them.

Switching the Now Playing view

Look for the faint circular icon in the top-right corner of the Now Playing screen. It sits at about 30% opacity so it doesn't distract from the album art. Tap it once to open the picker.

• →
  Vinyl — the default spinning record with tonearm. The arm tracks playback position; you can drag it to seek.
• →
  Lyrics — synced lyrics in three animation styles (see below).
• →
  VU Meter — retro stereo needles with tube glow. Animates from the actual audio.
• →
  Spectrum — 48-bar frequency analyzer.
• →
  Oscilloscope — classic green glowing waveform.
• →
  Radial Spectrum — circular frequency bars radiating from the center.
• →
  Tubes — four photoreal vacuum tubes glowing amber over a warm bokeh field. The glow breathes on a slow ~5-second cycle tied to the song’s overall loudness. New in v1.8.1.

Lyrics: three animation styles

When you pick the Lyrics view, a faint pill appears at the bottom of the screen with three style options. The pill stays at 20% opacity until you reach for it.

• →
  Scroll — karaoke-style. Current line highlighted in gold; everything scrolls smoothly. Best for reading along.
• →
  Spotlight — full-screen focus on the current line only, in big bold type. Best for ambient/lean-back listening.
• →
  Wave — gentle rising/falling transitions between lines. Best for slower songs.

Where lyrics come from

SugarSpin checks two free lyric databases automatically — you don't need any API keys.

• →
  LRCLib (primary) — community-uploaded synced lyrics, about 3 million songs. Great for Western pop and rock.
• →
  NetEase Cloud Music (fallback) — kicks in if LRCLib doesn't have the track. Big boost for K-pop, J-pop, Chinese, and older Western catalog.

Once a song's lyrics are found, they're cached in your local database forever. They only fetch once per song.

Visualizers that work even when casting

The cool one: even when SugarSpin is streaming to your Bluesound or NAD speaker (so your laptop's audio is silent), the visualizers still animate from the real audio. The server decodes the track and broadcasts level data 30 times per second to every connected browser. So your Mac, iPad, and any other open SugarSpin tab all bounce in perfect sync with what the speaker is playing.

First time each song plays after a SugarSpin upgrade, the server does a one-time decode in the background (1-2 seconds). After that it's instant.

ReplayGain: consistent volume across tracks

Different albums are mastered at wildly different levels — a quiet jazz record next to a loud rock record means constant volume-knob-twiddling. ReplayGain fixes that by storing a per-track and per-album loudness number in the file metadata, and SugarSpin applies it during playback so everything sits at the same perceived level.

Turning it on

Go to Settings → ReplayGain. Three options:

• →
  Off — raw file levels, no normalization. Default.
• →
  Track — each track normalized individually. Best for shuffled playlists where you're mixing songs from many albums.
• →
  Album — preserves intra-album dynamics (the quiet song stays quieter than the loud song on the same album) but normalizes between albums. Best for full-album listening.

For ReplayGain to work, your files need to have ReplayGain tags written in. Most modern downloads (Bandcamp, qobuz, etc.) already have them. For older files, tools like mp3gain, foobar2000, or MusicBrainz Picard can analyze and add the tags.

Discover Daily

SugarSpin generates a fresh 25-track playlist for you every day, mixed from:

• 12 tracks from your favorite artists (based on play history)
• 8 tracks from albums you haven't played in a while
• 5 deep-cut surprises from elsewhere in your library

It's pinned to the top of your Home page. Click Shuffle if you want a different mix on-demand. The playlist refreshes automatically each day — no setup needed.

Tube Warmth — analog DSP (new in v1.8.1)

A built-in vacuum-tube saturation stage that adds the gentle even-order harmonics and soft compression of a real tube preamp to your audio — the warmth without the gear. It runs entirely in the browser’s Web Audio API graph, between your file and your speakers/headphones. Your source FLAC/ALAC files are never touched.

Go to Settings → Tube Warmth. Four presets plus a custom drive slider:

• →
  Off — bypassed. Default.
• →
  Subtle — a hint of warmth. Hard to A/B but takes a digital edge off.
• →
  Warm — classic tube character. The one to start with if you’re curious.
• →
  Vintage — deeper saturation with rolled-off highs. Sounds like an old console.
• →
  Custom — reveals a Drive slider (0–100). Push it for more harmonic richness.

When a new version of SugarSpin is released, you'll see an Update Available banner on your Account page inside the app. Here's what that means and how to apply it.

What the update does

SugarSpin runs as a Docker container. Updating means pulling the new container image from Docker Hub and restarting SugarSpin with it. Your music library, playlists, favorites, settings, and play history are all stored in a separate data volume — they are completely unaffected by the update.

How to update

Click Copy Update Command on your Account page. This copies the update command to your clipboard. How you run it depends on how you manage Docker on your machine:

• NAS (QNAP, UGREEN, TrueNAS, Unraid, etc.) — Open your NAS's Docker management interface (Container Station, Container Manager, etc.), find the SugarSpin container, and use the "Update" or "Recreate" option. Most NAS Docker GUIs have a built-in way to pull a new image and restart — you don't need the command at all. Check your NAS's own documentation for the exact steps.
• Mac with Docker Desktop — Open Terminal (search for it in Spotlight with ⌘Space), paste the copied command, and press Enter. Docker Desktop will handle the rest.
• Windows with Docker Desktop — Open PowerShell or Command Prompt, paste the command, and press Enter.
• Linux — Open a terminal, paste the command, and press Enter.

Once the update finishes, SugarSpin restarts automatically and you'll be on the latest version. Refresh your browser if the page doesn't update on its own.

I'm not comfortable running commands — what do I do?

If you're on a NAS, you almost certainly don't need to. Your NAS Docker interface can handle the update graphically — look for an "Update image" or "Recreate container" button next to the SugarSpin container. If you're unsure where to find it, search for "[your NAS brand] update Docker container" for specific instructions.

If you do need to use a terminal and aren't sure how, feel free to reach out at support@hotdang.studio — we're happy to walk you through it.

Your SugarSpin license is yours — it's not permanently locked to one machine. You can deactivate it and move it to a different machine whenever you need to.

When would I need to do this?

• You're moving SugarSpin to a new NAS or a new computer
• You reinstalled Docker and it's treating the machine as new
• Your license shows as "free tier" after moving from one machine to another
• You want to run SugarSpin on a different machine for a while

How to deactivate your license

1. Open SugarSpin in your browser and go to the Account page (click your avatar or username in the sidebar).
2. Scroll down to the License section. You'll see your current tier and license key.
3. Click Deactivate License. A confirmation prompt will appear — read it and confirm.
4. Your machine reverts to the free tier. Your library, playlists, and favorites are untouched.
5. Your license key is now free to be activated on another machine.

How to activate on the new machine

1. Install and launch SugarSpin on the new machine.
2. Go to the Account page and find the License section.
3. Enter your license key (the same one you used before — format: SS-GOLD-XXXX-XXXX-XXXX-XXXXXXXX).
4. Click Activate. Your full tier unlocks immediately — no rescan needed.

What if I can't access the old machine anymore?

If the old machine is gone, broken, or you no longer have access to it, contact us at support@hotdang.studio with your license key. We'll manually release the activation and you can re-activate on the new machine. This is always available — you're not stuck.

Do I need to buy a new license?

No. Never. One purchase is valid for as long as you use SugarSpin. You can deactivate and re-activate as many times as you need, on as many machines as your tier allows (Pro: 1 machine, Gold: 2 machines). Your license key does not expire.