From d7524147ec29cf7c1079a668004a2fe54a983dea Mon Sep 17 00:00:00 2001 From: mrkmntal Date: Fri, 25 Sep 2026 23:26:07 -0400 Subject: [PATCH] Add README, update main view to show more current video info --- README.md | 150 +++++++++++++++++++++++++++++++++++++++++++++ mpvremote/views.py | 34 ++++++++-- 2 files changed, 180 insertions(+), 4 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ce907ff --- /dev/null +++ b/README.md @@ -0,0 +1,150 @@ +# mpvremote + +A Python 3 curses TUI that acts as a TV-style remote control for a running +[mpv](https://mpv.io/) instance, driven over its UNIX-socket IPC interface. + +Any device that can connect to your MPV machine via SSH and run a curses TUI +in an SSH shell — a phone, a laptop, a potato with a terminal — can be a +remote controller for your MPV. No X forwarding, no web server, no extra +dependencies: just SSH in and drive your media player from the couch. + +## How it works + +mpv exposes a JSON IPC interface when launched with `--input-ipc-server`. +mpvremote connects to that socket, polls playback properties (title, position, +volume, loop state, ...) and sends commands (seek, pause, queue, ...) — the +same interface mpv's own scripting API uses, but from a terminal UI. + +``` ++----------------+ ssh +----------------+ AF_UNIX +----------------+ +| Any device | -----------> | MPV machine | -----------> | mpv | +| (curses TUI) | | python3 -m | /tmp/ | --input-ipc- | +| | <----------- | mpvremote | mpv-socket | server=... | ++----------------+ +----------------+ +----------------+ +``` + +## Requirements + +- Python 3.6+ (standard library only — no pip installs) +- mpv running with IPC enabled +- Terminal with curses support (any Linux SSH session) + +## Quick start + +On the MPV machine, launch mpv with the IPC socket: + +```bash +mpv --input-ipc-server=/tmp/mpv-socket video.mkv +``` + +Or make it permanent in `mpv.conf`: + +``` +input-ipc-server=/tmp/mpv-socket +``` + +Then, from any device, SSH in and run the remote from the repo root: + +```bash +ssh user@mpv-machine +cd mpvremote +python3 -m mpvremote +``` + +## Configuration + +All settings live in `mpvremote/config.py`: + +| Setting | Default | Description | +|--------------|--------------------|---------------------------------------| +| `SOCKET` | `/tmp/mpv-socket` | Path to mpv's IPC socket | +| `MEDIA_DIR` | `~/GDrive/Videos` | Directory scanned for queueable video | +| `VIDEO_EXTS` | `mp4 mkv avi webm` | File extensions treated as video | + +## Keybindings + +### Main view (the remote) + +| Key | Action | +|---------|----------------------------| +| `Space` | Pause / resume | +| `h`/`l` | Seek -10s / +10s | +| `j`/`k` | Volume -5 / +5 | +| `s` | Cycle subtitles | +| `n`/`p` | Next / previous track | +| `r` | Toggle loop current file | +| `R` | Toggle loop playlist | +| `e` | Playlist view | +| `o` | Queue view | +| `c` | Show controls help | +| `q` | Quit | + +### Playlist view + +| Key | Action | +|----------------|--------------------------| +| `Up`/`Down` | Navigate | +| `Enter` | Skip to selected item | +| `Del` | Remove selected item | +| `Esc`/`q`/`←` | Back to main view | + +### Queue view + +| Key | Action | +|--------------|-------------------------------------| +| type | Incremental search of `MEDIA_DIR` | +| `Up`/`Down` | Navigate | +| `Enter` | Queue selected video (append-play) | +| `Backspace` | Delete search character | +| `Esc` | Clear search / back to main view | + +## Status bar + +The top status bar shows the current playback state: + +``` +> Playing | 1:23 / 5:00 | L:F+P | My Video Title | Vol: 50 +``` + +| Segment | Meaning | +|----------------|-------------------------------------------------------------| +| `> Playing` | Playback state (`\|\| Paused` when paused) | +| `1:23 / 5:00` | Current position / duration | +| `L:F+P` | Loop state (see below) | +| Title | Media title of the current file | +| `Vol: 50` | Volume level | + +Loop indicators: + +| Indicator | Meaning | +|-----------|----------------------------------| +| `L:--` | No looping | +| `L:F` | Current file loops | +| `L:P` | Playlist loops | +| `L:F+P` | Both file and playlist looping | + +## Views + +- **Main** — the remote: playback controls with a scrolling feedback log +- **Playlist** — the current mpv playlist; skip to or remove entries +- **Queue** — search your media library and append videos to the playlist + +The media library in `MEDIA_DIR` is scanned at startup and rescanned in the +background every 2 minutes, so newly added files show up without a restart. + +## Project layout + +``` +mpvremote/ +├── mpvremote/ +│ ├── __init__.py # Package exports +│ ├── __main__.py # Entry point: socket check + curses bootstrap +│ ├── app.py # App shell: drawing, colors, views, media rescan +│ ├── config.py # Socket path, media dir, extensions, key bindings +│ ├── mpv_client.py # Minimal mpv JSON IPC client (AF_UNIX socket) +│ └── views.py # MainView, PlaylistView, QueueView +``` + +## License + +GPLv3 diff --git a/mpvremote/views.py b/mpvremote/views.py index 714d1e2..c5d803b 100644 --- a/mpvremote/views.py +++ b/mpvremote/views.py @@ -11,18 +11,44 @@ class MainView: self._draw_messages() self._draw_help() + @staticmethod + def _fmt_time(seconds): + if seconds is None: + return "?" + seconds = int(seconds) + h, rem = divmod(seconds, 3600) + m, s = divmod(rem, 60) + if h: + return f"{h}:{m:02d}:{s:02d}" + return f"{m}:{s:02d}" + + @staticmethod + def _loop_str(f_loop, p_loop): + parts = [] + if f_loop not in (None, "no", False): + parts.append("F") + if p_loop not in (None, "no", False): + parts.append("P") + return ("L:" + "+".join(parts)) if parts else "L:--" + def _draw_status(self): try: title = self.app.client.get_property("media-title") or "Unknown" pause = self.app.client.get_property("pause") vol = self.app.client.get_property("volume") + pos = self.app.client.get_property("time-pos") + dur = self.app.client.get_property("duration") + f_loop = self.app.client.get_property("loop-file") + p_loop = self.app.client.get_property("loop-playlist") pause_str = "|| Paused" if pause else "> Playing" vol_str = f"Vol: {int(vol)}" if vol is not None else "Vol: ?" - avail = max(1, self.app.width - len(pause_str) - len(vol_str) - 10) + time_str = f"{self._fmt_time(pos)} / {self._fmt_time(dur)}" + loop_str = self._loop_str(f_loop, p_loop) + avail = max(1, self.app.width - len(pause_str) - len(vol_str) - len(time_str) - len(loop_str) - 16) title_display = title[:avail] - text = f" {pause_str} | {title_display} | {vol_str}" + text = f" {pause_str} | {time_str} | {loop_str} | {title_display} | {vol_str}" self.app.draw_status_bar(text) except Exception: self.app.draw_status_bar(" MPV Remote") @@ -31,7 +57,7 @@ class MainView: self.app.draw_messages() def _draw_help(self): - text = " [Space]Pause [h/l]Seek [j/k]Vol [s]Sub [e]Plist [o]Queue [q]Quit" + text = " [Space]Pause [h/l]Seek [j/k]Vol [s]Sub [e]Plist [o]Queue [r/R]Loop [q]Quit" self.app.draw_help_bar(text) def handle_key(self, key): @@ -89,7 +115,7 @@ class MainView: self.app.add_message("=== Controls ===") self.app.add_message("[Space] Pause | [h/l] Seek -10s/+10s | [j/k] Vol -/+") self.app.add_message("[s] Subtitle | [o] Queue | [e] Playlist | [n/p] Next/Prev") - self.app.add_message("[r] Loop File | [R] Loop Playlist | [q] Quit") + self.app.add_message("[r/R] Loop File/Playlist (state shown in status bar) | [q] Quit") elif key == config.KEY_PLAYLIST: self.app.switch_view('playlist') elif key == config.KEY_QUEUE: