Skip to content
BranchesTags

Repository files navigation

SeerrTV

AI developed with Cursor License GitHub release GitHub downloads Discord

SeerrTV is an Android TV application that provides a comprehensive media browsing and request management interface for Seerr, Jellyseerr and, Overseerr media request systems. It enables users to browse, search, request, and monitor the status of media requests directly from their Android TV device.

Screenshots

SeerrTV Main Screen

Main browsing interface

Media Details

Detailed media information

Search Interface

Search functionality

Filter Options

Advanced filtering options

Request Management

Request management interface

Features

Media Browsing & Discovery

  • Unified Browse Screens - Dedicated Movies and Series browse screens with grid-based layout optimized for Android TV
  • Advanced Filtering System - Comprehensive filtering with 13+ filter categories:
    • Release Date / First Air Date (date range)
    • Genres (multi-select with search)
    • Keywords (searchable multi-select)
    • Original Language (single selection)
    • Content Rating (multi-select with region support)
    • Runtime, User Score, Vote Count (range filters)
    • Studios (Movies only - searchable)
    • Networks (TV only - searchable multi-select)
    • Streaming Services (multi-select with region support)
  • Sort Menu - Sort by Popularity, Release Date, First Air Date, TMDB Rating, or Title (A→Z / Z→A) with bidirectional sorting
  • Enhanced Search - Real-time search with D-pad optimized navigation, inline results, and state preservation
  • Category Browsing - Browse by categories (Recently Added, Recent Requests, Trending, Popular Movies, Movie Genres, etc.)
  • Detailed Media Information - Cast, crew, ratings, and related content
  • Dynamic Backdrop System - Cycling backdrop images with gradient overlays
  • Person Information - Filmography browsing with biographical information
  • Category Exploration - Browse by genres, studios, and networks with dedicated discovery screens
  • Infinite Scroll Pagination - Automatic loading of additional results as you browse
  • State Preservation - Grid position, selection, filters, and sort preferences preserved during navigation

Request Management

  • Movie & TV Requests - Request movies and TV shows with configurable options
  • Tag Support - Organize requests with server-specific tags (multi-select)
  • Sonarr Lookup - Interactive series matching when TVDB ID is missing (with poster images and D-pad navigation)
  • HD/4K Support - Separate request options for HD and 4K quality tiers
  • Server Selection - Choose from multiple Radarr/Sonarr servers when configured
  • Quality Profile Selection - Select from configured quality profiles
  • Root Folder Selection - Choose root folder for TV show requests (when enabled)
  • Season Selection - Multi-select season picker for TV series
  • Real-time Status Monitoring - Monitor request status and download progress with automatic refresh
  • Permission-Based Actions - Support for different user permission levels (admin vs. regular user)
  • Request Approval Workflow - Administrators can approve/decline pending requests
  • Request Deletion - Delete requests and media files (based on permissions)
  • Media Status Indicators - Visual status icons including deleted and blacklisted states

Issue Reporting & Management

  • Permission-Based Access - Issue functionality controlled by VIEW_ISSUES and CREATE_ISSUES permissions
  • Issue Reporting - Report media quality and playback issues directly from the app
  • Categorized Issue Types - Video, Audio, Subtitle, and Other categories with precanned descriptions
  • Season/Episode Selection - Select specific seasons/episodes for TV series issues
  • Custom Descriptions - Add detailed problem descriptions beyond precanned options
  • Comment System - Discussion and updates on issues with threaded comments
  • Issue Status Tracking - Open and Resolved status with visual indicators
  • Issue Count Indicators - Display number of reported issues on media details screen
  • Issue Management - View and manage existing issues with detailed history and status updates

