Reiverr: A TV-first UI for TMDB Discovery and Plugin-based Playback

Stargazers GitHub issues Discord

Reiverr is an ambitious project designed to provide a single, cohesive user interface (UI) for discovering content through TMDB, streaming media from a range of sources, and acting as a practical alternative to Overseerr. The project is in an early stage of development, with many features still under testing, refinement, or planning. The author invites community involvement to help shape the roadmap and resolve bugs. The documentation you’ll read here captures the current state of Reiverr, including how to install, configure, and contribute to the project.

If you’re curious to see Reiverr in action, a demo video is available in the project assets. The video gives a sense of the layout, navigation, and the core flow from discovery through playback.

Demo Video embedded here

Reiverr 2.0: A Rewrite with TVs in Mind

Reiverr 2.0 represents a significant rewrite of the project, with a primary focus on televisions and large-screen experiences. While it retains the core goals of TMDB discovery, content playback, and a rich plugin ecosystem, the UI and interactions have been redesigned to prioritize readability, navigability, and ease of use on TV screens. As a result, some features from the previous version may be temporarily missing or in flux as the UI and underlying architecture stabilize for TV usage. If you’re seeking a more stable experience or primarily care about the web app, you might want to check out the 1.0 branch for now.

For those who want to watch the project evolve on a broader device footprint, the roadmap and discussion pages offer transparency into planned improvements, bug fixes, and feature ideas. The project’s taskboard tracks the major items and invites contributors to join the effort.

Major Features

Reiverr aims to bring together discovery, details, and playback into a single interface. The major features can be grouped into discovery, playback, and extensibility.

TMDB Discovery
Discover trending movies and TV shows, so you’re always up-to-date with what’s hot.
Get personalized recommendations based on your TMDB ratings, helping you discover content that aligns with your tastes.
View rich details about movies and TV shows, including cast, crew, ratings, and trailer information, enabling informed viewing decisions.
Search content by title, actor, or other metadata to quickly locate items of interest.
Content Playback Plugins
A plugin API enables access to media from various external sources, extending the app beyond a single library.
Built-in plugins currently include:
- Jellyfin plugin
- Torrent-Stream plugin (requires Jackett)
The plugin system is designed to be extensible, enabling new sources to be added as needed.
Administration and Security
Optional, persistent sessions via a JWT-based authentication flow, controlled by a SECRET environment variable.
Admin credentials can be defined in the Docker Compose setup, or you can create a user manually after installation.
Cross-Platform Access
While the 2.0 version emphasizes TV usability, the underlying architecture is designed to support a broad range of platforms and future targets.

If you want a broad view of planned work and known issues, the Reiverr Taskboard provides a snapshot of what’s in flight and what the community can tackle. You’ll find tickets organized by feature area, with labels to help prioritize and categorize work.

How Reiverr Works: A Look Under the Hood

Understanding the architecture helps in planning deployments, contributions, and plugin development. Reiverr blends a modern front-end framework with a robust back-end and a plugin ecosystem that makes it possible to pull media from multiple sources.

Frontend
Built with Svelte, delivering a responsive and accessible UI designed for larger screens and TVs.
The Svelte-based front end communicates with a NestJS back-end, forming a clean separation between UI and business logic.
Backend
NestJS provides a scalable, modular server-side environment that supports authentication, plugin orchestration, and API endpoints for the frontend.
A plugin system powers media source integration, enabling users to connect to Jellyfin, Torrent-Stream, and future plugins seamlessly.
Plugins
Plugins are distributed as npm packages containing a package.json and a .plugin folder extension.
Each plugin must export a PluginProvider class to integrate with the Reiverr ecosystem.
The built-in plugin package uses npm workspaces; developing outside the repository requires careful handling to maintain compatibility.
Documentation and source code for the plugin interface can be found in the reiverr-plugin package, helping developers understand how to implement their own plugins.
Data and Identity
Authentication relies on JWTs for session management; if the SECRET is not configured, sessions will not persist across server restarts.
The Jellyfin API key location is accessible through the Jellyfin Web UI (Administration > Dashboard > Advanced > API Keys), enabling secure integration.

The project’s documentation emphasizes a practical approach to plugin development, showing how to explore the structure of existing plugins and how to add new ones. This extensibility is central to Reiverr’s aim: to be a hub for streaming content from multiple sources while maintaining a simple, consistent user experience.

Installation and Getting Started

The recommended installation path for Reiverr is via Docker. Docker containers offer a straightforward way to deploy, manage dependencies, and isolate the application from the host system. Here are the primary routes to install and run Reiverr.

Docker CLI

To launch Reiverr with a quick start, you can use the following command. This example maps the host port to the container port, mounts configuration and plugin directories, and ensures the container restarts automatically unless stopped.

docker run -it --init \
  --name reiverr \
  --restart unless-stopped \
  -p 9494:9494 \
  -v /path/to/appdata/config:/config \
  -v /path/to/appdata/plugins:/plugins \
  ghcr.io/aleksilassila/reiverr:latest

