smartest-tv

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.

# 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 <URL>
├── 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 <name> to any command
├── Play on ALL TVs → add --all to play/off/volume/mute/notify
├── Play on a GROUP of TVs → add --group <name> 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

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.

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.

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.

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.

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.

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.

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.

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.

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.

TV control

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 <URL> (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":

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:

rm ~/.config/smartest-tv/cache.

---

*Content truncated.*