jellyfin-control

控制 Jellyfin 媒体服务器和电视。搜索内容、恢复播放、管理会话、控制电视电源和应用程序。支持 Home Assistant 和直接 WebOS 后端。一个命令即可打开电视、启动 Jellyfin 和播放内容。

## 概述（中文）

控制 Jellyfin 媒体服务器和电视。搜索内容、恢复播放、管理会话、控制电视电源和应用程序。支持 Home Assistant 和直接 WebOS 后端。一个命令即可打开电视、启动 Jellyfin 和播放内容。

## 原文

# Jellyfin Control

A robust skill to control Jellyfin playback and TV power via CLI.

## Features

- **🎯 One-Command Play:** `tv play "Breaking Bad"` — turns on TV, launches Jellyfin, finds the next episode, and plays it.
- **Smart Resume:** Automatically finds the next unplayed episode for series.
- **Resume Position:** Resumes Movies/Episodes exactly where left off (with `Seek` fallback for LG WebOS/Tizen).
- **Device Discovery:** Auto-detects controllable sessions (TVs, Phones, Web).
- **Remote Control:** Full playback control (play, pause, stop, next, prev, volume, mute).
- **TV Power & Apps:** Turn TV on/off, launch apps — works with or without Home Assistant.
- **Two TV Backends:** Home Assistant integration or direct WebOS (LG TVs, no HA needed).
- **Android TV Support:** Direct ADB backend for Chromecast w/ Google TV, Nvidia Shield, Fire TV, Mi Box — no HA needed.
- **Three connection modes:** Home Assistant (any TV), direct WebOS (LG), direct ADB (Android TV/Fire TV).

## Quick Start

### Minimal setup (Jellyfin only, no TV control)

```json
{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://YOUR_IP:8096",
          "JF_API_KEY": "your-api-key-here",
          "JF_USER": "your-username"
        }
      }
    }
  }
}
```

### With Home Assistant (recommended for TV control)

```json
{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://192.168.1.50:8096",
          "JF_API_KEY": "your-jellyfin-api-key",
          "JF_USER": "victor",
          "HA_URL": "http://192.168.1.138:8123",
          "HA_TOKEN": "your-ha-long-lived-token",
          "HA_TV_ENTITY": "media_player.lg_webos_tv_oled48c34la",
          "TV_MAC": "AA:BB:CC:DD:EE:FF"
        }
      }
    }
  }
}
```

### Direct WebOS (LG TV, no Home Assistant needed)

```json
{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://192.168.1.50:8096",
          "JF_API_KEY": "your-jellyfin-api-key",
          "JF_USER": "victor",
          "TV_IP": "192.168.1.100",
          "TV_MAC": "AA:BB:CC:DD:EE:FF"
        }
      }
    }
  }
}
```

> **First time with WebOS direct:** The TV will show a pairing prompt. Accept it and save the `TV_CLIENT_KEY` the skill prints — add it to your env to skip the prompt next time.

### Direct ADB (Android TV / Fire TV / Chromecast with Google TV, no HA needed)

```json
{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://192.168.1.50:8096",
          "JF_API_KEY": "your-jellyfin-api-key",
          "JF_USER": "victor",
          "ADB_DEVICE": "192.168.1.100:5555",
          "TV_MAC": "AA:BB:CC:DD:EE:FF"
        }
      }
    }
  }
}
```

> **First time with ADB:** Enable Developer Options on your TV (Settings → About → tap Build Number 7 times), then enable Network/USB debugging. First connection will show "Allow debugging?" on the TV — accept it. Requires `adb` installed on the OpenClaw host (`sudo apt install adb`).

## Environment Variables

### Jellyfin (required)

| Variable      | Required | Description                                                       |
| ------------- | -------- | ----------------------------------------------------------------- |
| `JF_URL`      | **Yes**  | Base URL of your Jellyfin server, e.g. `http://192.168.1.50:8096` |
| `JF_API_KEY`  | **Yes**  | API key from Jellyfin Dashboard → Advanced → API Keys             |
| `JF_USER`     | No       | Username — used to resolve user ID for user-specific endpoints    |
| `JF_USER_ID`  | No       | User ID directly — avoids needing to call `/Users`                |
| `JF_PASS`     | No       | Password — only if authenticating by user session                 |

