Custom renderers

Docs Documentation

Custom renderers

For partners: replace the part of the player that draws, with your own renderer.html — what it is, the render protocol in short, and how to upload, activate and roll back.

Every Wunderframe screen runs two parts. The host — the Android TV, desktop, Raspberry Pi or browser player — does the work: pairing, schedules, downloads, offline storage, keeping a wall in step, reports and commands. The renderer draws: one HTML page that the host tells what to show.

Wunderframe ships a renderer that draws every block. A workspace may upload its own, to restyle blocks, add new ones, or draw programs in a completely different way. Everything else stays: the editor, the Live board, walls, offline, publishing and Devices work exactly the same.

The render protocol in short

  • Messages. Host and renderer exchange small JSON messages with a type and the protocol version v: 1. The renderer finds its host when it starts, whichever player it runs in.
  • The conversation. The renderer says ready. The host sends load with a program; the renderer prepares it off-screen and answers prepared. The host sends play; the renderer shows it and reports each shot with shot. New data arrives as data, the next program as another load.
  • The timeline rule. What you draw must be a pure function of the timeline position the host gives you. That is how every panel of a wall shows the same frame.
  • No network of your own. The renderer gets the program, the data and local addresses for every picture and video. It never gets a key or a password, and it asks the host to fetch anything else.
  • Video and sound on TV players play in native layers below and above your page; the host tells you which layer to draw.

Rules for the file

  • One self-contained HTML file of at most 8 MB. Scripts, styles and fonts go inside it.
  • No scripts, styles or frames loaded from elsewhere, and no <iframe>.
  • No secrets in the file: its download address is public, like the stock renderer’s.

Upload, test and activate

Uploading, activating and rolling back are for workspace owners, in Settings → Player.

Settings → Player: the two example downloads, what the screens run now, and Upload renderer.html.

Settings → Player: an explanation of the player renderer with Minimal example renderer and Stock renderer downloads, Screens run the stock renderer, Your own renderer with an Upload renderer.html button, and Live monitoring with the small-dot option.

Settings → Player: the two example downloads, what the screens run now, and Upload renderer.html.

  1. Start from an example

    Minimal example renderer downloads a small working renderer in plain JavaScript. Stock renderer downloads the one Wunderframe ships, to see what it does.

  2. Upload renderer.html

    The file is checked against the rules above. A file that breaks one is refused with the reason.

  3. Pass the self-test

    Wunderframe runs your file in a sandbox with a short test program: two four-second shots, a picture and a caption each. Your renderer must answer ready, prepared and its first shot within 20 seconds, with no network. The result shows how fast each answer came.

  4. Activate

    Activate is possible only after a pass. Tick Tell every screen to switch now, or let screens switch at their next reload.

Watch it on the screens

Settings → Player counts how many screens run your renderer and how many fell back to the stock one. On Devices, each screen says which renderer it runs — Custom acme-2.1.0, Stock, or Stock (fallback) with the reason.

A screen never goes black because of a renderer. If yours does not say ready within 20 seconds, crashes, speaks another protocol version or fails to download, that screen runs the stock renderer and reports why.

Roll back

Activating makes the renderer it replaces the rollback target. Roll back to … goes back to it; Use the stock renderer goes back to Wunderframe’s and keeps yours ready to activate again. Both ask first, and both can tell every screen to switch now.