plex-tui 0.2.0__tar.gz

plex_tui-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+.env
+.env.*
+.DS_Store
+mpv-shot*.jpg

plex_tui-0.2.0/AGENTS.md

@@ -0,0 +1,80 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This is a Python/Textual terminal app for browsing Plex and launching playback
+through `mpv`.
+
+- `src/plextui/`: application source.
+  - `app.py`: Textual UI, navigation, settings, and high-level actions.
+  - `plex_service.py`: Plex API mapping and media detail extraction.
+  - `player.py`: `mpv` launch, stream selection, and playback diagnostics.
+  - `config.py`, `auth.py`, `artwork.py`, `models.py`: supporting modules.
+- `tests/`: pytest suite, split by app helpers/navigation and service modules.
+- `README.md`, `PACKAGING.md`, `RELEASE.md`, `ROADMAP.md`: user and release docs.
+- `config.example.toml`: example user configuration.
+
+## Build, Test, and Development Commands
+
+Use the project Makefile from the repository root:
+
+```bash
+make install-dev   # install editable package with dev dependencies
+make run           # start the TUI locally
+make smoke         # import/app construction sanity check
+make test          # run pytest
+make compile       # compile src and tests
+make build         # build sdist and wheel
+make check-package # build and validate package metadata
+make check         # smoke, tests, compile, and package validation
+```
+
+The app requires Python 3.11+ and uses external `mpv` for playback.
+
+## Coding Style & Naming Conventions
+
+Use standard Python style with 4-space indentation and type annotations for new
+public helpers or cross-module data. Prefer small pure helper functions for
+rendering/status logic, and keep Textual event handling in `PlexTuiApp`.
+
+Naming conventions:
+
+- Classes: `PascalCase`, for example `MediaGrid`.
+- Functions and variables: `snake_case`.
+- Tests: `test_<behavior>` or async helpers named `run_<behavior>_check`.
+
+No formatter is currently enforced. Keep edits minimal and consistent with
+nearby code.
+
+## Testing Guidelines
+
+Tests use `pytest`. Add focused unit tests for helper logic and app navigation
+tests for Textual behavior. Prefer deterministic fake objects over live Plex
+calls. Run at least:
+
+```bash
+make test
+make compile
+make smoke
+```
+
+For packaging or metadata changes, also run `make check-package` or `make check`.
+
+## Commit & Pull Request Guidelines
+
+Git history uses short imperative subjects, such as `Speed up grid navigation`
+and `Polish settings and grid navigation`. Keep commits scoped to one logical
+change and include docs/tests with behavior changes.
+
+Pull requests should include:
+
+- A concise summary of user-visible behavior.
+- Tests run and results.
+- Screenshots or terminal notes for TUI changes when useful.
+- Any config, packaging, or migration impact.
+
+## Security & Configuration Tips
+
+Never commit real Plex tokens, account tokens, debug logs, or local config files.
+Use `config.example.toml` for examples. Logs should redact tokens; preserve that
+behavior when changing playback or request diagnostics.

plex_tui-0.2.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.2.0 - 2026-06-11
+
+- Improved README structure and expanded the post-0.1.0 roadmap.
+- Grouped the Settings screen into account, stream, playback, artwork, browsing, and diagnostics sections.
+- Added direct Settings input for custom `mpv` window sizes.
+- Added direct Settings input for custom page size and auto-load threshold values.
+- Added confirmation for destructive Settings preference clears.
+- Replaced the heavy selected grid-card border with a quieter marker/footer treatment.
+- Added configurable compact, comfortable, and large grid density modes.
+- Kept Settings open after value changes and added clearer changed-value feedback.
+- Preserved Settings row highlighting after opening Settings and changing values.
+- Added README screenshots for grid and list views.
+- Clarified README install instructions for `main` versus tagged releases.
+- Improved active playback status, details-pane playback context, and abnormal `mpv` exit diagnostics.
+
+## 0.1.0 - 2026-06-11
+
+- Added Plex PIN login and server selection.
+- Added library browsing with paged loading and automatic loading near the end of the list.
+- Added current-library search with paged results and bounded global search.
+- Added playback through `mpv` with Plex resume and progress reporting.
+- Added audio and subtitle pickers with saved language preferences.
+- Added support for external subtitles and embedded PGS/VOBSUB subtitle playback.
+- Added media details for metadata, audio tracks, subtitle tracks, and saved stream preferences.
+- Added settings actions for reload, relogin, and audio/subtitle preference management.
+- Added settings actions for page size, auto-load threshold, mpv window sizing, and debug log visibility.
+- Added playback diagnostics with token-redacted `debug.log` output.
+- Added development workflow targets, smoke checks, and Linux/macOS setup documentation.
+- Added release checklist and packaging option documentation.
+- Added CLI flags for version, config/debug paths, and smoke checks.
+- Added configurable page size and auto-load threshold for browsing performance.
+- Added grid page navigation, richer grid status text, and adjacent-page artwork prefetching.

