### FluidAudioModel Initialization Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/transcription-models.md

Demonstrates how to create an instance of the FluidAudioModel struct. This example initializes a 'parakeet' model with specific performance and language details.

```swift
let parakeet = FluidAudioModel(
    name: "parakeet",
    displayName: "Parakeet",
    description: "Low-latency streaming model",
    size: "medium",
    speed: 0.95,
    accuracy: 0.88,
    ramUsage: 0.5,
    supportsStreaming: true,
    supportedLanguages: ["en": "English"]
)
```

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

### TranscriptionPipeline Process Method Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Provides an example of how to call the process method on a TranscriptionPipeline instance to get transcription results.

```swift
let result = try await pipeline.process(
    audioData: recordedAudio,
    modelName: "whisper-base",
    configuration: runtimeConfig
)
```

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

### ModeCustomCommand Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Illustrates how to initialize a ModeCustomCommand with a shell command string.

```swift
let customCmd = ModeCustomCommand(
    command: "echo '{% transcription %}' | pbcopy"
)
```

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

### Custom Cloud Model Instantiation Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/cloud-providers.md

Example of how to instantiate a CustomCloudModel with specific details. The API key is automatically fetched from Keychain.

```swift
let customModel = CustomCloudModel(
    name: "My API",
    displayName: "Custom Transcription",
    description: "Self-hosted Whisper",
    apiEndpoint: "https://whisper.example.com/v1",
    modelName: "whisper-large",
    isMultilingual: true
)
// API key automatically fetched from Keychain
```

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

### Example Source File Paths

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/INDEX.md

Illustrates the format of source file paths used within the documentation.

```text
Transcription/Engine/VoiceInkEngine.swift
Services/AIEnhancement/AIEnhancementService.swift
Models/TranscriptionModel.swift
Modes/ModeConfig.swift
Shortcuts/ShortcutStore.swift
```

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

### CustomPrompt Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Shows how to create a CustomPrompt instance with a title, prompt text, and system instruction preference.

```swift
let prompt = CustomPrompt(
    title: "Professional",
    promptText: "Fix grammar and improve clarity. Keep the original tone.",
    useSystemInstructions: true
)
```

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

### URLConfig Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Instantiates a URLConfig for 'github.com'. This will match any URL containing this substring, such as 'https://github.com/repo/issues'.

```swift
let github = URLConfig(url: "github.com")
```

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

### Example Shortcut Storage JSON

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

An example of a shortcut's data structure as stored in UserDefaults, including its ID, action, key, modifiers, and enabled state.

```json
{
  "id": "...",
  "action": "startRecording",
  "keyEquivalent": " ",
  "modifiers": ["command", "shift"],
  "isEnabled": true
}
```

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

### Example Usage of detectActiveMode

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Demonstrates how to use the detectActiveMode function to get the active mode based on the frontmost application and browser URL.

```swift
let activeMode = detectActiveMode(
    bundleId: NSWorkspace.shared.frontmostApplication?.bundleIdentifier,
    browserURL: getBrowserURL()
)
```

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

### Start Audio Recording

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Begins audio capture from the configured device and publishes raw PCM audio data as Data chunks. It also starts audio level monitoring and applies media pause/audio mute. Throws RecorderError.couldNotStartRecording if hardware fails.

```swift
func startRecording() async throws -> AnyPublisher<Data, Never>
```

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

### Instantiate NativeAppleModel

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/transcription-models.md

Example of how to create an instance of NativeAppleModel. This is used for on-device speech recognition.

```swift
let nativeModel = NativeAppleModel(
    name: "apple-speech-recognition",
    displayName: "Apple Speech Recognition",
    description: "On-device speech recognition",
    isMultilingualModel: true,
    supportedLanguages: ["en": "English"]
)
```

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

### Usage in Apple Shortcuts

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Example of how to invoke the ToggleMiniRecorderIntent within the Apple Shortcuts app.

```text
Run [Toggle Mini Recorder] with Show: true
```

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

### Clone and Build VoiceInk with Makefile

Source: https://github.com/beingpax/voiceink/blob/main/BUILDING.md

Use these commands to clone the repository and perform a full build. The 'make all' command is recommended for initial setup.

```bash
git clone https://github.com/Beingpax/VoiceInk.git
cd VoiceInk

make all
```

```bash
make dev
```

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

### Install VoiceInk with Homebrew

Source: https://github.com/beingpax/voiceink/blob/main/README.md

Install the VoiceInk application using the Homebrew package manager. This is a convenient method for macOS users.

```shell
brew install --cask voiceink
```

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

### AudioMeter Usage Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Demonstrates how to use the AudioMeter struct for UI visualization by normalizing peak power values.

```swift
@Published var audioMeter: AudioMeter = AudioMeter(averagePower: 0, peakPower: 0)

// In visualizer view:
let normalized = (audioMeter.peakPower + 160) / 160
```

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

### Transcription Model Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Demonstrates creating a Transcription instance, setting its properties, and assigning a raw status value.

```swift
let transcription = Transcription(
    text: "Hello world",
    duration: 2.5,
    transcriptionModelName: "whisper-base"
)
transcription.enhancedText = "Hello, world."
transcription.transcriptionStatus = TranscriptionStatus.completed.rawValue
```

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

### Instantiate CustomCloudModel

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/transcription-models.md

Example of how to create an instance of the CustomCloudModel. This is useful for setting up a user-defined transcription service.

```swift
let custom = CustomCloudModel(
    name: "My Custom API",
    displayName: "Custom Transcription",
    description: "Self-hosted transcription service",
    apiEndpoint: "https://api.example.com/v1/transcribe",
    modelName: "whisper-large-v3",
    isMultilingual: true
)
```

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