Authentication & Configuration

  • Multiple Authentication Methods:
    • API Key authentication
    • Local User authentication
    • Plex authentication with PIN code system
    • Jellyfin/Emby authentication (for Jellyseerr and Seerr)
  • Automatic Server Detection - Detects Seerr, Overseerr, or Jellyseerr server types automatically
  • Browser-Based Setup - QR code or URL-based configuration for easier setup
  • Manual Wizard - Step-by-step configuration wizard with guided setup
  • Cloudflare Protection - Bypass Cloudflare Access protection with service token authentication
  • Flexible Configuration - Supports HTTP/HTTPS with SSL certificate validation
  • Connection Testing - Real-time connection validation before proceeding
  • Multi-user Profiles - Create multiple local user profiles, each bound to its own API configuration (1:M).
  • Profile Selector & PIN (optional) - If multiple profiles exist (or a single profile is PIN protected), choose a profile at startup and enter an optional numeric PIN before activation.

TV-Optimized Interface

  • Material Design 3 - Theming optimized for TV screens with consistent styling
  • D-pad Navigation - Comprehensive D-pad navigation with focus management throughout the app
  • Visual Feedback - Clear focus indicators and selection state feedback
  • Slide Animations - Smooth slide-in/out animations for modals, drawers, and menus
  • Auto-Scrolling - Content automatically scrolls to keep focused items visible
  • Expandable Content - Expandable text areas for long descriptions with "Read More/Less"
  • Smart Layout - Dynamic layout adjustment based on content availability
  • Persistent Top Bar - Always-visible top bar with search, settings, clock, and active profile avatar
  • Settings - TV-friendly full-screen settings screen (includes User profiles management)

Localization & Internationalization

  • Independent App Language - User interface language is independent of Discovery Language
  • Language Selection - Choose from supported languages (English, German, Spanish, French, Japanese, Dutch, Portuguese, Chinese)
  • On-the-Fly Language Change - Switch UI language from the Settings screen without restarting
  • Automatic Migration - Existing users automatically use system default language (if supported) or English
  • Regional Settings - Default streaming region setting for watch providers and content ratings

External Integration

  • Media Server Playback:
    • Direct integration with Plex for media playback
    • Jellyfin media server support
    • Emby media server support with dual-app compatibility (Android TV and regular Android apps)
  • Trailer Viewing - YouTube integration for trailer playback
  • Metadata Integration - TMDb (The Movie Database) integration for ratings, cast, crew, and metadata
  • Downstream Services:
    • Sonarr server integration for TV series management
    • Radarr server integration for movie management
    • Multi-server support for both HD and 4K quality tiers
    • Server-specific quality profiles and root folder selection

Quick Start

For End Users

Installation Options

Option 1: Google Play Store (Recommended)

  • SeerrTV is available on Google Play Store for official releases
  • Automatic updates via Play Store
  • Easiest installation method

Option 2: GitHub Releases (Sideload)

  • Download the latest APK from GitHub Releases
  • Enable "Install from Unknown Sources" on your Android TV device
  • Transfer the APK to your device and install
  • The app automatically checks for updates from GitHub Releases when opened
  • See FAQ for detailed sideloading instructions

Basic Configuration

  1. Launch SeerrTV on your Android TV device
  2. Choose configuration method:
    • Browser-based setup (QR code or URL) - Recommended for easier setup
    • Manual step-by-step wizard
  3. Configure server connection:
    • Enter protocol (HTTP/HTTPS)
    • Set hostname or IP address
    • Select authentication method (API Key, Plex, Local User, or Jellyfin/Emby)
  4. Complete authentication:
    • Follow on-screen instructions for your chosen auth method
    • For Plex auth: Visit plex.tv/link and enter the provided PIN
    • For API key: Enter your server's API key
    • For local user: Enter username and password
  5. Start browsing! The app will automatically detect your server type (Seerr, Overseerr, or Jellyseerr). If multiple user profiles exist, select one first (and enter an optional PIN).

For detailed configuration guides, see:

For Developers

  1. Clone the repository:

    git clone https://github.com/devmesh-git/seerrtv.git
cd seerrtv

  2. Open in Android Studio:

    • Open Android Studio
    • Select "Open an Existing Project"
    • Navigate to the cloned seerrtv directory
    • Android Studio will sync Gradle dependencies

  3. Build and run:

    # Debug build (standard app)
./gradlew assembleDirectDebug

# Or build and install directly on connected device/emulator
./gradlew installDirectDebug

