Skip to content

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.

  • 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. On the TV open Settings > System > About.
  2. Move to “Android TV OS build” and press OK seven times, until the TV says you are a developer.
  3. 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.

From the computer:

Terminal window
adb connect TV_IP:5555

The 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:

Terminal window
adb devices
adb install -r tv-camera-popup.apk

If 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.

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.

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:

Terminal window
adb shell appops set com.workedge.tvpopup SYSTEM_ALERT_WINDOW allow

Without 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.

Terminal window
curl http://TV_IP:5001/status

The 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.

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:

Terminal window
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:

Terminal window
$body = @{ title = 'Front Door'; message = 'Test'; video = 'test-pattern'; duration = 15 } | ConvertTo-Json
Invoke-RestMethod -Uri http://TV_IP:5001/notify -Method Post -ContentType 'application/json' -Body $body

A popup with color bars appears in the top right corner for 15 seconds.

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": true holds 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.

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.