https://github.com/feoh/plexbar
https://github.com/feoh/plexbar
Last synced: about 17 hours ago
JSON representation
- Host: GitHub
- URL: https://github.com/feoh/plexbar
- Owner: feoh
- Created: 2026-06-08T19:22:20.000Z (20 days ago)
- Default Branch: main
- Last Pushed: 2026-06-08T20:49:47.000Z (20 days ago)
- Last Synced: 2026-06-08T22:11:04.300Z (19 days ago)
- Language: Python
- Size: 192 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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`](https://docs.astral.sh/uv/)
- [`mpv`](https://mpv.io/) 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`:
```bash
uv tool install plexbar
```
Run Plexbar:
```bash
plexbar
```
## Installation for development
Clone the repository and sync dependencies with `uv`:
```bash
git clone git@github.com:feoh/plexbar.git
cd plexbar
uv sync
```
Run Plexbar from the project checkout:
```bash
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:
```text
~/.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
```bash
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.