Skip to content

Instantly share code, notes, and snippets.

@dharamveer-gupta

dharamveer-gupta/dharamveer-tmdb-feature.md

Created April 20, 2026 06:45
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save dharamveer-gupta/1647794269f577bee26248a0aefd53c7 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save dharamveer-gupta/1647794269f577bee26248a0aefd53c7 to your computer and use it in GitHub Desktop.
Download ZIP
TMDB Feature v1
Raw
dharamveer-tmdb-feature.md

TvTime‑Style App – v1 Plan (Android‑Focused)

My goal is to ship a lean, polished v1 that validates the core tracking‑first product: users can search, discover, track what they watch, and see where titles stream, without over‑engineering social features or AI.
All TMDB endpoints listed below are available for free non‑commercial use with proper attribution. [web:2]

1. Features good for v1 (Android‑Centric)

The first release should answer three questions quickly and smoothly on mobile:

  1. What am I watching right now?
  2. What should I watch next?
  3. Where can I watch it?

Core Android‑UX features (v1)

  • User onboarding & auth

    • Simple sign‑in (Google/Email + optional TMDB‑linked account for watchlist/favorites).
    • Profile screen with basic preferences (e.g., favorite genres, region for watch‑providers).

  • Search & discovery

    • Unified search bar (movies, TV, people) with suggestions.
    • Fast search results with images, titles, and clear metadata.
    • Discover/home tabs using TMDB’s trending, popular, top‑rated, and genre‑based data. [web:49][web:50]

  • Title detail pages

    • Clean detail screens for movies and TV shows built around TMDB data:
      • Title, synopsis, genres, release date, runtime.
      • Seasons and episode lists (with thumbnails and short descriptions).
      • Cast and crew, images, trailers, and content ratings.
    • Support for both phones and tablets with responsive layout choices (single‑column vs grid‑card).

  • Episode/movie tracking

    • Mark episode or movie as watched (local + server sync).
    • Simple “Continue watching” and “Up next” screens (priority layouts for Android: vertical scroll + recycler view with sticky headers).
    • Offline‑first approach: sync status with TMDB IDs, then reconcile with backend when network is available.

  • Watchlist and favorites

    • Use TMDB watchlist/favorites endpoints if you go with TMDB account linking. [web:2][web:50]
    • Clean card‑based UI for “Watchlist” and “Favorites” tabs, with swipe‑to‑remove and batch actions.

  • Ratings and basic notes

    • Global 1–5 rating (star‑based) on title detail.
    • Optional short text note (stored in your backend, not TMDB).

  • Watch‑provider info

    • Per‑title watch‑provider section showing where a movie/TV show is available in the user’s region (using TMDB watch‑provider endpoints). [web:2]

  • Discover/home UX

    • Horizontal scroll carousels for “Trending,” “Popular,” “Top rated,” “Genres.”
    • Lightweight infinite‑scroll lists with image loading (Glide/Coil) and placeholder skeletons. [web:49][web:50]

2. Features to ignore or postpone

TvTime promotes chat, reactions, favorite‑character voting, reviews, and meme‑style community features, but these are not needed for v1 and add a lot of backend complexity and moderation. [web:3][web:6][web:41]

Ignore completely for v1

  • Public comments and fan threads.
  • Emoji‑reactions, stickers, emotion‑reaction systems.
  • Character‑voting or “favorite‑actor”‑style polls.
  • Meme‑style media, user‑generated reactions, GIF tools.
  • Social feed, follow system, friend activity.
  • Co‑watch, live‑watch rooms, or chat‑on‑episode.
  • Advanced AI‑driven recommendation engine.
  • Heavy gamification (badges, leaderboards, streaks, etc.).

Postpone to later releases

  • Custom collections and smart folders (e.g., “Anime,” “Weekend watch,” “Rewatch later”).
  • Personal stats and recap cards (hours watched, top genres, completion charts).
  • Reminder notifications and release‑calendar polish.
  • AI‑based “Because you watched X” recommendations.
  • Optional social features (friends, shared lists, spoiler‑safe communities).

From an Android‑dev perspective, v1 should be thin on social so the team can focus on smooth navigation, state persistence, and offline‑ready tracking.

3. TMDB APIs (free, non‑commercial use)

The following TMDB endpoints are free for non‑commercial apps with attribution:
“This product uses the TMDB API but is not endorsed or certified by TMDB.” [web:2]
Everything listed here can be used in your Android app as long as the project stays non‑commercial at launch.

