RadioGoGo

February 3, 2026 · View on GitHub

A terminal UI for browsing and playing internet radio stations. Built with Go using BubbleTea and the RadioBrowser API.

Features

Search stations by name, country, language, or codec
Browse results in a navigable table
Stream playback via ffplay
Real-time volume control during playback
Record streams to disk via ffmpeg
Customizable color themes and keybindings
Bookmark favorite stations for quick access
Hide unwanted stations from search results
Cross-platform (Linux, macOS, Windows)
Multi-language UI (English, German, Greek, Spanish, Italian, Japanese, Portuguese, Russian, Chinese)

How It Works

RadioGoGo uses FFmpeg tools for audio:

Playback: ffplay handles audio streaming. Volume changes restart the player with the new level (with debouncing to avoid rapid restarts).
Recording: ffmpeg runs alongside ffplay when recording. Both connect to the stream independently—audio keeps playing while the stream saves to disk.

The header shows two status indicators:

(●) play — green when playing, yellow during volume restart, gray when idle
(●) recording — red when recording, gray when idle

Keyboard Shortcuts

Key	Action
`Enter`	Play selected station
`Ctrl+K`	Stop playback
`9` / `0`	Volume down / up
`r`	Toggle recording (while playing)
`↑` / `↓` or `j` / `k`	Navigate station list
`b`	Toggle bookmark on selected station
`B`	View bookmarks / back to stations
`h`	Hide station from results
`H`	Manage hidden stations
`s`	Back to search
`L`	Cycle UI language (search screen)
`q`	Quit

Most keys are customizable via config (see Custom Keybindings below). Keys that cannot be changed: arrow keys, Enter, Tab, Escape, and common editing keys (Backspace, Delete, Ctrl+C, etc.).

Recording

Press r while a station is playing to start recording. The file saves to your current directory with the format:

station_name-YYYY-MM-DD-HH-MM-SS.codec

For example: bbc_radio_1-2026-01-22-18-32-00.mp3

Press r again to stop recording. The recording continues even if you adjust volume (only the player restarts, not the recorder).

Bookmarks & Hidden Stations

Bookmarks: Press b on any station to bookmark it (⭐ appears next to name). Press B to view all bookmarks. Press B again to return to your search results.

Hidden Stations: Press h to hide a station from search results. Press H to manage hidden stations and unhide them if needed.

Bookmarks and hidden stations persist across sessions.

Installation

Dependencies

You need ffplay for playback. For recording, you also need ffmpeg. Both come with the FFmpeg package.

Windows:

choco install ffmpeg

scoop install ffmpeg

Linux (apt):

sudo apt install ffmpeg

Linux (dnf/Fedora):

sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install ffmpeg

Linux (pacman):

sudo pacman -S ffmpeg

macOS:

brew install ffmpeg

Install RadioGoGo

Via Go:

go install github.com/zi0p4tch0/radiogogo@latest

Make sure $(go env GOPATH)/bin is in your PATH.

Via releases:

Download the binary for your platform from the Releases page.

Available Platforms

OS	Architecture	Filename	Notes
macOS	Apple Silicon (M1/M2/M3)	`darwin_arm64.zip`
	Intel	`darwin_amd64.zip`
Linux	x86 64-bit	`linux_amd64.zip`	Most desktops/servers
	x86 32-bit	`linux_386.zip`	Legacy systems
	ARM64	`linux_arm64.zip`	Pi 3/4/5 (64-bit OS), modern ARM servers
	ARMv7	`linux_armv7.zip`	Pi 2/3/4 (32-bit OS)
	ARMv6	`linux_armv6.zip`	Pi 1, Pi Zero, Pi Zero W
Windows	x64	`windows_amd64.zip`
	x86	`windows_386.zip`

Configuration

Config file location:

Windows: %LOCALAPPDATA%\radiogogo\config.yaml
Linux/macOS: ~/.config/radiogogo/config.yaml

Created automatically on first run.

