OpenSuperWhisper

https://github.com/starmel/opensuperwhisper
Admin
OpenSuperWhisper is a macOS application that provides real-time audio transcription using the...
Tokens:37,316
Snippets:578
Trust Score:8.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### startRecording() usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Example of how to start recording using the shared AudioRecorder instance.

```swift
AudioRecorder.shared.startRecording()
```

--------------------------------

### AudioDevice initialization examples

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/types.md

Examples of initializing AudioDevice for different types of hardware.

```swift
AudioDevice(id: "...", name: "MacBook Pro Microphone", manufacturer: "Apple", isBuiltIn: true)
```

```swift
AudioDevice(id: "...", name: "Logitech USB Headset", manufacturer: "Logitech", isBuiltIn: false)
```

```swift
AudioDevice(id: "...", name: "iPhone Microphone (Continuity)", manufacturer: "Apple", isBuiltIn: false)
```

--------------------------------

### convertAudioToPCM(fileURL:) usage example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

A single-threaded implementation example showing how to call the conversion method and handle potential errors.

```swift
do {
    if let samples = try await whisperEngine.convertAudioToPCM(fileURL: audioURL) {
        print("Converted \(samples.count) PCM samples")
    }
} catch {
    print("Conversion failed: \(error)")
}
```

--------------------------------

### addRecording(_:) Usage Example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Demonstrates how to instantiate a Recording object and add it to the store asynchronously.

```swift
let recording = Recording(
    id: UUID(),
    timestamp: Date(),
    fileName: "recording_1234567890.wav",
    transcription: "",
    duration: 10.5,
    status: .pending,
    progress: 0.0,
    sourceFileURL: nil
)
RecordingStore.shared.addRecording(recording)
```

--------------------------------

### WhisperEngine Initialization Example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

Demonstrates how to instantiate the WhisperEngine and initialize the model with error handling.

```swift
let engine = WhisperEngine()
do {
    try await engine.initialize()
    print("Whisper model loaded")
} catch {
    print("Failed to load model: \(error)")
}
```

--------------------------------

### getSupportedLanguages() usage example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

Example showing how to retrieve and print the list of supported languages from the whisperEngine instance.

```swift
let languages = whisperEngine.getSupportedLanguages()
print("Available languages: \(languages)")
```

--------------------------------

### Install OpenSuperWhisper via Homebrew

Source: https://github.com/starmel/opensuperwhisper/blob/master/Readme.md

Use Homebrew to install the application on macOS.

```shell
brew update # Optional
brew install opensuperwhisper
```

--------------------------------

### Using the UserDefault property wrapper

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Example implementation of a property using the UserDefault wrapper.

```swift
@UserDefault(key: "selectedEngine", defaultValue: "whisper")
var selectedEngine: String
```

--------------------------------

### Setup progress observer with setupProgressObserver()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-queue.md

Subscribes to transcription progress updates to provide real-time feedback without writing transient updates to the database.

```swift
private func setupProgressObserver()
```

--------------------------------

### Build OpenSuperWhisper locally

Source: https://github.com/starmel/opensuperwhisper/blob/master/Readme.md

Commands to clone the repository, initialize submodules, install dependencies, and build the project.

```shell
git clone git@github.com:Starmel/OpenSuperWhisper.git
cd OpenSuperWhisper
git submodule update --init --recursive
brew install cmake libomp rust ruby
gem install xcpretty
./run.sh build
```

--------------------------------

### playRecording(url:) usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Example of playing a recording file located at a specific path.

```swift
let fileURL = URL(fileURLWithPath: "/path/to/recording.wav")
AudioRecorder.shared.playRecording(url: fileURL)
```

--------------------------------

### Transcribing Audio Example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Demonstrates how to configure transcription settings and call the transcribeAudio method within a do-catch block.

```swift
let settings = Settings(
    selectedLanguage: "en",
    showTimestamps: false,
    suppressBlankAudio: true,
    temperature: 0.0,
    noSpeechThreshold: 0.6,
    initialPrompt: "",
    useBeamSearch: false,
    beamSize: 5,
    shouldApplyAsianAutocorrect: false
)

do {
    let audioURL = URL(fileURLWithPath: "/path/to/recording.wav")
    let text = try await TranscriptionService.shared.transcribeAudio(url: audioURL, settings: settings)
    print("Transcribed: \(text)")
} catch TranscriptionError.contextInitializationFailed {
    print("Engine context failed to load")
} catch TranscriptionError.audioConversionFailed {
    print("Audio conversion failed")
} catch {
    print("Transcription failed: \(error)")
}
```

--------------------------------

### fetchRecordings(limit:offset:) usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Example showing how to fetch sequential pages of recordings using the shared RecordingStore instance.

```swift
let page1 = try await RecordingStore.shared.fetchRecordings(limit: 20, offset: 0)
let page2 = try await RecordingStore.shared.fetchRecordings(limit: 20, offset: 20)
```

--------------------------------

### Using the OptionalUserDefault property wrapper

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Example implementation of an optional property using the OptionalUserDefault wrapper.

```swift
@OptionalUserDefault(key: "selectedWhisperModelPath")
var selectedWhisperModelPath: String?
```

--------------------------------

### stopPlaying() usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Example of stopping the current playback session.

```swift
AudioRecorder.shared.stopPlaying()
```

--------------------------------

### addRecordingSync(_:) Usage Example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Demonstrates how to call the synchronous add method within a do-catch block to handle potential database errors.

```swift
do {
    try await RecordingStore.shared.addRecordingSync(recording)
    print("Recording added")
} catch {
    print("Failed to add recording: \(error)")
}
```

--------------------------------

### stopRecording() usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Example of stopping a recording and handling the returned file URL or failure case.

```swift
if let recordingURL = await AudioRecorder.shared.stopRecording() {
    print("Recording saved: \(recordingURL)")
} else {
    print("Recording too short, discarded")
}
```

--------------------------------

### Starting the transcription queue

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-queue.md

Initiates the processing of pending recordings. This is typically called by the AppDelegate on app launch.

```swift
func startProcessingQueue()
```

