nixos/alsa: reintroduce hardware.alsa.enablePersistence (#373529)

nixos/doc/manual/release-notes/rl-2411.section.md

···
 
 If you set `sound.enable` in your configuration:
   - If you are using Pulseaudio or PipeWire, simply remove that option
-  - If you are using ALSA as your only sound system (no sound server), set `hardware.alsa.enable = true` instead
+  - If you are not using an external sound server, and want volumes to be persisted across shutdowns, set `hardware.alsa.enablePersistence = true` instead
 
 If you set `sound.enableOSSEmulation` in your configuration:
   - Make sure it is still necessary, as very few applications actually use OSS
-  - If necessary, set `hardware.alsa.enableOSSEmulation = true`
+  - If necessary, set `boot.kernelModules = [ "snd_pcm_oss" ]`
 
 If you set `sound.extraConfig` in your configuration:
-  - If you are using a sound server, like Pulseaudio, JACK or PipeWire, migrate your configuration to that
-  - If you are using ALSA as your only sound system, check if you can use the new structured ALSA options `hardware.alsa.defaultDevice`, `hardware.alsa.cardAliases`, `hardware.alsa.controls`, etc.
-  - Otherwise, move your configuration directly into `hardware.alsa.config`
+  - If you are using another sound server, like Pulseaudio, JACK or PipeWire, migrate your configuration to that
+  - If you are not using an external sound server, set `environment.etc."asound.conf".text = yourExtraConfig` instead
 
 If you set `sound.mediaKeys` in your configuration:
   - Preferably switch to handling media keys in your desktop environment/compositor

nixos/doc/manual/release-notes/rl-2505.section.md

···
 - The paperless module now has an option for regular automatic export of
   documents data using the integrated document exporter.
 
+- New options for the declarative configuration of the user space part of ALSA have been introduced under [hardware.alsa](options.html#opt-hardware.alsa.enable), including setting the default capture and playback device, defining sound card aliases and volume controls.
+  Note: these are intended for users not running a sound server like PulseAudio or PipeWire, but having ALSA as their only sound system.
+
 - Caddy can now be built with plugins by using `caddy.withPlugins`, a `passthru` function that accepts an attribute set as a parameter. The `plugins` argument represents a list of Caddy plugins, with each Caddy plugin being a versioned module. The `hash` argument represents the `vendorHash` of the resulting Caddy source code with the plugins added.
 
   Example:

nixos/modules/services/audio/alsa.nix

···
       [ "sound" "enableOSSEmulation" ]
       [ "hardware" "alsa" "enableOSSEmulation" ]
     )
-    (lib.mkRenamedOptionModule
-      [ "sound" "extraConfig" ]
-      [ "hardware" "alsa" "config" ])
+    (lib.mkRenamedOptionModule [ "sound" "extraConfig" ] [ "hardware" "alsa" "config" ])
   ];
 
   options.hardware.alsa = {
···
           };
         })
       );
-      default = {};
+      default = { };
       example = lib.literalExpression ''
         {
           firefox = { device = "front"; maxVolume = -25.0; };
···
 
   };
 
