Skip to content

Interactive popups

By default a popup is only shown: its window cannot take focus, so the remote keeps controlling the app underneath, and a popup never changes that.

A request with "interactive": true lets the viewer work the popup with the remote instead. The settings screen’s “popups use the remote” switch makes that the default, and a request can still override it with "interactive": false.

While an interactive popup shows it holds the remote. The app underneath keeps playing but cannot be controlled until the popup closes. When the popup closes the remote goes back to that app at once, with the focus where it was.

{
"title": "Front Door",
"message": "Motion",
"interactive": true,
"duration": 30,
"videos": [
{"title": "Front Door", "video": "rtsp://USER:PASSWORD@CAMERA_1_IP:554/live.sdp"},
{"title": "Garage", "video": "rtsp://USER:PASSWORD@CAMERA_2_IP:554/live.sdp"}
],
"actions": [
{"id": "unlock", "label": "Unlock door"},
{"id": "light", "label": "Porch light", "close": false}
],
"snooze_key": "front_door",
"snooze_minutes": 15,
"wait_for_end": true
}

The picture stays as it is. Under it, outside the picture, sits a control bar: a hint line that says what the remote does right now, and a row of buttons. The bar is about 60 pixels tall, so an interactive popup is that much taller than a plain one. Expanded, the picture gives up that strip at the bottom of the screen.

The element with the focus is outlined in white: the whole picture, or one button, which turns white.

Buttons, left to right:

  1. Sound on / Sound off, only for a real video.
  2. The actions, in order.
  3. Snooze, only when snooze_key is given.

Labels are cut with an ellipsis when the popup is narrow, so keep them short (about 12 characters) or use medium or larger.

The picture has the focus when the popup appears. A popup with no picture starts on its first button.

Left and Right do different things on the picture and in the button row, which settles the clash between “switch camera” and “move between buttons”.

Focus Key Does
Picture OK Expand to full screen, or back to the requested size.
Picture Left / Right Previous / next camera (wraps around). Only with more than one camera, otherwise nothing.
Picture Down Move to the first button. Nothing if there are no buttons.
Button Left / Right Move to the neighboring button.
Button OK Press it.
Button Up Back to the picture.
Anywhere Back Close the popup (end_reason: dismissed_by_user). Also when expanded.
Anywhere Home, Recents The system takes the key and goes home. The popup hears it and closes (dismissed_by_home), so that it does not hold the remote over the home screen.
Anywhere Input, guide, or anything else that takes the window focus The popup closes (dismissed_by_focus_loss) instead of lingering over whatever took the remote. A touch outside the popup does the same.

Other keys (volume, media keys, power) are not used by the popup and keep working as usual. A popup with only text and no buttons has nothing to focus, but Back still closes it.

videos lists up to 8 cameras.

"videos": [
{"title": "Front Door", "video": "rtsp://USER:PASSWORD@CAMERA_1_IP:554/live.sdp"},
{"title": "Garage", "video": "rtsp://USER:PASSWORD@CAMERA_2_IP:554/live.sdp"}
]
  • Left and Right on the picture switch to the previous or next camera, wrapping around, and the hint line shows camera 2/3.
  • While a camera has a title, it leads the caption’s title row, as Garage · Front Door.
  • A switch reuses the popup’s single player: it points it at the next stream, so it costs about what the first frame of a fresh popup costs, and fast repeated presses cannot pile up players.
  • Each camera gets a fresh retry after a connection problem.
  • An entry without a video is skipped with a warning; one with an address the app cannot play is HTTP 400, like video.
  • videos on a request that is not interactive shows the first camera only, with a warning.
  • A list may mix real cameras and test-pattern entries. A list of only test-pattern entries is a way to try camera switching without any camera.

The result records each camera separately, see Several cameras.

OK on the picture expands it to the whole screen; OK again returns it to the requested size. While the picture is expanded the countdown is paused, because the viewer asked to watch.

"actions": [
{"id": "unlock", "label": "Unlock door"},
{"id": "light", "label": "Porch light", "close": false}
]

An action does nothing in the app except record its id in the popup’s result (action and actions_pressed). The app never calls anything: there is no callback, webhook or other outbound call.

The caller finds out what was pressed in one of two ways:

  • Send the request with "wait_for_end": true, and read the result when the popup has closed.
  • Poll GET /stats, where the entry of a popup that is still showing already holds what was pressed.

Then the caller does the work: unlock the door, switch the light.

Rules:

  • Pressing an action closes the popup with end_reason: action, unless that action has "close": false. Then the popup stays up, “Pressed: label” shows in the hint line for two seconds, and the id is added to actions_pressed.
  • An entry needs a non-empty id of at most 64 characters; one without is skipped with a warning. Ids may repeat.
  • The label defaults to the id and is cut at 40 characters.
  • At most 4 actions; extra ones are ignored with a warning.

The Sound button switches the camera sound off and on. A request with mute: true starts muted, and the viewer can turn the sound on.

An interactive popup always fetches the camera’s audio track, also with mute: true, and silences it with the volume. An RTSP stream cannot take a left-out track back, so this is what lets the viewer turn the sound on later.

Meant for “stop bothering me about the front door for a while”.

  • Give requests from one source the same snooze_key (any text up to 64 characters, case matters). The popup then has a Snooze button.

  • Pressing it closes the popup (end_reason: snoozed) and snoozes that key for snooze_minutes (1 to 1440, default 15, the number on the button).

  • While a key is snoozed, every POST /notify with that key, interactive or not, is not shown. It gets HTTP 200 and no popup:

    {"ok": true, "shown": false, "snoozed": true, "snooze_key": "front_door", "snooze_remaining_s": 840}

    A request that is shown has no shown or snoozed field. A suppressed request leaves no entry in the stats and does not close the popup that is showing.

  • Requests with another key, or none, are never affected.

  • A snooze ends by itself, or on POST /unsnooze; GET /snooze shows what is active.

  • Snoozes live in memory: restarting the listener (or the TV) forgets them.

  • Only the viewer pressing Snooze starts one; there is no request that snoozes a key from outside.

duration is how long the popup lives without anyone touching it.

  • Every key press starts the countdown over: the popup now lives for the full duration again, and at least 10 seconds, so a duration of 3 does not close under the viewer’s hands.
  • While the picture is expanded the countdown is paused. Making it small again starts it over.
  • A failed stream’s error banner still goes away after 10 seconds, whatever the viewer presses.
  • POST /dismiss and a new request work at any time.

With wait_for_end the reply comes when the popup has really ended, so it can be much later than duration.

  • The app underneath may react to losing window focus, for instance by pausing itself. Most apps do not; this is that app’s choice and cannot be controlled by the popup.
  • Some TV keys are handled by the TV itself before any app sees them, see Known limits.
  • Touch and mouse input outside the popup still reach the app underneath.