```swift
// Called automatically by AppDelegate on app launch
TranscriptionQueue.shared.startProcessingQueue()
```

--------------------------------

### selectMicrophone(_:) usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Sets the user's preferred microphone. This example demonstrates selecting the first available non-built-in microphone.

```swift
let microphoneService = MicrophoneService.shared
if let externalMic = microphoneService.availableMicrophones.first(where: { !$0.isBuiltIn }) {
    microphoneService.selectMicrophone(externalMic)
}
```

--------------------------------

### startProcessingQueue()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-queue.md

Initiates the background processing of pending recordings in the queue. This method is idempotent and will not start if the queue is already active.

```APIDOC
## func startProcessingQueue()

### Description
Starts processing pending recordings in the queue. If the queue is already processing, this method performs no action.

### Usage
```swift
TranscriptionQueue.shared.startProcessingQueue()
```
```

--------------------------------

### cancelRecording() usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Example of cancelling the current recording session.

```swift
AudioRecorder.shared.cancelRecording()
```

--------------------------------

### Observe preference changes

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Listen for preference changes using NotificationCenter. The example shows how to observe the .appPreferencesLanguageChanged notification.

```swift
NotificationCenter.default.addObserver(
    self,
    selector: #selector(languageChanged),
    name: .appPreferencesLanguageChanged,
    object: nil
)
```

--------------------------------

### Configure and Build Whisper Static Library

Source: https://github.com/starmel/opensuperwhisper/blob/master/docs/build_whisper.md

This command configures the build environment for a static library release, disabling shared libraries, setting C++ standard to 11, applying visibility flags, and excluding examples and tests. It then proceeds to build the library using parallel jobs.

```bash
cd ../.. && rm -rf build && mkdir build && cd build && cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DCMAKE_CXX_STANDARD=11 -DCMAKE_CXX_FLAGS="-fvisibility=hidden" -DWHISPER_BUILD_EXAMPLES=OFF -DWHISPER_BUILD_TESTS=OFF ..

make -j$(sysctl -n hw.ncpu)
```

--------------------------------

### updateRecordingProgressTransient(_:progress:status:) Usage Example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Demonstrates updating progress during transcription without triggering a database write.

```swift
// Called by TranscriptionQueue during transcription
RecordingStore.shared.updateRecordingProgressTransient(
    recordingId,
    progress: 0.5,
    status: .transcribing
)
```

--------------------------------

### cancelTranscription() usage example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Demonstrates calling the cancelTranscription method on the shared TranscriptionService instance.

```swift
// User clicks cancel button
TranscriptionService.shared.cancelTranscription()
```

--------------------------------

### reloadModel(with:) Function Signature and Example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Reloads the Whisper engine with a new model file specified by the absolute path.

```swift
func reloadModel(with path: String)
```

```swift
let modelPath = "/Applications/OpenSuperWhisper/models/ggml-base.en.bin"
TranscriptionService.shared.reloadModel(with: modelPath)
```

--------------------------------

### reloadEngine() Function Signature and Example

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Reloads the current transcription engine, typically used when preferences or model files change.

```swift
func reloadEngine()
```

```swift
// User changed engine in settings
TranscriptionService.shared.reloadEngine()
```

--------------------------------

### cleanupMissingFiles() method definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-queue.md

Defines the asynchronous method used to remove pending recordings whose source files no longer exist on disk. This is called automatically when the processing queue starts.

```swift
private func cleanupMissingFiles() async
```

--------------------------------

### startRecording() method signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

The method signature for initiating audio recording.

```swift
func startRecording()
```

--------------------------------

### Configure initialPrompt

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Provides a context prompt to prime the model with domain-specific vocabulary for the first 30-second window.

```swift
@UserDefault(key: "initialPrompt", defaultValue: "")
var initialPrompt: String
```

--------------------------------

### startRecording()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Begins recording audio from the active microphone. This method is non-blocking and runs on an internal work queue.

```APIDOC
## startRecording()

### Description
Begins recording audio from the active microphone. It handles system input device switching and monitors connection stability.

### Signature
`func startRecording()`

### Example
```swift
AudioRecorder.shared.startRecording()
```
```

--------------------------------

### WhisperEngine initialize Method

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

Asynchronously loads the Whisper model from disk. Throws a TranscriptionError if the model file is missing or fails to load.

```swift
func initialize() async throws
```

--------------------------------

### initialPrompt

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Sets a context prompt to prime the model with domain-specific vocabulary.

```APIDOC
## initialPrompt

### Description
Context prompt to prime the model with domain-specific vocabulary for the first 30-second window.

### Type
String

### Default
""
```

--------------------------------

### WhisperVadSegment Struct

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/types.md

Represents a detected speech segment using start and end times in centiseconds.

```swift
struct WhisperVadSegment {
    var startCs: Int32  // Start time in centiseconds
    var endCs: Int32    // End time in centiseconds
}
```

--------------------------------

### Initialize recording trigger

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

The setupRecordingTrigger function is called on initialization to configure the recording trigger based on priority settings.

```swift
private func setupRecordingTrigger()
```

--------------------------------

### loadEngine() Function Signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Initializes the transcription engine based on app preferences.

```swift
private func loadEngine()
```

--------------------------------

### Accessing the AudioRecorder shared instance

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Use the shared singleton instance to interact with the audio recording service.

```swift
static let shared: AudioRecorder
```

--------------------------------

### Root Level Documentation Files List

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/COMPLETION-REPORT.md

A list of the core documentation files located at the project root, including their file sizes and descriptions.

```text
00-START-HERE.txt         9.3 KB  Quick navigation guide
INDEX.md                  12 KB   Complete index and cross-reference
README.md                 12 KB   Project overview and architecture
configuration.md          9.1 KB  Configuration options and schema
types.md                  9.7 KB  Type definitions and structures
```

--------------------------------

### Application Support Directory Structure

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/configuration.md

The directory stores audio recordings and the SQLite database file.

