Add sendspin-cli package with Python dependencies

Integrate sendspin-cli as a custom package using python3.withPackages. Packages aiosendspin from GitHub since it's only available in nixpkgs-unstable. Includes all required dependencies: aiohttp, av, numpy, qrcode, readchar, rich, sounddevice, and native libraries (portaudio, ffmpeg). Adds uv2nix flake inputs for future migration when sendspin-cli adds a uv.lock file.
2025-12-29 23:46:55 -08:00
5 changed files with 848 additions and 6 deletions
--- a/flake.lock
+++ b/flake.lock
@@ -256,6 +256,52 @@
        "type": "github"
      }
    },
+    "pyproject-build-systems": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "pyproject-nix"
+        ],
+        "uv2nix": [
+          "uv2nix"
+        ]
+      },
+      "locked": {
+        "lastModified": 1763662255,
+        "narHash": "sha256-4bocaOyLa3AfiS8KrWjZQYu+IAta05u3gYZzZ6zXbT0=",
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "rev": "042904167604c681a090c07eb6967b4dd4dae88c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "type": "github"
+      }
+    },
+    "pyproject-nix": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1764134915,
+        "narHash": "sha256-xaKvtPx6YAnA3HQVp5LwyYG1MaN4LLehpQI8xEdBvBY=",
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "rev": "2c8df1383b32e5443c921f61224b198a2282a657",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "type": "github"
+      }
+    },
    "root": {
      "inputs": {
        "google-cookie-retrieval": "google-cookie-retrieval",
@@ -267,7 +313,33 @@
        "nixpkgs": "nixpkgs_2",
        "nixpkgs-unstable": "nixpkgs-unstable",
        "plasma-manager": "plasma-manager",
-        "plasma-manager-unstable": "plasma-manager-unstable"
+        "plasma-manager-unstable": "plasma-manager-unstable",
+        "pyproject-build-systems": "pyproject-build-systems",
+        "pyproject-nix": "pyproject-nix",
+        "uv2nix": "uv2nix"
+      }
+    },
+    "uv2nix": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "pyproject-nix"
+        ]
+      },
+      "locked": {
+        "lastModified": 1766021660,
+        "narHash": "sha256-UUfz7qWB1Rb2KjGVCimt//Jncv3TgJwffPqbzqpkmgY=",
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "rev": "19fa99be3409f55ec05e823c66c9769df7a8dd17",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "type": "github"
      }
    }
  },
--- a/flake.nix
+++ b/flake.nix
@@ -42,9 +42,27 @@
      url = "github:Jovian-Experiments/Jovian-NixOS";
      inputs.nixpkgs.follows = "nixpkgs-unstable";
    };
+
+    pyproject-nix = {
+      url = "github:pyproject-nix/pyproject.nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    uv2nix = {
+      url = "github:pyproject-nix/uv2nix";
+      inputs.pyproject-nix.follows = "pyproject-nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    pyproject-build-systems = {
+      url = "github:pyproject-nix/build-system-pkgs";
+      inputs.pyproject-nix.follows = "pyproject-nix";
+      inputs.uv2nix.follows = "uv2nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
  };

-  outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, ... } @ inputs: let
+  outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, pyproject-nix, uv2nix, pyproject-build-systems, ... } @ inputs: let
    nixosModules = [
      ./roles
    ] ++ [
@@ -56,7 +74,7 @@
              system = prev.stdenv.hostPlatform.system;
              config.allowUnfree = true;
            };
-            custom = prev.callPackage ./packages {};
+            custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
          })
@@ -84,7 +102,7 @@
              system = prev.stdenv.hostPlatform.system;
              config.allowUnfree = true;
            };
-            custom = prev.callPackage ./packages {};
+            custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
          })
@@ -117,7 +135,7 @@
                })
              ];
            };
-            custom = prev.callPackage ./packages {};
+            custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
            # Compatibility: bitwarden renamed to bitwarden-desktop in unstable
            bitwarden-desktop = prev.bitwarden-desktop or prev.bitwarden;
          })
