termr

A simple, fast, and modern terminal radio player.

Table of Contents

• Features
• Installation
  • Linux
    • Arch Linux (AUR)
    • Ubuntu/Debian
    • From PyPI
    • From Source (Universal)
    • Requirements
• Usage Guide
  • Main Functions
    • Browse Stations
    • Search
    • Favorites
    • Themes
    • Keyboard Shortcuts
• Configuration
  • Settings
  • Options
    • Volume
    • Theme
    • Max Stations
    • Default Sort
    • API Timeout
    • Autoplay
• Troubleshooting

Features

• Fast, modern TUI radio player built with Textual
• Browse, search, and play thousands of internet radio stations
• Add and manage favorites
• Multiple color themes
• Volume control, pause/resume, and stop
• Minimal dependencies, easy to install
• Configurable and hackable

Installation

Linux

Arch Linux (AUR)

# With yay
yay -S termr

# Or clone and build manually
git clone https://aur.archlinux.org/termr.git
cd termr
makepkg -si

Ubuntu/Debian

# Download and install
wget https://github.com/Hibbins/termr/releases/download/v1.2.0/termr_1.2.0-1_all.deb
sudo apt install ./termr_1.2.0-1_all.deb

From PyPI

pip install termr

From Source (Universal)

# Clone and install from source
git clone https://github.com/Hibbins/termr.git
cd termr
pip install .

# Or install directly from GitHub
pip install git+https://github.com/Hibbins/termr.git

Requirements

• VLC Media Player (with cvlc command)

Usage Guide

Main Functions

Browse Stations

Navigate the main list to discover and play radio stations from around the world.

Search

Press s to search for stations by name, genre, country, etc.

Favorites

Press f to add/remove the selected station to/from your favorites. Access your favorites from the main menu.

Themes

Switch between multiple color themes from the menu for the best TUI experience.

Keyboard Shortcuts

Key	Action
q	Quit
h	Home
s	Search
f	Add/Remove Favorite
+ / -	Volume Up/Down
p	Pause/Resume
x	Stop
r	Refresh station list
escape	Back
enter	Play selected station

Configuration

The application automatically creates configuration files in ~/.config/termr/:

• favorites.json - Favorite stations
• settings.json - Application settings

Settings

You can edit ~/.config/termr/settings.json:

{
  "max_stations": 100,
  "default_sort": "clickcount",
  "auto_play": false,
  "volume": 100,
  "theme": "default",
  "last_station": null,
  "api_timeout": 10
}

Options

Volume

Default playback volume (0-200).

Theme

Choose your preferred color theme.

Max Stations

Set the maximum number of stations to load.

Default Sort

Choose how stations are sorted (e.g., by popularity).

API Timeout

Set the timeout for API requests.

Autoplay

If enabled, termr will automatically start playing the last played station on launch.

Troubleshooting

"VLC not found"

Install VLC according to the instructions above.

"Package not found"

Check that you are using the correct package manager for your system.

"Permission denied"

chmod +x termr

---

Enjoy listening!
If you like the project, consider starring it on GitHub or buying me a coffee!

---