Metadata-Version: 2.4
Name: plex-tui
Version: 0.2.0
Summary: A small standalone Plex terminal UI.
Project-URL: Homepage, https://github.com/so1omon563/plex-tui
Project-URL: Issues, https://github.com/so1omon563/plex-tui/issues
Project-URL: Repository, https://github.com/so1omon563/plex-tui
Author: so1omon
License-Expression: MIT
License-File: LICENSE
Keywords: mpv,plex,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: pillow>=10.0
Requires-Dist: platformdirs>=4.2
Requires-Dist: plexapi>=4.15
Requires-Dist: textual>=0.86
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# plex-tui

A standalone Python/Textual terminal UI for browsing Plex and launching playback
through `mpv`.

plex-tui is currently an early release. It supports Plex login, server
selection, paged library browsing, search, list/grid views, stream preferences,
terminal poster artwork, and playback progress reporting.

## Screenshots

### Grid view

![plex-tui grid view](docs/assets/grid-view.png)

### List view

![plex-tui list view](docs/assets/list-view.png)

## Requirements

- Python 3.11 or newer
- `mpv` available on `PATH`
- A Plex account/server

Install `mpv` with your platform package manager:

```bash
# macOS
brew install mpv

# Debian / Ubuntu
sudo apt install mpv

# Fedora
sudo dnf install mpv

# Arch Linux / Manjaro
sudo pacman -S mpv
```

## Install

The README tracks the current `main` branch. Tagged releases are available on
the GitHub Releases page.

The recommended install path for the latest `main` branch is `pipx`:

```bash
pipx install "git+https://github.com/so1omon563/plex-tui.git"
plex-tui --smoke
plex-tui
```

To install the latest tagged release instead:

```bash
pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.2.0"
```

Useful CLI checks:

```bash
plex-tui --version
plex-tui --config-path
plex-tui --debug-log-path
plex-tui --smoke
```

For local development:

```bash
git clone https://github.com/so1omon563/plex-tui.git
cd plex-tui
python3 -m venv .venv
source .venv/bin/activate
make install-dev
make run
```

## First Run & Configuration

On first run, plex-tui starts a Plex browser login and asks which server
connection to save. If a browser cannot be opened, use the login URL shown in
the terminal.

You can also configure a server manually. macOS config path:

```bash
mkdir -p "$HOME/Library/Application Support/plex-tui"
$EDITOR "$HOME/Library/Application Support/plex-tui/config.toml"
```

Linux config path:

```bash
mkdir -p "$HOME/.config/plex-tui"
$EDITOR "$HOME/.config/plex-tui/config.toml"
```

Minimal config:

```toml
base_url = "http://127.0.0.1:32400"
token = "your-plex-token"
```

Environment variables also work:

```bash
export PLEX_TUI_BASE_URL="http://127.0.0.1:32400"
export PLEX_TUI_TOKEN="your-plex-token"
```

See `config.example.toml` for optional settings.

## Key Bindings

| Key | Action |
| --- | --- |
| `q` | Quit |
| `r` | Reload Plex connection |
| `/` | Search current library |
| `g` | Search all libraries |
| `?` | Show help |
| `tab` / `shift+tab` | Move focus |
| `l` | Focus libraries |
| `m` | Focus media |
| `v` | Toggle list/grid view |
| `pageup` / `pagedown` | Move one page in grid view |
| `,` | Show settings |
| `escape` | Clear search, go back, or close current view |
| `enter` | Open selected item |
| `p` | Play selected item with `mpv` |
| `a` / `s` | Choose audio / subtitle preference |
| `A` / `S` | Clear audio preference / cycle subtitle mode |
| `x` | Stop launched `mpv` |

## Features

- Plex PIN login and server selection.
- Paged library browsing with automatic loading near the end of loaded items.
- Current-library search and bounded global search.
- List view plus configurable-density grid view with terminal poster artwork.
- External subtitle support and direct playback for embedded PGS/VOBSUB tracks.
- Audio and subtitle pickers with saved language preferences.
- Plex resume support and playback progress reporting.
- Settings screen for stream preferences, artwork modes, grid density, page
  size, auto-load threshold, media view, and `mpv` window size.

## Artwork

Poster artwork renders as portable colored block art, so it works in ordinary
terminals without Kitty, iTerm2, or Sixel support. Native terminal image output
is disabled for now because Kitty protocol rendering conflicts with Textual's
screen renderer in practice.

Grid view prefetches artwork for the visible page immediately and the next page
after selection settles. Compact, comfortable, and large density modes adjust
card and poster sizing. The artwork cache is bounded and stored in the app cache
directory shown in Settings.

## Diagnostics

Playback diagnostics are written to `debug.log` in the app config directory.
Tokens are redacted from logged `mpv` arguments.

Enable browsing performance timings before launch:

```bash
PLEX_TUI_PERF_LOG=1 plex-tui
```

## Development

Common commands:

```bash
make smoke          # app construction and helper sanity check
make test           # pytest suite
make compile        # compile src and tests
make check-package  # build and validate package metadata
make check          # smoke, tests, compile, package validation
```

Packaging and release docs:

- `PACKAGING.md`: PyPI/pipx, Homebrew, AUR, and standalone packaging options.
- `RELEASE.md`: release validation and tagging checklist.
- `ROADMAP.md`: planned follow-up work.
