Building Handy on an Intel Mac: A Step-by-Step Guide

Handy is a fantastic free and open-source speech-to-text application that runs completely offline, respecting your privacy while providing a powerful transcription service. While you can download pre-built versions from the website, building it from source gives you the ability to customize and contribute to the project.

This guide will walk you through the process of building Handy on an Intel-based Mac, including some of the common issues you might encounter and how to solve them.

Prerequisites

Before we begin, you’ll need to have a few tools installed on your system:

• Rust: The backend of Handy is written in Rust. You can install it via rustup.rs.
• Bun: Handy uses the Bun JavaScript runtime and package manager. You can install it from bun.sh.
• Xcode Command Line Tools: These tools are essential for development on macOS. You can install them by running xcode-select --install in your terminal.
• Homebrew: The “missing package manager for macOS”. We’ll need it to install one of the dependencies. You can install it from brew.sh.

Step 1: Getting the Source Code

First, you’ll need to clone the Handy repository from GitHub. Open your terminal and run:

git clone https://github.com/cjpais/Handy.git
cd Handy

Step 2: Installing Dependencies

Next, we’ll install the project’s JavaScript dependencies using Bun:

bun install

Step 3: Downloading the VAD Model

Handy uses a Voice Activity Detection (VAD) model to filter out silence. You’ll need to download this model and place it in the correct directory:

mkdir -p src-tauri/resources/models
curl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx

Step 4: The First Build Attempt (and a CMake fix)

With the setup complete, let’s try to build and run the application in development mode:

bun run tauri dev

You might encounter an error at this stage related to cmake:

failed to execute command: No such file or directory (os error 2)
is `cmake` not installed?

This error means that cmake, a tool required to build one of Handy’s dependencies, is not installed. We can easily install it using Homebrew:

brew install cmake

Once cmake is installed, you can try running bun run tauri dev again. This time, it should compile successfully and launch the application in development mode.

Step 5: The Production Build (and a TypeScript fix)

To create a distributable application that you can install on your system, you’ll need to run the build command:

bun run tauri build

During this process, you might come across a TypeScript error:

src/stores/settingsStore.ts:137:57 - error TS2345: Argument of type '{ autoSave: false; }' is not assignable to parameter of type 'StoreOptions'.

This error occurs because the code is calling a function to load settings without providing a default configuration. To fix this, you’ll need to edit src/stores/settingsStore.ts.

Find this line:

const store = await load("settings_store.json", { autoSave: false });

And change it to:

const store = await load("settings_store.json", { defaults: DEFAULT_SETTINGS, autoSave: false });

This change provides the necessary default settings and will allow the build to proceed.

Step 6: The Final Build and Installation

Now, run the build command again:

bun run tauri build

This time, the build should complete successfully. You’ll see a lot of output in your terminal, and at the end, you’ll find the paths to the application bundle and a DMG installer:

/Users/mthompson/Projects/local/Handy/src-tauri/target/release/bundle/macos/Handy.app
/Users/mthompson/Projects/local/Handy/src-tauri/target/release/bundle/dmg/Handy_0.5.4_x64.dmg

You can now open the DMG file and drag Handy.app to your “Applications” folder to install it.

Note: You might see a warning about code signing. This is normal for a local build. When you first open the application, you may also see a security warning from macOS. You can bypass this by right-clicking the app and selecting “Open”.

Conclusion

Building Handy from source is a great way to get a feel for the project and its architecture. We’ve seen how to set up the development environment, troubleshoot common build errors, and create a distributable application. Now you have a working version of Handy on your Intel Mac, and you’re ready to start transcribing!