# OpenSuperWhisper Configuration Options in AppPreferences.swift: Complete Reference Guide

> Explore all 21 configuration options in AppPreferences.swift for OpenSuperWhisper. Learn how to customize transcription language, hotkeys, and more with this complete reference guide.

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

---

**OpenSuperWhisper stores all user-tunable settings in [`AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AppPreferences.swift) using a singleton `AppPreferences` class that wraps `UserDefaults` with custom property wrappers, exposing 21 configuration options ranging from transcription language to hotkey behavior.**

OpenSuperWhisper, an open-source voice transcription application for macOS and iOS, centralizes its persistent user preferences in [`OpenSuperWhisper/Utils/AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Utils/AppPreferences.swift). This Swift file defines the `AppPreferences` class—a thread-safe singleton accessed via `AppPreferences.shared`—that abstracts the underlying `UserDefaults` system with compile-time type safety. Understanding these configuration options enables developers to programmatically customize transcription engines, decoding parameters, and automation workflows.

## Architecture of AppPreferences.swift

The `AppPreferences` class implements the **singleton pattern** to guarantee a single source of truth across the application lifecycle. Rather than accessing `UserDefaults` directly, the architecture relies on two custom property wrappers defined in the same file:

- **`@UserDefault`**: Persists non-optional values (`String`, `Bool`, `Double`, `Int`) and guarantees a default value when no data exists
- **`@OptionalUserDefault`**: Persists optional values (`String?`, `Data?`) that may legitimately be `nil`

On first initialization, the class executes `migrateOldPreferences()` (lines 30-35) to ensure backward compatibility. This routine automatically migrates the legacy `selectedModelPath` key to the current `selectedWhisperModelPath` key, preserving user settings across app updates.

## Available Configuration Options in AppPreferences.swift

The file exposes 21 distinct configuration options organized by functional responsibility:

### Model and Engine Settings

Control which transcription backend and model files OpenSuperWhisper utilizes:

- **`selectedEngine`** (`String`, default: `"whisper"`): Specifies the active transcription engine. Currently, only Whisper is supported. Source: [`@UserDefault(key: "selectedEngine")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L38)
- **`selectedWhisperModelPath`** (`String?`, default: `nil`): Absolute filesystem path to the user-selected Whisper model binary. Source: [`@OptionalUserDefault(key: "selectedWhisperModelPath")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L56)
- **`selectedModelPath`** (computed property): Convenience accessor that returns `selectedWhisperModelPath` when the engine is set to Whisper, ensuring compatibility with legacy code paths. Source: [`var selectedModelPath`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L42)
- **`fluidAudioModelVersion`** (`String`, default: `"v3"`): Version identifier for the optional Fluid Audio enhancement model. Source: [`@UserDefault(key: "fluidAudioModelVersion")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L59)

### Language and Output Behavior

Configure language detection, translation, and text formatting:

- **`whisperLanguage`** (`String`, default: `"en"`): ISO language code (e.g., "en", "ja", "de") used for transcription. Source: [`@UserDefault(key: "whisperLanguage")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L62)
- **`translateToEnglish`** (`Bool`, default: `false`): Automatically translates non-English speech into English text. Source: [`@UserDefault(key: "translateToEnglish")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L66)
- **`showTimestamps`** (`Bool`, default: `false`): Prepends timestamps to each transcribed segment in the output. Source: [`@UserDefault(key: "showTimestamps")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L72)
- **`suppressBlankAudio`** (`Bool`, default: `true`): Filters out segments containing only silence or background noise. Source: [`@UserDefault(key: "suppressBlankAudio")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L69)
- **`initialPrompt`** (`String`, default: `""`): Contextual text provided to the model before transcription to improve accuracy for specific vocabularies. Source: [`@UserDefault(key: "initialPrompt")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L81)
- **`addSpaceAfterSentence`** (`Bool`, default: `true`): Appends a trailing space after each completed sentence for continuous typing workflows. Source: [`@UserDefault(key: "addSpaceAfterSentence")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L114)

### Decoding Parameters

Advanced settings controlling the Whisper inference process:

- **`temperature`** (`Double`, default: `0.0`): Sampling temperature controlling randomness in decoding; higher values (e.g., 0.7) increase variability. Source: [`@UserDefault(key: "temperature")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L75)
- **`noSpeechThreshold`** (`Double`, default: `0.6`): Probability threshold for classifying audio chunks as non-speech. Source: [`@UserDefault(key: "noSpeechThreshold")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L78)
- **`useBeamSearch`** (`Bool`, default: `false`): Switches from greedy decoding to beam search for potentially higher accuracy at the cost of speed. Source: [`@UserDefault(key: "useBeamSearch")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L84)
- **`beamSize`** (`Int`, default: `5`): Number of candidate sequences to maintain when beam search is enabled. Source: [`@UserDefault(key: "beamSize")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L87)

### Automation and Clipboard

System integration options for workflow automation:

- **`autoCopyToClipboard`** (`Bool`, default: `true`): Automatically copies final transcription results to the system clipboard. Source: [`@UserDefault(key: "autoCopyToClipboard")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L118)
- **`autoPasteTranscription`** (`Bool`, default: `true`): Simulates keystrokes to paste transcription into the frontmost application after processing. Source: [`@UserDefault(key: "autoPasteTranscription")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L121)
- **`playSoundOnRecordStart`** (`Bool`, default: `false`): Plays a short audio cue when recording begins. Source: [`@UserDefault(key: "playSoundOnRecordStart")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L93)

### Hotkey and Input Configuration

Hardware interaction and accessibility settings:

- **`holdToRecord`** (`Bool`, default: `true`): When enabled, recording continues only while the activation hotkey is held down; releasing stops transcription. Source: [`@UserDefault(key: "holdToRecord")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L111)
- **`modifierOnlyHotkey`** (`String`, default: `"none"`): Configures activation using modifier keys (⌘, ⌥, ⇧) without requiring an additional character key. Source: [`@UserDefault(key: "modifierOnlyHotkey")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L105)
- **`mouseButtonHotkey`** (`String`, default: `"none"`): Binds transcription triggers to specific mouse button events. Source: [`@UserDefault(key: "mouseButtonHotkey")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L108)
- **`selectedMicrophoneData`** (`Data?`, default: `nil`): Serialized `AVAudioSession` or `AVCaptureDevice` configuration data representing the selected audio input. Source: [`@OptionalUserDefault(key: "selectedMicrophoneData")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L102)

### Application State

- **`hasCompletedOnboarding`** (`Bool`, default: `false`): Tracks whether the user has dismissed the initial setup/tutorial screens. Source: [`@UserDefault(key: "hasCompletedOnboarding")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L96)
- **`debugMode`** (`Bool`, default: `false`): Enables verbose console logging for troubleshooting transcription issues. Source: [`@UserDefault(key: "debugMode")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L90)
- **`useAsianAutocorrect`** (`Bool`, default: `true`): Activates specialized post-processing logic optimized for Chinese, Japanese, and Korean language transcription. Source: [`@UserDefault(key: "useAsianAutocorrect")`](https://github.com/Starmel/OpenSuperWhisper/blob/master/OpenSuperWhisper/Utils/AppPreferences.swift#L99)

## Accessing Configuration Options Programmatically

All UI components and services interact with `AppPreferences.shared` rather than `UserDefaults` directly. This abstraction provides compile-time type safety and instant persistence.

Reading values:

```swift
import OpenSuperWhisper

// Access the current transcription engine
let engine = AppPreferences.shared.selectedEngine

// Safely unwrap optional model path
if let modelPath = AppPreferences.shared.selectedWhisperModelPath {
    print("Loading model from: \(modelPath)")
}

// Check automation settings
let shouldAutoPaste = AppPreferences.shared.autoPasteTranscription

```

Modifying configuration options:

```swift
// Change transcription language to Japanese
AppPreferences.shared.whisperLanguage = "ja"

// Enable beam search for better accuracy
AppPreferences.shared.useBeamSearch = true
AppPreferences.shared.beamSize = 10

// Disable automatic pasting
AppPreferences.shared.autoPasteTranscription = false

```

The property wrappers persist changes immediately to `UserDefaults`, and the UI layer in [`Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/Settings.swift) reflects these updates without requiring manual synchronization.

## Summary

- **OpenSuperWhisper** centralizes user configuration in [`OpenSuperWhisper/Utils/AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/OpenSuperWhisper/Utils/AppPreferences.swift) via the `AppPreferences` singleton.
- **21 configuration options** cover model selection (`selectedWhisperModelPath`), transcription behavior (`whisperLanguage`, `translateToEnglish`), decoding parameters (`temperature`, `beamSize`), and workflow automation (`autoCopyToClipboard`, `autoPasteTranscription`).
- **Type-safe persistence** is achieved through custom `@UserDefault` and `@OptionalUserDefault` wrappers that eliminate boilerplate nil-checking.
- **Migration logic** in `migrateOldPreferences()` (lines 30-35) ensures backward compatibility by automatically upgrading legacy preference keys.
- **Separation of concerns** is maintained by having [`Settings.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/Settings.swift) serve as the exclusive UI layer for reading and writing these values.

## Frequently Asked Questions

### How do I reset all OpenSuperWhisper configuration options to their defaults?

OpenSuperWhisper does not expose a bulk reset API in [`AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AppPreferences.swift). To reset preferences programmatically, iterate through the specific keys listed above and remove them from `UserDefaults.standard`, or manually set each property on `AppPreferences.shared` back to its documented default value. For a complete reset, users can delete the app's preferences plist from `~/Library/Preferences/` or use the terminal command `defaults delete com.starmel.OpenSuperWhisper`.

### What is the difference between @UserDefault and @OptionalUserDefault in AppPreferences.swift?

The `@UserDefault` wrapper enforces non-optional types with mandatory default values, ensuring that properties like `temperature` always return a concrete `Double` (0.0) even when the key is absent from storage. The `@OptionalUserDefault` wrapper handles optional types such as `String?` or `Data?`, returning `nil` when no value exists, which is necessary for properties like `selectedWhisperModelPath` that have no meaningful default.

### Where does OpenSuperWhisper actually store these configuration values?

While [`AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AppPreferences.swift) provides the Swift interface, values persist to the standard macOS `UserDefaults` system (typically `~/Library/Preferences/com.starmel.OpenSuperWhisper.plist`). The property wrappers in [`AppPreferences.swift`](https://github.com/Starmel/OpenSuperWhisper/blob/main/AppPreferences.swift) abstract this implementation detail, so application code should always access values through `AppPreferences.shared` rather than `UserDefaults.standard` to ensure type safety and migration logic execution.

### Why does AppPreferences.swift contain both selectedModelPath and selectedWhisperModelPath?

`selectedWhisperModelPath` is the current canonical key for storing the model file path, introduced in a newer version of the app. `selectedModelPath` exists as a computed property that provides backward compatibility for legacy code paths. The `migrateOldPreferences()` function automatically copies values from the old `selectedModelPath` key to `selectedWhisperModelPath` when the app launches, ensuring existing users retain their model selection after updating.