# Jellyfin for Android TV: the official 10-foot client, and when to build it yourself

> Jellyfin for Android TV is the first-party Kotlin client for Android TV, Nvidia Shield and Fire TV boxes. It is the reference way to put a Jellyfin library on a television, but its release cadence and GPL-2.0 licence shape who can ship it.

**jellyfin/jellyfin-androidtv** — Android TV Client for Jellyfin

- Repository: https://github.com/jellyfin/jellyfin-androidtv
- Website: https://jellyfin.org
- Stars: 4,583 · Forks: 960
- Language: Kotlin
- License: GPL-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/jellyfin-jellyfin-androidtv

## What the official Android TV client exists to solve

A television is not a phone with a bigger screen. It is driven by a remote, watched from across a room, and usually running hardware that is several years old. Jellyfin for Android TV is the Jellyfin Project's own answer to that environment: a client for Android TV, Nvidia Shield and Amazon Fire TV devices, written in Kotlin. The target user is someone who already runs a Jellyfin server and wants the library on the living-room screen without a browser or a desktop app.

The project is explicit that it is part of the wider Jellyfin Project, and the README frames contributions as welcome, with one caveat: larger features should start as an issue so the implementation can be discussed before code is written. That is a normal open source governance signal, and it tells you the maintainers would rather shape a feature early than reject a finished pull request.

## How the app is put together and what the repository layout tells you

The top level of the repository is a Gradle project. build.gradle.kts and settings.gradle.kts sit alongside a buildSrc/ directory, which in Gradle terms means build logic is shared as compiled code rather than copied between modules. The app/ directory holds the Android application, and two sibling directories, playback/ and preference/, are separated out as their own concerns. That split is the clearest architectural statement in the repository: playback and preference handling are treated as units distinct from the application module, which is what you would expect from a client whose main job is decoding video and remembering what a viewer chose.

Quality tooling is checked in rather than implied. There is a detekt.yaml for static analysis, an android-lint.xml for Android Lint, an .editorconfig for editor-level formatting, and a CODEOWNERS file. Renovate is configured through renovate.json, so dependency updates are automated. A design/ directory and a fastlane/ directory are present too, the latter being the standard Android path for store metadata and screenshots. For an engineer deciding whether to fork, this is a codebase with enforced conventions, not a loose collection of source files.

## Installing Jellyfin for Android TV and building a debug APK

For most people the install is an app store install, not a build. The README links three distribution channels: Google Play under the package id org.jellyfin.androidtv, the Amazon Appstore, and F-Droid. There is also a download archive at repo.jellyfin.org for the Android TV client, which is where you go when a store listing is not available on your device. If you only want to watch, stop here and pick the channel your device supports.

If you want to build, the README recommends Android Studio, which bundles the required dependencies. A manual build needs a compatible JDK and the Android SDK on your PATH, and then the Gradle wrapper does the work:

```bash
./gradlew assembleDebug
```

The README states that this task produces an APK in the /app/build/outputs/apk/debug directory. One detail matters for anyone installing it by hand: that APK uses a different app-id from the stable builds, so it installs alongside a store version rather than replacing it. That is convenient for testing and confusing if you forget which icon is which.

Before you write code, read the branching section. master is the primary development branch and the target for all pull requests, and the README describes it as unstable, warning that it may contain breaking changes or unresolved bugs and that production deployments and forks should use the latest release-x.y.z branch instead. Release branches are created at the start of a beta cycle and are kept current with each published release, with maintainers cherry-picking selected backports into them. If you are building something you intend to keep, clone a release branch.

## The beta channel and what the version numbers actually mean

The release list is the part of this project that will surprise people who assume a store install is always the newest code. The most recent entries are v0.20.0-beta.2 from 2026-09-14 and v0.20.0-beta.1 from 2026-09-08, with v0.19.10 from 2026-08-16 as the last non-beta release. The README ties this to branching: a release branch is created when a beta cycle starts, which means the beta line and the stable line diverge on purpose and then converge at each published release.

The practical consequence is that if you want stability, the version you want is the newest one without a beta suffix, and the repository's own release branches are the supported base for production work. If you want a feature that only exists in the beta, you are accepting the beta's risk, and the README's warning about master is the same warning in a different form. The repository has not been archived, and the last push was on 2026-09-22, so the codebase is being worked on; that says nothing about whether any given beta is ready for your household.

## Where this client is the wrong tool

The clearest limitation is platform. This is an Android TV, Nvidia Shield and Amazon Fire TV client. It is not a client for an Apple TV, a Roku, a Samsung or LG smart TV, or a desktop browser, and nothing in the README suggests otherwise. If your television runs one of those other platforms, this repository cannot help you no matter how well it is maintained.

