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](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.