Getting started
This page takes a TV from nothing installed to a first popup on screen. It takes about ten minutes and needs a computer on the same network as the TV.
What you need
Section titled “What you need”- A TV or streaming box that runs Android TV or Google TV, Android 8.0 or newer. Samsung and LG TVs run other systems and cannot use the app, see Known limits.
- The TV Camera Popup APK file.
- A computer with
adb, which is part of the Android SDK Platform-Tools. - For live video, a camera with an RTSP address (H.264 video) that plays in a desktop player such as VLC. You do not need a camera for the first test.
In the commands below, replace TV_IP with the address of the TV, found on the TV under Settings > Network & Internet.
1. Turn on debugging on the TV
Section titled “1. Turn on debugging on the TV”- On the TV open Settings > System > About.
- Move to “Android TV OS build” and press OK seven times, until the TV says you are a developer.
- Open Settings > System > Developer options and turn on “USB debugging”. On Sony TVs this also turns on debugging over the network. If the TV shows a separate “Wireless debugging” or “Network debugging” switch, turn that on as well.
Menu names differ a little between TV brands, but the steps are the same.
2. Connect and install
Section titled “2. Connect and install”From the computer:
adb connect TV_IP:5555The TV shows an “Allow USB debugging?” prompt.
Tick “Always allow from this computer” and accept it.
Then check that the TV is listed as device, and install the app:
adb devicesadb install -r tv-camera-popup.apkIf more than one device is connected, add -s TV_IP:5555 after adb in every command, so the command goes to the TV you mean.
3. Open the app once
Section titled “3. Open the app once”Open TV Camera Popup from the TV’s app list. The app starts its listener when it is opened, and from then on by itself after every TV restart and every app update.
The settings screen shows the listener status, the TV’s address and port, and whether the overlay permission is granted.
4. Grant the overlay permission
Section titled “4. Grant the overlay permission”The app needs Android’s “display over other apps” permission to draw a popup over what is playing.
The settings screen has a button that opens the system setting, but many TVs hide that setting, so the reliable way is one adb command:
adb shell appops set com.workedge.tvpopup SYSTEM_ALERT_WINDOW allowWithout the permission the app answers every popup request with HTTP 403 and an error text that names this same command. The Help page has the same steps with more detail.
5. Check that the app is listening
Section titled “5. Check that the app is listening”curl http://TV_IP:5001/statusThe answer looks like this:
{"ok": true, "app": "TV Camera Popup", "version": "0.4.0", "overlay_permission": true, "showing": false, "token_required": false}overlay_permission must be true.
6. Show a first popup
Section titled “6. Show a first popup”The quickest test is the “Show test popup” button on the app’s settings screen. It shows a color-bar card at the default size and position, with no camera and no network involved.
The same test from the computer, as the request a home automation system would send:
curl -X POST http://TV_IP:5001/notify \ -H "Content-Type: application/json" \ -d '{"title": "Front Door", "message": "Test", "video": "test-pattern", "duration": 15}'In Windows PowerShell:
$body = @{ title = 'Front Door'; message = 'Test'; video = 'test-pattern'; duration = 15 } | ConvertTo-JsonInvoke-RestMethod -Uri http://TV_IP:5001/notify -Method Post -ContentType 'application/json' -Body $bodyA popup with color bars appears in the top right corner for 15 seconds.
7. Show a camera
Section titled “7. Show a camera”Replace test-pattern with the camera’s RTSP address, with the login in the address:
{ "title": "Front Door", "message": "Someone is at the door", "video": "rtsp://USER:PASSWORD@CAMERA_IP:554/live.sdp", "duration": 30, "size": "medium", "corner": "top_right", "wait": true}- Characters such as
@,:or/in the user name or password must be percent-encoded in the address (%40,%3A,%2F). "wait": trueholds the answer until the first picture or an error, and returns the timings, which helps while testing.- If the popup shows an error instead of a picture, see Troubleshooting.
Optional: set an access token
Section titled “Optional: set an access token”By default anything on the local network can send a popup. To require a token, open the app’s settings screen and type one, or generate a random one. Every request must then carry it, see Access token.
Next steps
Section titled “Next steps”- Request reference: every field of a popup request.
- Interactive popups: cameras the viewer can cycle, action buttons and snooze.
- Control4 driver integration: build popup support into a Control4 driver.
TV Camera Popup is free and provided as is, without warranty or support. It is an independent project, not affiliated with, endorsed by or sponsored by Control4, Sony or Google; those names are used only to say what the app works with. Privacy policy · Help