gostations/README.md

# GoStations
### console based radio station selector and player

<p align="center">
  <a href="https://repos.gmgauthier.com/gmgauthier/womm-certification">
    <img src="assets/womm-platinum.svg" alt="WOMM Platinum Certified" width="180"/>
  </a>
</p>

**WOMM Platinum Certified** (per [WOMM-STD-001:2026](https://repos.gmgauthier.com/gmgauthier/womm-certification))

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

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
```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.

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

--- 

The project is WOMM Platinum certified (see badge at the top).