plexbar 1.2.1

A command-line TUI music player for Plex

Plexbar

Plexbar is a keyboard-driven terminal music player for Plex. It gives you a simple Textual TUI for browsing and playing your Plex music library without opening a web browser.

Features

• First-run Plex connection setup
• Browse by Artists, Albums, Tracks, Playlists, and Genres
• Search your Plex music library
• Queue tracks, albums, artists, playlists, and genres
• Show cover art for the currently playing track or album
• Play, pause/resume, stop, and skip with keyboard shortcuts
• Local playback through mpv

Requirements

• Python 3.12+
• uv
• mpv installed and available on PATH
• A Plex server with at least one music library
• A Plex account that can access your Plex server

Installation

Install Plexbar as a standalone command with uv:

uv tool install plexbar

Run Plexbar:

plexbar

Installation for development

Clone the repository and sync dependencies with uv:

git clone [e-mail]:feoh/plexbar.git
cd plexbar
uv sync

Run Plexbar from the project checkout:

uv run plexbar

First-run setup

If ~/.config/plexbar/config.toml does not exist, Plexbar opens a setup screen and prompts for:

1. Plex base URL, for example http://puppy:32400 or http://127.0.0.1:32400
2. Plex sign-in authorization in your browser
3. Default music library

The config file is written to:

~/.config/plexbar/config.toml

Plexbar writes this file with user-only permissions where supported. During setup, Plexbar receives a Plex token from Plex after browser authorization and saves only that token. It does not ask for or store your Plex password. Do not commit or share your Plex token.

Usage

The top-level browser contains:

• Artists
• Albums
• Tracks
• Playlists
• Genres

Press Enter to drill down into artists, albums, playlists, and genres. Genre browsing offers "By Artist" and "By Album" groupings before listing tracks. Press Enter on a track to enqueue it.

Keybindings

Key	Action
/	Search Plex music
Enter	Select/drill down, or enqueue focused track
p	Play focused track/album/artist/playlist/genre artist/genre album immediately and replace queue
a	Append focused track/album/artist/playlist/genre artist/genre album to queue
Space	Pause/resume
n	Next track
s	Stop playback
q	Quit

Local validation

uv run ruff check .
uv run ruff format --check .
uv run pytest
uv run mypy src/plexbar tests

Playback

Plexbar keeps a persistent mpv process running and controls it through mpv's JSON IPC interface for responsive pause/resume, stop, and track changes.