tsplay/USER_GUIDE.md

tsplay — User Guide

tsplay lets you watch everything on your Jellyfin server straight from the terminal. You browse your libraries in a tidy text interface; when you pick something, it opens in a proper mpv video window (hardware-accelerated, full quality) while the terminal becomes the remote control — pause, seek, volume, and a live progress bar. Where you stop is remembered on the server, so you can pick up later from any device.

This guide is for everyday use. If you want the technical details, see the README.

---

1. Installing

On an Omarchy / Arch machine, one line does everything:

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

The installer:

• Installs the only thing it needs — mpv — if it isn't already present.
• Downloads the tsplay program and puts it in ~/.local/bin.
• On an Omarchy desktop, it also adds tsplay to the Walker launcher (with an icon), so you can start it like any other app.

That's it — nothing else to set up.

Prefer to build it yourself? Clone the repo and run the same script — with Go installed it builds from source:

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

On a non-Arch system? The installer won't install packages for you; it will just tell you to install mpv first, then re-run it.

---

2. Starting tsplay

Three ways, pick whichever suits you:

• Walker (Omarchy desktop): press your launcher key (usually SUPER), type tsplay, and hit enter. It opens in a floating terminal window.
• Terminal: just type tsplay.
• Over SSH (e.g. on a headless box): type tsplay. The video window then appears wherever mpv can open one; on a pure server with no screen, tsplay is mainly used for music.

---

3. Signing in (first run)

The first time you run tsplay you'll see a short login form.

tsplay automatically finds Jellyfin servers on your network, so the server address is usually filled in for you. You normally only need to type your username and password, then press enter.

Key	What it does
tab	Move between the boxes (server / username / password)
ctrl+n	Pick the next server, if more than one was found
ctrl+r	Scan the network again
enter	Sign in
esc	Quit

A few notes:

• If nothing is found automatically, just type the address yourself, e.g. https://media.example.com or http://192.168.1.50:8096.
• Your login is saved securely on your own machine, so you won't be asked again — every later run goes straight to your library.
• If you don't see your server, make sure tsplay and the server are on the same network, then press ctrl+r to rescan.

---

4. Finding and playing something

Once you're in, you'll see your libraries (Movies, Shows, Music, …). Move around with the arrow keys and open things with enter.

Key	What it does
↑ / ↓ (or j / k)	Move up and down the list
enter (or →)	Open a folder, or play a title
esc (or ←)	Go back one level
/	Search/filter the list you're looking at
c	Jump to Continue Watching
s	Switch to a different server
q	Quit tsplay

• Drill down naturally: Shows → a series → a season → an episode, then enter to play.
• Press / to filter a long list — start typing and the list narrows; press esc to clear the filter.

Continue Watching

Press c anywhere in the browser to see everything you started but didn't finish, newest first. Pick one and it resumes from where you left off — no need to scrub to the right spot. This is the same "Continue Watching" you see in the Jellyfin app, kept in sync with your phone, TV, and browser.

---

5. While something is playing

The video plays in its own mpv window. Keep the terminal focused to use these controls (you'll also see a live progress bar and the time):

Key	What it does
space (or k)	Play / pause
← / →	Skip back / forward 10s
shift+←/→	Skip back / forward 60s
↑ / ↓	Volume up / down
m	Mute / unmute
n / p	Next / previous track (music only)
q (or esc)	Stop and return to the library

Your position is reported back to the server as you watch, so it shows up in Continue Watching next time — and disappears once you finish.

---

6. Music

Music works just like video, but with no black window — the audio simply plays in the background while the terminal shows what's on.

• Play an album or a track and it keeps going: when one track ends, tsplay automatically moves to the next one in the album/folder, then returns to the browser when the album finishes.
• Use n and p to jump between tracks.
• Your last volume is remembered between tracks and between runs.

---

7. Switching to a different server

If you set up a new Jellyfin box (or moved house and rebuilt it elsewhere), you don't need to reinstall or wipe anything:

• Press s while browsing. tsplay drops back to the network scan, finds the new server, and lets you sign in. From then on it locks onto the new one and goes straight there on every run.
• If your old server has simply gone away, tsplay notices it can't connect when it starts and takes you to the scan automatically — so you're never stuck staring at a server that no longer exists.

(If you have the cliamp music player installed, switching servers updates its Jellyfin settings too, so your music stays in sync.)

---

8. Troubleshooting

"No servers found" on the login screen. Make sure your computer and the Jellyfin server are on the same Wi-Fi/network, then press ctrl+r to scan again. You can always type the address by hand — e.g. http://192.168.1.50:8096.

"Login failed". Double-check the username and password. If the server address is wrong, press tab back up to it and correct it (or ctrl+r to rediscover).

It can't connect / the library won't load. tsplay will usually send you back to the server scan on its own. If you're typing the address, prefer a plain http://…:8096 address on your home network, or a proper https:// address with a real certificate. Self-signed certificates are not trusted.

Video plays but is choppy / uses lots of CPU. That's the graphics drivers, not tsplay. On a normal Omarchy desktop this is already sorted. On a brand-new, minimal install you may need your GPU's video-decode drivers (the README lists them per graphics card).

I want to start over / log in as someone else. Delete the saved settings and relaunch:

rm ~/.config/tsplay/config.json
tsplay

You'll get the fresh login screen again.

---

9. Quick reference

Browsing      ↑/↓ move · enter open/play · esc back · / search
              c continue watching · s switch server · q quit

Playing       space pause · ←/→ ±10s · shift+←/→ ±60s
              ↑/↓ volume · m mute · n/p track (music) · q stop

Happy watching.