Homebridge Philips Ambilight TV

A Homebridge plugin to control Philips Android TVs with Ambilight as HomeKit Television accessories.

Originally based on homebridge-philips-tv-ambilight by Konrad Knitter, licensed under the Apache License 2.0. This fork has been substantially rewritten by MP Consulting.

Features

• Power ON/OFF with Wake-on-LAN support
• Input source selection (HDMI, TV tuner, apps)
• Dynamic app discovery — automatically finds all installed apps on the TV
• Volume control and mute
• Remote control (D-Pad, Back, Menu, Play/Pause, etc.)
• Ambilight color control with brightness, color picker, and Adaptive Lighting
• Ambilight + Hue switch — optional switch to toggle the Philips Hue integration independently
• Long-poll state detection — near-instant updates when TV state changes, with interval polling fallback
• State sensors — optional MotionSensor services for power, ambilight, and mute (for HomeKit automations)
• Multi-TV support
• Custom UI for easy setup and configuration

Ambilight Control

The Ambilight appears as a color lightbulb in HomeKit with:

• On/Off toggle - Turn Ambilight on or off
• Brightness slider - Control light intensity (0-100%)
• Color wheel - Pick any color using the HSB color picker
• Adaptive Lighting - Color temperature adjusts automatically throughout the day
• Color temperature slider - Manual control from 140 mireds (cool) to 500 mireds (warm)

When you select a color in HomeKit, the TV switches to "Follow Color" mode with your chosen color. The plugin also syncs the current color state from the TV back to HomeKit.

Ambilight + Hue

If your TV is paired with Philips Hue lamps, you can enable an extra switch that toggles the Ambilight + Hue integration (Hue lamps following Ambilight) independently of the main Ambilight controls:

{
  "ambilightHueSwitch": true
}

This appears as a separate Switch accessory in HomeKit, usable in scenes and automations. It is backed by the TV's /HueLamp/power endpoint.

Custom Apps

Some TVs don't report every installed app through their app list — sideloaded or region-specific apps (e.g. EON) can be missing, so they never appear as sources. You can add these manually, in addition to auto-discovered apps.

The easiest way is the config UI: edit a TV → Apps tab. Usually the package name is all you need — click Add.

You can also configure them directly:

{
  "customApps": [
    { "name": "EON", "packageName": "com.ug.eon.android.tv" }
  ]
}

When no launch activity is given, the plugin launches <packageName>.MainActivity (the common Android convention, e.g. com.netflix.ninja.MainActivity), which works for most apps. Some apps use a different launcher (e.g. Prime Video is com.amazon.ignition.IgnitionActivity) — for those, set the exact launch activity (className) in the optional field, or capture it with Detect from TV.

Detect from TV reads the app currently open on the TV and fills in its package name and exact launch activity. Make sure the app is in the foreground first — if the TV is on live TV or the home screen, it reports that system activity instead.

State Sensors

You can enable optional MotionSensor services that expose TV state for HomeKit automations:

{
  "stateSensors": ["power", "ambilight", "mute"]
}

Each sensor appears as a MotionSensor — "motion detected" means the state is active (TV on, ambilight on, or muted). This allows creating automations like "When TV turns on, turn on the lights".

Requirements

• Philips Android TV with JointSpace API v6 (2016+ models)
• TV and Homebridge on the same network
• Node.js 20.18.0 or later

Installation

Via Homebridge UI (Recommended)

1. Open the Homebridge UI
2. Go to the Plugins tab
3. Search for "homebridge-philips-ambilight-tv"
4. Click Install

Via Command Line

npm install -g homebridge-philips-ambilight-tv

Setup

Using the Custom UI (Recommended)

1. Open the Homebridge UI and go to the plugin settings
2. Click "Discover TVs" to find your TV on the network
3. Select your TV and follow the pairing wizard
4. Enter the PIN displayed on your TV screen
5. Customize sources and save

Manual Configuration

Add the following to your config.json:

