{
  "markdown": "<h1 align=\"center\">\n  <br>\n  📺\n  <br>\n  smartest-tv\n  <br>\n</h1>\n\n<h4 align=\"center\">The CLI your TV has been waiting for.</h4>\n\n<p align=\"center\">\n  <b>Play Netflix / Apple TV+ / YouTube / Spotify by name. Cast URLs. Multi-room audio. AI concierge. All from your terminal.</b>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/stv/\"><img src=\"https://img.shields.io/pypi/v/stv?style=flat-square&color=blue\" alt=\"PyPI: stv\"></a>\n  <a href=\"https://pepy.tech/project/stv\"><img src=\"https://static.pepy.tech/badge/stv\" alt=\"Total Downloads\"></a>\n  <a href=\"https://pepy.tech/project/stv\"><img src=\"https://static.pepy.tech/badge/stv/month\" alt=\"Downloads/month\"></a>\n  <a href=\"tests/\"><img src=\"https://img.shields.io/badge/tests-282%20passed-brightgreen?style=flat-square\" alt=\"Tests\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-yellow?style=flat-square\" alt=\"MIT License\"></a>\n  <a href=\"https://python.org\"><img src=\"https://img.shields.io/badge/python-3.11+-3776ab?style=flat-square&logo=python&logoColor=white\" alt=\"Python\"></a>\n  <a href=\"https://modelcontextprotocol.io\"><img src=\"https://img.shields.io/badge/MCP-21%20tools-8A2BE2?style=flat-square\" alt=\"MCP Tools\"></a>\n  <a href=\"https://glama.ai/mcp/servers/Hybirdss/smartest-tv\"><img src=\"https://img.shields.io/badge/Glama-A%20A%20A-00d992?style=flat-square\" alt=\"Glama Score\"></a>\n  <a href=\"https://github.com/punkpeye/awesome-mcp-servers\"><img src=\"https://img.shields.io/badge/awesome--mcp--servers-listed-fc60a8?style=flat-square&logo=awesome-lists&logoColor=white\" alt=\"Awesome MCP Servers\"></a>\n  <a href=\"https://github.com/vitalets/awesome-smart-tv\"><img src=\"https://img.shields.io/badge/awesome--smart--tv-listed-fc60a8?style=flat-square&logo=awesome-lists&logoColor=white\" alt=\"Awesome Smart TV\"></a>\n  <a href=\"https://github.com/hacs/integration\"><img src=\"https://img.shields.io/badge/HACS-Custom-41BDF5?style=flat-square\" alt=\"HACS\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"docs/i18n/README.ko.md\">한국어</a> · <a href=\"docs/i18n/README.zh.md\">中文</a> · <a href=\"docs/i18n/README.ja.md\">日本語</a> · <a href=\"docs/i18n/README.es.md\">Español</a> · <a href=\"docs/i18n/README.de.md\">Deutsch</a> · <a href=\"docs/i18n/README.pt-br.md\">Português</a> · <a href=\"docs/i18n/README.fr.md\">Français</a>\n</p>\n\n<br>\n\n<p align=\"center\"><code>pip install stv && stv play \"Frieren\"</code></p>\n\n<p align=\"center\"><sub>No TV? Opens in your browser. Got a TV? <code>stv setup</code> to connect it.</sub></p>\n\n<p align=\"center\">\n  <img src=\"docs/assets/hero.png\" alt=\"The Evolution of TV Control\" width=\"720\">\n</p>\n\n---\n\n<br>\n\n<table align=\"center\">\n<tr>\n<th>😩 Without stv</th>\n<th>😎 With stv</th>\n</tr>\n<tr>\n<td>\n\n1. Pick up remote\n2. Open Netflix app\n3. Search for show\n4. Pick the season\n5. Pick the episode\n6. Press play\n\n**~30 seconds**\n\n</td>\n<td>\n\n```bash\nstv play netflix \"Dark\" s1e1\n```\n\n**~3 seconds**\n\n</td>\n</tr>\n</table>\n\n<br>\n\n> **No TV? No problem.** Without a TV configured, stv opens content directly in your browser.\n> Netflix, YouTube, Spotify, Disney+ — just `pip install stv` and go.\n\n---\n\n## 🛋 Vibe-code and chill\n\nVibe-coding at 2am. Claude writes your code. You tell it to put on a show. It does.\n\n```\nyou: play frieren on the living room tv\nclaude: Playing Frieren s2e8 on Living Room. (3s)\n\nyou: bit quieter\nclaude: Volume → 18.\n\nyou: good night\nclaude: All 3 TVs off.\n```\n\nAlready installed stv? Just tell Claude:\n\n```bash\n# Option 1 — just talk (zero config)\n\"run stv play netflix Frieren s2e8\"\n\n# Option 2 — install the Skill for auto-trigger\nclawhub install smartest-tv\n# now \"play Frieren\", \"good night\", \"next episode\" just work mid-session\n```\n\n<sub>Also available as an MCP server (21 tools) for Claude Code, Codex, Antigravity, and other MCP clients.</sub>\n\n---\n\n## 🎯 Just type `stv`\n\n<p align=\"center\">\n  <img src=\"docs/assets/screenshots/12-home-connected.png\" alt=\"stv home dashboard\" width=\"720\">\n</p>\n\nNo subcommand? You get a Now Playing card and three contextual next-actions\nbased on your watch history — not a 30-command help dump.\n\n```bash\n$ stv \"play dark on netflix\"     # natural language works\n$ stv play \"Frieren\"             # auto-detects platform\n$ stv next                       # continue last show\n$ stv stats                      # → insights\n```\n\nUnknown input? You get a friendly hint, not an error.\n\n---\n\n## 🎨 A CLI that looks like a product\n\n<table>\n<tr>\n<td width=\"50%\"><img src=\"docs/assets/screenshots/01-status.png\" alt=\"stv status\"></td>\n<td width=\"50%\"><img src=\"docs/assets/screenshots/07-insights.png\" alt=\"stv insights\"></td>\n</tr>\n<tr>\n<td><img src=\"docs/assets/screenshots/03-scenes.png\" alt=\"stv scene list\"></td>\n<td><img src=\"docs/assets/screenshots/02-multi-list.png\" alt=\"stv multi list\"></td>\n</tr>\n<tr>\n<td><img src=\"docs/assets/screenshots/06-doctor.png\" alt=\"stv doctor\"></td>\n<td><img src=\"docs/assets/screenshots/16-nl-demo.png\" alt=\"natural language\"></td>\n</tr>\n</table>\n\nEvery command renders with Catppuccin Mocha colors, semantic icons, and real\nvisual hierarchy. Prefer another palette? Set `STV_THEME=nord` or `STV_THEME=gruvbox`.\n\n`--format json` is always available when you need to pipe to `jq`.\n\n---\n\n## ✨ What it does\n\n<table>\n<tr>\n<td width=\"33%\" valign=\"top\">\n\n### 🎬 Play by name\n```bash\nstv play netflix \"Dark\" s1e1\nstv play disney \"Percy Jackson\" s1e1\nstv play prime \"The Boys\" s1e1\nstv play \"Frieren\" s2e8          # auto-detects platform\n```\nSay the name. stv finds the ID, opens the app, starts playback. Netflix and Apple TV+ resolve via HTML parsing. Disney+, Max, Prime, Hulu, Paramount+, Peacock, Crunchyroll, and [every platform on JustWatch](https://www.justwatch.com/) resolve via their API — no login, no API key. Skip the platform name and stv auto-detects where it's streaming in your region.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 🔗 Cast any URL\n```bash\nstv cast https://youtu.be/dQw4w\nstv cast https://netflix.com/watch/...\nstv cast https://open.spotify.com/...\n```\nFriend sends a link. Paste it. TV plays it.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 🎵 Queue & party\n```bash\nstv queue add youtube \"Gangnam Style\"\nstv queue add spotify \"Blinding Lights\"\nstv queue play\n```\nEveryone adds their pick. TV plays in order.\n\n</td>\n</tr>\n<tr>\n<td width=\"33%\" valign=\"top\">\n\n### 🎭 Scene presets\n```bash\nstv scene movie-night   # volume 20, cinema\nstv scene kids          # volume 15, Cocomelon\nstv scene sleep         # rain sounds, auto-off\n```\nOne command sets the vibe.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 🔊 Multi-room audio\n```bash\nstv audio play \"lo-fi beats\"\nstv audio volume kitchen 30\nstv audio stop\n```\nScreens off. Music everywhere.<br>**Free Sonos.**\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 📺 TV as display\n```bash\nstv display message \"Dinner!\"\nstv display clock\nstv display dashboard \"Temp:22°C\"\n```\nDashboards, clocks, signage.<br>**$0/month.**\n\n</td>\n</tr>\n<tr>\n<td width=\"33%\" valign=\"top\">\n\n### 📊 Watch intelligence\n```bash\nstv insights\nstv screen-time\nstv sub-value netflix --cost 17.99\n```\nIs your Netflix worth $18/month?\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 🌐 Sync party\n```bash\nstv --all play youtube \"lo-fi beats\"\nstv --group party play netflix \"Wed...\"\nstv --all off   # good night\n```\nEvery TV. At once. Even remote friends.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### 🤖 AI concierge\n```\n\"Play something chill\"\n→ tv_recommend → tv_play\n→ Playing The Queen's Gambit\n```\n21 MCP tools. One sentence is enough.\n\n</td>\n</tr>\n</table>\n\n---\n\n## 🤖 Tell your AI to control your TV\n\nstv is an **MCP server**. Claude, GPT, Cursor, or any MCP client can control your TV with natural language.\n\n<table>\n<tr>\n<td width=\"50%\" valign=\"top\">\n\n**Setup (one line):**\n\n```json\n{\n  \"mcpServers\": {\n    \"tv\": {\n      \"command\": \"uvx\",\n      \"args\": [\"stv\"]\n    }\n  }\n}\n```\n\nOr via [OpenClaw](docs/integrations/openclaw.md):\n```bash\nclawhub install smartest-tv\n```\n\n</td>\n<td width=\"50%\" valign=\"top\">\n\n**Then just talk:**\n\n```\nYou: \"I just got home, set up movie night\"\n\nClaude: 🎬 Movie night activated.\n  Volume → 20, cinema mode on.\n  \n  Based on your history:\n  1. The Queen's Gambit (Netflix)\n  2. Ozark (Netflix)\n  3. Squid Game S2 (Netflix)\n\nYou: \"Play 1, put a clock on kitchen TV\"\n\nClaude: ✓ Playing The Queen's Gambit\n         ✓ Clock on kitchen TV\n```\n\n</td>\n</tr>\n</table>\n\n<details>\n<summary><b>All 21 MCP tools</b></summary>\n<br>\n\n| Category | Tool | What it does |\n|----------|------|-------------|\n| **Play** | `tv_play` | Search + play by name |\n| | `tv_cast` | Cast any URL |\n| | `tv_next` | Continue watching |\n| | `tv_launch` | Launch app with ID |\n| | `tv_resolve` | Get content ID only |\n| **Discover** | `tv_whats_on` | Trending content |\n| | `tv_recommend` | Personalized picks |\n| **Control** | `tv_power` | On/off |\n| | `tv_volume` | Get/set/step/mute |\n| | `tv_screen` | Screen on/off |\n| | `tv_notify` | Toast notification |\n| | `tv_status` | Current state |\n| **Organize** | `tv_queue` | Play queue |\n| | `tv_scene` | Scene presets |\n| | `tv_history` | Watch history |\n| **Intelligence** | `tv_insights` | Viewing stats |\n| | `tv_display` | TV as display |\n| | `tv_audio` | Multi-room audio |\n| **Multi-TV** | `tv_sync` | Play on all TVs |\n| | `tv_list_tvs` | List TVs |\n| | `tv_groups` | TV groups |\n\n</details>\n\n---\n\n## 📅 A day with stv\n\n| Time | What happens |\n|------|-------------|\n| **7am** | `stv display dashboard \"Weather:18°C\" \"Meeting:10am\"` on kitchen TV |\n| **8am** | `stv scene kids --tv kids-room` -- Cocomelon, volume 15 |\n| **12pm** | Friend sends Netflix link → `stv cast <url>` |\n| **5pm** | `stv screen-time` → kids watched 2h 15m today |\n| **6:30pm** | `stv scene movie-night` -- volume 20, cinema mode |\n| **7pm** | `stv recommend --mood chill` → suggests Ozark |\n| **9pm** | `stv audio play \"friday vibes\" -p spotify` -- music everywhere |\n| **10pm** | `stv --group party play netflix \"Wednesday\" s1e1` -- sync |\n| **11:30pm** | `stv scene sleep` → `stv --all off` -- good night |\n\n---\n\n## 🔥 Killer combos\n\n<table>\n<tr>\n<td width=\"33%\" valign=\"top\">\n\n**🌙 Bedtime autopilot**\n```bash\nstv audio play \"rain\" --rooms bedroom\nstv scene sleep\nstv --all off\n```\nAmbient sound, screen off, auto-timer, every other TV killed.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n**🎧 Free Sonos**\n```bash\nstv audio play \"lo-fi beats\"\nstv audio volume kitchen 40\nstv audio volume bedroom 15\n```\nEvery TV is a speaker. Per-room volume. Screens off.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n**💰 Subscription audit**\n```bash\nstv sub-value netflix --cost 17.99\n# → $8.50/hr — consider canceling\n\nstv sub-value youtube --cost 13.99\n# → $1.20/hr — good value\n```\n\n</td>\n</tr>\n</table>\n\n> [**10 more recipes →**](docs/guides/recipes.md)\n\n---\n\n<p align=\"center\">\n  <a href=\"https://github.com/Hybirdss/smartest-tv/releases/download/v0.3.0/KakaoTalk_20260403_051617935.mp4\">\n    <img src=\"docs/assets/demo.gif\" alt=\"smartest-tv demo\" width=\"720\">\n  </a>\n  <br>\n  <sub>▲ Click to watch the full demo</sub>\n</p>\n\n---\n\n## ⚙️ How it works\n\n```\n  \"Play Dark S1E1\"\n        │\n        ▼\n  ┌─── Resolution ───┐\n  │ Cache → API → Web │  content_id\n  │  0.1s   1s    3s  │──────────────▶ 📺 TV plays it\n  └───────────────────┘       │\n                         Deep link via\n                    LG / Samsung / Roku / Android\n```\n\nSay 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.\n\n---\n\n## 📦 Install\n\n```bash\npip install stv                    # LG webOS (default)\npip install \"stv[samsung]\"         # Samsung Tizen\npip install \"stv[android]\"         # Android TV / Fire TV\npip install \"stv[all]\"             # Everything\n```\n\n```bash\nstv setup                          # auto-discover + pair your TV\n```\n\n> Supports **LG webOS** · **Samsung Tizen** · **Android TV / Fire TV** · **Roku**\n\n### Home Assistant (HACS)\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=flat-square)](https://github.com/hacs/integration)\n\nAdd as a custom repository (default listing in review: [hacs/default#6907](https://github.com/hacs/default/pull/6907)):\n\n```\nHACS → ⋮ (top right) → Custom repositories\n  URL: https://github.com/Hybirdss/smartest-tv\n  Category: Integration → Add\nThen: Install → Restart HA\nSettings → Integrations → Add → \"Smartest TV\" → auto-discovers your TVs\n```\n\nAndroid TV / Fire TV: the setup flow shows a **6-digit PIN on the TV** —\nenter it in the pairing form to finish. In HA OS / HA Container set\n`STV_CONFIG_DIR=/config/smartest-tv` so pairing survives container\nrebuilds. See [docs/integrations/home-assistant.md](docs/integrations/home-assistant.md).\n\nThen use in automations:\n\n```yaml\nservice: media_player.play_media\ntarget:\n  entity_id: media_player.living_room\ndata:\n  media_content_type: stv\n  media_content_id: \"netflix:Frieren:s2e8\"\n```\n\nThis 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.\n\n---\n\n## 🔌 Works with\n\n| Integration | How |\n|------------|-----|\n| **Home Assistant** | HACS custom integration → `media_player.play_media` with content resolution |\n| **Claude Code / Cursor** | Add MCP config → `\"play Dark s1e1\"` |\n| **OpenClaw** | `clawhub install smartest-tv` → Telegram bot |\n| **cron** | `0 7 * * * stv display dashboard ...` |\n| **Shell scripts** | `sleep-mode`, `party-mode` one-liners |\n| **Any MCP client** | 21 tools, stdio or HTTP (`stv serve`) |\n\n---\n\n## 📚 Docs\n\n| | |\n|---|---|\n| [Getting Started](docs/getting-started/installation.md) | Setup for any TV brand |\n| [Playing Content](docs/guides/playing-content.md) | play, cast, queue, resolve |\n| [Scenes](docs/guides/scenes.md) | movie-night, kids, sleep, custom |\n| [Sync & Party](docs/guides/sync-party.md) | Multi-TV, remote watch party |\n| [Recipes](docs/guides/recipes.md) | **10 powerful feature combos** |\n| [AI Agents](docs/guides/ai-agents.md) | MCP for Claude, Cursor, OpenClaw |\n| [CLI Reference](docs/reference/cli.md) | Every command and option |\n| [MCP Tools](docs/reference/mcp-tools.md) | All 21 tools with parameters |\n\n---\n\n## 🔓 Open source\n\nEvery 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](https://www.justwatch.com/).\n\n---\n\n## 🔒 Privacy\n\nstv runs on your **local network**. No telemetry, no analytics, no cloud\nsync, no phoning home about what you watch. There is no `posthog`, no\n`amplitude`, no `sentry`, no `mixpanel` — grep the source.\n\n**One exception — community cache contribution.** When you play content\nthat isn't in the local cache, stv resolves it (via web parsing) and\nsubmits the resolved ID to a shared community cache so the next user\ngets an instant lookup. This is the same pattern as Wikipedia or a\npackage mirror — many small contributions, anonymous.\n\nWhat's sent (background HTTPS, fire-and-forget, never blocks playback):\n\n- Platform name (`netflix` / `youtube` / `spotify`)\n- Content slug (e.g. `frieren`)\n- Resolved content ID (Netflix title ID, YouTube video ID, Spotify URI)\n\nWhat's **not** sent:\n\n- Your name, email, or any user identifier\n- Your IP address (the CDN sees a connection IP per standard HTTP, but\n  the client never reads or transmits it)\n- Your watch history or play timestamps\n- Your TV's IP address or hardware info\n- Anything about how often or when you use stv\n\nTo disable cache contribution entirely:\n\n```bash\nexport STV_NO_CONTRIBUTE=1\n```\n\nSource: [`src/smartest_tv/cache.py`](src/smartest_tv/cache.py) — search for `_contribute`.\n\n---\n\n## 🤝 Contributing\n\n211 tests. No TV needed to run them.\n\n```bash\npip install -e \".[dev]\"\npython -m pytest tests/ -v\n```\n\nSamsung, Roku, and Android TV drivers need real-world testing. If you have one, [your feedback matters](https://github.com/Hybirdss/smartest-tv/issues).\n\n[Cache Contributions](docs/contributing/cache-contributions.md) · [Driver Development](docs/contributing/driver-development.md)\n\n---\n\n<p align=\"center\">\n  <img src=\"docs/assets/mascot.png\" alt=\"smartest-tv mascot\" width=\"256\">\n</p>\n\n<p align=\"center\">\n  <sub>MIT License · Made with Python · No cloud required</sub>\n</p>\n\n<!-- mcp-name: io.github.Hybirdss/smartest-tv -->\n",
  "bytes": 16486,
  "sha": "de08c2d8adad990f1ff80df684827d8bc7e57eb5c9693dd9d05c955e580c3b73",
  "repo_slug": "hybirdss/smartest-tv",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hybirdss_smartest_tv_93c03d1b/readme"
}