plexbar 0.1.2__tar.gz

plexbar-0.1.2/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: plexbar
+Version: 0.1.2
+Summary: A command-line TUI music player for Plex
+Author: Christopher Patti
+Author-email: Christopher Patti <feoh@feoh.org>
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: plexapi>=4.18.1
+Requires-Dist: textual>=8.2.7
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# 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, and Playlists
+- Search your Plex music library
+- Queue tracks, albums, artists, and playlists
+- 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 token
+
+## 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 token
+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. Do not
+commit or share your Plex token.
+
+### Finding your Plex token
+
+One common method:
+
+1. Open Plex Web and sign in.
+2. Open browser developer tools.
+3. Go to the Network tab.
+4. Refresh Plex Web or browse to a media item.
+5. Search requests for `X-Plex-Token`.
+6. Copy the token value only.
+
+## Usage
+
+The top-level browser contains:
+
+- Artists
+- Albums
+- Tracks
+- Playlists
+
+Press `Enter` to drill down into artists, albums, and playlists. 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 immediately and replace queue |
+| `a` | Append focused track/album/artist/playlist 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
+```
+
+## Current limitations
+
+Plexbar currently launches `mpv` as a subprocess for each track. Future versions
+may switch to mpv IPC for richer playback state and automatic end-of-track
+advancement.

plexbar-0.1.2/README.md

@@ -0,0 +1,107 @@
+# 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, and Playlists
+- Search your Plex music library
+- Queue tracks, albums, artists, and playlists
+- 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 token
+
+## 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 token
+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. Do not
+commit or share your Plex token.
+
+### Finding your Plex token
+
+One common method:
+
+1. Open Plex Web and sign in.
+2. Open browser developer tools.
+3. Go to the Network tab.
+4. Refresh Plex Web or browse to a media item.
+5. Search requests for `X-Plex-Token`.
+6. Copy the token value only.
+
+## Usage
+
+The top-level browser contains:
+
+- Artists
+- Albums
+- Tracks
+- Playlists
+
+Press `Enter` to drill down into artists, albums, and playlists. 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 immediately and replace queue |
+| `a` | Append focused track/album/artist/playlist 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
+```
+
+## Current limitations
+
+Plexbar currently launches `mpv` as a subprocess for each track. Future versions
+may switch to mpv IPC for richer playback state and automatic end-of-track
+advancement.

plexbar-0.1.2/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "plexbar"
+version = "0.1.2"
+description = "A command-line TUI music player for Plex"
+readme = "README.md"
+authors = [{ name = "Christopher Patti", email = "feoh@feoh.org" }]
+requires-python = ">=3.12"
+dependencies = ["platformdirs>=4.10.0", "plexapi>=4.18.1", "textual>=8.2.7"]
+
+[project.scripts]
+plexbar = "plexbar.app:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.3",
+    "ruff>=0.15.16",
+]

plexbar-0.1.2/src/plexbar/__init__.py

@@ -0,0 +1 @@
+"""Plexbar package."""

plexbar-0.1.2/src/plexbar/__main__.py

@@ -0,0 +1,6 @@
+"""Run Plexbar as a module."""
+
+from .app import main
+
+if __name__ == "__main__":
+    main()

plexbar-0.1.2/src/plexbar/app.py

