Skip to content

Troubleshooting

Start with the health check. It separates “the TV or app is not reachable” from everything else:

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

Then send a request with "wait": true, which returns the result of the popup, including error_text when something failed:

Terminal window
curl -X POST http://TV_IP:5001/notify \
-H "Content-Type: application/json" \
-d '{"title": "Test", "video": "test-pattern", "duration": 10, "wait": true}'

If the color-bar test card shows, the app, the permission and the placement are fine, and the problem is with the camera address or the network between the TV and the camera.

What you see Likely cause What to do
No answer on port 5001 The app is not installed, was never opened after installing, or the address is wrong. Open the app once from the TV’s app list, and check the address on its settings screen.
No answer, and the TV is in standby A TV in deep standby may be off the network. Wake the TV and try again.
HTTP 403 The overlay permission is missing. Grant it with adb, see Help.
HTTP 401 An access token is set in the app. Send the token, see Access token.
HTTP 400 The body is not valid JSON, or video does not start with rtsp://, rtspt://, http:// or https://. Read the error text in the answer.
HTTP 200 with "snoozed": true The viewer snoozed this snooze_key. Wait, or clear it with POST /unsnooze.
HTTP 200, nothing visible, no error The TV is in standby. The popup does not turn the screen on. Turn the TV on first.
A popup appears, then is gone at once A newer request replaced it, or something sent POST /dismiss. Look at end_reason in GET /stats.

The popup shows an error instead of a picture

Section titled “The popup shows an error instead of a picture”

The popup shows a short reason in the middle for up to 10 seconds, then closes. The same text is in error_text in the response and the stats.

Error text Likely cause
Camera refused the login The user name or password in the address is wrong, or contains @, : or / that must be percent-encoded.
Camera not reachable The TV cannot reach the camera’s address. The app gives up after 4 seconds per attempt. Check that the TV and the camera are on networks that can reach each other.
Camera has no stream at that address The path in the RTSP address is wrong.
TV video decoder is busy Another app holds the TV’s hardware decoder. Use the default "decoder": "software".
Unsupported video stream The camera sends a video format the app cannot play. Set the camera’s stream to H.264.
Stream ended The camera or the network closed the stream. It was retried once already.
Picture could not be read The image data is not a JPEG or PNG that Android can read.

Test the camera address in a desktop player such as VLC from a computer on the same network. If it does not play there, it will not play on the TV.

  • One to two seconds before the picture appears. The app waits for the camera’s next keyframe. Lower the keyframe interval in the camera’s settings; one second works well.
  • Stutter. Raise buffer_ms, for example to 500.
  • The picture is drawn in the wrong place or with artifacts. Try "surface": "texture".
  • The app underneath stops or goes black when the popup appears. The popup took the TV’s hardware decoder. Use "decoder": "software", which is the default.
  • mute is true in the request, or “camera sound muted” is on in the app’s settings.
  • The camera sends no audio track, or an audio format the TV cannot decode. audio_format in the stats shows what was found, and audio_playing_ms appears only once sound is really coming out.

"other_audio": "duck" and "pause" ask the app that is playing to lower or stop its sound, through Android audio focus. The other app decides whether to listen.

  • Apps that honor audio focus, such as YouTube, lower their volume or pause.
  • Tablo ignores both. The Tablo app never takes part in audio focus, so it neither ducks nor pauses, and its sound keeps playing under the camera’s. Other apps may behave the same way.
  • Android gives an app no way to lower or pause one specific other app, so the popup cannot force it. audio_focus: true in the response means Android granted the focus, not that the other app reacted.
  • other_audio is not used when mute is true.

If the app you watch ignores audio focus, the choices are to mute the popup, or to have your automation lower the TV or receiver volume around the popup.

What you see Cause
The remote does nothing in the popup The request did not set "interactive": true, and “popups use the remote” is off in the app’s settings.
Left and Right do not switch cameras The focus is on a button; press Up to go back to the picture. Or the request has only one camera.
Pressing an action button changes nothing in the house By design: an action button only records its id. The caller reads it and does the work, see Action buttons.
The TV’s input picker shows but cannot be used The TV drew its picker over the popup, which still holds the remote. Press Back first, see Known limits.
A popup does not show after Snooze was pressed That is the snooze. GET /snooze shows what is active.

The listener starts by itself after the TV restarts and after the app is updated, once the app has been opened at least once after it was installed. On a full restart it can take a minute or two before the TV starts it.

If the app does not answer after a restart, open it once from the TV’s app list.

The app writes one line per step to the Android log, with camera logins masked:

Terminal window
adb logcat -s TvPopup:* TvPopupExo:*

Found a bug in the app? See Report a bug.