# Launcher flavor (Apps row, reorder, home screen) — use this to test launcher features
./gradlew :tv:installPlayLauncherDebug
adb shell am start -n ca.devmesh.seerrtv.launcher/ca.devmesh.seerrtv.MainActivity

  4. See Development Setup below for detailed build instructions, including the Launcher build for the TV home-screen variant.

Requirements

For Users

  • Android TV device (Android 6.0 / API 23 or higher)
  • Seerr, Overseerr, or Jellyseerr server instance
  • Network access to your media server

For Developers

  • Java Development Kit (JDK): Java 21 (required)
    • macOS (recommended): Android Studio includes Java 21 (JBR) which is automatically used via gradle.properties
      • Alternative: Using Homebrew: brew install openjdk@21
      • Or download from Adoptium
    • Linux:
      • Ubuntu/Debian: sudo apt install openjdk-21-jdk
      • Fedora/RHEL: sudo dnf install java-21-openjdk-devel
      • Arch Linux: sudo pacman -S jdk21-openjdk
      • Or download from Adoptium
    • Windows:
    • Verify installation: java -version (should show version 21)
  • Android Studio Hedgehog or later
  • Android SDK with API level 25-36
  • Android TV emulator or physical device for testing

Technologies Used

  • UI Framework: Jetpack Compose for modern, declarative UI
  • Dependency Injection: Hilt for clean architecture
  • Image Loading: Coil for efficient image caching and loading
  • Asynchronous Operations: Coroutines and Flow for reactive programming
  • Navigation: Jetpack Navigation with custom transitions
  • Data Storage: SharedPreferences for configuration
  • HTTP Client: Ktor for API communication
  • Platform: Android TV SDK for TV-specific features

Development Setup

Building for Distribution

SeerrTV supports two distribution methods. Use these main build tasks (run from project root with ./gradlew or gradlew.bat on Windows):

Goal Task Output
Play Store (debug) bundlePlayDebug .aab for testing
Play Store (release) bundlePlayRelease .aab for Play Console
Direct / sideload (debug) assembleDirectDebug Both app + launcher .apk files
Direct / sideload (release) assembleDirectRelease Both app + launcher .apk files

After a build, Gradle prints the paths to the generated APK/AAB files. Use these four tasks; the generic assembleDebug (all debug variants at once) is not needed for normal development.

Play Store (.aab)

Build the play flavor for Google Play (no in-app update, minimal permissions):

./gradlew bundlePlayDebug    # Debug
./gradlew bundlePlayRelease  # Release for Play Console
  • Generates .aab in tv/build/outputs/bundle/playAppRelease/
  • Compliant with Play Store policies

Direct / Sideload (.apk)

Build the direct flavor for sideloading (includes auto-update from GitHub Releases):

./gradlew assembleDirectDebug    # Debug
./gradlew assembleDirectRelease  # Release: builds app + launcher APKs
  • Release outputs: SeerrTV-vX.Y.Z.apk and SeerrTV-vX.Y.Z.launcher.apk under tv/build/outputs/apk/
  • Upload both to a GitHub Release for the in-app updater to work

Platform notes: macOS uses Android Studio’s JBR via gradle.properties; set JAVA_HOME or org.gradle.java.home on Linux/Windows if needed.

Launcher build (optional)

SeerrTV can be built as an Android TV launcher (replaces the device home screen; app ID ca.devmesh.seerrtv.launcher).

  • Direct release (both APKs): ./gradlew assembleDirectRelease — produces the main app and launcher APKs.
  • Launcher-only (debug or single variant):
    • Play: assemblePlayLauncherDebug, bundlePlayLauncherRelease
    • Direct: assembleDirectLauncherDebug, assembleDirectLauncherRelease

