Skip to content

Request reference

A popup is shown by sending an HTTP POST with a JSON body to the app’s listener on port 5001:

POST http://TV_IP:5001/notify
Content-Type: application/json

Every field is optional. An empty body {} shows nothing useful, a body with only title shows a text popup, and a body with video shows live video.

{
"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"
}

If an access token is set in the app, the request must carry it, see Access token.

Field Default Meaning
title, message empty Text shown in a caption under the picture, never over it. The title is bold on one line, the message sits below it on up to two lines, and both end in an ellipsis when they do not fit. An empty row is left out, so a popup with only a title, only a message, or neither stays compact.
video empty rtsp:// (login in the address) or http(s):// (HLS or a progressive file). Empty gives a text-only popup. The special value test-pattern shows a color-bar card without any network.
image empty A still picture (JPEG or PNG) as base64 text, with or without a data:image/jpeg;base64, prefix. Shown when video is empty; video wins when both are given. The whole request may be up to 2 MB.
duration settings, 30 Seconds until the popup closes. 1 to 3600.
Field Default Meaning
size settings, medium small, medium, large or fullscreen. Widths are 20%, 33%, 50% and 100% of the screen width. Height follows the video’s shape, except fullscreen, which covers the whole screen and letterboxes the video.
width, height none Explicit size in app pixels, which is normally a 1920x1080 space even on a 4K panel. Overrides size. With only one of them, the other follows size (width) or the video’s shape (height). A fixed width and height letterbox the video inside the window. Values above the screen size are capped.
corner settings, top_right top_left, top_right, bottom_left, bottom_right or center. Fullscreen ignores it.
Field Default Meaning
mute settings, false Skips the camera’s audio track entirely.
other_audio keep What to ask other apps to do with their sound while the popup plays: keep, duck (lower the volume) or pause (stop). Uses Android audio focus, so an app can ignore it, see Sound from other apps. Not used when mute is true. The response shows audio_focus true or false.

These fields are described in full under Interactive popups.

Field Default Meaning
interactive settings, false The popup takes the remote while it shows.
videos none Several cameras the viewer can switch between: [{"title": "Front Door", "video": "rtsp://..."}, ...]. Up to 8. Needs interactive.
actions none Buttons: [{"id": "open", "label": "Open gate", "close": true}, ...]. Up to 4. Needs interactive.
snooze_key none Names the source of the popup. Adds a Snooze button, and while the key is snoozed, requests with the same key are not shown.
snooze_minutes 15 What the Snooze button suppresses snooze_key for. 1 to 1440.
Field Default Meaning
wait false Hold the HTTP response until the first frame or an error, and return the timings in it (up to 20 seconds).
wait_for_end false Hold the HTTP response until the popup has closed (up to an hour), and return its final result: end_reason, action and the rest. Meant for interactive popups. The caller’s HTTP timeout must be longer than the popup will live.
Field Default Meaning
decoder software software, hardware or auto, see Video decoder.
surface surface texture switches to a TextureView, to try if a TV composes the picture badly.
buffer_ms 0 Media buffered before playback starts. Raise it if the picture stutters.

The response is JSON: the popup’s stats with "ok": true. Without wait it comes back at once with only what is known so far. Errors look like {"ok": false, "error": "..."}.

Status When
200 The request was accepted. Also when the popup was suppressed by a snooze, see Snooze.
400 The body is not valid JSON, a video address could never play, or videos or actions is not a list.
401 An access token is set and the request has none, or the wrong one.
403 The overlay permission is missing. The error text holds the adb command that grants it.

The app is forgiving on purpose: a mistake in a request should cost a wrong corner, never a missing popup.

  • Unknown fields are ignored.
  • JSON null counts as “not given”.
  • Numbers and booleans sent as text ("30", "true") are accepted.
  • Choice words (size, corner, decoder, other_audio) are case-insensitive and treat - and _ alike, so Top-Right works.
  • An unknown choice word does not fail the request: the default is used and the response carries "warnings": [...].
  • A field of the wrong type is treated the same way: the default is used and a warning says which field and what type was received. This covers numbers and booleans that are not numbers or booleans ("duration": "soon", "mute": "yes"), a number outside its range (clamped), text fields given an object or array, and an unknown surface. A warning names the type, never the value, so a camera login cannot leak into it.
  • videos and actions must be JSON arrays. An object keyed by consecutive numbers from 1 or 0 ({"1": {...}, "2": {...}}, what a Lua-style encoder writes) is accepted and read in numeric order, with a warning that it was not an array. Any other non-array is rejected with HTTP 400, for example videos must be a JSON array, got a string. An entry that is not an object is skipped with a warning.
  • Warnings are returned in the reply, kept as warnings in that popup’s stats record, and written to the device log with camera logins masked.
  • A video that does not start with rtsp://, rtspt://, http:// or https:// (and is not test-pattern) is rejected with HTTP 400, since it could never play.
  • RTSP is played with RTP over TCP.
  • An image lets the caller fetch a camera snapshot itself, so the camera login never reaches the TV. The popup takes the picture’s shape, the same way it takes a video’s. Data that is not a picture Android can read still shows the popup, with error_text: "Picture could not be read".
  • A request uses video or videos, never both: when videos has at least one usable entry it wins and video is ignored, so a sender can give both for older app versions.
  • A stream that fails to connect or drops is retried once after half a second. A wrong login or a missing stream is not retried.
  • An unreachable camera gives up after 4 seconds per attempt.
  • A failed popup shows the reason in the middle of the popup for up to 10 seconds, then closes.
  • A new request replaces the popup that is showing. The replaced popup ends with end_reason: "replaced", and a caller waiting on it is released.
  • A request sent while the TV is in standby is accepted, but the popup does not turn the screen on, so nothing is seen.

duck and pause work through Android audio focus: the popup asks, and the app that is playing decides. Many apps honor the request, for example YouTube. Some never take part in audio focus and so neither lower their volume nor pause; the Tablo app is one. Android gives an app no way to lower or pause one specific other app, so there is nothing the popup can do about an app that ignores the request.

The response and the stats show audio_focus true or false, which says whether Android granted the focus, not whether the other app reacted.

TVs have very few hardware video decoders, and some have effectively one. A popup that takes it either interrupts the app underneath or loses the decoder to it.

  • software (default): never touches the hardware decoder. It has played a 1600x1200 camera stream over a streaming app without stopping that app.
  • hardware: always the hardware decoder. Faster to start, and it fights the app underneath for the decoder.
  • auto (experimental): hardware only when no other app is playing media, otherwise software. Android cannot say which decoders are busy, so “something is playing audio” stands in for it. If the hardware decoder then fails or is taken, the popup restarts on the software decoder without showing an error. It cannot be made fully safe: an app that shows video without sound holds a decoder too, and taking it would interrupt that video.

Use software unless the hardware decoder is needed.