HAmbiSync (Hue Ambilight Synchronization)

This project is a desktop/server version of the Ambilight+hue mobile app.

HAmbiSync periodically queries your Philips TV (2011+ models with ambilight are supported) for ambilight colors data on TV edges, calculates the average value of the user defined points and sends this color to the configured Hue Lamps.

The idea is to save the resources on the smartphone/tablet and run the synchronization service on your desktop or even a server. You can also control this app remotely using simple HTTP requests (via curl/wget or your own apps and scripts). See below for the XBMC automation example.

This app is intended for advanced users, or at least to the users who can read and understand the documentation below.


  • 1.0 beta, built: 19 November, 2016
Windows hambisync.zip 4.9MB
Linux/Mac/Unix hambisync.tar.gz 4.7MB
Sources hambisync-src.zip 20KB


  • Implemented in Java, runs on Windows, Linux, Mac OS X, Raspberry Pi, any OS where you can install Java 1.7
  • Potentially reduces lag compared to the mobile application (just wired connection can improve it)
  • Saves battery, you no longer have to keep your mobile device near charger to enjoy ambilight+hue experience
  • Provides more control over ambilight to hue mappings (choose which leds map to which lamps, configure brightness, transition time, immersion level per lamp)
  • Uses original color transformation algorithm from the mobile app (any other app you will find provides wrong colors/brightness levels)
  • Automatically detects when TV goes online and enables sync, disables sync when TV goes offline (configurable, can also turn off lamps when tv is offline)
  • Simple automation / API is available via HTTP requests (start ambilight+hue experience when you play movie in XBMC, restore hue lamps when playback is stopped)
  • Save current lamps state into a named preset, set lamps to any named preset saved before (with a single HTTP request)
  • Simple service installer for Windows (run headless)

Quick Start

  • Make sure you have Java 1.7 installed (32-bit JRE 1.7 is recommended on Windows, if you have JDK installed, but no JRE, hambisync.exe will not work).
  • Unpack the downloaded file into any folder on your system
  • Configure your Philips TV IP address. Edit conf/application.conf file, set tv.ip property. Activate jointSPACE API following the instructions. Double check that you can access ambilight data from the browser: http://<tv.ip>:1925/1/ambilight/processed.

