Voxlet

Voxlet is a native macOS push-to-talk utility. Hold the global shortcut, speak, and release; Voxlet transcribes locally, copies the result, pastes into the frontmost application when Accessibility permission is available, and saves a local text-only history.

Required model

Voxlet only supports animaslabs/parakeet-tdt-0.6b-v3-mlx-4bit, pinned to revision 65247a0a9e735426eba06056a9535f7e67dcbbb9. The app downloads the six runtime files into ~/Library/Application Support/Voxlet/Models/ and validates the 4-bit, group-size-64 configuration before loading weights. No alternate ASR model or cloud service is present.

Architecture

• SwiftUI/AppKit application and menu-bar extra
• Carbon hotkeys for key combinations; AppKit modifier monitoring for the default Right Command trigger
• AVAudioEngine in-memory recording and 16 kHz mono PCM conversion
• persistent bundled parakeet_mlx 0.5.2 + MLX 0.32.0 helper
• newline-delimited JSON IPC over private process pipes; no server or socket
• atomic JSON history in Application Support; audio is never persisted
• non-activating NSPanel floating pill

The helper constructs the Parakeet TDT model from config.json, calls mlx.nn.quantize(bits: 4, group_size: 64) before loading model.safetensors, and stays alive with the model warm.

Build and run

Requirements for developers: Apple Silicon, macOS 15+, Xcode, and Python 3.11+ to create the bundled helper. End users do not need Python or Terminal.

./script/build_and_run.sh
./script/build_and_run.sh --verify
DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer swift test
./script/package_app.sh release

The packaged app is written to dist/Voxlet.app. The first helper build creates a project-local virtual environment and can take several minutes. Subsequent app builds reuse the frozen helper. The packaging script automatically uses the first available Apple Development identity so macOS permission grants remain stable across local rebuilds; it falls back to ad-hoc signing only when no development identity exists. Set CODE_SIGN_IDENTITY to override the choice.

Permissions

• Microphone: required for recording.
• Accessibility: required for the default Right Command trigger and to synthesize Cmd+V. If denied, a custom Carbon key combination still works and Voxlet still copies and saves every successful transcription.

Input Monitoring, Screen Recording, Automation, network listening, analytics, and telemetry permissions are not used.

Developer ID and notarization

Set CODE_SIGN_IDENTITY to a Developer ID Application identity when packaging:

CODE_SIGN_IDENTITY='Developer ID Application: Example (TEAMID)' ./script/package_app.sh release
ditto -c -k --keepParent dist/Voxlet.app dist/Voxlet.zip
xcrun notarytool submit dist/Voxlet.zip --keychain-profile voxlet-notary --wait
xcrun stapler staple dist/Voxlet.app
spctl -a -vv --type execute dist/Voxlet.app

The package script signs every nested Mach-O helper component, then the main binary and outer bundle with hardened runtime enabled. The bundled-Python helper alone disables library validation and permits executable memory because librosa's bundled Numba dependency initializes LLVM; the native Voxlet process retains only the audio-input entitlement. The helper has no listener or network server and communicates only through inherited private pipes.