```text
~/Library/Application Support/com.opensuperwhisper/
├── recordings/                      # Audio files
│   ├── 1234567890.wav
│   ├── 1234567891.wav
│   └── ...
├── recordings.sqlite                # GRDB database
└── recordings.sqlite-shm            # SQLite shared memory file (temp)
```

--------------------------------

### addRecording(_:) Method Signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Asynchronously adds a new recording to the database.

```swift
func addRecording(_ recording: Recording)
```

--------------------------------

### Settings object initialization

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-queue.md

Initializes the Settings object using values from AppPreferences to configure the transcription process.

```swift
let settings = Settings(
    selectedLanguage: AppPreferences.shared.whisperLanguage,
    showTimestamps: AppPreferences.shared.showTimestamps,
    suppressBlankAudio: AppPreferences.shared.suppressBlankAudio,
    temperature: AppPreferences.shared.temperature,
    noSpeechThreshold: AppPreferences.shared.noSpeechThreshold,
    initialPrompt: AppPreferences.shared.initialPrompt,
    useBeamSearch: AppPreferences.shared.useBeamSearch,
    beamSize: AppPreferences.shared.beamSize,
    shouldApplyAsianAutocorrect: AppPreferences.shared.useAsianAutocorrect
)
```

--------------------------------

### Project File Structure

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/COMPLETION-REPORT.md

The directory structure of the generated documentation located in /workspace/home/output/.

```text
/workspace/home/output/
├── 00-START-HERE.txt                   (Quick navigation)
├── INDEX.md                             (Complete index)
├── README.md                            (Overview)
├── configuration.md                     (Config reference)
├── types.md                             (Type definitions)
└── api-reference/
    ├── app-preferences.md
    ├── audio-recorder.md
    ├── input-management.md
    ├── microphone-service.md
    ├── recording-store.md
    ├── transcription-engines.md
    ├── transcription-queue.md
    └── transcription-service.md
```

--------------------------------

### Search Recordings

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/README.md

Demonstrates both synchronous and asynchronous methods for searching the recording store.

```swift
let results = RecordingStore.shared.searchRecordings(query: "hello")
// or async:
let results = await RecordingStore.shared.searchRecordingsAsync(query: "hello", limit: 50, offset: 0)
```

--------------------------------

### Internal migrateOldPreferences method

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Internal method called on initialization to migrate legacy preference keys to new ones. It only executes if the new key does not already exist.

```swift
private func migrateOldPreferences()
```

--------------------------------

### selectMicrophone(_:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Sets the user's preferred microphone and persists the selection.

```APIDOC
## selectMicrophone(_:)

### Description
Sets the user's preferred microphone. This method updates the internal selection, persists it to UserDefaults, and posts a .microphoneDidChange notification.

### Signature
`func selectMicrophone(_ device: AudioDevice)`

### Parameters
- **device** (AudioDevice) - Required - The microphone to select.
```

--------------------------------

### addRecording(_:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Asynchronously adds a new recording to the database and notifies observers upon completion.

```APIDOC
## func addRecording(_ recording: Recording)

### Description
Asynchronously adds a new recording to the database. This method handles errors silently by printing to the console and posts a `recordingsDidUpdateNotification` when the operation is complete.

### Parameters
- **recording** (Recording) - Required - The recording object to insert into the database.
```

--------------------------------

### Access temporaryRecordingsDirectory

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Returns the system temporary directory path for temporary recordings.

```swift
static var temporaryRecordingsDirectory: URL
```

--------------------------------

### playRecording(url:) method signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

The method signature for playing an audio file from a specific URL.

```swift
func playRecording(url: URL)
```

--------------------------------

### isLoading property

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Indicates if the transcription engine is currently initializing or loading.

```swift
@Published private(set) var isLoading: Bool
```

--------------------------------

### addRecordingSync(_:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Synchronously adds a recording to the database, waiting for completion and throwing errors if the write fails.

```APIDOC
## func addRecordingSync(_ recording: Recording) async throws

### Description
Synchronously adds a recording and waits for the operation to finish. This method throws database write errors if the insertion fails.

### Parameters
- **recording** (Recording) - Required - The recording object to insert.
```

--------------------------------

### fetchRecordings(limit:offset:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Fetches a paginated list of recordings, ordered by most recent first.

```APIDOC
## fetchRecordings(limit:offset:)

### Description
Fetches paginated recordings ordered by most recent first.

### Signature
`nonisolated func fetchRecordings(limit: Int, offset: Int) async throws -> [Recording]`

### Parameters
- **limit** (Int) - Maximum number of recordings to return
- **offset** (Int) - Number of recordings to skip

### Returns
- `[Recording]` ordered by timestamp descending
```

--------------------------------

### WhisperEngine

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

Implementation of the TranscriptionEngine using Whisper.cpp.

```APIDOC
## WhisperEngine

### Description
Whisper.cpp-based transcription engine with voice activity detection (VAD) and advanced audio processing.

### Properties
- **onProgressUpdate** ((Float) -> Void)? - Callback closure invoked during transcription progress (0.0 to 1.0)

### Methods
- **initialize()** - Loads the Whisper model from disk. Throws TranscriptionError.contextInitializationFailed if model load fails.

### Example
```swift
let engine = WhisperEngine()
do {
    try await engine.initialize()
    print("Whisper model loaded")
} catch {
    print("Failed to load model: \(error)")
}
```
```

--------------------------------

### Recording Computed Property: url

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Returns the full path to the recording file on disk.

```swift
var url: URL
```

--------------------------------

### addRecordingSync(_:) Method Signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Synchronously adds a recording and waits for completion, throwing an error if the database write fails.

```swift
func addRecordingSync(_ recording: Recording) async throws
```

--------------------------------

### handleKeyUp() Method

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

Called when the hotkey is released to cancel pending hold work and manage recording state.

```swift
private func handleKeyUp()
```

--------------------------------

### recordingsDiskUsage()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Calculates the total disk space used by all recording files in bytes.

```swift
nonisolated static func recordingsDiskUsage() -> Int64
```

```swift
let totalBytes = RecordingStore.recordingsDiskUsage()
let totalMB = Double(totalBytes) / (1024 * 1024)
print("Recordings using \(totalMB) MB")
```