AFTER upgrading to the new firmware, jointSPACE NEEDS TO BE ACTIVATED by entering the following digits sequence while watching TV (WatchTV activity): "5646877223". You don't need to activate it if the original Ambilight+hue mobile app already works for you.

  • Configure lamp mappings, edit conf/sync-presets/lamps.json file.
    "1": {
        "right": [0],
        "top": [8, 7],
        "brightness": 10,
        "immersion": 10,
        "transition": 3
    "2": {
        "left": [0],
        "top": [0, 1],
        "brightness": 10,
        "immersion": 10,
        "transition": 3

This sample is for 2 hue lamps, lamp 1 is located on the right of the TV, above the top edge and is mapped to the top led on the right edge and to the 2 most right leds of the top edge. Lamp 2 is mapped to the top-left side leds. If you specify multiple sides/leds, the average color of all these leds will be used.

To find out how many leds your TV API reports, open http://<tv.ip>:1925/1/ambilight/topology.

	"layers": 1,
	"left": 4,
	"top": 9,
	"right": 4,
	"bottom": 0

For this model top side has 9 leds, right/left sides have 4 leds. Note that index is zero based, so the right top edge led index is 8, not 9. Lamp numbers can be found using the Hue app or Ambilight+hue app on your mobile device.

The above topology and lamps config corresponds to the following layout:

   (2)                                        (1)
           0  1         ...          7  8
         0 |                            | 0
         1 |                            | 1
         2 |                            | 2
         3 |                            | 3

Layout for your TV may be different. On some TVs index on the sides starts from the bottom instead of the top (3-2-1-0 instead of 0-1-2-3).

You can add more lamps to the config if needed and map them to any leds or the average value of arbitrary leds combination.

Ensure JSON syntax is still valid after your modifications, don't forget the commas.

  • transition property specifies how smoothly the colors will change. 3 is the default value used in the original mobile app for all the lamps except those in the shadowed zone (behind the user), this zone lamps have transition time set to 5.
  • immersion property sets the level of the experience. Value 10 is the default, value 0 will give you white lamps.
  • brightness is self explanatory (0-10).
  • model allows to specify the model of the lamp. Normally the model should be detected automatically from the bridge, but it may not work for some lamps. Recognized models: LCT001, LCT002, LCT003, LLC001, LLC005, LLC006, LLC007, LLC011, LLC012, LLC013, LLC014, LLS001, LST001. Lightstrip is LST001, Bloom is LLC007, A19 is LCT001, BR30 is LCT002.

Lamps will be updated in the same order as in the config file. If you have multiple lamps on the same side, it makes sense to put them close in the config.

Start the app:

  • Windows: run bin\hambisync.exe
  • Mac/Linux: cd bin, run java -jar hambisync.jar or run bin/hambisync.sh

On the first start the app will search for bridges in your local network. If you have only one bridge, it will try to connect to this bridge automatically. Follow the console log messages and press the button on your bridge to authorize the connection.

If you have multiple bridges, either specify the bridge IP in conf/application.conf via bridge.ip property or use HTTP API to connect to the specific bridge IP:<IP>, open for the bridges list.

Ctrl+C to stop the app. You need to restart the app after making any changes to configuration. Lamps configuration can be applied on the fly using /sync-preset/load/<name> WEB API, see below.

Running as Windows Service

After you've configured the app and ensured that it works properly, it's a good idea to start it automatically as the system service. Use the supplied scripts in the bin directory. Make sure to run them as Administrator.

  • install-service.bat to install the HAmbiSync service
  • start-service.bat to start the HAmbiSync service

If you want to access the service via HTTP API, change web.ip to IP address of your machine that can be accessed within the local network and ensure that web.port (4567 by default) is open on your firewall. You must add firewall exception for the service/app or add a rule for this specific port, otherwise firewall will block access and you will not be able to control the service remotely.

Linux/Mac users will have to use their system specific approach to run java -jar hambisync.jar or bin/hambisync.sh on system startup.

HTTP Control API

HAmbiSync starts a web server on the user specified web.ip:web.port ( by default). Use it to control the server remotely from other applications and scripts.

URL Description
/ app version and synchronization status
/status 1 if sync is running, 0 otherwise
/start start ambilight to hue sync
/stop stop ambilight to hue sync
/toggle toggle ambilight to hue sync
/sync-preset/load/<name> load lamps synchronization config from conf/sync-presets/<name>.json
/on turn all sync config lamps on
/off turn all sync config lamps off
/preset/save/<name> save current lamps state into the preset with provided <name>
/preset/load/<name> load preset with provided name and applies it to lamps
/preset/load/<name>/<delay> load preset after specified delay in milliseconds
/preset/list/ print the list of available presets
/bridge list discovered bridges
/bridge/connect connect to the first discovered bridge
/bridge/connect/<ip> connect to the bridge with the specified <ip>
/cc/<trigger> execute command and control preset with the specified <trigger>
/cc-ctrl/reload reload command and control presets without restating the server
/cc-ctrl/list list command preset triggers and the descriptions

Command & Control Presets

It's possible to define your own presets that will run applications/scripts on the machine where HAmbiSync is running via HTTP API calls. This way you can control apps and automate different processes by simple HTTP GET requests that can be performed from other apps, mobile devices, Android widgets (via Tasker), etc.

Presets are .json files that are placed in conf/cc-presets folder, example of the preset:

    "description": "Pass query action parameter to foobar",
    "trigger": "fb",
    "aliases": [
    "type": "exec",
    "command": "c:\\Program Files (x86)\\foobar2000\\foobar2000.exe",
    "args": [
  • trigger defines what URL will trigger the command, in this case it would be /cc/fb.
  • aliases can provide an optional array of triggers that will run the same preset
  • type defines what the preset does, use exec for execution of the process and http for HTTP request.
  • command is the path to the executable/script, if type is set to http, the command defines the URL to query
  • workdir is the working directory, if not set, executable's parent directory will be used
  • args defines an array of arguments to pass to the executable, each argument can be a fixed parameter or a placeholder ${param}, placeholders are substituted with the corresponding HTTP request parameters. To stop playing and pass /stop, the URL would be: /cc/fb?action=stop, to start playback again: /cc/fb?action=play

The minimal preset would look like:

    "description": "Run notepad.exe",
    "trigger": "notepad",
    "type": "exec",
    "command": "c:\\Windows\\System32\\notepad.exe"

and could be triggered by /cc/notepad URL.

At the moment there is no way to get the output from the scripts via HTTP as the process is started asynchronously and there is no waiting for the completion.

XBMC Automation

Start ambilight+hue experience on video playback and stop it automatically restoring the previous lamps state when the video stops.

Install service.xbmc.callbacks plugin.

Create .bat or .sh script depending on your OS.

Change IP address if HAmbiSync is running on another machine/address.



Don't forget to make the scripts executable: chmod +x *.sh.



You need to have curl.exe somewhere in PATH or in the script folder. If you don't have curl, download it here.

XBMC Plugin

Open service.xbmc.callbacks configuration, set the scripts to be executed on playback start/stop.

Last modified: 2016/11/19 00:42 (external edit)