--- name: smartest-tv description: "Control a smart TV or open streaming content in the browser. Play Netflix episodes/movies, YouTube videos, Spotify music — on TV or in browser (--tv browser). Also handles volume, power, notifications, history, 'continue watching', scenes, recommendations, cast URLs, queue, and multi-TV management. Triggers on: 'play', 'watch', 'TV', 'Netflix', 'YouTube', 'Spotify', 'volume', 'mute', 'good night', 'movie night', 'continue', 'next episode', 'scene', 'recommend', 'trending', 'cast', 'queue', 'play on browser', 'open in browser', 'stv'." version: 1.0.0 metadata: openclaw: requires: env: [] bins: - python3 - stv anyBins: [] config: [] primaryEnv: "" emoji: "📺" homepage: https://github.com/Hybirdss/smartest-tv os: [macos, linux] install: - kind: uv package: stv bins: [stv] --- # smartest-tv Control a smart TV via the `stv` CLI — or open content in the browser. ## TV vs Browser - **TV configured**: `stv play netflix "Dark" s1e1` - **No TV configured**: same command — auto-opens in browser - **TV configured but user wants browser**: `stv --tv browser play netflix "Dark" s1e1` - **User doesn't specify**: ask whether they want TV or browser **IMPORTANT**: `--tv browser` goes BEFORE the subcommand. `browser` is NOT a platform. ```bash # CORRECT: stv --tv browser play netflix Frieren -s 2 -e 8 stv --tv browser play youtube "lofi beats" # WRONG — these will fail: stv play browser Frieren # "browser" is not a platform stv play --tv browser Frieren # --tv must come before play ``` ## Decision Tree Use this to pick the right action: ``` User wants to... ├── Watch something specific → stv play (or stv --tv browser play for browser) ├── Watch a URL someone shared → stv cast ├── Continue what they were watching → stv next ├── Know what's popular → stv whats-on ├── Get a suggestion → stv recommend ├── Set a mood → stv scene ├── Build a playlist → stv queue add, then stv queue play ├── Control the TV → stv volume / stv mute / stv on / stv off ├── Send a message to the screen → stv notify ├── Use a different TV → add --tv to any command ├── Play on ALL TVs → add --all to play/off/volume/mute/notify ├── Play on a GROUP of TVs → add --group to play/off/volume/mute/notify ├── Open in browser instead of TV → add --tv browser ├── Watch with friends (remote) → tv_sync (MCP) or --group with remote TVs ├── Show something on TV screen → stv display (message, clock, dashboard, URL) ├── Play music everywhere → stv audio play (screens off, multi-room) ├── Check viewing habits → stv insights (weekly report, screen time) ├── Is my Netflix worth it? → stv sub-value netflix --cost 17.99 └── Don't know what to do → stv whats-on, then stv recommend ``` ## Platform Detection The user rarely says "netflix" or "youtube". Infer it: | User says | Platform | Why | |-----------|----------|-----| | "Play Stranger Things S4E7" | netflix | Series with season/episode | | "Play Glass Onion" | netflix | Movie title | | "Play Percy Jackson" | disney or auto | Could be Disney+, let auto-detect decide | | "Play The Boys" | prime or auto | Prime Video original | | "Play Frieren" | auto | Let stv figure out the platform | | "Play that cooking video" | youtube | General video content | | "Play baby shark" | youtube | Kids content, music video | | "Play Ye White Lines" | spotify | Song/artist name | | "Play my chill playlist" | spotify | Playlist / music genre | | "Play lofi hip hop radio" | youtube | Live stream / radio | When ambiguous or unsure, omit the platform — `stv play "title"` auto-detects which streaming service has it in your region. ## Core Commands ### Play something specific ```bash stv play netflix "Stranger Things" s4e7 # series episode stv play netflix "Glass Onion" # movie (auto title ID) stv play disney "Percy Jackson" s1e1 # Disney+ stv play prime "The Boys" s1e1 # Prime Video stv play "Frieren" # auto-detects platform stv play youtube "baby shark" # YouTube video stv play spotify "Ye White Lines" # Spotify track ``` 30+ streaming platforms supported: Netflix, Disney+, Prime Video, Max, Hulu, Paramount+, Peacock, Crunchyroll, Apple TV+, and more. Skip the platform name and stv auto-detects where it's streaming. ### Cast a URL User shares a link? Cast it directly. No need to figure out the platform or ID. ```bash stv cast https://youtube.com/watch?v=dQw4w9WgXcQ stv cast https://netflix.com/watch/81726716 stv cast https://open.spotify.com/track/3bbjDFVu... ``` ### Continue watching "Next episode", "keep watching", "where was I" → use `stv next`. ```bash stv next # most recent show stv next "Breaking Bad" # specific show stv history # what they've been watching ``` ### What's trending "What should I watch?", "what's popular?", "anything good on?" → start with whats-on. ```bash stv whats-on # Netflix + YouTube trending stv whats-on netflix # Netflix only stv whats-on youtube # YouTube only ``` ### Recommend based on history "Recommend something", "I'm bored", "suggest a movie" → use recommend. ```bash stv recommend # based on watch history stv recommend --mood chill # relaxing content stv recommend --mood action # thriller/action stv recommend --mood kids # family-friendly ``` After recommending, ask "want me to play any of these?" and use `stv play` on their choice. ### Scene presets "Movie night", "kids mode", "sleep mode", "music mode" → use scenes. ```bash stv scene movie-night # volume 20 + cinema vibe stv scene kids # volume 15 + Cocomelon stv scene sleep # ambient sounds + auto-off stv scene music # screen off + music stv scene list # all available scenes stv scene create date-night # make a custom scene ``` ### Play queue (party mode) Multiple people want to add songs/videos? Use the queue. ```bash stv queue add youtube "Gangnam Style" stv queue add youtube "Despacito" stv queue add spotify "playlist:Friday Night" stv queue show # see the list stv queue play # start playing stv queue skip # next in queue stv queue clear # reset ``` ### Multi-TV "Play on bedroom TV", "turn off the kitchen TV" → use --tv flag. ```bash stv multi list # see all TVs stv play netflix "Dark" --tv bedroom stv off --tv kids-room stv scene kids --tv kids-room ``` ### Sync / Party mode "Play on all TVs", "play in every room", "watch with friends" → use --all or --group. ```bash stv --all play youtube "lo-fi beats" # every TV in the house stv --group party play netflix "Wednesday" s1e1 # group of TVs stv --all volume 20 # same volume everywhere stv --all off # good night, all TVs stv --group home notify "Dinner's ready!" # toast on group ``` For AI agents (MCP), use `tv_sync_play` to play on multiple TVs at once: ``` tv_sync_play(platform="netflix", query="Squid Game", season=2, episode=3, group="watch-party") ``` **Remote TVs:** Friends run `stv serve`, you add them as `--platform remote`. Groups can mix local and remote TVs. See [Sync & Party Mode guide](docs/guides/sync-party.md). ### TV control ```bash stv volume 25 # set volume stv mute # toggle stv on / stv off # power stv status # what's playing, volume stv notify "Dinner's ready!" # toast on screen ``` ## Common Scenarios ### "I'm home from work" 1. `stv scene movie-night` 2. `stv recommend --mood chill` 3. User picks one → `stv play netflix "..."` or `stv play youtube "..."` ### "Put something on for the kids" 1. `stv scene kids --tv kids-room` (scene auto-plays Cocomelon at safe volume) ### "Good night" 1. `stv scene sleep` (ambient sounds, TV auto-off) ### "Friends are coming over" 1. Everyone: `stv queue add youtube "their song"` 2. `stv queue play` ### "What was I watching?" 1. `stv next` (continues automatically) Or: `stv history` → show the list → user picks → `stv play` ### "Someone sent me a link" 1. `stv cast ` (auto-detects platform + ID) ### "Watch party with friends" 1. `stv --group watch-party play netflix "Wednesday" s1e1` Or MCP: `tv_sync_play(platform="netflix", query="Wednesday", season=1, episode=1, group="watch-party")` ### "Play music in every room" 1. `stv --all play youtube "lo-fi hip hop"` or `stv --all play spotify "chill vibes"` ## Setup If `stv status` fails with "No TV configured": ```bash stv setup # auto-discover + pair stv setup --ip 192.168.1.100 # direct IP stv doctor # diagnose issues ``` ## MCP Tools (21 tools, optimized for AI agents) | Tool | When to use | Key params | |------|------------|------------| | `tv_play` | Play content by name (most common) | `platform`, `query`, `season?`, `episode?`, `tv_name?` | | `tv_cast` | User shares a URL | `url`, `tv_name?` | | `tv_next` | "Continue watching", "next episode" | `query?`, `tv_name?` | | `tv_whats_on` | "What's trending?", "what's popular?" | `platform?`, `limit?` | | `tv_recommend` | "Suggest something", "I'm bored" | `mood?`, `limit?` | | `tv_scene` | Scene presets (list or run) | `action: list/run`, `name?`, `tv_name?` | | `tv_queue` | Play queue (add/show/play/skip/clear) | `action`, `platform?`, `query?`, `tv_name?` | | `tv_power` | Turn TV on/off | `on: bool`, `tv_name?` | | `tv_volume` | Get/set volume, step, mute — all in one | `level?`, `direction?`, `mute?`, `tv_name?` | | `tv_screen` | Screen on/off (audio continues) | `on: bool`, `tv_name?` | | `tv_status` | Current app, volume, model | `tv_name?` | | `tv_notify` | Toast notification on screen | `message`, `tv_name?` | | `tv_launch` | Launch app with known ID | `app`, `content_id?`, `tv_name?` | | `tv_history` | Recent play history | `limit?` | | `tv_resolve` | Get content ID without playing | `platform`, `query`, `season?`, `episode?` | | `tv_sync` | Play on multiple TVs at once | `platform`, `query`, `group?`, `tv_names?` | | `tv_list_tvs` | Show all configured TVs | | | `tv_groups` | List TV groups | | | `tv_insights` | Viewing stats, screen time, sub value | `period?`, `report_type?` | | `tv_display` | TV as display: dashboards, clocks, messages | `content_type`, `data?`, `tv_name?` | | `tv_audio` | Multi-room audio, screens off | `action`, `query?`, `platform?`, `rooms?` | ## Troubleshooting ### Wrong content plays or resolve fails Cache might be stale. Clear it and retry: ```bash rm ~/.config/smartest-tv/cache.json stv play netflix "Dark" s1e1 # re-resolves fresh ``` ### Platform auto-detect picks wrong service Specify the platform explicitly: ```bash stv play disney "Percy Jackson" s1e1 # force Disney+ ``` ## Notes - All CLI commands support `--format json` for structured output - 30+ platforms: Netflix, Disney+, Prime, Max, Hulu, Paramount+, Peacock, Crunchyroll, Apple TV+, YouTube, Spotify, and more - First resolve: ~2-3s (web fetch). Cached after: ~0.1s - Netflix profile selection happens on-screen (can't skip) - If auto-search fails: `stv play netflix "X" --title-id XXXXX` - `tv_name` is optional on every MCP tool. Omit it to use the default TV ## MCP Configuration Claude Code (stdio, automatic): ```json {"mcpServers": {"tv": {"command": "uvx", "args": ["stv"]}}} ``` OpenClaw / other agents: ```json {"mcpServers": {"tv": {"command": "python3", "args": ["-m", "smartest_tv"], "env": {"TV_PLATFORM": "lg", "TV_IP": "192.168.1.100"}}}} ``` Remote HTTP: ```bash stv serve --port 8910 # Then connect to http://localhost:8910/sse ```