mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-18 08:36:13 +00:00
feat(cli)!: deprecate speaker-based station search in favour of find
The `find` family runs the search inside the CLI, querying the radio provider's public API directly (no speaker cloud, no soundtouch-service). Make it the canonical path and deprecate the speaker-based search family. - Add `find-tunein` and `find-radiobrowser` siblings; refactor the find actions onto a shared `runFind` helper (all support `--more`). - Rename the unreleased `search-radiobrowser` to `find-radiobrowser`. - Deprecate `search`, `search-tunein`, `search-pandora`, `search-spotify`: they keep working but print a stderr deprecation notice (new `PrintDeprecation` helper) pointing at the `find*` replacement. Pandora and Spotify have no built-in equivalent yet (they need the speaker + account), so their notices say so. - Docs: lead with the `find` family as recommended; mark the speaker-based search commands deprecated; drop the misleading "service-side" wording in favour of "built-in / queries the provider directly". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
21efb412fe
commit
c7eda7ed7b
@@ -904,25 +904,63 @@ Search for and manage radio stations and streaming content.
|
||||
|
||||
Search and manage stations.
|
||||
|
||||
##### Built-in search: the `find` family (recommended)
|
||||
|
||||
The `find` commands run the search **inside the CLI itself**, querying the
|
||||
radio provider's public API directly. They need **neither the speaker's
|
||||
cloud nor a running `soundtouch-service`**, and they don't require a
|
||||
reachable speaker (`--host`) to search — so they keep working even after
|
||||
the speaker's original cloud is gone. This is the recommended way to
|
||||
search.
|
||||
|
||||
- `station find --provider tunein|radiobrowser --query <term>` — unified
|
||||
built-in search. `--provider` defaults to `tunein`.
|
||||
- `station find-tunein --query <term>` — TuneIn sibling
|
||||
(= `find --provider tunein`).
|
||||
- `station find-radiobrowser --query <term>` — Radio Browser sibling
|
||||
(= `find --provider radiobrowser`).
|
||||
- `… --more` — follow up to three additional result pages when available
|
||||
(both TuneIn and Radio Browser paginate).
|
||||
|
||||
Results include each station's playback `Location`, which you can feed to
|
||||
`source tunein` (TuneIn) or a preset/play flow.
|
||||
|
||||
```bash
|
||||
# Search across any source
|
||||
# Unified built-in search (no speaker required)
|
||||
soundtouch-cli station find --provider tunein --query "jazz"
|
||||
|
||||
# TuneIn sibling
|
||||
soundtouch-cli station find-tunein --query "jazz"
|
||||
|
||||
# Radio Browser, walking extra result pages
|
||||
soundtouch-cli station find-radiobrowser --query "jazz" --more
|
||||
```
|
||||
|
||||
##### Deprecated: speaker-based search
|
||||
|
||||
These commands ask the **speaker** to search, which only works while the
|
||||
speaker's cloud source is reachable. They are **deprecated** — each prints
|
||||
a deprecation notice — and will be removed in a future release. Prefer the
|
||||
`find` family above. There is no built-in equivalent for Pandora or
|
||||
Spotify *yet*; those still require the speaker and your account.
|
||||
|
||||
```bash
|
||||
# [DEPRECATED] Search across any source via the speaker → use `station find`
|
||||
soundtouch-cli --host <device> station search --source <SOURCE> --query <SEARCH_TERM>
|
||||
|
||||
# Search TuneIn specifically
|
||||
# [DEPRECATED] Search TuneIn via the speaker → use `station find-tunein`
|
||||
soundtouch-cli --host <device> station search-tunein --query <SEARCH_TERM>
|
||||
|
||||
# Search Pandora specifically (requires account)
|
||||
# [DEPRECATED] Search Pandora via the speaker (no built-in equivalent yet)
|
||||
soundtouch-cli --host <device> station search-pandora --source-account <ACCOUNT> --query <SEARCH_TERM>
|
||||
|
||||
# Search Spotify specifically (requires account)
|
||||
# [DEPRECATED] Search Spotify via the speaker (no built-in equivalent yet)
|
||||
soundtouch-cli --host <device> station search-spotify --source-account <ACCOUNT> --query <SEARCH_TERM>
|
||||
```
|
||||
|
||||
# Find stations via the AfterTouch service (TuneIn or Radio Browser; no live cloud needed)
|
||||
soundtouch-cli station find --provider <tunein|radiobrowser> --query <SEARCH_TERM> [--more]
|
||||
|
||||
# Search Radio Browser via the AfterTouch service
|
||||
soundtouch-cli station search-radiobrowser --query <SEARCH_TERM>
|
||||
##### Manage stations
|
||||
|
||||
```bash
|
||||
# Add station and play immediately
|
||||
soundtouch-cli --host <device> station add --source <SOURCE> --token <TOKEN> --name <NAME>
|
||||
|
||||
@@ -933,51 +971,6 @@ soundtouch-cli --host <device> station remove --source <SOURCE> --location <LOCA
|
||||
soundtouch-cli --host <device> station list --source <SOURCE> [--source-account <ACCOUNT>]
|
||||
```
|
||||
|
||||
**Search Examples:**
|
||||
```bash
|
||||
# Search TuneIn for jazz stations
|
||||
soundtouch-cli --host 192.0.2.10 station search-tunein --query "jazz"
|
||||
|
||||
# Search Pandora for Taylor Swift
|
||||
soundtouch-cli --host 192.0.2.10 station search-pandora --source-account myuser123 --query "Taylor Swift"
|
||||
|
||||
# Search Spotify for workout playlists
|
||||
soundtouch-cli --host 192.0.2.10 station search-spotify --source-account spotify_user --query "workout playlist"
|
||||
|
||||
# General search across any source
|
||||
soundtouch-cli --host 192.0.2.10 station search --source TUNEIN --query "classic rock"
|
||||
```
|
||||
|
||||
##### Service-side search: `station find` and `station search-radiobrowser`
|
||||
|
||||
The commands above (`search`, `search-tunein`, …) ask the **speaker** to
|
||||
search, which only works while the speaker's cloud source is reachable.
|
||||
`station find` and `station search-radiobrowser` instead run the search
|
||||
**in AfterTouch itself**, so they work even when the speaker's original
|
||||
cloud is gone — and they don't require a reachable speaker (`--host`) to
|
||||
search:
|
||||
|
||||
- `station find --provider tunein|radiobrowser --query <term>` — unified
|
||||
service-side search. `--provider` defaults to `tunein`.
|
||||
- `station find … --more` — follow up to three additional result pages
|
||||
when more are available (Radio Browser and TuneIn both paginate).
|
||||
- `station search-radiobrowser --query <term>` — Radio Browser sibling,
|
||||
equivalent to `station find --provider radiobrowser`.
|
||||
|
||||
Results include each station's playback `Location`, which you can feed to
|
||||
`source tunein` (TuneIn) or a preset/play flow.
|
||||
|
||||
```bash
|
||||
# Service-side TuneIn search (no speaker required to search)
|
||||
soundtouch-cli station find --provider tunein --query "jazz"
|
||||
|
||||
# Service-side Radio Browser search, walking extra result pages
|
||||
soundtouch-cli station find --provider radiobrowser --query "jazz" --more
|
||||
|
||||
# Radio Browser sibling (same as: station find --provider radiobrowser)
|
||||
soundtouch-cli station search-radiobrowser --query "VRT"
|
||||
```
|
||||
|
||||
**Station Management Examples:**
|
||||
```bash
|
||||
# Add a station found from search results (use token from search output)
|
||||
@@ -1001,8 +994,8 @@ soundtouch-cli --host 192.0.2.10 station remove \
|
||||
|
||||
**Workflow Example - Discover and Play New Content:**
|
||||
```bash
|
||||
# 1. Search for content
|
||||
soundtouch-cli --host 192.0.2.10 station search-tunein --query "smooth jazz"
|
||||
# 1. Search for content (built-in, no speaker needed)
|
||||
soundtouch-cli station find-tunein --query "smooth jazz"
|
||||
|
||||
# 2. Add interesting station from results (copy token from output)
|
||||
soundtouch-cli --host 192.0.2.10 station add \
|
||||
|
||||
Reference in New Issue
Block a user