Add README, update main view to show more current video info

This commit is contained in:
mrkmntal 2026-09-25 23:26:07 -04:00
commit d7524147ec
2 changed files with 180 additions and 4 deletions

150
README.md Normal file
View file

@ -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

View file

@ -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: