<div align="center">
<img src="https://github.com/Hibbins/termr/raw/main/assets/termr_github_banner.png" />
<br />
<h1 align="center">termr</h1>
<p align="center">A simple, fast, and modern terminal radio player.</p>
<p>
<a href="https://github.com/Hibbins/termr/stargazers" target="_blank"><img src="https://img.shields.io/github/stars/Hibbins/termr.svg" alt="GitHub Stars"/></a>
<a href="https://github.com/Hibbins/termr/forks" target="_blank"><img src="https://img.shields.io/github/forks/Hibbins/termr.svg" alt="GitHub Forks"/></a>
<a href="https://github.com/Hibbins/termr/releases" target="_blank"><img src="https://img.shields.io/github/release/Hibbins/termr.svg" alt="Releases"/></a>
<a href="https://aur.archlinux.org/packages/termr" target="_blank"><img src="https://img.shields.io/aur/version/termr" alt="AUR Version"/></a>
<a href="https://github.com/Hibbins/termr/issues" target="_blank"><img src="https://img.shields.io/github/issues/Hibbins/termr.svg" alt="GitHub Issues"/></a>
<a href="https://github.com/Hibbins/termr/releases" target="_blank"><img src="https://img.shields.io/github/downloads/Hibbins/termr/total.svg" alt="Package Downloads"/></a>
<a href="https://github.com/Hibbins/termr/blob/master/LICENSE" target="_blank"><img src="https://img.shields.io/github/license/Hibbins/termr.svg" alt="License"/></a>
</p>
</div>
<br />
<div align="center">
<a href="https://ko-fi.com/M4M615Y5RB" target="_blank"><img width="200" src="https://github.com/user-attachments/assets/91dc5e85-3b94-4424-920c-497b32fc30a4" alt='Buy Me a Coffee at ko-fi.com' /></a>
</div>
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Linux](#linux)
- [Arch Linux (AUR)](#arch-linux-aur)
- [Ubuntu/Debian](#ubuntudebian)
- [From PyPI](#from-pypi)
- [From Source (Universal)](#from-source-universal)
- [Requirements](#requirements)
- [Usage Guide](#usage-guide)
- [Main Functions](#main-functions)
- [Browse Stations](#browse-stations)
- [Search](#search)
- [Favorites](#favorites)
- [Themes](#themes)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Configuration](#configuration)
- [Settings](#settings)
- [Options](#options)
- [Volume](#volume)
- [Theme](#theme)
- [Max Stations](#max-stations)
- [Default Sort](#default-sort)
- [API Timeout](#api-timeout)
- [Autoplay](#autoplay)
- [Troubleshooting](#troubleshooting)
## Features
- Fast, modern TUI radio player built with [Textual](https://github.com/Textualize/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)
```bash
# With pacman
sudo pacman -S termr
# With yay
yay -S termr
# Or clone and build manually
git clone https://aur.archlinux.org/termr.git
cd termr
makepkg -si
```
#### Ubuntu/Debian
```bash
# Download and install
wget https://github.com/Hibbins/termr/releases/download/v1.1.0/termr_1.1.0-1_all.deb
sudo apt install ./termr_1.1.0-1_all.deb
```
#### From PyPI
```bash
pip install termr
```
#### From Source (Universal)
```bash
# 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`:
```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"
```bash
chmod +x termr
```
---
Enjoy listening!
If you like the project, consider starring it on GitHub or buying me a coffee!
---
Raw data
{
"_id": null,
"home_page": null,
"name": "termr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "radio, terminal, tui, music, streaming",
"author": null,
"author_email": "Sebastian Westberg <sebastian@westberg.io>",
"download_url": "https://files.pythonhosted.org/packages/cf/85/44eafc8236456dd4b44faec5f9c985eb0c2c96f9138a2c29a8f10940f25c/termr-1.1.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://github.com/Hibbins/termr/raw/main/assets/termr_github_banner.png\" />\n <br />\n <h1 align=\"center\">termr</h1>\n <p align=\"center\">A simple, fast, and modern terminal radio player.</p>\n <p>\n <a href=\"https://github.com/Hibbins/termr/stargazers\" target=\"_blank\"><img src=\"https://img.shields.io/github/stars/Hibbins/termr.svg\" alt=\"GitHub Stars\"/></a>\n <a href=\"https://github.com/Hibbins/termr/forks\" target=\"_blank\"><img src=\"https://img.shields.io/github/forks/Hibbins/termr.svg\" alt=\"GitHub Forks\"/></a>\n <a href=\"https://github.com/Hibbins/termr/releases\" target=\"_blank\"><img src=\"https://img.shields.io/github/release/Hibbins/termr.svg\" alt=\"Releases\"/></a>\n <a href=\"https://aur.archlinux.org/packages/termr\" target=\"_blank\"><img src=\"https://img.shields.io/aur/version/termr\" alt=\"AUR Version\"/></a>\n <a href=\"https://github.com/Hibbins/termr/issues\" target=\"_blank\"><img src=\"https://img.shields.io/github/issues/Hibbins/termr.svg\" alt=\"GitHub Issues\"/></a>\n <a href=\"https://github.com/Hibbins/termr/releases\" target=\"_blank\"><img src=\"https://img.shields.io/github/downloads/Hibbins/termr/total.svg\" alt=\"Package Downloads\"/></a>\n <a href=\"https://github.com/Hibbins/termr/blob/master/LICENSE\" target=\"_blank\"><img src=\"https://img.shields.io/github/license/Hibbins/termr.svg\" alt=\"License\"/></a>\n </p>\n</div>\n<br />\n<div align=\"center\">\n <a href=\"https://ko-fi.com/M4M615Y5RB\" target=\"_blank\"><img width=\"200\" src=\"https://github.com/user-attachments/assets/91dc5e85-3b94-4424-920c-497b32fc30a4\" alt='Buy Me a Coffee at ko-fi.com' /></a>\n</div>\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n - [Linux](#linux)\n - [Arch Linux (AUR)](#arch-linux-aur)\n - [Ubuntu/Debian](#ubuntudebian)\n - [From PyPI](#from-pypi)\n - [From Source (Universal)](#from-source-universal)\n - [Requirements](#requirements)\n- [Usage Guide](#usage-guide)\n - [Main Functions](#main-functions)\n - [Browse Stations](#browse-stations)\n - [Search](#search)\n - [Favorites](#favorites)\n - [Themes](#themes)\n - [Keyboard Shortcuts](#keyboard-shortcuts)\n- [Configuration](#configuration)\n - [Settings](#settings)\n - [Options](#options)\n - [Volume](#volume)\n - [Theme](#theme)\n - [Max Stations](#max-stations)\n - [Default Sort](#default-sort)\n - [API Timeout](#api-timeout)\n - [Autoplay](#autoplay)\n- [Troubleshooting](#troubleshooting)\n\n## Features\n\n- Fast, modern TUI radio player built with [Textual](https://github.com/Textualize/textual)\n- Browse, search, and play thousands of internet radio stations\n- Add and manage favorites\n- Multiple color themes\n- Volume control, pause/resume, and stop\n- Minimal dependencies, easy to install\n- Configurable and hackable\n\n## Installation\n\n### Linux\n\n#### Arch Linux (AUR)\n\n```bash\n# With pacman\nsudo pacman -S termr\n\n# With yay\nyay -S termr\n\n# Or clone and build manually\ngit clone https://aur.archlinux.org/termr.git\ncd termr\nmakepkg -si\n```\n\n#### Ubuntu/Debian\n\n```bash\n# Download and install\nwget https://github.com/Hibbins/termr/releases/download/v1.1.0/termr_1.1.0-1_all.deb\nsudo apt install ./termr_1.1.0-1_all.deb\n```\n\n#### From PyPI\n\n```bash\npip install termr\n```\n\n#### From Source (Universal)\n\n```bash\n# Clone and install from source\ngit clone https://github.com/Hibbins/termr.git\ncd termr\npip install .\n\n# Or install directly from GitHub\npip install git+https://github.com/Hibbins/termr.git\n```\n\n#### Requirements\n- VLC Media Player (with cvlc command)\n\n## Usage Guide\n\n### Main Functions\n\n#### Browse Stations\nNavigate the main list to discover and play radio stations from around the world.\n\n#### Search\nPress `s` to search for stations by name, genre, country, etc.\n\n#### Favorites\nPress `f` to add/remove the selected station to/from your favorites. Access your favorites from the main menu.\n\n#### Themes\nSwitch between multiple color themes from the menu for the best TUI experience.\n\n#### Keyboard Shortcuts\n\n| Key | Action |\n|-------------|------------------------------|\n| `q` | Quit |\n| `h` | Home |\n| `s` | Search |\n| `f` | Add/Remove Favorite |\n| `+` / `-` | Volume Up/Down |\n| `p` | Pause/Resume |\n| `x` | Stop |\n| `r` | Refresh station list |\n| `escape` | Back |\n| `enter` | Play selected station |\n\n## Configuration\n\nThe application automatically creates configuration files in `~/.config/termr/`:\n\n- `favorites.json` - Favorite stations\n- `settings.json` - Application settings\n\n### Settings\n\nYou can edit `~/.config/termr/settings.json`:\n\n```json\n{\n \"max_stations\": 100,\n \"default_sort\": \"clickcount\",\n \"auto_play\": false,\n \"volume\": 100,\n \"theme\": \"default\",\n \"last_station\": null,\n \"api_timeout\": 10\n}\n```\n\n### Options\n\n#### Volume\nDefault playback volume (0-200).\n\n#### Theme\nChoose your preferred color theme.\n\n#### Max Stations\nSet the maximum number of stations to load.\n\n#### Default Sort\nChoose how stations are sorted (e.g., by popularity).\n\n#### API Timeout\nSet the timeout for API requests.\n\n#### Autoplay\nIf enabled, termr will automatically start playing the last played station on launch.\n\n## Troubleshooting\n\n### \"VLC not found\"\nInstall VLC according to the instructions above.\n\n### \"Package not found\"\nCheck that you are using the correct package manager for your system.\n\n### \"Permission denied\"\n```bash\nchmod +x termr\n```\n\n---\n\nEnjoy listening! \nIf you like the project, consider starring it on GitHub or buying me a coffee!\n\n---\n",
"bugtrack_url": null,
"license": null,
"summary": "Terminal-based radio player with TUI",
"version": "1.1.0",
"project_urls": {
"Documentation": "https://github.com/Hibbins/termr#readme",
"Homepage": "https://github.com/Hibbins/termr",
"Issues": "https://github.com/Hibbins/termr/issues",
"Repository": "https://github.com/Hibbins/termr"
},
"split_keywords": [
"radio",
" terminal",
" tui",
" music",
" streaming"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3fad9b0b29def82a6e12aa525f59dca9da113af1777a95f6617f9adbca0214a6",
"md5": "e3f9b0eea0da33cc4dc44aab93fb52b6",
"sha256": "911c39da50e169d5307e1e6b6757d21d58516e3efb0beffad132a05c48642f03"
},
"downloads": -1,
"filename": "termr-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3f9b0eea0da33cc4dc44aab93fb52b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20826,
"upload_time": "2025-07-13T09:30:46",
"upload_time_iso_8601": "2025-07-13T09:30:46.189266Z",
"url": "https://files.pythonhosted.org/packages/3f/ad/9b0b29def82a6e12aa525f59dca9da113af1777a95f6617f9adbca0214a6/termr-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cf8544eafc8236456dd4b44faec5f9c985eb0c2c96f9138a2c29a8f10940f25c",
"md5": "6ecb69b760dece76639cff20b8c41579",
"sha256": "62a3b6a7d608cf2f134eac1bf49f1c597589f079d217eaf56b613f000ed0d159"
},
"downloads": -1,
"filename": "termr-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6ecb69b760dece76639cff20b8c41579",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 23349,
"upload_time": "2025-07-13T09:30:47",
"upload_time_iso_8601": "2025-07-13T09:30:47.399506Z",
"url": "https://files.pythonhosted.org/packages/cf/85/44eafc8236456dd4b44faec5f9c985eb0c2c96f9138a2c29a8f10940f25c/termr-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 09:30:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hibbins",
"github_project": "termr#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "textual",
"specs": [
[
">=",
"0.40.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
}
],
"lcname": "termr"
}