Skip to content

Web Dashboard

Jump to bottom
github-actions[bot] edited this page Oct 11, 2026 · 10 revisions

Web Dashboard

TinyPPI can serve everything the overlay shows to a browser on your phone, tablet or laptop, so the readings can be followed while the picture on the TV stays untouched. On top of the readings the dashboard has a live luminance chart, an event history, a remote, VS10 switching, and the film and series library with continue watching.

The page is served entirely by the add-on: nothing is loaded from the internet, and it works on a box without any outside connection.

Contents

Switching it on

  1. Settings → Dashboard → Enable web dashboard (off by default).

  2. Settings → Dashboard → Show address and token shows the address to open and the access token — handy when you are standing in front of the TV with the phone in your hand.

  3. Open the address on any device on the same network:

    http://<box-ip>:8099/

The port is set under Settings → Dashboard → Port (1024–65535, default 8099). Leave 8080 alone; Kodi's own web server usually has it.

Do not forward the dashboard's port to the internet. It is meant for a home network. See Dashboard Security.

The server listens on IPv4 and IPv6. Reading without the token works for devices on the home network only; anything else is asked for the token.

On a phone the page can be added to the home screen; it then opens like an app, with the status bar in the theme's color.

The row labels come from Kodi's own string table, so the dashboard speaks the same language as the overlay.

The tabs

The page has six tabs, switched from a floating bar of icons at the foot of the screen:

Tab Address What is on it Shown
Live /#live Now playing, transport controls, VS10 output and every reading of the overlay always
Metadata /#metadata Active picture area, L1 luminance chart, the full Dolby Vision metadata list only while a Dolby Vision title plays (and Show the Dolby Vision metadata view is on)
Films /#films Continue watching (films), recently added, unwatched films, the whole film library when the film library is offered
Series /#series Continue watching (episodes), recently updated series, series with unwatched episodes, the whole series library when the series library is offered
History /#history Metrics, chart and events of the playing title — or, for ten minutes after the credits, of the one that just ended always
Settings /#settings Theme, access token, copy report always
  • The address remembers the tab, so a bookmark or a reload comes back to it, and each device reopens the tab it was left on.
  • A page that is on the Metadata tab when the Dolby Vision title ends goes back to Live.
  • The tab bar shows icons only; each key names its tab on hover and to screen readers. Like the TinyPPI app's bar, it steps out of the way after three seconds without interaction and returns with the next touch, scroll, key or pointer movement.
  • The top bar carries the name, the version and the connection light (Connected, Connecting…, Disconnected).
  • http://<box-ip>:8099/metadata — the address of the old stand-alone metadata page — still works and lands on the Metadata tab.

Live