--------------------------------

### API Reference Documentation Structure

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/COMPLETION-REPORT.md

A directory tree listing the API reference files and their respective focus areas.

```text
api-reference/
  ├─ app-preferences.md             9.8 KB  (40+ preference keys)
  ├─ audio-recorder.md              7.4 KB  (10+ recording methods)
  ├─ input-management.md            6.5 KB  (hotkeys and mouse buttons)
  ├─ microphone-service.md          7.9 KB  (device discovery and selection)
  ├─ recording-store.md             15 KB   (20+ database operations)
  ├─ transcription-engines.md       12 KB   (engine implementations)
  ├─ transcription-queue.md         6.8 KB  (queue processing)
  └─ transcription-service.md       7.1 KB  (transcription orchestration)
```

--------------------------------

### hasCompletedOnboarding Preference

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Tracks onboarding completion status. If false, the app displays the OnboardingView; otherwise, it shows the ContentView.

```swift
@UserDefault(key: "hasCompletedOnboarding", defaultValue: false)
var hasCompletedOnboarding: Bool
```

--------------------------------

### setSystemDefaultInputDevice(_:) configuration

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Changes the system default input device to the specified AudioDeviceID, returning a boolean indicating success.

```swift
func setSystemDefaultInputDevice(_ deviceID: AudioDeviceID) -> Bool
```

--------------------------------

### isBuiltInDevice(_:) implementation

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Determines if a device is built-in or Apple-manufactured, including logic for Continuity microphone detection.

```swift
private func isBuiltInDevice(_ device: AVCaptureDevice) -> Bool
```

--------------------------------

### AppPreferences Access Pattern

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

The AppPreferences singleton provides direct access to application settings. Changes are immediately persisted to disk.

```APIDOC
## AppPreferences Access

### Description
Access the shared singleton to read or update application preferences.

### Usage
```swift
// Read
let engine = AppPreferences.shared.selectedEngine
let language = AppPreferences.shared.whisperLanguage

// Write
AppPreferences.shared.selectedEngine = "fluidaudio"
AppPreferences.shared.whisperLanguage = "fr"
```
```

--------------------------------

### AppState Definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/types.md

Root application state tracking onboarding status, used by OpenSuperWhisperApp and AppPreferences.

```swift
class AppState: ObservableObject {
    @Published var hasCompletedOnboarding: Bool
}
```

--------------------------------

### Configure useBeamSearch

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Enables beam search decoding instead of greedy decoding for higher accuracy at the cost of speed.

```swift
@UserDefault(key: "useBeamSearch", defaultValue: false)
var useBeamSearch: Bool
```

--------------------------------

### useBeamSearch

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Toggles between beam search and greedy decoding.

```APIDOC
## useBeamSearch

### Description
Use beam search instead of greedy decoding. True provides higher accuracy but is slower.

### Type
Bool

### Default
false
```

--------------------------------

### getCurrentSystemDefaultInputDevice() query

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Queries the current system default input device and returns its AudioDeviceID.

```swift
func getCurrentSystemDefaultInputDevice() -> AudioDeviceID?
```

--------------------------------

### Recording Static Property: recordingsDirectory

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

The directory path where all recording files are stored.

```swift
static var recordingsDirectory: URL
```

--------------------------------

### playSoundOnRecordStart Preference

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Controls whether a notification sound plays when recording begins. Uses notification.mp3 from the app bundle.

```swift
@UserDefault(key: "playSoundOnRecordStart", defaultValue: false)
var playSoundOnRecordStart: Bool
```

--------------------------------

### setSystemDefaultInputDevice(_:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Changes the system default input device to the specified Core Audio device ID.

```APIDOC
## setSystemDefaultInputDevice(_:)

### Description
Changes the system default input device.

### Parameters
- **deviceID** (AudioDeviceID) - Required - Core Audio device ID to set as default

### Returns
- **Bool** - true if successfully set, false if operation failed.
```

--------------------------------

### handleKeyDown() Method

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

Called when the hotkey is pressed down to schedule hold detection and initiate recording.

```swift
private func handleKeyDown()
```

--------------------------------

### recordingsDiskUsage()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Calculates total disk space used by all recording files.

```APIDOC
## recordingsDiskUsage()

### Description
Calculates total disk space used by all recording files.

### Returns
- **Int64** - Total size in bytes
```

--------------------------------

### startHiddenInMenuBar Preference

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Determines if the app launches minimized to the menu bar rather than displaying the main window.

```swift
@UserDefault(key: "startHiddenInMenuBar", defaultValue: false)
var startHiddenInMenuBar: Bool
```

--------------------------------

### KeyboardShortcuts.Name toggleRecord Configuration

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

Defines the toggleRecord hotkey with a default of Option + Backtick.

```swift
extension KeyboardShortcuts.Name {
    static let toggleRecord = Self("toggleRecord", default: .init(.backtick, modifiers: .option))
}
```

--------------------------------

### Dispatch Input Handling to Main Thread

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

All input handling must be dispatched to the main thread to ensure recording state and UI updates are processed correctly.

```swift
Task { @MainActor in
    // Handle recording start/stop
}
```

--------------------------------

### Data Flow Pipeline

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/INDEX.md

The sequence of operations from initial user input to the final UI update.

```text
Input (hotkey/mouse) 
  → AudioRecorder (record to temp WAV)
  → Recording created in RecordingStore
  → TranscriptionQueue (process when idle)
  → TranscriptionService (load engine)
  → WhisperEngine/FluidAudioEngine (process)
  → Store transcription in Recording
  → UI updates via @Published properties
```

--------------------------------

### playRecording(url:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Plays the audio file located at the specified URL.

```APIDOC
## playRecording(url:)

### Description
Plays the audio file at the given URL. Stops any currently playing audio before starting.

### Signature
`func playRecording(url: URL)`

### Parameters
- **url** (URL) - Required - Path to the audio file to play

### Example
```swift
let fileURL = URL(fileURLWithPath: "/path/to/recording.wav")
AudioRecorder.shared.playRecording(url: fileURL)
```
```

