docs(soloist): add a setup guide

README.md

@@ -94,7 +94,7 @@ Then:
 
 Local Files, Subsonic, Internet Radio, YouTube and Qobuz play through spotatui's own audio engine. Apple Music plays in the Music app, and spotatui is its remote. The setup of each source is in [Configuration](docs/configuration.md).
 
-Spotify plays in spotatui itself, on any Spotify Connect device, or on Cast and Connect speakers on your network. See [Where Spotify plays](docs/native-streaming.md#where-spotify-plays).
+Spotify plays in spotatui itself, on any Spotify Connect device, or on Cast and Connect speakers on your network. See [Where Spotify plays](docs/native-streaming.md#where-spotify-plays). For lossless audio, or an account that native streaming cannot play, spotatui can run Spotify's own player: see [Soloist](docs/soloist.md).
 
 ## Learn more
 

docs/README.md

@@ -12,6 +12,7 @@
 ## Features
 
 - **[Native streaming](native-streaming.md):** play Spotify in spotatui itself, and where else Spotify can play.
+- **[Soloist](soloist.md):** play Spotify through Spotify's own player, for lossless audio or an account that native streaming cannot play.
 - **[CLI](cli.md):** control spotatui from your shell.
 - **[Playlist sync](playlist-sync.md):** mirror one playlist onto other sources.
 - **[Listening Party](listening-party.md):** listen in sync with friends.

docs/configuration.md

@@ -78,7 +78,7 @@ behavior:
 
 ## Native streaming
 
-Builds with the `streaming` feature play Spotify themselves as a Connect device. These fields also appear in Settings; a change takes effect after a restart.
+Builds with the `streaming` feature play Spotify themselves as a Connect device. These fields also appear in Settings; a change takes effect after a restart, except `playback_engine`, which switches at once while `enable_streaming` is on.
 
 ```yaml
 behavior:
@@ -87,7 +87,12 @@ behavior:
   streaming_bitrate: 320           # 96, 160, or 320 kbps
   streaming_audio_cache: false     # keep played audio in the streaming cache
   streaming_autoplay: true         # enable Spotify's related-songs autoplay
+  playback_engine: librespot       # or soloist: Spotify's own player (feature `soloist`)
+  soloist_path: /path/to/soloist   # the Soloist program; Settings can download it
+  soloist_audio_quality: lossless  # normal, high, very_high or lossless
 ```
+
+The Soloist API key is in `soloist_credentials.yml` next to `config.yml` (`api_key: ...`), or in `SPOTATUI_SOLOIST_API_KEY`. The setup is in [Soloist](soloist.md).
 ## Cover art dithering
 
 Build with `--features cover-art` to show the cover-art settings. Dithering is off by default and does not turn on cover art where terminal support has disabled it; `draw_cover_art_forced` still controls the basic-terminal fallback.

docs/installation.md

@@ -20,10 +20,10 @@ irm https://spotatui.com/install.ps1 | iex
 
 ### Which build has which features
 
-The prebuilt terminal binaries (the installer, GitHub Releases, Homebrew, `spotatui-bin`, winget) include every source (Local Files, Subsonic, Internet Radio, YouTube, Qobuz, and Apple Music on macOS), the MCP server and the AI DJ. A plain `cargo install` and the Nix flake build the smaller default set: Spotify only, without album art. `cargo binstall` gets the full build only when a release artifact matches your platform; otherwise it falls back to `cargo install` and you get the default set. Add the sources and album art with:
+The prebuilt terminal binaries (the installer, GitHub Releases, Homebrew, `spotatui-bin`, winget) include every source (Local Files, Subsonic, Internet Radio, YouTube, Qobuz, and Apple Music on macOS), the MCP server, the AI DJ and the [Soloist](soloist.md) engine. A plain `cargo install` and the Nix flake build the smaller default set: Spotify only, without album art. `cargo binstall` gets the full build only when a release artifact matches your platform; otherwise it falls back to `cargo install` and you get the default set. Add the sources and album art with:
 
 ```bash
-cargo install --locked spotatui --features local-files,subsonic,internet-radio,youtube,qobuz,cover-art,mcp-server,ai-dj
+cargo install --locked spotatui --features local-files,subsonic,internet-radio,youtube,qobuz,soloist,cover-art,mcp-server,ai-dj
 # macOS: also add apple-music
 ```
 
@@ -39,7 +39,7 @@ cargo install --locked spotatui
 cargo binstall spotatui
 ```
 
-`cargo install` builds the Spotify-only default. For the other sources, album art, the MCP server and the AI DJ, use the `--features` line from [Which build has which features](#which-build-has-which-features). `cargo binstall` fetches the release binary, which already has all of them.
+`cargo install` builds the Spotify-only default. For the other sources, album art, the MCP server, the AI DJ and the Soloist engine, use the `--features` line from [Which build has which features](#which-build-has-which-features). `cargo binstall` fetches the release binary, which already has all of them, when a release artifact matches your platform.
 
 ### Windows (winget)
 
@@ -222,15 +222,15 @@ cd spotatui
 
 **macOS:**
 ```bash
-cargo install --path . --no-default-features --features telemetry,tui,streaming,discord-rpc,cover-art,self-update,scripting,mcp-server,ai-dj,portaudio-backend,audio-viz-cpal,macos-media,local-files,subsonic,internet-radio,youtube,qobuz,apple-music
+cargo install --path . --no-default-features --features telemetry,tui,streaming,discord-rpc,cover-art,self-update,scripting,mcp-server,ai-dj,portaudio-backend,audio-viz-cpal,macos-media,local-files,subsonic,internet-radio,youtube,qobuz,soloist,apple-music
 ```
 
 **Linux/Windows:**
 ```bash
 # Spotify only (the default features)
 cargo install --path .
-# every source, album art, MCP server and AI DJ, like the release build
-cargo install --path . --features local-files,subsonic,internet-radio,youtube,qobuz,cover-art,mcp-server,ai-dj
+# every source, album art, MCP server, AI DJ and Soloist, like the release build
+cargo install --path . --features local-files,subsonic,internet-radio,youtube,qobuz,soloist,cover-art,mcp-server,ai-dj
 ```
 
 **Nix:**

docs/native-streaming.md

@@ -6,7 +6,7 @@ spotatui includes **native Spotify Connect** support, allowing it to play audio
 
 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.
+- **spotatui itself**, through native streaming (this page). Recommended. spotatui can also run Spotify's own player behind the same device: see [Soloist](soloist.md).
 - **Any Spotify Connect device**: the official app on your computer or phone, or [spotifyd](https://github.com/Spotifyd/spotifyd). Start that device first; it then shows up in the `d` list. If spotifyd does not show up, see [its logging docs](https://github.com/Spotifyd/spotifyd#logging).
 - **Speakers on your network**: Google Cast devices and Spotify Connect speakers on the LAN.
 
@@ -52,6 +52,10 @@ directory, for example `$XDG_CACHE_HOME/spotatui/streaming_cache` when
 - Native streaming is **enabled by default** when built with the `streaming` feature
 - Premium account is required
 
+## Tracks fail one after another
+
+If track after track fails with "couldn't be played natively" and the [log](configuration.md#logging) shows `error audio key 0 1`, Spotify refuses librespot the audio keys for your account. A spotatui update cannot change that. After three failed tracks in a row, spotatui offers to set up [Soloist](soloist.md), Spotify's own player, which plays those accounts.
+
 ## 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:

docs/soloist.md

@@ -0,0 +1,92 @@
+# Soloist
+
+[Spotify Soloist](https://developer.spotify.com/dashboard/soloist) is Spotify's own headless player. spotatui can run it as the engine behind its Spotify Connect device, in place of librespot, the engine that [native streaming](native-streaming.md) uses by default. spotatui then sends play, pause, skip, seek, volume, shuffle and repeat to Soloist, and Soloist plays the audio.
+
+## When to use it
+
+- **Native streaming cannot play your account.** Tracks fail one after another and the [log](configuration.md#logging) shows `error audio key 0 1`. Spotify refuses librespot the audio keys for some accounts. After three failed tracks in a row, spotatui offers to set up Soloist.
+- **You want lossless audio.** Soloist streams FLAC where your plan and country have Spotify lossless.
+
+## What you need
+
+- **A build with the Soloist engine.** The prebuilt binaries and the desktop app have it. With `cargo install`, add `--features soloist` (see [Which build has which features](installation.md#which-build-has-which-features)).
+- **Spotify Premium.**
+- **Native Streaming on** (`enable_streaming: true`, the default). Soloist runs behind the same Connect device, so it starts only when Native Streaming is on.
+- **A supported system:** Linux (x86_64, arm64, arm32), macOS on Apple Silicon, or Windows x86_64. Spotify has no Soloist build for Intel Macs, so the Soloist settings do not show there.
+- **A Soloist API key** from Spotify's developer dashboard.
+- **The Spotify app** on a computer or a phone on the same network, once, to pair.
+
+## Setup
+
+Every step is in Settings:
+
+- **Terminal:** open Settings and stay on the Behavior tab. The Soloist rows come right after Playback Engine. When you select a row that has a button, the row shows the button's key, `[o]`. Press `o` to use the button.
+- **Browser and desktop app:** open Settings. The Soloist rows are in the Streaming group, with their buttons next to them.
+
+1. **Download Soloist.** Select **Soloist Path** and press `o` (or click **Download from Spotify**). spotatui downloads the official build for your system from Spotify, unpacks it and saves its path. The status bar shows the progress. By using Soloist, you accept the Spotify Terms and Conditions of Use.
+   On Windows, Windows Firewall asks if Soloist can use the network. Allow it, or a phone or another computer cannot pair with it.
+2. **Get an API key.** Select **Soloist API Key** and press `o` (or click **Get a key**). Spotify's developer dashboard opens in your browser. Make a Soloist API key there and copy it.
+3. **Enter the key.** Edit the **Soloist API Key** row (Enter in the terminal), paste the key, confirm it, and save. spotatui keeps the key in `soloist_credentials.yml` next to `config.yml` and shows only dots in Settings.
+4. **Switch the engine.** Set **Playback Engine** to **Soloist** and save. spotatui stops librespot and starts Soloist. With Native Streaming on, you do not have to restart spotatui.
+5. **Pair once.** A window asks you to pick spotatui in Spotify. Open Spotify on a computer or phone on the same network, open its device menu, and pick **spotatui** (or the name you set in `streaming_device_name`). The window closes by itself when Soloist logs in, and spotatui shows "Paired: spotatui plays through Soloist."
+   Right after the first pairing, Soloist restarts once to apply the audio quality. Soloist keeps the login, so you pair only once.
+
+Now play something. The playbar shows what Soloist streams, for example `FLAC 44.1`.
+
+## Audio quality
+
+**Soloist Audio Quality** sets what Soloist asks for: Normal, High, Very high or Lossless (the default). A change takes effect when Soloist starts again, for example at the next launch.
+
+Lossless needs a Premium plan with lossless in your country. If the playbar still shows a lossy stream, open the device menu in the Spotify mobile app, pick spotatui, and set its quality to Lossless.
+
+spotatui turns Soloist's volume normalization off.
+
+## Switch back
+
+Set **Playback Engine** back to **librespot** and save. spotatui stops Soloist and starts native streaming again. With Native Streaming on, you do not have to restart spotatui. The Soloist download, the key and the pairing stay, so a later switch back to Soloist is immediate.
+
+## In the config file
+
+The same settings in `config.yml`:
+
+```yaml
+behavior:
+  playback_engine: soloist                # librespot (the default) or soloist
+  soloist_path: /path/to/soloist          # the download button fills this in
+  soloist_audio_quality: lossless         # normal, high, very_high or lossless
+```
+
+The key is in `soloist_credentials.yml`, next to `config.yml`:
+
+```yaml
+api_key: your-key
+```
+
+If the environment variable `SPOTATUI_SOLOIST_API_KEY` is set, spotatui uses it in place of the file.
+
+Where the files go:
+
+- Downloaded builds: `soloist-bin/` in the [state directory](configuration.md), one folder per download.
+- Soloist's own data (the pairing and the device id): `soloist/` in the state directory, and `soloist/` in the cache directory.
+
+## Good to know
+
+- **Builds expire.** A Soloist build stops working 90 days after its release. spotatui warns when less than a week is left. Download a new build in Settings (step 1); the key and the pairing stay.
+- **The key is visible to your other programs.** Soloist takes the key on its command line, so other programs that run as your user can read it. spotatui never writes the key to its log.
+- **No downloads for offline play.** Soloist has no offline mode; it streams, like native streaming.
+- **No other sources queued behind Spotify.** With Soloist, you cannot queue a track from another source behind a Spotify track, because Soloist does not tell spotatui when a track ends. Native streaming can.
+
+## Troubleshooting
+
+| Message | What to do |
+|---------|------------|
+| Soloist is not installed. | Download it (step 1). |
+| Soloist not found at ... | The file at Soloist Path is gone. Download it again (step 1). |
+| This Soloist build does not run on this CPU. | Download it again (step 1); spotatui picks the build for your system. |
+| Soloist needs an API key. | Get and enter a key (steps 2 and 3). |
+| Soloist rejected the API key. | Enter a new key (steps 2 and 3). |
+| Pair spotatui: open Spotify on a computer on this network and pick 'spotatui'. | Pair it (step 5). If a phone does not list spotatui, use the Spotify app on a computer. On Windows, check that Windows Firewall allows Soloist. |
+| Soloist build expired. | Download a new build (step 1). |
+| Soloist cannot reach Spotify. | Check your internet connection. |
+| Another Soloist uses spotatui's Soloist data folder. | Close the other Soloist, or the other spotatui that runs one. |
+| Soloist keeps exiting; see the log. | Run spotatui with `--debug` and look at the [log](configuration.md#logging). |