Docker Compose

For a more reproducible setup, a Docker Compose file is provided. It allows you to declare environment variables, volume mappings, and restart policies in a single YAML file. This is particularly helpful in multi-service environments or when managing multiple containers.

version: '3.8'
name: reiverr
services:
  reiverr:
    image: ghcr.io/aleksilassila/reiverr:latest
    container_name: reiverr
    ports:
      - 9494:9494
    environment:
      - SECRET=your_secret_here # optional, used to sign JWT tokens for authentication. If not set, sessions will not persist between server restarts. Use a random string.
      - ADMIN_USERNAME=admin # optional
      - ADMIN_PASSWORD=admin # optional
    volumes:
      - /path/to/appdata/config:/config
      - /path/to/appdata/plugins:/plugins
    restart: unless-stopped

Building from Source

If you prefer to develop locally or contribute directly to the codebase, you can build from source. The current guidance includes the following steps.

Prerequisites
Node v18.14.0 or higher
npm v9.3.1 or higher
Get the source
Clone from the master branch or download the latest source release from GitHub
Build and run
Install dependencies: npm install
Install backend dependencies: npm install --prefix backend
Start the preview: npm run preview

Note: Reiverr will be accessible via port 9494 by default when running the development server.

Tizen / Samsung Smart TVs

To run Reiverr on TVs, you’ll still need to host the backend backend on a separate device. The steps share the same setup for the backend and frontend, but there are additional platform-specific considerations.

Build steps remain the same for dependencies
Install on a TV via Tizen Studio or the CLI:
You’ll need to download Tizen Studio or the Tizen CLI tools
Connect Tizen Studio to your TV
Build and package the app for web runtime (WGT)
Install on the TV using the TV’s device identifier
If you’d rather avoid manual steps, you can wait for future official store distribution plans, but in the meantime, the manual installation path remains viable.

If you encounter issues or want to discuss features, you can start a discussion, open an issue, or check the Discord channel. Feature requests can be discussed and upvoted with a thumbs-up.

Post-Installation: First Run, Admin, and Plugins

After installation, there are a few best practices to get your initial setup in order and to start consuming media via plugins.

Admin account creation
The first login can be with any credentials; an admin user will be created automatically.
Alternatively, you can predefine admin credentials via environment variables in Docker Compose. If there are no existing accounts with the same name, a new admin account will be created.
Access to media playback
To enable media playback, connect to plugins by adding media sources in the settings.
Plugins can be installed by placing new plugin packages into the /plugins directory that you mounted during setup.
TMDB connection
For enhanced recommendations and metadata, connecting to TMDB is recommended.
Jellyfin keys
The Jellyfin API key is accessible under Jellyfin Administration > Dashboard > Advanced > API Keys. This helps you securely connect Jellyfin as a content source.
Community and support
If you have questions, you can start a discussion, open an issue, or join the Discord channel. Community discussions often help accelerate improvements and share best practices.

Contributing: How You Can Help

Reiverr distinguishes itself through a combination of Svelte-based UI work and NestJS-based server logic. If you’re new to Svelte, you’ll find the project approachable, and the official Svelte tutorial can be a great starting point.

Key guidelines for contributors:

Familiarize yourself with the feature set and known bugs by reviewing the Reiverr Taskboard.
When reporting bugs or proposing features, consider creating issues with clear context and steps to reproduce.
UI consistency matters. If you’re contributing UI changes, aim to align with the project’s visual language and discuss design decisions in advance for larger changes.
Conventional commits are encouraged, enabling you to maintain a clean history.
When creating pull requests, target the dev branch and mark drafts if a feature is a work in progress.
Designers are welcome to contribute; the project is still missing a logo, and design ideas are highly appreciated.
Plugins are a major part of the project’s philosophy. If you build a new plugin, you’ll contribute to the ecosystem and broaden Reiverr’s usefulness.

The plugin architecture invites experimentation. If you’re curious about how plugins are structured, the reiverr-plugin package documentation can be a helpful starting point. The example file reiverr-plugin/src/plugin.ts contains guidance on the plugin interface, and the docs provide additional context about how to integrate with the PluginProvider.

Development: Getting Started Locally

Developing Reiverr locally involves a few straightforward steps. The project is set up to be approachable for developers who want to explore frontend, backend, and plugin integration.

Clone the repository
Check out the dev branch
Install dependencies
npm install
npm install --prefix backend
Run the frontend
npm run dev
Or npx vite --host to expose the server
Run the backend
npm run --prefix backend start:dev

This setup enables you to see changes in real time as you adjust the UI components or the server logic. Given that the 2.0 release prioritizes TVs, development work tends to emphasize larger typography, touch-friendly navigation, and button sizing appropriate for remote control interactions.

Design considerations to keep in mind during development:

TV-first UI: Larger text, bigger interactive targets, and simplified navigation patterns improve usability on televisions.
Compatibility: The app should work with older browsers up to Chromium 69, as used in Tizen 5.5. When necessary, polyfills should be employed to bridge gaps in modern features.
CSS gaps: Some older browsers do not support the CSS gap property. To achieve similar spacing, you can rely on Tailwind’s space-x and space-y utilities to emulate gaps without relying on the CSS gap property.

