linux-wallpaperengine: add module

linux-wallpaperengine is an implementation of Wallpaper Engine on
Linux, this module allows it to be declaractively configured.

modules/misc/news.nix

@@ -1997,6 +1997,17 @@ in {
           See https://github.com/nikitabobko/AeroSpace for more.
         '';
       }
+
+      {
+        time = "2025-01-30T09:18:55+00:00";
+        condition = hostPlatform.isLinux;
+        message = ''
+          A new module is available: 'services.linux-wallpaperengine'.
+
+          Reproduce the background functionality of Wallpaper Engine on Linux
+          systems.
+        '';
+      }
     ];
   };
 }

modules/modules.nix

@@ -332,6 +332,7 @@ let
     ./services/keybase.nix
     ./services/keynav.nix
     ./services/lieer.nix
+    ./services/linux-wallpaperengine.nix
     ./services/listenbrainz-mpd.nix
     ./services/lorri.nix
     ./services/mako.nix

modules/services/linux-wallpaperengine.nix

@@ -0,0 +1,121 @@
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+let
+
+  cfg = config.services.linux-wallpaperengine;
+
+in {
+  meta.maintainers = [ hm.maintainers.ckgxrg ];
+
+  options.services.linux-wallpaperengine = {
+    enable = mkEnableOption
+      "linux-wallpaperengine, an implementation of Wallpaper Engine functionality";
+
+    package = mkPackageOption pkgs "linux-wallpaperengine" { };
+
+    assetsPath = mkOption {
+      type = types.path;
+      description = "Path to the assets directory.";
+    };
+
+    clamping = mkOption {
+      type = types.nullOr (types.enum [ "clamp" "border" "repeat" ]);
+      default = null;
+      description = "Clamping mode for all wallpapers.";
+    };
+
+    wallpapers = mkOption {
+      type = types.listOf (types.submodule {
+        options = {
+          monitor = mkOption {
+            type = types.str;
+            description = "Which monitor to display the wallpaper.";
+          };
+
+          wallpaperId = mkOption {
+            type = types.str;
+            description = "Wallpaper ID to be used.";
+          };
+
+          extraOptions = mkOption {
+            type = types.listOf types.str;
+            default = [ ];
+            description =
+              "Extra arguments to pass to the linux-wallpaperengine command for this wallpaper.";
+          };
+
+          scaling = mkOption {
+            type =
+              types.nullOr (types.enum [ "stretch" "fit" "fill" "default" ]);
+            default = null;
+            description = "Scaling mode for this wallpaper.";
+          };
+
+          fps = mkOption {
+            type = types.nullOr types.int;
+            default = null;
+            description = "Limits the FPS to a given number.";
+          };
+
+          audio = {
+            silent = mkOption {
+              type = types.bool;
+              default = false;
+              description = "Mutes all sound of the wallpaper.";
+            };
+
+            automute = mkOption {
+              type = types.bool;
+              default = true;
+              description = "Automute when another app is playing sound.";
+            };
+
+            processing = mkOption {
+              type = types.bool;
+              default = true;
+              description = "Enables audio processing for background.";
+            };
+          };
+        };
+      });
+      default = [ ];
+      description = "Define wallpapers.";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    assertions = [
+      (lib.hm.assertions.assertPlatform "services.linux-wallpaperengine" pkgs
+        lib.platforms.linux)
+    ];
+
+    home.packages = [ cfg.package ];
+
+    systemd.user.services."linux-wallpaperengine" = let
+      args = lists.forEach cfg.wallpapers (each:
+        concatStringsSep " " (cli.toGNUCommandLine { } {
+          screen-root = each.monitor;
+          inherit (each) scaling fps;
+          silent = each.audio.silent;
+          noautomute = !each.audio.automute;
+          no-audio-processing = !each.audio.processing;
+        } ++ each.extraOptions)
+        # This has to be the last argument in each group
+        + " --bg ${each.wallpaperId}");
+    in {
+      Unit = {
+        Description = "Implementation of Wallpaper Engine on Linux";
+        After = [ "graphical-session.target" ];
+        PartOf = [ "graphical-session.target" ];
+      };
+      Service = {
+        ExecStart = getExe cfg.package + " --assets-dir ${cfg.assetsPath} "
+          + "--clamping ${cfg.clamping} " + (strings.concatStringsSep " " args);
+        Restart = "on-failure";
+      };
+      Install = { WantedBy = [ "graphical-session.target" ]; };
+    };
+  };
+}

tests/default.nix

@@ -267,6 +267,7 @@ in import nmtSrc {
     ./modules/services/imapnotify
     ./modules/services/kanshi
     ./modules/services/lieer
+    ./modules/services/linux-wallpaperengine
     ./modules/services/mopidy
     ./modules/services/mpd
     ./modules/services/mpd-mpris

tests/modules/services/linux-wallpaperengine/basic-configuration-expected.service

@@ -0,0 +1,11 @@
+[Install]
+WantedBy=graphical-session.target
+
+[Service]
+ExecStart=@linux-wallpaperengine@/bin/dummy --assets-dir /some/path/to/assets --clamping border --fps 6 --scaling fit --screen-root HDMI-1 --bg 12345678 --no-audio-processing --noautomute --screen-root DP-1 --silent --scaling fill --fps 12 --bg 87654321
+Restart=on-failure
+
+[Unit]
+After=graphical-session.target
+Description=Implementation of Wallpaper Engine on Linux
+PartOf=graphical-session.target

tests/modules/services/linux-wallpaperengine/basic-configuration.nix

@@ -0,0 +1,35 @@
+{ config, pkgs, ... }:
+
+{
+  services.linux-wallpaperengine = {
+    enable = true;
+    assetsPath = "/some/path/to/assets";
+    clamping = "border";
+    wallpapers = [
+      {
+        monitor = "HDMI-1";
+        wallpaperId = "12345678";
+        scaling = "fit";
+        fps = 6;
+      }
+      {
+        monitor = "DP-1";
+        wallpaperId = "87654321";
+        extraOptions = [ "--scaling fill" "--fps 12" ];
+        audio = {
+          silent = true;
+          automute = false;
+          processing = false;
+        };
+      }
+    ];
+  };
+
+  test.stubs.linux-wallpaperengine = { };
+
+  nmt.script = ''
+    assertFileContent \
+        home-files/.config/systemd/user/linux-wallpaperengine.service \
+        ${./basic-configuration-expected.service}
+  '';
+}

tests/modules/services/linux-wallpaperengine/default.nix

@@ -0,0 +1 @@
+{ linux-wallpaperengine-basic-configuration = ./basic-configuration.nix; }