docs(readme): overhaul for v2.0 TUI, installers, and CLI
Update documentation to cover the new Bubble Tea TUI, one-liner installers (Linux/macOS/Windows), CLI subcommands (find/play/fav), playback view, configuration, and development/release workflow. Remove outdated build steps, legacy examples, and old TODO list.
This commit is contained in:
parent
8d80a3a647
commit
02c5dd0b09
266
README.md
266
README.md
@ -12,143 +12,157 @@
|
|||||||
This is a port of a Python script I wrote, called "radiostations". It is a simple console tool to grab a list of radio stations retrieved from `radio-browser.info`, put them into a menu, and then use your local installation of a console stream player, to play the station for you.
|
This is a port of a Python script I wrote, called "radiostations". It is a simple console tool to grab a list of radio stations retrieved from `radio-browser.info`, put them into a menu, and then use your local installation of a console stream player, to play the station for you.
|
||||||
|
|
||||||
|
|
||||||
### Requirements
|
## Requirements
|
||||||
* OS: Linux or macOS
|
* OS: Linux or macOS (Windows via the installers or WSL)
|
||||||
* the `mpv` player (or `mpg123` or `mplayer`, if you change the config)
|
* Recommended player: `mpv` (with `--no-video`). Alternatives (`mpg123`, `mplayer`, etc.) can be configured in the ini file.
|
||||||
* Go 1.14+ (if you build your own binary)
|
* For building from source: Go 1.24.2+
|
||||||
|
|
||||||
### Build
|
## Install (for normal users)
|
||||||
1. clone the repository
|
|
||||||
2. cd into the root of the project
|
The easiest way is the one-liner installer attached to each release:
|
||||||
3. run the following:
|
|
||||||
```
|
### Linux / macOS
|
||||||
> go mod vendor
|
```bash
|
||||||
> go mod tidy
|
curl -L https://repos.gmgauthier.com/gmgauthier/gostations/releases/download/v2.0.1/gostations-install.sh \
|
||||||
> go build -o /wherever/you/want/gostations github.com/gmgauthier/gostations
|
| VERSION=2.0.1 bash
|
||||||
```
|
```
|
||||||
|
|
||||||
### Install
|
### Windows (PowerShell) / macOS / Linux with PowerShell
|
||||||
1. copy `gostations` to a location that is on your `PATH`
|
```powershell
|
||||||
2. copy `radiostations.ini` to a location that is on your `XDG_CONFIG_HOME`
|
irm https://repos.gmgauthier.com/gmgauthier/gostations/releases/download/v2.0.1/gostations-install.ps1 | iex
|
||||||
* Note: if you skip step 2, the app will build an ini file for you automatically.
|
```
|
||||||
|
|
||||||
### Execute
|
The installer:
|
||||||
```
|
- Detects your OS and architecture.
|
||||||
> gostations -h
|
- Downloads the matching `gostations-OS-ARCH-vX.Y.Z.tar.gz` (verifies checksum when possible).
|
||||||
Usage:
|
- Installs the binary to `~/.local/bin/gostations` (`.exe` on Windows).
|
||||||
gostations [-n "name"] [-c "home country"] [-s "home state"] [-t "ordered,tag,list"] [-x]
|
- Prints `PATH` advice if needed and runs `gostations -v`.
|
||||||
-c string
|
|
||||||
Home country.
|
|
||||||
-n string
|
|
||||||
Station name (or identifier).
|
|
||||||
-s string
|
|
||||||
Home state (if in the United States).
|
|
||||||
-t string
|
|
||||||
Tag (or comma-separated tag list)
|
|
||||||
-x If toggled, will show stations that are down
|
|
||||||
-h (or none)
|
|
||||||
This help message
|
|
||||||
```
|
|
||||||
### Examples
|
|
||||||
```
|
|
||||||
greg.gauthier@C02DRPKUMD6M $ gostations -c "United Kingdom" -t "news" -n "LBC"
|
|
||||||
...Radio Menu...
|
|
||||||
1) LBC London (London stream) AAC AAC+ 0 http://media-sov.musicradio.com:80/LBCLondon
|
|
||||||
2) LBC London (London stream) MP3 MP3 48 http://media-ice.musicradio.com/LBCLondonMP3Low
|
|
||||||
3) LBC London (National stream) MP3 48 http://media-ice.musicradio.com/LBCUKMP3Low
|
|
||||||
4) LBC London News AAC 48 http://media-ice.musicradio.com/LBC1152.m3u
|
|
||||||
5) LBC UK AAC 48 http://media-ice.musicradio.com/LBCUK
|
|
||||||
6) *Quit
|
|
||||||
What is your choice?
|
|
||||||
```
|
|
||||||
```
|
|
||||||
greg.gauthier@C02DRPKUMD6M $ gostations -c "Gambia"
|
|
||||||
...Radio Menu...
|
|
||||||
1) Choice FM MP3 128 http://uk3-pn.webcast-server.net/8276/stream.mp3
|
|
||||||
2) *Quit
|
|
||||||
What is your choice?
|
|
||||||
```
|
|
||||||
```
|
|
||||||
greg.gauthier@C02DRPKUMD6M $ gostations -t "chicago,classical"
|
|
||||||
...Radio Menu...
|
|
||||||
1) WFMT 98.7 Chicago, IL (MP3) MP3 0 http://stream.wfmt.com/main-mp3
|
|
||||||
2) *Quit
|
|
||||||
What is your choice?
|
|
||||||
```
|
|
||||||
When you want to play, you just choose an entry from the menu and hit enter. Your selected stream player will begin playing, and its output will be seen on the console:
|
|
||||||
```
|
|
||||||
greg.gauthier@C02DRPKUMD6M $ gostations -s "Illinois" -t "classical"
|
|
||||||
...Radio Menu...
|
|
||||||
1) Ancient Faith Radio AAC+ 96 https://ancientfaith.streamguys1.com/music
|
|
||||||
2) Lutheran Public Radio - Collinsville, IL AAC+ 0 http://lpr.streamguys1.com/lpr-aac
|
|
||||||
3) Majesty Radio MP3 128 http://primary.moodyradiostream.org/majesty.mp3
|
|
||||||
4) WFMT 98.7 Chicago, IL (AAC) AAC 256 http://wowza.wfmt.com/live/smil:wfmt.smil/playlist.m3u8
|
|
||||||
5) WFMT 98.7 Chicago, IL (MP3) MP3 0 http://stream.wfmt.com/main-mp3
|
|
||||||
6) WNIU 90.5 Northern Public Radio Classica MP3 128 http://peace.str3am.com:6840/live-128k.mp3
|
|
||||||
7) WUIS-HD2 NPR Illinois Classic - Springfi MP3 96 http://war.str3am.com:7780/WUISRIS-2
|
|
||||||
8) WVIK MP3 0 https://wvik.streamguys1.com//live.mp3
|
|
||||||
9) *Quit
|
|
||||||
What is your choice?
|
|
||||||
5
|
|
||||||
Streaming: WFMT 98.7 Chicago, IL (MP3) MP3 0 http://stream.wfmt.com/main-mp3
|
|
||||||
(+) Audio --aid=1 (mp3 2ch 44100Hz)
|
|
||||||
AO: [coreaudio] 44100Hz stereo 2ch floatp
|
|
||||||
A: 00:00:00 / 00:00:06 (14%) Cache: 5.5s/195KB
|
|
||||||
File tags:
|
|
||||||
icy-title: Steiner - Treasure of the Sierra Madre (1948) - - - Centaur
|
|
||||||
A: 00:00:23 / 00:00:46 (49%) Cache: 23s/825KB
|
|
||||||
```
|
|
||||||
**NOTE:** If you are using `mpv` and you are on a Mac with a touchbar, and Catalina or better, you will see this error message:
|
|
||||||
```
|
|
||||||
2021-03-17 10:51:41.328 mpv[40610:6351061] This NSLayoutConstraint is being configured with a constant that exceeds
|
|
||||||
internal limits. A smaller value will be substituted, but this problem should be fixed. Break
|
|
||||||
on BOOL _NSLayoutConstraintNumberExceedsLimit(void) to debug. This will be logged only once. This may break in the future.
|
|
||||||
```
|
|
||||||
This is due to an issue between `mpv` and Apple at the moment, regarding the creation of `mpv` touchbar controls, and can be ignored.
|
|
||||||
|
|
||||||
While you are listening, all the normal stdin controls for `mpv` should work properly. So, `9` will lover the volume, `0` will raise the volume, and `m` will mute. To quit, type `q`. When you do, you'll automatically be delivered back to your original menu:
|
After installation, just run `gostations`. On first launch it creates a default `radiostations.ini` under `$XDG_CONFIG_HOME/gostations/` (usually `~/.config/gostations/radiostations.ini`) if none exists.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### TUI (default)
|
||||||
|
`gostations` (no arguments) launches the modern Bubble Tea UI:
|
||||||
|
|
||||||
|
- If you have any **favorites**, they are loaded first as the initial list (title: "Your Favorites"; entries marked ★).
|
||||||
|
- Otherwise a broad default search is performed against radio-browser.info (title includes "new TUI • ★ = favorite").
|
||||||
|
- Type to filter the visible list (filter activates automatically).
|
||||||
|
- While filtering, press **Enter** to perform a fresh server-side search (replaces the list; favorites still get ★).
|
||||||
|
- **f** / **F** — toggle favorite (★) on the selected station.
|
||||||
|
- Arrow keys / vim keys — navigate.
|
||||||
|
- **Enter** on a station — switch to the dedicated playback view.
|
||||||
|
- **q** or **Ctrl+C** — quit.
|
||||||
|
|
||||||
|
### Playback View
|
||||||
|
A compact, Winamp-inspired screen:
|
||||||
|
- Large "NOW PLAYING" viewer area (dark background + green text) showing live streamed metadata (station + song titles delivered over mpv JSON IPC).
|
||||||
|
- A vertical volume bar to the right of the metadata (dark gray background, green fill from the bottom; same height as the viewer; small gap).
|
||||||
|
- Keyboard-driven on-screen controls:
|
||||||
|
- `←` / `→` (or `h`/`l`) — skip back/forward.
|
||||||
|
- `↑` / `↓` — volume up/down.
|
||||||
|
- `m` / `M` — mute / unmute.
|
||||||
|
- `Space` or `p` / `P` — play / pause.
|
||||||
|
- `s` / `S` / `x` / `X` — stop playback and return to the station list.
|
||||||
|
- `q` quits the whole app.
|
||||||
|
|
||||||
|
Playback runs in the background; the TUI stays responsive.
|
||||||
|
|
||||||
|
### CLI subcommands (scripting)
|
||||||
```
|
```
|
||||||
(+) Audio --aid=1 (mp3 2ch 44100Hz)
|
gostations find [-n name] [-c country] [-s state] [-t tags] [-x] [-j]
|
||||||
AO: [coreaudio] 44100Hz stereo 2ch floatp
|
gostations play [-n name] [-c country] [-s state] [-t tags] [-x] [url]
|
||||||
A: 00:00:00 / 00:00:06 (14%) Cache: 5.5s/195KB
|
gostations fav list | add | del ...
|
||||||
File tags:
|
gostations -v
|
||||||
icy-title: Steiner - Treasure of the Sierra Madre (1948) - - - Centaur
|
gostations --legacy # force the classic wmenu UI (temporary)
|
||||||
|
|
||||||
A: 00:05:52 / 00:06:16 (94%) Cache: 23s/824KB
|
|
||||||
File tags:
|
|
||||||
icy-title: Korngold, Erich Wolfgang - The Sea Wolf film music - - - Koch
|
|
||||||
A: 00:07:42 / 00:08:06 (95%) Cache: 23s/827KB
|
|
||||||
|
|
||||||
Exiting... (Quit)
|
|
||||||
[]
|
|
||||||
1) Ancient Faith Radio AAC+ 96 https://ancientfaith.streamguys1.com/music
|
|
||||||
2) Lutheran Public Radio - Collinsville, IL AAC+ 0 http://lpr.streamguys1.com/lpr-aac
|
|
||||||
3) Majesty Radio MP3 128 http://primary.moodyradiostream.org/majesty.mp3
|
|
||||||
4) WFMT 98.7 Chicago, IL (AAC) AAC 256 http://wowza.wfmt.com/live/smil:wfmt.smil/playlist.m3u8
|
|
||||||
5) WFMT 98.7 Chicago, IL (MP3) MP3 0 http://stream.wfmt.com/main-mp3
|
|
||||||
6) WNIU 90.5 Northern Public Radio Classica MP3 128 http://peace.str3am.com:6840/live-128k.mp3
|
|
||||||
7) WUIS-HD2 NPR Illinois Classic - Springfi MP3 96 http://war.str3am.com:7780/WUISRIS-2
|
|
||||||
8) WVIK MP3 0 https://wvik.streamguys1.com//live.mp3
|
|
||||||
9) *Quit
|
|
||||||
What is your choice?
|
|
||||||
```
|
```
|
||||||
To exit the program entirely, choose the __*Quit__ option, or just hit `[ENTER]`
|
|
||||||
|
|
||||||
### Additional Notes:
|
Global search flags (`-n`/`-c`/`-s`/`-t`/`-x`) are accepted by `find`, `play`, and `fav add|del`.
|
||||||
|
|
||||||
1. The ini file sets a bunch of environmental defaults necessary for the program to work. Gostations looks for it on your `XDG_CONFIG_HOME` path. If that path is not set, or the file is not found on the path, a default version of the ini will be generated automatically, called `radiostations.ini`. The default location for the `XDG_CONFIG_HOME` is `$HOME/.config/gostations`, if you need to edit it.
|
- `find` — search and print results (`-j`/`--json` for machine-readable).
|
||||||
2. One of the defaults set in that ini file, is a limit on the number of entries that the program will retrieve from the radio-browser.info api, and the number of entries that will be displayed in the menu. `gostations` isn't really designed to dump the entire radio-browser database to a menu. I've set the limit to 9999 by default, but it could probably be less. Tuning your searches should help improve the experience.
|
- `play` — play the first match (or a direct URL). Uses the player + options from the ini.
|
||||||
3. Speaking of that, there are a number of things to keep in mind when searching:
|
- `fav list` — show your favorites (1-based index, stable sort by name).
|
||||||
* The country search is by country NAME, not CODE. So, "United States" will work, but "US" will not (likewise for "UK")
|
- `fav add` — add by search flags or direct URL.
|
||||||
* if you supply multiple tags in a comma-separated list, you may unintentionally filter out results. Unfortunately, the api at radio-info is such that the tag list you search for, has to be in precisely the order it is returned from the host. So, for example, if you search for "classical,chicago", your search will filter out WFMT, because their tags are "chicago,classical".
|
- `fav del` — remove by 1-based index (from `fav list`), search flags, or direct URL.
|
||||||
* It seems many of the stations put their city in the tag list. So, you can reduce the size of your results by doing something like this: `-c "United States" -t "atlanta"`, which makes more sense for radio stations anyway, for radio stations.
|
|
||||||
|
|
||||||
### TODO
|
Examples:
|
||||||
|
```bash
|
||||||
|
gostations find -c "United Kingdom" -t "news" -j
|
||||||
|
gostations play -c Gambia
|
||||||
|
gostations play http://stream.example.com/radio.mp3
|
||||||
|
gostations fav list
|
||||||
|
gostations fav add -n "WFMT"
|
||||||
|
gostations fav del 3
|
||||||
|
gostations fav del http://...
|
||||||
|
```
|
||||||
|
|
||||||
* Change the precheck, to do ini file validation once, rather than every time a config value is called for.
|
Run `gostations <subcommand> -h` or `gostations -h` for full flag details.
|
||||||
* Add a way to capture favorite selections. Perhaps a preloaded search or something.
|
|
||||||
* Add color or a dashboard to the menu and player.
|
|
||||||
|
|
||||||
|
### Legacy UI
|
||||||
|
Pass `--legacy` to use the old wmenu-based menu. The flag exists "until the new TUI is perfect." Playback now uses the modern player backend even under `--legacy`.
|
||||||
|
|
||||||
.
|
## Configuration
|
||||||
|
|
||||||
|
The ini file is at `$XDG_CONFIG_HOME/gostations/radiostations.ini` (falls back to `~/.config/gostations/radiostations.ini`). A default is generated on first run if missing.
|
||||||
|
|
||||||
|
Notable keys:
|
||||||
|
- `player.command=mpv`
|
||||||
|
- `player.options=--no-video`
|
||||||
|
- `radio_browser.api=...` (point at a mirror if desired)
|
||||||
|
- `menu_items.max=9999`
|
||||||
|
|
||||||
|
Favorites are stored as JSON (`favorites.json`) in the same directory. The TUI prefers loading favorites first when any exist.
|
||||||
|
|
||||||
|
## Develop (for power users & developers)
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
- Go 1.24.2+
|
||||||
|
- `make` (recommended)
|
||||||
|
- `mpv` (for local playback testing)
|
||||||
|
- Optional: `golangci-lint` for `make lint`
|
||||||
|
|
||||||
|
### Common tasks
|
||||||
|
```bash
|
||||||
|
git clone https://repos.gmgauthier.com/gmgauthier/gostations.git
|
||||||
|
cd gostations
|
||||||
|
|
||||||
|
make help # list all targets
|
||||||
|
make build # dev build (version from git describe, ldflags into internal/version + main.version)
|
||||||
|
make install # build + copy to ~/.local/bin/gostations
|
||||||
|
make test-short # fast unit tests (no network, no player required)
|
||||||
|
make test # full suite with -race
|
||||||
|
make test-cover # coverage report in build/
|
||||||
|
make lint
|
||||||
|
make cross # release matrix (linux/amd64+arm64, darwin/amd64+arm64, windows/amd64)
|
||||||
|
```
|
||||||
|
|
||||||
|
See the `Makefile` for the exact ldflags, per-platform `go mod download`, and the `release-notes` helper.
|
||||||
|
|
||||||
|
### Releasing
|
||||||
|
```bash
|
||||||
|
./release.sh v2.0.2
|
||||||
|
# or manually
|
||||||
|
git tag -a v2.0.2 -m "..."
|
||||||
|
git push origin v2.0.2
|
||||||
|
```
|
||||||
|
|
||||||
|
`release.sh` does a clean-tree check, creates the annotated tag, optionally runs `grokkit changelog` (best-effort), and pushes. The Gitea Actions workflow (`.gitea/workflows/release.yml`) then:
|
||||||
|
- Checks out the tag.
|
||||||
|
- Sets up Go 1.24.2 + module cache.
|
||||||
|
- Runs `go mod tidy` + `make cross`.
|
||||||
|
- Packages tarballs + checksums + the two install scripts.
|
||||||
|
- Creates the release (with install instructions in the body) and uploads every asset via the Gitea API using the `RELEASE_TOKEN` secret.
|
||||||
|
|
||||||
|
### Project layout (post-reorg)
|
||||||
|
- `internal/ui/` — Bubble Tea TUI (list + playback view + hint bar + volume bar + polling).
|
||||||
|
- `internal/player/` — `Player` interface + `mpvPlayer` (JSON IPC via unix socket) + legacy exec fallback.
|
||||||
|
- `internal/data/` — favorites (JSON, atomic save, sorted list with stable indices).
|
||||||
|
- `internal/radio/`, `internal/config/` — search + ini handling.
|
||||||
|
- Legacy wmenu code (`radiomenu.go`, `commander.go`, etc.) remains gated behind `--legacy`.
|
||||||
|
- `scripts/` — installers (`.sh` + `.ps1`).
|
||||||
|
- `.gitea/workflows/` — build + release CI.
|
||||||
|
- `Makefile` + `release.sh` drive local builds and the tag-triggered release path.
|
||||||
|
|
||||||
|
The project is WOMM Platinum certified (see badge at the top).
|
||||||
|
|
||||||
|
All the pre-2.0 wmenu screenshots, the old `go mod vendor` instructions, the touchbar error note, and the ancient TODO list have been retired from this document. See git history for the full modernization (TUI, IPC player, favorites + index delete, subcommands, internal/ package reorg, CI/release pipeline, etc.). The `--legacy` flag remains until the TUI is declared "perfect."
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user