This repository is an actively maintained fork of the original Mechvibes project with numerous improvements, fixes, and new features.

Official website: mechvibes-cbc.pages.dev

This project runs natively across major platforms. Below are the minimal OS and runtime version requirements:

• Windows:

  • OS Version: Windows 10 (Build 1903/19H1) or later (64-bit).
  • Runtime: Electron 43.1+ base, Node.js 22.

• macOS:

  • OS Version: macOS 10.15 (Catalina) or later.
  • Architecture: Intel (x64) & Apple Silicon natively compatible.

• Linux:

  • Linux Kernel: Kernel version 5.4 or newer (with standard user namespaces enabled for Electron sandbox).
  • GLIBC Requirement: glibc 2.31 or newer (Ubuntu 20.04+, Debian 11+, Fedora 32+).
  • Formats: Available as Debian packages (.deb), snappy packages (.snap), and universal standalone .AppImage runtimes.

• 🎹 Realistic mechanical keyboard sound simulation
• 🎵 Support for Soundpack v1, v2 and v3
• ⚡ Low-latency Web Audio playback engine
• 🎧 Output device selection
• 🌙 Dark mode support
• 📦 Easy soundpack installation and management
• 🖱️ Keyboard and mouse sound support
• 🔄 Stable and beta update channels
• 🪟 Improved Windows compatibility
• 🚀 Modern Electron runtime
• 🛠️ Continuous fixes and improvements

This fork focuses on improving the original Mechvibes experience while remaining compatible with the existing ecosystem.

Highlights include:

• Modernized Electron runtime
• Fully typed TypeScript codebase and a React user interface
• Updated global input hook
• Improved Windows stability
• Better release automation
• Soundpack v3 support
• Lower audio latency
• Safer soundpack management
• Numerous bug fixes and performance improvements
• Ongoing maintenance and feature development

Additional documentation:

• docs/soundpack-v3.md
• docs/releases.md
• docs/windows-critical-fixes.md

Download the latest release from:

https://github.com/omnizs38/mechvibes-cbc/releases/latest

Run the installer and enjoy.

Every source file under src/, tools/ and tests/ is TypeScript. The compiled JavaScript (src/**/*.js, tools/**/*.js, tests/**/*.js) and the renderer bundle (src/renderer-dist/) are build artefacts: they are ignored by git and regenerated by the scripts below, so always build before running or packaging.

Requires Node.js 22.22.0 (see .nvmrc).

npm ci
npm run verify
npm start

npm start compiles the main process, bundles the renderer and launches Electron. The individual steps are also available:

Build installers (each target compiles the sources first):

npm run build:win
npm run build:mac
npm run build:linux

On Windows, packaging rebuilds the native uiohook-napi module, which requires Visual Studio Build Tools with the "Desktop development with C++" workload. Without it electron-builder fails with Could not find any Visual Studio installation to use. The release workflow builds all three platforms on GitHub Actions, where the toolchains are preinstalled.

• Soundpack v3 Specification
• Release Process
• Windows Critical Fix Verification

See the docs/ directory.

Contributions are welcome.

If you find a bug or have an idea for a new feature, feel free to open an issue or submit a pull request.

Before opening a pull request, run npm run verify — the same script gates CI.

This repository is a fork of the original Mechvibes project created by Hai Nguyen.

• The original upstream source code is licensed under the MIT License. See LICENSE.MIT.

• Modifications and new contributions made by omnizs38 are licensed under the Mozilla Public License Version 2.0 (MPL-2.0). See LICENSE.

Additional copyright and licensing information is available in the NOTICE file.

Original project:

https://github.com/hainguyents13/mechvibes

Thanks to Hai Nguyen for creating the original Mechvibes project and to everyone who has contributed to both the upstream project and this fork.