music-light

luz-musica.py changes a Home Assistant light to match the active media artwork.

Home Manager integration

This repository includes a Home Manager module at home-manager/music-light.nix that creates:

• a systemd --user service called music-light.service
• helper commands:
  • toggle-music-light
  • start-music-light
  • stop-music-light
  • music-light-status
• an optional desktop launcher: Music Light Toggle

1. Import the module

Add this to your Home Manager configuration:

{
  imports = [
    /home/vini/music-light/home-manager/music-light.nix
  ];

  programs.music-light = {
    enable = true;
    scriptDir = "/home/vini/music-light";
    pythonPath = "/usr/bin/python3";
    playerctlPath = "/usr/bin/playerctl";
    enableDesktopEntry = true;
    autostart = false;
  };
}

If your Home Manager config is inside a flake, add the module to the relevant homeManagerConfiguration.

2. Install the host runtime on Ubuntu

On the Ubuntu host, install the runtime used by the service:

sudo apt update
sudo apt install -y python3 python3-venv playerctl
cd /home/vini/music-light
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Then point Home Manager at the venv interpreter:

programs.music-light.pythonPath = "/home/vini/music-light/.venv/bin/python";

If you prefer system-wide Python packages instead of a venv, keep pythonPath = "/usr/bin/python3" and make sure requests and Pillow are installed on the host.

3. Apply Home Manager for the host user

The service must run in the host user's systemd --user, not inside the Docker container.

The Docker container can generate the Home Manager files as long as it writes into the real home directory used by the Ubuntu user. After activation, reload the user units on the host:

systemctl --user daemon-reload

Then control it with:

toggle-music-light
music-light-status
start-music-light
stop-music-light
journalctl --user -u music-light.service -f

4. Desktop button

With enableDesktopEntry = true, Home Manager creates a launcher named Music Light Toggle.

It typically appears in:

• the application menu
• launchers that read .desktop files
• ~/.local/share/applications/

The generated launcher simply runs toggle-music-light, which starts or stops music-light.service.

Important detail about Docker + Ubuntu host

If Home Manager is executed inside a container, that is fine for generating the user configuration files, but:

• the target home directory must be the real home directory used by the host user
• the service is started by the host's systemd --user
• python3, playerctl, the virtualenv, and the media-session DBus must all be available on the host
• the service must not point to executables that exist only inside the container or its /nix/store

If systemctl --user inside the container does not control the host user session, run the final activation from the host side.