Install and test:

  1. Build one of the launcher variants above.
  2. Install on a device or emulator:
    • One-liner (build and install on connected device/emulator): 
      ./gradlew :tv:installPlayLauncherDebug
    • Manual install (after building): 
      adb install -r tv/build/outputs/apk/playLauncher/debug/tv-playLauncher-debug.apk
      Use the same path for directLauncher if you built that variant (tv/build/outputs/apk/directLauncher/debug/...).
  3. Emulator: Start your Android TV emulator (Device Manager in Android Studio, or emulator -avd <your_tv_avd_name>), then run the install command above.
  4. Set SeerrTV Launcher as the default home screen (required for Home to open SeerrTV):
    • Via ADB (most reliable): disable the current default launcher, then press Home; the system will offer SeerrTV Launcher. Google TV (Chromecast with Google TV, many recent devices): 
      adb shell pm disable-user --user 0 com.google.android.apps.tv.launcherx
      Android TV (older devices, some set-top boxes): 
      adb shell pm disable-user --user 0 com.google.android.tvlauncher
      To find your device's launcher package name: adb shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME.
    • Via device: Some devices have Settings → Apps → Default apps → Home app (or similar) where you can pick the launcher.
  5. Press Home on the remote; SeerrTV Launcher should open. Use the Apps row at the top to open other installed TV apps.

Restoring the default launcher

To switch back to the stock Android TV / Google TV home screen:

  1. Re-enable the stock launcher via ADB (use the same package name you disabled earlier):
    • Google TV (Chromecast with Google TV, many recent devices): 
      adb shell pm enable --user 0 com.google.android.apps.tv.launcherx
    • Android TV (older devices, some set-top boxes): 
      adb shell pm enable --user 0 com.google.android.tvlauncher
  2. If you don't remember the package name, list home-capable apps:
    adb shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME
    Then run: adb shell pm enable --user 0 <package_name>.
  3. Press Home on the remote; the system may show a launcher picker—choose the stock launcher. On some devices the stock launcher becomes active again automatically once re-enabled.

Launcher-specific behavior:

  • The main screen shows an Apps row listing other installed Android TV apps; D-pad Left/Right to move, Enter to launch.
  • From the top bar, Down goes to the Apps row first, then to content categories.
  • For more detail (intent filters, features, phases), see docs/LAUNCHER_ANALYSIS.md.

Build variants

Task / variant Output Use case
bundlePlayRelease .aab Play Store (main app)
assembleDirectRelease app + launcher .apk Direct/sideload (GitHub Releases)
playLauncher .aab/.apk TV launcher from Play
directLauncher .apk TV launcher, sideload (auto-update)

Signing Configuration

For release builds, you need to configure APK signing:

  1. Create signing properties file:

    # macOS/Linux:
cp tv/signing.properties.template tv/signing.properties

# Windows (Command Prompt):
copy tv\signing.properties.template tv\signing.properties

# Windows (PowerShell):
Copy-Item tv\signing.properties.template tv\signing.properties

  2. Edit tv/signing.properties with your keystore information:

    storeFile=../localSigningKey.jks
storePassword=your_keystore_password
keyAlias=your_key_alias
keyPassword=your_key_password

  3. Security Notes:

    • signing.properties is automatically gitignored
    • Debug builds use the default debug keystore automatically
    • For CI/CD, you can use environment variables: KEYSTORE_PASSWORD, KEY_ALIAS, KEY_PASSWORD

For detailed signing setup instructions, see Signing Setup Guide.

Configuration Files

Browser Configuration: The browser-based configuration endpoint can be customized by creating a browser-config.properties file:

  • Copy tv/browser-config.properties.template to tv/browser-config.properties
  • Update the browser.config.base.url property if needed
  • Default value points to https://seerrtv.devmesh.ca
  • This file is gitignored for security

Release: Play Store → ./gradlew bundlePlayRelease, upload the .aab to Play Console. Direct → ./gradlew assembleDirectRelease, upload SeerrTV-vX.Y.Z.apk and SeerrTV-vX.Y.Z.launcher.apk to a GitHub Release (tag e.g. v0.26.4). The app checks GitHub Releases for updates.

App Configuration

