feat(nix): NixOS integration — ALSA_PLUGIN_DIR + nixosModule by zitongcharliedeng · Pull Request #1025 · cjpais/Handy

zitongcharliedeng · 2026-03-12T22:35:58Z

Summary

Two changes to make Handy work out-of-the-box on NixOS:

1. ALSA_PLUGIN_DIR in package wrapper (flake.nix, +1 line)

On NixOS with PipeWire, CPAL opens the ALSA "default" device but gets 0 audio samples because PipeWire's ALSA plugin isn't on the default search path. Setting ALSA_PLUGIN_DIR in the gapps wrapper fixes this.

2. nixosModule for system-level config (nix/module.nix, new file)

Adds a nixosModules.default output so NixOS users can enable Handy with:

inputs.handy.url = "github:cjpais/Handy";

# In your NixOS config:
{ programs.handy.enable = true; }

The module handles system config that the package wrapper cannot:

udev rule for /dev/uinput (rdev grab() needs it for virtual input devices)
Adds the Handy package to systemPackages

Users still need to add themselves to the input group for evdev hotkey access.

Test plan

nix flake check --no-build passes
Build and run on NixOS with PipeWire — verify audio capture works
Verify programs.handy.enable = true sets up udev rule correctly

zitongcharliedeng · 2026-03-12T22:41:36Z

Note: Global hotkeys on Wayland

~~Previously noted that global shortcuts don't work on Wayland via Tauri/rdev's X11 path.~~

Update: HandyKeys (evdev backend) works natively on Wayland — no xdotool workaround needed. Set keyboard_implementation: "handy_keys" in settings and it captures hotkeys directly via /dev/input/event*, bypassing X11 entirely.

cjpais · 2026-03-12T23:19:37Z

Just a heads up I don't believe handy keys works generally on Linux, but you can let me know. It's certainly not going to be the default without more testing

zitongcharliedeng · 2026-03-13T02:20:41Z

Seems to work fine on my Niri on Wayland.

2026-03-13.02-20-07.mp4

zitongcharliedeng · 2026-03-13T04:30:51Z

Updated to put the key fix in handey-keys repo.

zitongcharliedeng · 2026-03-13T04:31:24Z

I presume there is some auto bump in the nix flake for it to propagate

cjpais · 2026-03-13T07:51:58Z

Updated to put the key fix in handey-keys repo.

what is this fix?

zitongcharliedeng · 2026-03-13T08:10:36Z

Just adding the missing Insert Key and preventing keyboard hotplugs from disconnecting listeners. handy-computer/handy-keys#12

…

