Kodi Addon – Lifx Ambient Light

What’s better than watching a Movie? Watching a movie with the perfect ambient lighting. After researching a bunch of proprietary solutions, I decided to build something on my own. This way, I can set it up just the way I like and evolve over time with a little initial cost. Little did I know, this will turn into my most successful contribution to the open-source community yet.

This Kodi media center add-on controls Lifx smart wifi lights to create the perfect ambient light environment for a great movie experience. It comes with a setup wizard for auto-discovery and a number of fully customizable user preferences.

Disclaimer: This is a late post, check out my other post on creating a TV Ambient light setup that’s a little more flexible, but requires working with LED strip, microcontrollers, soldering iron, and a bunch of extra hardware for capturing the frames from any HDMI input.

Statistics

Before going into too many details about the addon itself, here are some all-time statistics I have collected from the addon’s usage (From the users who had metrics reporting enabled)

• 120,000 Sessions with average 25 sessions per user
• 4800 Unique Users with 350 Daily Active Users at its peak
• 42 Different Kodi versions
• 60% Desktop and 40% Mobile Devices across 5 Operating Systems
• Users from 6 Continents, 15 Subcontinents, 59 Countries, 940 Cities in 28 Languages

Requirements

While looking for an ambient light setup, I had the following requirements:

• Non Functional
  • It should be able to make at least 10 requests/second for color changes.
    • These requests should be made directly to the device or hub to change the colors without the roundtrip from the cloud
    • I should be able to capture the image frame from the video being played on screen and process the image for list of colors and maybe positions in a 2D Matrix.
• Functional
  • I should be able to create virtual groups of bulbs – Theater, Ambient and Static groups.
    • Ambient lights will change colors and brightness based on the picture frames on TV
    • Theater group turns on/off and changes brightness based on the playback status of the Video
    • Static group acts opposite to the theater lights
  • All of the bulbs restore to their initial state when media playback stops
  • Auto discovery
  • Customizable user preferences for differnt moods and lighting conditions

Why Lifx + Kodi

While researching my options for setting up ambient lighting, I came across the wifi-controlled smart bulbs from Lifx. While they were not as popular as Philips Hue, I picked these up because – 1. These didn’t require a separate hub and 2. These support very low latency, which is perfect for Ambilight development work.

While Lifx Cloud API can only handle 120 requests/minute (2 requests/second), there is a much faster LAN protocol officially published by Lifx. This allows controlling Lifx devices locally via UDP and allows 20 requests/second (20Hz). Although this is much more complicated to implement, there is already an open-source client library that implements this protocol – LifxLAN.

For the media platform, I had to go with Kodi, because it provides native API for screen capture and I was already familiar with the user interface. Best of all it is an open-source entertainment platform with support for custom addons.

Features

• Fully customizable
  • Each group fully configurable with a discovery and selection wizard.
  • Override brightness/hue/saturation/temperature for different states in each of the theater/ambilight/static group – playback started/resumed, paused and stopped.
  • Option to forcefully turn on or ignore lights which are powered off (not switched off)
  • Option to flash lights once on discovery
  • Option to disable the Theater/Ambilight mode for short videos
    • Option to customize what is considered a short video
  • Restore the lights to original states (color and power) when movie stops.
• 3 groups for your Lifx powered media center room
  • Theater
    • Lights in the theater group act like wall lights in a typical theater. When playback starts the lights dim and they un-dim when playback is paused or ends. If you only want some of the lights to un-dim during a pause, it is possible to configure “subgroup” in add-on settings -> Theater and only dim the subgroup.
    • Dim or Turn off the lights when Movie starts playing
    • Undim or Turn on the lights when you pause the movie
    • Return the lights to original settings when Movie ends.
    • Option to configure Fading time to be proportional to the current brightness. (e.g. take 7 seconds to change brightness from 100% to 30%, while taking 5 seconds to change from 50% to 0%)
  • Ambilight
    • Ambilight group tries to control the lights similarly to modern Ambilight TVs. The add-on tries to figure out the most represented colors and brightness in each frame and change the lights to reflect that. They can also be configured to work similarly to theater groups when playback is paused.
    • Option to Dim the lights when Movie starts playing
    • Option to change minimum and maximum brightness
    • Option to configure threshold (minimum) values for brightness and saturation when calculating the color/brightness from picture frame.
    • Option to set different colors for different lights or same color for all lights
    • Option to configure bias value (lower the bias – more variety of colors, higher the bias – less variety of colors, but higher accuracy)
  • Static
    • Static lights act opposite to the theater lights — they are turned on when playback starts, turned off when you pause the playback, and go back to the initial state after the playback stops.
    • Option to set random color to the static lights that turn on when the video playback starts.
    • Option to override hue, saturation, brightness or temperature values

Success

After publishing this addon on Github, I started noticing a lot of interest in the addon. I started noticing a lot of views on the demo video on YouTube. I also engaged with some of the users on Reddit, Lifx Community, and Kodi Forum. Overall, I received great feedback for the addon and more feature requests. I created an issue template on Github to make it easier for the users to report issues and feature requests. I also got a couple of Pull Requests from fellow developers.

Analytics

As this was my side project with very limited bandwidth, I wanted to prioritize my work on the addon. I have always been a huge proponent for making data-driven decisions. Similar to my previous post where I created a WordPress plugin to better understand my users in a huge multisite installation at New York University, I had to create custom tooling to collect analytics and especially error reports from the addon. In order to better understand my user base and prioritize the tasks, I had to hack together a Google Analytics client. Since this is not a native mobile app or a web app, I had to write a custom script for sending GA events from the addon running on Kodi. This also works as a custom tooling for error reporting as I was able to send a snippet of stack trace when an exception was caught.

This gave me insights into my user base and helped prioritize the todo list. Here are some examples of the analytics I used:

1. Kodi OS and Python versions, so I can work on supporting all the top versions in use
2. Exceptions and Crash Reports. Each crash event in GA also included snippets of traceback for additional info
3. Types top Lifx devices used – So I can support the integration for new device types e.g. Lifx-Z LED Strip., Tiles, Beam, etc.
4. Most popular/common settings, so I can set them as defaults in next release
5. Popular countries and languages, so I can prioritize translations and localization work
6. Most popular day/times, so I can pick the best time to push a new release

Demo

Disclaimer: These were taken with the initial version of the addon and lag was quite distracting. This has improved a lot over multiple iterations.

Screenshots

Github Links