hybirdss/smartest-tv

📺

smartest-tv

The CLI your TV has been waiting for.

Play Netflix / Apple TV+ / YouTube / Spotify by name. Cast URLs. Multi-room audio. AI concierge. All from your terminal.

한국어 · 中文 · 日本語 · Español · Deutsch · Português · Français

pip install stv && stv play “Frieren”

No TV? Opens in your browser. Got a TV? stv setup to connect it.

---

No TV? No problem. Without a TV configured, stv opens content directly in your browser. Netflix, YouTube, Spotify, Disney+ — just pip install stv and go.

---

🛋 Vibe-code and chill

Vibe-coding at 2am. Claude writes your code. You tell it to put on a show. It does.

you: play frieren on the living room tv
claude: Playing Frieren s2e8 on Living Room. (3s)

you: bit quieter
claude: Volume → 18.

you: good night
claude: All 3 TVs off.

Already installed stv? Just tell Claude:

# Option 1 — just talk (zero config)
"run stv play netflix Frieren s2e8"

# Option 2 — install the Skill for auto-trigger
clawhub install smartest-tv
# now "play Frieren", "good night", "next episode" just work mid-session

Also available as an MCP server (21 tools) for Claude Code, Codex, Antigravity, and other MCP clients.

---

🎯 Just type stv

No subcommand? You get a Now Playing card and three contextual next-actions based on your watch history — not a 30-command help dump.

$ stv "play dark on netflix"     # natural language works
$ stv play "Frieren"             # auto-detects platform
$ stv next                       # continue last show
$ stv stats                      # → insights

Unknown input? You get a friendly hint, not an error.

---

🎨 A CLI that looks like a product

Every command renders with Catppuccin Mocha colors, semantic icons, and real visual hierarchy. Prefer another palette? Set STV_THEME=nord or STV_THEME=gruvbox.

--format json is always available when you need to pipe to jq.

---

✨ What it does

---

🤖 Tell your AI to control your TV

stv is an MCP server. Claude, GPT, Cursor, or any MCP client can control your TV with natural language.

---

📅 A day with stv

---

🔥 Killer combos

10 more recipes →

---

▲ Click to watch the full demo

---

⚙️ How it works

  "Play Dark S1E1"
        │
        ▼
  ┌─── Resolution ───┐
  │ Cache → API → Web │  content_id
  │  0.1s   1s    3s  │──────────────▶ 📺 TV plays it
  └───────────────────┘       │
                         Deep link via
                    LG / Samsung / Roku / Android

Say a name. stv resolves it to a content ID, deep-links into the app on your TV. No browser automation, no API keys, no cloud dependency. Results are cached so repeat plays are instant.

---

📦 Install

pip install stv                    # LG webOS (default)
pip install "stv[samsung]"         # Samsung Tizen
pip install "stv[android]"         # Android TV / Fire TV
pip install "stv[all]"             # Everything

stv setup                          # auto-discover + pair your TV

Supports LG webOS · Samsung Tizen · Android TV / Fire TV · Roku

Home Assistant (HACS)

Add as a custom repository (default listing in review: hacs/default#6907):

HACS → ⋮ (top right) → Custom repositories
  URL: https://github.com/Hybirdss/smartest-tv
  Category: Integration → Add
Then: Install → Restart HA
Settings → Integrations → Add → "Smartest TV" → auto-discovers your TVs

Android TV / Fire TV: the setup flow shows a 6-digit PIN on the TV — enter it in the pairing form to finish. In HA OS / HA Container set STV_CONFIG_DIR=/config/smartest-tv so pairing survives container rebuilds. See docs/integrations/home-assistant.md.

Then use in automations:

service: media_player.play_media
target:
  entity_id: media_player.living_room
data:
  media_content_type: stv
  media_content_id: "netflix:Frieren:s2e8"

This does what HA’s built-in media_player.play_media can’t: resolve a show by name and deep-link into the streaming app. Power, volume, and playback controls also work as standard HA media player entities.

---

🔌 Works with

---

📚 Docs

---

🔓 Open source

Every line of stv is on GitHub — the CLI, resolvers (Netflix, Apple TV+, YouTube, Spotify, Disney+, Max, Prime Video, Paramount+, Hulu, Peacock, Crunchyroll, and more via JustWatch), all 4 TV drivers (LG, Samsung, Roku, Android), cache, sync engine, scenes, and all 253 tests. Streaming availability data powered by JustWatch.

---

🔒 Privacy

stv runs on your local network. No telemetry, no analytics, no cloud sync, no phoning home about what you watch. There is no posthog, no amplitude, no sentry, no mixpanel — grep the source.

One exception — community cache contribution. When you play content that isn’t in the local cache, stv resolves it (via web parsing) and submits the resolved ID to a shared community cache so the next user gets an instant lookup. This is the same pattern as Wikipedia or a package mirror — many small contributions, anonymous.

What’s sent (background HTTPS, fire-and-forget, never blocks playback):

• Platform name (netflix / youtube / spotify)
• Content slug (e.g. frieren)
• Resolved content ID (Netflix title ID, YouTube video ID, Spotify URI)

What’s not sent:

• Your name, email, or any user identifier
• Your IP address (the CDN sees a connection IP per standard HTTP, but the client never reads or transmits it)
• Your watch history or play timestamps
• Your TV’s IP address or hardware info
• Anything about how often or when you use stv

To disable cache contribution entirely:

export STV_NO_CONTRIBUTE=1

Source: src/smartest_tv/cache.py — search for _contribute.

---

🤝 Contributing

211 tests. No TV needed to run them.

pip install -e ".[dev]"
python -m pytest tests/ -v

Samsung, Roku, and Android TV drivers need real-world testing. If you have one, your feedback matters.

Cache Contributions · Driver Development

---

MIT License · Made with Python · No cloud required