### Start Deepgram Streaming Transcription

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/cloud-providers.md

Example of how to initiate a streaming transcription session with Deepgram and process the results. Ensure API key and endpoint are configured.

```swift
let deepgram = DeepgramStreamingProvider()
let stream = try await deepgram.startStreaming(language: "en")

for await partialText in stream {
    print("Partial: \(partialText)")
}
```

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

### Instantiating CloudModel

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/transcription-models.md

Example of how to create an instance of the CloudModel struct. This demonstrates providing values for all required parameters to represent a specific transcription model.

```swift
let deepgram = CloudModel(
    name: "nova-2",
    displayName: "Deepgram Nova 2",
    description: "High-accuracy cloud transcription",
    provider: .deepgram,
    speed: 0.9,
    accuracy: 0.98,
    isMultilingual: true,
    supportsStreaming: true,
    supportedLanguages: ["en": "English", "es": "Spanish"]
)
```

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

### Instantiate WhisperModel

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/transcription-models.md

Example of how to create an instance of WhisperModel. This represents a Whisper model with its performance characteristics.

```swift
let whisper = WhisperModel(
    name: "ggml-base",
    displayName: "Base",
    size: "base",
    supportedLanguages: ["en": "English"],
    description: "Balanced speed and accuracy",
    speed: 0.7,
    accuracy: 0.9,
    ramUsage: 1.5
)
```

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

### AppConfig Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Instantiates an AppConfig for the macOS Mail application. This can be used to trigger a mode when Mail is active.

```swift
let mailApp = AppConfig(
    bundleIdentifier: "com.apple.mail",
    appName: "Mail"
)
```

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

### Create a ModeConfig Instance

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Example of initializing a ModeConfig object with specific settings for an 'Email' mode, including app configuration, AI enhancement, and output mode.

```swift
let mode = ModeConfig(
    id: UUID(),
    name: "Email",
    icon: .emoji("✉️"),
    appConfigs: [AppConfig(bundleIdentifier: "com.apple.mail", appName: "Mail")],
    isAIEnhancementEnabled: true,
    selectedPrompt: "Professional",
    useSelectedTextContext: true,
    outputMode: .paste
)
```

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

### VoiceInkEngine.startRecording

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Starts the audio recording process, initializing a new transcription session. It can be used for new sessions or assistant follow-ups.

```APIDOC
## startRecording(useCase: RecordingUseCase) async throws

### Description
Starts the audio recording process, initializing a new transcription session. It can be used for new sessions or assistant follow-ups.

### Method
`async throws`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **useCase** (RecordingUseCase) - Required - `.newSession` or `.assistantFollowUp`

### Throws
- `VoiceInkEngineError` if microphone unavailable or insufficient permissions.

### Details
- Creates new `TranscriptionSession` with unique ID
- Captures current application and browser context
- Initializes realtime audio buffering and chunk gating
- Registers audio chunk callbacks for streaming models
- Posts `.recordingDidStart` notification

### Request Example
```swift
do {
    try await engine.startRecording(useCase: .newSession)
} catch {
    await handleRecordingError(error)
}
```

### Response
#### Success Response
None

#### Response Example
None
```

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

### Start Recording with VoiceInkEngine

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Initiates a new recording session using the VoiceInkEngine. Handles potential errors related to microphone access or permissions.

```swift
do {
    try await engine.startRecording(useCase: .newSession)
} catch {
    await handleRecordingError(error)
}
```

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

### Prepare Recorder for Audio Device

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Sets up the CoreAudio session for a specified audio input device. This method configures sample rate, format, and buffer sizes, and runs on a dedicated queue for thread safety. It throws a RecorderError if CoreAudio setup fails.

```swift
func prepare(for device: AudioDeviceID) async throws
```

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

### Start Keyboard Event Monitoring

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Registers an NSEvent monitor for keyboard events. Call this method to begin monitoring.

```swift
func start()
```

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

### Listen for Shortcut Press

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Set up a manager to monitor for shortcut presses and handle the corresponding actions. This involves starting monitoring and defining a handler for shortcut events.

```swift
class RecorderController {
    let shortcutManager = RecordingShortcutManager()
    
    func setup() async {
        await shortcutManager.startMonitoring()
    }
    
    func handleShortcutAction(_ action: ShortcutAction) {
        switch action {
        case .startRecording:
            Task {
                try await engine.startRecording(useCase: .newSession)
            }
        case .stopRecording:
            Task {
                await engine.stopRecording()
            }
        default:
            break
        }
    }
}
```

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

### Stream Transcription with Streaming Service

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/cloud-providers.md

Demonstrates how to initiate and process a real-time transcription stream using StreamingTranscriptionService. This example includes iterating over the stream and handling UI updates.

```swift
let service = StreamingTranscriptionService()
let stream = try await service.startStreaming(
    model: deepgramModel,
    language: "en"
)

for await partial in stream {
    await updateUI(with: partial)
    if shouldStop {
        break
    }
}

let final = await service.getFinalResult()
```

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

### Handle RecorderError

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/errors.md

Demonstrates how to catch and handle the `RecorderError.couldNotStartRecording` exception. This is useful for notifying the user and guiding them to check system audio settings.

```swift
do {
    try await recorder.startRecording()
} catch RecorderError.couldNotStartRecording {
    // Notify user, check System Settings > Sound
}
```

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

### Transcribe Audio with Cloud Service

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/cloud-providers.md

Provides an example of how to use the CloudTranscriptionService to transcribe audio data. Ensure you have recorded audio and a model defined.

