mirror of
https://github.com/anomalyco/hex.git
synced 2026-11-22 21:23:02 +01:00
215 lines
8.7 KiB
Markdown
215 lines
8.7 KiB
Markdown
# Nix
|
|
|
|
The flake packages Hex for Linux only, `x86_64-linux` and `aarch64-linux`;
|
|
there is no macOS package. Both targets build from source; `aarch64-linux`
|
|
evaluates but has not been built or run on real ARM64 hardware yet. It
|
|
supports the Linux X11 beta and native Wayland on compatible wlroots
|
|
compositors. Wayland requires layer-shell for the recording overlay, the
|
|
clipboard protocol used by `wl-copy`, and the virtual-keyboard protocol
|
|
used by `wtype`. Global shortcuts come from the desktop's GlobalShortcuts
|
|
portal, or from your own compositor keybindings running the `hex` commands.
|
|
This is not a claim of support for every Wayland desktop; GNOME and KDE are
|
|
not covered by this contract.
|
|
|
|
## Run Or Install
|
|
|
|
On macOS, install the [DMG or Homebrew cask](../README.md#downloads) instead;
|
|
the flake has no `aarch64-darwin` package.
|
|
|
|
From a checkout, with Nix flakes enabled:
|
|
|
|
```sh
|
|
nix build
|
|
nix run . -- model install
|
|
nix run . -- app
|
|
```
|
|
|
|
Or add `hex.url = "github:anomalyco/hex"` to your configuration's flake inputs
|
|
and install `hex.packages.${system}.default` (`x86_64-linux` or
|
|
`aarch64-linux`). The package supplies the
|
|
`hex` command and desktop launcher, native libraries (including PipeWire and
|
|
libva for Annotate), and the `curl`, `wl-copy`, `wtype`, and `ffmpeg`/`ffprobe`
|
|
runtime dependencies. Annotate's hardware encoder uses whatever VA-API driver
|
|
your system provides (NixOS: `hardware.graphics`, through `/run/opengl-driver`);
|
|
without one it falls back to ffmpeg's libx264. Your system still needs a
|
|
working audio session and a Vulkan driver for Settings, even when inference
|
|
falls back to the CPU. On non-NixOS hosts, Nix GUI
|
|
applications may require the host's usual Nix graphics integration.
|
|
|
|
On NixOS, Hex built from its own pinned nixpkgs can use an older glibc than
|
|
your system's graphics drivers need. Hex then finds no suitable Vulkan
|
|
adapter and its window does not open. Make Hex's nixpkgs follow your
|
|
system's, so both use the same glibc:
|
|
|
|
```nix
|
|
{
|
|
inputs.hex = {
|
|
url = "github:anomalyco/hex";
|
|
# Use the name of your own nixpkgs input here.
|
|
inputs.nixpkgs.follows = "nixpkgs";
|
|
};
|
|
}
|
|
```
|
|
|
|
Models are downloaded into your user data directory, not the Nix store.
|
|
Run `hex model install` once, then launch Hex as your normal desktop user.
|
|
Do not run Hex as root.
|
|
|
|
The Nix store is not Hex's user-local managed installation layout. In-app
|
|
updates do not replace a Nix installation. Update the flake input and
|
|
rebuild or switch your Nix/Home Manager configuration instead. Remove any
|
|
old source-install XDG autostart entry before enabling a second autostart
|
|
mechanism; do not run two Hex listeners.
|
|
|
|
## NixOS
|
|
|
|
Import `hex.nixosModules.hex` and enable the package:
|
|
|
|
```nix
|
|
{
|
|
imports = [ hex.nixosModules.hex ];
|
|
programs.hex.enable = true;
|
|
}
|
|
```
|
|
|
|
This installs Hex system-wide. It does not start a root service or enable
|
|
autostart for every account. Use the
|
|
Home Manager module below for per-user autostart. Both modules accept an
|
|
explicit `programs.hex.package` override. The flake also exports
|
|
`hex.overlays.default` for configurations that prefer `pkgs.hex`.
|
|
|
|
## Home Manager
|
|
|
|
```nix
|
|
{
|
|
imports = [ hex.homeManagerModules.hex ];
|
|
programs.hex = {
|
|
enable = true;
|
|
autostart = true;
|
|
# Use your compositor's session target when appropriate:
|
|
# systemdTarget = "sway-session.target";
|
|
};
|
|
}
|
|
```
|
|
|
|
The module always installs the systemd **user** service. Autostart defaults to
|
|
`false`; when enabled, the unit is wanted by `graphical-session.target` by default.
|
|
It waits for a Wayland socket or an X11 window manager before launching `hex service`,
|
|
which reports readiness to systemd (`Type=notify`) once its socket answers.
|
|
Hex is one process: `hex` opens its window, starting the unit when it is not
|
|
running, and `hex start` starts it without the window. Closing the window never
|
|
stops Hex; a tray icon shows when the desktop has a tray host. The unit stops with the configured target
|
|
and retries failed starts without a tight restart loop; a crash restart opens no
|
|
window. `hex quit` (or **Quit Hex** in the window) leaves it stopped until the
|
|
next session or the next launch.
|
|
|
|
Your session manager must import its current `DISPLAY`, `XAUTHORITY`,
|
|
`WAYLAND_DISPLAY`, and `XDG_RUNTIME_DIR` values as applicable into the systemd
|
|
user environment **before** starting the target, and stop the target at
|
|
logout. Use your compositor's systemd integration, such as Home Manager's
|
|
Sway integration, rather than starting the target from a shell login.
|
|
The module does not create a graphical session or grant permission to use
|
|
one. A bare `startx`/i3 session without systemd session integration will not
|
|
start this service automatically.
|
|
|
|
`hex start` records the current display/session environment in an owner-only
|
|
file read by the unit; it clears stale variables when switching between X11 and
|
|
Wayland. There is one Hex per user. Launching it from a different desktop
|
|
explicitly restarts the unit for that session. The unit names Hex's default
|
|
data folder, so Hex still treats it as its own supervised service: a stale
|
|
`XAUTHORITY` from an earlier login (GNOME's XWayland cookie) is replaced with
|
|
the user manager's current one, keeping the HUD working after a re-login (#1140).
|
|
|
|
Home Manager's normal service-switch policy applies: newly enabled services
|
|
can start during a switch if the session target is already active, and
|
|
package changes can restart a running service. Do not switch during an
|
|
active recording. Inspect failures with:
|
|
|
|
```sh
|
|
systemctl --user status hex.service
|
|
journalctl --user -u hex.service
|
|
```
|
|
|
|
### Declarative Settings
|
|
|
|
```nix
|
|
{
|
|
programs.hex = {
|
|
enable = true;
|
|
shortcut = "control+option+space"; # dictation_hotkey
|
|
model = "parakeet_v3";
|
|
language = "de";
|
|
installModel = true;
|
|
settings = {
|
|
shortcut_mode = "toggle";
|
|
sound_effect_volume = 0.4;
|
|
paste_with_shift = true;
|
|
"meetings.enabled" = true;
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
`settings` takes the dotted keys `hex settings list` shows, with JSON values:
|
|
booleans, numbers, text such as shortcuts and choices, `null` to clear an
|
|
optional setting, and attribute sets or lists for its `json` settings. The
|
|
`shortcut`, `model`, and `language` options are shorthands for
|
|
`dictation_hotkey`, `transcription.model`, and `transcription.language`.
|
|
|
|
Every activation merges them into Hex with `hex settings apply`, after
|
|
systemd units reload. Declared keys overwrite Hex's values; anything you
|
|
change in the window that isn't declared keeps its value until you declare
|
|
it. A running Hex saves and adopts the settings at once, so it never writes
|
|
older values back from memory; with Hex stopped they go straight into
|
|
`settings.json`. `settings.json` stays an ordinary writable file. An unknown
|
|
key or invalid value applies nothing and prints a warning, without failing
|
|
the switch.
|
|
|
|
Declaring a model only selects it; activation never downloads. With
|
|
`installModel = true`, the `hex-model` user service runs `hex model install`
|
|
for the selected model at login, once the system's `network-online.target`
|
|
is reached (or after two minutes), and retries a failed download. A switch
|
|
does not wait for it.
|
|
|
|
## Wayland Shortcuts
|
|
|
|
Hex reads no input devices, so neither module adds users to the `input`
|
|
group, installs udev rules, or grants capabilities. With a GlobalShortcuts
|
|
portal, the desktop grants the shortcuts Settings records; the portal
|
|
identifies Hex by the package's `anomaly.hex.desktop` entry, so keep the package's
|
|
`share/applications` on `XDG_DATA_DIRS` (NixOS and Home Manager profiles do).
|
|
Without the portal, bind the commands in your compositor, for example in Sway:
|
|
|
|
```sh
|
|
bindsym F9 exec hex dictation start
|
|
bindsym --release F9 exec hex dictation stop
|
|
```
|
|
|
|
`hex dictation toggle` and `hex paste-last`
|
|
are also available; see the
|
|
[Linux guide](linux.md#shortcuts). The paste helper is `wtype`; no privileged
|
|
input-injection fallback is installed.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
nix develop
|
|
cargo build --locked
|
|
cargo test --locked
|
|
cargo run --locked -- app
|
|
```
|
|
|
|
The package and shell share the native build environment and runtime
|
|
library/plugin paths. OpenBLAS link ordering is handled by `build.rs`, not
|
|
by Nix-only `RUSTFLAGS`. The shell also supplies the paste and download
|
|
helpers, so it does not rely on the installed app's wrapper. Desktop commands
|
|
still require a real graphical/audio session and the permissions described above.
|
|
|
|
`nix flake check` evaluates the module and shell-environment regressions and
|
|
builds the package with its normal display-free Rust tests. Tests explicitly
|
|
marked ignored because they require a desktop or installed model remain
|
|
ignored; the Nix build does not download models or exercise live input.
|
|
|
|
The initial packaging design builds on [PR #29](https://github.com/anomalyco/hex/pull/29).
|
|
Declarative settings follow
|
|
[@SymphonySimper's request in #588](https://github.com/anomalyco/hex/issues/588).
|