A modern internet radio player for the terminal and desktop.
FluxTuner combines:
- a fast keyboard-oriented TUI
- an experimental GTK4 desktop GUI
- smart favorites and playlists
- theming support
- modular playback backends
- lightweight live metadata support
into a lightweight application designed for daily use.
Built with Python and focused on speed, usability and modularity.
- Search internet radio stations by name, genre and country
- Modular playback backend support (
mpvandffplay) - Favorites with custom names and tags
- Smart Play by tag or playlist
- Persistent playlists and dynamic tag playlists
- Full theming system with live preview
- Structured table view
- Volume, mute and playback control
- Estimated data usage tracking
- Experimental GTK desktop GUI
- Clean modular architecture
- Live stream metadata display (artist and track when available)
FluxTuner requires:
- Python 3.10+
mpvorffmpeg/ffplay- A terminal emulator with good Unicode support
The GTK desktop GUI currently requires:
- GTK4
- PyGObject
sudo prt-get depinst mpvsudo apt install mpvsudo pacman -S mpvsudo dnf install mpvbrew install mpvffplay is included with FFmpeg and can be used as a lightweight fallback backend.
sudo prt-get depinst ffmpegsudo apt install ffmpegsudo pacman -S ffmpegsudo dnf install ffmpegbrew install ffmpegVerify:
ffplay -versionFluxTuner currently provides two interfaces:
- TUI (Terminal User Interface) → fast, lightweight and keyboard-oriented
- GTK Desktop GUI → visual desktop experience with playlists, favorites and responsive layout
Both interfaces share the same playback backend, favorites system and playlist data.
FluxTuner uses a modular playback backend architecture.
FluxTuner automatically detects the best available playback backend.
Current priority order:
mpv(recommended)ffplay(lightweight fallback)
Inspect detected playback backends with:
fluxtuner --list-playersor, when running from source:
python -m fluxtuner --list-playersAdditional backends may be added in future versions.
The TUI is ideal for:
- SSH sessions
- low-resource systems
- keyboard-driven workflows
- tiling window managers
- fast station browsing
This is the simplest and least invasive way to test or run FluxTuner from a checkout:
git clone https://github.com/pitill0/fluxtuner.git
cd fluxtuner
python -m venv .venv
source .venv/bin/activate
pip install -e .
python -m fluxtunerfluxtunerEquivalent to:
python -m fluxtunerfluxtuner --tuior:
python -m fluxtuner --tui- Fast search
- Country filtering
- Minimum bitrate filtering
- Favorites support
- Dynamic playlists
- Random playback by tag
- Theme support
- Session data usage tracking
- Modular backend support
FluxTuner also includes an experimental GTK4 desktop interface.
The GUI focuses on:
- responsive layout
- playlist workflows
- favorites management
- visual station browsing
- desktop-friendly playback controls
- live metadata display
fluxtuner --guior:
python -m fluxtuner --gui- GTK4 desktop interface
- Responsive dark theme
- Fast station search
- Favorites management
- Tag playlist filtering
- Random playback by tag
- Session data usage tracking
- Playback status indicators
- Volume and mute controls
- Live artist / track metadata
- Active backend display
For testing or running FluxTuner without installing it globally:
git clone https://github.com/pitill0/fluxtuner.git
cd fluxtuner
python -m venv .venv
source .venv/bin/activate
pip install -e .
python -m fluxtuner --player mpv
python -m fluxtuner --gui --player mpvYou can also rely on backend autodetection:
python -m fluxtuner
python -m fluxtuner --guiThis workflow is especially useful for development, CRUX Linux and systems where you prefer to avoid global installation.
Recommended if you want FluxTuner available as a standalone command:
pipx install git+https://github.com/pitill0/fluxtuner.gitRun:
fluxtunerInstall a specific version:
pipx install git+https://github.com/pitill0/fluxtuner.git@v0.1.0Upgrade:
pipx upgrade fluxtunerUninstall:
pipx uninstall fluxtunerFluxTuner currently supports:
mpv(recommended)ffplay(lightweight fallback backend)
FluxTuner automatically selects the best available backend by default.
Inspect detected playback backends with:
fluxtuner --list-playersExamples:
fluxtuner --player mpvfluxtuner --gui --player mpvfluxtuner --player ffplayfluxtuner --gui --player ffplayWhen running from source, use:
python -m fluxtuner --player mpv
python -m fluxtuner --player ffplay
python -m fluxtuner --gui --player mpv
python -m fluxtuner --gui --player ffplayList available themes:
fluxtuner --list-themesRun with a theme:
fluxtuner --theme nordSave a theme as default:
fluxtuner --theme nord --save-themeor:
fluxtuner --save-theme nord# Show help
fluxtuner --help
# Show version
fluxtuner --version
# List available playback backends
fluxtuner --list-players
# Clear search cache
fluxtuner --clear-cache
# Export favorites
fluxtuner --export-favs favorites.json
# Import favorites
fluxtuner --import-favs favorites.json
# Export playlists
fluxtuner --export-playlists playlists.json
# Import playlists
fluxtuner --import-playlists playlists.jsonWhen running from source, replace fluxtuner with:
python -m fluxtunerWhen using a Python virtual environment, PyGObject installed via Homebrew may not be visible inside the venv.
Install dependencies:
brew install gtk4 pygobject3 mpv ffmpegIf your shell aliases python to a system interpreter, the virtual environment may be bypassed.
Check:
which pythonIf needed:
unalias pythonIf the GUI fails with:
ModuleNotFoundError: No module named 'gi'
run FluxTuner with Homebrew's PyGObject path:
PYGOBJECT_SITE_PACKAGES="$(dirname "$(find "$(brew --prefix)" -path "*/site-packages/gi/__init__.py" 2>/dev/null | head -n 1)")"
PYTHONPATH="$PYGOBJECT_SITE_PACKAGES" python -m fluxtuner --gui --player mpvOn Apple Silicon this often resolves to:
PYTHONPATH=/opt/homebrew/lib/python3.14/site-packages \
python -m fluxtuner --gui --player mpvFind the correct path with:
find "$(brew --prefix)" -path "*site-packages/gi/__init__.py" 2>/dev/null| Key | Action |
|---|---|
/ |
Focus search |
Enter |
Play selected station |
x |
Stop playback |
Space |
Pause / Resume |
+ / - |
Volume up / down |
m |
Mute |
a |
Add to favorites |
f |
Open favorites |
d |
Remove favorite |
e |
Edit favorite name |
g |
Edit favorite tags |
p |
Open playlists |
n |
New playlist |
b |
Add to playlist |
t |
Filter by tag / open theme selector depending on context |
h |
History |
l |
Play last station |
q |
Quit |
Built-in themes:
- default
- nord
- dracula
- amber
- ptmtrx
Features:
- Live preview in selector
- Apply with
Enter - Save with
y
- Favorites:
~/.fluxtuner_favorites.json - Playlists:
~/.fluxtuner_playlists.json - Config:
~/.config/fluxtuner/config.json - Data usage:
~/.fluxtuner_usage.json
- Improved GTK desktop experience
- Better playlist workflows
- Responsive layouts
- Packaging and distribution
- Persistent GUI settings
- Live stream metadata improvements
- Native volume integration
- MPRIS/media key support
- Station history
- Import/export improvements
- Flatpak packaging
- AppImage builds
- Mobile-oriented interface experiments
PRs are welcome.
Issues, feature requests and feedback are always appreciated.
FluxTuner is open source and available under the MIT license.
You are free to use, modify, and distribute it, including for commercial purposes.
That said, if you plan to integrate FluxTuner into a commercial product, service, or distribution, please consider reaching out.
Contributions, attribution, or collaboration are always appreciated.
MIT
If you find FluxTuner useful:
- Star the repository
- Report issues
- Suggest improvements
- Share screenshots or workflows
Your support helps shape the future of the project.