OpenWhisper

A Free and Open Source alternative to WhisperFlow (and competitors) for Apple Silicon macs.

Features

• Local Audio Transcription: Support for local transcription models using OpenAI's whisper models optimised for MLX (Apple Silicon) or other platforms (using Faster Whisper)
• Intelligent Text Notation: Removes disfluencies, self-corrects text and cleans up transcription using LLMs (support for both local and cloud)
• Privacy First: ALL processing can be ran on device.
• Flexible LLM Integration: Supports Ollama, LM Studio, or any Open-AI compatiable API

Architecture

OpenWhisper has two main components:

Backend (Python + FastAPI)

• FastAPI server for audio transcription
• MLX Whisper for Apple Silicon, Faster Whisper for other platforms
• LLM integration for text normalisation (Ollama, LM Studio, and cloud providers)

macOS App (Swift + SwiftUI)

• Native macOS interface
• Global hotkey for recording
• Automatic text inseration after transcription

Installation

1. Backend Setup

Using Docker (Recommended):

cd backend

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your settings (generate token with: openssl rand -hex 32)

# Start services (includes Ollama by default)
docker-compose up -d

# Pull a model for Ollama
docker exec ollama-server ollama pull llama2

Using Python:

cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run the server
uvicorn main:app --host 0.0.0.0 --port 8000

2. macOS App Setup

cd macos-app

# Open in Xcode
open openwhisper.xcodeproj

# Build and run (⌘R)

Or build from command line:

xcodebuild -project openwhisper.xcodeproj -scheme openwhisper -configuration Release

Configuration

Backend Configuration

Create a .env file in the backend/ directory:

# API Authentication
API_AUTH_TOKEN=your_secure_token_here  # Generate with: openssl rand -hex 32

# LLM Provider (ollama, lm_studio, or cloud)
LLM_PROVIDER=ollama
LLM_MODEL_NAME=llama2

# Ollama Configuration
OLLAMA_SERVER_URL=http://localhost
OLLAMA_SERVER_PORT=11434

# LM Studio Configuration
LM_STUDIO_SERVER_URL=
LM_STUDIO_SERVER_PORT=1234

# Cloud API Configuration (for OpenAI-compatible APIs)
CLOUD_API_BASE_URL=https://api.openai.com/v1
CLOUD_API_KEY=your_api_key_here

# Transcription Provider (local or cloud)
TRANSCRIPTION_PROVIDER=local
TRANSCRIPTION_MODEL_NAME=whisper-large-v3

macOS App Configuration

1. Launch the app
2. Click the menu bar icon
3. Select "Settings"
4. Configure:
   • API endpoint (default: http://localhost:8000)
   • API token (must match backend API_AUTH_TOKEN)
   • Global hotkey (default: ⌘⌥R)

Usage

macOS App

1. Press the global hotkey to start recording
2. Speak your audio
3. Press the hotkey again to stop recording
4. The transcribed text will be automatically typed into your active application

API Usage

See docs/API.md for detailed API documentation, including:

• Authentication
• Endpoints
• Request/Response formats
• Code examples (Python, JavaScript, cURL)
• Error handling
• Docker deployment

Quick Example:

# Health check
curl http://localhost:8000/health

# Transcribe audio
curl -X POST http://localhost:8000/transcribe \
  -H "Content-Type: application/json" \
  -H "Authorization: your_auth_token" \
  -d '{"audio_base64":"'$(base64 -i audio.mp3)'"}'

License

GPL-3.0-or-later