Skip to content

native-streaming.md

Latest commit

 

History

History
118 lines (80 loc) · 5.66 KB

native-streaming.md

File metadata and controls

118 lines (80 loc) · 5.66 KB
Raw

Native Streaming

spotatui includes native Spotify Connect support, allowing it to play audio directly on your computer without needing an external player like spotifyd.

Where Spotify plays

spotatui talks to Spotify the way the official app does. Press d to pick where the music plays:

  • spotatui itself, through native streaming (this page). Recommended.
  • Any Spotify Connect device: the official app on your computer or phone, or spotifyd. Start that device first; it then shows up in the d list. If spotifyd does not show up, see its logging docs.
  • Speakers on your network: Google Cast devices and Spotify Connect speakers on the LAN.

Spotify in spotatui needs a Premium account: the login refuses a free account. The other sources (Local Files, Subsonic, Internet Radio, YouTube, Qobuz) play through spotatui's own audio engine and need none of this; Apple Music plays in the Music app.

Setup

Native streaming uses the Spotify login, so there is no separate setup. After you log in (see Connecting to Spotify), "spotatui" appears in your Spotify Connect device list.

How It Works

  • When streaming is enabled, "spotatui" registers as a Spotify Connect device
  • You can control playback from the TUI, your phone, or any other Spotify client
  • Audio plays directly on the computer running spotatui

Audio Quality

Native streaming uses 320 kbps by default. To select a different quality, set streaming_bitrate under behavior in config.yml, or change it in Settings, and restart spotatui:

behavior:
  streaming_bitrate: 320 # 96, 160, or 320 kbps

The same section holds enable_streaming, streaming_device_name (the name in the Connect device list), streaming_audio_cache and streaming_autoplay. Set streaming_autoplay: false to disable Spotify's related-songs autoplay; restart spotatui for the change to take effect. Autoplay is per device, so this applies only to the spotatui Connect device, not your phone or other Connect devices. The bitrate setting controls the librespot native player directly; the Spotify app may still describe a Connect device's quality as "Automatic". The Spotify login and the audio cache are stored in the app cache directory, for example $XDG_CACHE_HOME/spotatui/streaming_cache when XDG_CACHE_HOME is set to an absolute path, or ~/.cache/spotatui/streaming_cache when it is unset or not absolute.

Notes

  • Native streaming is enabled by default when built with the streaming feature
  • Premium account is required

No sound

If the playbar stays on "Paused" with Audio backend failed (or No audio output: ALSA has no default device) and the log shows a line like this, ALSA has no default device:

Audio backend start error: Audio Sink Error Connection Refused: <AlsaSink> Device default May be Invalid, Busy, or Already in Use, ALSA function 'snd_pcm_open' failed with error 'No such file or directory (2)'

Run aplay -L to list the ALSA devices; if default is missing, that's the problem.

On PipeWire this usually means the ALSA bridge isn't installed. Install pipewire-alsa (same package name on Arch, Debian/Ubuntu and Fedora) and restart spotatui. On NixOS, see the PipeWire block in installation.md.

To use a different ALSA device, set SPOTATUI_STREAMING_AUDIO_DEVICE to a name from aplay -L, for example SPOTATUI_STREAMING_AUDIO_DEVICE=pipewire spotatui or plughw:0,0. This only applies to Spotify playback; the other sources use the system default output.

MPRIS D-Bus Integration (Linux)

When using native streaming on Linux, spotatui automatically registers with the MPRIS D-Bus interface, enabling:

  • Media key support - Play/pause, next, previous via keyboard media keys
  • Desktop integration - Track info appears in GNOME/KDE media widgets
  • playerctl compatibility - Control spotatui from the command line:
# Check available players
playerctl -l
# Should show: spotatui

# Control playback
playerctl -p spotatui play-pause
playerctl -p spotatui next
playerctl -p spotatui previous

# View current track metadata
playerctl -p spotatui metadata

MPRIS is enabled by default on Linux builds with native streaming.

macOS Now Playing Integration

When using native streaming on macOS, spotatui registers with the system's Now Playing interface, enabling:

  • Media key support - Play/pause, next, previous via keyboard media keys
  • Control Center integration - Control playback from macOS Control Center
  • Touch Bar support - Media controls on MacBook Pro Touch Bar
  • AirPods / Headphone controls - Play/pause and skip via Bluetooth headphone buttons

This feature uses Apple's MPRemoteCommandCenter API and is enabled by default on macOS builds with native streaming.

Windows System Media Transport Controls (SMTC)

When using native streaming on Windows, spotatui registers with the System Media Transport Controls (SMTC), enabling:

  • Media key support - Play/pause, next, previous via keyboard media keys
  • Media overlay integration - Track title, artist, album, and cover art appear in the Windows volume flyout / media overlay
  • Transport controls - Play, pause, next, previous, stop, and seek requests from the OS are routed back into spotatui

This feature uses the smtc-tokio crate and is enabled by default on Windows builds with native streaming.