```swift
let service = CloudTranscriptionService()
let result = try await service.transcribe(
    audioData: recordedAudio,
    model: deepgramModel,
    language: "en"
)
```

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

### ModeOutputMode Usage Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Demonstrates how to declare a ModeOutputMode variable and access its iconName computed property.

```swift
let outputMode = ModeOutputMode.paste
let icon = outputMode.iconName // "doc.on.clipboard"
```

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

### ShortcutMonitor

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Manages low-level global keyboard event monitoring. Use start() to begin monitoring and stop() to end it. The isMonitoring property indicates the current status.

```APIDOC
## ShortcutMonitor Class

Low-level global keyboard event monitor.

### Methods

#### start()

Registers NSEvent monitor for keyboard events.

### start()

#### stop()

Removes event monitor.

### stop()

#### isMonitoring

Indicates if the monitor is currently active.

### isMonitoring

```

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

### Start Global Event Monitoring

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Registers a global event monitor to intercept keyboard events and match them against defined shortcut bindings. This method runs on the MainActor.

```swift
func startMonitoring() async
```

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

### AutoSendKey Usage Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Demonstrates how to declare an AutoSendKey variable and check its isEnabled computed property before applying auto-send behavior.

```swift
let autoSend = AutoSendKey.commandEnter
if autoSend.isEnabled {
    // Apply the auto-send behavior
}
```

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

### ModeTriggerGroup Example

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Creates a 'Social Media' trigger group containing configurations for Twitter, Facebook, and Instagram URLs. This can be used to manage related triggers efficiently.

```swift
let socialMediaGroup = ModeTriggerGroup(
    name: "Social Media",
    appConfigs: [
        AppConfig(bundleIdentifier: "com.twitter.twitter", appName: "Twitter"),
        AppConfig(bundleIdentifier: "com.facebook.Facebook", appName: "Facebook")
    ],
    urlConfigs: [
        URLConfig(url: "instagram.com")
    ]
)
```

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

### Get Mode Configuration by URL

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Finds the first enabled mode configuration that matches a given URL substring. Searches both direct URL configurations and trigger groups.

```swift
if let mode = ModeManager.shared.getConfigurationForURL("github.com/issues") {
    // Apply mode
}
```

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

### Instantiate ImportedWhisperModel

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/transcription-models.md

Example of how to create an instance of the ImportedWhisperModel struct using a base filename. This is used to represent a local Whisper model file.

```swift
let imported = ImportedWhisperModel(fileBaseName: "ggml-medium.bin")
```

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

### Handle Shortcut Press Action

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Processes a shortcut press based on the provided action. Different actions trigger specific recording behaviors like starting, stopping, canceling, toggling, or push-to-talk.

```swift
func handleShortcutPress(action: ShortcutAction)
```

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

### Get Mode-Specific Shortcuts

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Retrieves the list of shortcuts configured to activate a particular application mode. This is useful for understanding which shortcuts are associated with a given mode.

```swift
func getShortcuts(for mode: ModeConfig) -> [Shortcut]
```

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

### Start Streaming Transcription

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/README.md

Initiates a real-time transcription stream using a specified model and language. The stream yields partial results as they become available.

```swift
let stream = try await streamingService.startStreaming(
    model: deepgramModel,
    language: "en"
)

for await partial in stream {
    updateUI(with: partial) // Partial transcription
}

let final = await getFinalized()
```

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

### Handle AIEnhancementError in Swift

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/errors.md

Demonstrates how to catch and manage specific AI enhancement errors using a do-catch block. Includes examples for handling API key issues and rate limiting with backoff.

```swift
do {
    let enhanced = try await service.enhance(...)
} catch AIEnhancementError.apiKeyNotFound(let provider) {
    print("Please add API key for \(provider)")
} catch AIEnhancementError.rateLimitExceeded {
    try await Task.sleep(nanoseconds: 2_000_000_000) // 2s backoff
    // Retry
} catch {
    handleError(error)
}
```

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

### Get Mode Configuration by App Bundle ID

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Retrieves the first enabled mode configuration that matches a specific application bundle ID. Performs an exact match.

```swift
if let mode = ModeManager.shared.getConfigurationForApp("com.apple.mail") {
    // Apply email-specific settings
}
```

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

### Recorder.prepare

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Sets up the CoreAudio session for a specified audio input device. It configures essential audio parameters and ensures thread safety by running on a dedicated queue.

```APIDOC
## prepare(for device: AudioDeviceID) async throws

### Description
Sets up CoreAudio session for specified device, configuring sample rate, format, and buffer sizes. Runs on a dedicated audio setup queue for thread safety.

### Method
`async throws`

### Parameters
#### Path Parameters
- **device** (AudioDeviceID) - Required - Target audio input device ID

### Throws
- `RecorderError` if CoreAudio setup fails
```

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

### Get Shortcut Method

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Retrieves the active shortcut binding for a specified action.

```swift
func getShortcut(for action: ShortcutAction) -> Shortcut?
```

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

### AIEnhancementService Get AIService Method

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Retrieves the underlying AIService instance used by the enhancement service.

```swift
func getAIService() -> AIService?
```

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

### Recorder.startRecording

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Begins audio capture from the configured device, publishing raw PCM audio data chunks via a Combine Publisher. It also initiates audio level monitoring and respects media pause/mute states.

```APIDOC
## startRecording() async throws -> AnyPublisher<Data, Never>

### Description
Begins audio capture from the configured device, publishing raw PCM audio data as Data chunks. Starts audio level monitoring and applies media pause/audio mute.

### Method
`async throws -> AnyPublisher<Data, Never>`

### Returns
Combine Publisher emitting audio data chunks.

### Throws
- `RecorderError.couldNotStartRecording` if hardware fails
```

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

