How to Contribute to the OpenSuperWhisper Project: A Comprehensive Developer Guide

To contribute to OpenSuperWhisper, fork the repository, initialize submodules with git submodule update --init --recursive, install dependencies via Homebrew, and build with ./run.sh build before submitting a pull request.

OpenSuperWhisper is an open-source macOS application that provides real-time audio transcription using interchangeable Whisper and Parakeet engines. Whether you want to fix bugs, add features, or improve documentation, this guide covers the complete contribution workflow with specific references to the Swift source code and build system.

---

Setting Up Your Development Environment

A proper local environment is essential before you can contribute to OpenSuperWhisper. The project combines Swift UI, C++ transcription engines via submodules, and Ruby tooling for build automation.

Step 1: Fork and Clone the Repository

Start by creating your own fork on GitHub, then clone it locally:

git clone https://github.com/<your-username>/OpenSuperWhisper.git
cd OpenSuperWhisper

Step 2: Initialize Submodules

The project depends on whisper.cpp and other native libraries managed as Git submodules. Run this command to pull all dependencies:

git submodule update --init --recursive

This step is critical—without it, the C++ transcription engines will not compile.

Step 3: Install Build Dependencies

The build pipeline requires CMake, OpenMP, Rust, and Ruby. Install these via Homebrew:

brew install cmake libomp rust ruby
gem install xcpretty

The xcpretty gem formats Xcode build output for readability during compilation.

Step 4: Build the Application

OpenSuperWhisper uses a custom build script that orchestrates CMake and Swift compilation:

./run.sh build

This command compiles the whisper.cpp engine, links native libraries, and builds the Swift package. For development, you can also open OpenSuperWhisper.xcodeproj in Xcode or use ./run.sh launch for a quick test run.

All setup steps are documented in the repository's Readme under the Installation and Building locally sections【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/Readme.md#L21-L48】.

---

Understanding the Core Architecture

Before contributing code, understand how OpenSuperWhisper's components interact. The app follows a clean separation between model management, transcription services, and UI interaction.

Model Management (WhisperModelManager.swift)

The WhisperModelManager singleton handles all Whisper model files in ~/Library/Application Support/<bundle-id>/whisper-models. Key functionality includes:

• Directory initialization – createModelsDirectoryIfNeeded() (lines 61-66) ensures the models folder exists【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/WhisperModelManager.swift#L61-L66】
• Default model setup – copyDefaultModelIfNeeded() (lines 69-86) copies bundled models on first launch【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/WhisperModelManager.swift#L69-L86】
• Download with progress – downloadModel(url:name:progressCallback:) (lines 109-188) uses URLSession with a custom WhisperDownloadDelegate to stream progress updates【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/WhisperModelManager.swift#L109-L188】
• Cancellation support – cancelDownload(name:) (lines 190-199) allows aborting in-progress downloads【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/WhisperModelManager.swift#L190-L199】

Transcription Pipeline (TranscriptionService.swift)

The TranscriptionService class (an ObservableObject) coordinates the entire transcription flow. Critical methods include:

• Engine loading – loadEngine() (lines 37-53) selects between whisper and fluidaudio engines and initializes them asynchronously【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/TranscriptionService.swift#L37-L53】
• Progress callbacks – Lines 17-32 attach onProgressUpdate closures to concrete engines for real-time UI updates【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/TranscriptionService.swift#L17-L32】
• Cancellation handling – The service checks a shared isCancelled flag at lines 24-44 and 67-77 to abort tasks gracefully【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/TranscriptionService.swift#L24-L44】【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/OpenSuperWhisper/TranscriptionService.swift#L67-L77】

UI and Interaction Components

• OpenSuperWhisperApp.swift – Entry point that injects TranscriptionService into the SwiftUI view hierarchy
• ShortcutManager.swift – Registers global hotkeys and forwards events to the transcription service
• IndicatorWindow.swift – Displays on-screen progress overlays during transcription
• FileDropHandler.swift – Handles drag-and-drop of audio files for batch processing

---

Running Tests and Validation

OpenSuperWhisper includes XCTest suites covering model loading, engine initialization, and UI state updates. Run tests from the command line:

