Skip to content

usage.md

Latest commit

 

History

History
408 lines (284 loc) · 10.9 KB

usage.md

File metadata and controls

408 lines (284 loc) · 10.9 KB
Raw

Usage Guide

This guide covers installing, running and configuring FluxTuner.

Requirements

FluxTuner requires:

  • Python 3.11 or newer.
  • At least one playback backend:
    • mpv recommended for broad stream compatibility and live controls.
    • ffplay, provided by FFmpeg, as a broad fallback.
    • mpg123 as an optional lightweight MP3/MPEG backend.
    • ogg123, provided by vorbis-tools, as an optional lightweight Ogg/Vorbis/Opus-style backend.
  • A terminal emulator with good Unicode support for the TUI.

The GTK desktop GUI also requires GTK4 and PyGObject.

Install player backends

CRUX Linux

sudo prt-get depinst mpv
sudo prt-get depinst ffmpeg
sudo prt-get depinst mpg123
sudo prt-get depinst libao vorbis-tools

Debian / Ubuntu

sudo apt install mpv ffmpeg mpg123 vorbis-tools

Arch Linux

sudo pacman -S mpv ffmpeg mpg123 vorbis-tools

Fedora

sudo dnf install mpv ffmpeg mpg123 vorbis-tools

macOS

brew install mpv ffmpeg mpg123 vorbis-tools

Verify ffplay if you plan to use the fallback backend:

ffplay -version

Run from source

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 fluxtuner

Install with pipx

pipx install git+https://github.com/pitill0/fluxtuner.git
fluxtuner

Upgrade:

pipx upgrade fluxtuner

Uninstall:

pipx uninstall fluxtuner

Launch modes

FluxTuner provides four user-facing modes that share core services and library behavior: the Textual TUI, GTK4 GUI, legacy numbered CLI and browser-based Web/server mode.

fluxtuner                                      # Textual TUI, default
fluxtuner --gui                                # GTK4 desktop GUI
fluxtuner --cli                                # legacy numbered CLI
fluxtuner-web --host 127.0.0.1 --port 8080    # Web/server mode

The Web/server command requires the optional Web dependencies, installed with python -m pip install -e ".[web]" from a source checkout.

The examples in this guide use the installed fluxtuner command. When working directly from a source checkout, use the equivalent module form:

python -m fluxtuner

Options are identical, so fluxtuner --doctor becomes python -m fluxtuner --doctor, for example.

Player backends

FluxTuner currently supports:

  • mpv
  • ffplay
  • mpg123
  • ogg123

By default, FluxTuner uses automatic backend detection.

fluxtuner --player auto
fluxtuner --player mpv
fluxtuner --player ffplay
fluxtuner --player mpg123
fluxtuner --player ogg123

List supported and available backends:

fluxtuner --list-players
fluxtuner --doctor

Backend notes:

  • mpv supports play/stop, live pause, live volume and live mute controls.
  • ffplay is a broad fallback focused on simple play/stop.
  • mpg123 is a specialized lightweight backend for MP3/MPEG streams.
  • ogg123 is a specialized lightweight backend for Ogg/Vorbis/Opus-style streams, depending on the local ogg123 build.

Themes

List available themes:

fluxtuner --list-themes

Run with a theme:

fluxtuner --theme nord

Save a theme as default:

fluxtuner --theme nord --save-theme

or:

fluxtuner --save-theme nord

Built-in themes:

  • default
  • nord
  • dracula
  • amber
  • ptmtrx

Useful commands

fluxtuner --help
fluxtuner --version
fluxtuner --list-players
fluxtuner --doctor
fluxtuner --list-themes
fluxtuner --clear-cache
fluxtuner --export-favs favorites.json
fluxtuner --import-favs favorites.json
fluxtuner --export-playlists playlists.json
fluxtuner --import-playlists playlists.json

TUI keybindings

Key Action
/ Focus search
Enter Play/apply selected row
Escape Focus station list
Space Play/stop selected station
x Stop playback
+ / - Volume up/down when supported by the active backend
m Mute/unmute when supported by the active backend
a Add selected station to favorites
f Show favorites
d Remove selected favorite
e Rename favorite
g Edit favorite tags
u Filter favorites by tag
p Show playlists
n Create playlist
b Add station to playlist
r Play random favorite
h Show history
l Play last station
t Show themes
y Save selected theme
q Quit

Data storage

FluxTuner stores local data in XDG-style locations.

The base directories respect XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_CACHE_HOME when they are set.

Default locations:

  • Library database: ~/.local/share/fluxtuner/fluxtuner.db
  • Config: ~/.config/fluxtuner/config.json
  • Data usage: ~/.local/share/fluxtuner/usage.json
  • Search cache: ~/.cache/fluxtuner/search_cache.json

The library database stores favorites, playback history, manual playlists and normalized station records for profile-scoped library data.

Favorites are the saved-station library used by all FluxTuner frontends. Manual playlists reference saved stations; adding a station to a playlist can therefore also save it to favorites/library if it is not already present. This keeps playlist resolution, exports and compatibility checks consistent across the TUI, GTK, CLI and Web modes.

