{"id":51478122,"url":"https://github.com/oxyzenq/zylaxion","last_synced_at":"2026-07-06T23:01:16.570Z","repository":{"id":365187189,"uuid":"1269883104","full_name":"oxyzenQ/zylaxion","owner":"oxyzenQ","description":"Linux-first keyboard acoustic engine. Pure procedural synthesis, zero audio samples. Flawless on Wayland, X11, and TTY.","archived":false,"fork":false,"pushed_at":"2026-07-05T17:02:14.000Z","size":3524,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T17:09:18.243Z","etag":null,"topics":["accoustic","bucklespring-alternative","dsp","keyboard","libinput","linux","mechanical-keyboard","procedural-audio","rust","wayland"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxyzenQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"rezky","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-06-15T07:26:45.000Z","updated_at":"2026-07-05T17:02:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oxyzenQ/zylaxion","commit_stats":null,"previous_names":["oxyzenq/zylaxion"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/oxyzenQ/zylaxion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxyzenQ%2Fzylaxion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxyzenQ%2Fzylaxion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxyzenQ%2Fzylaxion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxyzenQ%2Fzylaxion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxyzenQ","download_url":"https://codeload.github.com/oxyzenQ/zylaxion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxyzenQ%2Fzylaxion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35208141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accoustic","bucklespring-alternative","dsp","keyboard","libinput","linux","mechanical-keyboard","procedural-audio","rust","wayland"],"created_at":"2026-07-06T23:01:15.271Z","updated_at":"2026-07-06T23:01:16.542Z","avatar_url":"https://github.com/oxyzenQ.png","language":"Rust","funding_links":["https://ko-fi.com/rezky"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/zylaxion-logo-master.png\" alt=\"zylaxion logo\" width=\"260\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ezylaxion\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLinux-first real-time mechanical keyboard acoustic engine.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Pure procedural synthesis. Zero audio samples. Low-latency.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ko-fi.com/rezky\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Ko--fi-support-7C3AED?style=flat-square\u0026logo=kofi\u0026logoColor=white\u0026labelColor=111827\" alt=\"Support on Ko-fi\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nZylaxion transforms every keystroke into a spatially accurate mechanical keyboard sound using Linux's `evdev` interface and real-time audio output through `cpal` and PipeWire.\n\nInstead of replaying recorded samples, every sound is **synthesized mathematically** using noise excitation, TPT State Variable Filters, resonance modeling, and exponential decay envelopes. This pure procedural approach means:\n\n- **Zero audio samples** — no wavetables, no recorded clips, no sample libraries. The entire sound engine is mathematical computation.\n- **Ultra-lightweight** — the binary is self-contained; no audio assets to load, store, or manage.\n- **Infinitely tunable** — every parameter (filter frequencies, resonance Q, decay coefficients, spring mix) is a number in `config.toml`, adjustable in real time.\n- **Deterministic** — the same key + same config always produces the same waveform. No random variation from sample playback.\n\nNo audio files. No sample libraries. No wavetable playback. Just math.\n\n**Works on Wayland, X11, and Linux TTY.**\n\n## Features\n\n- **Pure procedural synthesis** — all sounds generated from math, not samples.\n  Dual TPT SVF filters model the click transient and spring resonance of\n  real mechanical key switches with zero audio assets.\n- **Real-time audio** — cpal + PipeWire with interrupt-driven ring buffer\n  rendering. Typical latency under 3 ms.\n- **Polyphonic voice pool** — 16 simultaneous voices with oldest-first voice\n  stealing, stereo panning based on key position, and exponential decay.\n- **Central `config.toml`** — single source of truth for all acoustic\n  DSP parameters (click frequency, resonance, spring mix, decay\n  coefficient, per-key overrides). Edit, save, and the running daemon\n  auto-reloads within 1 second — no restart needed. Presets for 5 sound\n  characters (`technical`, `classic`, `studio`, `elegant`, `whisper`)\n  are documented as copy-paste blocks at the top of the file.\n- **Daemon mode** — POSIX-compliant daemonization with signal handling,\n  PID file with recycling protection, and Unix Domain Socket IPC for\n  remote stop/status commands.\n- **Zero system dependencies** — only requires a C compiler for linking.\n  Audio via PipeWire/PulseAudio (system), input via libinput (kernel evdev).\n- **Linux-first** — built for the Linux kernel's evdev subsystem.\n  No X11 or Wayland dependency; input capture works everywhere.\n\n## Installation\n\n### From source\n\nRequires: Rust toolchain ([rustup.rs](https://rustup.rs/)),\n`pkg-config`, `libasound2-dev`, `libinput-dev`, `libudev-dev`.\n\n\u003e Zylaxion plays audio through `cpal`, which talks to PipeWire /\n\u003e PulseAudio / ALSA via the OS's default audio bridge. No PipeWire\n\u003e native development headers are required — only `libasound2-dev`\n\u003e (ALSA backend that cpal links against).\n\n```bash\ngit clone https://github.com/oxyzenQ/zylaxion.git\ncd zylaxion\n\n# Build the release binary\ncargo build --release --locked\n\n# Install (binary + config.toml go to ~/.local by default)\n./scripts/install.sh\n```\n\nTo install to a custom prefix:\n\n```bash\nPREFIX=\"$HOME/.local\" ./scripts/install.sh\n```\n\nThe installer copies the binary to `${PREFIX}/bin/zylaxion` and the\ncentral `config.toml` to `${PREFIX}/share/zylaxion/config.toml`. It\ndoes **not** run `cargo build` — build first, then install.\n\nSince v3.0.0 the installer also deploys a **systemd user service** to\n`~/.config/systemd/user/zylaxion.service`. To enable auto-start on login:\n\n```bash\nsystemctl --user enable --now zylaxion\nsystemctl --user status  zylaxion\njournalctl --user -u zylaxion -f   # live logs\n```\n\n\u003e **Note:** your user must be in the `input` group for keyboard access:\n\u003e `sudo usermod -aG input $USER \u0026\u0026 log out/in`\n\n### Download a release binary\n\nPre-built binaries are attached to each [GitHub release](https://github.com/oxyzenQ/zylaxion/releases).\nDownload, make executable, and copy to a directory on your PATH:\n\n```bash\nwget https://github.com/oxyzenQ/zylaxion/releases/latest/download/zylaxion\nchmod +x zylaxion\ninstall -Dm755 zylaxion \"$HOME/.local/bin/zylaxion\"\n```\n\n### Release Verification\n\nEach release ships **three** checksums: classical SHA-512 + quantum-resistant\nBLAKE2b-512 + SHAKE256. Full instructions in\n[docs/VERIFY_RELEASE.md](docs/VERIFY_RELEASE.md).\n\n```bash\n# Classical (universal)\nsha512sum -c zylaxion-vX.Y.Z-linux-amd64-gnu.tar.gz.sha512sum\n\n# Quantum-resistant — BLAKE2b (fastest, in coreutils)\nb2sum -c zylaxion-vX.Y.Z-linux-amd64-gnu.tar.gz.b2sum\n\n# Quantum-resistant — SHAKE256 (NIST PQ standard, via Python)\n# openssl's -shake256 default output length varies; Python is consistent\nCOMPUTED=$(python3 -c \"import hashlib; print(hashlib.shake_256(open('zylaxion-vX.Y.Z-linux-amd64-gnu.tar.gz','rb').read()).hexdigest(64))\")\nEXPECTED=$(awk '{print $1}' zylaxion-vX.Y.Z-linux-amd64-gnu.tar.gz.shake256)\n[ \"$COMPUTED\" = \"$EXPECTED\" ] \u0026\u0026 echo \"OK\" || echo \"FAILED\"\n```\n\n## Usage\n\n```\nzylaxion start                    # Foreground mode (Ctrl+C to quit)\nzylaxion start --preset cherryMX  # Override active preset from CLI\nzylaxion daemon                   # Background daemon mode\nzylaxion stop                     # Stop a running daemon\nzylaxion status                   # Check if daemon is running\nzylaxion doctor                   # System health diagnostic\nzylaxion testconf                 # Validate config.toml syntax + ranges\nzylaxion list-presets             # List available presets + active one\nzylaxion list-backends            # Show available audio backends\n```\n\n### Configuration\n\nThe central `config.toml` controls every aspect of the click sound:\nfilter frequencies, resonance (Q), spring mix level, decay rate, and\namplitude, plus optional `[[keys]]` per-scancode overrides. The file\nis loaded from (first found wins):\n\n1. `~/.config/zylaxion/config.toml` — user-local override\n2. `/etc/zylaxion/config.toml` — system config\n3. `/usr/local/share/zylaxion/config.toml` — installed default\n4. `./config.toml` — relative to CWD (development)\n5. Hardcoded default — always available\n\n#### Active preset selection\n\nThe file defines multiple named `[preset.NAME]` tables. The active\npreset is determined by:\n\n1. `--preset \u003cname\u003e` on the CLI (highest priority — overrides everything)\n2. `tuning = \"\u003cname\u003e\"` in the `[preset]` table of `config.toml`\n3. `\"technical\"` (hardcoded default) if neither is set\n\nIf the resolved preset does NOT exist in `config.toml`, the program\nprints a clear error listing the available presets and exits — there\nis **no silent fallback**. This prevents accidental misconfiguration.\n\n#### Auto-reload\n\nThe running daemon polls `config.toml`'s mtime every 1 second and\nauto-reloads on change. If you started without `--preset`, changing\n`tuning = \"cherryMX\"` and saving causes an immediate swap to the\ncherryMX preset — no restart needed. If you started with `--preset`,\nthe CLI value wins and `tuning` changes are ignored (you'd need to\nrestart with a different `--preset`).\n\nRun `zylaxion testconf` after editing to catch TOML typos and\nout-of-bounds DSP values before they affect the running daemon.\n\n### Built-in sound presets\n\nZylaxion ships with **24 presets** — 6 \"character\" presets, 3\nswitch-type presets, **10 high-fidelity legendary keyboard profiles**\n(v4.0.0+) tuned to mimic real switches, and **5 sci-fi / futuristic\npresets** (v4.1.0+) that don't mimic anything real. Since v4.2.0,\n**every preset** uses a 3-layer DSP engine (click + spring + housing\n\"thock\") for realistic acoustic body. Since v5.0.0, every keypress\napplies **micro-randomization** (±1.5% pitch drift, ±5% amplitude\ndrift, unique noise seed) so the same key never sounds identical twice\n— breaking the \"uncanny valley\" of deterministic synthesis.\n\n#### Character presets (general use)\n\n| Preset    | Description                                      |\n|-----------|--------------------------------------------------|\n| technical | Crisp, loud, punchy. Cherry MX Blue click style. |\n| cherryMX  | Balanced reference. General MX Blue/Brown.       |\n| classic   | Deeper, resonant. Warm bucklespring tone.        |\n| studio    | Softer attack, longer decay. Office-friendly.     |\n| elegant   | Very soft, muffled. Low-profile keyboards.       |\n| whisper   | Extremely quiet, short decay. Libraries/meetings. |\n\nPlus three switch-type presets: `linear`, `tactile`, `clicky`.\n\n#### Legendary keyboard profiles (v4.0.0+)\n\nEach of the following presets was hand-tuned against reference\nrecordings of the actual hardware. The DSP parameters (click\nfrequency, resonance Q, decay coefficient, ambient rattle) are\nadjusted to capture the signature character of each switch. Three\npresets (`ibm_model_m`, `topre`, `alps_skcm`) received a\nrealism tuning pass in v4.1.0 — softer Topre attack, longer IBM\nModel M ring, deeper ALPS housing.\n\n| Preset             | Switch Type         | Character                                              |\n|--------------------|---------------------|--------------------------------------------------------|\n| `ibm_model_m`      | Buckling spring     | Deep, very resonant, long ring. **Default since v4.0.0.** |\n| `topre`            | Electrocapacitive   | Deep \"thock\", smooth, low resonance. Realforce/HHKB.  |\n| `cherry_mx_black`  | Linear (heavy)      | Smooth thud, faint spring ping. ~80g actuation.       |\n| `cherry_mx_clear`  | Tactile (heavy)     | Pronounced bump, louder than Brown. ~65g actuation.   |\n| `cherry_mx_silver` | Linear (low-pro)    | Fast, snappy bottom-out. Designed for gaming.         |\n| `buckling_spring`  | Buckling spring     | Sharper \u0026 brighter than Model M. Think Model F.       |\n| `alps_skcm`        | Tactile (vintage)   | Complicated ALPS — loud, hollow housing ring.         |\n| `gateron_yellow`   | Linear (thocky)     | Lubed linear with PBT caps. Deep, rounded thock.      |\n| `zealios_v2`       | Tactile (sharp)     | Almost clicky-feeling bump. Enthusiast tactile.       |\n| `rotary_encoder`   | Encoder detent      | Not a keyboard — a smooth metallic knob click.        |\n\n#### Sci-Fi / Futuristic presets (v4.1.0+)\n\nThese five presets are completely original acoustic signatures —\nthey don't mimic real keyboards. Each pushes the DSP parameter\nranges to extremes for cyberpunk aesthetic, gaming immersion, or\njust fun. Perfect for streaming setups with a sci-fi theme, game\ndevelopers wanting UI key sounds, or anyone who wants a unique\ntyping experience no human has heard before.\n\n| Preset             | Character                                                  |\n|--------------------|------------------------------------------------------------|\n| `cyber_deck`       | High-pitched metallic pings. Hollywood \"future terminal\".  |\n| `oceanic`          | Deep underwater rumble, long bass sustain, muffled thud.   |\n| `glass_tactile`    | Tapping a crystal wine glass — pure ringing tone.          |\n| `retro_typewriter` | Sharp typebar strike + cast-iron frame ring (no bell).     |\n| `neon_pulse`       | Cyberpunk UI button — heavy granular texture on a click.   |\n\nTry them all:\n\n```bash\nzylaxion list-presets\nzylaxion start --preset ibm_model_m\nzylaxion start --preset topre\nzylaxion start --preset alps_skcm\nzylaxion start --preset glass_tactile\nzylaxion start --preset neon_pulse\n```\n\n## Security \u0026 Privacy\n\nZylaxion is designed with a **zero-leakage** posture. The short\nversion: **your keystrokes never leave the process.**\n\n### What Zylaxion reads\n\n- **Hardware scancodes** — the physical key location on the keyboard\n  (e.g. scancode `30` is the home row key under QWERTY's left hand).\n  This is *not* an ASCII character. Zylaxion does not translate\n  scancodes into letters, symbols, or text. It feeds them straight\n  into the DSP engine to choose a stereo pan position and trigger a\n  click sound.\n- The kernel's `evdev` interface via `libinput` — same data any\n  keyboard-aware Linux program can read.\n\n### What Zylaxion does NOT do\n\n- **Does not log scancodes** — not at `info`, not at `debug`, not at\n  `trace`. The `KeyEvent` struct exists to drive the DSP engine, not\n  for human inspection. Audit the codebase: `grep -r 'scancode'\n  crates/ | grep -E 'log::|println!|eprintln!'` returns zero hits\n  in production paths.\n- **Does not store keystrokes** — there is no on-disk log, no\n  history file, no analytics. The only thing Zylaxion writes to disk\n  is its PID file (`$XDG_RUNTIME_DIR/zylaxion.pid`) and the daemon's\n  Unix socket (`$XDG_RUNTIME_DIR/zylaxion.sock`).\n- **Does not transmit keystrokes** — no telemetry, no analytics, no\n  crash reports. The only outbound network call is the explicit\n  `zylaxion --check-update` subcommand, which fetches the latest\n  GitHub release tag and exits. No background phone-home.\n- **Does not accept inbound network connections** — there is no TCP\n  listener, no HTTP server. The only IPC channel is a Unix domain\n  socket bound to `$XDG_RUNTIME_DIR/zylaxion.sock` with file mode\n  `0o600` (owner-only read/write). Other users on the system cannot\n  send `stop` / `status` commands to your daemon.\n\n### Why this matters\n\nA naive \"acoustic keyboard\" implementation that logged scancodes for\ndebugging would be a side-channel leak: malware with read access to\n`journalctl --user -u zylaxion` could reconstruct typed passwords by\nmapping scancodes back through the user's keyboard layout (QWERTY,\nDvorak, etc.). Zylaxion's zero-trust logging policy eliminates this\nattack surface — there is nothing in the logs to reconstruct.\n\n### Verifying the policy yourself\n\n```bash\n# Should print zero matches in production paths (excluding examples/\n# which carry an explicit --dump-scancodes opt-in for hardware\n# debugging):\ngrep -rn 'scancode' crates/ --include='*.rs' | \\\n    grep -E 'log::|println!|eprintln!' | \\\n    grep -v 'examples/'\n\n# Verify the IPC socket has mode 0o600 after starting the daemon:\nls -l \"$XDG_RUNTIME_DIR/zylaxion.sock\"\n# Expected: srw------- 1 user user 0 ... zylaxion.sock\n```\n\n## Building\n\n```bash\n# Run all checks (fmt + clippy + test)\n./scripts/build.sh --check-all\n\n# Build release binary\ncargo build --release --locked\n\n# Bump workspace version\n./scripts/version-to.sh v5.0.1\n```\n\n## Uninstall\n\n```bash\n./scripts/uninstall.sh\n```\n\n## Architecture\n\n```\nzylaxion-input          zylaxion-core           zactrix-engine          zylaxion-output\n(The Ears)              (The Brain)            (Zactrix Engine)        (The Mouth)\n───────────             ──────────             ───────────────         ─────────────\nLibinputSource ──►      recv_timeout()\n   KeyEvent               │\n                     trigger / release\n                           │\n                           ▼\n                     VoicePool::process()\n                           │\n                     [[f32; 2]] batch\n                           │\n                           ▼\n                     AudioSink::write_batch()\n                                          ringbuf ──►  cpal callback\n```\n\n## Intellectual Property \u0026 Trademark\n\n**zylaxion** is the exclusive intellectual property of\n**rezky_nightky (oxyzenQ)**.\n\n- Source code: licensed under **GPL-3.0-only** (see [LICENSE](LICENSE)).\n- Name, logo, and branding (\"the Marks\"): governed by\n  [TRADEMARK.md](TRADEMARK.md). The Marks are NOT covered by the GPL and\n  are reserved by the owner.\n- This project is **NOT for sale**. Unauthorized rebranding, relicensing,\n  or source-code theft is strictly prohibited.\n\nFor trademark licensing or written permission, contact\n**rezky_nightky (oxyzenQ)** — https://github.com/oxyzenQ.\n\n---\n\n© 2026 rezky_nightky (oxyzenQ). All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxyzenq%2Fzylaxion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxyzenq%2Fzylaxion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxyzenq%2Fzylaxion/lists"}