xcodebuild test -scheme OpenSuperWhisper -destination 'platform=macOS,arch=x86_64'

When contributing new features, add corresponding tests in the OpenSuperWhisperTests or OpenSuperWhisperUITests folders. The CI configuration in .github/workflows/build.yml defines the required build environment and validation steps.

---

Making Your First Contribution

Follow this workflow to submit changes to the OpenSuperWhisper project:

1. Create a Feature Branch

git checkout -b feature/your-description

2. Implement and Format

Maintain consistency with existing Swift code. Use Xcode's built-in formatter (Control-I) to match the project's style.

3. Validate with Full Build

Run the complete build pipeline to catch integration issues:

./run.sh build

4. Commit with Clear Messages

Reference related issues in your commit:

git add .
git commit -m "Add voice activation toggle (Closes #42)"

5. Push and Open Pull Request

git push origin feature/your-description

Target the upstream master branch. Include:

• A clear description of changes
• Reference to any related issues (e.g., "Closes #15")
• Explanation of new dependencies or permission requirements

The Readme explicitly encourages contributions at lines 55-59【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/Readme.md#L55-L59】.

---

Key Source Files Every Contributor Should Know

Area	File Path	Purpose
Project Overview	Readme.md【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/Readme.md#L9-L23】	Features, installation, and build instructions
Whisper Build	docs/build_whisper.md	Detailed whisper.cpp compilation steps
Model Management	OpenSuperWhisper/WhisperModelManager.swift	All model storage and download logic
Transcription Core	OpenSuperWhisper/TranscriptionService.swift	Async pipeline and cancellation handling
Keyboard Shortcuts	OpenSuperWhisper/ShortcutManager.swift	Global hotkey registration
UI Components	OpenSuperWhisper/ContentView.swift, IndicatorWindow.swift	Main interface and progress overlay
CI/CD	.github/workflows/build.yml	Automated build and test configuration
Release Process	docs/release_build.md	Packaging and code signing procedures

---

Common First-Timer Tasks

Task	Files to Edit	Verification Steps
Add new language model	WhisperModelManager.swift (modify copyDefaultModelIfNeeded or UI selection)	Confirm model appears in list and loads without errors
Improve shortcut handling	ShortcutManager.swift	Test that start/stop triggers work without system conflicts
Fix UI layout issues	ContentView.swift or related SwiftUI files	Visual verification on macOS 13+ devices
Update documentation	README.md, docs/*.md	Run ./run.sh build to confirm accuracy

---

Summary

• Fork and clone the repository, then run git submodule update --init --recursive to fetch native dependencies
• Install build tools with brew install cmake libomp rust ruby and build via ./run.sh build
• Understand the architecture: WhisperModelManager.swift handles models, TranscriptionService.swift coordinates transcription, and ShortcutManager.swift manages global hotkeys
• Test changes using xcodebuild test before submitting
• Submit pull requests targeting master with clear commit messages and issue references

---

Frequently Asked Questions

What programming languages does OpenSuperWhisper use?

OpenSuperWhisper is primarily built in Swift for the macOS UI and application logic. It integrates C++ through whisper.cpp for on-device transcription and uses Ruby scripts for build automation. The project also includes Rust dependencies for certain native components.

Do I need a paid Apple Developer account to contribute?

No. You can build and run OpenSuperWhisper locally with the free Xcode tools. However, testing certain features like code signing or creating release builds may require a Developer ID. The docs/release_build.md file documents the full signing process for maintainers.

How do I update the whisper.cpp submodule to a newer version?

Navigate to the submodule directory and pull the latest upstream changes, then commit the updated submodule reference:

cd whisper.cpp
git pull origin master
cd ..
git add whisper.cpp
git commit -m "Update whisper.cpp to latest upstream"

Verify the build still compiles with ./run.sh build before submitting this change.

Where should I report bugs or request features?

Open an issue on the GitHub repository with a clear reproduction case for bugs, or a detailed use case for feature requests. Check existing issues first to avoid duplicates. The repository may also reference community channels in the README for real-time discussion.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}