Services

Color FX currently exposes two services: one for matching lights to prominent colors in an image, and one for turning them to a random color.

color_fx.turn_light_to_matched_color Changes the specified light(s) to match a prominent color from the image specifed.

Parameter	Required	Type	Description	Example	Default
entity_id	Yes	string or list	Entity ID(s) of the light(s) you wish to change.	light.lamp	-
url	Yes	url	URL of an image to use for color recognition. This must be specified if 'media_player' is not.	https://f4.bcbits.com/img/a0581187129_10.jpg	-
media_player	Yes	string	A single entity ID for which to use the 'entity_picture' state for recognition. This must be specified if 'url' is not. If this is specified, 'host' must be set in the confgiguration.	https://f4.bcbits.com/img/a0581187129_10.jpg	-
mode	No	string	Changes the recognition mode.	recognized or complementary	recognized
same_color	No	boolean	Set all lights to the same color.	true or false	false
brightness	No	int	A brightness value (0-255) to force lights to be set to.	128	192
brightness_pct	No	int	A brightness percentage (0-100) to force lights to be set to.	35	75

color_fx.turn_light_to_random_color Changes the specified light(s) to a random color.

Parameter	Required	Type	Description	Example	Default
entity_id	Yes	string or list	Entity ID(s) of the light(s) you wish to change.	light.lamp	-
mode	No	string	Changes the color space for the returned color.	rgb_color or hs_color	hs_color
hs_color	No	int or int list	A dictionary of either ints or int lists, corresponding to each color component.	hue: 30, saturation: [60, 90]	hue: [0, 360], saturation: [80, 100]
rgb_color	No	int or int list	A dictionary of either ints or int lists, corresponding to each color component.	red: 30, green: [60, 90], blue: [75]	red: [0, 255], green: [0, 255], blue: [0, 255]
same_color	No	boolean	Set all lights to the same color.	true or false	false
brightness	No	int or int list	An int or list of ints (0-255) to clamp random brightness between.	[32, 192]	192
brightness_pct	No	int or int list	An int or list of ints (0-100) to clamp random brightness percentage between.	75	75

color_fx.turn_light_to_cycle_color Cycles the specified light(s) along the hue spectrum.

Parameter	Required	Type	Description	Example	Default
entity_id	Yes	string or list	Entity ID(s) of the light(s) you wish to change.	light.lamp	-
same_color	No	boolean	Set all lights to the same color.	true or false	false
steps	No	int	Number of steps in the cycle.	12	24
start	No	int	Override starting hue.	0	180
saturation	No	int or int list	An int or list of ints (0-100) to clamp random saturation between.	[80, 100]	[32, 90]
brightness	No	int or int list	An int or list of ints (0-255) to clamp random brightness between.	[32, 192]	192
brightness_pct	No	int or int list	An int or list of ints (0-100) to clamp random brightness percentage between.	75	75

Usage with multiple lights

---

If a list is passed for entity_id (multiple lights) in either service, they will be set to different colors, unless your service call contains same_color: true, which will cause it to set all the desired lights to the same color.

For matched colors, the default behavior is to assign the first light in the list to the "most colorful" (as defined in Measuring Colorfulness in Natural Images) color, with each successive light being the next most colorful. This approach typically results in either:

• Each light representing a different vibrant color from the supplied image
• Each light being a different shade of a single vibrant color

Depending on how many different distinct colors are found in the image.

For random colors, the default behavior is to set each light to a different random color.

Color in Range

---

In order to produce a random color within some range, leverage the hs_color (and its components, hue and saturation) or rgb_color (and its components, red, green, and blue) parameters in your service call.

Each of these parameters take a dictionary containing integers (or lists of integers) within which to clamp the respective values. If the list has only one element, that value will not be randomized. Conversely, if the list is longer than two elements, any extra elements will be ignored. All values will be clamped to their natural minimum and maximum values (0-360 for hue, 0-100 for saturation, and 0-255 for RGB values), if the specified range is too large in either direction. This same logic applies to the brightness, brightness_pct parameters, and saturation parameters.

This example service call will clamp the red value between 192 and 240, the green value between 32 and 168, and the blue value between 27 and 255. It also randomizes brightness between 50 and 80.

service: color_fx.turn_light_to_random_color
data:
  entity_id: light.lamp
  rgb_color:
    red:
      - 192
      - 240
    green:
      - 32
      - 168
    blue:
      - 27
      - 255
  brightness:
    - 50
    - 80

In this example, only the hue is randomized, within a range of 20 to 120, keeping saturation constant at 90, and brightness constant at 60.

service: color_fx.turn_light_to_random_color
data:
  entity_id: light.lamp
  hs_color:
    hue:
      - 20
      - 120
    saturation: 90
  brightness: 60