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.

New here? The User Guide is a plain-English, step-by-step walkthrough of installing, signing in, and watching. This README is the technical overview.

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

One line, nothing to clone:

curl -fsSL https://raw.githubusercontent.com/28allday/tsplay/main/install.sh | bash

This installs mpv if it's missing (Arch), downloads the right binary for your architecture into ~/.local/bin, then you just run tsplay. Pin a version with TSPLAY_VERSION=v1.0.0, or change the prefix with PREFIX=/opt.

From a clone it builds from source instead (if Go is present), otherwise it falls back to downloading the released binary:

git clone https://github.com/28allday/tsplay.git
cd tsplay && ./install.sh

On an Omarchy desktop the installer also adds a Walker entry (with icon) that launches tsplay as a floating terminal window — search tsplay in Walker — using the stock TUI.float app-id, so no Hyprland config is needed. On headless boxes this step is skipped and tsplay stays a plain shell TUI.

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.

Switching servers. Once signed in, tsplay locks onto that server and goes straight to the library on every later run — it won't ask again. If you move to a different Jellyfin box, press s in the browser to drop back to discovery, pick the new server, and sign in; the new one is then saved and locked in. If a saved server has gone away (e.g. you rebuilt it elsewhere), tsplay notices the failed connection on startup and falls back to discovery automatically so you're never stuck pointing at a dead server.

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	cancel — back to the library, or quit if not yet signed in

Browse

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

Playing

Key	Action
space / k	play / pause
← / →	seek ∓10s
shift+←/→	seek ∓60s
n / p	next / previous track (music)
↑ / ↓	volume ±5
m	mute / unmute
q / esc	stop, back to list

Features

• LAN auto-discovery of Jellyfin servers, with one-key server switching and automatic fallback if a saved server goes away.
• Browse movies, shows (season/episode drill-down) and music, with a compact one-line list (media-type icon, title, and a right-aligned year · duration · watched column) and / to filter.
• Direct-play to mpv (no server-side transcoding), resume from your last position, and progress/stop reporting so Continue Watching stays in sync across all your devices.
• Audio auto-advance — music plays through the album/folder and returns to the browser when it's done — with volume remembered across tracks and runs.
• Colours follow the active Omarchy theme, with an ANSI fallback over SSH.

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.