Skip to main content
Tested on macOS 12 (Monterey) through macOS 15 (Sequoia), Intel and Apple Silicon.
1

Install Xcode Command Line Tools

A system dialog will appear - click Install and wait for it to finish (~2 min).Verify:
If you see xcode-select: error: command line tools are already installed - you’re good, move on.
2

Install Node.js 22

Install via nvm (recommended). Skip the curl line if you already have nvm.
Close and reopen your terminal, then:
Verify:
If nvm: command not found: Close your terminal and open a new one - nvm’s install script adds itself to your shell profile, but only new shells pick it up.
3

Install GStreamer

Don’t have Homebrew? Install it first from brew.sh.
Verify:
Homebrew’s pkg-config path isn’t set. Add the correct line to your ~/.zshrc and restart your terminal:
4

Clone the repo and install dependencies

npm install takes a few minutes. It automatically rebuilds better-sqlite3 for Electron via the postinstall script - you’ll see @electron/rebuild output near the end.Verify:
If npm install fails with node-gyp errors, make sure Xcode Command Line Tools installed successfully in Step 1. Run xcode-select -p to confirm.
5

Build the GStreamer echo-cancellation addon

What this does:
  1. Installs the addon’s build tools (cmake-js, node-addon-api)
  2. Verifies all GStreamer libraries and builds the WebRTC DSP plugin from source (Homebrew doesn’t ship it)
  3. Compiles the C++ echo-cancellation native module
Verify:
  • build-deps.sh fails with “gstreamer-1.0 not found”: Revisit Step 3 and make sure pkg-config --modversion gstreamer-1.0 works.
  • cmake-js compile fails with “cmake not found”: cmake is bundled with cmake-js. Run npx cmake-js --version - if that fails, delete node_modules inside src/native/aec/ and re-run npm install.
6

Build the Swift audio capture binary

Verify:
Your Swift toolchain may be too old (5.9+ required). Check with swift --version. Update Xcode Command Line Tools:
7

Run the app

The Electron app opens. On first launch you’ll be prompted to enter your API keys (Deepgram for transcription, Claude or OpenAI for AI assistance).
If audio capture doesn’t work: macOS requires explicit permissions. Go to System Settings > Privacy & Security and grant both Microphone and Screen Recording access to the app (or to your terminal emulator during development).

​
Required Permissions

macOS requires explicit user consent for audio capture. On first recording, the app will request these:
During development, you may need to grant these permissions to your terminal emulator (e.g., iTerm, Terminal.app) rather than the Electron app directly. In production builds, the signed .app is the target.

​
Troubleshooting