### Shortcuts

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/README.md

Documentation for managing global and mode-specific keyboard shortcuts, including data models and Siri integration.

```APIDOC
## Shortcuts

### Description
Details the data models and management of keyboard shortcuts for quick access to VoiceInk features. Includes global monitoring, mode-specific bindings, and Siri integration via App Intents.

### Data Models
- **Shortcut**: Data model for shortcuts.
- **ShortcutAction**: Enumeration of possible shortcut actions.

### Management
- **ShortcutStore**: Manages keyboard binding persistence.
- **RecordingShortcutManager**: Handles global shortcut monitoring.
- **ModeShortcutManager**: Manages mode-specific shortcut bindings.

### Integration
- **App Intents**: For Siri integration.
- **ShortcutValidator**: Detects and manages shortcut conflicts.
```

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

### Get Custom Model API Key

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Retrieves the API key associated with a specific custom model using its UUID.

```swift
func getCustomModelAPIKey(forModelId modelId: UUID) -> String?
```

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

### ModeOutputMode Static Method

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

A static method to get available choices, optionally filtering by whether the app supports responding.

```swift
static func choices(canRespond: Bool) -> [ModeOutputMode]
```

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

### Get Standard Provider API Key

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Retrieves the stored API key for a given provider. Returns nil if the key is not found.

```swift
func getAPIKey(forProvider provider: String) -> String?
```

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

### Get Mode Configuration by ID

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Retrieves a specific mode configuration by its ID. Returns the configuration if found, otherwise returns nil.

```swift
func getConfiguration(with id: UUID) -> ModeConfig?
```

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

### Configuration Reference

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/README.md

Details on application configuration, including UserDefaults keys, environment variables, file storage, and SwiftData schema.

```APIDOC
## Configuration Reference

### Description
Details the various configuration mechanisms used by VoiceInk, including storage locations, runtime options, and feature flags.

### Configuration Sources
- **UserDefaults**: Keys and structure for user preferences.
- **Environment Variables**: For runtime configuration.
- **File Storage**: Locations for data persistence.
- **Keychain**: Identifiers for secure credential storage.

### Specific Configurations
- **ModeConfig**: Runtime options for modes.
- **Shortcut Configuration**: Storage for keyboard shortcut settings.
- **SwiftData Schema**: Details of the data model queries.
- **Feature Flags**: For controlling build configurations.
- **Notification Names**: Purposes of various notification events.
```

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

### Shortcut Storage Key Structure

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Illustrates the key structure used in UserDefaults for storing individual shortcut configurations.

```plaintext
com.prakashjoshipax.voiceink.shortcut.{action}
```

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

### Basic AI Enhancement Usage

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Demonstrates how to use the AIEnhancementService for basic text enhancement with an OpenAI provider. Ensure the service is configured with the necessary API key and model details before use.

```swift
let service = AIEnhancementService()

// Create or load a prompt
let prompt = CustomPrompt(
    title: "Professional",
    promptText: "Fix grammar and improve clarity while maintaining tone."
)

// Create runtime configuration
let config = EnhancementRuntimeConfiguration(
    prompt: prompt,
    provider: .openai,
    modelName: "gpt-4",
    useSelectedTextContext: true,
    useClipboardContext: false,
    useScreenCaptureContext: false
)

// Check if ready
guard service.isConfigured(for: config) else {
    print("Missing API key or configuration")
    return
}

// Enhance transcription
let enhanced = try await service.enhance(
    transcription: "hello world how are you",
    with: prompt,
    context: config,
    contextSnapshot: contextSnapshot
)
print(enhanced) // "Hello world, how are you?"
```

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

### Custom Prompt Management with AIEnhancementService

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Shows how to manage custom prompts using the AIEnhancementService, including adding new prompts, listing all available prompts, and updating existing ones. Changes are automatically saved.

```swift
let service = AIEnhancementService()

// Add new prompt
let newPrompt = CustomPrompt(
    id: UUID(),
    title: "Casual",
    promptText: "Make it sound more casual and friendly."
)
service.customPrompts.append(newPrompt)
// Automatically saved to UserDefaults

// List all prompts
for prompt in service.allPrompts {
    print(prompt.title)
}

// Update prompt
if let index = service.customPrompts.firstIndex(where: { $0.title == "Casual" }) {
    service.customPrompts[index].promptText = "Make it sound very casual and fun!"
}
```

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

### AIEnhancementService Initializer

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Initializes the AIEnhancementService with an optional AIService and a required ModelContext. Loads saved prompts and sets up observers.

```swift
init(aiService: AIService = AIService(), modelContext: ModelContext)
```

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

### GroqProvider Class Implementation

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/cloud-providers.md

Implements the CloudProvider protocol for Groq's transcription service, supporting streaming. Requires API key and endpoint configuration. Offers different models for transcription and enhancement.

```swift
class GroqProvider: CloudProvider {
    var name: String { "groq" }
    var displayName: String { "Groq" }
    var supportsStreaming: Bool { true }
    
    func transcribe(
        audioData: Data,
        model: String,
        language: String?
    ) async throws -> String
}
```

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

### Define RecorderError Enum

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/errors.md

Defines the enumeration for low-level audio hardware errors. This error specifically indicates a failure to start the recording process.

```swift
enum RecorderError: Error {
    case couldNotStartRecording
}
```

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

### CustomVocabularyService.addWord

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Adds a custom word or proper noun to the vocabulary, optionally with a phonetic guide. This helps improve transcription accuracy for specific terms.

