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.
This commit is contained in:
74
flake.lock
generated
74
flake.lock
generated
@@ -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"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
26
flake.nix
26
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";
|
||||
};
|
||||
|
||||
outputs = { self, nixpkgs, nixpkgs-unstable, nixos-wsl, ... } @ inputs: let
|
||||
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, 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;
|
||||
})
|
||||
|
||||
@@ -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; };
|
||||
}
|
||||
|
||||
91
packages/sendspin-cli/default.nix
Normal file
91
packages/sendspin-cli/default.nix
Normal file
@@ -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;
|
||||
};
|
||||
}
|
||||
660
thoughts/shared/plans/2025-12-29-sendspin-cli-integration.md
Normal file
660
thoughts/shared/plans/2025-12-29-sendspin-cli-integration.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user