Player and Daemon

The player is the product. If next, pause, device transfer, or search-to-play is flaky, nothing else matters.

Device model

spotuify controls Spotify Connect devices. The preferred local device on this machine is spotuify-hume.

spotuify devices
spotuify transfer spotuify-hume
spotuify status

Choose the local audio output

spotuify-hume is the embedded player running on this machine. It renders to your system’s default audio output unless you pick one. List the outputs and select one:

spotuify audio-outputs                          # list local outputs
spotuify audio-output "MacBook Pro Speakers"    # rebind live, resume playback
spotuify audio-output default                   # follow the system default again

What you get: the choice persisted as player.audio_output_device, the player’s sink rebound in-process (no daemon restart), and the interrupted track resumed where it left off. In the TUI, press O for the same picker.

This is the local output (which speaker on this Mac), not the Connect target. To play on another Connect device (a phone, an Echo), use spotuify transfer instead.

Daemon lifecycle

spotuify daemon start
spotuify daemon status
spotuify daemon stop

Install the user service:

spotuify daemon install-service

Remove it:

spotuify daemon uninstall-service

install-service registers a user-level service for the current platform: launchd on macOS, systemd user units on Linux, and a Task Scheduler logon trigger on Windows.

Upgrading the daemon

The daemon is long-lived, so a freshly-installed binary doesn’t take effect until it restarts. Any CLI command (or launching the TUI) detects a version mismatch and restarts the stale daemon for you. The exception is mid-playback: it leaves the running daemon alone so your audio isn’t cut, and prints a note to restart when ready:

brew update
brew upgrade planetaryescape/spotuify/spotuify
spotuify daemon restart

spotuify --no-daemon-start status refuses a stale daemon instead of replacing it. Use daemon status --format json to inspect the running version and build, then explicitly restart when ready.

If a TUI is already open when you upgrade, it shows an Update installed banner; press R to restart the daemon onto the new build without quitting.

Playback continues after the TUI exits

spotuify

Start music, quit with q, then check:

spotuify status

Playback controls are hot

Play/pause, next, previous, seek, and volume are treated as hot-path actions. The daemon updates its playback clock optimistically for subscribers, then tries the embedded player’s local transport path before waiting on Spotify Web API reconciliation. That is why pressing Space in the TUI should feel immediate even when Spotify’s API response is slow.

Opening the TUI is not a refresh

The TUI seeds Home from cached daemon state. It does not fetch playback, devices, queue, playlists, or library data from Spotify just because a window opened. That keeps provider budget available for the action you actually take, like play, transfer, queue, or search.

Force fresh data when you need it:

spotuify sync library
spotuify playlists --format json
spotuify doctor

Recover a stale session

spotuify reconnect
spotuify devices
spotuify play "imagine dragons"

Use this after sleep/wake, VPN changes, or a Spotify session that stopped responding.

The daemon has two checks. A session health loop runs every 60 seconds and reconnects a dead session that emitted no disconnect event. A separate audio watchdog samples the local PCM counter every 2 seconds. If playback belongs to this device and the counter stays flat for 6 seconds, it marks playback stalled and tries one shared, backoff-controlled reconnect. Neither check takes playback back from a phone or another active Connect device.

Native audio cleanup is fail-closed. If the old player does not finish teardown within 2 seconds, the reconnect stops before it creates another sink. Further reconnects return a message asking for a clean daemon restart after system audio has recovered. This prevents a wedged audio driver from accumulating native sinks and cleanup threads in one process. See silent playback on macOS.

Reload config

spotuify config set player.bitrate 320
spotuify reload

Failure rule

No raw Spotify error should be the final user experience. If playback fails, run:

spotuify doctor
spotuify daemon status --format json
spotuify logs tail 200