Theme

theme:
    textColor: '#ffffff'
    primaryColor: '#5a4f9f'
    secondaryColor: '#8b77db'
    tertiaryColor: '#4e4e4e'
    errorColor: '#ff0000'

Language

Set the UI language:

language: en

Available: de (German), el (Greek), en (English), es (Spanish), it (Italian), ja (Japanese), pt (Portuguese), ru (Russian), zh (Chinese)

Press L on the search screen to cycle through languages.

Custom Keybindings

Most keys can be customized. Changes require restarting the app.

keybindings:
  quit: q
  search: s
  record: r
  bookmarkToggle: b
  bookmarksView: B
  hideStation: h
  manageHidden: H
  changeLanguage: L
  volumeDown: "9"
  volumeUp: "0"
  navigateDown: j
  navigateUp: k
  stopPlayback: ctrl+k

Reserved keys (cannot be remapped): arrow keys (up, down, left, right), tab, enter, esc, backspace, delete, pgup, pgdown, home, end, and terminal control keys (ctrl+c, ctrl+z, ctrl+s, ctrl+q, ctrl+l, ctrl+a, ctrl+e, ctrl+u, ctrl+k, ctrl+w, ctrl+d, ctrl+h).

If you set an invalid key or duplicate, the app warns at startup and uses the default for that key.

Example alternate theme:

theme:
    textColor: '#f0e6e6'
    primaryColor: '#c41230'
    secondaryColor: '#e4414f'
    tertiaryColor: '#f58b8d'
    errorColor: '#ff0000'

Troubleshooting

Playback Issues

"FFplay not found" error on startup

Ensure FFmpeg is installed (see Dependencies)
Verify ffplay is in your PATH: run ffplay -version in terminal
On Windows, you may need to restart your terminal after installing FFmpeg

Station takes a while to start playing

Some streams need time to buffer depending on server location and connection
Wait a few seconds for the stream to start
Check if the station works in a browser first

No audio output

Check your system audio settings and output device
Try playing a different station (some may be temporarily offline)
Verify FFplay works: run ffplay -autoexit -nodisp <any audio file>

Station doesn't work at all

Stations go offline or change URLs frequently
RadioBrowser is community-maintained, so some entries may be stale
Try searching for the same station by name to find updated URLs

Recording Issues

Recording button doesn't work

Recording requires ffmpeg installed separately from ffplay
Verify ffmpeg is in your PATH: run ffmpeg -version
Recording only works while a station is actively playing

Recording file is empty or corrupt

Some stations may use codecs or streams that FFmpeg cannot capture
Check write permissions in your current directory
Ensure you have sufficient disk space

Configuration Issues

Config changes not taking effect

Restart the app after editing config.yaml
Check for YAML syntax errors (proper indentation, quotes around special characters)
Invalid keybindings show warnings at startup and fall back to defaults

Terminal too small error

Resize your terminal to at least 115 columns x 29 rows
Use a terminal that supports resizing
Check if your terminal font size is too large

Building from Source

Prerequisites

Go 1.25 or later
FFmpeg (for playback and recording)

Build

# Clone the repository
git clone https://github.com/zi0p4tch0/radiogogo.git
cd radiogogo

# Build
go build -o radiogogo

# Or install to GOPATH/bin
go install

Run Tests

# Run all tests
go test ./...

# Run with verbose output
go test -v ./...

# Run tests for a specific package
go test ./api
go test ./models
go test ./playback

Nix Development Environment

If you use Nix with flakes:

# Enter development shell (provides Go, FFmpeg, Delve, Gopls)
nix develop

# Or with direnv
direnv allow

FAQ

Recording requires ffmpeg?

Yes. Playback only needs ffplay, but recording needs ffmpeg installed and in your PATH.

Mentions

Golang Weekly Issue 481

Contributing

Bug reports, fixes, and feature ideas welcome. For new features, open an issue first to discuss.

License

MIT. See LICENSE.