If you’re exploring plugins and want to see how built-in plugins work, review the built-in package sources and the plugin.ts file in the reiverr-plugin package to understand the expected structure and provider export pattern.

Plugins: Building and Integrating Your Own Source

Plugins are an essential part of Reiverr’s extensibility. They let you pull media from various external sources, expanding the breadth of available content beyond a single library.

Plugins are npm packages with a .plugin extension and include a package.json manifest.
Each plugin must implement and export a PluginProvider class, which serves as the contract for how the plugin integrates with the Reiverr ecosystem.
To install and publish plugins to the Github npm registry, you’ll need an .npmrc configuration and an access token associated with a GitHub account.
The Reiverr plugin architecture uses npm workspaces. While this is convenient for development within the repository, publishing or developing outside of the workspace requires additional considerations.
For a deeper understanding of how plugins are structured, consult:
reiverr-plugin/src/plugin.ts
The official plugin documentation and examples provided in the repository.

This plugin model encourages experimentation and modular growth. If you’re designing a new plugin, consider how the source integrates with TMDB metadata, how to fetch and cache data, and how playback from your source will be initiated within the Reiverr front end.

Useful resources for plugin development and related integration points include:

TMDB Reference API
Jellyfin API
Jellyfin Web UI: a familiar model for managing media servers and metadata
General network debugging practices (Network tab in browser consoles) as used in Jellyfin, Radarr, and Sonarr UIs

Useful Resources

TMDB API reference: https://developer.themoviedb.org/reference
Jellyfin API: https://api.jellyfin.org/
Jellyfin Web: https://github.com/jellyfin/jellyfin-web
Design and compatibility references:
Android TV design guidance: https://developer.android.com/design/ui/tv/guides/styles/layouts
caniuse compatibility checks: https://caniuse.com/

These resources can help you understand data structures, metadata, streaming handoffs, and cross-platform compatibility as you develop plugins or integrate new sources into Reiverr.

Additional Screenshots

To give you a sense of the user interface and built-in screens, the project includes several sample pages:

Landing Page
Series Page
Library Page

These screenshots illustrate how the interface organizes content, displays details, and presents media libraries. They also provide a visual baseline for contributors who want to tweak the UI to improve clarity, navigation, or visual rhythm, especially on larger screens or TVs.

Roadmap and Platform Vision

The project has an eye toward broader platform support in future iterations. In addition to the current focus on the web app and TV interfaces, there is explicit planning for:

Android TV
WebOS
Windows Desktop App
MacOS Desktop App

This roadmap reinforces the goal of making Reiverr a flexible, cross-platform hub for discovery, metadata, and playback. While not all of these targets are available today, the vision emphasizes a unified experience across devices.

Final Thoughts: Why Reiverr?

Reiverr is more than a media player; it’s an ambitious attempt to unify discovery, metadata, and playback across multiple sources in a single, cohesive experience. Its core strengths lie in:

A clear, TV-friendly design ethos that prioritizes usability on larger displays and remote control navigation.
A robust plugin ecosystem that enables content from Jellyfin, Torrent-Stream, and future sources, creating a flexible streaming environment.
An architecture that separates UI from business logic, enabling more straightforward maintenance, testing, and contribution.
An emphasis on community involvement, with clear pathways to contribute through issues, discussions, and PRs.

If you’re drawn to building a customizable, multi-source streaming frontend with a strong plugin API, Reiverr offers a compelling foundation. It invites developers and enthusiasts to contribute—whether by refining the UI for TV devices, expanding the set of plugins, or improving the documentation and onboarding flow.

Installation, Usage, and Community

Start with Docker for a quick setup and straightforward maintenance.
Use Docker Compose for reproducible deployments with clear environment variables for authentication and admin credentials.
Build from source if you want to experiment with the front end or contribute directly to the core code.
Explore Tizen/TV workflows to bring Reiverr to Samsung TVs and other smart TVs in the ecosystem.
Engage with the community through discussions, issues, and the Discord channel to share ideas and resolve problems.

If you’d like to see more, the project’s taskboard and documentation pages provide additional context about ongoing work, feature requests, and known bugs. And if you’re a designer, your input—especially on branding and UI polish—would be especially valuable as the project continues to mature.

Images referenced in the post

Demo Video: images/reiverr-demo.gif
Landing Page: images/screenshot-1.png
Series Page: images/screenshot-2.png
Library Page: images/screenshot-3.png

By engaging with Reiverr, you’re joining a growing effort to make media discovery and playback more unified, extensible, and accessible on a range of devices. Whether you’re a user seeking a more consolidated streaming experience, a developer eager to contribute plugins, or a designer with ideas for a polished look, Reiverr offers a welcoming gateway to participate in shaping the future of personal media ecosystems.

Reiverr 2.0: A TV-First UI for TMDB and Plugins