Legacy library JSON files are still supported as migration sources:

  • ~/.local/share/fluxtuner/favorites.json
  • ~/.local/share/fluxtuner/playlists.json
  • ~/.local/share/fluxtuner/history.json

Older dotfiles such as ~/.fluxtuner_favorites.json, ~/.fluxtuner_playlists.json, ~/.fluxtuner_history.json and ~/.fluxtuner_usage.json are copied into the current XDG locations when needed and kept in place as a conservative migration.

Import and export commands still use JSON files:

fluxtuner --export-favs favorites.json
fluxtuner --import-favs favorites.json
fluxtuner --export-playlists playlists.json
fluxtuner --import-playlists playlists.json

macOS GTK note

When using a Python virtual environment, PyGObject installed through Homebrew may not be visible inside the venv.

Install system dependencies:

brew install gtk4 pygobject3 mpv ffmpeg

If the GUI fails with ModuleNotFoundError: No module named 'gi', find the Homebrew PyGObject path:

find "$(brew --prefix)" -path "*site-packages/gi/__init__.py" 2>/dev/null

Then run FluxTuner with that site-packages directory in PYTHONPATH.

Specialized player backend compatibility

FluxTuner supports both general-purpose and specialized playback backends.

General-purpose backends:

  • mpv — recommended backend with broad stream compatibility and live controls.
  • ffplay — broad compatibility fallback provided by FFmpeg.

Specialized lightweight backends:

  • mpg123 — lightweight backend for MP3/MPEG streams.
  • ogg123 — lightweight backend for Ogg/Vorbis/Opus/FLAC-style streams, depending on the local ogg123 build.

When a specialized backend is selected explicitly, FluxTuner filters search results where possible so the station list only contains streams that match the active backend capabilities. Saved favorites, history and playlists are kept intact, but incompatible stations are marked and blocked from playback with a clear message.

fluxtuner --player mpg123
fluxtuner --player ogg123

The legacy numbered CLI uses the same compatibility checks for searches, favorites and random favorite playback when a specialized backend is active.

Runtime diagnostics

Use --doctor to print a compact runtime diagnostic report:

fluxtuner --doctor

The report includes the FluxTuner version, Python/runtime platform, XDG storage paths and player backend availability. This is useful when reporting issues or checking what FluxTuner can see inside a sandboxed environment.

Troubleshooting player backends

Use --list-players to inspect which playback backends FluxTuner can find in the current environment:

fluxtuner --list-players

The command shows whether each backend is available or missing, whether it is general-purpose or specialized, and which codecs or live controls it declares.

If no backend is available, install at least one supported player:

  • mpv for the recommended general-purpose backend.
  • ffmpeg / ffplay for the broad fallback backend.
  • mpg123 for lightweight MP3/MPEG playback.
  • vorbis-tools / ogg123 for lightweight Ogg/Vorbis/Opus-style playback.

Inside Flatpak or other sandboxed environments, run the same command inside the sandbox to confirm which player binaries are actually visible to FluxTuner.

Profiles

FluxTuner profiles separate favorites, manual playlists and playback history by context. They are useful for setups such as work, home, terrace, pool, focus or testing.

Profiles are not separate user accounts. Anyone using the same FluxTuner installation can still see and select the available profiles.

List known profiles:

python -m fluxtuner --list-profiles

Use --profile NAME to target a profile explicitly:

python -m fluxtuner --profile work

Persistent active profile

FluxTuner can persist an active profile for profile-aware commands and interfaces:

python -m fluxtuner --profile work --set-active-profile
python -m fluxtuner --show-active-profile
python -m fluxtuner --clear-active-profile

Profile resolution order is:

1. Explicit `--profile NAME` or Web `?profile=NAME`
2. Persisted active profile
3. Internal default profile

Legacy CLI profile scope

The legacy numbered CLI honors --profile NAME for favorites operations:

python -m fluxtuner --cli --profile work

This scopes saving favorites from search, listing/removing favorites and random favorite playback to the selected profile.

When --profile NAME is omitted, the legacy numbered CLI uses the persisted active profile if one is configured, otherwise it falls back to the internal default profile.

Profile-aware import and export

Import and export commands accept --profile NAME to target a named profile:

python -m fluxtuner --profile work --export-favs work-favorites.json
python -m fluxtuner --profile work --import-favs work-favorites.json
python -m fluxtuner --profile work --export-playlists work-playlists.json
python -m fluxtuner --profile work --import-playlists work-playlists.json

When --profile NAME is omitted, FluxTuner uses the persisted active profile if one is configured, otherwise it falls back to the internal default profile.

Profile-aware interfaces

The persisted active profile is used by CLI import/export commands, the legacy numbered CLI favorites flow, the Textual TUI, GTK GUI and Web mode.

Web API endpoints also accept ?profile=NAME as a per-request override:

/api/favorites?profile=work
/api/history?profile=work
/api/playlists?profile=work

Web profile overrides have the highest priority for that request, followed by the persisted active profile and then the internal default profile.