plex_tui-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 so1omon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plex_tui-0.2.0/Makefile

@@ -0,0 +1,29 @@
+.PHONY: install-dev run test compile smoke build check-package check clean
+
+PYTHON ?= .venv/bin/python
+
+install-dev:
+	$(PYTHON) -m pip install -e ".[dev]"
+
+run:
+	$(PYTHON) -m plextui
+
+test:
+	$(PYTHON) -m pytest
+
+compile:
+	python3 -m compileall -f src tests
+
+smoke:
+	$(PYTHON) -m plextui.smoke
+
+build:
+	$(PYTHON) -m build --no-isolation
+
+check-package: build
+	$(PYTHON) -m twine check dist/*
+
+check: smoke test compile check-package
+
+clean:
+	rm -rf build dist *.egg-info src/*.egg-info

plex_tui-0.2.0/PACKAGING.md

@@ -0,0 +1,108 @@
+# Packaging Options
+
+## Current Target
+
+The current package is a standard Python project with a `plex-tui` console
+script. The best short-term install path is:
+
+```bash
+pipx install .
+```
+
+This keeps Python dependencies isolated while still exposing a normal command.
+Users must install `mpv` separately with their system package manager.
+
+Once pushed to GitHub, users can also install from:
+
+```bash
+pipx install "git+https://github.com/so1omon563/plex-tui.git"
+```
+
+Before the first push, configure the repository remote:
+
+```bash
+git remote add origin https://github.com/so1omon563/plex-tui.git
+git push -u origin main
+```
+
+For local package validation, test both source and wheel installs:
+
+```bash
+pipx install --force .
+plex-tui --version
+plex-tui --smoke
+python -m build
+pipx install --force dist/plex_tui-*.whl
+plex-tui --version
+plex-tui --smoke
+```
+
+## Recommended Path
+
+1. **PyPI + pipx**
+
+   Publish the Python package to PyPI once tagged GitHub releases are stable.
+   Users install with:
+
+   ```bash
+   pipx install plex-tui
+   ```
+
+   This is the lowest-maintenance distribution path for Python/Textual apps.
+   It does not solve the external `mpv` dependency, so docs must keep calling
+   that out explicitly.
+
+2. **Homebrew tap**
+
+   Add a Homebrew formula after PyPI packaging is stable. The formula can depend
+   on `mpv` and install the Python package through a virtualenv.
+
+   This would give macOS users a single command:
+
+   ```bash
+   brew install <tap>/plex-tui
+   ```
+
+   Formula requirements:
+
+   - Depend on `python@3.13` or the current Homebrew Python.
+   - Depend on `mpv`.
+   - Install from a tagged source archive or PyPI release.
+   - Run `plex-tui --smoke` in the formula test.
+
+3. **Arch AUR**
+
+   Add an AUR package for Arch users. This can depend on `mpv` and Python
+   dependencies from Arch packages where practical.
+
+   Package requirements:
+
+   - `depends=('python' 'mpv' ...)`
+   - Use a tagged GitHub source archive for `plex-tui`.
+   - Prefer system Python packages for `python-textual`, `python-pillow`,
+     `python-plexapi`, and `python-platformdirs` when available.
+   - Include a `check()` step that runs `plex-tui --smoke`.
+
+4. **Standalone binaries**
+
+   Consider PyInstaller or Shiv/Pex only after the app behavior stabilizes.
+   Standalone artifacts are convenient but add CI and platform complexity.
+   They still cannot bundle every user's `mpv` setup cleanly, so they do not
+   remove the external player dependency.
+
+## Not Recommended Yet
+
+- System distro packages before the app has tagged releases.
+- Bundling `mpv` into the Python package.
+- Native image protocol support as a packaging requirement.
+
+## Packaging Requirements
+
+Every distribution path should preserve:
+
+- `plex-tui` command name.
+- Python 3.11+ support.
+- MIT license metadata.
+- Clear external `mpv` dependency.
+- Config paths based on `platformdirs`.
+- Smoke/test/build checks from `RELEASE.md`.

plex_tui-0.2.0/PKG-INFO

@@ -0,0 +1,226 @@
+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.