- Python 98.9%
- Shell 0.9%
- Batchfile 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- 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]> |
||
| scripts | ||
| src/atv_shortcuts | ||
| tests | ||
| .gitignore | ||
| AndroidTVShortcutInspector.spec | ||
| install.bat | ||
| install.sh | ||
| pyproject.toml | ||
| README.md | ||
| run.bat | ||
| run.sh | ||
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 TVorBedroom 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_VIEWdeep 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
adbis 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.exeavailable inPATH- 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
- Enable Developer Options on the TV.
- Enable USB debugging or Wireless Debugging.
- If using modern Wireless Debugging, note both ports:
- pairing port
- normal ADB connection port
- Pair first, then connect.
The pairing port and the normal ADB port are not assumed to be the same.
Wireless Debugging
GUI:
- Open
Devices. - Click
Pair Device. - Enter IP address, pairing port, ADB port, and pairing code.
- 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 runandroid-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.exetoPATH. - 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 Devicefirst. - Confirm that you are using the pairing port for
pairand the ADB port forconnect.
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.