jellyfin-control
Control Jellyfin media server and TV. Search content, resume playback, manage sessions, control TV power and apps. Supports Home Assistant and direct WebOS backends. One command to turn on TV, launch Jellyfin, and play content.
安装 / 下载方式
TotalClaw CLI推荐
totalclaw install clawskills:clawskills~titunito-jellyfin-controlcURL直接下载，无需登录
curl -fsSL https://skills.taituai.com/api/skills/clawskills%3Aclawskills~titunito-jellyfin-control/file -o titunito-jellyfin-control.md# 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 | ✅ | ✅ | ✅ | — |
| List apps | ✅ (via HA logs)