GitHub - zsh-ncursed/somafm_tui: Somafm console player

SomaFM TUI Player is a modern terminal application for listening to SomaFM — the legendary internet radio with over 40 unique channels.

The app combines a minimalist interface, rich features, and low resource consumption, making it ideal for terminal-based workflows.

🌟 Features

Core Features

• 📻 40+ Radio Channels — Access all SomaFM channels directly from your terminal
• 🎵 Track Metadata — Real-time display of artist and track title
• ❤️ Favorites — Save favorite channels with local persistence
• 🎨 Color Themes — 20+ built-in themes (dark and light)
• 🔊 Volume Control — Adjust volume and mute toggle
• ⏱ Sleep Timer — Auto-shutdown with configurable timer
• 🔍 Search — Quick channel search by name and description
• 📊 Usage-Based Sorting — Channels sorted by listening history
• 🔍 Favorites-Only Mode — Filter channel list to show only favorites
• 💚 Add Track to Favorites — Save currently playing track while listening
• 🙈 Toggle Hotkey Hints — Hide/show the bottom footer with keybindings
• 👥 Listener Count — Display number of listeners per channel
• 🎚 Bitrate Selection — Choose stream quality per channel

System Integration

• 🎧 MPRIS/D-Bus — Linux media keys integration (play/pause/next/previous)
• 🖥 System Tray — System tray support (via compatible environments)
• ⌨️ Vim Navigation — j/k key navigation for Vim users
• 📦 AUR Package — Easy installation on Arch Linux via AUR

📦 Installation

Arch Linux (Recommended)

Install from AUR (Arch User Repository):

paru -S somafm_tui
# or
yay -S somafm_tui

Manual installation from AUR:

git clone https://aur.archlinux.org/somafm_tui.git
cd somafm_tui
makepkg -si

After installation, run the app with:

Installation from Source

# Clone the repository
git clone https://github.com/zsh-ncursed/somafm_tui.git
cd somafm_tui

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python -m somafm_tui

Installation via pip

Install directly from PyPI (when available):

Or install from the repository:

pip install git+https://github.com/zsh-ncursed/somafm_tui.git

After pip installation, the somafm-tui command will be available in your PATH.

Installation via pipx

pipx installs Python CLI applications in isolated environments. Recommended way to install somafm-tui without affecting system packages:

# Install pipx (if not already installed)
pip install pipx
# or on Arch Linux: sudo pacman -S python-pipx

# Install somafm-tui
pipx install somafm-tui

After installation, run with:

To update:

Note: mpv must still be installed on your system via your package manager (see Dependencies).

Shell Scripts

Quick launch using provided scripts:

# Fish shell
./somafm.fish

# Bash/Zsh
./somafm.sh

Dependencies

• Python 3.8+
• MPV — Media player for stream playback
• python-requests — HTTP client for API requests
• python-mpv — MPV Python bindings
• python-dbus-next — D-Bus integration for MPRIS (optional)

Installing Dependencies on Different Distributions

Arch Linux:

sudo pacman -S python mpv python-requests python-mpv python-dbus-next

Ubuntu/Debian:

sudo apt-get install python3 python3-pip mpv libmpv-dev
pip install requests mpv dbus-next

Fedora:

sudo dnf install python3 python3-pip mpv mpv-libs
pip install requests mpv dbus-next

⌨️ Controls

Interactive Mode

Launch the application:

Navigation

Playback

Command-Line Interface

The application supports various CLI arguments for automation and quick actions:

# Show help
somafm-tui --help

# List all available channels
somafm-tui --list-channels

# Search for channels
somafm-tui --search "drone"

# Show favorite channels
somafm-tui --favorites

# List available themes
somafm-tui --list-themes

# Play specific channel with custom settings
somafm-tui --play dronezone --volume 70 --theme dracula

# Set sleep timer from command line
somafm-tui --sleep 30

# Disable MPRIS integration
somafm-tui --no-dbus

# Combine multiple options
somafm-tui -p groovesalad -v 50 -t monochrome -s 60

MPRIS (Media Keys)

When D-Bus support is enabled (dbus_allowed: true in config), the app responds to system media keys:

• Play/Pause — Toggle playback
• Next — Next channel
• Previous — Previous channel
• Stop — Stop playback

⚙️ Configuration

Config File

Configuration is stored in ~/.somafm_tui/somafm.cfg

# Configuration file for SomaFM TUI Player
#
# theme: Color theme
# dbus_allowed: Enable MPRIS/D-Bus support for media keys (true/false)
# dbus_send_metadata: Send channel metadata over D-Bus (true/false)
# dbus_send_metadata_artworks: Send channel picture with metadata over D-Bus (true/false)
# dbus_cache_metadata_artworks: Cache channel picture locally for D-Bus (true/false)
# volume: Default volume (0-100)
#
[somafm]
theme = default
dbus_allowed = false
dbus_send_metadata = false
dbus_send_metadata_artworks = false
dbus_cache_metadata_artworks = true
volume = 100

Configuration Examples

