Skip to content

Platform Quick-Start

This page covers platform-specific prerequisites, build steps, and first-run examples for macOS, Linux, and Windows.

For the install walkthrough, dependency overview, and backend configuration, see Getting Started.

Prerequisites

  • macOS 12 (Monterey) or later — Intel and Apple Silicon both supported

  • Go 1.23+ — install via Homebrew:

    brew install go

  • (Optional) ffmpeg for advanced WAV handling:

    brew install ffmpeg

Build

git clone https://github.com/Blackrim-Vox/blackrim-vox.git
cd blackrim-vox
make build
# Produces ./bin/vox

First run — transcribe a WAV (no API key, no network)

./bin/vox transcribe --asr echo path/to/file.wav

Live mic — echo stub

./bin/vox transcribe --live --asr echo
# Grant the microphone permission prompt once, then Ctrl-C to stop.

Local Whisper (offline, on-device)

./scripts/install-whisper-model.sh        # downloads ggml-base.en (~150 MB)
./bin/vox transcribe --live --asr whisper-cli

To install the whisper-cpp binary if it is not already on your PATH:

./scripts/install-whisper-model.sh --install-deps yes

Cloud ASR — bring your own key

# Deepgram (streaming + REST)
DEEPGRAM_API_KEY=dg_... ./bin/vox transcribe --live --asr deepgram

# AssemblyAI (REST)
ASSEMBLYAI_API_KEY=... ./bin/vox transcribe --live --asr assemblyai

# Azure Cognitive Services Speech
AZURE_SPEECH_KEY=... AZURE_SPEECH_REGION=eastus \
  ./bin/vox transcribe --live --asr azure

# Fallback chain — tries each backend in order
./bin/vox transcribe --live --asr fallback --asr-fallback deepgram,whispercli

Continuous listen mode

./bin/vox listen --asr whisper-cli

Indicator surface — macOS menubar

Status: scaffolded.

The daemon publishes recording state over a local Unix socket (~/.vox/indicator.sock) via internal/indicator/ipc/. Native CGo finalization — NSStatusItem menubar item and overlay dot — is not yet rendered. The indicator subsystem compiles and the IPC socket is live; the visible menubar icon is tracked in the roadmap.

Known limitations

  • Native menubar icon not yet rendered (scaffolded, not finalized)
  • Overlay dot requires CGo finalization (roadmap)

Prerequisites

  • Linux kernel 5.x or later with ALSA or PulseAudio

  • Go 1.23+ — install via your package manager:

    # Debian / Ubuntu
sudo apt install golang-go

# Fedora
sudo dnf install golang

# Arch
sudo pacman -S go

  • (For local Whisper) build tools:

    # Debian / Ubuntu
sudo apt install make cmake g++

# Fedora
sudo dnf install make cmake gcc-c++

# Arch
sudo pacman -S base-devel cmake

Build

git clone https://github.com/Blackrim-Vox/blackrim-vox.git
cd blackrim-vox
make build
# Produces ./bin/vox

Transcribe a WAV

./bin/vox transcribe --asr echo path/to/file.wav

Live mic

Live capture status

ALSA/PulseAudio live capture is not yet fully wired. Transcribing from a pre-recorded WAV file works reliably. Live mic input on Linux falls back to the filewav-based path and is best-effort today.

# Best-effort; results depend on your audio stack
./bin/vox transcribe --live --asr echo

Cloud ASR — bring your own key

DEEPGRAM_API_KEY=dg_... ./bin/vox transcribe --asr deepgram path/to/file.wav
ASSEMBLYAI_API_KEY=... ./bin/vox transcribe --asr assemblyai path/to/file.wav

Indicator surface — system tray

Status: roadmap.

internal/indicator/tray/tray_linux.go is implemented using ayatana-appindicator3 and D-Bus, but requires the native library at runtime. Until tray integration ships, recording state appears in stderr:

./bin/vox listen --asr echo
# Recording state logged to stderr

Full tray integration is tracked in the roadmap.

Known limitations

  • Live microphone capture is best-effort (ALSA/PulseAudio adapter not yet wired)
  • System tray requires libayatana-appindicator3 at runtime (roadmap)
  • Local Whisper build requires make, cmake, and g++

Prerequisites

Build (PowerShell)

git clone https://github.com/Blackrim-Vox/blackrim-vox.git
cd blackrim-vox
go build -o bin\vox.exe .\cmd\vox\...

make build also works if you have GNU make available via MSYS2 or Chocolatey.

First run — transcribe a WAV

.\bin\vox.exe transcribe --asr echo path\to\file.wav

Cloud ASR — bring your own key

$env:DEEPGRAM_API_KEY = "dg_..."
.\bin\vox.exe transcribe --asr deepgram path\to\file.wav

$env:ASSEMBLYAI_API_KEY = "..."
.\bin\vox.exe transcribe --asr assemblyai path\to\file.wav

Continuous listen mode

.\bin\vox.exe listen --asr echo

Indicator surface — system tray

Status: roadmap.

internal/indicator/tray/tray_windows.go is implemented using Shell_NotifyIcon / Win32, but CGo finalization is not yet complete. Foreground CLI mode is the supported path today:

.\bin\vox.exe listen --asr echo
# Recording state printed to the console

Full tray integration is tracked in the roadmap.

Known limitations

  • System tray icon requires CGo finalization (roadmap)
  • Local Whisper build requires MSYS2 or WSL2
  • Live microphone capture on Windows is untested; WAV file transcription is the verified path