Anime, movies, series, and live TV in one app for your Android TV and phone

Plays your Stremio addons and IPTV playlists, made for a remote control

Install | Sources | Remote control | How it works | Documentation

---

Overview

ZettaStream is a stream aggregator for Android TV and Android phones. It shows the catalogs of your Stremio addons as rows of posters, finds the streams for a title in all your addons at the same time, and plays them. It also plays IPTV playlists as live TV, with a guide.

The app comes with no sources. You add your own list one time, and on a TV you do not type it with the remote control: you scan a QR code with your phone and paste the list there.

It is made for a remote control first. A slim bar of icons stays at the left of the TV screen, and each button on the remote has a job. On a phone, the same app has a tab bar and touch controls.

Screens

The layout follows Miruro 2.0, in black and white, with the Karla font. These screens are from the Android TV emulator and a phone emulator.

Home starts with a banner of featured titles.	The Anime filter. Each card shows the kind, the year, and the rating.
Your watchlist has its own row on Home.	The icon bar opens with a new Left press, Menu, or 0.
A title page: the art, the facts, and the buttons.	Seasons and episode cards.
A film, with Resume and an About table.	Search in all your addons.
Live TV from a playlist, with groups and favourites.	Settings.

The same app on a phone, with a tab bar.

Features

Watching Rows of posters from the catalogs of each addon Streams from all addons at the same time, with badges for quality, HDR, and dual audio, and torrents sorted by seeders Torrent streams, played while they download, with no seeding after Seasons and episodes, with the next episode to watch A countdown to the next episode, from the same source and quality Play starts the best 1080p stream at once, and shows which source plays. When a stream fails, the next best one starts. Yellow shows the list All the text of each stream shows next to it Continue watching, a watchlist, and watched marks, on the device only Subtitles from the stream and from subtitle addons Change the subtitle and the audio track with one button Viewer settings: subtitles, languages, subtitle size, next episode An options panel in the player: Menu, 0, or hold OK Skip the intro of an anime episode at the exact second, from AniSkip Subtitles from OpenSubtitles when no subtitle addon is in your list A subtitle delay and an audio delay in the player options Side bars of a 4:3 video filled with an ambient blur of the picture, or a stretch to fill the screen Video filters in the player: CRT, VHS, vintage film, and black and white Profiles, as on Netflix: each person has a picture, a history, a watchlist, and settings A "New episodes" row for the shows that you follow A trailer, the cast, and "More like this" on each title page "Explore more" at the end of each row opens all of its titles in a grid On a phone, the video goes on in a small window when you leave the app Live TV from M3U playlists, with now and next from an XMLTV guide, favourite channels, and a guide grid Back up and restore the library and the settings from the phone page

Made for a TV A slim icon bar at the left. Left at the start of a row opens it, but a fast run of Left presses stops at the edge Works with a game controller or a keyboard Turn each home row on or off, with new releases first Number buttons go straight to each screen Colour buttons for the watchlist, watched, sources, and filters Channel buttons for the next episode or the next channel A white ring that follows the edge of the focused item Add sources from a phone with a QR code A diagnostics page on the phone shows the last events of the TV Install updates from inside the app Unfinished titles in the Play next row of the TV home screen Voice search, and a TV that switches to the frame rate of the video A test screen that shows each button of your remote

Install on a TV

ZettaStream is not in the Play Store. Install it with the free Downloader app by AFTVnews.

1. On the TV, install Downloader from the Play Store.
2. In the settings of the TV, permit Downloader to install unknown apps.
3. Open Downloader, and enter the code 8764108.
4. Downloader shows the real URL for a moment. Make sure that it is github.com/Stiven-Gjekaj/ZettaStream.
5. Install the APK, then open ZettaStream from the list of apps.

The code opens this URL, which you can also type:

https://github.com/Stiven-Gjekaj/ZettaStream/releases/latest/download/ZettaStream.apk

The code always gives the newest release. To update, enter the same code again and install over the old version. The home screen tells you when a newer version is available.

An old TV

An old TV, such as one with Android 7.0, does not trust the certificate of GitHub downloads. Downloader then shows "unknown error". Enter the code 1216046 in Downloader instead. The code opens this URL, which you can also type:

https://cdn.jsdelivr.net/gh/Stiven-Gjekaj/ZettaStream@5476948f230292986bfec25133b529a757e25cc1/ZettaStream.apk

jsDelivr serves the APK with a certificate that old TVs trust. This link gives version 1.7.0. From 1.6.0, the app updates itself from GitHub, also on Android 7. The notes of each release give the link to its own APK.

If the TV is slow, open Settings, App, Lite mode. Lite mode is on by itself on Android 7 and on a TV with less than 2.5 GB of memory. The same row shows the memory and the chip of the TV.

Install on a phone

Open the newest release on the phone, download ZettaStream.apk, and open it. Android asks you to permit the browser to install apps.

Add your sources

ZettaStream reads three kinds of line. Put one URL on each line:

Line	Example	Gives
A Stremio addon	https://.../manifest.json	Catalogs, titles, streams, subtitles
An IPTV playlist	https://.../playlist.m3u	Live channels
A TV guide	https://.../guide.xml.gz	What is on now and next

On a TV:

1. Open the menu, then Settings, then Sources. The TV shows a QR code.
2. Scan the code with your phone. The phone must be on the same Wi-Fi.
3. Paste your list, and press Send.

On a phone: open Settings, then Sources, paste the list, and press Save.