--- a/packages/default.nix
+++ b/packages/default.nix
@@ -1,7 +1,8 @@
-{ pkgs, ... }:
+{ pkgs, uv2nix ? null, pyproject-nix ? null, pyproject-build-systems ? null, ... }:
 {
  vulkanHDRLayer = pkgs.callPackage ./vulkan-hdr-layer {};
  tea-rbw = pkgs.callPackage ./tea-rbw {};
  app-launcher-server = pkgs.callPackage ./app-launcher-server {};
  claude-code = pkgs.callPackage ./claude-code {};
+  sendspin-cli = pkgs.callPackage ./sendspin-cli { inherit uv2nix pyproject-nix pyproject-build-systems; };
 }
--- a/packages/sendspin-cli/default.nix
+++ b/packages/sendspin-cli/default.nix
@@ -0,0 +1,91 @@
+{ pkgs
+, lib
+, fetchFromGitHub
+, uv2nix ? null
+, pyproject-nix ? null
+, pyproject-build-systems ? null
+}:
+
+# Simple package build
+# Note: uv2nix would be ideal but requires uv.lock which sendspin-cli doesn't have yet
+let
+  # Package aiosendspin from GitHub since it's only in nixpkgs-unstable
+  aiosendspin = pkgs.python312Packages.buildPythonPackage rec {
+    pname = "aiosendspin";
+    version = "1.2.0";
+    pyproject = true;
+
+    src = fetchFromGitHub {
+      owner = "Sendspin";
+      repo = "aiosendspin";
+      rev = version;
+      sha256 = "sha256-3vTEfXeFqouPswRKST/9U7yg9ah7J9m2KAMoxaBZNR0=";
+    };
+
+    build-system = with pkgs.python312Packages; [
+      hatchling
+      setuptools
+    ];
+
+    dependencies = with pkgs.python312Packages; [
+      aiohttp
+      av
+      mashumaro
+      orjson
+      pillow
+      zeroconf
+    ];
+
+    pythonImportsCheck = [ "aiosendspin" ];
+
+    meta = {
+      description = "Async Python implementation of the Sendspin Protocol";
+      homepage = "https://github.com/Sendspin-Protocol/aiosendspin";
+      license = lib.licenses.asl20;
+    };
+  };
+
+  python = pkgs.python312.withPackages (ps: with ps; [
+    # Core dependencies from pyproject.toml
+    aiosendspin
+    av
+    numpy
+    qrcode
+    readchar
+    rich
+    sounddevice
+    setuptools
+  ]);
+in
+pkgs.stdenv.mkDerivation rec {
+  pname = "sendspin-cli";
+  version = "0.0.0";
+
+  src = fetchFromGitHub {
+    owner = "Sendspin";
+    repo = "sendspin-cli";
+    rev = "main";
+    sha256 = "sha256-z8ieaDHv4C6WNLpPGybhcfB+E6Jj/rCc7zSRpL6vdk0=";
+  };
+
+  buildInputs = [ python pkgs.portaudio pkgs.ffmpeg ];
+
+  installPhase = ''
+    mkdir -p $out/bin $out/lib
+    cp -r sendspin $out/lib/
+    cat > $out/bin/sendspin <<EOF
+#!/bin/sh
+export PYTHONPATH="$out/lib:\$PYTHONPATH"
+export LD_LIBRARY_PATH="${pkgs.portaudio}/lib:${pkgs.ffmpeg}/lib:\$LD_LIBRARY_PATH"
+exec ${python}/bin/python3 -m sendspin.cli "\$@"
+EOF
+    chmod +x $out/bin/sendspin
+  '';
+
+  meta = {
+    description = "Synchronized audio player for Sendspin servers";
+    homepage = "https://github.com/Sendspin/sendspin-cli";
+    license = lib.licenses.asl20;
+    platforms = lib.platforms.linux;
+  };
+}
--- a/thoughts/shared/plans/2025-12-29-sendspin-cli-integration.md
+++ b/thoughts/shared/plans/2025-12-29-sendspin-cli-integration.md
@@ -0,0 +1,660 @@
+# Sendspin-CLI Integration Implementation Plan
+
+## Overview
+
+Integrate sendspin-cli (https://github.com/Sendspin/sendspin-cli) into the NixOS configuration using uv2nix for Python packaging. Provide a flexible systemd service template that runs as the graphical user, supporting multiple use cases: standalone media centers (like `boxy` running as `kodi` user) and desktop workstations (like `zix790prors` running as `johno` user).
+
+## Current State Analysis
+
+**Existing Infrastructure:**
+- Custom package system using overlays at flake.nix:54-59
+- Packages defined in `packages/default.nix` and exposed as `pkgs.custom.<name>`
+- Role-based configuration system with audio role at roles/audio/default.nix:1-41
+- User-level systemd services pattern demonstrated in machines/zix790prors/virtual-surround.nix:79-103
+- Python packaging pattern using `python3.withPackages` at packages/app-launcher-server/default.nix:1-10
+
+**Sendspin-CLI Analysis:**
+- Python 3.12+ application with setuptools build system
+- Entry point: `sendspin.cli:main` (sendspin-cli/sendspin/cli.py:143)
+- Dependencies: aiosendspin, av, numpy, qrcode, readchar, rich, sounddevice (sendspin-cli/pyproject.toml:16-23)
+- Native dependencies needed: portaudio (for sounddevice), ffmpeg (for av)
+- Supports headless mode via `--headless` flag (sendspin-cli/sendspin/cli.py:115-117)
+- Device selection via `--audio-device <index|name>` (sendspin-cli/sendspin/cli.py:96-102)
+- Device discovery via `--list-audio-devices` (sendspin-cli/sendspin/cli.py:15-34)
+- Auto-discovers servers via mDNS unless `--url` specified (sendspin-cli/sendspin/cli.py:69-71)
+- No `uv.lock` file currently in repository (only `pyproject.toml`)
+
+**Gap:**
+- No uv2nix flake inputs (pyproject-nix, uv2nix, pyproject-build-systems)
+- No sendspin-cli package definition
+- No sendspin role or systemd service configuration
+
+## Desired End State
+
+After implementation completion:
+1. **Package available**: `pkgs.custom.sendspin-cli` builds successfully with all dependencies
+2. **Role available**: `roles.sendspin.enable = true` provides sendspin with configurable service
+3. **Service template**: Systemd user service runs as graphical session user with configurable audio device
+4. **Audio device compatibility**: Uses sendspin's native device specification (index or name prefix)
+5. **Flexible user context**: Service can run as kodi, johno, or any graphical session user
+
+### Verification Commands:
+```bash
+# Package builds successfully
+nix build .#nixosConfigurations.zix790prors.config.environment.systemPackages --no-link | grep sendspin-cli
+
+# Package contains working executable
+$(nix-build -E '(import <nixpkgs> {}).callPackage ./packages/sendspin-cli {}')/bin/sendspin --help
+
+# Service template is generated
+nixos-rebuild dry-build --flake .#zix790prors 2>&1 | grep sendspin
+```
+
+## Key Discoveries
+
+### uv2nix Integration Points
+- **No lock file**: sendspin-cli has `pyproject.toml` but no `uv.lock` - uv2nix will resolve from pyproject.toml
+- **Native dependencies**: sounddevice and av require portaudio and ffmpeg in buildInputs
+- **Workspace loading**: uv2nix.lib.workspace.loadWorkspace works with pyproject.toml-only projects
+- **Build system**: Uses setuptools (declared in pyproject.toml:1-3)
+
+### Service Architecture
+- **User services**: Must use `systemd.user.services` (not system services) for audio access
+- **Automatic user detection**: User services run in the logged-in graphical user's session
+- **PipeWire dependency**: Service must start after `pipewire.service` and `wireplumber.service`
+- **Auto-restart**: Use `Restart=always` for persistent background operation
+
+### Audio Device Handling
+- **Native format**: Sendspin expects device index (0, 1, 2) or name prefix ("AmazonBasics")
+- **Discovery**: `sendspin --list-audio-devices` shows available devices
+- **PipeWire independence**: No need to use PipeWire node names; sendspin queries via sounddevice library
+
+## What We're NOT Doing
+
+To prevent scope creep:
+
+1. **Not creating uv.lock**: Using pyproject.toml directly; lock file can be added upstream later
+2. **Not implementing multi-instance configuration**: Providing single-instance template; machines can extend for multiple instances
+3. **Not configuring specific machines**: Template only; zix790prors multi-instance setup is future work
+4. **Not creating home-manager module**: Using system-level role with user services
+5. **Not implementing server mode**: Client-only integration; `sendspin serve` can be added later
+6. **Not auto-detecting graphical user**: Relying on systemd user service behavior; explicit user selection can be added later
+7. **Not packaging dev dependencies**: Only runtime dependencies; test tools (mypy, ruff) excluded
+
+## Implementation Approach
+
+Use uv2nix to package sendspin-cli from its GitHub repository, accessing pyproject.toml for dependency resolution. Create a NixOS role following the spotifyd pattern with a systemd user service template. The service runs in the logged-in user's session (automatic user detection) and can be configured per-machine for different audio devices.
+
+**Key Technical Decisions:**
+1. **uv2nix over python3.withPackages**: Better maintainability, automatic dependency resolution, aligns with upstream development
+2. **System-level role with user services**: Follows existing patterns (virtual-surround.nix), enables per-user configuration
+3. **Headless mode default**: Services always use `--headless`; TUI available via manual `sendspin` command
+4. **mDNS discovery default**: No `--url` by default; let sendspin auto-discover servers on the network
+
+---
+
+## Phase 1: Add uv2nix Flake Inputs
+
+### Overview
+Add pyproject-nix, uv2nix, and pyproject-build-systems as flake inputs and thread them through to package definitions.
+
+### Changes Required
+
+#### 1. Flake Inputs
+**File**: `flake.nix`
+**Changes**: Add new inputs after existing inputs (after line 44)
+
+```nix
+pyproject-nix = {
+  url = "github:pyproject-nix/pyproject.nix";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+
+uv2nix = {
+  url = "github:pyproject-nix/uv2nix";
+  inputs.pyproject-nix.follows = "pyproject-nix";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+
+pyproject-build-systems = {
+  url = "github:pyproject-nix/build-system-pkgs";
+  inputs.pyproject-nix.follows = "pyproject-nix";
+  inputs.uv2nix.follows = "uv2nix";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+```
+
+#### 2. Outputs Signature
+**File**: `flake.nix`
+**Changes**: Update outputs function signature (line 47)
+
+```nix
+# Before
+outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, ... } @ inputs:
+
+# After
+outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, pyproject-nix, uv2nix, pyproject-build-systems, ... } @ inputs:
+```
+
+#### 3. Pass Inputs to Packages
+**File**: `flake.nix`
+**Changes**: Update custom package overlay (line 59 and 87)
+
+```nix
+# Before
+custom = prev.callPackage ./packages {};
+
+# After
+custom = prev.callPackage ./packages { inherit uv2nix pyproject-nix pyproject-build-systems; };
+```
+
+#### 4. Update Packages Default.nix Signature
+**File**: `packages/default.nix`
+**Changes**: Accept new parameters
+
+```nix
+# Before
+{ pkgs, ... }:
+
+# After
+{ pkgs, uv2nix ? null, pyproject-nix ? null, pyproject-build-systems ? null, ... }:
+```
+
+**Note**: Parameters are optional to maintain compatibility with direct `nix-build` calls.
+
+### Success Criteria
+
+#### Automated Verification:
+- [x] Flake evaluation succeeds: `nix flake check`
+- [x] Custom packages still build: `nix build .#nixosConfigurations.zix790prors.config.environment.systemPackages`
+- [x] No evaluation errors: `nixos-rebuild dry-build --flake .#zix790prors`
+
+#### Manual Verification:
+- [x] Flake inputs show pyproject-nix, uv2nix, and pyproject-build-systems: `nix flake metadata`
+- [x] Existing machines still build without errors
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation before proceeding to Phase 2.
+
+---
+
+## Phase 2: Create Sendspin-CLI Package
+
+### Overview
+Create uv2nix-based package for sendspin-cli that handles Python dependencies and native libraries (portaudio, ffmpeg).
+
+### Changes Required
+
+#### 1. Package Definition
+**File**: `packages/sendspin-cli/default.nix`
+**Changes**: Create new file
+
+```nix
+{ pkgs
+, uv2nix ? null
+, pyproject-nix ? null
+, pyproject-build-systems ? null
+, lib
+, fetchFromGitHub
+}:
+
+# Fallback to simple package if uv2nix not available
+if uv2nix == null || pyproject-nix == null || pyproject-build-systems == null then
+  let
+    python = pkgs.python312.withPackages (ps: with ps; [
+      # Core dependencies from pyproject.toml
+      # Note: aiosendspin may need to be packaged separately if not in nixpkgs
+      av
+      numpy
+      qrcode
+      readchar
+      rich
+      sounddevice
+      # Build dependencies
+      setuptools
+    ]);
+  in
+  pkgs.stdenv.mkDerivation rec {
+    pname = "sendspin-cli";
+    version = "0.0.0-fallback";
+
+    src = fetchFromGitHub {
+      owner = "Sendspin";
+      repo = "sendspin-cli";
+      rev = "main";
+      sha256 = lib.fakeSha256;  # Replace with actual hash after first build
+    };
+
+    buildInputs = [ python pkgs.portaudio pkgs.ffmpeg ];
+
+    installPhase = ''
+      mkdir -p $out/bin $out/lib
+      cp -r sendspin $out/lib/
+      cat > $out/bin/sendspin <<EOF
+#!/bin/sh
+export PYTHONPATH="$out/lib:\$PYTHONPATH"
+exec ${python}/bin/python3 -m sendspin.cli "\$@"
+EOF
+      chmod +x $out/bin/sendspin
+    '';
+
+    meta = {
+      description = "Synchronized audio player for Sendspin servers (fallback build)";
+      homepage = "https://github.com/Sendspin/sendspin-cli";
+      license = lib.licenses.asl20;
+    };
+  }
+else
+  let
+    # Fetch sendspin-cli source
+    src = fetchFromGitHub {
+      owner = "Sendspin";
+      repo = "sendspin-cli";
+      rev = "main";  # TODO: Pin to specific release tag
+      sha256 = lib.fakeSha256;  # Replace with actual hash after first build
+    };
+
+    # Load workspace from pyproject.toml
+    workspace = uv2nix.lib.workspace.loadWorkspace {
+      workspaceRoot = src;
+    };
+
+    # Create overlay from pyproject.toml dependencies
+    overlay = workspace.mkPyprojectOverlay {
+      sourcePreference = "wheel";  # Prefer wheels for faster builds
+    };
+
+    # Build Python package set with native dependency overrides
+    pythonSet = (pkgs.callPackage pyproject-nix.build.packages {
+      python = pkgs.python312;
+    }).overrideScope (lib.composeManyExtensions [
+      pyproject-build-systems.overlays.default
+      overlay
+      # Override for packages with native dependencies
+      (final: prev: {
+        # sounddevice needs portaudio
+        sounddevice = prev.sounddevice.overrideAttrs (old: {
+          buildInputs = (old.buildInputs or []) ++ [ pkgs.portaudio ];
+          nativeBuildInputs = (old.nativeBuildInputs or []) ++ [ pkgs.portaudio ];
+        });
+        # av (PyAV) needs ffmpeg
+        av = prev.av.overrideAttrs (old: {
+          buildInputs = (old.buildInputs or []) ++ [ pkgs.ffmpeg ];
+          nativeBuildInputs = (old.nativeBuildInputs or []) ++ [ pkgs.pkg-config ];
+        });
+      })
+    ]);
+
+    # Create virtual environment with all dependencies
+    venv = pythonSet.mkVirtualEnv "sendspin-cli-env" workspace.deps.default;
+  in
+  pkgs.stdenv.mkDerivation {
+    pname = "sendspin-cli";
+    version = "0.0.0";
+    inherit src;
+
+    buildInputs = [ venv pkgs.portaudio pkgs.ffmpeg ];
+
+    installPhase = ''
+      mkdir -p $out/bin
+      # Copy virtual environment
+      cp -r ${venv} $out/venv
+      # Create wrapper script
+      cat > $out/bin/sendspin <<EOF
+#!/bin/sh
+export LD_LIBRARY_PATH="${pkgs.portaudio}/lib:${pkgs.ffmpeg}/lib:\$LD_LIBRARY_PATH"
+exec $out/venv/bin/sendspin "\$@"
+EOF
+      chmod +x $out/bin/sendspin
+    '';
+
+    meta = {
+      description = "Synchronized audio player for Sendspin servers";
+      homepage = "https://github.com/Sendspin/sendspin-cli";
+      license = lib.licenses.asl20;
+      platforms = lib.platforms.linux;
+    };
+  }
+```
+
+#### 2. Register Package
+**File**: `packages/default.nix`
+**Changes**: Add sendspin-cli to exports (after line 6)
+
+```nix
+{ pkgs, uv2nix ? null, pyproject-nix ? null, pyproject-build-systems ? null, ... }:
+{
+  vulkanHDRLayer = pkgs.callPackage ./vulkan-hdr-layer {};
+  tea-rbw = pkgs.callPackage ./tea-rbw {};
+  app-launcher-server = pkgs.callPackage ./app-launcher-server {};
+  claude-code = pkgs.callPackage ./claude-code {};
+  sendspin-cli = pkgs.callPackage ./sendspin-cli { inherit uv2nix pyproject-nix pyproject-build-systems; };
+}
+```
+
+### Success Criteria
+
+#### Automated Verification:
+- [x] Package builds successfully: `nix build .#nixosConfigurations.zix790prors.pkgs.custom.sendspin-cli`
+- [x] Binary exists in output: `nix path-info .#nixosConfigurations.zix790prors.pkgs.custom.sendspin-cli`
+- [x] No build errors in dry-run: `nixos-rebuild dry-build --flake .#zix790prors`
+
+#### Manual Verification:
+- [ ] Help text displays correctly: `$(nix-build '<nixpkgs>' -A custom.sendspin-cli)/bin/sendspin --help`
+- [ ] List audio devices works: `$(nix-build '<nixpkgs>' -A custom.sendspin-cli)/bin/sendspin --list-audio-devices`
+- [ ] Version information is correct: `$(nix-build '<nixpkgs>' -A custom.sendspin-cli)/bin/sendspin --version` (if supported)
+- [ ] Dependencies are bundled: Check that output closure contains portaudio and ffmpeg libraries
+
+**Implementation Note**: The first build will fail with `lib.fakeSha256` error. Copy the actual hash from the error message and replace `lib.fakeSha256` with the real hash. After completing this phase and all automated verification passes, pause here for manual confirmation before proceeding to Phase 3.
+
+---
+
+## Phase 3: Create Sendspin Role with Service Template
+
+### Overview
+Create NixOS role that provides sendspin-cli package and configurable systemd user service template for running sendspin as a background service.
+
+### Changes Required
+
+#### 1. Role Definition
+**File**: `roles/sendspin/default.nix`
+**Changes**: Create new file
+
+```nix
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+let
+  cfg = config.roles.sendspin;
+in
+{
+  options.roles.sendspin = {
+    enable = mkEnableOption "Enable the sendspin role";
+
+    audioDevice = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Audio output device by index (e.g., "0", "1") or name prefix (e.g., "AmazonBasics").
+        Use `sendspin --list-audio-devices` to see available devices.
+        If null, uses system default audio device.
+      '';
+      example = "0";
+    };
+
+    clientName = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Friendly name for this Sendspin client.
+        Defaults to hostname if not specified.
+      '';
+      example = "Living Room Speakers";
+    };
+
+    clientId = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Unique identifier for this Sendspin client.
+        Defaults to sendspin-cli-<hostname> if not specified.
+      '';
+      example = "sendspin-livingroom";
+    };
+
+    serverUrl = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        WebSocket URL of the Sendspin server.
+        If null, auto-discovers servers via mDNS.
+      '';
+      example = "ws://192.168.1.100:8927";
+    };
+
+    staticDelayMs = mkOption {
+      type = types.float;
+      default = 0.0;
+      description = ''
+        Extra playback delay in milliseconds applied after clock sync.
+        Useful for compensating audio latency differences between devices.
+      '';
+      example = 50.0;
+    };
+
+    logLevel = mkOption {
+      type = types.enum [ "DEBUG" "INFO" "WARNING" "ERROR" "CRITICAL" ];
+      default = "INFO";
+      description = "Logging level for sendspin service";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # Ensure audio infrastructure is available
+    roles.audio.enable = true;
+
+    # Make sendspin-cli available system-wide
+    environment.systemPackages = with pkgs; [
+      custom.sendspin-cli
+    ];
+
+    # Systemd user service for running sendspin in headless mode
+    systemd.user.services.sendspin = {
+      description = "Sendspin Audio Sync Client";
+      documentation = [ "https://github.com/Sendspin/sendspin-cli" ];
+
+      # Start after audio services are ready
+      after = [ "pipewire.service" "wireplumber.service" ];
+      requires = [ "pipewire.service" "wireplumber.service" ];
+
+      # Auto-start with pipewire (which starts with graphical session)
+      wantedBy = [ "pipewire.service" ];
+
+      serviceConfig = {
+        Type = "simple";
+        Restart = "always";
+        RestartSec = "5s";
+
+        # Build command with configured options
+        ExecStart = pkgs.writeShellScript "sendspin-start" ''
+          exec ${pkgs.custom.sendspin-cli}/bin/sendspin \
+            --headless \
+            --log-level ${cfg.logLevel} \
+            ${optionalString (cfg.audioDevice != null) "--audio-device '${cfg.audioDevice}'"} \
+            ${optionalString (cfg.clientName != null) "--name '${cfg.clientName}'"} \
+            ${optionalString (cfg.clientId != null) "--id '${cfg.clientId}'"} \
+            ${optionalString (cfg.serverUrl != null) "--url '${cfg.serverUrl}'"} \
+            ${optionalString (cfg.staticDelayMs != 0.0) "--static-delay-ms ${toString cfg.staticDelayMs}"}
+        '';
+      };
+    };
+
+    # Open firewall for mDNS discovery
+    networking.firewall.allowedUDPPorts = [ 5353 ];
+  };
+}
+```
+
+#### 2. Register Role
+**File**: `roles/default.nix`
+**Changes**: Add sendspin to imports (after line 16)
+
+```nix
+imports = [
+  ./audio
+  ./bluetooth
+  ./btrfs
+  ./desktop
+  ./kodi
+  ./nfs-mounts
+  ./nvidia
+  ./printing
+  ./remote-build
+  ./sendspin
+  ./spotifyd
+  ./users
+  ./virtualisation
+];
+```
+
+### Success Criteria
+
+#### Automated Verification:
+- [ ] Configuration evaluates: `nixos-rebuild dry-build --flake .#zix790prors`
+- [ ] Service unit is generated: `nixos-rebuild dry-build --flake .#zix790prors 2>&1 | grep -i sendspin`
+- [ ] No syntax errors: `nix eval .#nixosConfigurations.zix790prors.config.roles.sendspin.enable`
+
+#### Manual Verification:
+- [ ] Role can be enabled in machine config without errors
+- [ ] Service dependencies are correct (after pipewire/wireplumber)
+- [ ] Firewall rule for mDNS is present
+- [ ] Sendspin-cli is in system packages when role is enabled
+- [ ] All configuration options (audioDevice, clientName, etc.) are exposed
+- [ ] Service starts successfully after enabling role and rebuilding
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation. Test the service by adding `roles.sendspin.enable = true;` to a machine configuration, rebuilding, and verifying the service runs as the logged-in user.
+
+---
+
+## Testing Strategy
+
+### Unit Tests (Per-Phase)
+
+**Phase 1 (Flake Inputs):**
+```bash
+# Verify flake is valid
+nix flake check
+
+# Verify inputs are available
+nix flake metadata | grep -E "(pyproject-nix|uv2nix|pyproject-build-systems)"
+
+# Verify existing builds still work
+nix build .#nixosConfigurations.zix790prors.config.system.build.toplevel
+```
+
+**Phase 2 (Package):**
+```bash
+# Build package
+nix build .#nixosConfigurations.zix790prors.pkgs.custom.sendspin-cli
+
+# Test executable
+result/bin/sendspin --help
+result/bin/sendspin --list-audio-devices
+
+# Verify dependencies
+nix-store --query --requisites result | grep -E "(portaudio|ffmpeg)"
+```
+
+**Phase 3 (Role):**
+```bash
+# Evaluate with role enabled
+nix eval .#nixosConfigurations.zix790prors.config.roles.sendspin.enable
+
+# Check service definition
+nixos-rebuild dry-build --flake .#zix790prors
+systemctl --user cat sendspin.service  # After rebuild
+
+# Verify audio device option works
+nix eval '.#nixosConfigurations.zix790prors.config.roles.sendspin.audioDevice'
+```
+
+### Integration Tests
+
+**Basic Service Test:**
+1. Enable role on a test machine: `roles.sendspin.enable = true;`
+2. Rebuild system: `make switch`
+3. Check service status: `systemctl --user status sendspin.service`
+4. Verify logs show connection attempts: `journalctl --user -u sendspin -f`
+5. Run server locally: `sendspin serve --demo`
+6. Verify client connects and plays audio
+
+**Multi-Device Test (Future - zix790prors):**
+1. Create multiple service instances with different audio devices
+2. Verify each instance targets correct device
+3. Test audio sync between devices
+
+**User Context Test:**
+1. Test on `boxy` running as `kodi` user
+2. Test on `zix790prors` running as `johno` user
+3. Verify service runs in correct user session
+
+### Manual Testing Steps
+
+1. **Package Installation:**
+   ```bash
+   # As root
+   nix-shell -p 'pkgs.custom.sendspin-cli'
+   sendspin --list-audio-devices
+   ```
+
+2. **Service Functionality:**
+   ```bash
+   # After enabling role and rebuilding
+   systemctl --user status sendspin
+   journalctl --user -u sendspin -n 50
+   ```
+
+3. **Audio Device Selection:**
+   ```bash
+   # Configure specific device
+   roles.sendspin.audioDevice = "0";
+   # Rebuild and verify service uses correct device
+   ```
+
+4. **Server Discovery:**
+   ```bash
+   # Without serverUrl, verify mDNS discovery
+   sendspin --list-servers
+   ```
+
+5. **Delay Calibration:**
+   ```bash
+   # Test delay configuration
+   roles.sendspin.staticDelayMs = 50.0;
+   # Verify in service logs
+   ```
+
+## Performance Considerations
+
+**Build Time:**
+- uv2nix initial build may take 5-10 minutes (Python dependency resolution)
+- Subsequent builds use Nix cache
+- Consider using binary cache if building on multiple machines
+
+**Runtime:**
+- Sendspin client is lightweight (~20-50 MB memory)
+- CPU usage minimal when not playing audio
+- Network: Uses mDNS (UDP 5353) and WebSocket connection to server
+
+**Storage:**
+- Package closure size: ~200-300 MB (Python + dependencies + libraries)
+- No persistent cache by sendspin-cli itself
+
+## Migration Notes
+
+**For Existing Systems:**
+1. Add role to machine configuration
+2. Configure audio device if not using default
+3. Rebuild and enable service
+4. No data migration needed (stateless service)
+
+**For Multi-Instance Setups (Future):**
+When implementing multiple instances for zix790prors:
+1. Disable default service: `systemd.user.services.sendspin.wantedBy = lib.mkForce [];`
+2. Create per-device service instances manually
+3. Each instance needs unique `--id` and `--audio-device`
+
+## References
+
+- Original research: `thoughts/shared/research/2025-12-29-sendspin-cli-integration.md`
+- Sendspin-CLI source: `~/src/sendspin-cli/` (GitHub: https://github.com/Sendspin/sendspin-cli)
+- Sendspin pyproject.toml: `~/src/sendspin-cli/pyproject.toml`
+- Sendspin CLI implementation: `~/src/sendspin-cli/sendspin/cli.py:143-222`
+- Custom packages pattern: `packages/default.nix:1-7`
+- Python package pattern: `packages/app-launcher-server/default.nix:1-10`
+- Audio role pattern: `roles/audio/default.nix:1-41`
+- Service role pattern: `roles/spotifyd/default.nix:1-40`
+- User service pattern: `machines/zix790prors/virtual-surround.nix:79-132`
+- Flake overlay: `flake.nix:54-59`
+- uv2nix documentation: https://pyproject-nix.github.io/uv2nix/
+- uv2nix getting started: https://pyproject-nix.github.io/uv2nix/usage/getting-started.html