HomeKey TV

Fast, lightweight Jetpack Compose quick-access dock and remote button remapper for Google TV and Android TV, seamlessly integrated with Home Assistant.

---

Screenshots

Floating Quick-Access Dock with dynamic state badge over Google TV

---

Features

• Floating Quick-Access Dock:

  • Customizable dock positioning: Bottom Dock, Left Dock, or Right Dock.
  • Solid, high-contrast tiles and badges designed for TV readability over any background or active video stream.
  • Interactive popup dialogs for light brightness adjustment (0–100%), switches/booleans, and climate controls (temperature and HVAC modes).
  • Pin installed Android TV apps directly alongside Home Assistant entities.
  • Smart Reorder Visibility: Reorder button automatically hides when 1 or fewer items are pinned, keeping the dock interface clean and uncluttered.
  • Side Dock Inset Badges: Entity label badges in Left and Right dock modes are positioned at the top and inset inward to prevent visual overlapping with dock items.

• Recent Apps Satellite Dock:

  • Display up to 5 recently used Android TV apps in a satellite row or column adjacent to the primary dock.
  • Configurable app count (1 to 5) via Settings > Installed Apps.
  • Full-bleed circular icon styling with smooth 1.15x scale focus animation.
  • Fluid bidirectional D-pad navigation:
    • In Bottom Dock mode: press DPAD DOWN to move from dock items into the recent apps row; press DPAD UP to return.
    • In Side Dock modes: centered vertical column easily accessible via D-pad.
  • Clean Empty Dock State: When no entities are pinned, displays only recent apps along with a matching circular Settings shortcut, or a direct "Configure from settings" card if recent apps are disabled.

• Smart Home Media & TV Controls:

  • Interactive MediaPlayerDialog modal for active media players: volume control bar with D-pad Left/Right control and Mute toggle, input source carousel, transport playback buttons (Play/Pause, Prev, Next), and power toggle.
  • Short click on a media player tile in the dock toggles Play/Pause instantly; long-press opens the interactive dialog.

• Native Remote Button Remapper:

  • Intercept and remap any remote button (e.g. Netflix, YouTube, Color Keys, Guide, Live TV, Star button) using an isolated, non-blocking AccessibilityService.
  • Independent Single-Press, Double-Press, and Long-Press triggers per keycode.
  • Remap to actions: Open Dock, Toggle Light/Switch, Input Source Switch, Launch TV App, Sleep TV, or TV Settings.
  • Input Source Switching (SELECT_SOURCE): Map any physical remote button to switch your TV or receiver directly to a desired input (e.g. TV, HDMI 1, HDMI 2) via Home Assistant with zero UI popups.
  • Entity Search: Instant real-time search filter when selecting Toggle HA entities in button remap configuration.
  • In-App Local ADB Auto-Setup: Activate button remapping and overlay permissions directly from the TV on Fire OS and Android TV without requiring an external computer or manual terminal commands.
  • Pass-through protection for system keys: Home, Volume, Recents, and Sleep are never blocked.

• Instant Phone Web Setup (Port 8124):

  • Built-in lightweight local web server with QR code for instant pairing on mobile or desktop browsers.
  • Search, filter, and multi-select entities from your Home Assistant instance.
  • Custom Entity Renaming: Set custom display names directly in the web UI.
  • Custom Icon Picker: Choose from an extensive Material icon gallery.
  • Automatic credential persistence in browser storage for instant, hassle-free updates.

• In-App GitHub Update Checker:

  • Direct integration with GitHub Releases to check for latest updates.
  • Semantic version checking and release notes display.
  • Direct APK download and automated prompt for Android TV Package Installer.

• Security and Hardened Architecture:

  • Long-Lived Access Tokens stored in EncryptedSharedPreferences backed by the hardware Android Keystore.
  • 6-digit dynamic pairing PIN with automated brute-force rate-limiting and temporary lockouts.
  • Entity fetching proxied exclusively to your verified Home Assistant server (SSRF protection).
  • allowBackup="false" to prevent token extraction via ADB or cloud backups.

• Hardware-Accelerated Smoothness:

  • Optimized for low-power quad-core TV chipsets (e.g. MediaTek Cortex-A55).
  • Isolated Compose state holders to eliminate root layout recomposition on D-pad navigation.
  • RenderNode scaling via Modifier.graphicsLayer and memoized icon vector parsing for steady 60fps operation.

---

Architecture and Tech Stack

• UI Framework: Jetpack Compose for Leanback and Android TV.
• Async and Reactive: Kotlin Coroutines and StateFlow reactive pipelines.
• Home Assistant Communication:
  • WebSocket Client: Real-time bidirectional connection (HAWebSocketClient) with exponential backoff and automatic event resubscription.
  • REST Client: OkHttp for entity fetching and service calls.
• Embedded Web Server: NanoHTTPD for local network phone pairing.
• System Hooking: Android AccessibilityService (RemoteButtonRemapService) for native keycode capture and TV power controls.
• Storage: Android Jetpack EncryptedSharedPreferences and Security-Crypto.

---

Installation

Option 1: Sideload via ADB (Recommended)

1. Enable Developer Options and Network Debugging on your Google TV / Android TV (Settings > System > About > Build — tap 7 times).
2. Connect to your TV via ADB:

   adb connect <TV_IP_ADDRESS>:5555

3. Install the Release APK:

   adb install -r HomeKeyTV-v1.6.3.apk

Option 2: Sideload via File Manager

Transfer the APK to your TV using a USB drive or local network sharing app (e.g., Send Files to TV), then install via a TV file manager.

---

Setup Guide

1. Launch HomeKey TV from your TV apps list or Leanback launcher.
2. Open Settings (gear icon on the dock or from the app drawer).
3. Select Instant Phone Setup:
   • Scan the on-screen QR Code or navigate to http://<TV_IP>:8124 in your mobile browser.
   • Enter the 6-digit Pairing PIN shown on the TV screen.
   • Provide your Home Assistant URL (e.g. http://192.168.1.100:8123 or Nabu Casa URL) and a Long-Lived Access Token (created in Home Assistant under Profile > Long-Lived Access Tokens).
4. Choose and Customize Entities:
   • Select entities to display on your dock.
   • Edit custom display names and select custom icons.
   • Tap Save Configuration to TV.

Setting Up Remote Button Remapping

1. In the TV app, navigate to Settings > Remote Button Remap.
2. Tap Enable Accessibility Service to grant the button remapping permission.
3. Click Add New Button Remap and press the physical button on your remote control to detect its KeyCode.
4. Configure actions for Single Press, Double Press, and Long Press.
5. Save your remap rule.

---

Building from Source

Prerequisites

• JDK 17+
• Android SDK with API 34+
• Gradle 8.4+

Build Commands

# Clone repository
git clone https://github.com/leonida92/HomeKeyTV.git
cd HomeKeyTV

# Run Unit Tests
./gradlew testDebugUnitTest

# Assemble Release APK
./gradlew assembleRelease

The compiled release APK will be located at: app/build/outputs/apk/release/HomeKeyTV-v1.6.3.apk

---

License

Copyright 2026 HomeKey TV Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.