On Fri, 13 Mar 2026, 07:52 CJ Pais, ***@***.***> wrote: *cjpais* left a comment (cjpais/Handy#1025) <#1025 (comment)> Updated to put the key fix in handey-keys repo. what is this fix? — Reply to this email directly, view it on GitHub <#1025 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AZ3GVSJTRJXOQS47BWRWLOL4QO43LAVCNFSM6AAAAACWQI62ZOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DANJTGQYDCOBSG4> . You are receiving this because you authored the thread.Message ID: ***@***.***>

cjpais · 2026-03-13T13:38:17Z

@y0usaf @xilec @CaptainSpof @kakapt please confirm this is a good change to have

@zitongcharliedeng handy keys#12 should be pulled in tomorrow, just waiting on comment from you there to get more background

kakapt · 2026-03-13T14:12:01Z

@y0usaf @xilec @CaptainSpof @kakapt please confirm this is a good change to have

@zitongcharliedeng handy keys#12 should be pulled in tomorrow, just waiting on comment from you there to get more background

I think setting ALSA_PLUGIN_DIR is redundant because by default if we have pipewire enabled then cpal will able to detect ALSA. The issue is the version mismatch between cpal and ALSA. I've played around this in pr 787 and also discussed with @cjpais on Discord earlier

kakapt · 2026-03-13T14:15:25Z

For nixosModule, I think it is a good change but can we consider providing home manager module too?

flake.nix

zitongcharliedeng · 2026-03-14T10:31:35Z

Updated the PR based on feedback:

@kakapt re ALSA_PLUGIN_DIR — On my NixOS setup, without ALSA_PLUGIN_DIR set, CPAL gets 0 audio samples. Setting it to the pipewire store path fixed it, consistent with what nixpkgs does for alsa-utils (#432786). But I haven't tested with your PR #787 changes — is the ALSA version mismatch fix sufficient to make CPAL find PipeWire without ALSA_PLUGIN_DIR? Happy to drop it if so.

@kakapt re home-manager module — Added homeManagerModules.default with systemd service, .asoundrc PipeWire routing, and first-install settings seed. One caveat: Handy's Tauri app.store() overrides settings_store.json on startup, so the module can only seed settings on first install — after that Handy's UI is the source of truth.

kakapt · 2026-03-14T11:11:45Z

Updated the PR based on feedback:

@kakapt re ALSA_PLUGIN_DIR — On my NixOS setup, without ALSA_PLUGIN_DIR set, CPAL gets 0 audio samples. Setting it to the pipewire store path fixed it, consistent with what nixpkgs does for alsa-utils (#432786). But I haven't tested with your PR #787 changes — is the ALSA version mismatch fix sufficient to make CPAL find PipeWire without ALSA_PLUGIN_DIR? Happy to drop it if so.

Yeah, I had the same issue before. I also tried adding ALSA_PLUGIN_DIR but finally figured out that it is actually the cpal error.
@zitongcharliedeng You can see some of my debug logs on Handy discord: https://discord.com/channels/1391636091853078608/1471037063171281007

kakapt · 2026-03-14T11:13:19Z

Updated the PR based on feedback:

@kakapt re home-manager module — Added homeManagerModules.default with systemd service, .asoundrc PipeWire routing, and first-install settings seed. One caveat: Handy's Tauri app.store() overrides settings_store.json on startup, so the module can only seed settings on first install — after that Handy's UI is the source of truth.

Thanks for it! I'll test it soon and let you know!

…ager module - Set ALSA_PLUGIN_DIR to PipeWire's alsa-lib path in package wrapper (NixOS store paths aren't in ALSA's default plugin search) - Add nixosModules.default: udev rule for /dev/uinput, systemPackages - Add homeManagerModules.default: systemd user service for autostart

xilec · 2026-03-14T12:23:02Z

LGTM

cjpais · 2026-03-14T12:27:35Z

everyone here please give confirmation and I will pull it in when there is consensus!

zitongcharliedeng · 2026-03-14T12:49:02Z

Lgtm

kakapt · 2026-03-16T12:13:07Z

@cjpais I notice that the doc does not mention the udev rules for uinput for general linux user

cjpais · 2026-03-16T12:14:07Z

@kakapt if you want to submit a PR to them I would gladly pull in

cjpais · 2026-03-16T12:15:01Z

@xilec will this cause a merge conflict with the work we are doing in #1041, and if I pull this in, can you fix that conflict

xilec · 2026-03-16T12:25:16Z

@cjpais The changes don't overlap — #1025 touches preFixup and adds modules, while #1041 adds the overlay and an env var. Git should auto-merge without conflicts.

cjpais · 2026-03-16T12:27:53Z

great thanks, just gonna wait for the build to finish here and will pull in

…ager module (cjpais#1025) - Set ALSA_PLUGIN_DIR to PipeWire's alsa-lib path in package wrapper (NixOS store paths aren't in ALSA's default plugin search) - Add nixosModules.default: udev rule for /dev/uinput, systemPackages - Add homeManagerModules.default: systemd user service for autostart Co-authored-by: zitongcharliedeng <[email protected]> (cherry picked from commit cf284b1)

zitongcharliedeng force-pushed the fix/nixos-pipewire-alsa branch from d5a5390 to 0739005 Compare March 12, 2026 22:39

zitongcharliedeng marked this pull request as draft March 12, 2026 22:44

zitongcharliedeng changed the title ~~fix(nix): set ALSA_PLUGIN_DIR for PipeWire audio capture~~ fix(linux): NixOS PipeWire audio + Wayland global hotkeys Mar 12, 2026

zitongcharliedeng marked this pull request as ready for review March 13, 2026 02:10

zitongcharliedeng marked this pull request as draft March 13, 2026 02:27

zitongcharliedeng force-pushed the fix/nixos-pipewire-alsa branch from a26d7e8 to e590850 Compare March 13, 2026 02:29

zitongcharliedeng changed the title ~~fix(linux): NixOS PipeWire audio + Wayland global hotkeys~~ fix(linux): NixOS PipeWire audio + Wayland hotkeys + Insert key support Mar 13, 2026

zitongcharliedeng marked this pull request as ready for review March 13, 2026 04:07

zitongcharliedeng force-pushed the fix/nixos-pipewire-alsa branch from d5b245f to 069fdaf Compare March 13, 2026 04:28

zitongcharliedeng changed the title ~~fix(linux): NixOS PipeWire audio + Wayland hotkeys + Insert key support~~ fix(nix): set ALSA_PLUGIN_DIR for PipeWire audio capture Mar 13, 2026

zitongcharliedeng force-pushed the fix/nixos-pipewire-alsa branch from 069fdaf to ceca5d9 Compare March 13, 2026 04:37

zitongcharliedeng changed the title ~~fix(nix): set ALSA_PLUGIN_DIR for PipeWire audio capture~~ feat(nix): NixOS integration — ALSA_PLUGIN_DIR + nixosModule Mar 13, 2026

xilec reviewed Mar 13, 2026

View reviewed changes

flake.nix Outdated Show resolved Hide resolved

xilec reviewed Mar 13, 2026

View reviewed changes

flake.nix Outdated Show resolved Hide resolved

zitongcharliedeng force-pushed the fix/nixos-pipewire-alsa branch from 7a6bf61 to 46493c2 Compare March 14, 2026 11:11

zitongcharliedeng force-pushed the fix/nixos-pipewire-alsa branch from 46493c2 to 0692500 Compare March 14, 2026 11:11

zitongcharliedeng force-pushed the fix/nixos-pipewire-alsa branch from 0692500 to 34bd090 Compare March 14, 2026 11:16

cjpais merged commit cf284b1 into cjpais:main Mar 16, 2026
5 checks passed

Uh oh!

Conversation

zitongcharliedeng commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

zitongcharliedeng commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Note: Global hotkeys on Wayland

Uh oh!

cjpais commented Mar 12, 2026

Uh oh!

zitongcharliedeng commented Mar 13, 2026

Uh oh!

zitongcharliedeng commented Mar 13, 2026

Uh oh!

zitongcharliedeng commented Mar 13, 2026

Uh oh!

cjpais commented Mar 13, 2026

Uh oh!

zitongcharliedeng commented Mar 13, 2026 via email

Uh oh!

cjpais commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kakapt commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kakapt commented Mar 13, 2026

Uh oh!

Uh oh!

Uh oh!

zitongcharliedeng commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kakapt commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kakapt commented Mar 14, 2026

Uh oh!

xilec commented Mar 14, 2026

Uh oh!

cjpais commented Mar 14, 2026

Uh oh!

zitongcharliedeng commented Mar 14, 2026

Uh oh!

kakapt commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cjpais commented Mar 16, 2026

Uh oh!

cjpais commented Mar 16, 2026

Uh oh!

xilec commented Mar 16, 2026

Uh oh!

cjpais commented Mar 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zitongcharliedeng commented Mar 12, 2026 •

edited

Loading

zitongcharliedeng commented Mar 12, 2026 •

edited

Loading

cjpais commented Mar 13, 2026 •

edited

Loading

kakapt commented Mar 13, 2026 •

edited

Loading

zitongcharliedeng commented Mar 14, 2026 •

edited

Loading

kakapt commented Mar 14, 2026 •

edited

Loading

kakapt commented Mar 16, 2026 •

edited

Loading