# Does OpenSuperWhisper Offer an API?

> Explore the OpenSuperWhisper API. Discover how to use its internal Swift API for programmatic transcription within your macOS applications.

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

---

**OpenSuperWhisper does not expose a public HTTP/REST API for external network access, but provides a comprehensive internal Swift API centered on `TranscriptionService` that enables programmatic transcription for code running within the same macOS process.**

OpenSuperWhisper is a native macOS transcription application built around OpenAI's Whisper models. While the repository does not implement server-based networking endpoints, it exposes a robust internal architecture that Swift developers can leverage to drive transcription workflows programmatically. This design allows deep integration with the transcription engine without requiring external HTTP calls.

## No Public HTTP/REST API

Analysis of the source code reveals no networking endpoints, REST controllers, or HTTP server implementations. The application is architected as a standalone macOS client using Swift and SwiftUI, with all transcription functionality encapsulated within the app bundle. Unlike server-based transcription services, OpenSuperWhisper does not listen on TCP ports or expose webhooks that external applications could query over the network.

## The Internal Swift API Architecture

The internal API revolves around a singleton service pattern that coordinates model management, audio processing, and transcription execution:

- **`TranscriptionService`** – Located in [`OpenSuperWhisper/TranscriptionService.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/TranscriptionService.swift), this singleton acts as the primary entry point. It manages engine initialization, model switching, and exposes the async `transcribeAudio(url:settings:)` method.

- **`TranscriptionEngine`** protocol – Defined in [`OpenSuperWhisper/Engines/TranscriptionEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Engines/TranscriptionEngine.swift), this protocol establishes the contract for transcription implementations, requiring methods like `initialize()`, `transcribeAudio()`, and `cancelTranscription()`.

- **`WhisperEngine`** – Implemented in [`OpenSuperWhisper/Engines/WhisperEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Engines/WhisperEngine.swift), this concrete class handles the Whisper-cpp integration, audio conversion, Voice Activity Detection (VAD), and progress callbacks.

- **`WhisperModelManager`** – Found in [`OpenSuperWhisper/WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/WhisperModelManager.swift), this utility handles downloading model files from Hugging Face repositories and caching them locally.

- **`Settings`** – Defined in [`OpenSuperWhisper/Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Settings.swift), this configuration object stores user preferences including language selection, temperature, and timestamp options.

## How to Programmatically Transcribe Audio

To use OpenSuperWhisper's API in your own Swift code, import the framework and interact with `TranscriptionService.shared`. The workflow requires preparing a local audio file URL, configuring a `Settings` object, and awaiting the asynchronous transcription result.

```swift
import OpenSuperWhisper

// Prepare the audio file URL (must be a local file)
let audioURL = URL(fileURLWithPath: "/path/to/audio.wav")

// Create a Settings object matching the UI configuration
var transcriptionSettings = Settings()
transcriptionSettings.selectedLanguage = "en"          // or "auto"
transcriptionSettings.temperature = 0.2
transcriptionSettings.showTimestamps = false

// Execute transcription asynchronously
Task {
    do {
        let result = try await TranscriptionService.shared.transcribeAudio(
            url: audioURL,
            settings: transcriptionSettings
        )
        print("Transcription result:\n\(result)")
    } catch {
        print("Failed to transcribe: \(error)")
    }
}

```

## Monitoring Progress via Combine

The `TranscriptionService` publishes real-time progress updates using the Combine framework. Observe the `$progress` publisher to receive float values between 0.0 and 1.0 representing completion percentage.

```swift
import Combine

let cancellable = TranscriptionService.shared.$progress
    .sink { progress in
        print("Progress: \(progress * 100)%")
    }

```

## Key Source Files and Their Roles

| File | Role |
|------|------|
| [`OpenSuperWhisper/TranscriptionService.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/TranscriptionService.swift) | Singleton coordinating model loading and the async `transcribeAudio` entry point. |
| [`OpenSuperWhisper/Engines/WhisperEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Engines/WhisperEngine.swift) | Whisper-cpp integration handling audio conversion and VAD. |
| [`OpenSuperWhisper/Engines/TranscriptionEngine.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Engines/TranscriptionEngine.swift) | Protocol defining the common transcription interface. |
| [`OpenSuperWhisper/WhisperModelManager.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/WhisperModelManager.swift) | Automated model downloading and caching from Hugging Face. |
| [`OpenSuperWhisper/Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Settings.swift) | Configuration storage for transcription parameters. |

## Summary

- OpenSuperWhisper does **not** offer a network-accessible HTTP/REST API.
- Programmatic access requires Swift code running in the same macOS process as the application.
- The primary API entry point is `TranscriptionService.shared.transcribeAudio(url:settings:)`.
- Real-time progress monitoring is available through Combine publishers on the shared service instance.
- All major components follow the `TranscriptionEngine` protocol, enabling extensible architecture.

## Frequently Asked Questions

### Can I access OpenSuperWhisper via HTTP requests from another application?

No. OpenSuperWhisper is a native macOS application without HTTP server components. It does not expose REST endpoints, socket listeners, or webhook interfaces for external network access. All API interactions must occur within the same process using Swift method calls.

### How do I integrate OpenSuperWhisper into my own Swift project?

Import the source files or framework into your Xcode project and reference `TranscriptionService.shared`. Call the `transcribeAudio(url:settings:)` method with a local file URL and a configured `Settings` object. The method returns a `String` containing the transcription text via Swift's async/await pattern.

### Is there a Python or JavaScript API available for OpenSuperWhisper?

No. The API is Swift-only and requires execution within the same macOS process. There are no language bindings, FFI interfaces, or subprocess APIs for Python, JavaScript, or other languages. Developers requiring cross-language support would need to build a wrapper service that links against the Swift codebase.

### Can I monitor transcription progress programmatically?

Yes. The `TranscriptionService` exposes a `@Published` property named `progress` that emits Float values from 0.0 to 1.0. Subscribe to this publisher using the Combine framework to receive real-time updates during the transcription process, enabling progress bars or status indicators in your own UI.