tsplay/README.md

tsplay

A terminal Jellyfin client for Arch / Omarchy. Browse your server's libraries in the terminal; the selected title plays in an mpv window (hardware accelerated) while the TUI acts as the remote — pause, seek, and a live progress bar, with resume points reported back to the server.

It's the watch-side companion to TUISTREAM (which sets up and manages the Jellyfin server). tsplay only plays.

How it works

• BubbleTea drives the login form and a stack-based library browser.
• mpv does the actual playback. tsplay spawns it with --input-ipc-server and talks to it over a JSON IPC socket: it sends pause/seek/quit and observes time-pos/duration/pause/eof-reached, so the terminal can render a progress bar and report progress to Jellyfin.
• Media is direct-played (/Videos/{id}/stream?static=true) — mpv handles almost every container/codec natively, so the server doesn't transcode.
• Colours follow the active Omarchy theme, falling back to ANSI palette indices over SSH / on non-Omarchy boxes.

Requirements

• mpv — the only run-time dependency
• Go ≥ 1.26 — build-time only (compiled into the binary)

On Arch / Omarchy the installer fetches both for you via pacman if they're missing, so you don't normally need to install anything by hand.

GPU drivers (hardware-accelerated playback)

mpv leans on your GPU's video-decode drivers (VA-API on Intel/AMD, NVDEC on NVIDIA) for smooth, low-CPU playback. A normal Omarchy desktop already has these, so there's nothing to do. On a fresh, minimal Arch box you'd want the matching stack, e.g.:

• Intel: intel-media-driver (or libva-intel-driver for older iGPUs)
• AMD: libva-mesa-driver mesa
• NVIDIA: nvidia-utils (provides NVDEC)

The installer deliberately does not touch graphics drivers — that's a system-level choice, not tsplay's to make. Without them mpv still plays, just with software decoding (higher CPU use).

Install

./install.sh

Installs missing deps (Arch), builds ~/.local/bin/tsplay, then just run tsplay.

Usage

First run shows a login form. tsplay auto-detects Jellyfin servers on your LAN (Jellyfin's UDP discovery on port 7359) and pre-fills the server URL, so you usually only type your username and password. Credentials and a stable device id are saved to ~/.config/tsplay/config.json (mode 0600), so subsequent runs go straight to the library.

Discovery probes both broadcast and a unicast sweep of your subnet, because many home networks (especially WiFi) silently drop broadcast packets.

Login

Key	Action
tab	move between fields
ctrl+n	next discovered server (if more than one)
ctrl+r	rescan the network
enter	sign in
esc	quit

Browse

Key	Action
↑/↓ j/k	move
enter / l / →	open folder · play item
esc / ← / h	back
c	jump to Continue Watching
/	filter the current list
q	quit

Playing

Key	Action
space / k	play / pause
← / →	seek ∓10s
shift+←/→	seek ∓60s
↑ / ↓	volume ±5
m	mute / unmute
q / esc	stop, back to list

Status

v0.1 — LAN auto-discovery, movies/shows (season/episode drill-down)/music browse

• direct-play, resume on start, progress/stop reporting, volume control with remembered level, and audio auto-advance (music plays through the album/ folder, then returns to the browser). The UI uses a shared header/footer frame and a compact one-line list (media-type icon, title, and a right-aligned year · duration · watched column).

Roadmap: search, subtitle/audio-track selection, quick-connect login, video "play next episode".

Notes

• Self-signed TLS isn't trusted by default — use a proper cert (your Jellyfin is usually behind Caddy anyway) or a plain http://…:8096 URL on the LAN.