```APIDOC
## addWord(_:pronunciation:) throws

### Description
Adds a custom word or proper noun to the vocabulary, optionally with a phonetic guide. This helps improve transcription accuracy for specific terms.

### Method
Throws

### Parameters
#### Path Parameters
- **word** (String) - Required - Custom term/proper noun
- **pronunciation** (String?) - Optional - Phonetic guide

### Response
#### Success Response
void

#### Response Example
(No example provided)
```

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

### Transcription Model Constructor

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Shows how to initialize a Transcription object with various parameters, including optional fields and default values.

```swift
init(text: String, duration: TimeInterval, enhancedText: String? = nil,
     audioFileURL: String? = nil, transcriptionModelName: String? = nil,
     aiEnhancementModelName: String? = nil, promptName: String? = nil,
     transcriptionDuration: TimeInterval? = nil, enhancementDuration: TimeInterval? = nil,
     aiRequestSystemMessage: String? = nil, aiRequestUserMessage: String? = nil,
     modeName: String? = nil, modeEmoji: String? = nil,
     transcriptionStatus: TranscriptionStatus = .pending)
```

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

### Get Streaming Transcript from VoiceInkEngine

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Retrieves the current partial transcription as it is being streamed from the model. This is typically used by the UI to display live transcription progress.

```swift
func getStreamingTranscript() -> String {
    return partialTranscript
}
```

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

### SystemInfoService

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Provides access to system and application information.

```APIDOC
## SystemInfoService Class

Provides system and application information.

### Properties

- **osVersion** (String) - macOS version (e.g., "14.4")
- **systemArchitecture** (String) - "arm64" or "x86_64"
- **appVersion** (String) - VoiceInk version string
```

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

### getConfigurationForApp(_ bundleId: String) -> ModeConfig?

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Finds the first enabled mode that matches a given application's bundle identifier. Matching is exact.

```APIDOC
## getConfigurationForApp(_ bundleId: String) -> ModeConfig?

### Description
Retrieves the first enabled mode configuration that matches a given application's bundle identifier. The matching is performed as an exact string comparison.

### Method
Swift Function Call

### Endpoint
N/A (Local method)

### Parameters
#### Path Parameters
- **bundleId** (String) - Required - The macOS bundle identifier of the application to match.

### Returns
- **ModeConfig?** - The matching mode configuration if found, otherwise `nil`.

### Details
- Searches enabled modes only.
- Checks both direct `appConfigs` and `triggerGroups`.
- Exact bundle ID matching.

### Request Example
```swift
if let mode = ModeManager.shared.getConfigurationForApp("com.apple.mail") {
    // Apply email-specific settings
}
```
```

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

### AudioDeviceManager getSystemInputDevice Method

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Retrieves the default system input audio device. Returns the device if available, otherwise nil.

```swift
func getSystemInputDevice() -> AudioDevice?
```

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

### loadConfigurations()

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Loads modes from UserDefaults. This method is called automatically on initialization.

```APIDOC
## loadConfigurations()

### Description
Loads modes from UserDefaults, performing data migrations if necessary. This is typically called automatically during initialization.

### Method
Swift Function Call

### Endpoint
N/A (Local method)

### Parameters
None

### Details
- Reads key `"modeConfigurationsV2"` from UserDefaults.
- Runs data migrations on loaded configurations.
- Called automatically on initialization.
```

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

### Get Formatted Custom Vocabulary

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Retrieves the entire custom vocabulary formatted as a string suitable for AI system messages. The format is TERM: pronunciation or definition.

```swift
func getCustomVocabulary(from context: ModelContext) -> String
```

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

### Add Word to Custom Vocabulary

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Adds a custom word or proper noun to the vocabulary, optionally with a phonetic guide. This method can throw an error if the operation fails.

```swift
func addWord(_ word: String, pronunciation: String?) throws
```

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

### addConfiguration(_ config: ModeConfig)

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Adds a new mode configuration if a mode with the same ID does not already exist. It then saves the configurations and checks for shortcut availability.

```APIDOC
## addConfiguration(_ config: ModeConfig)

### Description
Adds a new mode configuration to the list. The configuration is only added if no existing mode shares the same ID. This operation also saves the updated configurations and checks for shortcut availability.

### Method
Swift Function Call

### Endpoint
N/A (Local method)

### Parameters
#### Request Body
- **config** (ModeConfig) - Required - The mode configuration object to add.

### Details
- Appends the configuration only if no existing mode with the same ID is found.
- Saves configurations and posts change notifications.
- Checks for shortcut availability changes.

### Request Example
```swift
let newMode = ModeConfig(
    id: UUID(),
    name: "Email",
    isAIEnhancementEnabled: true
)
ModeManager.shared.addConfiguration(newMode)
```
```

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

### SelectedTextService.captureScreenContent

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Asynchronously captures and extracts text content from the visible screen using OCR and accessibility APIs. This is useful for getting text from elements that are not standard text fields.

```APIDOC
## captureScreenContent() async -> String?

### Description
Asynchronously captures and extracts text content from the visible screen using OCR and accessibility APIs. This is useful for getting text from elements that are not standard text fields.

### Method
Async

### Returns
OCR/accessibility text from visible window.

### Response
#### Success Response
- **screenContent** (String?) - The extracted text from the screen, or nil if capture fails.

#### Response Example
(No example provided)
```

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

### LocalCLIService.executeCommand

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Executes a local shell command with provided input and returns the standard output. This is useful for integrating external text processing tools.

