"Philips Ambilight for desktops". A tool to generate color palettes from your desktop wallpaper and send them to Home Assistant.
MIT License
DesktopDye is an open source project written in Rust that allows users to have their lights paired with Home Assistant adjust to the most dominant color on their computer screen, similar to how Philips Ambilight works with their TVs. This README file provides instructions on how to install and use DesktopDye.
cd desktop_dye/cli
, and then install the DesktopDye CLI by running cargo install --path .
.<USER_DIR>/.desktop_dye/config.yaml
. For Windows users, the user directory is usually C:\Users\<USERNAME>\.desktop_dye\
. For macOS/Linux users, this will most likely be ~/.desktop_dye/
.Four things need to be done to set up Home Assistant to support DesktopDye.
This light group will contain the lights that will change based on the screen's color.
This will be the text field that DesktopDye will send new color values to, which an automation (made in the next step) will use to control the light group made in the previous step.
In the same Helpers menu as before, create a Helper of type Text. Give it an easily recognizable name and take note of the entity ID for later.
This is the automation that will be triggered when the Text helper's value is changed by DesktopDye, and should change the state of the light group from before to the values in the text field.
input_text.YOUR_TEXT_INPUT_ENTITY
and light.YOUR_LIGHT_GROUP
parts to match the entity IDs of your text input helper and light group, respectively.
alias: 'Desktop Dye Client'
description: ''
trigger:
- platform: state
entity_id:
- input_text.YOUR_TEXT_INPUT_ENTITY
condition: []
action:
- service: light.turn_on
target:
entity_id: light.YOUR_LIGHT_GROUP
data:
transition: 2
rgb_color:
- >-
{{ states.input_text.YOUR_TEXT_INPUT_ENTITY.state.split("
")[0].split(",")[0] }}
- >-
{{ states.input_text.YOUR_TEXT_INPUT_ENTITY.state.split("
")[0].split(",")[1] }}
- >-
{{ states.input_text.YOUR_TEXT_INPUT_ENTITY.state.split("
")[0].split(",")[2] }}
brightness_pct: >-
{{ states.input_text.YOUR_TEXT_INPUT_ENTITY.state.split("
")[0].split(",")[3] }}
mode: single
<USER_DIR>/.desktop_dye/config.yaml
. Again, for Windows users, this will most likely be C:\Users\<USERNAME>\.desktop_dye\
. For macOS/Linux users, this will most likely be ~/.desktop_dye/
.ha_target_entity_id
: Enter the entity ID of the light group helper you created earlier
ha_token
: Enter the Home Assistant access token you created earlier
ha_endpoint
: Verify that this is the correct endpoint for your Home Assistant setup. By default, this should be http://homeassistant.local:8123
.Congratulations, you have successfully set up DesktopDye! You can now run the CLI by running desktop_dye_cli
in your terminal. If you want to run it in the background, you can use a tool like tmux.
The DesktopDye config file contains various settings used to control the behavior of the CLI. The config file is located in <USER_DIR>/.desktop_dye/config.yaml
. Again, for Windows users, this will most likely be C:\Users\<USERNAME>\.desktop_dye\
. For macOS/Linux users, this will most likely be ~/.desktop_dye/
.
The default config file contains fields for all available settings, and looks like this:
# The ID of the screen to capture colors from.
# Is optional. If not specified, the screen primary screen is used.
# Run the application to see a list of screens and their IDs.
screen_id:
# The endpoint of the Home Assistant instance to send the colors to.
# This can usually be set to http://homeassistant.local:8123
# Is required. If not specified, the application will not start.
ha_endpoint: http://homeassistant.local:8123
# The API token to use to authenticate with Home Assistant.
# Is required. If not specified, the application will not start.
ha_token:
# The Home Assistant entity ID to send the colors to.
# This should be a text helper entity, and will usually start with 'input_text.'
# Is required. If not specified, the application will not start.
ha_target_entity_id:
# The amount of colors to sample and send to Home Assistant.
#
# Note that, depending on the algorithm used, the amount of colors sent may be less than
# this value.
#
# Is optional. If not specified, the application will sample 3 colors per capture.
# Must be between 1 and 10 (inclusive).
sample_size: 3
# The algorithm to use to select the colors to send to Home Assistant.
#
# There are two algorithms:
# - 'color_thief': A fast algorithm that selects the most dominant colors.
# This is the default algorithm, and is relatively accurate for most use cases.
# - 'pigmnts': A slower algorithm based on the kmeans-algorithm that selects the
# most dominant colors. Though generally slightly more accurate, it is also
# significantly slower and not recommended for most use cases.
#
# Is optional. If not specified, the default 'color_thief' algorithm is used.
algorithm: color_thief
# The amount of seconds to wait between color captures.
#
# In other words, every this many seconds, the application will capture the colors on the
# screen, and send them to Home Assistant (if it is not already sending colors, and if the
# colors have changed).
#
# Is optional. If not specified, the application will capture colors every 3 seconds.
capture_interval: 3.0
# Selects the mode of color selection.
#
# This determines what colors are sent to Home Assistant, and in what order.
#
# There are three modes:
# - 'default': Orders the colors by occurrence, with the most dominant color first.
# - 'brightest': Orders the colors by brightness, with the brightest color first.
# - 'hue_shift': A special mode where a set of hues around the most dominant color are sent,
# creating a gradient. In this mode, the primary color is not sent first, and may not
# be sent at if the amount of colors in the gradient is an even number.
#
# Is optional. If not specified, the default mode is used.
mode: default
# Determines the amount of degrees of shift to use when selecting hues.
#
# This is only used when the mode is set to 'hues'.
#
# This value is used to shift the primary color to the left and right, creating a gradient.
# For example, if this is set to 45.0, the primary color will be shifted 45 degrees to the
# left and right, creating a gradient with a width of 90 degrees (with the primary color
# in the middle).
#
# Is optional. If not specified, the default value of 45.0 degrees is used.
hue_shift: 45.0
# Determines the format in which the colors are sent to Home Assistant.
#
# There are two formats:
# - 'rgb': The colors are sent as a comma-separated list of RGB values.
# RGB values consist of three components; red, green, and blue,
# and are integers in the range of 0-255 (inclusive).
# Example: "255,255,0 255,0,0 0,255,0"
# - `rgbb`: The colors are sent as a comma-separated list of RGB values, with a brightness
# component at the end. This is the default format.
# The RGB values are integers in the range of 0-255 (inclusive), while
# the brightness value is a float in the range of 0.0-100.0 (inclusive).
# This is useful since Home Assistant devices generally don't support setting the brightness
# through the RGB values, and instead require a separate brightness value.
# Example: "255,255,0,100.0 255,0,0,100.0 0,255,0,100.0"
# - `hsb`: The colors are sent as a comma-separated list of HSB (hue, saturation, brightness)
# values. While this format is more accurate, it is also more difficult to work with in
# Home Assistant, and can lead to unexpected results in color accuracy. However, this is
# the only format that supports setting a specific brightness for Home Assistant lights,
# which the RGB format does not support.
# HSB values are in the range of floats 0.0-360.0 for hue and floats 0.0-100.0 for the
# saturation and brightness.
# Example: "60.0,100.0,100.0 0.0,100.0,100.0 120.0,100.0,100.0"
#
# Is optional. If not specified, the default format (`rgbb`) is used.
color_format: rgbb
# Determines the factor by which to increase the brightness of every color.
#
# If provided, the brightness of every color is multiplied by this value. This
# is useful if the colors are too dark, or if the brightness of the colors is
# not sufficient for your lighting setup.
#
# Note that brightness values are clamped to the range of 0.0-100.0 (inclusive).
# Setting this value lower than 1.0 will decrease the brightness of the colors,
# while setting it to 0.0 will result in all colors being black.
#
# Example:
# - brightness_factor = 0.5, base brightness = 50.0, result = 25.0
# - brightness_factor = 2.0, base brightness = 50.0, result = 100.0
# - brightness_factor = 2.0, base brightness = 75.0, result = 100.0 (clamped)
#
# Is optional. If not specified, it is set to 1.0, which means no brightness
# adjustment is performed.
brightness_factor: 1.0
To uninstall DesktopDye, follow these steps:
<USER_DIR>/.desktop_dye/config.yaml
.If the colors of the lights in your light group aren't changing, make sure that:
desktop_dye_cli
won't start on macOSIf you are on macOS and desktop_dye_cli won't start, it is likely because it needs permission to capture screenshots. You can grant it permission by going to System Preferences -> Security & Privacy -> Privacy -> Screen Recording, and then adding desktop_dye_cli to the list of apps allowed to capture screenshots.
desktop_dye_cli
won't start on LinuxIf you are on Linux and desktop_dye_cli won't start, it is likely because it needs permission to read the screen. You can grant it permission by running the following command:
$ which desktop_dye_cli
## Take note of the path to the desktop_dye_cli binary, then run the following command.
sudo setcap cap_sys_admin+ep path/to/desktop_dye_cli
## Replace path/to/desktop_dye_cli with the actual path to the binary from the first command.
If you find a bug or have a feature request, please file an issue on the GitHub repository.
If you want to contribute to the code, please submit a pull request. Contributions are welcome and appreciated.
DesktopDye is licensed under the MIT license. See LICENSE for more information.