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)

CODEBLOCK0

With Home Assistant (recommended for TV control)

CODEBLOCK1

Direct WebOS (LG TV, no Home Assistant needed)

CODEBLOCK2

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)

CODEBLOCK3

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
INLINECODE5	Yes	Base URL of your Jellyfin server, e.g. INLINECODE6
INLINECODE7

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
INLINECODE12	All	Force backend: homeassistant, webos, androidtv, or INLINECODE16
INLINECODE17

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. 1. HA_URL + HA_TOKEN + HA_TV_ENTITY set → Home Assistant backend
2. INLINECODE40 set → direct ADB (Android TV)
3. INLINECODE41 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:

CODEBLOCK4

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

Resume / Play Smart

If TV and Jellyfin are already running:

CODEBLOCK5

TV Control

CODEBLOCK6

Remote Control

CODEBLOCK7

Search Content

CODEBLOCK8

Library Stats & Scan

CODEBLOCK9

User History (requires admin API key)

CODEBLOCK10

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) | ✅ (direct output) | ✅ (direct output) | — | | Extra dependency | None | npm install ws | apt install adb | None | | Setup complexity | Medium (need HA) | Low (TV IP + MAC) | Low (enable ADB on TV) | None | | Jellyfin playback | ✅ | ✅ | ✅ | ✅ |

Recommendation:

• - Already have Home Assistant? → Use HA backend (most versatile, any TV brand)
• LG WebOS TV, no HA? → Use direct WebOS backend
• Android TV / Fire TV / Chromecast with Google TV, no HA? → Use direct ADB backend
• No smart TV control needed? → Skip TV config, resume works if Jellyfin app is already open

Security Notes

• - API keys only in openclaw.json env — never in workspace files, .env files, or markdown docs.
• HA tokens are long-lived and powerful. Create a dedicated HA user with limited permissions if possible.
• TVCLIENTKEY (WebOS) is sensitive — it allows full control of your TV. Treat it like a password.
• ADB access grants full control of your Android TV. Ensure your network is secured — anyone on the same network could connect via ADB if debugging is enabled.
• Admin operations (history, scan) require an admin-level Jellyfin API key and will fail gracefully with 403 if permissions are insufficient.

Architecture

• - lib/jellyfin.js — Jellyfin REST API (auth, search, sessions, playback control)
• INLINECODE50 — TV control abstraction (HA backend, WebOS backend, Wake-on-LAN)
• INLINECODE51 — User-friendly CLI with all commands

Workflow: Agent says "Play Star Trek on TV"

CODEBLOCK11