This is an comprehensive command-line interface (CLI) for bluOS streamers.
I wrote it, because its incredible borring to switch to a mobile phone while working just because you want to hear different sounds, written in python.
Originally based on https://github.com/irrelative/blucli (opens in a new tab) This project has since diverged significantly and is maintained independently.
Extensive usage of claude-code (opus4.6)
A comprehensive CLI interface to control Blusound streamers.
- Automatic discovery of Blusound players on the network
- Interactive player selection and control
- Volume adjustment
- Play/pause functionality
- Track navigation (skip forward/backward)
- Display of currently playing information
- Input selection for each player
- Detailed view of player status
- Displays the current playlist and let you toggle
- API call to musicbrainz for additional information about the track
- openai API call to get textbased information about the track
- Displays an ascii-art image from the cover (c)
- Radio Integration with Tunein & Radio Paradise
- Lyrics from lrclib.net integrated
- It mainly works well for qobuz support
- No Spotify Support. BluOS does not support it
- Not tested local/private streaming-services
- The information form MusicBrainz is sometimes wrong. It is used when no OPENAI_API_KEY is present. All other additional Informations are from chatgpt - so it could be wrong
- Radio Stations cannot be stored as favorites.
- No Multi-Room feature (planned)
- Python 3.6+
-
Clone this repository:
git clone https://github.com/xernot/bluxir.git cd bluxir -
Set up a virtual environment:
python3 -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate` -
Install the required dependencies:
pip install -r requirements.txt
Run the script using:
python bluxir.py
bluxir is a curses-based terminal UI with multiple views. Navigate between them using keyboard shortcuts.
On startup, bluxir discovers Blusound players on your local network via zeroconf. If a player was used previously, it reconnects automatically (stored in config.json).
| Key | Action |
|---|---|
| UP/DOWN | Select player |
| ENTER | Activate player |
| q | Quit |
The main view is split into two halves:
Left side displays:
- Track title, artist, album
- Technical details: Format, Quality (Hi-Res/CD-Quality/MP3/MQA), Sample Rate, Bit Depth, dB Level
- Album metadata: Track number, Composer, Year, Label, Genre (fetched via OpenAI or MusicBrainz)
- Track description generated by OpenAI (configurable model and system prompt)
- Cover art as terminal ASCII art (toggle with
c)
Right side displays:
- Playlist with the current track highlighted and auto-scrolling
- When playing radio: station info (Now playing / Next program)
| Key | Action |
|---|---|
| UP/DOWN | Adjust volume |
| SPACE | Play / Pause |
| > | Skip to next track |
| < | Previous track |
| i | Browse and select input sources |
| s | Search (within a source like Qobuz) |
| f | Qobuz favorites |
| l | Load a saved playlist |
| w | Save current playlist |
| c | Toggle cover art display |
| + | Add current album to favourites |
| - | Remove current album from favourites |
| p | Pretty print (JSON debug view of player status) |
| ? | Show keyboard shortcuts |
| b | Back to player selection |
| q | Quit |
Press i to browse available sources (Qobuz, TuneIn, Radio Paradise, etc.).
Navigate the source hierarchy to find albums, playlists, or radio stations.
| Key | Action |
|---|---|
| UP/DOWN | Navigate list |
| ENTER | Play (radio streams play directly, songs offer Play now / Add next / Add last) |
| RIGHT | Expand / enter subfolder |
| LEFT | Go back one level |
| s | Search within current source |
| n/p | Next / previous page |
| + | Add to favourites |
| - | Remove from favourites |
| t | Sort by title |
| a | Sort by artist |
| o | Restore original order |
| b | Back to player control |
Press s from source browsing or player control to search within a source (e.g. Qobuz).
Type your search term and press ENTER. Results show albums and tracks. For tracks,
ENTER opens a queue dialog (Play now / Add next / Add last). For albums, ENTER browses into the album.
Select a radio station from TuneIn or Radio Paradise via source browsing. Press ENTER to play directly. The right side switches to a radio info panel showing the current program and next show. bluxir also fetches a description of the station via OpenAI.
Press c to toggle cover art rendering.
Album covers and radio station logos are displayed using half-block
terminal characters with 256 colors. The image is rendered inline in the left panel.
When an OpenAI API key is configured, bluxir fetches:
- Album metadata (year, label, genre)
- A short description of the current track or radio station
Configure in config.json:
openai_model: the model to use (default:gpt-4o-mini, can be set togpt-4o,gpt-5.2, etc.)openai_system_prompt: instructions for the track description (e.g. include musician details, studios)
The API key is stored separately in a private config file (not committed to git).
Without an API key, bluxir falls back to MusicBrainz for album metadata (less accurate).
(documentation generated by claude opus 4.6)