The second limitation is licensing. The project is GPL-2.0. If you want to take this code, modify it and ship a closed-source product, the licence is the obstacle, and that is a legal question for your own counsel rather than something the README resolves. The third is the instability of master, already stated plainly by the maintainers. A team that builds a long-lived internal fork from master is doing the one thing the README tells them not to do.

There is also a documentation gap worth naming. The README covers building, branching and translating, and it does not document rollback, downgrade paths, or how a beta install returns to a stable release. Anyone planning to run the beta line should treat that as unverified ground and test it on a spare device first.

## Alternatives and the real difference in approach

The obvious alternative is the Jellyfin Android client rather than the Android TV client: same server, same project, different target hardware. The distinction is the input model and the screen. The Android TV client is built for a remote and a ten-foot viewing distance, and the repository's separate playback/ and preference/ modules reflect that focus. A phone or tablet client is built around touch. If your device is a television, the TV client is the one designed for it; if your device is a tablet propped on a stand, the phone client is the more natural fit.

The other alternative is a third-party Jellyfin client. The README does not name or compare any of them, so the honest statement is that the difference lies in who maintains the code and how closely it tracks the server. This repository is part of the Jellyfin Project, which means its release branches, translation workflow and feature requests all run through the project's own infrastructure. A third-party client may move faster on a specific feature, but you are relying on a different maintainer's schedule and a different bug tracker. Neither is automatically better; they are different dependencies.

## Maintenance cost, upgrades and the GPL-2.0 question

Running the official app costs you nothing operationally. You install it from a store or the download archive and it updates through that channel. Building it costs more: a JDK, the Android SDK, and Gradle, with Android Studio recommended because it carries the dependencies. The repository reduces some of the ongoing burden through renovate.json for dependency updates and checked-in detekt and lint configuration, which means a fork inherits a working quality gate instead of assembling one.

Upgrades are where the branching policy bites. If you build from a release-x.y.z branch, you track published releases and the maintainers' cherry-picked backports. If you build from master, you inherit breaking changes the README warns about. There is no documented downgrade procedure, so a beta that misbehaves on your hardware is a problem you solve by reinstalling a stable build, not by following a rollback guide, because the README does not provide one.

On licensing, GPL-2.0 is a copyleft licence, and the practical implication is that distributing a modified version carries source obligations. That is a statement about the licence text, not legal advice, and any commercial plan should go through a lawyer. Translation is a separate workflow: the README states that translations are handled on the project's Weblate instance and that changes to translation files via pull requests cannot be accepted.

## Conclusion

Adopt it if you run a Jellyfin server and want the client the project itself maintains for TV hardware, installed from Google Play, the Amazon Appstore or F-Droid, or built from a release-x.y.z branch. Do not adopt it if you need a signed, redistributable closed-source build, or if you want to ship from master, which the README calls unstable and warns against for production and long-lived forks. Before you commit, verify three things: that your device is one of the target platforms (Android TV, Nvidia Shield, Amazon Fire TV), that the release you install is the one you intend (the newest entries are v0.20.0-beta.2 and v0.20.0-beta.1, with v0.19.10 the last non-beta), and that your build environment has a compatible JDK and the Android SDK on PATH, because the README points Android Studio users at the bundled toolchain instead.

## FAQ

### Is there a Jellyfin app for Android TV?

Yes. Jellyfin for Android TV is the Jellyfin Project's client for Android TV, Nvidia Shield and Amazon Fire TV devices, and it is distributed through Google Play, the Amazon Appstore and F-Droid.

### How do I connect the Jellyfin Android TV app to my server?

The README does not document the connection flow or a server address field. It only states that the app is a Jellyfin client for Android TV, Shield and Fire TV, so the in-app steps are not something this article can confirm.

### How do I update Jellyfin for Android TV?

Updates arrive through whichever channel you installed from: Google Play, the Amazon Appstore, F-Droid, or the download archive at repo.jellyfin.org. The README does not describe a manual update procedure or a rollback path.

### What are the alternatives to Jellyfin for Android TV?

The README does not compare this client with any other. Within the same project, the closest alternative is the Jellyfin Android client for phones and tablets, which targets touch input rather than a remote and a television screen.

## Sources

- [jellyfin/jellyfin-androidtv on GitHub](https://github.com/jellyfin/jellyfin-androidtv)
- [License: GPL-2.0](https://github.com/jellyfin/jellyfin-androidtv/blob/master/LICENSE)
- [Project website](https://jellyfin.org)
- [README](https://github.com/jellyfin/jellyfin-androidtv/blob/master/README.md)
- [Releases](https://github.com/jellyfin/jellyfin-androidtv/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jellyfin-jellyfin-androidtv