7: packaging — systemd user unit + Nix modules + README

Ships the daemon as a real installable, not just `cargo build`.

Artifacts

  - `contrib/systemd/headroom.service` — user-scope unit. Type=simple
    (the daemon doesn't fork), After=pipewire.service, Restart=on-
    failure with a 2 s back-off so a crash loop doesn't spam stderr,
    StandardOutput/Error=journal, LimitRTPRIO=20 / LimitNICE=-11 to
    match the rtkit-style grant PipeWire's own unit carries. The
    file is templated with `@bindir@` so the build derivation can
    substitute in an absolute store path at install time, without
    the unit having to rely on whatever `headroom` happens to be on
    PATH.

  - `nix/home-module.nix` — `services.headroom.enable`. Installs the
    package on the user's PATH, symlinks the shipped profiles into
    `$XDG_CONFIG_HOME/headroom/profiles/`, and writes the systemd
    user unit (start After=pipewire.service Requires=pipewire.service
    Wants=wireplumber.service WantedBy=pipewire.service). Knobs:
    `installDefaultProfiles` for users who maintain their own set,
    `extraProfiles` (attrset of filename → path) to drop in personal
    profiles that override shipped ones by name.

  - `nix/nixos-module.nix` — `programs.headroom.enable`. Narrow scope:
    binary on global PATH, the package's `lib/systemd/user/*.service`
    is materialised under `/etc/systemd/user/` via `systemd.packages`,
    and an assertion fires if pipewire isn't enabled (clearer than a
    runtime crash). Per-user defaults (profile install, RT priority
    tuning) live in the Home Manager module; the two compose.

Build derivation

  `postInstall` now installs the unit (with `@bindir@` substituted to
  `$out/bin`) and copies `profiles/*.toml` to
  `$out/share/headroom/profiles/`. The flake's version lookup moved
  from `crates/headroom-cli/Cargo.toml` (where `version.workspace =
  true` evaluates to a table, not a string) to the workspace
  `Cargo.toml`. Modules exposed under `nixosModules.default` and
  `homeModules.default`.

README

  Rewrote the install section: Nix flake-based install with both
  Home Manager and NixOS module examples, plus a from-scratch
  `cargo install` + `install`/`sed` recipe for non-Nix users. Added
  a usage section with the common `headroom` subcommands and bumped
  the status banner from "pre-alpha" to "alpha" (signal chain,
  routing, IPC, monitor TUI, profile reload, and packaging all work
  end-to-end now).

Verified

  - `nix flake check` passes; NixOS module type-checks under
    nixpkgs eval.
  - `nix build .#headroom` produces `bin/headroom`,
    `lib/systemd/user/headroom.service` with the absolute store-path
    ExecStart baked in, and all five shipped profiles under
    `share/headroom/profiles/`.
  - `systemd-analyze verify --user` accepts the unit.
  - 185 workspace tests still pass; clippy clean at -D warnings
    --all-targets; `nix fmt` happy.

nix/home-module.nix

@@ -0,0 +1,119 @@
+# Home Manager module — installs the headroom binary, the systemd
+# user service, and (optionally) a default set of profiles into the
+# user's XDG_CONFIG_HOME.
+#
+# Headroom is a per-user daemon that talks to PipeWire over the user
+# session, so the Home Manager scope is its natural install point. A
+# separate NixOS module (./nixos-module.nix) covers the case where the
+# user wants `headroom` on every account's PATH or wants to enable the
+# service at the system level via systemd-user; that module simply
+# delegates the heavy lifting to `services.headroom` (this file) when
+# Home Manager is in use.
+self:
+{ config, lib, pkgs, ... }:
+
+let
+  inherit (lib) mkEnableOption mkOption mkIf types literalExpression;
+
+  cfg = config.services.headroom;
+
+  package = cfg.package;
+
+  # Profiles shipped by the package, suitable for symlinking into the
+  # user's XDG_CONFIG_HOME so they show up in `headroom profile list`
+  # without the user having to copy them by hand.
+  shippedProfilesDir = "${package}/share/headroom/profiles";
+in
+{
+  options.services.headroom = {
+    enable = mkEnableOption "Headroom — PipeWire AGC + compressor + true-peak limiter daemon";
+
+    package = mkOption {
+      type = types.package;
+      default = self.packages.${pkgs.system}.headroom;
+      defaultText = literalExpression "headroom.packages.\${pkgs.system}.headroom";
+      description = ''
+        The headroom package to install. Override to pin a local
+        build (e.g. `path:/home/me/code/headroom`) when iterating.
+      '';
+    };
+
+    installDefaultProfiles = mkOption {
+      type = types.bool;
+      default = true;
+      description = ''
+        Symlink the profiles shipped with the package into
+        `$XDG_CONFIG_HOME/headroom/profiles/`. Disable if you
+        maintain your own profile set and don't want the shipped
+        ones cluttering `headroom profile list`.
+      '';
+    };
+
+    extraProfiles = mkOption {
+      type = types.attrsOf types.path;
+      default = { };
+      example = literalExpression ''
+        {
+          "studio.toml" = ./profiles/studio.toml;
+        }
+      '';
+      description = ''
+        Additional profile TOML files to drop into the user's
+        profile directory, keyed by filename. Overrides any
+        identically-named shipped profile.
+      '';
+    };
+  };
+
+  config = mkIf cfg.enable {
+    home.packages = [ package ];
+
+    # Symlink shipped profiles + any user-provided extras into the
+    # user's XDG_CONFIG_HOME. The daemon's profile watcher
+    # (notify-debouncer-mini) treats symlinks identically to
+    # regular files, so this is transparent.
+    xdg.configFile = lib.mkMerge [
+      (mkIf cfg.installDefaultProfiles (
+        lib.mapAttrs'
+          (name: _: lib.nameValuePair "headroom/profiles/${name}" {
+            source = "${shippedProfilesDir}/${name}";
+          })
+          (builtins.readDir shippedProfilesDir)
+      ))
+      (lib.mapAttrs'
+        (name: path: lib.nameValuePair "headroom/profiles/${name}" {
+          source = path;
+        })
+        cfg.extraProfiles)
+    ];
+
+    # systemd user unit. The unit shipped by the package already
+    # carries the right ExecStart with an absolute path baked in,
+    # so we just symlink it into the user's services directory and
+    # let Home Manager start it via its systemd-user machinery.
+    systemd.user.services.headroom = {
+      Unit = {
+        Description = "Headroom audio daemon (PipeWire AGC + compressor + true-peak limiter)";
+        Documentation = "https://github.com/amaanq/headroom";
+        After = [ "pipewire.service" "pipewire-pulse.service" "wireplumber.service" ];
+        Requires = [ "pipewire.service" ];
+        Wants = [ "wireplumber.service" ];
+      };
+      Service = {
+        Type = "simple";
+        ExecStart = "${package}/bin/headroom daemon";
+        Restart = "on-failure";
+        RestartSec = "2s";
+        StandardOutput = "journal";
+        StandardError = "journal";
+        SyslogIdentifier = "headroom";
+        LimitRTPRIO = 20;
+        LimitRTTIME = 200000;
+        LimitNICE = -11;
+      };
+      Install = {
+        WantedBy = [ "pipewire.service" ];
+      };
+    };
+  };
+}