On first run, the app will guide you through the configuration process:

  1. Choose configuration method:

    • Browser-based setup (QR code or URL)
    • Manual step-by-step wizard

  2. Configure server connection:

  3. Complete authentication:

    • Follow on-screen instructions for your chosen auth method
    • For Plex auth: Visit plex.tv/link and enter the provided PIN
    • For API key: Enter your server's API key
    • For local user: Enter username and password

For detailed configuration guides, see:

User Guides

Navigation Guide

The app is optimized for TV remote control navigation:

  • D-pad Navigation:

    • UP/DOWN: Move between categories
    • LEFT/RIGHT: Navigate within categories
    • ENTER: Select focused item
    • BACK: Return to previous screen

  • Special Actions:

    • Press UP at top of screen to refresh content
    • Use BACK button to close modals
    • D-pad navigation preserves selection state

Performance Features

  • Lazy loading of media content
  • Efficient image caching
  • Optimized focus management
  • State preservation during navigation
  • Debounced search to prevent excessive API calls
  • Smart refresh mechanisms
  • Memory-efficient data structures

Community & Support

Get Help:

Contribute:

SeerrTV is part of the Seerr community. This project was originally created by DevMesh and is now community-driven.

Contributing

We welcome contributions! SeerrTV is an open-source project and contributions from the community are essential for its growth.

Quick Start for Contributors

  1. Fork the repository and create a feature branch
  2. Make your changes following our code style guidelines
  3. Test thoroughly on an Android TV device or emulator
  4. Submit a pull request with a clear description

Important Notes

Android TV Requirements: SeerrTV is an Android TV application. All contributions must follow Android TV navigation patterns:

  • ✅ Use D-pad navigation, not touch/click
  • ✅ Test with TV remote controls
  • ✅ Follow the custom navigation component patterns
  • ❌ Do NOT use onClick modifiers
  • ❌ Do NOT use focusable() or clickable() modifiers for navigation

Getting Help

  • 📖 Full Contributing Guide: See CONTRIBUTING.md for detailed guidelines on:
    • How to report bugs
    • How to suggest features
    • Pull request process
    • Code style guidelines
    • Android TV-specific requirements
  • 💬 Discord: Join the Seerr Community Discord for contributor discussions
  • 🏷️ Good First Issues: Look for issues labeled good first issue - perfect for new contributors!

Downloads

Google Play Store

SeerrTV is available on Google Play Store for official releases. This is the recommended installation method as it provides:

  • Automatic updates via Play Store
  • Verified security and compatibility
  • Easiest installation process

Direct Distribution (Sideload)

For users who prefer to sideload builds, direct APK releases are available on GitHub:

  • Latest Release: GitHub Releases
  • The app automatically checks for updates from GitHub Releases when opened
  • Download the .apk file and install on your Android TV device

Sideload Installation Steps

  1. Enable Unknown Sources:

    • Go to Settings → Security & restrictions → Unknown sources
    • Enable installation from unknown sources (varies by device)

  2. Download the APK:

  3. Transfer to Your Device:

    • Use ADB: adb install seerrtv-release.apk
    • Use a USB drive or network file transfer
    • Use a file manager app on your TV

  4. Install:

    • Open the APK file using a file manager
    • Follow the installation prompts
    • Launch SeerrTV from your app drawer

Note: The direct distribution build includes auto-update functionality that checks GitHub Releases for new versions. Release notes and changelogs are also announced in the official Discord community.

Build Variants

Distribution Build task File type Updates
Play Store bundlePlayRelease .aab Play Store
Direct/sideload assembleDirectRelease .apk GitHub Releases

FAQ & Troubleshooting

Installation

Q: How do I sideload the APK on my Android TV?

A: Follow these steps:

  1. Enable "Install from Unknown Sources" in your TV's settings (Settings → Security & restrictions → Unknown sources)
  2. Download the APK from GitHub Releases
  3. Transfer the APK to your TV via USB, network share, or ADB
  4. Open the APK using a file manager app on your TV
  5. Follow the installation prompts

For detailed instructions, see the Downloads section above.

Q: The app won't install. What should I do?

A: Make sure:

  • "Unknown Sources" is enabled in your TV settings
  • You downloaded the correct APK for your device architecture
  • Your TV has enough storage space
  • The APK file wasn't corrupted during download (try re-downloading)