### TV Control (optional — choose one backend)

| Variable           | Backend   | Description                                                           |
| ------------------ | --------- | --------------------------------------------------------------------- |
| `TV_BACKEND`       | All       | Force backend: `homeassistant`, `webos`, `androidtv`, or `auto`       |
| `TV_PLATFORM`      | HA        | Force platform: `webos` or `androidtv` (auto-detected from entity)    |
| `HA_URL`           | HA        | Home Assistant URL, e.g. `http://192.168.1.138:8123`                  |
| `HA_TOKEN`         | HA        | HA long-lived access token (Profile → Long-Lived Access Tokens)       |
| `HA_TV_ENTITY`     | HA        | Entity ID of your TV, e.g. `media_player.lg_webos_tv_oled48c34la`     |
| `TV_IP`            | WebOS     | LG TV IP address for direct WebOS SSAP connection                     |
| `TV_CLIENT_KEY`    | WebOS     | Pairing key (printed on first connection — save it!)                  |
| `ADB_DEVICE`       | AndroidTV | TV address for ADB, e.g. `192.168.1.100:5555`                        |
| `TV_MAC`           | All       | TV MAC address for Wake-on-LAN (needed to turn on TV)                 |
| `TV_JELLYFIN_APP`  | All       | Override Jellyfin app ID (auto: `org.jellyfin.webos` / `org.jellyfin.androidtv`) |
| `TV_BOOT_DELAY`    | All       | Seconds to wait after TV wake (default: 10)                           |
| `TV_APP_DELAY`     | All       | Seconds to wait after launching Jellyfin (default: 8)                 |

**Auto-detection:** If `TV_BACKEND` is `auto` (default):
1. `HA_URL` + `HA_TOKEN` + `HA_TV_ENTITY` set → Home Assistant backend
2. `ADB_DEVICE` set → direct ADB (Android TV)
3. `TV_IP` set → direct WebOS (LG)
4. Nothing set → TV commands disabled, Jellyfin-only mode

## Usage

### 🎯 One-Command Play (the magic)

Turn on TV → launch Jellyfin → find next episode → play it. All in one command:

```bash
node skills/jellyfin-control/cli.js tv play "Breaking Bad"
node skills/jellyfin-control/cli.js tv play "The Matrix"
```

The skill validates the content exists BEFORE turning on the TV (fail fast).

### Resume / Play Smart

If TV and Jellyfin are already running:

```bash
node skills/jellyfin-control/cli.js resume "Breaking Bad"
node skills/jellyfin-control/cli.js resume "Matrix" --device "Chromecast"
```

### TV Control

```bash
node skills/jellyfin-control/cli.js tv on           # Turn on (Wake-on-LAN)
node skills/jellyfin-control/cli.js tv off          # Turn off
node skills/jellyfin-control/cli.js tv launch       # Launch Jellyfin app
node skills/jellyfin-control/cli.js tv launch com.webos.app.hdmi1  # Launch specific app
node skills/jellyfin-control/cli.js tv apps         # List installed apps
```

### Remote Control

```bash
node skills/jellyfin-control/cli.js control pause
node skills/jellyfin-control/cli.js control play
node skills/jellyfin-control/cli.js control next
node skills/jellyfin-control/cli.js control vol 50
```

### Search Content

```bash
node skills/jellyfin-control/cli.js search "Star Wars"
```

### Library Stats & Scan

```bash
node skills/jellyfin-control/cli.js stats
node skills/jellyfin-control/cli.js scan            # requires admin API key
```

### User History (requires admin API key)

```bash
node skills/jellyfin-control/cli.js history
node skills/jellyfin-control/cli.js history jorge --days 7
```

## Choosing a TV Backend

| Feature             | Home Assistant        | Direct WebOS            | Direct ADB (Android TV)     | No Backend     |
| ------------------- | --------------------- | ----------------------- | --------------------------- | -------------- |
| TV brands           | Any (via HA)          | LG only                 | Android TV, Fire TV, CCwGTV | —              |
| Turn on (WoL)       | ✅                    | ✅                      | ✅ (WoL or ADB wakeup)     | —              |
| Turn off            | ✅                    | ✅                      | ✅                          | —              |
| Launch apps         | ✅