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, view your license key, and check for SugarSpin updates.

Your devices now live in the Stream To sheet (the dancing–wave button in the play bar), not on the Account page. Open it to see what’s playing now plus every device and BluOS / NAD speaker you can send the music to. Tap into any device to give it a friendly name, set a default device (a gold dot marks it) so playback lands where you want when you press play, or sign a device out with a single tap. It all syncs across your account. The Account page keeps just the Auto logout setting under Sessions — pick Never if you want sessions to persist until you sign them out yourself.

SugarSpin uses one server address, the same one at home and away. Sign in once on a device and it stays signed in. There’s no LAN/Remote switch to think about any more: set up remote access once (Tailscale recommended, below) and your single address just works on Wi-Fi and on cellular.

Appearance

Under Settings → Appearance you can choose the app's accent color. SugarSpin's signature gold always leads; you pick the one highlight that rides with it — Deep Teal (default), VU-Meter Blue, or Warm Cream. It colors the active page, the player progress, and selected tabs, and saves instantly on that device.

Choosing where the music plays

Press play on whichever device you're at and that device becomes the one making sound; your other devices stay in sync as controllers. To move playback elsewhere, open Stream To (the dancing–wave button in the play bar) — it lists every active device plus your BluOS / NAD speakers from any screen, your phone included — and tap the one you want.

Once your server is up and running, the cleanest way to use SugarSpin on a Mac is the native desktop app. It runs in its own window with no browser chrome, no tabs, no address bar, no browser quirks, and behaves like a proper Mac music app should.

How to install

• 1
  From the homepage, click Download for Mac. You’ll get a file called SugarSpin.dmg.
• 2
  Double click the DMG. A window opens showing the SugarSpin app icon next to a shortcut to the Applications folder.
• 3
  Drag the SugarSpin icon onto the Applications folder shortcut. Wait a moment for the copy to finish.
• 4
  Open Launchpad or your Applications folder and double click SugarSpin to launch.
• 5
  On first launch you’ll see a setup screen asking for your server address. Enter it (e.g. http://your-nas.local:3333 or your remote address) and click Connect. The app remembers it forever after.

Switching servers later

If you move your server to a new IP, or want to point at a different address, click the SugarSpin menu at the top of your screen and choose Switch Server…. The app clears the saved address and restarts you back to the setup screen.

SugarSpin can update itself automatically. The install script from sugarspin.app already includes this, a tiny companion container called Watchtower polls Docker Hub once a day, pulls new SugarSpin releases, and restarts the container. You never see it, you never run it, you never think about it.

How to check if auto updates are on

• 1
  Open SugarSpin and go to Profile → Server Access.
• 2
  Scroll to the Auto Updates card.
• 3
  Green dot + “ON” means you’re set. Click Check for updates now to trigger an immediate poll instead of waiting up to 24 hours.

Turning it on (existing installs only)

If you installed before auto updates were built in, the Auto Updates card shows OFF with a copy paste snippet. Add that snippet to your docker compose.yml, run docker compose up -d, and you’re done.

By default SugarSpin is only reachable on your home network. To stream from your phone, car, or anywhere with internet, set up remote access once. The big win: with the recommended option below, your single SugarSpin address works everywhere, the same address at home and away, so there’s nothing to switch when you walk out the door.

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. Use your SugarSpin address (e.g. http://192.168.1.50:3333). If you set up Tailscale or a Cloudflare Tunnel earlier, that same address works on cellular too, so it keeps playing in the car.
• →
  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.
• →
  Stage, a full screen big-screen view for the TV or 4K monitor: rotating artist photography (or your own album covers), a real scrubbable audio waveform, the track's format and dynamic range, and optional giant synced lyrics.
• →
  Levels, a live meter bridge, peak, loudness (LUFS), stereo width, dynamic range, LRA, and bass energy, all reading off whatever's playing. It only watches the sound, it never changes it.

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