OpenSuperWhisper Configuration Options in AppPreferences.swift: Complete Reference Guide

OpenSuperWhisper stores all user-tunable settings in 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. 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")
• selectedWhisperModelPath (String?, default: nil): Absolute filesystem path to the user-selected Whisper model binary. Source: @OptionalUserDefault(key: "selectedWhisperModelPath")
• selectedModelPath (computed property): Convenience accessor that returns selectedWhisperModelPath when the engine is set to Whisper, ensuring compatibility with legacy code paths. Source: var selectedModelPath
• fluidAudioModelVersion (String, default: "v3"): Version identifier for the optional Fluid Audio enhancement model. Source: @UserDefault(key: "fluidAudioModelVersion")

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")
• translateToEnglish (Bool, default: false): Automatically translates non-English speech into English text. Source: @UserDefault(key: "translateToEnglish")
• showTimestamps (Bool, default: false): Prepends timestamps to each transcribed segment in the output. Source: @UserDefault(key: "showTimestamps")
• suppressBlankAudio (Bool, default: true): Filters out segments containing only silence or background noise. Source: @UserDefault(key: "suppressBlankAudio")
• initialPrompt (String, default: ""): Contextual text provided to the model before transcription to improve accuracy for specific vocabularies. Source: @UserDefault(key: "initialPrompt")
• addSpaceAfterSentence (Bool, default: true): Appends a trailing space after each completed sentence for continuous typing workflows. Source: @UserDefault(key: "addSpaceAfterSentence")

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")
• noSpeechThreshold (Double, default: 0.6): Probability threshold for classifying audio chunks as non-speech. Source: @UserDefault(key: "noSpeechThreshold")
• useBeamSearch (Bool, default: false): Switches from greedy decoding to beam search for potentially higher accuracy at the cost of speed. Source: @UserDefault(key: "useBeamSearch")
• beamSize (Int, default: 5): Number of candidate sequences to maintain when beam search is enabled. Source: @UserDefault(key: "beamSize")

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")
• autoPasteTranscription (Bool, default: true): Simulates keystrokes to paste transcription into the frontmost application after processing. Source: @UserDefault(key: "autoPasteTranscription")
• playSoundOnRecordStart (Bool, default: false): Plays a short audio cue when recording begins. Source: @UserDefault(key: "playSoundOnRecordStart")

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")
• modifierOnlyHotkey (String, default: "none"): Configures activation using modifier keys (⌘, ⌥, ⇧) without requiring an additional character key. Source: @UserDefault(key: "modifierOnlyHotkey")
• mouseButtonHotkey (String, default: "none"): Binds transcription triggers to specific mouse button events. Source: @UserDefault(key: "mouseButtonHotkey")
• selectedMicrophoneData (Data?, default: nil): Serialized AVAudioSession or AVCaptureDevice configuration data representing the selected audio input. Source: @OptionalUserDefault(key: "selectedMicrophoneData")

Application State

• hasCompletedOnboarding (Bool, default: false): Tracks whether the user has dismissed the initial setup/tutorial screens. Source: @UserDefault(key: "hasCompletedOnboarding")
• debugMode (Bool, default: false): Enables verbose console logging for troubleshooting transcription issues. Source: @UserDefault(key: "debugMode")
• useAsianAutocorrect (Bool, default: true): Activates specialized post-processing logic optimized for Chinese, Japanese, and Korean language transcription. Source: @UserDefault(key: "useAsianAutocorrect")

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:

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:

// 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 reflects these updates without requiring manual synchronization.

Summary

• OpenSuperWhisper centralizes user configuration in 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 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. 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 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 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.

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