Native Streaming

Native Streaming

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

Setup

The native streaming feature uses a separate authentication flow. On first run:

1. Your browser will open to Spotify's authorization page
2. Important: The redirect URI will be http://127.0.0.1:8989/login - this is different from the main app's callback URL
3. After authorizing, "spotatui" will appear in your Spotify Connect device list
4. Credentials are cached so you only need to do this once

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

Notes

• Native streaming is enabled by default when built with the streaming feature
• A Spotify Premium account is required for playback (free accounts fall back to controlling other devices via the Web API)
• The streaming authentication uses a different client than the main app's API controls
• A stable device id is persisted under ~/.config/spotatui/streaming_cache/ so reconnecting does not leave "ghost" Connect devices behind

---

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 (feature mpris).

---

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 MPNowPlayingInfoCenter / MPRemoteCommandCenter APIs and is enabled by default on macOS builds with native streaming (feature macos-media).

---

Windows Media Controls (SMTC)

On Windows, spotatui registers with the System Media Transport Controls (SMTC) — the media overlay surfaced through media keys, the volume flyout, and the taskbar / Win+G Game Bar controls. This enables:

• Media key support - Play/pause, next, previous via keyboard media keys
• System Now Playing display - Track title, artist, album, and cover art in the Windows media flyout
• Position & playback state - Reflected live in the SMTC display

This integration is built on smtc-tokio, is enabled by default on Windows builds (feature windows-media), and activates when the native player is running. Media keys are routed to the native player when a native track is loaded, otherwise to the Spotify Web API.