Personal tools



From NiftyWiki
Jump to: navigation, search
Home Documentation Download Support Showroom Links


libniftyled is a library to control LED devices using images or video

It's designed to provide a lightweight and versatile framework to...

  • ...combine different LED hardware and different interfaces (USB, RS232, ...) in the same setup using plugins
  • ...provide maximum freedom for software developers when integrating niftyled with other lighting applications
  • ...provide maximum freedom for hardware developers by using a versatile abstraction design
  • ...scale - so big setups can be created with least hardware effort
  • ...minimize the needed firmware complexity
  • ...create new light setups quickly

Pixels are defined from color components by positioning LEDs on a pixmap. By grouping chains of LEDs into tiles (and smaller tiles into larger tiles), large setups can be created from repeating patterns.

When pixels are fed into niftyled, brightness values for each configured LED are extracted and sent serially to the hardware plugin(s) in correct order. This way hardware firmware can be trivial.


  • setup configuration is saved in a standard XML file - configurations can be used with every niftyled application
  • realtime pixel ➙ component (color channel) ➙ light source brightness mapping
  • grouping of light sources into "tiles" so larger clusters can be formed from smaller clusters
  • arbitrary colorspace-conversion using libbabl
  • hardware-plugin API to integrate new hardware
  • application API to quickly develop LED control software


Data flows like this:

Vlc-outputGstreamerLedcapLedcatApplication writing HOWTOCategory:LibniftyledCategory:Libniftyled hardware-pluginsCategory:Libniftyled hardware-pluginsCategory:Libniftyled hardware-pluginsLED-setup XMLniftyled dataflow



If not done, yet:

  • import archive key (Fingerprint: 895D 8086 8FEF 100C DA82 0393 16CC 4680 AA46 5E22):
wget -qO - | sudo apt-key add -
  • register niftylight package source in /etc/apt/sources.list:
deb unstable main
deb-src unstable main
  • update
sudo apt-get update

to install, run:

sudo apt-get install libniftyled

optionally, you might want to install all plugins:

sudo apt-get install niftyled-plugins


Emerge layman if you don't have it already.

emerge -va layman

Add the niftyled overlay (if you don't have already)

layman -f -o -a niftyled


emerge --autounmask-write niftyled

optionally, you might want to install all plugins:

emerge --autounmask-write niftyled-plugins

Compile manually


to compile from sources:

  • compiler e.g. gcc
  • autotools (autoconf, autoheader, ...)
  • libdlfcn / dlfcn.h header
  • libbabl + dev headers
  • niftylog + dev headers
  • niftyprefs + dev headers

Get sources Github-logo.png

Git: git clone git://


If your OS doesn't include the default install prefix, you might have to do that yourself before compiling:

export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"
export LD_LIBRARY_PATH="/usr/local/lib"
export PATH="${PATH}:/usr/local/bin"

to compile & install, cd into the source directory and run:

autoreconf -is
mkdir build
cd build
sudo make install

If you don't want to install to the default location (/usr/local), you can choose a different install prefix, e.g.:

./configure --prefix=/usr

To freshly rebuild a previously built tree, do (you can skip this if you just checked out the sources):

make maintainer-clean
or just remove all contents of the build directory and repeat the previous steps.

See additional compile time options by running:

./configure --help


pixel → LED mapping

  • Read about LED mapping to learn how the "pixel → LED" translation works
  • Read about LED-setup XML to learn how a setup is defined (you can use ledset or Niftyconf to help you create a configuration)

Environment variables

name example description
NFT_LOG_MECHANISM NFT_LOG_MECHANISM="stderr" Set logging mechanism. For a list of available mechanisms use NFT_LOG_MECHANISM="list" or s. mechanism.c sourcecode
NFT_LOG_LEVEL NFT_LOG_LEVEL="debug" Set loglevel. For a list of available log levels check the NftLoglevel section in the doxygen documentation. A list of available loglevels should also be printed in the --help text of applications.
NFT_LOG_IDENT NFT_LOG_IDENT="myapp" Set identity for log mechanisms that support it (e.g. syslog)

name example description
NFT_LED_SETUP NFT_LED_SETUP="~/.nifty.xml" Use this file as default LED-setup XML. (This will not override a config file specified by a commandline argument)



#include "<niftyled.h>"

to your source and compile like:

gcc -o yourprog yourprog.c `pkg-config --cflags --libs niftyled`


Hardware plugins

Multiple output controller devices can be connected at the same time. Each one defined in the config using a <hardware> tag.

Currently maintained hardware-plugins:

Plugin Description URL Manufacturer Stability in current version
dummy Example plugin for debugging & testing - -
niftylino Niftylight niftylino USB controller github
arduino-max72xx Arduino + MAX7219/MAX7221 LED driver github
ldp8806-spi LDP8806 LED driver via SPI github
artnet control ArtNet devices through libartnet github Open Lighting Project

More info on hardware plugins: Libniftyled hardware-plugins


Some applications using libniftyled:

  • Niftyconf - LED setup configuration GUI
  • Ledcap - Screen-capture → LEDs
  • Ledcat - image/raw/pipe → LEDs
  • Ledset - light one single LED in a setup

Other applications using libniftyled.


Please report anything via the issue tracker.


niftyled is a library written in C to control LED devices using pixmaps
Control and configure LED matrix hardware
niftylight GmbH


This category has the following 2 subcategories, out of 2 total.

Pages in category "Libniftyled"

The following 6 pages are in this category, out of 6 total.