No description
  • Python 98.9%
  • Shell 0.9%
  • Batchfile 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Codex 2720dab311 Release 0.2.0: single-file builds
- Spec now builds a single-file GUI program with unused Qt modules excluded.
- Bump version to 0.2.0; document release downloads.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
2026-10-14 01:58:39 +02:00
scripts Initial Android TV Shortcut Inspector 2026-10-09 11:31:29 +02:00
src/atv_shortcuts Release 0.2.0: single-file builds 2026-10-14 01:58:39 +02:00
tests Add Now Playing and slim the GUI down 2026-10-14 01:36:42 +02:00
.gitignore Initial Android TV Shortcut Inspector 2026-10-09 11:31:29 +02:00
AndroidTVShortcutInspector.spec Release 0.2.0: single-file builds 2026-10-14 01:58:39 +02:00
install.bat Initial Android TV Shortcut Inspector 2026-10-09 11:31:29 +02:00
install.sh Initial Android TV Shortcut Inspector 2026-10-09 11:31:29 +02:00
pyproject.toml Release 0.2.0: single-file builds 2026-10-14 01:58:39 +02:00
README.md Release 0.2.0: single-file builds 2026-10-14 01:58:39 +02:00
run.bat Initial Android TV Shortcut Inspector 2026-10-09 11:31:29 +02:00
run.sh Initial Android TV Shortcut Inspector 2026-10-09 11:31:29 +02:00

Android TV Shortcut Inspector

Android TV Shortcut Inspector is a cross-platform Python desktop application for discovering, testing, saving, verifying, and exporting Android TV / Google TV deep-link shortcuts over ADB.

The GUI is the primary interface. The optional atv-shortcuts CLI uses the same backend for scripting and debugging.

