# VoiceScribe Pro Runbook (LLM/Dev)

## 1. Overview

VoiceScribe Pro is a macOS application designed for seamless voice transcription using on-device processing. Key features include:

- **Fn Hotkey Activation:** Use the Function key to start and stop voice recording.
- **Audio Capture:** Utilizes `AVAudioEngine` to capture microphone input.
- **Streaming Transcription:** Employs Apple’s WhisperKit for on-device streaming speech recognition.
- **Auto-Paste Functionality:** Transcribed text is automatically pasted into the current text input via Accessibility APIs.

---

## 2. Permissions & Entitlements

VoiceScribe Pro requires several permissions and entitlements to function properly:

### Info.plist Keys

- `NSMicrophoneUsageDescription` — Access to microphone.
- `NSAppleEventsUsageDescription` — Needed if sending Apple Events.
- `NSAccessibilityUsageDescription` — Required for controlling system UI and pasting text.
- `com.apple.security.device.audio-input` — Audio input entitlement.
- `com.apple.security.automation.apple-events` — For Apple Events, if applicable.

### Accessibility Permissions Setup

To enable auto-paste and hotkey monitoring via Accessibility:

1. Open System Preferences → Security & Privacy → Privacy → Accessibility.
2. Add VoiceScribe Pro to the list.
3. Ensure VoiceScribe Pro is checked.
4. Restart the app after granting permissions.

---

## 3. Start/Stop Orchestration

### Start Streaming Sequence

```swift
// Prepare audio session
try AVAudioSession.sharedInstance().setCategory(.record, mode: .measurement, options: [.duckOthers])
try AVAudioSession.sharedInstance().setActive(true, options: [.notifyOthersOnDeactivation])

// Prepare transcriber
let transcriber = WhisperKitTranscriber()
transcriber.prepare()

// Install tap on AVAudioEngine inputNode
inputNode.installTap(onBus: 0, bufferSize: 1024, format: inputFormat) { buffer, time in
    transcriber.streamAudio(buffer)
}

// Start audio engine
try audioEngine.start()

// Start transcriber streaming
transcriber.startStreaming()