```APIDOC
## LocalCLIService.executeCommand

### Description
Executes a local shell command with provided input and returns the standard output. This is useful for integrating external text processing tools.

### Method
`executeCommand(_:with:) async throws -> String`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
let result = try await service.executeCommand(
    "sed 's/hello/hi/g'",
    with: "hello world"
)
// Returns: "hi world"
```

### Response
#### Success Response (200)
- **output** (String) - The standard output from the executed command.

#### Response Example
```json
{
  "output": "hi world"
}
```

### Errors
- `ProcessError` if the command fails.
```

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

### AppShortcuts

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Defines Siri voice commands and Apple Shortcuts integration for VoiceInk.

```APIDOC
## App Intents

### AppShortcuts

Defines Siri voice commands and Apple Shortcuts integration.

**Available Voice Commands:**
- "Toggle VoiceInk recorder"
- "Hide VoiceInk recorder"
```

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

### Deepgram Streaming Provider Class Definition

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/cloud-providers.md

Defines the structure for a streaming transcription provider using Deepgram. It indicates support for streaming and outlines the method for starting a streaming session.

```swift
class DeepgramStreamingProvider: StreamingTranscriptionProvider {
    var supportsStreaming: Bool { true } 
    
    func startStreaming(
        language: String?
    ) async throws -> AsyncStream<String>
}
```

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

### Mode Selection Flow

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/README.md

Details the process of capturing context and detecting the active mode when recording starts. This flow determines the transcription model, AI enhancement, and output method to be applied.

```text
Recording starts
    ↓
Capture context (app, URL, selected text)
    ↓
ModeManager.detectActiveMode()
    ├─ Check app triggers
    ├─ Check URL triggers
    └─ Return default or matching mode
    ↓
ModeRuntimeConfiguration resolved
    ↓
Apply transcription model, AI enhancement, output method
```

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

### Combine App and URL Configurations

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/types.md

Computed properties that combine top-level and group-nested app and URL configurations into single arrays.

```swift
var allAppConfigs: [AppConfig]
var allURLConfigs: [URLConfig]
```

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

### Get Selected Text

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Asynchronously retrieves the text currently selected in a focused field. Returns nil if no text is selected. This method relies on native text fields and accessibility APIs.

```swift
func getSelectedText() async -> String?
```

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

### Core Services

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/README.md

Documentation for various utility services, including API key management, audio device handling, custom vocabulary, and more.

```APIDOC
## Core Services

### Description
Provides reference for essential utility services within VoiceInk, such as managing API keys, handling audio devices, custom vocabulary, and session metrics.

### Services
- **APIKeyManager**: Securely stores and retrieves API credentials.
- **KeychainService**: Low-level wrapper for Keychain operations.
- **AudioDeviceManager**: Manages audio device selection.
- **CustomVocabularyService**: Manages domain-specific terms for improved accuracy.
- **SelectedTextService**: Captures context from selected text.
- **ClipboardManager**: Provides access to the system clipboard.
- **SessionMetricRecorder**: Tracks usage metrics.
- **AudioFileTranscriptionService**: Handles transcription of audio files.
- **ImportExportService**: Facilitates backup and restore operations.
```

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

### Check AIEnhancementService Configuration

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Determines if the service is configured with the necessary API keys and models for a given runtime configuration. Checks for prompt selection, provider availability, and API key presence.

```swift
func isConfigured(for configuration: EnhancementRuntimeConfiguration) -> Bool
```

```swift
let runtimeConfig = EnhancementRuntimeConfiguration(
    prompt: customPrompt,
    provider: .openai,
    modelName: "gpt-4"
)
let isReady = service.isConfigured(for: runtimeConfig)
```

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

### Handling Keychain Errors

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/errors.md

Demonstrates how to catch and handle specific KeychainError cases when retrieving an API key.

```swift
do {
    let key = try APIKeyManager.shared.getAPIKey(forProvider: "openai")
} catch KeychainError.itemNotFound {
    // Key not set up
}
```

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

### saveShortcut(_ shortcut: Shortcut)

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Stores a given shortcut mapping, registers it with the event monitor, saves it to UserDefaults, and posts a shortcut change notification.

```APIDOC
## saveShortcut(_ shortcut: Shortcut)

### Description
Stores shortcut mapping, registers with event monitor, saves to UserDefaults, and posts shortcut change notification.

### Method
Swift Function Call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **shortcut** (Shortcut) - The shortcut object to save.
```

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

### Recorder Class

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/recording-engine.md

Manages audio hardware interaction using CoreAudio, monitors audio levels, and handles device changes. It provides methods to prepare, start, stop, and switch audio input devices.

```swift
@MainActor
class Recorder: NSObject, ObservableObject {
    @Published var audioMeter: AudioMeter
    var onAudioChunk: ((_ data: Data) -> Void)?
    
    func prepare(for device: AudioDeviceID) async throws
    func startRecording() async throws -> AnyPublisher<Data, Never>
    func stopRecording() async throws -> Data
    func switchDevice(to newDeviceID: AudioDeviceID) throws
}
```

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

### Clone VoiceInk Repository Manually

Source: https://github.com/beingpax/voiceink/blob/main/BUILDING.md

Manually clone the VoiceInk repository. This is the first step in the manual build process.

```bash
git clone https://github.com/Beingpax/VoiceInk.git
cd VoiceInk
```

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

### Register a Custom Shortcut

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Register a new custom shortcut with a specific action, key equivalent, and modifiers. Ensure the ShortcutStore is accessible for saving.

```swift
let newShortcut = Shortcut(
    id: UUID(),
    action: .startRecording,
    keyEquivalent: "r",
    modifiers: [.command, .shift],
    isEnabled: true
)

ShortcutStore.shared.saveShortcut(newShortcut)
```

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

### Load Mode Configurations

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Loads mode configurations from UserDefaults. This method is called automatically on initialization.

```swift
func loadConfigurations()
```

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

### File Statistics Overview

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/INDEX.md

Provides a summary of the total number of documentation files and lines, broken down by type and distribution across different features.

```markdown
Total Documentation Files: 11
Total Lines: 4,994

By Type:
- API Reference: 8 files (3,200 lines)
- Type Reference: 1 file (800 lines)
- Configuration: 1 file (500 lines)
- Error Catalog: 1 file (500 lines)

Distribution:
- Recording & Engine: 600 lines
- Types & Data: 800 lines
- AI & Enhancement: 700 lines
- Cloud Providers: 800 lines
- Services: 600 lines
- Modes & Config: 600 lines
- Shortcuts: 400 lines
- Errors: 500 lines
- Config: 500 lines
```

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

### ShortcutStore Class Definition

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Defines the ShortcutStore class, its properties, and methods for managing shortcuts.

```swift
class ShortcutStore: ObservableObject {
    static let shared: ShortcutStore
    
    @Published var shortcuts: [ShortcutAction: Shortcut]
    
    func saveShortcut(_ shortcut: Shortcut)
    func removeShortcut(for action: ShortcutAction)
    func getShortcut(for action: ShortcutAction) -> Shortcut?
    func validateShortcut(_ shortcut: Shortcut) -> Bool
}
```

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

### getConfigurationForURL(_ url: String) -> ModeConfig?

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Finds the first enabled mode that matches a given URL. Matching is performed as a case-insensitive substring search.

```APIDOC
## getConfigurationForURL(_ url: String) -> ModeConfig?

### Description
Retrieves the first enabled mode configuration that matches a given URL. The matching is done as a case-insensitive substring search against the URL.

### Method
Swift Function Call

### Endpoint
N/A (Local method)

### Parameters
#### Path Parameters
- **url** (String) - Required - The browser URL to match against.

### Returns
- **ModeConfig?** - The matching mode configuration if found, otherwise `nil`.

### Details
- Searches enabled modes only.
- Checks both direct `urlConfigs` and `triggerGroups`.
- Matching is substring-based (case-insensitive).

### Request Example
```swift
if let mode = ModeManager.shared.getConfigurationForURL("github.com/issues") {
    // Apply mode
}
```
```

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

### shouldApplyMode

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Determines if a specific mode configuration should be applied for the given application bundle ID or URL.

```APIDOC
## shouldApplyMode

### Description
Determines if a specific mode configuration should be applied for the given application bundle ID or URL.

### Function Signature
```swift
func shouldApplyMode(
    _ mode: ModeConfig,
    forApp bundleId: String?,
    orURL url: String?
) -> Bool
```

### Parameters
#### Required Parameters
- **mode** (ModeConfig) - The mode configuration to check.

#### Optional Parameters
- **bundleId** (String?) - The application bundle identifier.
- **url** (String?) - The URL to check against.

### Returns
- **Bool** - True if the mode should be applied, false otherwise.
```

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

### Build VoiceInk for Local Use

Source: https://github.com/beingpax/voiceink/blob/main/BUILDING.md

Build VoiceInk for local deployment without requiring an Apple Developer certificate. This uses ad-hoc signing and a separate build configuration.

```bash
git clone https://github.com/Beingpax/VoiceInk.git
cd VoiceInk
make local
open ~/Downloads/VoiceInk.app
```

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

### enhancementSystemTemplate Format

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Illustrates the format string for the AI enhancement system template, including a placeholder for custom prompt text.

```plaintext
You are a text enhancement assistant. Your role is to improve transcribed speech-to-text output.
%@
[Context sections if applicable]
```

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

### Core Recording Flow

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/README.md

Illustrates the sequence of events from user shortcut activation to saving a transcription record. This flow involves audio capture, transcription, optional AI enhancement, and final delivery.

```text
User activates shortcut
    ↓
VoiceInkEngine.startRecording()
    ↓
Recorder captures audio via CoreAudio
    ↓
TranscriptionService processes audio
    ├─ Streaming transcription → UI updates
    └─ Final result
    ↓
AIEnhancementService (optional)
    ↓
TranscriptionDelivery
    ├─ Paste to clipboard
    ├─ Respond in app
    └─ Execute custom command
    ↓
TranscriptionRecord saved to SwiftData
```

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

### Save Shortcut Method

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Stores a shortcut mapping, registers it with the event monitor, saves it to UserDefaults, and posts a shortcut change notification.

```swift
func saveShortcut(_ shortcut: Shortcut)
```

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

### Build whisper.cpp XCFramework Manually

Source: https://github.com/beingpax/voiceink/blob/main/BUILDING.md

Manually clone and build the whisper.cpp project to generate the necessary XCFramework. This is an alternative to the Makefile's automated process.

```bash
git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp
./build-xcframework.sh
```

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

### RecordingShortcutManager

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Manages global event monitoring and execution of recording shortcuts.

```APIDOC
## RecordingShortcutManager Class

Manages and executes recording shortcuts globally.

### Methods

#### startMonitoring() async

Registers a global event monitor to intercept keyboard events and match them against shortcut bindings. This method runs on the MainActor.

- **Method:** async

#### stopMonitoring()

Removes the global event monitor.

- **Method:** synchronous

#### handleShortcutPress(action: ShortcutAction)

Handles the press of a shortcut action, with behavior varying based on the action type:
- `.startRecording`: Initiates a new recording session.
- `.stopRecording`: Stops the current recording.
- `.cancelRecording`: Cancels the current recording.
- `.toggleRecording`: Starts recording if idle, or stops if active.
- `.pushToTalk`: Records while a key is held and transcribes upon release.

