AI TV Guide

A spoiler-safe AI guide for your TV. Pause anything, ask “what’s happening?” or “who is that actor?”, and get an answer that only uses what you’ve already watched.

Comment

Inspiration

We’ve all paused a show 40 minutes in and thought, wait, who is that, and why does it matter? Your options are bad. You can search the web and risk a spoiler, ask whoever’s on the couch, or keep watching confused. Streaming apps have some built-in help, such as Prime Video’s X-Ray, but it only works inside one app. We wanted a guide that you can simply ask, and that never tells you more than you’ve already watched.

What it does

TV Guide is an AI companion for the TV. You say what you’re watching and how far in you are, then ask:

“What’s happening in this scene?” “Catch me up on the story so far.” “Who’s in this, and who do they play?” “Who directed this episode?”

Answers are 2 to 4 plain sentences, short enough to read from the couch. A “What the AI was given” panel shows exactly what the model was allowed to see, and which episodes were withheld.

How we built it

The prototype has no framework and no npm dependencies:

Backend: Node.js using only built-in modules (http, fetch, node:test). Data: the TMDB API for titles, cast, crew and episode synopses. AI: Claude through the Anthropic Messages API, with a system prompt that tells it to treat the reference material as data and to admit when it’s inferring. Frontend: a single vanilla HTML/CSS/JS page with a search box, season and episode pickers, a playback-position slider and quick-question buttons. Mock mode: with no API keys it runs on a fictional catalogue, so the whole pipeline can be tested offline.

Challenges we ran into

We can’t see the video. Streaming apps use DRM, so a third-party app can’t capture frames or audio. The guide works from metadata and synopses, so scene-level answers are inferences. The prompt makes the model say so rather than pretend it’s watching. Spoilers within an episode. TMDB’s synopses cover whole episodes, not minute by minute. We handled this by labelling the synopsis as covering the whole episode and giving the model the viewer’s position. That is a prompt-level guard, not a hard filter. Cast lists leak. A series-wide cast list can hint at characters who haven’t appeared yet. We labelled it accordingly and told the model not to volunteer unseen characters, but a hard filter would need per-episode cast data. Platform uncertainty. The plan to read what’s playing relies on Android-based Fire OS media sessions. Newer Fire TV devices on Vega OS don’t run Android apps, and we haven’t confirmed an equivalent there. Small bugs along the way. The test command failed until we changed how the test runner was invoked, and early on I sent only some of the project’s files, which made the server crash on a missing module. Both are fixed.

Accomplishments that we're proud of

A working answer engine where spoiler safety is enforced by what the model is given, and verified by tests. A transparent “what the AI was given” view that makes the clamp easy to demonstrate. It runs with zero dependencies and zero keys.

What we learned

Controlling the model’s input is far more reliable than asking it to keep a secret. Metadata granularity limits answer quality more than model quality does. Timed subtitles would help the most. For a publishable app, platform rules (DRM, permissions, Appstore review, data licensing) matter as much as the AI.

What's next for AI TV Guide

Test with live TMDB and Claude on 10 to 15 real shows and judge answer quality. Build the Fire TV app: a media-session listener to detect the title and position, plus voice input from the remote. Move the backend to a hosted service that holds the API keys, with rate limits. Add timed subtitles where licensing allows, for scene-level accuracy. Confirm Vega OS support and Amazon Appstore requirements.

Built With

Share this project:

Updates

Submission history