Skip to content

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.

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_TOKEN
Authorization: Bearer THE_TOKEN

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

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

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

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.

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.
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.
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.
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. null for 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 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.

The same lines go to the Android log under the tag TvPopup, and the player’s own event log under TvPopupExo:

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