Basic setup with custom volume:

[somafm]
theme = dracula
volume = 80
dbus_allowed = false

Full MPRIS integration (Linux desktop):

[somafm]
theme = github-dark
dbus_allowed = true
dbus_send_metadata = true
dbus_send_metadata_artworks = true
dbus_cache_metadata_artworks = true
volume = 70

Minimal configuration (no D-Bus, default theme):

[somafm]
theme = default
dbus_allowed = false
volume = 100

Available Themes

Run somafm-tui --list-themes to see all available themes:

Dark Themes

Light Themes

See themes.json for complete color definitions.

Enabling MPRIS

For Linux media keys integration, set:

dbus_allowed = true
dbus_send_metadata = true

The app will then appear in media control systems (GNOME, KDE, etc.)

📁 Data Structure

Directories

Data Formats

Favorites (channel_favorites.json):

["dronezone", "beatblender", "groovesalad"]

History (channel_usage.json):

{
  "dronezone": 1709481600,
  "beatblender": 1709395200
}

🔧 Troubleshooting

Error: "MPV player is not installed"

Ensure MPV is installed on your system:

# Check installation
mpv --version

# Install (Arch Linux)
sudo pacman -S mpv

# Install (Ubuntu/Debian)
sudo apt-get install mpv

# Install (Fedora)
sudo dnf install mpv

Error: "Failed to fetch channels"

Check your internet connection and SomaFM API availability:

# Test API connectivity
curl https://api.somafm.com/channels.json

# Check DNS resolution
ping api.somafm.com

# If using a firewall, ensure outbound HTTPS (port 443) is allowed

Solutions:

1. Check your internet connection
2. Verify SomaFM API is accessible: curl -I https://api.somafm.com/channels.json
3. If behind a proxy, set environment variables:

   export HTTP_PROXY=http://proxy:port
   export HTTPS_PROXY=https://proxy:port

4. Clear channel cache and retry:

   rm -rf /tmp/.somafmtmp/cache/channels.json
   somafm-tui

Error: "No channel playing" or playback issues

1. Check stream URL availability:

   # Test stream connectivity
   mpv --really-verbose "https://ice1.somafm.com/dronezone-128-mp3"

2. Reset configuration:

   rm ~/.somafm_tui/somafm.cfg
   somafm-tui

3. Check audio output:

   • Ensure system volume is not muted
   • Verify audio device is selected correctly in MPV

Emojis Display Incorrectly

The app automatically uses ASCII symbols in terminals without Unicode support. To force ASCII, ensure TERM is set correctly:

export TERM=xterm-256color

Add to your shell configuration (~/.bashrc or ~/.zshrc):

export TERM=xterm-256color

MPRIS Not Working

1. Ensure dbus_allowed = true in config
2. Verify python-dbus-next is installed:
3. Check D-Bus service is running:

   systemctl --user status dbus

4. Verify app appears in media controllers:
5. Restart the application after configuration changes

Sleep Timer Not Working

1. Maximum sleep timer is 480 minutes (8 hours)
2. Check if timer is active: look for ⏱ MM:SS in bottom right corner
3. Cancel and re-set timer if needed:
   • Press s to open sleep overlay
   • Enter minutes (1-480)
   • Press Enter to confirm

High CPU Usage

1. Disable MPRIS if not needed:

2. Reduce cache update frequency (if applicable)

3. Check for background processes:

Logs and Debugging

Enable verbose logging:

View logs:

# Real-time log viewing
tail -f /tmp/.somafmtmp/somafm.log

# Last 50 lines
tail -n 50 /tmp/.somafmtmp/somafm.log

Common log messages:

• Using cached channels — Cache is working correctly
• Timeout fetching — Network issues, retrying automatically
• MPRIS service disabled — D-Bus integration is off (expected if dbus_allowed = false)

📊 Screenshots

The TUI supports a wide range of themes. Here are a few highlights.

Themes

Ayu Dark	Solarized Dark

GitHub Dark	Monochrome Dark

Catppuccin	Catppuccin (theme change toast)

Default Dark	Solarized Light

Tokyo Night

Browsing & Playback (Ayu Dark)

Ayu Dark	Ayu Dark

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md before submitting pull requests.

Reporting Bugs

• Check existing issues first
• Include app version (somafm-tui --version or from PKGBUILD)
• Attach logs from /tmp/.somafmtmp/somafm.log

Feature Requests

• Describe the desired functionality
• Explain how it improves user experience

📄 License

Distributed under the MIT License. See LICENSE for details.

🙏 Acknowledgments

• SomaFM — For amazing radio and open API
• python-mpv — For excellent MPV Python bindings
• dbus-next — For modern D-Bus library for Python

📬 Contact

• GitHub: zsh-ncursed/somafm_tui
• AUR: somafm_tui
• Email: zsh.ncursed@gmail.com

🗺 Roadmap

• Listening history export
• Last.fm integration (scrobbling)
• Support for other streaming services
• GUI settings via ncurses dialogs

Made with ❤️ for quality internet radio lovers