# Immich Android TV: a photo and video viewer for a self-hosted library > The Immich Android TV app is a Kotlin television client for a self-hosted Immich server, with a screensaver mode, slideshows and album sorting. It requires an Immich server on version 3.0.0 or newer, an API key with seventeen specific permissions, and a debug build session to make the screensaver work on most devices. **giejay/Immich-Android-TV** — An Android TV app for the self hosted photos and videos backup solution. - Repository: https://github.com/giejay/Immich-Android-TV - Stars: 915 · Forks: 89 - Language: Kotlin - License: GPL-3.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/giejay-immich-android-tv ## A television client, not a backup app The distinction matters, because the name suggests otherwise. Immich itself is described as a self hosted backup solution for photos and videos, and the features listed for it include uploading and viewing videos and photos, automatic backup when the app is opened, selective album backup, multi-user support, and both ordinary and shared albums. Those are the server's features, and the television app is a viewer for the photos and videos that are already there. The project says exactly that: the Android TV app lets you view those uploaded photos and videos. The client is written in Kotlin, and it talks to a server over its API rather than to a local library, which is why everything in this project is framed around the API key, the server version and the permission list. If you are looking for a way to get photos off your phone and onto a server, this is the wrong project, and the main Immich repository is the one to look at. ## Version 3.0.0 of the server is the hard floor Compatibility with the server is stated precisely, and it is a floor rather than a range. The app is compatible with Immich server v3.0.0 and newer. The reason given is that 3.0.0 introduced several breaking API changes, and they are named: album asset loading via the search/metadata endpoint, search visibility defaults, and the error response format. The app has been adapted to those changes. One point reassures users about permissions: no additional API key permissions are required for v3 compared to earlier versions, because the existing asset.read and album.read permissions already cover the endpoints this app uses. In practice, an older server will not work with this build, and a newer server may change things again, so the version number is the first thing to check when the app misbehaves. The release history shows steady work: Immich TV 6.2.0 on 2026-10-16, release 6.1.0 on 2026-08-21 and 6.0.0 on 2026-08-14. ## Seventeen permissions, and a key you have to make by hand Signing in works in two ways, and both are marked done in the feature table: by phone, through a separate authentication project linked from the README, and by entering an API key. If you take the API key route, the server will not hand you a working key by default, because the app needs a specific set of scopes granted when the key is created. The list is long enough to be worth reading before you start: activity.read, album.download, album.read, archive.read, asset.download, asset.read, asset.view, face.read, folder.read, library.read, memory.read, partner.read, person.read, session.read, tag.asset, tag.read and timeline.read. Each one has a plain description, from reading activity data to reading timeline data. Granting them all is what the documentation tells you to do so the app can function properly, and it is worth understanding what you are granting on your own server, since several of these read data about people and faces. ## The screensaver is the feature that needs a debugger Setting the app as the screensaver is listed as done, and it is the reason most people install this project. The app can be set as the screensaver, you can choose which albums it shows, and you can configure the interval, plus the background media info that is still marked as to do. Making it work is where the documentation turns into a troubleshooting guide, and the answer involves the developer options on the television. You enable development mode by clicking the build number, or the Android TV OS Build entry, seven times in the system about settings, then go to the developer options and enable USB debugging. You need ADB on your computer, and the instructions point at a guide for installing it on Windows, macOS and Linux. You connect to the device by its IP address with adb connect, and on an Amazon Fire TV there is an extra step, executing a command that disables the ambient mode before rebooting. That last part is the practical reality of this feature: it works, but on some devices you are reconfiguring the television's own screensaver behaviour by hand. ## Sorting and slideshow options that go beyond a plain grid The feature table is more revealing about what the app does with a library than any screenshot. You can show people, random, recent or seasonal photos, which means the library is navigable by face and by season rather than only by date. There is generic sorting of albums and photos, and a separate sort for one specific album, which works by selecting the last item in a row and pressing right again. The slideshow of photos and videos runs on a configured interval, has transitions, and can be told not to play sound with videos, so a silent ambient slideshow is one setting away. EXIF data can be shown, and there is a separate entry about improving the slideshow view to accommodate it. There is also a performance option that is easy to miss and useful on a large library: showing the 4K thumbnail instead of the full image, to speed up loading. Smarter merging of portrait photos is listed as to do, which is the feature that would group shots of the same people, date and city. ## The feature table tells you what is missing The project publishes its feature list with a status column, and several rows are worth reading closely because they describe the boundary of the project rather than its features. Adding a places and tags view is to do, and so is searching in and for albums, which means there is no search box on the television. Background media playing info in the screensaver is also to do. Dependency injection with Hilt or Dagger is listed as to do, which is a note about the codebase rather than the product. Casting capabilities are marked out of scope, and that is the one row that is explicitly a decision rather than a backlog. The demo environment is marked done, which is a developer convenience for trying the app without a server. Read this table before you install, because it is a more reliable statement of what the app does than any promotional description, and because several of the gaps are ones you would notice immediately on a large library. ## Building it yourself needs Firebase and a demo server There is no published build in the usual sense, so the build steps are the way to run it. You clone the project with submodules, using the recursive flag, because the repository carries a gitmodules file and the submodules are needed: ```bash git clone --recurse git@github.com:giejay/Immich-Android-TV.git ``` Then you create a Firebase account and a google-services.json file, and the project gives you a copy of an example to start from: ```bash cp app/google-services.example app/google-services.json ``` Next you copy the strings_other.xml example into the resources, to the path app/src/main/res/values/strings_other.xml, and modify the address and API keys for your demo server. The final step is the Gradle build: ```bash ./gradlew assembleRelease ``` The repository root holds the usual Android pieces, with an app directory for the application, a separate mediaslider directory, a gradle wrapper, a create-release.sh script, a get-version.sh script and a .run directory. The demo server step in the build is what the demo environment feature in the table exists for, since a build needs somewhere to point. ## GPL-3.0 and an active but small project The licence field on the repository says GPL-3.0, and the LICENSE file at the root carries the terms, which matters for one specific case: if you intend to modify the app and distribute the modified build, the copyleft terms come with it. The repository also carries a CODE_OF_CONDUCT file, and the project asks for bug reports and pull requests rather than only donations, which is the normal pattern for a community-run client of a larger project. The last push was on 2026-10-16, the same day as the 6.2.0 release, so the work is current rather than abandoned. There is no homepage field for the project, so the README's link to the main Immich repository is the entry point for the wider ecosystem, and the authentication helper for phone sign-in is a separate repository of its own, which is worth knowing before you set up the easier of the two sign-in methods. ## Conclusion Immich Android TV suits a household that runs its own Immich server and wants the photo library on the television, especially as a screensaver, and that is comfortable creating an API key with the seventeen permissions the app lists. It does not suit someone who wants the app to upload media, because the upload and backup side belongs to the phone app, and it does not suit a family that wants search, places and tags on the television, because those items are listed as still to do. Before installing it, confirm your server is on version 3.0.0 or newer, grant the listed permissions when you create the API key, and expect to enable developer options and use ADB to register the screensaver. ## FAQ ### Which Immich server version does the Immich Android TV app need? The app is compatible with Immich server v3.0.0 and newer. Version 3.0.0 introduced breaking API changes including album asset loading via search/metadata, search visibility defaults and the error response format, and the app has been adapted to them. ### What permissions does the Immich Android TV API key need? The documented set is activity.read, album.download, album.read, archive.read, asset.download, asset.read, asset.view, face.read, folder.read, library.read, memory.read, partner.read, person.read, session.read, tag.asset, tag.read and timeline.read. No extra permissions are needed for v3 compared to earlier server versions. ### How do I set the Immich Android TV app as the screensaver? Enable developer mode on the device by clicking the build number seven times in the system about settings, turn on USB debugging in the developer options, install ADB on your computer, and connect with adb connect using the device IP. On an Amazon Fire TV, run the command that disables the ambient mode first and reboot. ### Can the Immich Android TV app upload photos and videos? No. Uploading and automatic backup are features of the main Immich application and its server, and this project is described as a way to view the photos and videos that have already been uploaded. ## Sources - [giejay/Immich-Android-TV on GitHub](https://github.com/giejay/Immich-Android-TV) - [Issues](https://github.com/giejay/Immich-Android-TV/issues) - [License: GPL-3.0](https://github.com/giejay/Immich-Android-TV/blob/main/LICENSE) - [README](https://github.com/giejay/Immich-Android-TV/blob/main/README.md) - [Releases](https://github.com/giejay/Immich-Android-TV/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/giejay-immich-android-tv