# 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](README.md). --- ## 1. Installing On an **Omarchy / Arch** machine, one line does everything: ```bash 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: > > ```bash > 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](README.md#gpu-drivers-hardware-accelerated-playback) lists them per graphics card). **I want to start over / log in as someone else.** Delete the saved settings and relaunch: ```bash 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.