{
  "platforms": [
    {
      "platform": "PhilipsAmbilightTV",
      "devices": [
        {
          "name": "Living Room TV",
          "ip": "192.168.1.10",
          "mac": "AA:BB:CC:DD:EE:FF",
          "username": "your_device_id",
          "password": "your_auth_key"
        }
      ]
    }
  ]
}

Configuration Options

| Key | Description | Required | | --- | --- | --- | | platform | Must be PhilipsAmbilightTV | Yes | | devices | Array of TV configurations | Yes | | devices[].name | Display name for the TV | Yes | | devices[].ip | IP address of your TV | Yes | | devices[].mac | MAC address (for Wake-on-LAN) | Yes | | devices[].username | Device ID from pairing | Yes | | devices[].password | Auth key from pairing | Yes | | devices[].sources | Custom source configuration | No | | devices[].ambilightMode | Ambilight mode on turn-on (e.g. "FOLLOW_VIDEO/NATURAL") | No | | devices[].ambilightOnStart | Automatically turn Ambilight on (in ambilightMode) when the TV powers on | No | | devices[].stateSensors | Array of state sensors: "power", "ambilight", "mute" | No | | devices[].ambilightHueSwitch | Expose the Ambilight + Hue integration as a separate switch | No | | devices[].customApps | Apps the TV doesn't report (added on top of discovered apps); each has name, packageName, optional className/action | No | | devices[].pollingInterval | Polling interval in ms (1000-60000, default: 10000) | No |

Getting Credentials

The username and password are obtained during the pairing process:

1. Use the plugin's custom UI to pair (recommended)
2. Or use the TV's built-in pairing API:
   • Send a pairing request to https://<TV_IP>:1926/6/pair/request
   • Complete the pairing with the PIN shown on TV
   • The response contains your credentials

Editing Sources

The plugin supports customizing which sources appear in HomeKit:

1. Go to the plugin settings in Homebridge UI
2. Click "Edit Sources" on your configured TV
3. Drag and drop to reorder sources
4. Toggle visibility for each source
5. Click "Done" to save

The plugin supports up to 30 input sources (5 static + 25 apps).

Troubleshooting

TV not discovered

• Ensure the TV is powered on (not in standby)
• Check that TV and Homebridge are on the same network/VLAN
• Try entering the IP address manually

Pairing fails

• Make sure no other device is pairing simultaneously
• Try restarting the TV
• Check the TV's network settings

TV not responding

• Verify the TV's IP hasn't changed (consider a static IP)
• Check if Wake-on-LAN is enabled in TV settings
• Ensure the TV's API is accessible (port 1926)

"Write handler didn't respond at all" warnings

If you see these warnings in the Homebridge logs, make sure you are running v1.0.4 or later. Earlier versions used a 15-second API timeout that exceeded Homebridge's handler deadline, causing the plugin to slow down the entire instance when the TV was unreachable.

Debug logging

Run Homebridge with the -D flag to enable debug mode. The plugin logs state changes as they happen:

[Living Room TV] Power: On
[Living Room TV] Volume: 17
[Living Room TV] Ambilight: FOLLOW_VIDEO (STANDARD)
[Living Room TV] Active app: com.netflix.ninja

POST requests (user actions) are always logged. GET polling is silent unless a state change is detected.

Input sources not updating in Home app

This is a known tvOS 18 bug. The plugin includes a workaround that may require removing and re-adding the TV in the Home app.

Development

# Clone the repository
git clone https://github.com/mp-consulting/homebridge-philips-ambilight-tv.git

# Install dependencies
npm install

# Build
npm run build

# Run with test config
npm start

# Test TV endpoints
npm run test:tv

License

This project is derived from homebridge-philips-tv-ambilight by Konrad Knitter, which is licensed under the Apache License 2.0. Modifications and new code are licensed under the MIT License. See the LICENSE file for full details.

Credits

• Homebridge
• Philips JointSpace API documentation