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/notifyContent-Type: application/jsonEvery 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.
Fields
Section titled “Fields”Content
Section titled “Content”| 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. |
Size and position
Section titled “Size and position”| 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. |
Interactive popups
Section titled “Interactive popups”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. |
Waiting for a result
Section titled “Waiting for a result”| 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. |
Playback tuning
Section titled “Playback tuning”| 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
Section titled “The response”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. |
How fields are read
Section titled “How fields are read”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
nullcounts 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, soTop-Rightworks. - 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 unknownsurface. A warning names the type, never the value, so a camera login cannot leak into it. videosandactionsmust 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 examplevideos 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
warningsin that popup’s stats record, and written to the device log with camera logins masked.
Video and pictures
Section titled “Video and pictures”- A
videothat does not start withrtsp://,rtspt://,http://orhttps://(and is nottest-pattern) is rejected with HTTP 400, since it could never play. - RTSP is played with RTP over TCP.
- An
imagelets 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, witherror_text: "Picture could not be read". - A request uses
videoorvideos, never both: whenvideoshas at least one usable entry it wins andvideois 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.
One popup at a time
Section titled “One popup at a time”- 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.
Sound from other apps
Section titled “Sound from other apps”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.
Video decoder
Section titled “Video decoder”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.
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