Authentication (for TMDB account flows)

  • POST /authentication/token/new
  • POST /authentication/token/validate_with_login
  • POST /authentication/session/new
  • DELETE /authentication/session

Configuration (images, regions, languages)

  • GET /configuration
  • GET /configuration/countries
  • GET /configuration/languages
  • GET /configuration/timezones

Search (critical for mobile UX)

  • GET /search/movie
  • GET /search/tv
  • GET /search/person
  • GET /search/multi

Discover and browse (home/discover tabs)

  • GET /trending/movie/day
  • GET /trending/tv/day
  • GET /movie/popular
  • GET /movie/top_rated
  • GET /movie/upcoming
  • GET /tv/popular
  • GET /tv/top_rated
  • GET /tv/on_the_air
  • GET /tv/airing_today
  • GET /discover/movie
  • GET /discover/tv
  • GET /genre/movie/list
  • GET /genre/tv/list

Movies

  • GET /movie/{movie_id}
  • GET /movie/{movie_id}/credits
  • GET /movie/{movie_id}/images
  • GET /movie/{movie_id}/videos
  • GET /movie/{movie_id}/external_ids
  • GET /movie/{movie_id}/recommendations
  • GET /movie/{movie_id}/similar
  • GET /movie/{movie_id}/release_dates
  • GET /movie/{movie_id}/watch/providers

TV series

  • GET /tv/{series_id}
  • GET /tv/{series_id}/credits
  • GET /tv/{series_id}/images
  • GET /tv/{series_id}/videos
  • GET /tv/{series_id}/external_ids
  • GET /tv/{series_id}/recommendations
  • GET /tv/{series_id}/similar
  • GET /tv/{series_id}/content_ratings
  • GET /tv/{series_id}/watch/providers

Seasons and episodes

  • GET /tv/{series_id}/season/{season_number}
  • GET /tv/{series_id}/season/{season_number}/credits
  • GET /tv/{series_id}/season/{season_number}/images
  • GET /tv/{series_id}/season/{season_number}/videos
  • GET /tv/{series_id}/season/{season_number}/watch/providers
  • GET /tv/{series_id}/season/{season_number}/episode/{episode_number}
  • GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/credits
  • GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/images
  • GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/videos

People

  • GET /person/{person_id}
  • GET /person/{person_id}/movie_credits
  • GET /person/{person_id}/tv_credits
  • GET /person/{person_id}/images

Account features (watchlist, favorites, ratings, lists)

All of these are free for non‑commercial use if you integrate TMDB accounts. [web:2]

  • GET /account/{account_id}
  • POST /account/{account_id}/favorite
  • POST /account/{account_id}/watchlist
  • GET /account/{account_id}/favorite/movies
  • GET /account/{account_id}/favorite/tv
  • GET /account/{account_id}/watchlist/movies
  • GET /account/{account_id}/watchlist/tv
  • GET /account/{account_id}/rated/movies
  • GET /account/{account_id}/rated/tv
  • GET /account/{account_id}/rated/tv/episodes
  • GET /account/{account_id}/lists
  • POST /list
  • GET /list/{list_id}
  • POST /list/{list_id}/add_item
  • POST /list/{list_id}/remove_item

For Android, these can be wired through:

  • Repository pattern (Kotlin).
  • Coroutines + Retrofit for networking.
  • Room for local caching of IDs, titles, and watch status.

4. Android‑specific responsibilities vs. TMDB

What TMDB provides (free, non‑commercial)

  • Search, title metadata, images, videos, credits, external IDs, genres, discover/trending, and watch‑provider data. [web:49][web:50][web:2]
  • Account‑linked watchlist, favorites, and ratings if you use TMDB accounts. [web:2]

What your Android app and backend must own

  • User auth and profile (Google/Email + optional TMDB‑session bridge).
  • Episode‑level progress and custom progress UI (e.g., “Next episode to watch” chips, progress bars).
  • Custom collections, tags, private notes, and UI‑specific states (e.g., “On hold,” “Dropped”).
  • Notifications, reminders, release‑calendar logic, and AI‑based recommendations.
  • Analytics, feature flags, A/B tests, and moderation tools.

I’d summarize this for the team:

“For non‑commercial v1, TMDB’s free endpoints cover all content and discovery needs—search, titles, images, videos, credits, trending, watch‑provider data, and account‑linked watchlists/favorites/ratings.
Our Android app is responsible for smooth navigation, offline‑ready tracking, local caching, and a clean UI, while our backend owns progress, custom collections, notifications, and AI.” [web:2][web:50]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment