# OpenSuperWhisper Example Usage: Complete Guide to Real-Time Transcription

> Explore OpenSuperWhisper example usage with this comprehensive guide. Learn instant recording, batch processing, and Swift API integration for real-time transcription.

- Repository: [Starmel/OpenSuperWhisper](https://github.com/Starmel/OpenSuperWhisper)
- Tags: deep-dive
- Published: 2026-07-07

---

**TLDR:** OpenSuperWhisper provides three primary usage patterns: global keyboard shortcuts for instant recording, drag-and-drop batch file processing, and direct Swift API integration via the `WhisperEngine` class.

OpenSuperWhisper is a macOS GUI application that runs the Whisper transcription engine locally for real-time speech-to-text. Available as a Homebrew package and a full Xcode project on GitHub, the repository contains Swift classes implementing the complete transcription pipeline. This guide demonstrates concrete OpenSuperWhisper example usage extracted directly from the source code, covering installation, interactive workflows, and programmatic embedding.

## Installation and Setup

You can install the application via Homebrew or build from source using the provided scripts.

**Homebrew installation** (recommended):

```bash
brew update
brew install opensuperwhisper

```

**Building from source** requires the helper script [`run.sh`](https://github.com/Starmel/OpenSuperWhisper/blob/main/run.sh) at the repository root, which configures `libwhisper`, builds the `autocorrect-swift` library, and compiles the Xcode project:

```bash

# Clone the repository

git clone https://github.com/Starmel/OpenSuperWhisper.git
cd OpenSuperWhisper

# Execute the build script

./run.sh

```

The build script references [`libwhisper/CMakeLists.txt`](https://github.com/Starmel/OpenSuperWhisper/blob/main/libwhisper/CMakeLists.txt) for model compilation and generates the `OpenSuperWhisper.app` bundle with its entry point in [`OpenSuperWhisper/ContentView.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ContentView.swift).

## Interactive Usage Examples

These patterns require no code and utilize the global shortcut system defined in [`OpenSuperWhisper/Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Settings.swift).

### Real-Time Recording with Global Shortcuts

When the app launches, it registers system-wide hotkeys. By default, pressing **left ⌘**, **right ⌥**, or **Fn** starts recording on key-down and stops on key-up. Alternatively, configure a mouse button (middle-click or thumb button) in the Settings pane.

When a shortcut triggers, the app instantiates a `Recording` object from [`OpenSuperWhisper/Models/Recording.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Models/Recording.swift) and begins capturing microphone input. The [`AudioRecorder.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AudioRecorder.swift) class streams PCM frames to the transcription engine until the key is released.

### Batch Transcription via Drag-and-Drop

Process existing audio files without manual recording:

1. Drag any compatible audio file (WAV, MP3, M4A) onto the OpenSuperWhisper window
2. The app wraps the file path in a `Recording` instance
3. The file enters [`TranscriptionQueue.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/TranscriptionQueue.swift), which processes items sequentially using the shared `WhisperEngine` instance

```swift
// Simplified internal logic from TranscriptionQueue.swift
let fileURL = URL(fileURLWithPath: "/Users/me/meeting.m4a")
let recorder = Recording(fileURL: fileURL)
TranscriptionQueue.shared.enqueue(recorder)

```

The queue automatically handles conversion to PCM via [`AudioUtil.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AudioUtil.swift) and emits results through the same publisher pipeline used for live recording.

## Programmatic Usage Example

For embedding transcription in your own Swift projects, import the `Engines` module and instantiate `WhisperEngine` directly. This example demonstrates transcribing a local audio file programmatically:

```swift
import OpenSuperWhisper

// 1️⃣ Load a Whisper model (e.g., ggml-tiny.en.bin)
let modelURL = Bundle.main.url(forResource: "ggml-tiny.en", withExtension: "bin")!
let engine = try WhisperEngine(
    modelURL: modelURL,
    language: .english,
    temperature: 0.0
)

// 2️⃣ Load audio into PCM buffer
let audioURL = URL(fileURLWithPath: "/path/to/audio.wav")
let pcmData = try AudioUtil.loadPCM(from: audioURL)

// 3️⃣ Feed audio to the engine
try engine.appendAudio(pcmData)

// 4️⃣ Retrieve final transcription
let result = try engine.finalResult()
print("🗣️ Transcription:", result.text)

```

**Key source files referenced:**

- **[`OpenSuperWhisper/Engines/WhisperEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Engines/WhisperEngine.swift)** – Concrete implementation of the `TranscriptionEngine` protocol
- **[`OpenSuperWhisper/Utils/AudioUtil.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Utils/AudioUtil.swift)** – Helper for loading PCM data from common audio containers
- **[`OpenSuperWhisper/WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/WhisperModelManager.swift)** – Logic for locating and validating model binaries

## Core Architecture Components

Understanding these classes helps when extending the example usage patterns:

**[`TranscriptionEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/TranscriptionEngine.swift)** – Defines the protocol that all transcription backends implement, specifying methods for audio appending and result retrieval.

**[`WhisperEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/WhisperEngine.swift)** – The primary implementation that wraps the C++ Whisper bindings from `libwhisper`. It manages model state, language detection, and emits partial results through a Combine publisher.

**[`TranscriptionService.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/TranscriptionService.swift)** – Acts as the coordinator between the UI layer ([`ContentView.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ContentView.swift)), the audio recorder, and the engine. It handles instantiation of `WhisperEngine` via [`WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/WhisperModelManager.swift).

**[`AudioRecorder.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AudioRecorder.swift)** – Captures microphone samples in real-time and forwards them to the active engine instance.

## Summary

- **Install** via `brew install opensuperwhisper` or build locally using [`run.sh`](https://github.com/Starmel/OpenSuperWhisper/blob/main/run.sh) which configures `libwhisper` and the Xcode project
- **Record interactively** using global shortcuts defined in [`OpenSuperWhisper/Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Settings.swift), which trigger `Recording` objects and stream audio through [`AudioRecorder.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AudioRecorder.swift)
- **Process files** by dragging them onto the app window; [`TranscriptionQueue.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/TranscriptionQueue.swift) manages sequential processing through the shared engine
- **Integrate programmatically** by importing the `Engines` package and instantiating `WhisperEngine` with a model from [`WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/WhisperModelManager.swift)
- **Customize** language and model settings through the UI or by modifying [`WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/WhisperModelManager.swift) to load custom `.bin` models

## Frequently Asked Questions

### How do I install OpenSuperWhisper without building from source?

Use **Homebrew**. Run `brew install opensuperwhisper` to download the precompiled binary and all dependencies. This avoids compiling the `libwhisper` C++ libraries and the `autocorrect-swift` helper manually.

### Can I use OpenSuperWhisper as a library in my own Swift project?

Yes. The `WhisperEngine` class in [`OpenSuperWhisper/Engines/WhisperEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Engines/WhisperEngine.swift) provides a public API for embedding transcription. Import the module, initialize the engine with a model URL from [`WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/WhisperModelManager.swift), and feed PCM data using `appendAudio(_:)` to receive transcription results.

### Where are the global keyboard shortcuts configured?

Shortcut definitions and modifier key mappings reside in **[`OpenSuperWhisper/Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Settings.swift)**. You can customize single-modifier keys (like left ⌘ or right ⌥) and mouse buttons through the Settings UI, or modify the `Settings` struct directly in the source code to change default bindings.

### What audio formats are supported for batch transcription?

The [`TranscriptionQueue.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/TranscriptionQueue.swift) handler accepts standard formats including **WAV, MP3, and M4A**. The `Recording` model passes these files to [`AudioUtil.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AudioUtil.swift), which converts them to PCM buffers before feeding them into the `WhisperEngine` for processing.