The new list replaces the old list. To remove a source, remove its line and send the list again. Each QR code works one time.

The order of the lines sets the order of the rows on the home screen. Put the addon whose catalogs you like most first.

A metadata addon such as Cinemeta gives the rows on the home screen. A stream addon gives the streams. ZettaStream plays HTTP streams and torrent streams.

Torrents and your IP address

A torrent stream connects your TV to other people's devices. They can see your IP address. ZettaStream limits the upload to 4 KB/s, does not seed, and deletes each torrent when you stop watching, but it cannot hide your IP address. Use a VPN that permits P2P. The app reminds you at start; it does not check.

To avoid torrents, turn off Settings, Show torrent streams. A debrid key in a torrent addon's settings also changes its torrents into HTTP links.

The remote control

Button	Anywhere	In the player
Directions, OK	Move, select	Left and Right: back or forward 10 s. OK: pause
Back	Go back. Leave the icon bar	Leave the player
Menu, 0	Go into the icon bar, or leave it	Open or close the options
Hold OK		Open the options
1 to 5	Home, Search, Library, Live TV, Settings	1 to 9: go to 10% to 90%
Info	Open the focused title	Show the title and the time
Guide	Live TV
Red	Add to the watchlist, or remove
Green	Mark as watched
Yellow	Choose a source	Choose another source
Blue	Filter the home screen
Channel up and down	Scroll	Press twice: next or previous episode or channel
Subtitles		Next subtitle track
Language		Next audio track
Text		Skip the intro, ending, or recap (anime). Otherwise jump 85 s
OK at a prompt		Skip the part, or play the next episode now

A remote with no Menu key and no number keys can still do each action. Press Left at the start of a row to reach the icon bar. In the player, hold OK for the options, which also change the channel. Channel up and down change the episode, and Yellow chooses another source.

A game controller and a keyboard also work. A or Enter is OK. B or Escape is Back. Start, X, or Tab is Menu. Y is Info. L1 and R1 are Channel down and up.

Some TVs keep a button for themselves. Settings, Remote control test shows each button that reaches the app.

How it works

your list -> addons -> catalogs -> a title -> streams from each addon -> the player

ZettaStream speaks the open Stremio addon protocol. An addon is a small web server that answers requests in JSON. When you open an episode, the app asks each of your addons for streams at the same time, and shows each answer as it arrives. When an addon repairs a broken site, your TV gets the repair at once, because the work happens on the addon's side.

The app runs no code from a source. It sends HTTP requests and plays what comes back. For a torrent, a libtorrent engine downloads the file in order and serves it to the player on 127.0.0.1.

See docs/architecture.md for the whole picture, and docs/decisions.md for the reason behind each choice.

Project structure

app/src/main/kotlin/.../zettastream/
  addon/      the Stremio addon protocol
  iptv/       M3U playlists and XMLTV guides
  source/     the source list
  library/    the watchlist and the watch history
  pairing/    the page that a phone opens to send the list
  remote/     what each remote control button does
  torrent/    the torrent engine and its local server
  settings/   the viewer settings
  ui/         the screens, the theme, and the components
app/src/test/ the unit tests
assets/brand/ the icon and the TV banner
docs/         how the parts fit together, and why

Documentation

Build How the parts fit together Architecture

Decide Each choice and its reason Decisions

Help When something does not play Support

Join in How to work on this Contributing

Follow What changed, and when Changelog

Terms What you agree to by using it Terms

Building

You need JDK 21 and the Android SDK.

git clone https://github.com/Stiven-Gjekaj/ZettaStream
cd ZettaStream
./gradlew assembleDebug

The APK is in app/build/outputs/apk/debug/. A tag such as v0.1.0 makes the workflow build a signed APK and attach it to a release.

The app has a startup profile in app/src/main/baseline-prof.txt. Android compiles this code ahead of time, so the first starts after an install are not slow. To record it again after a large change, start an emulator with Android 13 or newer and run:

./gradlew :baselineprofile:connectedBenchmarkAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=io.github.stivengjekaj.zettastream.baselineprofile.StartupProfile

Then copy the StartupProfile_record-startup-prof.txt file from baselineprofile/build/outputs/connected_android_test_additional_output/ to app/src/main/baseline-prof.txt.

Testing

./gradlew testDebugUnitTest lintDebug

The unit tests cover the addon protocol, the playlists and the guides, the source list, the library, the remote control keys, the pairing page, the torrent helpers, the settings, the skip times, the stream data, the home rows, the HTTP cache, and the player messages. The tests of the addon client talk to a local mock server, not to a real addon. Lint must report no error and no warning. The workflow runs both on each push.

The interface is tested by hand on an Android TV emulator with a D-pad, and on a phone emulator. See CONTRIBUTING.md.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, follow the Code of Conduct, and see SUPPORT.md if you need help. A contribution that adds a source, or a link to a source, is refused.

Profile pictures

The pictures of anime characters come from AniList. The pictures of TV characters and actors come from TVmaze, under CC BY-SA. The app asks these services only when you choose a picture. The rights to each picture stay with their owners.

A note on rights

ZettaStream is a player. It contains no media and no sources, and the project does not recommend any. You choose your sources, and you are responsible for them and for what you watch. See TERMS.md.

License

MIT. See LICENSE for the text, and TERMS.md for the terms of the project. Karla is under the SIL Open Font License, in licenses/.

_{Made for one Hitachi TV and one remote control. Press 0 for the menu.}