Other endpoints
The listener is plain HTTP on port 5001.
All bodies are JSON, every endpoint answers JSON, and errors look like {"ok": false, "error": "..."}.
| Endpoint | Does |
|---|---|
POST /notify |
Shows a popup. |
POST /dismiss |
Closes the popup that is showing. |
GET /status |
A cheap health check. |
GET /stats |
The last 20 popups with timings and results. |
GET /snooze |
Lists what is snoozed. |
POST /unsnooze |
Clears snoozes. |
Access token
Section titled “Access token”Off by default. When a token is set on the app’s settings screen, every endpoint requires it, sent as either header:
X-Access-Token: THE_TOKENAuthorization: Bearer THE_TOKENA missing or wrong token gets HTTP 401.
The token travels in clear text over the local network, like everything else here. Treat it as a guard against accidents and casual neighbors, not against someone who can watch the network.
GET /status
Section titled “GET /status”{"ok": true, "app": "TV Camera Popup", "version": "0.4.0", "overlay_permission": true, "showing": false, "token_required": false}Use it to tell a TV that is off (no answer) from an app that is running but missing its permission.
POST /dismiss
Section titled “POST /dismiss”Closes the popup that is showing, interactive or not.
Answers {"ok": true, "dismissed": true}, or "dismissed": false if nothing was showing.
No body needed.
GET /snooze and POST /unsnooze
Section titled “GET /snooze and POST /unsnooze”GET /snooze lists what is snoozed:
{"ok": true, "snoozes": [{"snooze_key": "front_door", "remaining_s": 840}]}POST /unsnooze clears snoozes and answers {"ok": true, "cleared": 1}, the number that were still active.
Body {"snooze_key": "front_door"} clears that key; no body, or no snooze_key, clears every snooze.
Clearing a key that is not snoozed is not an error ("cleared": 0).
See Snooze for how a snooze starts.
GET /stats
Section titled “GET /stats”Returns the last 20 popups as {"ok": true, "popups": [...]}, with timings in milliseconds since the request arrived.
The reply to POST /notify is the same record for that one popup.
Timings and playback
Section titled “Timings and playback”| Key | Meaning |
|---|---|
first_frame_ms |
The number that matters: request to first rendered picture. |
overlay_shown_ms, prepare_called_ms, video_decoder_ready_ms, ready_ms |
Steps on the way. |
audio_playing_ms |
Appears only once sound is really coming out. |
audio_focus |
Whether Android granted the audio focus asked for with other_audio. |
video_decoder, video_format, video_size, audio_decoder, audio_format |
What is playing. |
decoder_choice |
software or hardware, the decoder the player started with (the last one after a fallback). |
fell_back_to_software |
Present when decoder: auto lost the hardware decoder; holds the player’s error name. |
retried_after |
Present when the stream was retried once; holds the reason. |
players_created |
Players started for the popup: 1 normally, more only after a retry or decoder fallback. Switching cameras and muting never add one. |
dropped_frames |
Frames the player dropped. |
image_bytes, image_size |
For an image popup: the size of the picture data and its width x height. first_frame_ms is when it was shown. |
warnings |
What the app corrected in the request, see How fields are read. |
Errors
Section titled “Errors”| Key | Meaning |
|---|---|
error |
The player’s error code and the chain of causes. For logs, not for people. |
error_text |
Short reason also shown on the TV: Camera refused the login, Camera not reachable, Camera has no stream at that address, TV video decoder is busy, Unsupported video stream, Stream ended, Picture could not be read. |
How the popup ended
Section titled “How the popup ended”| Key | Meaning |
|---|---|
end_reason |
Why the popup closed, see the table below. |
interactive |
true when the popup took the remote. Always present. |
interacted |
Present and true once the viewer pressed any key on an interactive popup. |
action, actions_pressed |
The id of the last action button pressed, and every id pressed in order (a list), also those that left the popup open. Present once a button was pressed. |
muted |
Interactive video popup: whether the camera sound is off right now. |
expanded |
Present once the viewer used OK on the picture; true while expanded. |
snooze_key, snooze_minutes |
Present when the viewer pressed Snooze. |
end_reason |
Meaning |
|---|---|
duration |
The countdown ran out. |
dismissed |
POST /dismiss. |
replaced |
A newer request took its place. |
service stopped |
The listener stopped. |
dismissed_by_user |
Interactive: the viewer pressed Back. |
dismissed_by_home |
Interactive: the viewer pressed Home or Recents. |
dismissed_by_focus_loss |
Interactive: another window took the remote. |
action |
Interactive: an action button closed the popup. |
snoozed |
Interactive: the viewer pressed Snooze. |
Several cameras
Section titled “Several cameras”| Key | Meaning |
|---|---|
camera_index, camera_switches |
Which camera is showing (0 is the first in videos) and how many times the viewer switched. video shows the current camera. |
camera_switch_ms |
Time from the last camera switch to its first frame. |
cameras |
Present when the request used videos: one record per entry, in list order, to pick out a slow or failing camera. |
One cameras record, updated live while the popup shows:
{"index": 1, "title": "Garage", "video": "rtsp://***@CAMERA_IP/live", "shown": 3, "frame_ms": [900, null, 2500], "frame_first_ms": 900, "frame_last_ms": 2500, "frame_worst_ms": 2500, "failures": 1, "error": "ERROR_CODE_IO_UNSPECIFIED | ..."}shown: how many times the camera came on screen (the first showing counts), also when it never got a picture.frame_ms: one entry per showing, in order: milliseconds from the camera coming on screen to its first picture, including any automatic retry.nullfor a showing that never got a picture, for instance because the viewer switched away or it failed.frame_first_ms,frame_last_ms,frame_worst_ms: the first, the latest and the slowest of the pictures that did arrive. Absent while there is none.failures: how many errors the camera had, also those the popup recovered from by retrying.error: the latest error text, absent when there was none.
Camera logins are masked
Section titled “Camera logins are masked”Camera logins are replaced by *** in every response, in the stats and in the device log.
Error messages are masked the same way, including parser errors that quote the request body.
Device log
Section titled “Device log”The same lines go to the Android log under the tag TvPopup, and the player’s own event log under TvPopupExo:
adb logcat -s TvPopup:* TvPopupExo:*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