{"id":13579984,"url":"https://github.com/NiklasReiche/ad-spotify-mood-lights-sync","last_synced_at":"2025-04-06T00:30:35.655Z","repository":{"id":50439311,"uuid":"331696949","full_name":"NiklasReiche/ad-spotify-mood-lights-sync","owner":"NiklasReiche","description":"AppDaemon app that synchronizes rgb lights to the mood of the currently playing spotify song in Home Assistant.","archived":false,"fork":false,"pushed_at":"2024-12-30T14:35:35.000Z","size":425,"stargazers_count":40,"open_issues_count":1,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-30T15:30:44.042Z","etag":null,"topics":["appdaemon","home-assistant","rgb-lights","spotify"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NiklasReiche.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-21T17:08:28.000Z","updated_at":"2024-12-30T14:35:39.000Z","dependencies_parsed_at":"2024-08-01T15:31:33.181Z","dependency_job_id":"03559f72-ed60-4d6e-baaf-7e204f441cb0","html_url":"https://github.com/NiklasReiche/ad-spotify-mood-lights-sync","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":"ludeeus/ad-hacs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiklasReiche%2Fad-spotify-mood-lights-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiklasReiche%2Fad-spotify-mood-lights-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiklasReiche%2Fad-spotify-mood-lights-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiklasReiche%2Fad-spotify-mood-lights-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NiklasReiche","download_url":"https://codeload.github.com/NiklasReiche/ad-spotify-mood-lights-sync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419597,"owners_count":20936009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appdaemon","home-assistant","rgb-lights","spotify"],"created_at":"2024-08-01T15:01:45.577Z","updated_at":"2025-04-06T00:30:35.647Z","avatar_url":"https://github.com/NiklasReiche.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Important\n\nDue to [recent changes to Spotify's API](https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api), this app will no longer work for new users. Existing installations may continue to work for now.\n\n# Spotify Mood Lights Sync\n\n_AppDaemon app that synchronizes rgb lights to the mood of the currently playing song in Home Assistant._\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg?style=for-the-badge)](https://github.com/custom-components/hacs)\n![GitHub Release](https://img.shields.io/github/v/release/NiklasReiche/ad-spotify-mood-lights-sync?sort=date\u0026display_name=release\u0026style=for-the-badge)\n\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/NiklasReiche/ad-spotify-mood-lights-sync/validate.yaml?branch=master\u0026label=HACS-Validation\u0026style=for-the-badge)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/NiklasReiche/ad-spotify-mood-lights-sync/test.yaml?branch=master\u0026label=Tests\u0026style=for-the-badge)\n\n## About\n\nThis app uses the Spotify API to extract the emotional mood value of the currently playing track. Each mood value lies\non a 2D plane which is mapped to a color spectrum from which the color for the light is picked.\n\nThe built-in color maps used by the app look as follows. The horizontal axis ranges from negative (left) to positive\n(right) emotion while the vertical axis ranges from low (bottom) to high (top) energy. A sad, slow song is thus mapped\nto blue light while a happy, upbeat song is mapped to yellow light.\n\n\u003cimg src=\"https://github.com/NiklasReiche/ha-spotify-lights-sync/blob/master/profiles.png\" alt=\"color profiles\" width=500\u003e\n\n## Prerequisites\n\nFor this app to work, the following python package must be installed in the [AppDaemon environment](https://github.com/hassio-addons/addon-appdaemon/blob/main/appdaemon/DOCS.md#configuration):\n\n```yaml\npython_packages:\n  - spotipy\n```\n\n## Installation\n\nThis app is available on [HACS](https://hacs.xyz/) for easy installation and updating.\n\n**Important:** HACS does not work by default if you are running AppDaemon with version 15 or newer of the Home \nAssistant add-on. Refer to https://github.com/joBr99/nspanel-lovelace-ui/issues/1029#issue-1995332526 for a workaround.\nOther AppDaemon installations should work with HACS as long as the `app_dir` in your `appdaemon.yaml` points to \n`appdaemon/apps/` within your Home Assistant config folder, as this is where HACS puts downloaded apps.\n\nYou can also install this app manually by simply downloading the `spotify_mood_lights_sync` directory from inside the \n`apps` directory here to your local `apps` directory. Then add the configuration to your `apps/apps.yaml`.\n\n## Minimal configuration\n\nThe following shows a minimal example configuration (the spotify credentials are supplied via a secrets file here):\n\n```yaml\nspotify_mood_lights_sync:\n  module: spotify_mood_lights_sync\n  class: SpotifyMoodLightsSync\n  client_id: !secret spotify_client_id\n  client_secret: !secret spotify_client_secret\n  media_player: media_player.spotify_johndoe\n  light: light.bedroom\n```\n\n## Conditional execution\n\nYou can switch the light synchronization on and off through Home Assistant by using\nAppDaemon [Callback Constraints](https://appdaemon.readthedocs.io/en/latest/APPGUIDE.html#hass-plugin-constraints). For\nexample, you can control the execution with an `input_boolean` switch:\n\n```yaml\nspotify_lights_sync:\n  constrain_input_boolean: input_boolean.spotify_lights_sync_toggle\n```\n\n## Lights\n\nThe app expects a single entity name for the `light` option. If you want to control multiple lights at once, you have to\ncreate a group in Home Assistant and provide the group entity for the `light` option.\n\nThe app only deals with the color attributes of the lights, leaving the brightness untouched. You can therefore control \nthe brightness of your lights independently.\n\n## Spotify\n\nThe app queries information from Spotify using the client id and client secret of a Spotify-Develop App for \nauthentication. You can use the same values here that you use for the Spotify integration in Home Assistant. \n\n## Media Players\n\nThe app supports media players from the spotify integration as well as generic media players.\n\n### Spotify media player (direct mode)\n\nUsing a spotify media player is the default and thus no special config options must be set. Note that only the \nmedia players directly provided by the spotify integration will work in this mode.\u003csup id=\"sp-player\"\u003e[1](#sp-player-note)\u003c/sup\u003e\nFor other integrations, e.g. Sonos speakers, this may not work, and you should use \n[search mode](#generic-media-player-search-mode) instead.\n\nSince the Spotify integration in Home Assistant only polls the Spotify API every 30 seconds to detect when the currently\nplaying song changes, the light synchronization may be delayed by up to 30 seconds in the worst case.\n\n\u003cb id=\"sp-player-note\"\u003e[1](#sp-player)\u003c/b\u003e: This mode is reliant on the `media_content_id` attribute of the \n`media_player` containing the spotify track id (e.g. `spotify:track:abcdefghijkl`) for the current song. If your \nnon-spotify media player supports this, you can also use direct mode.\n\n### Generic media player (search mode)\n\nThe app can also listen on all non-spotify media players that support the `media_title` and `media_artist` state\nattributes. In order to use such a player, add the `mode: search` option to the app config. In this mode the app tries\nto find the corresponding track in Spotify by title and artist before calculating the mood.\n\nIf a track cannot be found in Spotify the light will not be synced for that song.\n\n## Full app configuration\n\n| key                                       | optional | type    | default   | description                                                                                                                                                                                                     |\n|-------------------------------------------|----------|---------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `module`                                  | False    | string  |           | The module name of the app. Must be `spotify_mood_lights_sync`.                                                                                                                                                 |\n| `class`                                   | False    | string  |           | The name of the Class. Must be `SpotifyMoodLightsSync`.                                                                                                                                                         |\n| `client_id`                               | False    | string  |           | The client id of the Spotify-For-Developers app to use for accessing the Spotify API.                                                                                                                           |\n| `client_secret`                           | False    | string  |           | The client secret of the Spotify-For-Developers app to use for accessing the Spotify API.                                                                                                                       |\n| `media_player`                            | False    | string  |           | The entity_id of the media player to sync from.                                                                                                                                                                 |\n| `light`                                   | False    | string  |           | The entity_id of the light or light group to sync.                                                                                                                                                              |\n| `color_profile`                           | True     | string  | `default` | The color profile to use for mapping moods to colors. Possible values are `default`, `saturated`, or `custom`. When `custom` is specified, the color map will be built from the parameters in `custom_profile`. |\n| `mode`                                    | True     | string  | `direct`  | Possible values are `direct` or `search`. Use `search` if you want to use a non-spotify `media_player`. Use `direct` when using a spotify `media_player`.                                                       |\n| `max_retries`                             | True     | number  | `1`       | Number of times a Spotify API call should be retried after a connection error before the track is skipped.                                                                                                      |\n| `custom_profile`                          | True     | object  |           | Parameters to use for the `custom` `color_profile`. See `Custom color profile` section.                                                                                                                         |\n| `custom_profile.color_mode`               | False    | string  |           | Possible values are 'rgb' or 'hs'. See `Custom color profile` section.                                                                                                                                          |\n| `custom_profile.global_weight`            | True     | number  | `1`       | Used in 'rgb' mode. Weight applied to all sampling points. See `Custom color profile` section.                                                                                                                  |\n| `custom_profile.sample_data`              | False    | object  |           | Used in 'rgb' mode. Sample data consisting of point-color pairs. See `Custom color profile` section.                                                                                                            |\n| `custom_profile.sample_data.point`        | False    | tuple   |           | Used in 'rgb' mode. A point in the [0, 1]X[0, 1] range. See `Custom color profile` section.                                                                                                                     |\n| `custom_profile.sample_data.color`        | False    | tuple   |           | Used in 'rgb' mode. An RGB color value in the [0,255] range for each channel. See `Custom color profile` section.                                                                                               |\n| `custom_profile.sample_data.local_weight` | True     | number  | `1`       | Used in 'rgb' mode. Weight applied to the sample point. See `Custom color profile` section.                                                                                                                     |\n| `custom_profile.mirror_x`                 | True     | boolean | `False`   | Used in 'hs' mode. Mirrors the hue angle in the x direction. See `Custom color profile` section.                                                                                                                |\n| `custom_profile.mirror_y`                 | True     | boolean | `False`   | Used in 'hs' mode. Mirrors the hue angle in the y direction. See `Custom color profile` section.                                                                                                                |\n| `custom_profile.rotation`                 | True     | number  | `0`       | Used in 'hs' mode. Rotates the hue angle. See `Custom color profile` section.                                                                                                                                   |\n| `custom_profile.drop_off`                 | True     | number  | `1`       | Used in 'hs' mode. How fast the saturation drops off towards the center (0 for no saturation loss). See `Custom color profile` section.                                                                         |\n| `color_map_image`                         | True     | object  |           | Output the color map as an image for debugging.                                                                                                                                                                 |\n| `color_map_image.size`                    | False    | number  |           | Size (height=width) of the output image in pixels.                                                                                                                                                              |\n| `color_map_image.location`                | False    | string  |           | Path to which the image should be saved.                                                                                                                                                                        |\n\n## Custom color profile\n\nYou can create your own color profile for the app to use by specifying the `custom_profile` app argument and\nsetting `color_profile` to `custom`.\nThe mood of a song is a 2-dimensional value in the range `[0.0,1.0]`x`[0.0,1.0]` where the first axis is \nthe valence, and the second axis the energy of the song. In general, the color value for a song is then sampled from a \ncolor field based on where the mood value of that song lies on the 2D plane. See the [Spotify API](https://developer.spotify.com/documentation/web-api/reference/#object-audiofeaturesobject) for more \ninformation on these values.\n\nColor profiles use either the RGB or the HS color space with different methods for sampling colors, respectively. While \nRGB profiles perform an IDW interpolation, HS profiles simply map the positional information to a color circle. \nTherefore, the `custom_profile` profiles takes a different set of parameters depending on which option is given for \n`custom_profile.color_mode`.\n\n### RGB Profiles\nIn order to create an RGB color map the app expects a list of 2D sample points with a corresponding RGB color for each point.\nFor a given point on the mood plane, the color is then interpolated between the given sample points. \nTo give individual samples more weight you can add the `custom_profile.sample_data.local_weight` option to any point-color pair. \nAdditionally, the `custom_profile.global_weight` option gets applied to all points. \nA higher weight value effectively increases the influence radius of a color sample.\nFor reference, the following section replicates the default profile:\n```yaml\nspotify_mood_lights_sync:\n  color_profile: custom\n  custom_profile:\n    'color_mode': rgb\n    'global_weight': 2\n    'sample_data':\n      - 'point': [0.0, 0.5]\n        'color': [128, 0, 128]\n        'local_weight': 1\n      - 'point': [0.0, 1.0]\n        'color': [255, 0, 0]\n        'local_weight': 1\n      - 'point': [0.5, 1.0]\n        'color': [255, 165, 0]\n        'local_weight': 1\n      - 'point': [1.0, 1.0]\n        'color': [255, 255, 0]\n        'local_weight': 1\n      - 'point': [1.0, 0.0]\n        'color': [0, 205, 0]\n        'local_weight': 1\n      - 'point': [0.5, 0.0]\n        'color': [0, 180, 255]\n        'local_weight': 1\n      - 'point': [0.0, 0.0]\n        'color': [0, 0, 255]\n        'local_weight': 1\n```\n\n### HS Profiles\nFor HS profiles, the app calculates the angle and distance of the query point to the center of the mood plane. The angle\ngets mapped to a hue value while the distance maps to a saturation value. The origin for the hue angle is the \ncenter-right of the mood plane. This hue mapping can be mirrored and rotated. A drop-off factor is applied to the \nsaturation to modify the saturation curve, where a factor of 0 preserves full saturation for the whole color map. \nFor reference, the following section replicates the saturated profile:\n```yaml\nspotify_mood_lights_sync:\n  color_profile: custom\n  custom_profile:\n    color_mode': hs\n    mirror_x: True\n    mirror_y: False\n    rotation: -60\n    drop_off: 0\n```\n\n### Debugging color profiles\n\nIf you wish to view the color map currently in use, e.g. for debugging custom color profiles, you additionally need the\nfollowing packages. These are, however, _not_ needed for standard app operation:\n\n```yaml\npython_packages:\n  - Pillow\nsystem_packages:\n  - py3-pillow\n```\n\nAdding the `color_map_image` key in the config will prompt the app to generate an image file of the used color \nmap, where the x and y axes map to valence and energy, respectively. You can specify the pixel size, i.e. height and \nwidth, of the image and the location to which it should be saved.\n\n```yaml\nspotify_mood_lights_sync:\n  color_map_image:\n    size: 50\n    location: /config/www/spotify-lights-sync/test.png\n```\n\n## Acknowledgments\n\nThis project is based on the following projects:\n\n- https://github.com/ericmatte/ad-media-lights-sync\n- https://github.com/tyiannak/color_your_music_mood\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNiklasReiche%2Fad-spotify-mood-lights-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNiklasReiche%2Fad-spotify-mood-lights-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNiklasReiche%2Fad-spotify-mood-lights-sync/lists"}