-  config = lib.mkIf cfg.enable {
+  options.hardware.alsa.enablePersistence = lib.mkOption {
+    type = lib.types.bool;
+    defaultText = lib.literalExpression "config.hardware.alsa.enable";
+    default = config.hardware.alsa.enable;
+    description = ''
+      Whether to enable ALSA sound card state saving on shutdown.
+      This is generally not necessary if you're using an external sound server.
+    '';
+  };
 
-    # Disable sound servers enabled by default and,
-    # if the user enabled one manually, cause a conflict.
-    services.pipewire.enable = false;
-    hardware.pulseaudio.enable = false;
+  config = lib.mkMerge [
 
-    hardware.alsa.config =
-      let
-        conf = [
-          ''
-            pcm.!default fromenv
+    (lib.mkIf cfg.enable {
+      # Disable sound servers enabled by default and,
+      # if the user enabled one manually, cause a conflict.
+      services.pipewire.enable = false;
+      services.pulseaudio.enable = false;
 
-            # Read the capture and playback device from
-            # the ALSA_AUDIO_IN, ALSA_AUDIO_OUT variables
-            pcm.fromenv {
-              type asym
-              playback.pcm {
-                type plug
-                slave.pcm {
-                  @func getenv
-                  vars [ ALSA_AUDIO_OUT ]
-                  default pcm.sysdefault
+      hardware.alsa.config =
+        let
+          conf = [
+            ''
+              pcm.!default fromenv
+
+              # Read the capture and playback device from
+              # the ALSA_AUDIO_IN, ALSA_AUDIO_OUT variables
+              pcm.fromenv {
+                type asym
+                playback.pcm {
+                  type plug
+                  slave.pcm {
+                    @func getenv
+                    vars [ ALSA_AUDIO_OUT ]
+                    default pcm.sysdefault
+                  }
                 }
-              }
-              capture.pcm {
-                type plug
-                slave.pcm {
-                  @func getenv
-                  vars [ ALSA_AUDIO_IN ]
-                  default pcm.sysdefault
+                capture.pcm {
+                  type plug
+                  slave.pcm {
+                    @func getenv
+                    vars [ ALSA_AUDIO_IN ]
+                    default pcm.sysdefault
+                  }
                 }
               }
-            }
-          ''
-          (lib.optional cfg.enableRecorder ''
-            pcm.!default "splitter:fromenv,recorder"
+            ''
+            (lib.optional cfg.enableRecorder ''
+              pcm.!default "splitter:fromenv,recorder"
 
-            # Send audio to two stereo devices
-            pcm.splitter {
-              @args [ A B ]
-              @args.A.type string
-              @args.B.type string
-              type asym
-              playback.pcm {
-                type plug
-                route_policy "duplicate"
-                slave.pcm {
-                  type multi
-                  slaves.a.pcm $A
-                  slaves.b.pcm $B
-                  slaves.a.channels 2
-                  slaves.b.channels 2
-                  bindings [
-                   { slave a channel 0 }
-                   { slave a channel 1 }
-                   { slave b channel 0 }
-                   { slave b channel 1 }
-                  ]
+              # Send audio to two stereo devices
+              pcm.splitter {
+                @args [ A B ]
+                @args.A.type string
+                @args.B.type string
+                type asym
+                playback.pcm {
+                  type plug
+                  route_policy "duplicate"
+                  slave.pcm {
+                    type multi
+                    slaves.a.pcm $A
+                    slaves.b.pcm $B
+                    slaves.a.channels 2
+                    slaves.b.channels 2
+                    bindings [
+                     { slave a channel 0 }
+                     { slave a channel 1 }
+                     { slave b channel 0 }
+                     { slave b channel 1 }
+                    ]
+                  }
                 }
+                capture.pcm $A
               }
-              capture.pcm $A
-            }
 
-            # Device which records and plays back audio
-            pcm.recorder {
-              type asym
-              capture.pcm {
-                type dsnoop
-                ipc_key 9165218
-                ipc_perm 0666
-                slave.pcm "hw:loopback,1,0"
-                slave.period_size 1024
-                slave.buffer_size 8192
-              }
-              playback.pcm {
-                type dmix
-                ipc_key 6181923
-                ipc_perm 0666
-                slave.pcm "hw:loopback,0,0"
-                slave.period_size 1024
-                slave.buffer_size 8192
+              # Device which records and plays back audio
+              pcm.recorder {
+                type asym
+                capture.pcm {
+                  type dsnoop
+                  ipc_key 9165218
+                  ipc_perm 0666
+                  slave.pcm "hw:loopback,1,0"
+                  slave.period_size 1024
+                  slave.buffer_size 8192
+                }
+                playback.pcm {
+                  type dmix
+                  ipc_key 6181923
+                  ipc_perm 0666
+                  slave.pcm "hw:loopback,0,0"
+                  slave.period_size 1024
+                  slave.buffer_size 8192
+                }
               }
-            }
-          '')
-          (lib.mapAttrsToList mkControl cfg.controls)
-          (lib.mapAttrsToList (n: v: "pcm.${n} ${quote v}") cfg.deviceAliases)
-        ];
-      in
-      lib.mkBefore (lib.concatStringsSep "\n" (lib.flatten conf));
+            '')
+            (lib.mapAttrsToList mkControl cfg.controls)
+            (lib.mapAttrsToList (n: v: "pcm.${n} ${quote v}") cfg.deviceAliases)
+          ];
+        in
+        lib.mkBefore (lib.concatStringsSep "\n" (lib.flatten conf));
 
-    hardware.alsa.cardAliases = lib.mkIf cfg.enableRecorder {
-      loopback.driver = "snd_aloop";
-      loopback.id = 2;
-    };
+      hardware.alsa.cardAliases = lib.mkIf cfg.enableRecorder {
+        loopback.driver = "snd_aloop";
+        loopback.id = 2;
+      };
 
-    # Set default PCM devices
-    environment.sessionVariables = defaultDeviceVars;
-    systemd.globalEnvironment = defaultDeviceVars;
+      # Set default PCM devices
+      environment.sessionVariables = defaultDeviceVars;
+      systemd.globalEnvironment = defaultDeviceVars;
 
-    environment.etc."asound.conf".text = cfg.config;
+      environment.etc."asound.conf".text = cfg.config;
 
-    boot.kernelModules =
-      [ ]
-      ++ lib.optionals cfg.enableOSSEmulation [ "snd_pcm_oss" "snd_mixer_oss" ]
-      ++ lib.optionals cfg.enableRecorder [ "snd_aloop" ];
+      boot.kernelModules =
+        [ ]
+        ++ lib.optionals cfg.enableOSSEmulation [
+          "snd_pcm_oss"
+          "snd_mixer_oss"
+        ]
+        ++ lib.optionals cfg.enableRecorder [ "snd_aloop" ];
 
-    # Assign names to the sound cards
-    boot.extraModprobeConfig = lib.concatStringsSep "\n" cardsConfig;
+      # Assign names to the sound cards
+      boot.extraModprobeConfig = lib.concatStringsSep "\n" cardsConfig;
 
-    # Provide alsamixer, aplay, arecord, etc.
-    environment.systemPackages = [ pkgs.alsa-utils ];
+      # Provide alsamixer, aplay, arecord, etc.
+      environment.systemPackages = [ pkgs.alsa-utils ];
+    })
 
-    # Install udev rules for restoring card settings on boot
-    services.udev.extraRules = ''
-      ACTION=="add", SUBSYSTEM=="sound", KERNEL=="controlC*", KERNELS!="card*", GOTO="alsa_restore_go"
-      GOTO="alsa_restore_end"
+    (lib.mkIf config.hardware.alsa.enablePersistence {
 
-      LABEL="alsa_restore_go"
-      TEST!="/etc/alsa/state-daemon.conf", RUN+="${alsactl} restore -gU $attr{device/number}"
-      TEST=="/etc/alsa/state-daemon.conf", RUN+="${alsactl} nrestore -gU $attr{device/number}"
-      LABEL="alsa_restore_end"
-    '';
+      # Install udev rules for restoring card settings on boot
+      services.udev.extraRules = ''
+        ACTION=="add", SUBSYSTEM=="sound", KERNEL=="controlC*", KERNELS!="card*", GOTO="alsa_restore_go"
+        GOTO="alsa_restore_end"
 
-    # Service to store/restore the sound card settings
-    systemd.services.alsa-store = {
-      description = "Store Sound Card State";
-      wantedBy = [ "multi-user.target" ];
-      restartIfChanged = false;
-      unitConfig = {
-        RequiresMountsFor = "/var/lib/alsa";
-        ConditionVirtualization = "!systemd-nspawn";
-      };
-      serviceConfig = {
-        Type = "oneshot";
-        RemainAfterExit = true;
-        StateDirectory = "alsa";
-        # Note: the service should never be restated, otherwise any
-        # setting changed between the last `store` and now will be lost.
-        # To prevent NixOS from starting it in case it has failed we
-        # expand the exit codes considered successful
-        SuccessExitStatus = [ 0 99 ];
-        ExecStart = "${alsactl} restore -gU";
-        ExecStop = "${alsactl} store -gU";
+        LABEL="alsa_restore_go"
+        TEST!="/etc/alsa/state-daemon.conf", RUN+="${alsactl} restore -gU $attr{device/number}"
+        TEST=="/etc/alsa/state-daemon.conf", RUN+="${alsactl} nrestore -gU $attr{device/number}"
+        LABEL="alsa_restore_end"
+      '';
+
+      # Service to store/restore the sound card settings
+      systemd.services.alsa-store = {
+        description = "Store Sound Card State";
+        wantedBy = [ "multi-user.target" ];
+        restartIfChanged = false;
+        unitConfig = {
+          RequiresMountsFor = "/var/lib/alsa";
+          ConditionVirtualization = "!systemd-nspawn";
+        };
+        serviceConfig = {
+          Type = "oneshot";
+          RemainAfterExit = true;
+          StateDirectory = "alsa";
+          # Note: the service should never be restated, otherwise any
+          # setting changed between the last `store` and now will be lost.
+          # To prevent NixOS from starting it in case it has failed we
+          # expand the exit codes considered successful
+          SuccessExitStatus = [
+            0
+            99
+          ];
+          ExecStart = "${alsactl} restore -gU";
+          ExecStop = "${alsactl} store -gU";
+        };
       };
-    };
-  };
+    })
+
+  ];
 
   meta.maintainers = with lib.maintainers; [ rnhmjoj ];