--------------------------------

### Configure temperature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Controls decoding randomness from 0.0 (deterministic) to 1.0+ (more random).

```swift
@UserDefault(key: "temperature", defaultValue: 0.0)
var temperature: Double
```

--------------------------------

### temporaryRecordingsDirectory

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Retrieves the system temporary directory path used for storing temporary recordings.

```APIDOC
## static var temporaryRecordingsDirectory

### Description
Returns the system temporary directory path for temporary recordings.

### Signature
`static var temporaryRecordingsDirectory: URL`

### Location
`FileManager.default.temporaryDirectory/temp_recordings/`
```

--------------------------------

### Configuring temporaryFileMaxAge

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Sets the maximum age for temporary files in seconds before they are automatically cleaned up, defaulting to 24 hours.

```swift
static let temporaryFileMaxAge: TimeInterval = 24 * 60 * 60
```

--------------------------------

### moveTemporaryRecording(from:to:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Moves a temporary recording file to a specified permanent location, handling directory creation and existing file replacement.

```APIDOC
## func moveTemporaryRecording(from:to:)

### Description
Moves a temporary recording file to a permanent location. This method creates parent directories if needed and removes any existing file at the destination.

### Signature
`func moveTemporaryRecording(from tempURL: URL, to finalURL: URL) throws`

### Parameters
- **tempURL** (URL) - Required - Source temporary file URL
- **finalURL** (URL) - Required - Destination file URL

### Throws
- `Error` if file operations fail (move, create directory, remove existing file)
```

--------------------------------

### refreshAvailableMicrophones()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Manually triggers a rescan of the system for connected microphones.

```APIDOC
## refreshAvailableMicrophones()

### Description
Rescans the system for connected microphones and updates the available devices list. This is typically called automatically on device connection changes.

### Signature
`func refreshAvailableMicrophones()`
```

--------------------------------

### Configure suppressBlankAudio

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Determines whether to skip blank audio segments to improve speed and reduce hallucinations.

```swift
@UserDefault(key: "suppressBlankAudio", defaultValue: true)
var suppressBlankAudio: Bool
```

--------------------------------

### Select External Microphone

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/README.md

Identifies and selects the first available non-built-in microphone from the MicrophoneService.

```swift
let micService = MicrophoneService.shared
if let externalMic = micService.availableMicrophones.first(where: { !$0.isBuiltIn }) {
    micService.selectMicrophone(externalMic)
}
```

--------------------------------

### conversionProgress property

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Represents the progress of the audio conversion phase as a float between 0.0 and 1.0.

```swift
@Published private(set) var conversionProgress: Float
```

--------------------------------

### Accessing the AppPreferences singleton

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Use the shared static instance to access application preferences.

```swift
static let shared: AppPreferences
```

--------------------------------

### Configuring minimumRecordingDuration

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Defines the minimum duration in seconds required for a recording to be saved, defaulting to 1.0 second.

```swift
static let minimumRecordingDuration: TimeInterval = 1.0
```

--------------------------------

### updateRecording(_:) Method Signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Asynchronously updates an existing recording in the database based on its ID.

```swift
func updateRecording(_ recording: Recording)
```

--------------------------------

### convertAudioToPCM(fileURL:) definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

The signature for the asynchronous method that converts audio files to 16 kHz mono PCM format.

```swift
nonisolated func convertAudioToPCM(fileURL: URL) async throws -> [Float]?
```

--------------------------------

### Notarize App Script

Source: https://github.com/starmel/opensuperwhisper/blob/master/docs/release_build.md

Execute the notarization script with the code sign identity. Ensure the identity is correctly formatted.

```shell
./notarize_app.sh $CODE_SIGN_IDENTITY
```

```shell
./notarize_app.sh "Developer ID Application: AAAA BBBB (XXXXX)"
```

--------------------------------

### transcribeAudio(url:settings:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Transcribes audio from a file URL using the loaded engine. This method is asynchronous and returns the transcribed text as a String.

```APIDOC
## transcribeAudio(url:settings:)

### Description
Transcribes audio from a file URL using the loaded engine. This method serializes transcriptions and runs on a detached task with user-initiated priority.

### Signature
`func transcribeAudio(url: URL, settings: Settings) async throws -> String`

### Parameters
- **url** (URL) - Required - Path to audio file to transcribe
- **settings** (Settings) - Required - Transcription options (language, model, timestamps, etc.)

### Returns
- `String` containing the transcribed text

### Throws
- `TranscriptionError.contextInitializationFailed`
- `TranscriptionError.audioConversionFailed`
- `TranscriptionError.processingFailed`
- `CancellationError`
```

--------------------------------

### ShortcutManager Singleton Definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

The central singleton class responsible for managing all input methods for recording.

```swift
class ShortcutManager {
    static let shared: ShortcutManager
}
```

--------------------------------

### Model Files Directory Structure

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/configuration.md

Contains the Whisper and VAD model files used by the application.

```text
~/Library/Application Support/com.opensuperwhisper/models/
├── ggml-base.en.bin                 # Whisper base English model
├── ggml-small.bin                   # Whisper small multilingual
├── ggml-large-v3-turbo.bin          # Whisper large v3 turbo
└── ggml-silero-v5.1.2.bin           # VAD model (bundled in app)
```

--------------------------------

### getPendingRecordings()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Returns recordings that are currently in a pending, converting, or transcribing state.

```APIDOC
## getPendingRecordings()

### Description
Returns recordings that are still being processed. This is a synchronous blocking call.

### Signature
`func getPendingRecordings() -> [Recording]`

### Returns
- `[Recording]` with status `.pending`, `.converting`, or `.transcribing`, ordered by oldest timestamp first
```

--------------------------------

### MicrophoneService.selectMicrophone

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/README.md

Selects a specific microphone device for recording.

```APIDOC
## MicrophoneService.selectMicrophone

### Description
Sets the active microphone for the application.

### Signature
`MicrophoneService.shared.selectMicrophone(microphone)`

### Parameters
- **microphone** (Object) - Required - The microphone object selected from `availableMicrophones`.
```