@@ -0,0 +1,411 @@
+"""Textual application for Plexbar."""
+
+from collections.abc import Callable
+
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.screen import Screen
+from textual.widgets import (
+    Button,
+    Footer,
+    Header,
+    Input,
+    Label,
+    ListItem,
+    ListView,
+    Static,
+)
+
+from plexbar.models import BrowserItem, ItemKind, QueueTrack
+from plexbar.playback import MpvNotFoundError, MpvPlayer, PlaybackQueue
+from plexbar.plex_client import PlexMusicClient
+from plexbar.settings import (
+    CONFIG_PATH,
+    PlexbarConfig,
+    config_exists,
+    load_config,
+    save_config,
+)
+
+
+class BrowserRow(ListItem):
+    """List item that carries a BrowserItem payload."""
+
+    def __init__(self, item: BrowserItem) -> None:
+        super().__init__(Label(item.display_title))
+        self.item = item
+
+
+class SetupScreen(Screen[None]):
+    """First-run Plex configuration screen."""
+
+    CSS = """
+    SetupScreen {
+        align: center middle;
+    }
+
+    #setup-box {
+        width: 70;
+        height: auto;
+        border: round $accent;
+        padding: 1 2;
+    }
+
+    #setup-status {
+        min-height: 3;
+    }
+    """
+
+    def __init__(self, on_configured: Callable[[PlexbarConfig], None]) -> None:
+        super().__init__()
+        self._on_configured = on_configured
+        self._base_url = ""
+        self._token = ""
+        self._libraries: list[str] = []
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="setup-box"):
+            yield Label("Plexbar first-run setup")
+            yield Label("Plex base URL")
+            yield Input(placeholder="http://127.0.0.1:32400", id="plex-url")
+            yield Label("Plex token")
+            yield Input(password=True, placeholder="Your Plex token", id="plex-token")
+            yield Button("Validate connection", id="validate", variant="primary")
+            yield Static("Enter your Plex connection details.", id="setup-status")
+            yield ListView(id="library-list")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one("#library-list", ListView).display = False
+        self.query_one("#plex-url", Input).focus()
+
+    @on(Button.Pressed, "#validate")
+    def validate_connection(self) -> None:
+        """Validate credentials and load music libraries."""
+
+        base_url = self.query_one("#plex-url", Input).value.strip()
+        token = self.query_one("#plex-token", Input).value.strip()
+        if not base_url or not token:
+            self._set_status("Plex URL and token are required.")
+            return
+        self._base_url = base_url
+        self._token = token
+        self._set_status("Validating Plex connection…")
+        self._validate_connection(base_url, token)
+
+    @work(thread=True)
+    def _validate_connection(self, base_url: str, token: str) -> None:
+        try:
+            libraries = PlexMusicClient.validate(base_url, token)
+        except Exception as exc:  # noqa: BLE001 - display connection failures to user
+            self.app.call_from_thread(self._show_validation_error, str(exc))
+            return
+        self.app.call_from_thread(self._show_libraries, libraries)
+
+    def _show_validation_error(self, message: str) -> None:
+        self._set_status(f"Connection failed: {message}")
+
+    def _show_libraries(self, libraries: list[str]) -> None:
+        self._libraries = libraries
+        if not libraries:
+            self._set_status("Connected, but no music libraries were found.")
+            return
+        library_list = self.query_one("#library-list", ListView)
+        library_list.clear()
+        for library in libraries:
+            library_list.append(BrowserRow(BrowserItem(library, ItemKind.ROOT)))
+        library_list.display = True
+        library_list.focus()
+        self._set_status("Select a default music library and press Enter.")
+
+    @on(ListView.Selected, "#library-list")
+    def save_selected_library(self, event: ListView.Selected) -> None:
+        """Persist selected library and continue into the app."""
+
+        row = event.item
+        if not isinstance(row, BrowserRow):
+            return
+        config = PlexbarConfig(
+            base_url=self._base_url,
+            token=self._token,
+            default_library=row.item.title,
+        )
+        save_config(config)
+        self._on_configured(config)
+        self.dismiss()
+
+    def _set_status(self, message: str) -> None:
+        self.query_one("#setup-status", Static).update(message)
+
+
+class PlexbarApp(App[None]):
+    """Plex music player TUI."""
+
+    CSS = """
+    #browser {
+        width: 2fr;
+        border: round $primary;
+    }
+
+    #side {
+        width: 1fr;
+        border: round $secondary;
+    }
+
+    #search {
+        dock: top;
+    }
+
+    #status {
+        dock: bottom;
+        height: 3;
+        border-top: solid $primary;
+    }
+
+    .panel-title {
+        text-style: bold;
+        padding: 0 1;
+    }
+    """
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("/", "search", "Search"),
+        Binding("enter", "select", "Select/enqueue"),
+        Binding("p", "play_now", "Play now"),
+        Binding("a", "append", "Append"),
+        Binding("space", "pause_resume", "Pause/resume"),
+        Binding("n", "next_track", "Next"),
+        Binding("s", "stop", "Stop"),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.config: PlexbarConfig | None = None
+        self.client: PlexMusicClient | None = None
+        self.player: MpvPlayer | None = None
+        self.queue = PlaybackQueue()
+        self.history: list[list[BrowserItem]] = []
+        self.items: list[BrowserItem] = []
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Input(placeholder="Search Plex music…", id="search")
+        with Horizontal():
+            with Vertical(id="browser"):
+                yield Label("Browse", classes="panel-title")
+                yield ListView(id="browser-list")
+            with Vertical(id="side"):
+                yield Label("Now Playing", classes="panel-title")
+                yield Static("Nothing playing", id="now-playing")
+                yield Label("Queue", classes="panel-title")
+                yield Static("Queue is empty", id="queue")
+        yield Static("Starting Plexbar…", id="status")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one("#search", Input).display = False
+        if config_exists():
+            try:
+                self.start_with_config(load_config())
+            except Exception as exc:  # noqa: BLE001 - show config failures in TUI
+                self.set_status(f"Failed to load {CONFIG_PATH}: {exc}")
+                self.push_screen(SetupScreen(self.start_with_config))
+        else:
+            self.push_screen(SetupScreen(self.start_with_config))
+
+    def start_with_config(self, config: PlexbarConfig) -> None:
+        """Connect to Plex and initialize playback/browsing."""
+
+        self.config = config
+        self.set_status("Connecting to Plex…")
+        self._connect(config)
+
+    @work(thread=True)
+    def _connect(self, config: PlexbarConfig) -> None:
+        try:
+            client = PlexMusicClient(config)
+            player = MpvPlayer()
+        except MpvNotFoundError as exc:
+            self.call_from_thread(self.set_status, str(exc))
+            return
+        except Exception as exc:  # noqa: BLE001 - show connection failures in TUI
+            self.call_from_thread(self.set_status, f"Plex connection failed: {exc}")
+            return
+        self.call_from_thread(self._connected, client, player)
+
+    def _connected(self, client: PlexMusicClient, player: MpvPlayer) -> None:
+        self.client = client
+        self.player = player
+        self.show_items(
+            client.root_items(), "Connected. Choose a section.", remember=False
+        )
+
+    def show_items(
+        self, items: list[BrowserItem], status: str, *, remember: bool = True
+    ) -> None:
+        """Display browser items."""
+
+        if remember and self.items:
+            self.history.append(self.items)
+        self.items = items
+        browser = self.query_one("#browser-list", ListView)
+        browser.clear()
+        if self.history:
+            browser.append(BrowserRow(BrowserItem("..", ItemKind.BACK)))
+        for item in items:
+            browser.append(BrowserRow(item))
+        browser.focus()
+        self.set_status(status)
+
+    async def action_quit(self) -> None:
+        """Stop playback before exiting Plexbar."""
+
+        if self.player is not None:
+            self.player.stop()
+        self.exit()
+
+    def action_search(self) -> None:
+        search = self.query_one("#search", Input)
+        search.display = True
+        search.focus()
+
+    @on(Input.Submitted, "#search")
+    def perform_search(self, event: Input.Submitted) -> None:
+        query = event.value.strip()
+        search = self.query_one("#search", Input)
+        search.display = False
+        search.value = ""
+        if not query or self.client is None:
+            return
+        self.show_items(self.client.search(query), f"Search results for '{query}'.")
+
+    @on(ListView.Selected, "#browser-list")
+    def select_browser_row(self, event: ListView.Selected) -> None:
+        """Handle Enter on the browser list.
+
+        Textual's ListView consumes Enter and emits ``Selected`` instead of
+        letting the app-level Enter binding run, so route the selected row
+        through the same selection logic used by the explicit action.
+        """
+
+        row = event.item
+        if isinstance(row, BrowserRow):
+            self.select_item(row.item)
+
+    def action_select(self) -> None:
+        item = self.focused_item()
+        if item is not None:
+            self.select_item(item)
+
+    def select_item(self, item: BrowserItem) -> None:
+        """Select, drill into, or enqueue a browser item."""
+
+        if self.client is None:
+            return
+        if item.kind is ItemKind.BACK:
+            self.go_back()
+        elif item.kind is ItemKind.ARTISTS:
+            self.show_items(self.client.artists(), "Artists")
+        elif item.kind is ItemKind.ALBUMS:
+            self.show_items(self.client.albums(), "Albums")
+        elif item.kind is ItemKind.TRACKS:
+            self.show_items(self.client.tracks(), "Tracks")
+        elif item.kind is ItemKind.PLAYLISTS:
+            self.show_items(self.client.playlists(), "Playlists")
+        elif item.kind is ItemKind.ARTIST:
+            self.show_items(self.client.albums(item.source), f"Albums by {item.title}")
+        elif item.kind in {ItemKind.ALBUM, ItemKind.PLAYLIST}:
+            self.show_items(self.client.tracks(item.source), item.title)
+        elif item.kind is ItemKind.TRACK:
+            self.append_item(item)
+
+    def action_play_now(self) -> None:
+        item = self.focused_item()
+        if item is None or self.client is None:
+            return
+        tracks = self.client.playable_tracks(item)
+        first = self.queue.replace(tracks)
+        if first is None:
+            self.set_status(f"Nothing playable for {item.title}.")
+            return
+        self.play(first)
+        self.refresh_queue()
+
+    def action_append(self) -> None:
+        item = self.focused_item()
+        if item is not None:
+            self.append_item(item)
+
+    def action_pause_resume(self) -> None:
+        if self.player is not None:
+            self.player.pause_resume()
+
+    def action_next_track(self) -> None:
+        track = self.queue.next()
+        if track is None:
+            self.set_status("End of queue.")
+            self.refresh_queue()
+            return
+        self.play(track)
+        self.refresh_queue()
+
+    def action_stop(self) -> None:
+        if self.player is not None:
+            self.player.stop()
+        self.set_status("Stopped.")
+
+    def append_item(self, item: BrowserItem) -> None:
+        if self.client is None:
+            return
+        tracks = self.client.playable_tracks(item)
+        if not tracks:
+            self.set_status(f"Nothing playable for {item.title}.")
+            return
+        self.queue.append(tracks)
+        self.refresh_queue()
+        self.set_status(f"Added {len(tracks)} track(s) to queue.")
+
+    def play(self, track: QueueTrack) -> None:
+        if self.player is None:
+            self.set_status("mpv is not available.")
+            return
+        self.player.play(track)
+        self.query_one("#now-playing", Static).update(track.label)
+        self.set_status(f"Playing {track.label}")
+
+    def focused_item(self) -> BrowserItem | None:
+        browser = self.query_one("#browser-list", ListView)
+        row = browser.highlighted_child
+        if isinstance(row, BrowserRow):
+            return row.item
+        return None
+
+    def go_back(self) -> None:
+        if not self.history:
+            return
+        self.items = self.history.pop()
+        browser = self.query_one("#browser-list", ListView)
+        browser.clear()
+        if self.history:
+            browser.append(BrowserRow(BrowserItem("..", ItemKind.BACK)))
+        for item in self.items:
+            browser.append(BrowserRow(item))
+        self.set_status("Back")
+
+    def refresh_queue(self) -> None:
+        labels = self.queue.labels()
+        self.query_one("#queue", Static).update(
+            "\n".join(labels) if labels else "Queue is empty"
+        )
+
+    def set_status(self, message: str) -> None:
+        self.query_one("#status", Static).update(message)
+
+
+def main() -> None:
+    """Run Plexbar."""
+
+    PlexbarApp().run()

