Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.useraven.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Install Xcode Command Line Tools

xcode-select --install
A system dialog will appear - click Install and wait for it to finish (~2 min).Verify:
xcode-select -p
# Expected: /Library/Developer/CommandLineTools  (or an Xcode.app path)
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.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
Close and reopen your terminal, then:
nvm install 22
nvm use 22
Verify:
node -v
# Expected: v22.x.x (any 22+ version)
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

brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad
Don’t have Homebrew? Install it first from brew.sh.
Verify:
pkg-config --modversion gstreamer-1.0
# Expected: 1.24.x (or similar)
Homebrew’s pkg-config path isn’t set. Add the correct line to your ~/.zshrc and restart your terminal:
# Apple Silicon (M1/M2/M3/M4):
echo 'export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc

# Intel Mac:
echo 'export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc
4

Clone the repo and install dependencies

git clone https://github.com/Laxcorp-Research/project-raven.git
cd project-raven
npm install
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:
ls node_modules/.package-lock.json && echo "OK"
# Expected: OK
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

cd src/native/aec
npm install
./build-deps.sh
npx cmake-js compile
cd ../../..
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:
ls src/native/aec/build/Release/raven-aec.node && echo "OK"
# Expected: OK
  • 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

cd src/native/swift/AudioCapture
swift build -c release
cd ../../../..
Verify:
ls src/native/swift/AudioCapture/.build/release/audiocapture && echo "OK"
# Expected: OK
Your Swift toolchain may be too old (5.9+ required). Check with swift --version. Update Xcode Command Line Tools:
sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install
7

Run the app

npm run dev
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:
PermissionWhy it’s neededHow to grant
MicrophoneCapture your voiceSystem Settings > Privacy & Security > Microphone
Screen RecordingCapture system audioSystem Settings > Privacy & Security > Screen Recording
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

SymptomFix
build-deps.sh: “gstreamer-1.0 not found”Revisit Step 3 - check pkg-config --modversion gstreamer-1.0
cmake-js compile fails with “cmake not found”Run npx cmake-js --version - if it fails, delete node_modules inside src/native/aec/ and re-run npm install
swift build fails with unresolved importsSwift toolchain too old (5.9+ required)
npm install fails with node-gyp errorsxcode-select --install - ensure CLI tools are installed
NODE_MODULE_VERSION mismatch at runtimenpx @electron/rebuild -f -w better-sqlite3 from the project root
No audio captured despite permissions grantedRestart the app - macOS sometimes requires a restart after granting Screen Recording
App starts, no audioSystem Settings > Privacy & Security: grant Microphone and Screen Recording