Features

  • Connect over USB ADB, traditional TCP/IP ADB, or modern Wireless Debugging pairing.
  • Save friendly aliases such as Living Room TV or Bedroom TV.
  • Browse installed packages with pm list packages.
  • Inspect package metadata and deep-link intent filters from dumpsys package.
  • Inspect the foreground package/activity from dumpsys activity activities.
  • Live-watch activity transitions without duplicating unchanged samples.
  • Now Playing: shows what is playing on the TV (verified via the app's audio track), the deep link that reopens it, and the direct stream URL only if the app exposes one. Test and Save in one click.
  • Find: type what you are looking for (a channel, show or id) and search the app's saved shortcuts, TV home-screen listings, log, code, and URL patterns; every URL is checked with Android's own resolver before it is ranked.
  • Learn: watch the TV while you navigate, tying the focused item to the URL/activity it opens.
  • Test ACTION_VIEW deep links and verify whether they opened only the app or likely content.
  • Capture and filter logcat in Python.
  • Record a manual navigation session, analyze activity/logcat evidence, and suggest shortcut candidates.
  • Save shortcuts in JSON.
  • Launch saved shortcuts.
  • Export tvQuickActions fields, ADB commands, JSON, or plain text.
  • Optional Linux user-level systemd reconnect helper.

Supported Platforms

  • Windows 10/11
  • Ubuntu Linux
  • Debian Linux
  • Raspberry Pi OS
  • Other Linux distributions where adb is available

The backend does not rely on PowerShell, cmd.exe, grep, findstr, sed, or awk. ADB commands are executed with Python subprocess argument arrays, and parsing/filtering happens in Python.

Project Layout

android-tv-shortcut-inspector/
├── pyproject.toml
├── README.md
├── install.bat
├── install.sh
├── run.bat
├── run.sh
├── scripts/
│   ├── adb-connect.sh
│   └── adb-tv.service
├── src/atv_shortcuts/
│   ├── main.py
│   ├── cli.py
│   ├── config.py
│   ├── adb/
│   ├── parsers/
│   ├── discovery/
│   ├── shortcuts/
│   ├── gui/
│   └── workers/
└── tests/

Downloads

Prebuilt single-file programs (Windows x64, Linux x86_64, glibc 2.35+) are attached to each release on the repository's Releases page. Both still need adb installed (see below). The Windows exe is unsigned, so SmartScreen may warn on first run.

Windows Install

Install Python 3, then run:

install.bat
run.bat

ADB can be:

  • adb.exe available in PATH
  • a custom path configured in Settings
  • Google's Android SDK Platform Tools directory added to PATH

Linux Install

Run:

chmod +x install.sh run.sh scripts/adb-connect.sh
./install.sh
./run.sh

On Debian, Ubuntu, or Raspberry Pi OS, install ADB with:

sudo apt update
sudo apt install adb

Alternative: download Google's current Android SDK Platform Tools, extract it, and either add the folder to PATH or set the custom ADB path in Settings.

Google TV / Android TV Setup

  1. Enable Developer Options on the TV.
  2. Enable USB debugging or Wireless Debugging.
  3. If using modern Wireless Debugging, note both ports:
    • pairing port
    • normal ADB connection port
  4. Pair first, then connect.

The pairing port and the normal ADB port are not assumed to be the same.

Wireless Debugging

GUI:

  1. Open Devices.
  2. Click Pair Device.
  3. Enter IP address, pairing port, ADB port, and pairing code.
  4. Click Connect.

CLI:

atv-shortcuts pair 192.168.1.50:37123
atv-shortcuts connect 192.168.1.50:42345

Traditional TCP/IP ADB:

atv-shortcuts connect 192.168.1.50:5555

Disconnect:

atv-shortcuts disconnect
atv-shortcuts disconnect 192.168.1.50:5555

List devices:

atv-shortcuts devices

Device Aliases

atv-shortcuts device add livingroom 192.168.1.50:5555 --default
atv-shortcuts device add bedroom 192.168.1.51:5555
atv-shortcuts use livingroom
atv-shortcuts --device livingroom scan-app dk.dr.tvplayer

The app stores devices in:

  • Windows: %APPDATA%\AndroidTVShortcutInspector\
  • Linux: ~/.config/android-tv-shortcut-inspector/

For portable/testing runs, override the config directory:

ATV_SHORTCUTS_CONFIG_DIR=/path/to/config atv-shortcuts shortcuts

Files:

config.json
devices.json
shortcuts.json
sessions/

Main GUI Pages

Screenshot placeholders:

  • Dashboard: connection state, Android version, foreground app/activity, saved shortcut count.
  • Devices: connected devices, aliases, pairing, connect/disconnect/reconnect.
  • Apps: installed packages, package inspection, deep-link handlers.
  • Inspector: current activity and Live Watch transition timeline.
  • Find: search an app for a channel/show/id, or Learn from your remote navigation.
  • Discover Shortcut: record what you do, capture relevant activity/logcat events, suggest candidates.
  • Deep Link Tester: build and test intents.
  • Logcat: clear, capture, filter, and export relevant log lines.
  • Shortcuts: launch, test, edit, duplicate, delete, export.
  • Export: tvQuickActions, ADB command, JSON, plain text.
  • Recording Sessions: inspect stored discovery sessions.
  • Settings: ADB path, default device, polling interval, theme, auto reconnect, retention, logcat defaults.

CLI Examples

List packages:

atv-shortcuts packages

Scan one app:

atv-shortcuts scan-app dk.dr.tvplayer

Show current activity:

atv-shortcuts current

Capture the currently running app/activity into a saved shortcut draft:

atv-shortcuts capture-current "Current DRTV"

If Android does not expose the content URI, attach a known or discovered deep link:

atv-shortcuts capture-current TVA --data "https://www.dr.dk/drtv/kanal/192099"

Analyze the current app with foreground state, package deep-link handlers, recent filtered logcat, and known app profiles:

atv-shortcuts discover-current

Candidate sources are explicit:

OBSERVED_NOW     The URI was exposed by the currently foreground Android intent.
OBSERVED_LOGCAT  The URI appeared in recent filtered logcat.
SAVED_SHORTCUT   A shortcut you already saved for this package.
KNOWN_PROFILE    A known shortcut suggestion for that app, not proof of the current stream.

This is intentionally generic: DRTV examples are built-in profile suggestions, but every Android TV app uses the same discovery pipeline. As you save working shortcuts for Plex, YouTube, TV 2 Play, or another app, those saved shortcuts become package-specific profile suggestions for future discovery.

What is playing right now:

atv-shortcuts now
atv-shortcuts now --test --save DR1

The deep link comes from the foreground intent when the app was opened with one, otherwise it is rebuilt from the app's own log and matched to the item the app requested just before playback started. A direct stream URL (.m3u8/.mpd) is only shown if it appears in the app's log or media session. Most apps fetch it over HTTPS without logging it, in which case the tool says so; it cannot be read over ADB without root.

Find something in an app:

atv-shortcuts find dk.dr.tvplayer "DR1"
atv-shortcuts find dk.dr.tvplayer dr1 --test --save DR1

Find looks in these places and ranks the results (HIGH/MEDIUM/LOW):

SAVED        Shortcuts you already saved.
KNOWN        Built-in profile entries (a hint, not proof: press Test).
TV_PROVIDER  Titles + intent URIs the app publishes to the TV home screen (Watch Next / channels).
LOGCAT       URLs in the app's log near your term, including links rebuilt from its own API calls
             (e.g. an API call with path=/kanal/dr1_20875 becomes https://www.dr.dk/drtv/kanal/dr1_20875).
APK          With --scan-code only: URL strings found in the app's code (slow, rarely useful).

Each URL is checked with cmd package resolve-activity: if Android would not route it to the app it is demoted. The final proof is always Test (--test).

If the app never exposes the item (content ids usually live on the app's servers), use Learn. Open the app, then:

atv-shortcuts learn dk.dr.tvplayer --query "DR1" --seconds 90 --save-best DR1

Move to what you want on the TV and open it. Learn records what was focused, what the app logged, and which screen opened, then reports links labelled with the on-screen name. The same two modes are on the GUI Find page (Search, Start Learning / Stop Learning).

Watch transitions:

atv-shortcuts watch

Test a deep link:

atv-shortcuts test dk.dr.tvplayer "https://www.dr.dk/drtv/kanal/dr1_20875"

Test with explicit activity and verification:

atv-shortcuts test dk.dr.tvplayer "https://www.dr.dk/drtv/kanal/dr1_20875" --activity axis.androidtv.sdk.app.MainActivity --verify

Save and launch:

atv-shortcuts save DR1 dk.dr.tvplayer "https://www.dr.dk/drtv/kanal/dr1_20875" --activity axis.androidtv.sdk.app.MainActivity --expected-result-activity axis.androidtv.sdk.app.player.PlayerActivity
atv-shortcuts launch DR1 --verify

Export:

atv-shortcuts export --format tvQuickActions DR1
atv-shortcuts export --format adb
atv-shortcuts export --format json

Verification Statuses

  • OPENED_CONTENT: strong evidence that content/player screen opened.
  • OPENED_APP: target app opened, but not the expected content screen.
  • FAILED: command or resolution failed.
  • UNKNOWN: evidence is insufficient.

The app does not treat a successful am start as proof that the intended content opened. It checks the resulting foreground activity and learned/expected player activities.

DRTV Examples

These are examples only, not hard-coded universal assumptions.

Package:
dk.dr.tvplayer

Main TV activity:
axis.androidtv.sdk.app.MainActivity

Observed player activity:
axis.androidtv.sdk.app.player.PlayerActivity

DR1:
https://www.dr.dk/drtv/kanal/dr1_20875

TVA:
https://www.dr.dk/drtv/kanal/192099

Example ADB command:

adb shell am start -a android.intent.action.VIEW -d "https://www.dr.dk/drtv/kanal/dr1_20875" dk.dr.tvplayer

Install DRTV samples:

atv-shortcuts wizard --install-samples

tvQuickActions Export

The export page and CLI produce copyable fields:

Name:
DR1

Type:
Activity

App:
DRTV

Activity:
axis.androidtv.sdk.app.MainActivity

Action:
android.intent.action.VIEW

Data:
https://www.dr.dk/drtv/kanal/dr1_20875

The app does not modify tvQuickActions directly because there is no assumed reliable import method.

Optional Linux systemd User Service

The application works normally without systemd. The service helper is only for maintaining a saved ADB connection.

Install:

mkdir -p ~/.local/bin ~/.config/systemd/user
cp scripts/adb-connect.sh ~/.local/bin/adb-connect.sh
chmod +x ~/.local/bin/adb-connect.sh
cp scripts/adb-tv.service ~/.config/systemd/user/adb-tv.service
systemctl --user daemon-reload
systemctl --user enable --now adb-tv.service

The helper reads the default device from ~/.config/android-tv-shortcut-inspector/config.json and devices.json. You can also override it:

ADB_TV_ADDRESS=192.168.1.50:5555 ~/.local/bin/adb-connect.sh

Packaging

Windows PyInstaller build:

python -m pip install -e .[build]
pyinstaller AndroidTVShortcutInspector.spec

The output folder contains AndroidTVShortcutInspector.exe.

Linux portable build options:

  • Build with PyInstaller on the target distro.
  • Wrap the PyInstaller output in AppImage using your preferred AppImage tooling.
  • Or install with pip install -e . and run android-tv-shortcut-inspector.

Tests

Parser and storage tests do not require a real Android TV:

python -m unittest discover -s tests

Integration testing with a real TV is intentionally manual because ADB availability, pairing state, and installed apps vary by device.

Troubleshooting

ADB missing

  • Add adb/adb.exe to PATH.
  • Or set the custom ADB path in Settings.
  • Or install Google's Android SDK Platform Tools.

UNAUTHORIZED

  • Check the TV screen for an authorization prompt.
  • Revoke USB debugging authorizations and reconnect if needed.

OFFLINE

  • Disconnect/reconnect ADB.
  • Toggle Wireless Debugging.
  • Reboot the TV if ADB is stuck.

PAIRING_REQUIRED

  • Use Pair Device first.
  • Confirm that you are using the pairing port for pair and the ADB port for connect.

Multiple devices connected

  • Choose a default device in Settings or pass --device.

Deep link only opens app home

  • The URI may be accepted by the app but not enough to open content.
  • Use Discover Shortcut and Logcat to find content IDs, URLs, or player transitions.

Architecture Notes

The first release uses standard non-root ADB only. The shortcut and discovery models are intentionally compatible with future additions such as Projectivy export, tvQuickActions direct import, shortcut APK generation, APK static analysis, and richer deep-link discovery.