plexbar-0.1.2/src/plexbar/models.py

@@ -0,0 +1,61 @@
+"""Small domain models used by the Plexbar UI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class ItemKind(StrEnum):
+    """Kinds of Plex music items Plexbar can browse."""
+
+    ROOT = "root"
+    ARTISTS = "artists"
+    ALBUMS = "albums"
+    TRACKS = "tracks"
+    PLAYLISTS = "playlists"
+    ARTIST = "artist"
+    ALBUM = "album"
+    TRACK = "track"
+    PLAYLIST = "playlist"
+    BACK = "back"
+
+
+@dataclass(frozen=True)
+class BrowserItem:
+    """A row displayed in the browser list."""
+
+    title: str
+    kind: ItemKind
+    source: Any | None = None
+    subtitle: str = ""
+
+    @property
+    def display_title(self) -> str:
+        """Human-readable title with optional subtitle."""
+
+        if self.subtitle:
+            return f"{self.title} — {self.subtitle}"
+        return self.title
+
+
+@dataclass(frozen=True)
+class QueueTrack:
+    """A track queued for playback."""
+
+    title: str
+    artist: str
+    album: str
+    stream_url: str
+
+    @property
+    def label(self) -> str:
+        """Human-readable track label."""
+
+        bits = [self.title]
+        if self.artist:
+            bits.append(self.artist)
+        if self.album:
+            bits.append(self.album)
+        return " — ".join(bits)

plexbar-0.1.2/src/plexbar/playback.py

@@ -0,0 +1,115 @@
+"""Playback queue and mpv subprocess integration."""
+
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+
+from plexbar.models import QueueTrack
+
+
+class MpvNotFoundError(RuntimeError):
+    """Raised when mpv is required but not installed."""
+
+
+@dataclass
+class PlaybackQueue:
+    """In-memory playback queue."""
+
+    tracks: list[QueueTrack] = field(default_factory=list)
+    current_index: int = -1
+
+    @property
+    def current(self) -> QueueTrack | None:
+        """Return the current track, if any."""
+
+        if 0 <= self.current_index < len(self.tracks):
+            return self.tracks[self.current_index]
+        return None
+
+    def append(self, tracks: list[QueueTrack]) -> None:
+        """Append tracks to the queue."""
+
+        self.tracks.extend(tracks)
+        if self.current_index == -1 and self.tracks:
+            self.current_index = 0
+
+    def replace(self, tracks: list[QueueTrack]) -> QueueTrack | None:
+        """Replace the queue and return the first track."""
+
+        self.tracks = list(tracks)
+        self.current_index = 0 if self.tracks else -1
+        return self.current
+
+    def next(self) -> QueueTrack | None:
+        """Advance to the next track and return it."""
+
+        if self.current_index + 1 < len(self.tracks):
+            self.current_index += 1
+            return self.current
+        self.current_index = -1
+        return None
+
+    def labels(self) -> list[str]:
+        """Return display labels for the queue."""
+
+        labels: list[str] = []
+        for index, track in enumerate(self.tracks):
+            prefix = "▶ " if index == self.current_index else "  "
+            labels.append(f"{prefix}{track.label}")
+        return labels
+
+
+class MpvPlayer:
+    """Simple one-track-at-a-time mpv controller."""
+
+    def __init__(self) -> None:
+        if shutil.which("mpv") is None:
+            raise MpvNotFoundError(
+                "mpv was not found on PATH; install mpv to use Plexbar playback."
+            )
+        self._process: subprocess.Popen[str] | None = None
+        self._paused = False
+
+    @property
+    def is_running(self) -> bool:
+        """Return whether mpv is currently running."""
+
+        return self._process is not None and self._process.poll() is None
+
+    def play(self, track: QueueTrack) -> None:
+        """Start playing a track, replacing any existing mpv process."""
+
+        self.stop()
+        self._paused = False
+        self._process = subprocess.Popen(  # noqa: S603
+            ["mpv", "--no-video", "--really-quiet", track.stream_url],
+            stdin=subprocess.PIPE,
+            text=True,
+        )
+
+    def pause_resume(self) -> None:
+        """Toggle pause/resume in mpv."""
+
+        if (
+            self._process is None
+            or self._process.stdin is None
+            or self._process.poll() is not None
+        ):
+            return
+        self._process.stdin.write("p\n")
+        self._process.stdin.flush()
+        self._paused = not self._paused
+
+    def stop(self) -> None:
+        """Stop mpv if it is running."""
+
+        if self._process is None:
+            return
+        if self._process.poll() is None:
+            self._process.terminate()
+            try:
+                self._process.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                self._process.kill()
+        self._process = None
+        self._paused = False

plexbar-0.1.2/src/plexbar/plex_client.py

@@ -0,0 +1,193 @@
+"""Plex API wrapper for music browsing."""
+
+from collections.abc import Iterable
+from typing import Any, cast
+
+from plexapi.audio import Album, Artist, Track  # type: ignore[import-untyped]
+from plexapi.library import MusicSection  # type: ignore[import-untyped]
+from plexapi.server import PlexServer  # type: ignore[import-untyped]
+
+from plexbar.models import BrowserItem, ItemKind, QueueTrack
+
+
+class PlexMusicClient:
+    """Small adapter around python-plexapi for the UI."""
+
+    def __init__(self, config: Any) -> None:
+        self.config = config
+        self.server = PlexServer(config.base_url, config.token)
+        self.library = self._default_music_library(config.default_library)
+
+    @staticmethod
+    def validate(base_url: str, token: str) -> list[str]:
+        """Validate Plex credentials and return available music library names."""
+
+        server = PlexServer(base_url, token)
+        return [section.title for section in music_sections(server)]
+
+    def root_items(self) -> list[BrowserItem]:
+        """Top-level browser sections."""
+
+        return [
+            BrowserItem("Artists", ItemKind.ARTISTS),
+            BrowserItem("Albums", ItemKind.ALBUMS),
+            BrowserItem("Tracks", ItemKind.TRACKS),
+            BrowserItem("Playlists", ItemKind.PLAYLISTS),
+        ]
+
+    def artists(self) -> list[BrowserItem]:
+        """Return artist rows."""
+
+        artists = self.library.search(libtype="artist")
+        return [BrowserItem(item.title, ItemKind.ARTIST, item) for item in artists]
+
+    def albums(self, artist: Any | None = None) -> list[BrowserItem]:
+        """Return album rows, optionally scoped to an artist."""
+
+        albums = artist.albums() if artist is not None else self.library.albums()
+        return [
+            BrowserItem(
+                str(album.title),
+                ItemKind.ALBUM,
+                album,
+                _safe_title(album, "parentTitle"),
+            )
+            for album in albums
+            if album is not None
+        ]
+
+    def tracks(self, parent: Any | None = None) -> list[BrowserItem]:
+        """Return track rows, optionally scoped to an album or playlist."""
+
+        if parent is None:
+            tracks = self.library.search(libtype="track")
+        elif hasattr(parent, "tracks"):
+            tracks = parent.tracks()
+        elif hasattr(parent, "items"):
+            tracks = [item for item in parent.items() if _is_track(item)]
+        else:
+            tracks = []
+        return [self.track_item(track) for track in tracks]
+
+    def playlists(self) -> list[BrowserItem]:
+        """Return music playlists."""
+
+        playlists = [
+            playlist
+            for playlist in self.server.playlists()
+            if playlist is not None and _is_audio_playlist(playlist)
+        ]
+        return [
+            BrowserItem(str(playlist.title), ItemKind.PLAYLIST, playlist)
+            for playlist in playlists
+        ]
+
+    def search(self, query: str) -> list[BrowserItem]:
+        """Search the configured music library by title.
+
+        PlexAPI's ``MusicSection.search`` does not accept a ``query`` keyword;
+        unknown keywords are treated as filter fields, which can raise for music
+        libraries. Search each supported music type by title instead.
+        """
+
+        items: list[BrowserItem] = []
+        for libtype in ("artist", "album", "track"):
+            results = self.library.search(title=query, libtype=libtype)
+            for result in results:
+                item = self._item_from_result(result)
+                if item is not None:
+                    items.append(item)
+        items.extend(
+            playlist
+            for playlist in self.playlists()
+            if query.casefold() in playlist.title.casefold()
+        )
+        return items
+
+    def playable_tracks(self, item: BrowserItem) -> list[QueueTrack]:
+        """Expand a browser item to queueable tracks."""
+
+        if item.kind is ItemKind.TRACK and item.source is not None:
+            return [self.queue_track(item.source)]
+        if item.kind is ItemKind.ALBUM and item.source is not None:
+            return [self.queue_track(track) for track in item.source.tracks()]
+        if item.kind is ItemKind.PLAYLIST and item.source is not None:
+            return [
+                self.queue_track(track) for track in self._playlist_tracks(item.source)
+            ]
+        if item.kind is ItemKind.ARTIST and item.source is not None:
+            return [
+                self.queue_track(track)
+                for album in item.source.albums()
+                for track in album.tracks()
+            ]
+        return []
+
+    def track_item(self, track: Track) -> BrowserItem:
+        """Convert a Plex track to a browser row."""
+
+        return BrowserItem(track.title, ItemKind.TRACK, track, _track_subtitle(track))
+
+    def queue_track(self, track: Track) -> QueueTrack:
+        """Convert a Plex track to a playback queue item."""
+
+        return QueueTrack(
+            title=track.title,
+            artist=_safe_title(track, "grandparentTitle"),
+            album=_safe_title(track, "parentTitle"),
+            stream_url=track.getStreamURL(),
+        )
+
+    def _default_music_library(self, preferred_name: str | None) -> MusicSection:
+        sections = music_sections(self.server)
+        if not sections:
+            msg = "No Plex music libraries were found."
+            raise RuntimeError(msg)
+        if preferred_name:
+            for section in sections:
+                if section.title == preferred_name:
+                    return section
+        return sections[0]
+
+    def _playlist_tracks(self, playlist: Any) -> list[Track]:
+        return [cast(Track, item) for item in playlist.items() if _is_track(item)]
+
+    def _item_from_result(self, result: Any) -> BrowserItem | None:
+        if isinstance(result, Artist):
+            return BrowserItem(result.title, ItemKind.ARTIST, result)
+        if isinstance(result, Album):
+            return BrowserItem(
+                result.title, ItemKind.ALBUM, result, _safe_title(result, "parentTitle")
+            )
+        if _is_track(result):
+            return self.track_item(result)
+        return None
+
+
+def music_sections(server: PlexServer) -> list[MusicSection]:
+    """Return only music sections from a Plex server."""
+
+    return [
+        section
+        for section in server.library.sections()
+        if isinstance(section, MusicSection)
+    ]
+
+
+def _track_subtitle(track: Track) -> str:
+    artist = _safe_title(track, "grandparentTitle")
+    album = _safe_title(track, "parentTitle")
+    return " — ".join(part for part in [artist, album] if part)
+
+
+def _safe_title(item: Any, attr: str) -> str:
+    return str(getattr(item, attr, "") or "")
+
+
+def _is_track(item: Any) -> bool:
+    return isinstance(item, Track) or getattr(item, "TYPE", None) == "track"
+
+
+def _is_audio_playlist(playlist: Any) -> bool:
+    items: Iterable[Any] = playlist.items()
+    return any(_is_track(item) for item in items)

plexbar-0.1.2/src/plexbar/settings.py

@@ -0,0 +1,76 @@
+"""Configuration loading and first-run setup persistence."""
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_config_dir
+
+APP_NAME = "plexbar"
+CONFIG_DIR = Path(user_config_dir(APP_NAME))
+CONFIG_PATH = CONFIG_DIR / "config.toml"
+
+
+@dataclass(frozen=True)
+class PlexbarConfig:
+    """Persisted Plexbar configuration."""
+
+    base_url: str
+    token: str
+    default_library: str | None = None
+
+
+def config_exists(path: Path = CONFIG_PATH) -> bool:
+    """Return whether a Plexbar config file exists."""
+
+    return path.exists()
+
+
+def load_config(path: Path = CONFIG_PATH) -> PlexbarConfig:
+    """Load config from TOML."""
+
+    with path.open("rb") as config_file:
+        data = tomllib.load(config_file)
+
+    plex = data.get("plex", {})
+    base_url = str(plex.get("base_url", "")).strip()
+    token = str(plex.get("token", "")).strip()
+    default_library = plex.get("default_library")
+
+    if not base_url or not token:
+        msg = f"Invalid Plexbar config at {path}: base_url and token are required"
+        raise ValueError(msg)
+
+    return PlexbarConfig(
+        base_url=base_url,
+        token=token,
+        default_library=str(default_library) if default_library else None,
+    )
+
+
+def save_config(config: PlexbarConfig, path: Path = CONFIG_PATH) -> None:
+    """Save config as TOML with user-only permissions where possible."""
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [
+        "[plex]",
+        f'base_url = "{_toml_escape(config.base_url)}"',
+        f'token = "{_toml_escape(config.token)}"',
+    ]
+    if config.default_library:
+        lines.append(f'default_library = "{_toml_escape(config.default_library)}"')
+    contents = "\n".join(lines) + "\n"
+
+    old_umask = os.umask(0o177)
+    try:
+        path.write_text(contents, encoding="utf-8")
+    finally:
+        os.umask(old_umask)
+    path.chmod(0o600)
+
+
+def _toml_escape(value: str) -> str:
+    """Escape a value for a basic TOML string."""
+
+    return value.replace("\\", "\\\\").replace('"', '\\"')