--------------------------------

### Define Project Name

Source: https://github.com/starmel/opensuperwhisper/blob/master/libwhisper/CMakeLists.txt

Declares the project name as 'libwhisper'.

```cmake
project(libwhisper)
```

--------------------------------

### Internal queue processing with processQueue()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-queue.md

The main asynchronous loop that processes pending recordings sequentially from the database.

```swift
private func processQueue() async
```

--------------------------------

### loadSavedMicrophone() method

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Restores the previously saved microphone selection from UserDefaults. This is called on initialization to decode the saved AudioDevice and set the selected microphone.

```swift
private func loadSavedMicrophone()
```

--------------------------------

### debugMode Preference

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Enables verbose logging to the console for troubleshooting and internal diagnostics.

```swift
@UserDefault(key: "debugMode", defaultValue: false)
var debugMode: Bool
```

--------------------------------

### isConverting property

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Indicates if the service is currently in the audio format conversion phase.

```swift
@Published private(set) var isConverting: Bool
```

--------------------------------

### Recording Data Model Structure

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/README.md

Defines the schema for the Recording model, which is persisted in SQLite and observable through RecordingStore.

```text
Recording {
    id: UUID
    timestamp: Date
    fileName: String
    transcription: String (mutable)
    duration: TimeInterval
    status: RecordingStatus (mutable)
    progress: Float (mutable)
    sourceFileURL: String? (optional, for imports)
    isRegeneration: Bool (for retries)
}
```

--------------------------------

### recordingsOlderThan(days:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Counts and finds the oldest completed recording older than the specified threshold in days.

```swift
nonisolated func recordingsOlderThan(days: Int) async throws -> (count: Int, oldestDate: Date?)
```

--------------------------------

### mouseButtonHotkey Preference

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Defines a mouse button, such as middle or thumb buttons, to trigger recording.

```swift
@UserDefault(key: "mouseButtonHotkey", defaultValue: "")
var mouseButtonHotkey: String
```

--------------------------------

### updateRecordingSync(_:) Method Signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Synchronously updates a recording, throwing an error if the database write fails.

```swift
func updateRecordingSync(_ recording: Recording) async throws
```

--------------------------------

### getInputChannelCount(for:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Returns the number of input channels for a given device.

```APIDOC
## getInputChannelCount(for:)

### Description
Returns the number of input channels for a device.

### Parameters
- **device** (AudioDevice) - Required - The device to query

### Returns
- **Int** - Number of input channels (defaults to 1 if unavailable).
```

--------------------------------

### RecordingStore Class Definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

The main actor-isolated database manager for recordings, located in OpenSuperWhisper/Models/Recording.swift.

```swift
@MainActor
class RecordingStore: ObservableObject {
    static let shared: RecordingStore
}
```

--------------------------------

### updateCurrentMicrophone() method

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Reconciles the current microphone with device availability. It sets the current microphone to the selected one if available, otherwise falls back to the system default and updates the published property.

```swift
private func updateCurrentMicrophone()
```

--------------------------------

### updateRecording(_:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Asynchronously updates an existing recording's fields in the database.

```APIDOC
## func updateRecording(_ recording: Recording)

### Description
Updates all mutable fields of an existing recording, such as transcription, status, and progress. The update is performed based on the recording's `id` field.

### Parameters
- **recording** (Recording) - Required - The recording object containing updated fields.
```

--------------------------------

### Configure Shared Libraries Option

Source: https://github.com/starmel/opensuperwhisper/blob/master/libwhisper/CMakeLists.txt

Sets an option to control whether shared libraries are built. Defaults to OFF.

```cmake
option(BUILD_SHARED_LIBS "build shared libraries" OFF)
```

--------------------------------

### Set macOS Deployment Target

Source: https://github.com/starmel/opensuperwhisper/blob/master/libwhisper/CMakeLists.txt

Configures the minimum macOS version for which the project will be deployed. This is set to 14.0.

```cmake
set(CMAKE_OSX_DEPLOYMENT_TARGET "14.0")
```

--------------------------------

### updateRecordingSync(_:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Synchronously updates an existing recording in the database.

```APIDOC
## func updateRecordingSync(_ recording: Recording) async throws

### Description
Synchronously updates a recording in the database. Throws database write errors if the operation fails.

### Parameters
- **recording** (Recording) - Required - The recording object with updated fields.
```

--------------------------------

### Standard Keyboard Shortcut Event Handling

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

Registers key down and key up events for the toggleRecord shortcut.

```swift
KeyboardShortcuts.onKeyDown(for: .toggleRecord) { [weak self] in
    self?.handleKeyDown()
}

KeyboardShortcuts.onKeyUp(for: .toggleRecord) { [weak self] in
    self?.handleKeyUp()
}
```

--------------------------------

### Move temporary recording with moveTemporaryRecording

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Moves a temporary recording file to a permanent location, creating parent directories and removing existing files at the destination if necessary.

```swift
func moveTemporaryRecording(from tempURL: URL, to finalURL: URL) throws
```

```swift
do {
    let tempURL = URL(fileURLWithPath: "/var/folders/.../temp.wav")
    let finalURL = URL(fileURLWithPath: "/Applications/OpenSuperWhisper/.../recording.wav")
    try AudioRecorder.shared.moveTemporaryRecording(from: tempURL, to: finalURL)
} catch {
    print("Failed to move recording: \(error)")
}
```

--------------------------------

### WhisperEngine vadModelPath Constant

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

The path to the Silero VAD model used for silence detection.

```swift
static let vadModelPath: String?
```

--------------------------------

### searchRecordingsAsync(query:limit:offset:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Asynchronously searches transcriptions with support for pagination.

```APIDOC
## searchRecordingsAsync(query:limit:offset:)

### Description
Asynchronously searches with pagination.

### Signature
`nonisolated func searchRecordingsAsync(query: String, limit: Int = 100, offset: Int = 0) async -> [Recording]`

### Parameters
- **query** (String) - Search text
- **limit** (Int) - Results per page (Default: 100)
- **offset** (Int) - Results to skip (Default: 0)

### Returns
- `[Recording]` matching transcriptions with pagination
```

--------------------------------

### convertAudioToPCM(fileURL:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

Converts an audio file to 16 kHz mono PCM format. This method handles format detection and utilizes parallel processing for larger files.

```APIDOC
## convertAudioToPCM(fileURL:)

### Description
Converts audio to 16 kHz mono PCM format. It detects MP4/M4A formats by file header and uses parallel processing for files longer than 10 seconds.

### Parameters
- **fileURL** (URL) - Required - Audio file path

### Returns
- **[Float]** - PCM samples at 16 kHz, mono
- **nil** - If audio file is empty or invalid

### Throws
- **TranscriptionError.audioConversionFailed** - Format conversion failed

### Example
```swift
do {
    if let samples = try await whisperEngine.convertAudioToPCM(fileURL: audioURL) {
        print("Converted \(samples.count) PCM samples")
    }
} catch {
    print("Conversion failed: \(error)")
}
```
```

--------------------------------

### Temporary Files Directory Structure

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/configuration.md

Stores temporary audio recordings during capture, which are cleaned up after 24 hours.

```text
/var/folders/.../T/com.opensuperwhisper.audiorecorder/
├── 1234567890.wav                   # Temporary recording during capture
├── 1234567891.wav
└── ...
```

--------------------------------

### Hold-to-Record Threshold Configuration

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

Defines the time interval threshold for entering hold-to-record mode.

```swift
private let holdThreshold: TimeInterval = 0.3
```

--------------------------------

### Settings struct definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/types.md

The Settings struct defines the configuration parameters for transcription engines.

```swift
struct Settings {
    let selectedLanguage: String
    let showTimestamps: Bool
    let suppressBlankAudio: Bool
    let temperature: Double
    let noSpeechThreshold: Double
    let initialPrompt: String
    let useBeamSearch: Bool
    let beamSize: Int
    let shouldApplyAsianAutocorrect: Bool
}
```

--------------------------------

### hotkeySettingsChanged() Synchronization

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/input-management.md

Triggered by settings updates to tear down and re-initialize input monitors.

```swift
@objc private func hotkeySettingsChanged()
```

--------------------------------

### Recording Auto-Delete Settings

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Configuration properties for managing the automatic deletion of completed recordings.

```APIDOC
## Recording Auto-Delete Properties

### autoDeleteRecordingsEnabled
- **Type**: Bool
- **Default**: false
- **Description**: Enables or disables the automatic deletion of old completed recordings.

### autoDeleteRecordingsAfterDays
- **Type**: Int
- **Default**: 30
- **Description**: The age threshold in days for auto-deletion. Only applied if autoDeleteRecordingsEnabled is true.
```

--------------------------------

### Access MicrophoneService shared instance

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Use the static shared property to access the singleton instance of the microphone service.

```swift
static let shared: MicrophoneService
```

--------------------------------

### Checking recording availability with canRecord

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Indicates if recording is possible based on microphone availability and access permissions.

```swift
@Published var canRecord: Bool
```

--------------------------------

### Initialize C++ Compiler Flags

Source: https://github.com/starmel/opensuperwhisper/blob/master/libwhisper/CMakeLists.txt

Sets the initial C++ compiler flags, specifically enabling `-fvisibility=hidden` to control symbol visibility.

```cmake
set(CMAKE_CXX_FLAGS_INIT "-fvisibility=hidden")
```

--------------------------------

### fetchRecordings(limit:offset:) definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

The signature for the asynchronous method used to fetch paginated recordings.

```swift
nonisolated func fetchRecordings(limit: Int, offset: Int) async throws -> [Recording]
```

--------------------------------

### Configure beamSize

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Defines the number of hypotheses used in beam search, typically ranging from 1 to 10.

```swift
@UserDefault(key: "beamSize", defaultValue: 5)
var beamSize: Int
```

--------------------------------

### getInputChannelCount(for:) retrieval

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Returns the number of input channels for a given AudioDevice, defaulting to 1 if unavailable.

```swift
func getInputChannelCount(for device: AudioDevice) -> Int
```

--------------------------------

### getCurrentSystemDefaultInputDevice()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Queries the current system default input device ID.

```APIDOC
## getCurrentSystemDefaultInputDevice()

### Description
Queries the current system default input device.

### Returns
- **AudioDeviceID?** - The ID of the default input device, or nil if unavailable.
```

--------------------------------

### Add Subdirectory for Whisper Source

Source: https://github.com/starmel/opensuperwhisper/blob/master/libwhisper/CMakeLists.txt

Includes the 'whisper.cpp' subdirectory, which contains the main source code for the whisper library.

```cmake
add_subdirectory(whisper.cpp)
```

--------------------------------

### backfillMissingDurations()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Restores duration for recordings saved with duration = 0. Used as a migration for old recordings created before duration tracking.

```swift
nonisolated func backfillMissingDurations() async
```

--------------------------------

### updateRecordingProgressOnlySync(_:transcription:progress:status:isRegeneration:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Persists transcription progress to the database asynchronously, updates the in-memory recordings array, and posts a notification.

```swift
func updateRecordingProgressOnlySync(
    _ id: UUID,
    transcription: String,
    progress: Float,
    status: RecordingStatus,
    isRegeneration: Bool? = nil
) async
```

--------------------------------

### updateRecordingProgressTransient(_:progress:status:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Updates recording progress in memory only to avoid database transaction overhead.

```APIDOC
## func updateRecordingProgressTransient(_ id: UUID, progress: Float, status: RecordingStatus)

### Description
Updates progress and status in memory only. This is an optimization to avoid database transaction overhead during frequent progress updates.

### Parameters
- **id** (UUID) - Required - The ID of the recording to update.
- **progress** (Float) - Required - The progress value (0.0 to 1.0).
- **status** (RecordingStatus) - Required - The status update.
```

--------------------------------

### getSupportedLanguages() definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

Returns an array of ISO 639-1 language codes supported by the Whisper engine.

```swift
func getSupportedLanguages() -> [String]
```

--------------------------------

### Configure noSpeechThreshold

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Sets the confidence threshold for detecting non-speech audio, ranging from 0.0 to 1.0.

```swift
@UserDefault(key: "noSpeechThreshold", defaultValue: 0.6)
var noSpeechThreshold: Double
```

--------------------------------

### progress property

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Represents the overall transcription progress as a float between 0.0 and 1.0.

```swift
@Published private(set) var progress: Float
```

--------------------------------

### deleteAllRecordings()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Deletes all recordings and their associated audio files from the disk and database.

```swift
func deleteAllRecordings()
```

--------------------------------

### AudioDevice structure definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

The AudioDevice struct represents an audio input device and conforms to Identifiable, Equatable, and Codable protocols.

```swift
struct AudioDevice: Identifiable, Equatable, Codable {
    let id: String
    let name: String
    let manufacturer: String?
    let isBuiltIn: Bool
    
    var displayName: String { name }
}
```

--------------------------------

### cancelRecording()

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Stops recording immediately and discards the audio.

```APIDOC
## cancelRecording()

### Description
Stops recording immediately and discards the audio data.

### Signature
`func cancelRecording()`

### Example
```swift
AudioRecorder.shared.cancelRecording()
```
```

--------------------------------

### refreshAvailableMicrophones() usage

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

Manually triggers a rescan of the system for connected microphones. This is typically handled automatically by the service.

```swift
// Manual refresh (usually automatic)
MicrophoneService.shared.refreshAvailableMicrophones()
```

--------------------------------

### Configure showTimestamps

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/app-preferences.md

Toggles the inclusion of segment timestamps in the transcription output in the format [start->end] text.

```swift
@UserDefault(key: "showTimestamps", defaultValue: false)
var showTimestamps: Bool
```

--------------------------------

### TranscriptionQueue.addFileToQueue

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/README.md

Adds an audio file to the transcription queue for processing.

```APIDOC
## TranscriptionQueue.addFileToQueue

### Description
Adds a local audio file to the transcription queue.

### Signature
`await TranscriptionQueue.shared.addFileToQueue(url: URL)`

### Parameters
- **url** (URL) - Required - The file system path to the audio file.
```

--------------------------------

### updateRecordingStatusOnly(_:progress:status:isRegeneration:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Updates the status and progress of a recording without modifying the transcription text.

```swift
func updateRecordingStatusOnly(
    _ id: UUID,
    progress: Float,
    status: RecordingStatus,
    isRegeneration: Bool? = nil
) async
```

--------------------------------

### IndicatorViewModel Definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/types.md

State model for the recording indicator window, used by IndicatorWindow, IndicatorWindowManager, and ShortcutManager.

```swift
@MainActor
class IndicatorViewModel: ObservableObject {
    @Published var isRecording: Bool
    @Published var recordingDuration: TimeInterval
    @Published var transcribingProgress: Float
    @Published var statusMessage: String
    // ... other properties
}
```

--------------------------------

### Monitoring connection status with isConnecting

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/audio-recorder.md

Indicates if the system is waiting for an external microphone connection to stabilize.

```swift
@Published var isConnecting: Bool
```

--------------------------------

### updateRecordingProgressTransient(_:progress:status:) Method Signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Updates progress in memory only to avoid database transaction overhead during frequent updates.

```swift
func updateRecordingProgressTransient(_ id: UUID, progress: Float, status: RecordingStatus)
```

--------------------------------

### getPendingRecordings() definition

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

The signature for the synchronous method that retrieves recordings currently in a pending state.

```swift
func getPendingRecordings() -> [Recording]
```

--------------------------------

### Recording Static Property: databaseTableName

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

The SQLite table name used for storing recordings.

```swift
static let databaseTableName: String = "recordings"
```

--------------------------------

### Access availableMicrophones property

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/microphone-service.md

This published property contains an array of currently available microphones and updates automatically upon device connection or disconnection.

```swift
@Published var availableMicrophones: [AudioDevice]
```

--------------------------------

### TranscriptionEngine Protocol

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-engines.md

The base protocol defining the interface for all transcription engines in the system.

```APIDOC
## TranscriptionEngine Protocol

### Description
Base protocol for all transcription engines. Defines the required properties and methods for any engine implementation.

### Properties
- **isModelLoaded** (Bool) - Whether the transcription model is currently loaded in memory
- **engineName** (String) - Display name of the engine

### Methods
- **initialize()** - Asynchronously loads and initializes the transcription model
- **transcribeAudio(url: URL, settings: Settings)** - Transcribes audio file at URL with given settings
- **cancelTranscription()** - Cancels the currently running transcription
- **getSupportedLanguages()** - Returns array of supported language codes
```

--------------------------------

### recordingsOlderThan(days:)

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Counts and finds the oldest completed recording older than the specified threshold.

```APIDOC
## recordingsOlderThan(days:)

### Description
Counts and finds the oldest completed recording older than the provided age threshold in days.

### Parameters
- **days** (Int) - Age threshold in days

### Returns
- **(count: Int, oldestDate: Date?)** - Count of deletable recordings and oldest timestamp

### Throws
- Database read errors
```

--------------------------------

### transcribeAudio(url:settings:) Function Signature

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

The primary method for transcribing audio from a file URL using the loaded engine.

```swift
func transcribeAudio(url: URL, settings: Settings) async throws -> String
```

--------------------------------

### RecordingStatus State Machine

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/README.md

Visual representation of the lifecycle states for a recording.

```text
pending → converting → transcribing → completed
                    ↓
                   failed
```

--------------------------------

### Recording Computed Property: sourceFileName

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/recording-store.md

Returns the filename of the original imported audio file or nil if not applicable.

```swift
var sourceFileName: String?
```

--------------------------------

### isTranscribing property

Source: https://github.com/starmel/opensuperwhisper/blob/master/_autodocs/api-reference/transcription-service.md

Indicates if a transcription is currently in progress.

```swift
@Published private(set) var isTranscribing: Bool
```
Tokens:
Raw