stv 0.8.0

Talk to your TV. Control any smart TV with natural language.

📺
smartest-tv

The CLI your TV has been waiting for.

Play Netflix by name. Cast URLs. Multi-room audio. AI concierge. All from your terminal.

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

pip install stv && stv setup

_{Runs on your local network. No cloud. No API keys. No subscriptions.}

---

😩 Without stv	😎 With stv
Pick up remote Open Netflix app Search for show Pick the season Pick the episode Press play ~30 seconds	stv play netflix "Dark" s1e1 ~3 seconds

---

✨ What it does

🎬 Play by name stv play netflix "Dark" s1e1 stv play youtube "baby shark" stv play spotify "chill vibes" Say the name. stv finds the ID, opens the app, starts playback.	🔗 Cast any URL stv cast https://youtu.be/dQw4w stv cast https://netflix.com/watch/... stv cast https://open.spotify.com/... Friend sends a link. Paste it. TV plays it.	🎵 Queue & party stv queue add youtube "Gangnam Style" stv queue add spotify "Blinding Lights" stv queue play Everyone adds their pick. TV plays in order.
🎭 Scene presets stv scene movie-night # volume 20, cinema stv scene kids # volume 15, Cocomelon stv scene sleep # rain sounds, auto-off One command sets the vibe.	🔊 Multi-room audio stv audio play "lo-fi beats" stv audio volume kitchen 30 stv audio stop Screens off. Music everywhere. Free Sonos.	📺 TV as display stv display message "Dinner!" stv display clock stv display dashboard "Temp:22°C" Dashboards, clocks, signage. $0/month.
📊 Watch intelligence stv insights stv screen-time stv sub-value netflix --cost 17.99 Is your Netflix worth $18/month?	🌐 Sync party stv --all play youtube "lo-fi beats" stv --group party play netflix "Wed..." stv --all off # good night Every TV. At once. Even remote friends.	🤖 AI concierge "Play something chill" → tv_recommend → tv_play → Playing The Queen's Gambit 21 MCP tools. One sentence is enough.

---

🤖 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.

Setup (one line): { "mcpServers": { "tv": { "command": "uvx", "args": ["stv"] } } } Or via OpenClaw: clawhub install smartest-tv

Then just talk: You: "I just got home, set up movie night" Claude: 🎬 Movie night activated. Volume → 20, cinema mode on. Based on your history: 1. The Queen's Gambit (Netflix) 2. Ozark (Netflix) 3. Squid Game S2 (Netflix) You: "Play 1, put a clock on kitchen TV" Claude: ✓ Playing The Queen's Gambit ✓ Clock on kitchen TV

All 21 MCP tools

Category	Tool	What it does
Play	tv_play	Search + play by name
	tv_cast	Cast any URL
	tv_next	Continue watching
	tv_launch	Launch app with ID
	tv_resolve	Get content ID only
Discover	tv_whats_on	Trending content
	tv_recommend	Personalized picks
Control	tv_power	On/off
	tv_volume	Get/set/step/mute
	tv_screen	Screen on/off
	tv_notify	Toast notification
	tv_status	Current state
Organize	tv_queue	Play queue
	tv_scene	Scene presets
	tv_history	Watch history
Intelligence	tv_insights	Viewing stats
	tv_display	TV as display
	tv_audio	Multi-room audio
Multi-TV	tv_sync	Play on all TVs
	tv_list_tvs	List TVs
	tv_groups	TV groups

---

📅 A day with stv

Time	What happens
7am	stv display dashboard "Weather:18°C" "Meeting:10am" on kitchen TV
8am	stv scene kids --tv kids-room -- Cocomelon, volume 15
12pm	Friend sends Netflix link → stv cast <url>
5pm	stv screen-time → kids watched 2h 15m today
6:30pm	stv scene movie-night -- volume 20, cinema mode
7pm	stv recommend --mood chill → suggests Ozark
9pm	stv audio play "friday vibes" -p spotify -- music everywhere
10pm	stv --group party play netflix "Wednesday" s1e1 -- sync
11:30pm	stv scene sleep → stv --all off -- good night

---

🔥 Killer combos

🌙 Bedtime autopilot stv audio play "rain" --rooms bedroom stv scene sleep stv --all off Ambient sound, screen off, auto-timer, every other TV killed.

🎧 Free Sonos stv audio play "lo-fi beats" stv audio volume kitchen 40 stv audio volume bedroom 15 Every TV is a speaker. Per-room volume. Screens off.

💰 Subscription audit stv sub-value netflix --cost 17.99 # → $8.50/hr — consider canceling stv sub-value youtube --cost 13.99 # → $1.20/hr — good value

10 more recipes →

---

⚙️ 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

---

🔌 Works with

Integration	How
Claude Code / Cursor	Add MCP config → "play Dark s1e1"
OpenClaw	clawhub install smartest-tv → Telegram bot
Home Assistant	Shell commands in automations
cron	0 7 * * * stv display dashboard ...
Shell scripts	sleep-mode, party-mode one-liners
Any MCP client	21 tools, stdio or HTTP (stv serve)

---

📚 Docs

Getting Started	Setup for any TV brand
Playing Content	play, cast, queue, resolve
Scenes	movie-night, kids, sleep, custom
Sync & Party	Multi-TV, remote watch party
Recipes	10 powerful feature combos
AI Agents	MCP for Claude, Cursor, OpenClaw
CLI Reference	Every command and option
MCP Tools	All 21 tools with parameters

---

🤝 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

---

_{FSL-1.1-Apache-2.0 · Free to use · Becomes Apache 2.0 in 2028 · No cloud required}