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
  Open the Settings tab using the gear icon. The SugarSpin Address card shows the exact address you are currently using. It is read-only and can be copied for reference.
• 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:

• →
  SugarSpin Address, the read-only address currently being used to open the app
• →
  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.

The address shown is not a promise that it will work from every network. SugarSpin does not detect or configure your router, internet access, VPN, or tunnel. If you want access away from home, the server owner must separately configure an address the remote device can reach.

Appearance

SugarSpin uses one consistent warm-cream interface accent. The older accent-color selector was removed to keep Settings simpler and the appearance consistent across devices.

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 Settings and scroll to the Auto Updates card.
• 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 reachable only on the network where its server runs. SugarSpin does not detect, install, configure, or manage remote access. If you want to connect from cellular or another location, choose and configure an independent networking option, then use the address that service makes reachable. The examples below are starting points only; follow each provider's current documentation for your hardware and network.

CarPlay is built into the official SugarSpin iPhone app and uses the normal SugarSpin connection. It does not use the optional third-party username and password. Android Auto currently requires a compatible third-party app that connects through SugarSpin's Subsonic-compatible API.

Official iPhone app and CarPlay

Install the official SugarSpin app from the App Store and connect it to a SugarSpin address your phone can reach. CarPlay is built into that app. If you are away from home, the address must already be reachable through remote access configured by the server owner.

Android Auto or another third-party client

• 1
  Open SugarSpin Settings and expand Advanced → Third-Party Music Apps.
• 2
  Enter a server address that the other device can actually reach. SugarSpin does not detect or configure that network path.
• 3
  Choose an app-only username and password, or use Generate to create a password.
• 4
  Click Enable & Save, then enter those same three values in the compatible third-party app.

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 the exact reachable address saved in Third-Party Music Apps. A local IP normally will not work on cellular without separately configured remote access.
• →
  Username. Whatever you set in Third-Party Music Apps. Default is sugarspin.
• →
  Password. The one you generated and copied in step 1.

Tap Connect / Save. What appears next depends on which SugarSpin endpoints and dashboard features that third-party app supports.

Step 4, Plug into your car

Plug your phone into your car or use wireless CarPlay / Android Auto if supported by the vehicle. Whether a third-party app appears and which controls it exposes are determined by the phone, vehicle, and app.

Sharing with family

Pro and Gold allow unlimited simultaneous clients. Anyone you authorize still needs an address their device can reach. Treat the third-party app password as a credential: share it only with people you trust and replace it if necessary.

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, Confirm local reachability

Open SugarSpin and the BluOS controller on the local network and confirm that both the server and speaker are reachable. Guest Wi-Fi, VLAN isolation, firewall rules, and some container network configurations can block discovery or playback.

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. Paste the same license key you used before, exactly as it appears in your purchase email.
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 (one server installation per license). Your license key does not expire.