- **Method:** synchronous
- **Parameters:**
  - **action** (ShortcutAction) - The specific shortcut action to handle.
```

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

### AppShortcuts Provider

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Defines Siri voice commands and Apple Shortcuts integration for VoiceInk. This includes shortcuts for toggling and dismissing the mini recorder.

```swift
struct AppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: ToggleMiniRecorderIntent(),
            phrases: ["Toggle VoiceInk recorder"],
            shortTitle: "Toggle Recorder",
            systemImageName: "waveform"
        )
        
        AppShortcut(
            intent: DismissMiniRecorderIntent(),
            phrases: ["Hide VoiceInk recorder"],
            shortTitle: "Hide Recorder",
            systemImageName: "xmark.circle"
        )
    }
}
```

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

### VoiceInk Application Support File Structure

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/configuration.md

Overview of the directory structure for VoiceInk application support files. This includes configuration files like custom prompts and vocabulary, downloaded Whisper models, and transcription history.

```text
~/Library/Application Support/com.prakashjoshipax.voiceink/
├── modes.json               # Mode configurations (legacy)
├── customPrompts.json       # Custom AI prompts
├── vocabularyWords.json     # Custom vocabulary entries
├── whisperModels/           # Downloaded Whisper model files
│   ├── ggml-base.bin
│   ├── ggml-small.bin
│   └── ggml-large.bin
└── history/                 # Transcription history (SwiftData)
    └── default.store
```

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

### moveConfigurations(fromOffsets: IndexSet, toOffset: Int)

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/modes-configuration.md

Reorders the list of mode configurations, typically used for UI-driven drag-and-drop functionality. Changes are saved and notifications are posted.

```APIDOC
## moveConfigurations(fromOffsets: IndexSet, toOffset: Int)

### Description
Reorders the list of mode configurations. This is commonly used to support drag-and-drop UI interactions for changing the order of modes. The changes are saved, and notifications are posted.

### Method
Swift Function Call

### Endpoint
N/A (Local method)

### Parameters
#### Path Parameters
- **fromOffsets** (IndexSet) - Required - The set of indices representing the items to be moved.
- **toOffset** (Int) - Required - The destination index where the items should be moved.

### Details
- Reorders configurations, typically used by drag-and-drop UI.
- Saves configurations and notifies of changes.
```

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

### AudioFileTranscriptionService Transcribe Method

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Handles the transcription of audio files. Specify the model and optionally the language for transcription. Ensure the audio file exists at the provided URL.

```swift
func transcribe(
        fileURL: URL,
        model: String,
        language: String?
    ) async throws -> String
```

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

### ShortcutMonitor Class Definition

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Defines the structure for the ShortcutMonitor class, which handles low-level global keyboard event monitoring.

```swift
class ShortcutMonitor: NSObject {
    func start()
    func stop()
    var isMonitoring: Bool
}
```

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

### AIEnhancementService customPrompts management

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/ai-enhancement.md

Manages custom prompts for AI enhancements. Users can add new prompts, list existing ones, and update their text.

```APIDOC
## AIEnhancementService customPrompts

### Description
Manages custom prompts for AI enhancements. Users can add new prompts, list existing ones, and update their text.

### Properties
- **customPrompts** (Array<CustomPrompt>) - Access and modify the list of custom prompts.
- **allPrompts** (Array<CustomPrompt>) - Read-only access to all available prompts (custom and predefined).

### Methods
- **add custom prompt**: Append a `CustomPrompt` object to the `customPrompts` array.
- **update custom prompt**: Modify the `promptText` of an existing `CustomPrompt` in the `customPrompts` array.
- **list all prompts**: Iterate through the `allPrompts` array to access prompt titles.
```

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

### Shortcut Struct

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/shortcuts.md

Represents a single keyboard shortcut binding, including its action, key equivalent, modifier flags, and enabled state.

```APIDOC
## Shortcut Struct

### Description
Represents a single keyboard shortcut binding.

### Properties
- **id** (UUID) - Unique shortcut identifier
- **action** (ShortcutAction) - What happens when pressed
- **keyEquivalent** (String) - Key character (e.g., " " for spacebar)
- **modifiers** (NSEvent.ModifierFlags) - Ctrl, Shift, Cmd, Option flags
- **isEnabled** (Bool) - Shortcut is active

### ModifierFlags
- `.command` — Command key (⌘)
- `.shift` — Shift key (⇧)
- `.option` — Option key (⌥)
- `.control` — Control key (⌃)
```

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

### AudioDeviceManager

Source: https://github.com/beingpax/voiceink/blob/main/_autodocs/api-reference/services.md

Manages audio input device selection and monitoring, allowing users to set preferred devices and retrieve system defaults.

```APIDOC
## AudioDeviceManager Class

Manages audio input device selection and monitoring.

### Properties

- **availableDevices** ([AudioDevice]) - List of available input devices.
- **currentDevice** (AudioDevice?) - The currently selected audio input device.
- **isRecordingActive** (Bool) - Indicates if a recording is currently in progress.

### Methods

#### setPreferredDevice(_:) throws

Sets the preferred audio input device.

**Parameters:**
- **device** (AudioDevice) - The audio device to set as preferred.

**Throws:**
- `AudioDeviceError` - If the device switch operation fails.

---

#### getSystemInputDevice() -> AudioDevice?

Retrieves the default system input audio device.

**Returns:**
- AudioDevice? - The default system input device, or nil if none is available or an error occurs.

---
```