gostations/README.md

GoStations

console based radio station selector and player

WOMM Platinum Certified (per WOMM-STD-001:2026)

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

• OS: Linux or macOS (Windows via the installers or WSL)
• Recommended player: mpv (with --no-video). Alternatives (mpg123, mplayer, etc.) can be configured in the ini file.
• For building from source: Go 1.24.2+

Install (for normal users)

The easiest way is the one-liner installer attached to each release:

Linux / macOS

curl -L https://repos.gmgauthier.com/gmgauthier/gostations/releases/download/v2.0.1/gostations-install.sh \
  | VERSION=2.0.1 bash

Windows (PowerShell) / macOS / Linux with PowerShell

irm https://repos.gmgauthier.com/gmgauthier/gostations/releases/download/v2.0.1/gostations-install.ps1 | iex

The installer:

• Detects your OS and architecture.
• Downloads the matching gostations-OS-ARCH-vX.Y.Z.tar.gz (verifies checksum when possible).
• Installs the binary to ~/.local/bin/gostations (.exe on Windows).
• Prints PATH advice if needed and runs gostations -v.

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)

gostations find   [-n name] [-c country] [-s state] [-t tags] [-x] [-j]
gostations play   [-n name] [-c country] [-s state] [-t tags] [-x] [url]
gostations fav    list | add | del ...
gostations -v
gostations --legacy          # force the classic wmenu UI (temporary)

Global search flags (-n/-c/-s/-t/-x) are accepted by find, play, and fav add|del.

• find — search and print results (-j/--json for machine-readable).
• play — play the first match (or a direct URL). Uses the player + options from the ini.
• fav list — show your favorites (1-based index, stable sort by name).
• fav add — add by search flags or direct URL.
• fav del — remove by 1-based index (from fav list), search flags, or direct URL.

Examples:

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://...

Run gostations <subcommand> -h or gostations -h for full flag details.

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

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

./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."