jellystack

Android TV, Google TV, and Fire TV

Jellystack TV is a remote-first companion build in the same Kotlin Multiplatform repository. It shares server, authentication, metadata, settings, and playback code with Jellystack mobile while using a dedicated Compose for TV interface.

The current closed beta is 0.16.0-tv-beta.4 with versionCode 22 and package ID app.jellystack.mobile.

Supported devices

• Android TV and Google TV on Android 7.0 or newer
• Fire TV devices on Fire OS 6 or newer
• 1080p and 4K landscape displays

The first beta does not include downloads, Cast, App Lock, biometrics, the admin dashboard, picture-in-picture, touch navigation, or voice search.

Build

Run all commands from the repository root with JDK 17:

.\gradlew.bat :app-android:assembleDebug
.\gradlew.bat :app-tv:assembleDebug
.\gradlew.bat :app-tv:assembleRelease :app-tv:bundleRelease
.\gradlew.bat verifyUniqueAndroidVersionCodes :app-tv:verifyTvReleaseManifestPermissions

Outputs:

• Debug APK: app-tv/build/outputs/apk/debug/app-tv-debug.apk
• Release APK: app-tv/build/outputs/apk/release/app-tv-release.apk
• Release AAB: app-tv/build/outputs/bundle/release/app-tv-release.aab

The TV AAB is a local store artifact. It must not be committed or attached to a GitHub release.

Emulator and Fire TV installation

List connected devices and install the debug build:

adb devices
adb -s <serial> install -r app-tv/build/outputs/apk/debug/app-tv-debug.apk
adb -s <serial> shell monkey -p app.jellystack.mobile -c android.intent.category.LEANBACK_LAUNCHER 1

For a physical Fire TV, enable Developer Options, ADB Debugging, and Apps from Unknown Sources. Connect with adb connect <fire-tv-ip>:5555, confirm the prompt on the TV, then use the same install command.

Test at minimum:

• Cold start, Home, Sleep/Wake, app switching, and Back behavior
• D-pad, Play/Pause, Rewind, Fast Forward, and Fire TV Menu
• Quick Connect and password fallback
• Direct Play and HLS with AAC, AC3, EAC3, Opus, and a forced-transcode case
• Audio and subtitle switching, quality, playback speed, Stats for Nerds, and SyncPlay
• Wi-Fi or Ethernet interruption and recovery
• A playback session longer than 30 minutes

Remote controls

• Center: open controls or toggle play/pause when controls are hidden
• Left/Right: seek when controls are hidden; hold for accelerated scrubbing
• Up/Down: show controls and move between player information
• Back: close dialog, close panel, hide controls, leave player, then focus the navigation rail
• Hardware Play/Pause, Rewind, Fast Forward, Stop, and Menu are handled explicitly

Permissions and platform services

The TV manifest is limited to INTERNET and ACCESS_NETWORK_STATE, plus the application-scoped receiver permission generated by Android. TV does not include Google Play Services, Cast, location, storage, notification, or biometric permissions. Active playback keeps the display awake through the Activity window lifecycle rather than a wake-lock permission.

Run :app-tv:verifyTvReleaseManifestPermissions before every store build. Also inspect the final release manifest because transitive dependencies can change.

Google Play closed TV test

1. Enable the Android TV form factor for the existing Play Console app.
2. Create a dedicated closed Android TV test track.
3. Upload app-tv-release.aab with versionCode 22.
4. Upload store-assets/tv/google-play-banner-320x180.png as the localized TV banner.
5. Upload at least two real 1920x1080 TV screenshots captured from a current build.
6. Provide reusable English reviewer credentials and Quick Connect instructions under App Access.
7. Confirm the Data safety and permission declarations match the TV artifact.
8. Promote only after the emulator and physical Fire TV checklist passes.

Google guidance: https://developer.android.com/training/tv/publishing/distribute

Amazon Live App Testing

1. Create a Fire TV app in the Amazon Developer Console using package ID app.jellystack.mobile.
2. Select Fire TV as the supported device class.
3. Upload the same GMS-free TV APK or AAB used for Google TV testing.
4. Upload:
   • store-assets/amazon/0.16.0-tv-beta.3/fire-tv/app-icon-1280x720.png
   • store-assets/amazon/0.16.0-tv-beta.3/fire-tv/background-1920x1080.png
   • the five real 1920x1080 screenshots in the same fire-tv directory
5. Add the privacy URL, support URL, English reviewer credentials, and Quick Connect steps.
6. Start Live App Testing, install Amazon’s re-signed build on a physical Fire TV, and rerun playback, audio focus, remote, network, and lifecycle checks.
7. Submit for normal review only after Live App Testing passes.

Amazon guidance:

• https://developer.amazon.com/docs/app-submission/upload-app-file.html
• https://developer.amazon.com/docs/fire-tv/differences-from-android-tv-development.html
• https://developer.amazon.com/docs/fire-tv/multimedia-app-requirements.html

Store and binary validation

Before upload:

• Confirm APK and AAB signatures use the expected upload certificate.
• Record SHA-256 hashes for both release files.
• Inspect every packaged ABI and native library.
• Confirm packaged native libraries are compatible with 16 KB page sizes.
• Confirm the TV dependency graph contains no Google Play Services or mobile-only modules.
• Keep AAB files local; screenshots and public store artwork may be committed when they contain no private server or account data.

This site is open source. Improve this page.