# ~/nixos/modules/nixos/desktop/audio.nix
#
# Baseline audio stack:
# - PipeWire as the audio server
# - PulseAudio compatibility via pipewire-pulse
# - ALSA compatibility (+ 32-bit ALSA for games/legacy)
# - WirePlumber session manager
# - RTKit for better realtime scheduling (often reduces crackling under load)
#
# IMPORTANT (NixOS option churn):
# - On some nixpkgs revisions the old `hardware.pulseaudio` option was renamed to
#   `services.pulseaudio`. We set the *services* one explicitly.
# - Avoid `lib.mkForce` on pulseaudio enable/disable here because certain revisions
#   have had type/override weirdness; use plain booleans instead.

{ config, lib, pkgs, ... }:

let
  moduleName = "nixos-audio";
in
{
  # ---- Disable the standalone PulseAudio daemon ----
  #
  # We want PipeWire to provide PulseAudio compatibility (pipewire-pulse),
  # not a separate pulseaudio service.
  services.pulseaudio.enable = false;

  # ---- PipeWire ----
  services.pipewire = {
    enable = true;

    # PulseAudio compatibility server (pipewire-pulse)
    pulse.enable = true;

    # ALSA compatibility (+ 32-bit for Steam/older apps)
    alsa = {
      enable = true;
      support32Bit = true;
    };

    # Recommended policy/session manager
    wireplumber.enable = true;

    # Optional JACK compatibility (leave off unless you need it)
    jack.enable = false;
  };

  # Realtime scheduling broker commonly used by PipeWire
  security.rtkit.enable = true;

  # Useful tooling
  environment.systemPackages = with pkgs; [
    pavucontrol
    helvum
    alsa-utils
  ];

  # Breadcrumb for debugging module load order
  environment.etc."nixlog/loaded.${moduleName}".text = "loaded\n";
}