Configuration

Q: How do I configure Cloudflare Access protection?

A: See the Cloudflare Access Configuration Guide for detailed instructions on setting up Cloudflare Zero Trust protection with SeerrTV.

Q: I can't connect to my server. What's wrong?

A: Check the following:

  • Verify your server URL is correct (include http:// or https:// and port if needed)
  • Ensure your Android TV device can reach your server over the network
  • Check if your server has firewall rules blocking connections
  • Verify SSL certificate settings if using HTTPS
  • For Cloudflare-protected servers, ensure service token authentication is configured correctly

Q: How do I change the authentication method?

A: Go to Settings → Server Configuration → Authentication Method and select your preferred method. You'll need to re-authenticate with the new method.

Updates

Q: The app says an update is available, but I can't update. Why?

A: If you installed from Play Store, updates come through Play Store automatically. If you sideloaded:

  • Make sure "Unknown Sources" is still enabled
  • The app needs REQUEST_INSTALL_PACKAGES permission (only in direct builds)
  • Check your network connection
  • Try manually downloading from GitHub Releases

Q: How do I check for updates manually?

A: Go to Settings → About → Check for Updates. The app will automatically check GitHub Releases for the latest version.

Navigation

Q: D-pad navigation isn't working properly. What should I do?

A: This is an Android TV app designed for D-pad navigation. Make sure:

  • You're using a TV remote with D-pad, not a mouse or touch screen
  • The focused element is visible (try pressing UP at the top of screens to refresh)
  • You're not trying to use touch/click interactions (this app doesn't support them)
  • If issues persist, report a bug with specific navigation steps

Q: How do I navigate the app?

A: Use your TV remote D-pad:

  • UP/DOWN: Move between rows/categories
  • LEFT/RIGHT: Navigate within a row
  • ENTER/SELECT: Open/select the focused item
  • BACK: Return to previous screen or close dialogs

Features

Q: Can I use this with Overseerr/Jellyseerr/Seerr?

A: Yes! SeerrTV automatically detects and works with all three server types: Overseerr, Jellyseerr, and Seerr. The app will detect your server type during initial configuration.

Q: Does SeerrTV support 4K requests?

A: Yes, SeerrTV supports separate HD and 4K request configurations. You can configure multiple Radarr/Sonarr servers for both HD and 4K quality tiers.

Reporting Issues

Q: How do I report a bug?

A:

  1. Check if the bug has already been reported in GitHub Issues
  2. If not, create a new issue using our bug report template
  3. Include as much information as possible: app version, device model, Android version, steps to reproduce
  4. For D-pad navigation issues, include the exact navigation path
  5. If possible, attach logs captured using the Support Logs Guide

Q: How do I request a new feature?

A:

  1. Check existing feature requests first
  2. Create a new issue using our feature request template
  3. Describe the use case, who would benefit, and how it would improve the experience
  4. Consider Android TV constraints (D-pad navigation, screen size, etc.)

Q: Where can I get help with issues not covered here?

A: Join the Seerr Community Discord - the official community for support and discussions. You can also create a GitHub issue with the question label.

Launcher

Q: How do I restore the default (stock) launcher?

A: If you set SeerrTV Launcher as your home screen and want to go back to the stock Android TV / Google TV launcher, re-enable it via ADB (see Restoring the default launcher in the Launcher build section):

  • Google TV: adb shell pm enable --user 0 com.google.android.apps.tv.launcherx
  • Android TV: adb shell pm enable --user 0 com.google.android.tvlauncher

Then press Home; choose the stock launcher if a picker appears. If you don't know your device's launcher package, use:
adb shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME
then adb shell pm enable --user 0 <package_name>.

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

SeerrTV leverages Seerr (Overseerr/Jellyseerr) from the comfort of your living room. Seerr is a request management and media discovery tool built to work with your existing Plex/Jellyfin/Emby ecosystem.

devmesh.ca/seerrtv

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

22 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

Sponsor this project

Packages

Contributors

Languages