JointSpace API Documentation

Introduction to the ambilight interface


The LEDs of the ambilight system are called pixels.

A colour can be set for each pixel by means of an RGB value.

Individual pixels are address by specifying the side (left, top, right, bottom) and pixel number and layer

Per side pixels are numbered clockwise starting from 0. E.g. the pixel on the top left is pixel 0. In a system with four pixels on the right, the bottom pixel on the right side is pixel 3.

In a system with multiple layers, layer 1 contains the pixels projecting colour closest to the frame of the TV. Layer 2 projects colour more outward and so on.


The topology describes the number of pixels on each side and the number of layers.

The ambilight algorithm

The ambilight algorithm calculates the pixel colour values based on measurements from the video displayed on the screen. The algorithm e.g. takes care of smoothing the colour transition between adjacent pixels and between successive scenes. The behaviour of the algorithm is depending on configurable values in the TV menu.

The behaviour of the ambilight algorithm can be observed by reading two sets of pixels.

Pixel cache

The pixel cache contains the custom pixel colour values that are set through the JointSpace API.

How the pixels in the cache are used by the ambilight algorithm depends on the mode.


The ambilight algorithm has three modes:


The JointSpace ambilight API provides methods for following functionality: