Android TV

Beta (since 1.3.6). Tested on an NVIDIA SHIELD so far. Tell us how it goes with your TV.

Astrion can pair with an Android TV or Google TV directly, like the Google TV app on a phone: no Home Assistant, no ADB, no Harmony hub. You get the remote keys, app launching, power, and the TV's state (on/off, current app, volume).

Works with devices running Android TV Remote Service (nearly every Android TV / Google TV): NVIDIA SHIELD, Chromecast with Google TV, Google TV Streamer, Sony, Philips, TCL, Hisense and Xiaomi TVs and boxes… Not with Fire TV (Amazon left that service out).

Your TV and the remote must be on the same network.

Pair

On the remote's web page › Android TV › + Add Android TV:

1. Astrion searches your network. Pick your TV, or type its IP address if it isn't listed (some routers block the search).
2. A 6-character code (digits and letters A–F) appears on the TV: type it and click Pair. Give it a name (e.g. Living room).

The first pairing takes a few extra seconds: the remote creates its own key, then reuses it for every TV.

The list then shows the TV, its entity (media_player.androidtv_living_room) and its state: ● on, ● off, ○ not reachable, or ⚠ pair it again.

What you get

Each paired TV becomes two entities that Astrion answers itself, named like Home Assistant's Android TV Remote integration:

Entity
media_player.androidtv_<name>	On / off, current app (app_id, app_name, also as source), volume level and mute, a source_list of common apps
remote.androidtv_<name>	remote.send_command with Android key names

They're added to the device catalogue automatically, so the builder offers them everywhere:

Where
TV remote card (tv_remote)	Pick remote.androidtv_…: D-pad, back, home, menu, volume, power and app buttons work as is. The now-playing strip shows the app in front with its icon
Media player card	State, volume, mute
Source select card	Launch an app
Hotkeys	Action Android TV key or app: pick the TV, then a key (e.g. CHANNEL_UP on the CH+ key, repeated while held) or an app to open
Activities	Section Android TV (network) in the wizard: turned on when the Activity starts, off when it ends, can open an app

Title and cover need the Astrion TV Helper. The protocol only says which app is in front, not what it plays (the Google TV app doesn't show it either). Without the helper, give each app an icon in the TV remote card: the now-playing strip shows it.

Keys (remote.send_command)

Android key names, with or without KEYCODE_: DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT, DPAD_CENTER, BACK, HOME, MENU, POWER, VOLUME_UP, VOLUME_DOWN, VOLUME_MUTE, MEDIA_PLAY_PAUSE, MEDIA_NEXT, MEDIA_PREVIOUS, MEDIA_REWIND, MEDIA_FAST_FORWARD, CHANNEL_UP, CHANNEL_DOWN, SEARCH, SETTINGS, TV_INPUT, 0–9… Shortcuts: UP, DOWN, LEFT, RIGHT, OK/SELECT, PLAY_PAUSE, PLAY, PAUSE, NEXT, PREVIOUS. A number sends that key code.

• MUTE mutes the sound (like VOLUME_MUTE). For the microphone key, send 91.
• num_repeats (up to 20) repeats the command.
• hold_secs greater than 0 makes a long press (what it does depends on the TV and the key).

{ "service": "remote.send_command", "entity_id": "remote.androidtv_living_room", "data": { "command": "CHANNEL_UP" } }

Apps

media_player.select_source or media_player.play_media (media_content_type: app) with an app name from the list or an Android package name:

{ "service": "media_player.select_source", "entity_id": "media_player.androidtv_living_room", "data": { "source": "Netflix" } }

Known names: Netflix, YouTube, Prime Video, Disney+, Max, Apple TV, Paramount+, Plex, Kodi, Spotify, YouTube Music, Twitch, myCANAL, Molotov, france.tv, Stan, DAZN, Crunchyroll, GeForce NOW, YouTube Kids. Any other app: use its package name (e.g. org.videolan.vlc), as shown in its Play Store link (?id=…). A link (https://…) opens in the app that handles it.

Since August 2026, a Google Play Store update makes many TVs refuse to open an app by its package name. YouTube, Netflix, Prime Video, Disney+, Plex, Twitch and myCANAL are opened through their deep link, which still works. For other apps, use the app's deep link: see Finding an app's deep link.

The protocol can't list installed apps, so source_list is this fixed list.

Power

• turn_on sends Power only if the TV is off (when its state is unknown, it sends Wake-up, which never switches it off).
• turn_off sends Power only if the TV is on.
• The TV remote card's power button sends POWER: a toggle.

Astrion TV Helper: title, cover, any app

A small free app to install on the TV itself (1.3.6+). With it, the TV's media_player gets:

• what's playing: title, artist or episode, cover, duration and position, playing / paused, for every app that shares it with Android (Plex, Netflix, YouTube, Spotify… myCANAL only shares playing / paused);
• any app opens, even the ones without a deep link: the helper starts them on the TV itself;
• seeking (media_player.media_seek), e.g. from the media player card's progress bar.

Cards, the dock clock and Activities use it with no other setting.

Install

1. Download astrion-tv-helper.apk from the tv-helper release.

2. On the TV: Settings › Device Preferences › Developer options, turn on Network debugging (on a SHIELD; elsewhere USB debugging + ADB over network). The TV shows its address, e.g. 192.168.2.18:5555.

3. On a computer with ADB, using that address:

   adb connect 192.168.2.18:5555
   adb install astrion-tv-helper.apk
   adb shell cmd notification allow_listener com.custom.astrion.tvhelper/com.custom.astrion.tvhelper.MediaListener
   adb shell appops set com.custom.astrion.tvhelper SYSTEM_ALERT_WINDOW allow

   Accept the Allow debugging? prompt on the TV the first time. The third line lets the helper read what's playing (Android calls it notification access; the helper never reads notifications), the fourth lets it open apps.

4. Open Astrion TV Helper from the TV's apps: it shows a 6-character code and two ✓.

5. On the remote's web page › Android TV, click + Helper next to the TV and type the code. The list then shows ● helper.

You can turn Network debugging off again afterwards. The helper starts by itself with the TV; it only runs a small local web server (port 6470), which answers only a remote that has its code.

Troubleshooting the helper

Symptom	Check
Helper not linked: no Astrion TV Helper at …	Is the helper installed, and opened once? Same network as the remote?
⚠ helper code refused	The helper was reinstalled (new code): click Helper… and type the new code.
○ helper not reachable	The TV is off or asleep; the remote retries by itself.
No title for an app	That app doesn't share it with Android. With ADB: adb shell dumpsys media_session while it plays: metadata: null means it shares nothing.
✗ on the helper's screen	Run the matching ADB line from step 3 again (after a TV reset, for example).

Rename or remove

• ✎ renames it. The entity id is kept, so your cards keep working.
• ✕ removes it. Cards using it stop working until you pair again.

Pairing the same TV again (after a reset, for instance) keeps its entity id.

Troubleshooting

Symptom	Check
"No Android TV found"	Is the TV on and on the same network (same VLAN, no client isolation)? Search again, or type its IP (TV › Settings › Network).
No code on the TV	The TV must be awake. On a SHIELD, wake it first. Try again from the list.
"Wrong code"	Check the letters: only 0–9 and A–F. Codes expire when the pairing screen closes: start over and type the new one right away.
⚠ pair it again	The TV forgot the remote (reset, or Settings › Remotes & Accessories cleared). Pair it again: the entity id stays.
○ not reachable	The TV is off the network, or its IP changed. Astrion looks for it again on the network by itself every few failed tries. A fixed IP (DHCP reservation) on your router avoids it.
An app doesn't open, and the remote reconnects (keys work)	Since a Google Play Store update (August 2026), many Android TVs refuse the generic way of opening an app (market://launch?id=…), for every remote, Home Assistant's included. Astrion uses the app's deep link instead for YouTube, Netflix, Prime Video, Disney+, Plex, Twitch and myCANAL. For another app, put its deep link (https://… or app://…) in the card's or hotkey's app field instead of the package name: see below.
Opening an app does nothing and the log says doesn't offer app launches	The TV doesn't offer app launches to remotes; the log (AndroidTv) says doesn't offer app launches. On the TV: Settings › Apps › See all apps › Show system apps › Android TV Remote Service › Clear data, then pair it again on the remote's web page (the entity id stays).
A key does nothing	Some keys depend on the TV and the app in front. Try the KEYCODE_ number instead.

Finding an app's deep link

With ADB (TV › Developer options › Network debugging):

adb connect <TV IP>:5555
adb shell dumpsys package <package> | findstr /i "scheme"

(grep -i scheme instead of findstr on macOS/Linux.) Each Scheme: "xxx" is a candidate: try it with adb shell am start -a android.intent.action.VIEW -d "xxx://". If the app opens, xxx:// is the link to use. If it says unable to resolve Intent, the scheme needs an address: show its block with adb shell dumpsys package <package> | Select-String -Context 10,6 <scheme> (PowerShell) and build the link from its Authority and Path lines, e.g. myCANAL's mycanaltvlauncher://com.canal.android.canal/startapp.

How it works

Astrion speaks the Android TV Remote v2 protocol (the one the Google TV app uses) over your network, on ports 6466 and 6467, encrypted (TLS). Pairing exchanges certificates: after that, only this remote's key can control the TV, and Astrion only accepts that TV's certificate. Nothing goes through the internet.