Website: https://fluxtuner.vjml.es
FluxTuner is a modern internet radio player for the terminal and desktop.
It combines a fast keyboard-oriented Textual TUI, a GTK4 desktop GUI, smart favorites and playlists, theming, live metadata, data usage tracking and modular playback backends.
- Search internet radio stations by name, genre/tag and country.
- Play streams through
mpv,ffplay,mpg123orogg123with automatic backend detection. - Manage favorites, custom favorite names, tags and playlists.
- Use dynamic tag playlists, random playback and station history.
- Switch built-in TUI themes with live preview.
- Run either the default Textual TUI, the GTK4 desktop GUI or the legacy numbered CLI.
- Store user data in XDG-style config, data and cache locations.
- Python 3.11+
mpvrecommended,ffmpeg/ffplayas broad fallback, or optional lightweightmpg123/ogg123backends- Optional GUI dependencies: GTK4 and PyGObject
git clone https://github.com/pitill0/fluxtuner.git
cd fluxtuner
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m fluxtunerpipx install git+https://github.com/pitill0/fluxtuner.git
fluxtunerYou can run FluxTuner directly from a tagged source archive:
wget https://github.com/pitill0/fluxtuner/archive/refs/tags/v0.4.0.tar.gz
tar xvf v0.4.0.tar.gz
cd fluxtuner-0.4.0
Install the Python dependencies required by the terminal interface.
For pip-based environments:
python -m pip install requests rich textual
On systems using distribution packages, install the equivalent packages instead, for example:
requests
rich
textual
Then launch FluxTuner:
python -m fluxtuner
For playback, make sure at least one supported player backend is installed:
mpv
ffplay
mpg123
ogg123
mpv is recommended for the best general compatibility.
To run the GTK interface, you also need GTK 4 and PyGObject available on your system.
For pip-based environments, PyGObject may still require system GTK development/runtime packages, so distribution packages are often preferred.
On Debian/Ubuntu-based systems:
sudo apt install python3-gi gir1.2-gtk-4.0
On Arch Linux:
sudo pacman -S gtk4 python-gobject
On systems using source-based or ports-based package managers, install the equivalent packages for:
GTK 4
PyGObject
GObject Introspection
Then launch the GUI mode using the documented FluxTuner GUI option.
This method is useful for testing a release quickly. For regular use, prefer the packaged installation methods when available.
fluxtuner # default Textual TUI
fluxtuner --gui # GTK4 desktop GUI
fluxtuner --cli # legacy numbered CLIfluxtuner --help
fluxtuner --version
fluxtuner --list-players
fluxtuner --doctor
fluxtuner --list-themes
fluxtuner --theme nord
fluxtuner --theme nord --save-theme
fluxtuner --export-favs favorites.json
fluxtuner --import-favs favorites.json
fluxtuner --export-playlists playlists.json
fluxtuner --import-playlists playlists.json
fluxtuner --clear-cache| Topic | Link |
|---|---|
| Project website, overview, screenshots and quick introduction | FluxTuner website |
| Installation, launch modes, player backends, themes, keybindings and data storage | Usage guide |
| Architecture, modules, storage and playback flow | Architecture |
| Local development, tests, quality checks and troubleshooting | Development guide |
| Release process | Release guide |
| Flatpak packaging notes | Flatpak guide |
| Security policy | Security |
| Changes by version | Changelog |
| Contributing workflow | Contributing |
flowchart LR
User["User"] --> Entry["fluxtuner command"]
Entry --> TUI["Textual TUI"]
Entry --> GUI["GTK4 GUI"]
Entry --> CLI["Legacy CLI"]
TUI --> Services["Core services"]
GUI --> Services
CLI --> Services
Services --> Search["Radio Browser search"]
Services --> Compatibility["Station compatibility"]
Services --> Library["Favorites, playlists, history"]
Services --> Config["Config and playback state"]
Services --> PlayerRegistry["Player registry"]
Search --> Compatibility
Compatibility --> PlayerRegistry
PlayerRegistry --> MPV["mpv backend"]
PlayerRegistry --> FFPLAY["ffplay backend"]
PlayerRegistry --> MPG123["mpg123 backend"]
PlayerRegistry --> OGG123["ogg123 backend"]
MPV --> Streams["Online radio streams"]
FFPLAY --> Streams
MPG123 --> Streams
OGG123 --> Streams
Library --> Storage["XDG data files"]
Config --> Storage
See the full design notes in docs/architecture.md.
FluxTuner is under active development. The current focus is to keep improving the stable TUI and GTK desktop GUI, refine playlist and favorites workflows, improve packaging/distribution paths, and continue hardening reliability, tests and documentation.
The roadmap is intentionally kept out of the README until items are confirmed. Please use GitHub issues and discussions for proposed features, bugs and packaging requests.
Issues, feature requests, screenshots, workflows and pull requests are welcome.
A good first contribution can be as simple as:
- trying FluxTuner on your Linux/macOS setup,
- reporting whether
mpv,ffplay,mpg123orogg123detection works, - sharing terminal or GTK screenshots,
- suggesting stations, playlist workflows or packaging improvements,
- opening a small documentation or bug-fix PR.
See CONTRIBUTING.md and docs/development.md.
FluxTuner is open source and available under the MIT license.
You are free to use, modify and distribute it, including for commercial purposes. If you plan to integrate FluxTuner into a commercial product, service or distribution, collaboration, attribution or feedback would be appreciated.
MIT
If you find FluxTuner useful, please consider starring the repository, opening issues, suggesting improvements or sharing your setup. Feedback helps shape the future of the project.