RadioGoGo

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

or

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.