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

> Contribute to the OpenSuperWhisper project by forking the repository, initializing submodules, installing dependencies, and building. Follow our guide to submit your pull request.

- Repository: [Starmel/OpenSuperWhisper](https://github.com/Starmel/OpenSuperWhisper)
- Tags: how-to-guide
- Published: 2026-07-05

---

**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:

```bash
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:

```bash
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:

```bash
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:

```bash
./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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisperApp.swift)** – Entry point that injects `TranscriptionService` into the SwiftUI view hierarchy
- **[`ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ShortcutManager.swift)** – Registers global hotkeys and forwards events to the transcription service
- **[`IndicatorWindow.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/IndicatorWindow.swift)** – Displays on-screen progress overlays during transcription
- **[`FileDropHandler.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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:

```bash
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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/.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

```bash
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:

```bash
./run.sh build

```

### 4. Commit with Clear Messages

Reference related issues in your commit:

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

```

### 5. Push and Open Pull Request

```bash
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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/Readme.md)【/cache/repos/github.com/Starmel/OpenSuperWhisper/master/Readme.md#L9-L23】 | Features, installation, and build instructions |
| **Whisper Build** | [`docs/build_whisper.md`](https://github.com/Starmel/OpenSuperWhisper/blob/main/docs/build_whisper.md) | Detailed whisper.cpp compilation steps |
| **Model Management** | [`OpenSuperWhisper/WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/WhisperModelManager.swift) | All model storage and download logic |
| **Transcription Core** | [`OpenSuperWhisper/TranscriptionService.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/TranscriptionService.swift) | Async pipeline and cancellation handling |
| **Keyboard Shortcuts** | [`OpenSuperWhisper/ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ShortcutManager.swift) | Global hotkey registration |
| **UI Components** | [`OpenSuperWhisper/ContentView.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/ContentView.swift), [`IndicatorWindow.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/IndicatorWindow.swift) | Main interface and progress overlay |
| **CI/CD** | [`.github/workflows/build.yml`](https://github.com/Starmel/OpenSuperWhisper/blob/main/.github/workflows/build.yml) | Automated build and test configuration |
| **Release Process** | [`docs/release_build.md`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/WhisperModelManager.swift) (modify `copyDefaultModelIfNeeded` or UI selection) | Confirm model appears in list and loads without errors |
| **Improve shortcut handling** | [`ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ShortcutManager.swift) | Test that start/stop triggers work without system conflicts |
| **Fix UI layout issues** | [`ContentView.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/ContentView.swift) or related SwiftUI files | Visual verification on macOS 13+ devices |
| **Update documentation** | [`README.md`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/WhisperModelManager.swift) handles models, [`TranscriptionService.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/TranscriptionService.swift) coordinates transcription, and [`ShortcutManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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`](https://github.com/Starmel/OpenSuperWhisper/blob/main/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:

```bash
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.