Now playing — the poster, title, year and genre, the file name (only when the overlay's Show file name is on), elapsed time, progress and the time the title ends at.

Format badges — the same badges the TinyPPI app draws under the title:

  • a picture row: resolution, HDR format with the Dolby Vision profile and layer, a conversion such as DV → HDR10, IMAX;
  • a sound row: codec, Atmos or DTS:X, channel layout.

VS10 output — the current output and the modes that can be switched to (see below).

Every row of the overlay, grouped as on screen: Video, Processing, Audio, HDR static metadata, Dolby Vision, Metadata and System. A reading that just moved is highlighted the same way the overlay highlights it.

The remote sits on this tab too (see below).

With nothing playing the tab says "Nothing is playing — Start a video on the box and everything it carries appears here."

What a source cannot carry is left out rather than shown empty: the peak and average tiles, the luminance chart, the active-area box and both metadata sections come from the Dolby Vision RPU and appear only for Dolby Vision; the HDR static metadata group is left out for SDR. That is the same rule the overlay follows.

Metadata

Only while a Dolby Vision title plays.

  • Active picture area — the L5 active area the RPU declares, drawn to scale inside the coded frame: the letterbox as the stream describes it, changing with the scene on an IMAX Enhanced title.
  • Frame luminance (L1) — the peak and frame average on a logarithmic scale, over the last 1 min, the last 10 min or the whole title. The add-on samples from the start of playback, so a page opened halfway through a film gets the part it missed instead of starting from empty.
  • The Dolby Vision metadata list — the same list as the on-screen metadata view: configuration record, the RPU from its header through L255, the composer's reshaping curves, the trim passes and the static SEIs. It stays live, highlights changed readings, and flows into two or three columns on a wide screen without breaking a section across columns.

The list is the largest thing the dashboard sends. It can be switched off under Settings → Dashboard → Show the Dolby Vision metadata view — the first thing to turn off on a slow network.

History

The figures of the playing title:

  • Metrics — player cache, current frame rate, warning count, and how often the output or a playback track was switched.
  • Luminance chart (Dolby Vision) — as on the Metadata tab.
  • Events — a timestamped list of what is worth knowing about. A long list scrolls inside its card.
Event Recorded when
VS10 output the output is switched to or from Dolby Vision (counts as a switch)
Display mode the HDMI display mode changes (switch)
Audio track the selected audio track changes (switch)
Subtitle the selected subtitle changes (switch)
Frame rate the input frame rate changes
Temperature the CPU reaches 75 °C (warning)
Processor the CPU reaches full load (warning)

The history keeps one sample per second for the chart (up to the last hour) and the last 60 events. Track changes are recorded only once they have been stable for 1.5 s, dated from the moment they started.

What the last title came to — for ten minutes after playback ends the page keeps the film that just finished: a card with its switch and warning totals, and its events under it. Those figures matter most once a film is over, which is exactly when they used to be thrown away.

Films

The film library: every film in Kodi's video database as a wall of posters, in the order Kodi files them. A tap opens the title dialog.

  • A film left half-watched carries a progress bar along the bottom of its poster and is resumed where it was.
  • A film already seen wears a tick in the corner.
  • The IMDb rating — or TMDb where IMDb has none — sits in the opposite corner; neither, no badge.
  • Under the title: the year and the running time.
  • A search box narrows the wall as you type; the cross in it clears it.

The tab is there whether or not anything is playing — lining up what comes next from the phone halfway through a film is a fair thing to want. A search still being typed, or a show open on the Series tab, survives a film starting underneath.

Posters are fetched small. A tile on a phone is about 120 px wide, while the scraped poster is often 2000 px. Kodi already keeps a smaller copy of everything it has drawn, so walls are served from Kodi's texture cache (falling back to the original only when the cache has just been cleared). Posters are fetched as they scroll into view, and each crosses the network once: its address carries the picture's own tag, so the browser keeps it.

It keeps itself up to date. Every snapshot carries the library's version, which moves whenever what the shelves would show moves — a film watched to the end, one stopped in the middle, a scan that added something. A page left open all evening re-reads the list the moment it goes out of date. A re-read that finds nothing new costs one validator request and leaves the wall, the search box and the open show exactly as they were. A change made in Kodi's own windows reaches the page about two seconds later.

The cards arrive open and fold away under their headings (with the number of titles beside them); each device remembers how they were left.

Series

The same wall for what Kodi knows as TV shows, with one level more:

  • Each poster shows how many episodes are still unwatched, in the corner a watched film wears its tick; a show seen right through wears the tick. Ratings as on the film wall.
  • A tap on a series opens the title dialog; Open shows its episodes in the order they were made, each season folded under its own heading (season number, episode count and total running time). Specials have their own heading.
  • A tap opens a season; a tap on an episode opens its dialog.
  • The way back to the wall is at the top of the card, one tap away however far down you scrolled.
  • A half-watched episode carries the same progress bar, and each row shows the episode's running time.

The seasons arrive folded because a show that ran nine years is several hundred rows; folded, it is a dozen lines, and a still inside a folded season is never fetched. A show's episodes are only read when the show is opened — a house with ninety series would otherwise send every episode of all of them to draw ninety posters.

Continue watching and recently added

At the top of the Films and Series tabs:

Row Contents
Continue watching Films (respectively episodes) stopped part-way, the last one seen first, up to 30. Read with Kodi's own in progress filter. An episode shows its show's poster with the episode under the name.
Recently added The 10 films that arrived last, and the 10 series that gained an episode last (Kodi dates a series by its newest episode), newest first.
Unwatched films / Unwatched series Only what is still unwatched: films without a tick, series with an episode waiting.

Each is a row that scrolls sideways. A row with nothing in it is not shown. The full walls (Films, All series) follow underneath.

Play, resume and watched marks

A tap on a film, series or episode — on a wall or in a row — opens a dialog:

Option Shown for Effect
Play / Resume films, episodes Starts it on the box; Resume where Kodi has a resume point.
Open series Shows its episodes (a series itself cannot be played).
Play from the beginning stopped part-way Starts from the top, without the resume question on the TV.
Clear resume point stopped part-way Forgets where it got to (taking it off Continue watching), leaving watched/unwatched as it was.
Mark as watched all Writes a play count and removes the resume point — as Kodi's context menu does. A series marks every episode.
Mark as unwatched all Removes the play count. A series marks every episode.

All of these need the access token and Allow VS10 switching from the dashboard.

Kodi writes where a title got to slightly after it reports that playback stopped (and announces nothing when it only wrote a resume point), so the lists are refreshed a moment after a stop rather than at the stop itself.

The remote

On the Live tab, under the progress bar, in two rows:

Row Buttons
First Back and forward by 10 s, 1 min and 10 min
Second Previous chapter · Play / Pause · Volume down · Mute · Volume up · Stop · Next chapter

Under them: a picker for the audio track and one for the subtitles (including Off). Tapping the progress bar seeks there; with the bar focused, the arrow keys nudge it 10 s.

  • Every button goes through Kodi's JSON-RPC into the running player, and the page only offers what the player reports: a file with one audio track has no audio picker; without chapters the chapter keys are dimmed rather than seeking a big step instead.
  • On live TV the progress bar is the broadcast (EPG event), and seeking is done relative to it.
  • Volume steps rather than slides — it is sent as the same volume up / down / mute actions a remote sends. A box whose CEC adapter forwards volume passes them to the amplifier or soundbar; otherwise Kodi's own mixer reacts. CEC has no "set to 40" command, and Kodi's own volume number stands still while the amplifier changes, so no level is displayed.

The remote needs the token, and it is not drawn at all with Allow VS10 switching from the dashboard off.

Switching VS10 from the browser

With Allow VS10 switching from the dashboard on (the default), the Live tab shows the output modes that apply to the playing source — the same set as the on-screen VS10 dialog, SDR sources included — and a tap applies one. The switch takes exactly the path a run_mode keymap takes, native VS10 actions included.

  • A switch takes a few seconds. Taps arriving meanwhile are not queued: the last one replaces any still waiting.
  • HDR10+ and HLG sources, and Dolby Vision titles carrying HDR10+, have no VS10 modes; the whole VS10 card, output line included, is hidden for them.
  • Switching always requires the access token, whatever the reading setting says.

Settings tab

  • Theme — Dark, Dark (adaptive) or Midnight, and the adaptive intensity (see Themes).
  • Access token — the token this device holds, all but its last two characters hidden, and a key to enter a new one.
  • Copy report — copies everything as plain text, ready to paste into a forum post: the rows, what the title added up to, and the events. With nothing playing it copies the report of the title that just finished.
  • A second key beside it copies the Dolby Vision metadata list.

A key with nothing to copy is dimmed.

Themes

Three themes, all dark — this is watched in the room the projector is in:

Theme Look
Dark The plain theme.
Dark (adaptive) What a first visit gets: the same page, with the now-playing card taking its color from the poster. The artwork is read region by region, and the one color that stands for it best is drawn across the card as a broad glow — strongest beside the poster, gone well before the card's foot. How much color survives is worked out per film against the contrast the text needs: a dark poster keeps nearly all of it, a bright one is held back. Other cards keep their plain surfaces but take the film's accent for headings, badges, buttons and the chart's traces. Intensity: Subtle, Standard or Strong. A title without a poster looks like plain Dark.
Midnight Deeper and bluer, for a room with nothing else lit.

The choice is stored in the browser, per device, applied before the first paint (no flash of the wrong theme) and never sent to the box.

Layout on phones and desktops

  • Phone: one column, read top to bottom — what is playing, every reading, then figures, charts and events.
  • Laptop / tablet held sideways: two columns — what is playing down the left, what it has come to down the right — with the readings full width beneath, as many cards per row as fit.

It is the same page folded differently: nothing is hidden by the wide layout or added by the narrow one. Every panel below the film folds away, and each device remembers which were open — a second screen on a shelf can be trimmed to the two or three readings you watch for.

What it costs the box

A second screen often stays open for a whole film, so the dashboard is built not to be felt:

Design Effect
Connects as it loads The live stream opens together with the page, not after the translations.
Only what moved is sent A browser gets one full snapshot on connect, then — five times a second — only the readings that changed: a few dozen bytes on a still scene, instead of tens of kilobytes.
Hidden pages disconnect Lock the phone or switch browser tabs and the stream is dropped; come back and it reconnects at once. Saves the phone's battery and one of the six stream slots.
Nothing is built for nobody With no page connected the box builds no snapshot at all; once a second it only records what the history needs (chart sample, events).
One builder for all pages Five open tabs cost the same as one.
Static files are cached Page files are sent compressed with a validator; a second visit fetches almost nothing. The poster is fetched once per film, from Kodi's texture cache.
Library scans are coalesced Kodi announces every item a scan adds. The box waits until the scan pauses for 2 s (or 10 s have passed on a long one) and drops its lists once. Two pages asking for the same list at once share one database read.
A full server says so A seventh device sees "Too many connections" instead of a silent Disconnected, and takes the first slot that frees.

Dashboard settings

All under Settings → Dashboard:

Setting Default Effect
Enable web dashboard Off Starts or stops the server. Applied immediately — no restart needed.
Port 8099 Listening port (1024–65535). Out-of-range values fall back to 8099.
Show address and token — Shows the address and the current token.
Access token generated The key the page asks for. Created automatically (8 characters) the first time it is needed; can also be typed in.
Generate a new token — Replaces the token; every browser with the old one has to enter the new one.
Show the Dolby Vision metadata view On Adds the Metadata tab's full list.
Show the film library On Offers the Films tab and film rows. Needs Allow VS10 switching too.
Show the series library On Offers the Series tab and episode rows. Needs Allow VS10 switching too.
Require the token for reading too Off Asks for the token before showing anything at all.
Allow VS10 switching from the dashboard On Enables VS10 switching, the remote, playback and watched marks from the browser. Off makes the dashboard read-only.

Security details — the token, the lockout, trusted host names and the headers — are on Dashboard Security. The endpoints are documented on Dashboard HTTP API.

TinyPPI (script.tinyppi) · Source · Issues · Code: AGPL-3.0-or-later · Name, logo and artwork: all rights reserved

TinyPPI Wiki

User guide

Web dashboard

Reference

Developers

Project

Clone this wiki locally