plex-tui 0.4.3__tar.gz → 0.4.7__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {plex_tui-0.4.3 → plex_tui-0.4.7}/CHANGELOG.md +23 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/PKG-INFO +93 -34
- {plex_tui-0.4.3 → plex_tui-0.4.7}/README.md +92 -33
- {plex_tui-0.4.3 → plex_tui-0.4.7}/ROADMAP.md +22 -8
- {plex_tui-0.4.3 → plex_tui-0.4.7}/config.example.toml +4 -0
- plex_tui-0.4.7/docs/assets/collection-categories.png +0 -0
- plex_tui-0.4.7/docs/assets/collection-recommended.png +0 -0
- plex_tui-0.4.7/docs/assets/grid-tv-shows.png +0 -0
- plex_tui-0.4.7/docs/assets/grid-view.png +0 -0
- plex_tui-0.4.7/docs/assets/list-view.png +0 -0
- plex_tui-0.4.7/docs/collection-artwork-design.md +73 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/docs/plex-integration-research.md +10 -18
- {plex_tui-0.4.3 → plex_tui-0.4.7}/packaging/aur/.SRCINFO +3 -3
- {plex_tui-0.4.3 → plex_tui-0.4.7}/packaging/aur/PKGBUILD +2 -2
- {plex_tui-0.4.3 → plex_tui-0.4.7}/pyproject.toml +1 -1
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/__init__.py +1 -1
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/app.py +714 -29
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/config.py +9 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/player.py +39 -4
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/plex_service.py +149 -5
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_app_helpers.py +126 -11
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_app_navigation.py +381 -7
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_config.py +6 -1
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_player.py +36 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_plex_service.py +128 -1
- plex_tui-0.4.3/docs/assets/grid-view.png +0 -0
- plex_tui-0.4.3/docs/assets/list-view.png +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/aur.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/bump.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/ci.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/post-release-aur.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/post-release-homebrew.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/publish-aur.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/publish-pypi.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.github/workflows/publish-testpypi.yml +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/.gitignore +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/AGENTS.md +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/LICENSE +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/Makefile +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/PACKAGING.md +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/RELEASE.md +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/docs/homebrew-install-time.md +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/packaging/aur/README.md +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/packaging/homebrew/README.md +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/scripts/check_release.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/scripts/measure_homebrew_install.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/scripts/prepare_homebrew_bottle_assets.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/scripts/stage_release.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/scripts/update_aur_package.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/scripts/update_homebrew_formula.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/__main__.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/artwork.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/auth.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/models.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/src/plextui/smoke.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_artwork.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_auth.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_cli.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_homebrew_bottle_assets.py +0 -0
- {plex_tui-0.4.3 → plex_tui-0.4.7}/tests/test_release_checks.py +0 -0
|
@@ -2,6 +2,29 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.4.7 - 2026-06-19
|
|
6
|
+
|
|
7
|
+
- Added playlist management for creating playlists from selected media, adding
|
|
8
|
+
selected media to existing playlists, and removing items from playlist views.
|
|
9
|
+
- Added intentional collection-card artwork for hub, playlist, category, and
|
|
10
|
+
other container grid cards, with geometric glyphs and roomier spacing for
|
|
11
|
+
all-container grids such as Recommended.
|
|
12
|
+
|
|
13
|
+
## 0.4.4 - 2026-06-18
|
|
14
|
+
|
|
15
|
+
- Added a keyboard action to mark the selected playable Plex item watched or
|
|
16
|
+
unwatched from the browse view.
|
|
17
|
+
- Added Plex library Categories browsing, visible movie-edition variants, and
|
|
18
|
+
live mpv audio/subtitle switching when the active playback exposes matching
|
|
19
|
+
tracks.
|
|
20
|
+
- Made library rows open the full Library view by default, with Space opening
|
|
21
|
+
the browse-mode menu as the alternate action, and added a Settings option to
|
|
22
|
+
swap those actions.
|
|
23
|
+
- Added a Backspace/Delete Continue Watching removal action for selected items
|
|
24
|
+
in the Continue Watching view.
|
|
25
|
+
- Improved episode readability by showing show, season, and episode context in
|
|
26
|
+
episode rows and directly under the episode title in details.
|
|
27
|
+
|
|
5
28
|
## 0.4.3 - 2026-06-18
|
|
6
29
|
|
|
7
30
|
- Made the default `mpv` window open with `--autofit=80%`, keeping custom
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: plex-tui
|
|
3
|
-
Version: 0.4.
|
|
3
|
+
Version: 0.4.7
|
|
4
4
|
Summary: A small standalone Plex terminal UI.
|
|
5
5
|
Project-URL: Homepage, https://github.com/so1omon563/plex-tui
|
|
6
6
|
Project-URL: Issues, https://github.com/so1omon563/plex-tui/issues
|
|
@@ -44,23 +44,86 @@ Description-Content-Type: text/markdown
|
|
|
44
44
|
[](https://github.com/so1omon563/homebrew-plex-tui)
|
|
45
45
|
[](LICENSE)
|
|
46
46
|
|
|
47
|
-
A
|
|
48
|
-
through `mpv`.
|
|
47
|
+
A terminal Plex client built for watching media, not managing servers.
|
|
49
48
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
49
|
+
There are plenty of tools for administering Plex from the command line.
|
|
50
|
+
Surprisingly few are built for sitting down, browsing your library, and watching
|
|
51
|
+
something without leaving the terminal.
|
|
52
|
+
|
|
53
|
+
plex-tui is a standalone Textual application that brings Plex browsing, poster
|
|
54
|
+
artwork, collection cards, playlists, search, stream preferences, and `mpv`
|
|
55
|
+
playback into a keyboard-first terminal interface.
|
|
56
|
+
|
|
57
|
+
Built for people who spend their day in a terminal and would rather stay there.
|
|
58
|
+
|
|
59
|
+
## Why?
|
|
60
|
+
|
|
61
|
+
Most terminal Plex tools are built for administration, automation, or quick
|
|
62
|
+
status checks. Those are useful jobs, but they are not the same as browsing a
|
|
63
|
+
library, comparing options, and choosing something to watch.
|
|
64
|
+
|
|
65
|
+
Meanwhile, terminal applications got better. Tools like lazygit, gitui, btop,
|
|
66
|
+
and modern Textual apps raised the bar for what a TUI can be: rich layouts,
|
|
67
|
+
keyboard-first workflows, responsive interfaces, and even artwork are no longer
|
|
68
|
+
unusual.
|
|
69
|
+
|
|
70
|
+
plex-tui exists because browsing Plex and choosing something to watch deserves
|
|
71
|
+
that same kind of terminal-native experience.
|
|
72
|
+
|
|
73
|
+
## Project Status
|
|
74
|
+
|
|
75
|
+
plex-tui is still early, but already usable. Login, server selection, library
|
|
76
|
+
browsing, search, playlists, artwork, stream preferences, and playback are
|
|
77
|
+
working today. Expect rough edges, but expect progress too.
|
|
53
78
|
|
|
54
79
|
## Screenshots
|
|
55
80
|
|
|
56
|
-
###
|
|
81
|
+
### Movie grid
|
|
57
82
|
|
|
58
83
|

|
|
59
84
|
|
|
85
|
+
### TV show grid
|
|
86
|
+
|
|
87
|
+

|
|
88
|
+
|
|
89
|
+
### Collection cards
|
|
90
|
+
|
|
91
|
+

|
|
92
|
+
|
|
93
|
+

|
|
94
|
+
|
|
60
95
|
### List view
|
|
61
96
|
|
|
62
97
|

|
|
63
98
|
|
|
99
|
+
## Features
|
|
100
|
+
|
|
101
|
+
- Plex PIN login and server selection.
|
|
102
|
+
- Paged library browsing with automatic loading near the end of loaded items.
|
|
103
|
+
- Library submenu entrypoints for all items, Recommended, Collections,
|
|
104
|
+
Playlists, and Categories. Library rows open all items by default; Space
|
|
105
|
+
opens the browse-mode menu, and Settings can swap the primary and alternate
|
|
106
|
+
actions.
|
|
107
|
+
- Current-library search and bounded global search.
|
|
108
|
+
- List view plus configurable-density grid view with terminal poster artwork,
|
|
109
|
+
missing-artwork placeholders, and intentional glyph cards for collections and
|
|
110
|
+
hubs.
|
|
111
|
+
- External subtitle support and direct playback for embedded PGS/VOBSUB tracks.
|
|
112
|
+
- Audio and subtitle pickers with saved language preferences.
|
|
113
|
+
- Separate play-from-start and resume actions with Plex progress reporting.
|
|
114
|
+
- Watched/unwatched toggling for selected playable Plex items.
|
|
115
|
+
- Continue Watching episode rows show their show, season, and episode context,
|
|
116
|
+
and items can be removed from the Continue Watching view.
|
|
117
|
+
- Playlist management for creating playlists from selected media, adding media
|
|
118
|
+
to existing playlists, and removing items while browsing a playlist.
|
|
119
|
+
- Movie editions appear as distinct variants when Plex reports multiple
|
|
120
|
+
editions for a selected movie.
|
|
121
|
+
- Settings screen for stream preferences, playback mode and transcode quality,
|
|
122
|
+
artwork modes, grid density, page size, auto-load threshold, grid artwork
|
|
123
|
+
prefetching, media view, library Enter behavior, and `mpv` window size.
|
|
124
|
+
- App diagnostics view for version, paths, `mpv`, Plex connection, artwork, and
|
|
125
|
+
browsing settings.
|
|
126
|
+
|
|
64
127
|
## Requirements
|
|
65
128
|
|
|
66
129
|
- Python 3.11 or newer
|
|
@@ -95,9 +158,9 @@ plex-tui
|
|
|
95
158
|
```
|
|
96
159
|
|
|
97
160
|
This is the recommended cross-platform install path. It keeps Python
|
|
98
|
-
dependencies isolated, but you still need to install `mpv` separately.
|
|
99
|
-
|
|
100
|
-
|
|
161
|
+
dependencies isolated, but you still need to install `mpv` separately. If
|
|
162
|
+
`pipx` is not installed, install it with your platform package manager first or
|
|
163
|
+
follow the pipx installation guide.
|
|
101
164
|
|
|
102
165
|
### Homebrew
|
|
103
166
|
|
|
@@ -108,14 +171,11 @@ brew install plex-tui
|
|
|
108
171
|
plex-tui --smoke
|
|
109
172
|
```
|
|
110
173
|
|
|
111
|
-
The Homebrew formula installs `mpv` automatically. Apple Silicon macOS
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
Homebrew 6 requires non-official taps to be trusted before Homebrew loads
|
|
117
|
-
formulae from them. `plex-tui` only depends on formulae from Homebrew/core, so no
|
|
118
|
-
additional tap trust is required for its dependencies.
|
|
174
|
+
The Homebrew formula installs `mpv` automatically. Apple Silicon macOS uses
|
|
175
|
+
prebuilt bottles when available, while Intel macOS still uses Homebrew's
|
|
176
|
+
source-build path. Homebrew 6 requires non-official taps to be trusted before
|
|
177
|
+
loading formulae from them; `plex-tui` only depends on formulae from
|
|
178
|
+
Homebrew/core, so no additional tap trust is required for dependencies.
|
|
119
179
|
|
|
120
180
|
### Arch Linux
|
|
121
181
|
|
|
@@ -131,7 +191,7 @@ example.
|
|
|
131
191
|
|
|
132
192
|
```bash
|
|
133
193
|
pipx install "git+https://github.com/so1omon563/plex-tui.git"
|
|
134
|
-
pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.
|
|
194
|
+
pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.4.4"
|
|
135
195
|
```
|
|
136
196
|
|
|
137
197
|
Use this path for testing `main` before a tagged/PyPI release.
|
|
@@ -211,6 +271,10 @@ comfortable size on modern displays; Settings can override this with values
|
|
|
211
271
|
such as `90%`, `1280x720`, or `80%x80%`. If an older config has an exact
|
|
212
272
|
`mpv_window_size = "1280x720"` override, cycle the mpv window-size setting once
|
|
213
273
|
to return to the Default preset.
|
|
274
|
+
Use `w` from a playable movie or episode to toggle its Plex watched state.
|
|
275
|
+
When playback is active, choosing an audio or subtitle track from the picker
|
|
276
|
+
also asks mpv to switch the active track when the launched stream exposes a
|
|
277
|
+
matching track.
|
|
214
278
|
|
|
215
279
|
## Key Bindings
|
|
216
280
|
|
|
@@ -224,6 +288,7 @@ to return to the Default preset.
|
|
|
224
288
|
| `tab` / `shift+tab` | Move focus |
|
|
225
289
|
| `l` | Focus libraries |
|
|
226
290
|
| `m` | Focus media |
|
|
291
|
+
| `space` | Run the alternate action for a selected library |
|
|
227
292
|
| `v` | Toggle list/grid view |
|
|
228
293
|
| `pageup` / `pagedown` | Move one page in grid view |
|
|
229
294
|
| `,` | Show settings |
|
|
@@ -231,25 +296,13 @@ to return to the Default preset.
|
|
|
231
296
|
| `enter` | Open selected item |
|
|
232
297
|
| `p` | Play selected item from the beginning |
|
|
233
298
|
| `r` | Resume selected item from the saved Plex position |
|
|
299
|
+
| `w` | Mark selected item watched / unwatched |
|
|
300
|
+
| `P` | Add selected playable item to a playlist |
|
|
301
|
+
| `backspace` / `delete` | Remove selected item from Continue Watching or a playlist |
|
|
234
302
|
| `a` / `s` | Choose audio / subtitle preference |
|
|
235
303
|
| `A` / `S` | Clear audio preference / cycle subtitle mode |
|
|
236
304
|
| `x` | Stop launched `mpv` |
|
|
237
305
|
|
|
238
|
-
## Features
|
|
239
|
-
|
|
240
|
-
- Plex PIN login and server selection.
|
|
241
|
-
- Paged library browsing with automatic loading near the end of loaded items.
|
|
242
|
-
- Current-library search and bounded global search.
|
|
243
|
-
- List view plus configurable-density grid view with terminal poster artwork.
|
|
244
|
-
- External subtitle support and direct playback for embedded PGS/VOBSUB tracks.
|
|
245
|
-
- Audio and subtitle pickers with saved language preferences.
|
|
246
|
-
- Separate play-from-start and resume actions with Plex progress reporting.
|
|
247
|
-
- Settings screen for stream preferences, playback mode and transcode quality,
|
|
248
|
-
artwork modes, grid density, page size, auto-load threshold, grid artwork
|
|
249
|
-
prefetching, media view, and `mpv` window size.
|
|
250
|
-
- App diagnostics view for version, paths, `mpv`, Plex connection, artwork, and
|
|
251
|
-
browsing settings.
|
|
252
|
-
|
|
253
306
|
## Artwork
|
|
254
307
|
|
|
255
308
|
Poster artwork renders as portable colored block art by default, so it works in
|
|
@@ -261,6 +314,12 @@ charge of layout and redraws while the terminal paints the poster inside those
|
|
|
261
314
|
cells. Outside detected Kitty-compatible terminals, `auto` falls back to block
|
|
262
315
|
art; `plex-tui --diagnostics` reports the active renderer status.
|
|
263
316
|
|
|
317
|
+
Cards that represent collections, playlists, categories, hubs, or query shelves
|
|
318
|
+
use geometric glyph artwork instead of pretending to be missing posters. Rows
|
|
319
|
+
made entirely of those cards use roomier navigation-grid spacing. See
|
|
320
|
+
`docs/collection-artwork-design.md` for the design notes behind that visual
|
|
321
|
+
language.
|
|
322
|
+
|
|
264
323
|
Grid view prefetches artwork for the visible page immediately and, by default,
|
|
265
324
|
prepares three pages ahead in the background. `grid_prefetch_pages` can be set
|
|
266
325
|
from `0` to `5`; use `0` to fetch only the visible page on slower systems.
|
|
@@ -7,23 +7,86 @@
|
|
|
7
7
|
[](https://github.com/so1omon563/homebrew-plex-tui)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
A
|
|
11
|
-
through `mpv`.
|
|
10
|
+
A terminal Plex client built for watching media, not managing servers.
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
There are plenty of tools for administering Plex from the command line.
|
|
13
|
+
Surprisingly few are built for sitting down, browsing your library, and watching
|
|
14
|
+
something without leaving the terminal.
|
|
15
|
+
|
|
16
|
+
plex-tui is a standalone Textual application that brings Plex browsing, poster
|
|
17
|
+
artwork, collection cards, playlists, search, stream preferences, and `mpv`
|
|
18
|
+
playback into a keyboard-first terminal interface.
|
|
19
|
+
|
|
20
|
+
Built for people who spend their day in a terminal and would rather stay there.
|
|
21
|
+
|
|
22
|
+
## Why?
|
|
23
|
+
|
|
24
|
+
Most terminal Plex tools are built for administration, automation, or quick
|
|
25
|
+
status checks. Those are useful jobs, but they are not the same as browsing a
|
|
26
|
+
library, comparing options, and choosing something to watch.
|
|
27
|
+
|
|
28
|
+
Meanwhile, terminal applications got better. Tools like lazygit, gitui, btop,
|
|
29
|
+
and modern Textual apps raised the bar for what a TUI can be: rich layouts,
|
|
30
|
+
keyboard-first workflows, responsive interfaces, and even artwork are no longer
|
|
31
|
+
unusual.
|
|
32
|
+
|
|
33
|
+
plex-tui exists because browsing Plex and choosing something to watch deserves
|
|
34
|
+
that same kind of terminal-native experience.
|
|
35
|
+
|
|
36
|
+
## Project Status
|
|
37
|
+
|
|
38
|
+
plex-tui is still early, but already usable. Login, server selection, library
|
|
39
|
+
browsing, search, playlists, artwork, stream preferences, and playback are
|
|
40
|
+
working today. Expect rough edges, but expect progress too.
|
|
16
41
|
|
|
17
42
|
## Screenshots
|
|
18
43
|
|
|
19
|
-
###
|
|
44
|
+
### Movie grid
|
|
20
45
|
|
|
21
46
|

|
|
22
47
|
|
|
48
|
+
### TV show grid
|
|
49
|
+
|
|
50
|
+

|
|
51
|
+
|
|
52
|
+
### Collection cards
|
|
53
|
+
|
|
54
|
+

|
|
55
|
+
|
|
56
|
+

|
|
57
|
+
|
|
23
58
|
### List view
|
|
24
59
|
|
|
25
60
|

|
|
26
61
|
|
|
62
|
+
## Features
|
|
63
|
+
|
|
64
|
+
- Plex PIN login and server selection.
|
|
65
|
+
- Paged library browsing with automatic loading near the end of loaded items.
|
|
66
|
+
- Library submenu entrypoints for all items, Recommended, Collections,
|
|
67
|
+
Playlists, and Categories. Library rows open all items by default; Space
|
|
68
|
+
opens the browse-mode menu, and Settings can swap the primary and alternate
|
|
69
|
+
actions.
|
|
70
|
+
- Current-library search and bounded global search.
|
|
71
|
+
- List view plus configurable-density grid view with terminal poster artwork,
|
|
72
|
+
missing-artwork placeholders, and intentional glyph cards for collections and
|
|
73
|
+
hubs.
|
|
74
|
+
- External subtitle support and direct playback for embedded PGS/VOBSUB tracks.
|
|
75
|
+
- Audio and subtitle pickers with saved language preferences.
|
|
76
|
+
- Separate play-from-start and resume actions with Plex progress reporting.
|
|
77
|
+
- Watched/unwatched toggling for selected playable Plex items.
|
|
78
|
+
- Continue Watching episode rows show their show, season, and episode context,
|
|
79
|
+
and items can be removed from the Continue Watching view.
|
|
80
|
+
- Playlist management for creating playlists from selected media, adding media
|
|
81
|
+
to existing playlists, and removing items while browsing a playlist.
|
|
82
|
+
- Movie editions appear as distinct variants when Plex reports multiple
|
|
83
|
+
editions for a selected movie.
|
|
84
|
+
- Settings screen for stream preferences, playback mode and transcode quality,
|
|
85
|
+
artwork modes, grid density, page size, auto-load threshold, grid artwork
|
|
86
|
+
prefetching, media view, library Enter behavior, and `mpv` window size.
|
|
87
|
+
- App diagnostics view for version, paths, `mpv`, Plex connection, artwork, and
|
|
88
|
+
browsing settings.
|
|
89
|
+
|
|
27
90
|
## Requirements
|
|
28
91
|
|
|
29
92
|
- Python 3.11 or newer
|
|
@@ -58,9 +121,9 @@ plex-tui
|
|
|
58
121
|
```
|
|
59
122
|
|
|
60
123
|
This is the recommended cross-platform install path. It keeps Python
|
|
61
|
-
dependencies isolated, but you still need to install `mpv` separately.
|
|
62
|
-
|
|
63
|
-
|
|
124
|
+
dependencies isolated, but you still need to install `mpv` separately. If
|
|
125
|
+
`pipx` is not installed, install it with your platform package manager first or
|
|
126
|
+
follow the pipx installation guide.
|
|
64
127
|
|
|
65
128
|
### Homebrew
|
|
66
129
|
|
|
@@ -71,14 +134,11 @@ brew install plex-tui
|
|
|
71
134
|
plex-tui --smoke
|
|
72
135
|
```
|
|
73
136
|
|
|
74
|
-
The Homebrew formula installs `mpv` automatically. Apple Silicon macOS
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
Homebrew 6 requires non-official taps to be trusted before Homebrew loads
|
|
80
|
-
formulae from them. `plex-tui` only depends on formulae from Homebrew/core, so no
|
|
81
|
-
additional tap trust is required for its dependencies.
|
|
137
|
+
The Homebrew formula installs `mpv` automatically. Apple Silicon macOS uses
|
|
138
|
+
prebuilt bottles when available, while Intel macOS still uses Homebrew's
|
|
139
|
+
source-build path. Homebrew 6 requires non-official taps to be trusted before
|
|
140
|
+
loading formulae from them; `plex-tui` only depends on formulae from
|
|
141
|
+
Homebrew/core, so no additional tap trust is required for dependencies.
|
|
82
142
|
|
|
83
143
|
### Arch Linux
|
|
84
144
|
|
|
@@ -94,7 +154,7 @@ example.
|
|
|
94
154
|
|
|
95
155
|
```bash
|
|
96
156
|
pipx install "git+https://github.com/so1omon563/plex-tui.git"
|
|
97
|
-
pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.
|
|
157
|
+
pipx install "git+https://github.com/so1omon563/plex-tui.git@v0.4.4"
|
|
98
158
|
```
|
|
99
159
|
|
|
100
160
|
Use this path for testing `main` before a tagged/PyPI release.
|
|
@@ -174,6 +234,10 @@ comfortable size on modern displays; Settings can override this with values
|
|
|
174
234
|
such as `90%`, `1280x720`, or `80%x80%`. If an older config has an exact
|
|
175
235
|
`mpv_window_size = "1280x720"` override, cycle the mpv window-size setting once
|
|
176
236
|
to return to the Default preset.
|
|
237
|
+
Use `w` from a playable movie or episode to toggle its Plex watched state.
|
|
238
|
+
When playback is active, choosing an audio or subtitle track from the picker
|
|
239
|
+
also asks mpv to switch the active track when the launched stream exposes a
|
|
240
|
+
matching track.
|
|
177
241
|
|
|
178
242
|
## Key Bindings
|
|
179
243
|
|
|
@@ -187,6 +251,7 @@ to return to the Default preset.
|
|
|
187
251
|
| `tab` / `shift+tab` | Move focus |
|
|
188
252
|
| `l` | Focus libraries |
|
|
189
253
|
| `m` | Focus media |
|
|
254
|
+
| `space` | Run the alternate action for a selected library |
|
|
190
255
|
| `v` | Toggle list/grid view |
|
|
191
256
|
| `pageup` / `pagedown` | Move one page in grid view |
|
|
192
257
|
| `,` | Show settings |
|
|
@@ -194,25 +259,13 @@ to return to the Default preset.
|
|
|
194
259
|
| `enter` | Open selected item |
|
|
195
260
|
| `p` | Play selected item from the beginning |
|
|
196
261
|
| `r` | Resume selected item from the saved Plex position |
|
|
262
|
+
| `w` | Mark selected item watched / unwatched |
|
|
263
|
+
| `P` | Add selected playable item to a playlist |
|
|
264
|
+
| `backspace` / `delete` | Remove selected item from Continue Watching or a playlist |
|
|
197
265
|
| `a` / `s` | Choose audio / subtitle preference |
|
|
198
266
|
| `A` / `S` | Clear audio preference / cycle subtitle mode |
|
|
199
267
|
| `x` | Stop launched `mpv` |
|
|
200
268
|
|
|
201
|
-
## Features
|
|
202
|
-
|
|
203
|
-
- Plex PIN login and server selection.
|
|
204
|
-
- Paged library browsing with automatic loading near the end of loaded items.
|
|
205
|
-
- Current-library search and bounded global search.
|
|
206
|
-
- List view plus configurable-density grid view with terminal poster artwork.
|
|
207
|
-
- External subtitle support and direct playback for embedded PGS/VOBSUB tracks.
|
|
208
|
-
- Audio and subtitle pickers with saved language preferences.
|
|
209
|
-
- Separate play-from-start and resume actions with Plex progress reporting.
|
|
210
|
-
- Settings screen for stream preferences, playback mode and transcode quality,
|
|
211
|
-
artwork modes, grid density, page size, auto-load threshold, grid artwork
|
|
212
|
-
prefetching, media view, and `mpv` window size.
|
|
213
|
-
- App diagnostics view for version, paths, `mpv`, Plex connection, artwork, and
|
|
214
|
-
browsing settings.
|
|
215
|
-
|
|
216
269
|
## Artwork
|
|
217
270
|
|
|
218
271
|
Poster artwork renders as portable colored block art by default, so it works in
|
|
@@ -224,6 +277,12 @@ charge of layout and redraws while the terminal paints the poster inside those
|
|
|
224
277
|
cells. Outside detected Kitty-compatible terminals, `auto` falls back to block
|
|
225
278
|
art; `plex-tui --diagnostics` reports the active renderer status.
|
|
226
279
|
|
|
280
|
+
Cards that represent collections, playlists, categories, hubs, or query shelves
|
|
281
|
+
use geometric glyph artwork instead of pretending to be missing posters. Rows
|
|
282
|
+
made entirely of those cards use roomier navigation-grid spacing. See
|
|
283
|
+
`docs/collection-artwork-design.md` for the design notes behind that visual
|
|
284
|
+
language.
|
|
285
|
+
|
|
227
286
|
Grid view prefetches artwork for the visible page immediately and, by default,
|
|
228
287
|
prepares three pages ahead in the background. `grid_prefetch_pages` can be set
|
|
229
288
|
from `0` to `5`; use `0` to fetch only the visible page on slower systems.
|
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
## App UX
|
|
4
4
|
|
|
5
|
-
- Continue refining grid view presentation after the
|
|
6
|
-
|
|
5
|
+
- Continue refining grid view presentation after the collection-card artwork
|
|
6
|
+
pass, especially against real terminal themes, wide/narrow panes, and
|
|
7
|
+
screenshot refreshes.
|
|
7
8
|
- Continue tuning focus, row markers, and selection affordances based on real
|
|
8
9
|
terminal themes. Status hints should keep a compact context prefix such as
|
|
9
10
|
`Media:`, `Grid:`, or `Settings:` so the active pane is clear at a glance.
|
|
@@ -47,19 +48,32 @@
|
|
|
47
48
|
[`anthonycaccese/240-MP`](https://github.com/anthonycaccese/240-MP/tree/main)
|
|
48
49
|
live in `docs/plex-integration-research.md`.
|
|
49
50
|
- Continue Watching now has a sidebar browse entrypoint backed by Plex on-deck
|
|
50
|
-
data;
|
|
51
|
+
data; selected items can be removed from Continue Watching. Watch for
|
|
52
|
+
real-library edge cases around ordering and pagination.
|
|
51
53
|
- Selective library visibility is available in Settings so noisy Plex libraries
|
|
52
54
|
can be hidden from the sidebar.
|
|
53
|
-
- Library submenus are available for Library, Recommended, Collections,
|
|
54
|
-
Playlists
|
|
55
|
-
|
|
55
|
+
- Library submenus are available for Library, Recommended, Collections,
|
|
56
|
+
Playlists, and Categories. Categories use PlexAPI category helpers when
|
|
57
|
+
present and genre filter choices as the fallback. Library rows open all items
|
|
58
|
+
by default, Space opens the browse-mode menu, and Settings can swap those
|
|
59
|
+
primary/alternate actions.
|
|
56
60
|
- Alphabet navigation is available for loaded browse lists and grids with
|
|
57
61
|
previous/next section jumps.
|
|
58
62
|
- Explicit playback controls are available for play-from-start versus resume,
|
|
59
63
|
direct/default playback versus selected transcode quality presets, and
|
|
60
64
|
Plex-side resume offsets for transcoded streams.
|
|
61
|
-
-
|
|
62
|
-
|
|
65
|
+
- Watched/unwatched toggling is available for selected playable movies and
|
|
66
|
+
episodes.
|
|
67
|
+
- Movie editions are visible as distinct variants when Plex reports multiple
|
|
68
|
+
editions for a selected movie.
|
|
69
|
+
- In-playback audio/subtitle switching uses mpv IPC when the active stream
|
|
70
|
+
exposes matching tracks; Plex-transcoded streams may still require relaunching
|
|
71
|
+
with the saved preference.
|
|
72
|
+
- Playlist management can create playlists from selected media, add selected
|
|
73
|
+
media to existing playlists, and remove items while browsing a playlist.
|
|
74
|
+
Continue design passes for bulk playlist actions and richer playlist editing
|
|
75
|
+
if real-library use shows those workflows are needed.
|
|
76
|
+
- Later design passes: profile switching with auto sign-in.
|
|
63
77
|
|
|
64
78
|
## Technical Follow-Up
|
|
65
79
|
|
|
@@ -52,6 +52,10 @@ client_identifier = "plex-tui-your-stable-client-id"
|
|
|
52
52
|
# detail_artwork_mode = "list_only"
|
|
53
53
|
# media_view can be "list" or "grid".
|
|
54
54
|
# media_view = "list"
|
|
55
|
+
# library_enter_action can be "library" or "browse_modes". The default
|
|
56
|
+
# "library" opens all items with Enter and uses Space for browse modes.
|
|
57
|
+
# "browse_modes" swaps those two actions.
|
|
58
|
+
# library_enter_action = "library"
|
|
55
59
|
# grid_density can be "compact", "comfortable", or "large".
|
|
56
60
|
# grid_density = "comfortable"
|
|
57
61
|
# Textual theme selected from the command palette.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Collection Artwork Design
|
|
2
|
+
|
|
3
|
+
`plex-tui` uses real Plex artwork whenever Plex provides media posters,
|
|
4
|
+
episode stills, season art, or collection art. The collection artwork system is
|
|
5
|
+
for a different state: browse cards that represent organization instead of
|
|
6
|
+
media.
|
|
7
|
+
|
|
8
|
+
## Visual Language
|
|
9
|
+
|
|
10
|
+
Collection cards should feel like wayfinding and information architecture, not
|
|
11
|
+
fake posters. The first version uses terminal-native geometric glyphs on muted
|
|
12
|
+
blueprint-style panels:
|
|
13
|
+
|
|
14
|
+
- poster or still: actual media artwork;
|
|
15
|
+
- missing poster: quiet missing-artwork block;
|
|
16
|
+
- collection card: intentional glyph for a hub, playlist, category, or query.
|
|
17
|
+
|
|
18
|
+
The glyph is the dominant artwork element. A faint construction layer of corner
|
|
19
|
+
marks, guide dots, and center lines sits behind the glyph so the card feels like
|
|
20
|
+
part of a deliberate wayfinding system instead of an empty color field. Title,
|
|
21
|
+
type, and action remain in the normal grid-card text below the artwork so the
|
|
22
|
+
visual stays calm at compact terminal sizes.
|
|
23
|
+
|
|
24
|
+
## Glyph System
|
|
25
|
+
|
|
26
|
+
Glyphs are selected from stable media metadata first, then title hints when Plex
|
|
27
|
+
only reports a generic hub object.
|
|
28
|
+
|
|
29
|
+
- Continue Watching: play/progress mark.
|
|
30
|
+
- Recently Added: plus/cross mark.
|
|
31
|
+
- Recently Released: burst mark.
|
|
32
|
+
- Recommended: connected-node constellation.
|
|
33
|
+
- Trending and Top shelves: upward path.
|
|
34
|
+
- Unwatched shelves: hollow circles.
|
|
35
|
+
- Actor shelves: simplified person.
|
|
36
|
+
- Genre and category cards: one shared family with title-derived motif
|
|
37
|
+
variations, such as angled marks for action, circles for comedy, diamonds for
|
|
38
|
+
horror, and grid marks for documentary.
|
|
39
|
+
- Playlist cards: layered panel.
|
|
40
|
+
- Collection cards: repeated diamond mark.
|
|
41
|
+
- Generic hubs: abstract geometric mark.
|
|
42
|
+
|
|
43
|
+
The system is intentionally small and text-based so it remains legible in
|
|
44
|
+
compact grids, plain terminals, Kitty/Ghostty image modes, and low-resolution
|
|
45
|
+
remote sessions. New glyphs should use the same line weight, centered geometry,
|
|
46
|
+
and blueprint layer so they read as symbols from one fictional design system,
|
|
47
|
+
not unrelated icons.
|
|
48
|
+
|
|
49
|
+
## Grid Behavior
|
|
50
|
+
|
|
51
|
+
Rows made entirely of collection cards use a navigation-grid treatment instead
|
|
52
|
+
of poster-grid treatment. They are left aligned and separated by a blank row so
|
|
53
|
+
views like Recommended read as deliberate browse choices instead of a compact
|
|
54
|
+
cluster of failed posters.
|
|
55
|
+
|
|
56
|
+
Mixed rows or playable-media rows continue to use the centered poster-grid
|
|
57
|
+
presentation.
|
|
58
|
+
|
|
59
|
+
## Screenshots
|
|
60
|
+
|
|
61
|
+
Current examples live in the README screenshot set:
|
|
62
|
+
|
|
63
|
+
- `docs/assets/collection-recommended.png`
|
|
64
|
+
- `docs/assets/collection-categories.png`
|
|
65
|
+
- `docs/assets/grid-view.png`
|
|
66
|
+
- `docs/assets/grid-tv-shows.png`
|
|
67
|
+
- `docs/assets/list-view.png`
|
|
68
|
+
|
|
69
|
+
## Expansion Notes
|
|
70
|
+
|
|
71
|
+
Future iterations can reuse these glyphs in sidebar navigation, filters,
|
|
72
|
+
badges, and search result indicators. New glyphs should stay geometric,
|
|
73
|
+
low-detail, and readable at compact density before they are added.
|
|
@@ -39,44 +39,36 @@ Already covered:
|
|
|
39
39
|
- Plex PIN login and server selection.
|
|
40
40
|
- Library list browsing with paged loading and automatic load-more.
|
|
41
41
|
- Continue Watching as a top-level browse entry.
|
|
42
|
+
- Removing selected items from Continue Watching.
|
|
42
43
|
- Selective library display in Settings.
|
|
43
44
|
- Library submenus for Library, Recommended, Collections, and Playlists.
|
|
45
|
+
- Library Categories through PlexAPI category helpers or genre filter choices.
|
|
46
|
+
- Library rows open all items by default, with Space as the alternate
|
|
47
|
+
browse-mode menu action and a global Settings toggle to swap the behavior.
|
|
44
48
|
- Alphabet navigation for loaded browse lists and grids.
|
|
45
49
|
- Current-library and global search.
|
|
46
50
|
- Show/season/episode child browsing through PlexAPI child helpers.
|
|
47
51
|
- Separate play-from-start and resume controls, including Plex-side resume
|
|
48
52
|
offsets for transcoded streams and progress reporting.
|
|
49
53
|
- Saved audio/subtitle language preferences plus per-item stream pickers.
|
|
54
|
+
- Live audio/subtitle switching through mpv IPC when the active stream exposes
|
|
55
|
+
matching tracks.
|
|
50
56
|
- Direct playback paths where possible, with transcode fallback through PlexAPI.
|
|
51
57
|
- Explicit video quality/direct/transcode preference in Settings and playback.
|
|
52
58
|
- Details pane metadata, audio/subtitle stream display, and playback readiness.
|
|
59
|
+
- Playlist management for creating playlists from selected media, adding media
|
|
60
|
+
to existing playlists, and removing items from playlist views.
|
|
53
61
|
|
|
54
62
|
Not yet covered:
|
|
55
63
|
|
|
56
|
-
-
|
|
57
|
-
- Library Categories where PlexAPI exposes them cleanly.
|
|
58
|
-
- Movie editions as distinct, visible item variants.
|
|
59
|
-
- In-playback audio/subtitle switching after mpv has launched.
|
|
64
|
+
- Fuller profile switching and auto sign-in.
|
|
60
65
|
|
|
61
66
|
## Recommended Sequence
|
|
62
67
|
|
|
63
|
-
1.
|
|
64
|
-
Add Categories to the library submenu after mapping PlexAPI support against
|
|
65
|
-
real server responses. Keep the default browse path simple so
|
|
66
|
-
Enter-on-library behavior stays fast.
|
|
67
|
-
|
|
68
|
-
2. Profile switching and auto sign-in.
|
|
68
|
+
1. Profile switching and auto sign-in.
|
|
69
69
|
Useful, but more invasive than the browse entrypoints because it changes auth
|
|
70
70
|
and account-token assumptions. Treat it as a separate design pass.
|
|
71
71
|
|
|
72
|
-
3. Movie editions.
|
|
73
|
-
Surface editions as distinct item variants once enough real-library examples
|
|
74
|
-
are available to keep the UI compact.
|
|
75
|
-
|
|
76
|
-
4. In-playback track switching.
|
|
77
|
-
Defer until there is a clear design for driving mpv IPC track changes and
|
|
78
|
-
reconciling Plex stream state after launch.
|
|
79
|
-
|
|
80
72
|
## Design Notes for plex-tui
|
|
81
73
|
|
|
82
74
|
- Keep terminal-first density. Prefer list entrypoints and status/detail text
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
pkgbase = plex-tui
|
|
2
2
|
pkgdesc = Standalone Plex terminal UI with mpv playback
|
|
3
|
-
pkgver = 0.4.
|
|
3
|
+
pkgver = 0.4.4
|
|
4
4
|
pkgrel = 1
|
|
5
5
|
url = https://github.com/so1omon563/plex-tui
|
|
6
6
|
arch = any
|
|
@@ -16,7 +16,7 @@ pkgbase = plex-tui
|
|
|
16
16
|
depends = python-plexapi
|
|
17
17
|
depends = python-rich
|
|
18
18
|
depends = python-textual
|
|
19
|
-
source = plex-tui-0.4.
|
|
20
|
-
sha256sums =
|
|
19
|
+
source = plex-tui-0.4.4.tar.gz::https://github.com/so1omon563/plex-tui/archive/refs/tags/v0.4.4.tar.gz
|
|
20
|
+
sha256sums = 77cddf1fa9117ae4f9030767968783e88f49300d9fc8bb01fbb5ded80993db7b
|
|
21
21
|
|
|
22
22
|
pkgname = plex-tui
|