Implement Phase 1: Global hotkey, HUD, and audio capture

Add complete listening UX without STT:
- Global hotkey manager with ⌘⇧V, push-to-talk and toggle modes
- Floating HUD with real-time RMS audio visualization
- AVAudioEngine capture with 16kHz mono PCM conversion
- 10-minute dictation timeout with ESC cancellation
- Optional start/stop sounds and microphone permissions
- Permission management for accessibility and input monitoring

All Phase 1 acceptance criteria met.
This commit is contained in:
Felipe M 2025-09-18 20:06:46 +02:00
parent 1db16227b2
commit 6e768a7753
Signed by: fmartingr
GPG key ID: CCFBC5637D4000A8
10 changed files with 1005 additions and 51 deletions

View file

@ -0,0 +1,239 @@
import SwiftUI
import CoreUtils
import MenuWhisperAudio
import CorePermissions
import AVFoundation
public class AppController: ObservableObject {
private let logger = Logger(category: "AppController")
// Core components
private let hotkeyManager = HotkeyManager()
private let audioEngine = AudioEngine()
private let permissionManager = PermissionManager()
private let soundManager = SoundManager()
// UI components
private var hudWindow: HUDWindow?
// State management
@Published public private(set) var currentState: AppState = .idle
@Published public var isToggleListening = false
// Dictation timer
private var dictationTimer: Timer?
private let maxDictationDuration: TimeInterval = 600 // 10 minutes default
public init() {
setupDelegates()
setupNotifications()
}
deinit {
cleanup()
}
public func start() {
logger.info("Starting app controller")
// Check microphone permission first
checkMicrophonePermission { [weak self] granted in
if granted {
self?.setupHotkey()
} else {
self?.logger.warning("Microphone permission not granted")
}
}
}
private func setupDelegates() {
hotkeyManager.delegate = self
audioEngine.delegate = self
}
private func setupNotifications() {
NotificationCenter.default.addObserver(
self,
selector: #selector(handleHUDEscape),
name: .hudEscapePressed,
object: nil
)
}
private func setupHotkey() {
hotkeyManager.enableHotkey()
}
private func checkMicrophonePermission(completion: @escaping (Bool) -> Void) {
permissionManager.requestMicrophonePermission { status in
DispatchQueue.main.async {
completion(status == .granted)
}
}
}
@objc private func handleHUDEscape() {
logger.info("HUD escape pressed - cancelling dictation")
cancelDictation()
}
private func startListening() {
guard currentState == .idle else {
logger.warning("Cannot start listening from state: \(currentState)")
return
}
logger.info("Starting listening")
currentState = .listening
do {
try audioEngine.startCapture()
showHUD(state: .listening(level: 0))
startDictationTimer()
soundManager.playStartSound()
} catch {
logger.error("Failed to start audio capture: \(error)")
currentState = .error
soundManager.playErrorSound()
showError("Failed to start microphone: \(error.localizedDescription)")
}
}
private func stopListening() {
guard currentState == .listening else {
logger.warning("Cannot stop listening from state: \(currentState)")
return
}
logger.info("Stopping listening")
stopDictationTimer()
audioEngine.stopCapture()
soundManager.playStopSound()
// Transition to processing state
currentState = .processing
showHUD(state: .processing)
// For Phase 1, we'll just simulate processing and return to idle
// In Phase 2, this is where we'd call the STT engine
DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
self.finishProcessing()
}
}
private func finishProcessing() {
logger.info("Finishing processing")
currentState = .idle
hideHUD()
// Reset toggle state if in toggle mode
if hotkeyManager.currentMode == .toggle {
isToggleListening = false
}
}
private func cancelDictation() {
logger.info("Cancelling dictation")
stopDictationTimer()
if audioEngine.isCapturing {
audioEngine.stopCapture()
}
currentState = .idle
hideHUD()
// Reset toggle state
if hotkeyManager.currentMode == .toggle {
isToggleListening = false
}
}
private func startDictationTimer() {
stopDictationTimer() // Clean up any existing timer
dictationTimer = Timer.scheduledTimer(withTimeInterval: maxDictationDuration, repeats: false) { [weak self] _ in
self?.logger.info("Dictation timeout reached")
self?.stopListening()
}
}
private func stopDictationTimer() {
dictationTimer?.invalidate()
dictationTimer = nil
}
private func showHUD(state: HUDState) {
if hudWindow == nil {
hudWindow = HUDWindow()
}
hudWindow?.show(state: state)
}
private func hideHUD() {
hudWindow?.hide()
}
private func showError(_ message: String) {
logger.error("Error: \(message)")
// TODO: Show error dialog in a later phase
currentState = .idle
}
private func cleanup() {
stopDictationTimer()
audioEngine.stopCapture()
hotkeyManager.disableHotkey()
NotificationCenter.default.removeObserver(self)
}
}
// MARK: - HotkeyManagerDelegate
extension AppController: HotkeyManagerDelegate {
public func hotkeyPressed(mode: HotkeyMode, isKeyDown: Bool) {
logger.debug("Hotkey pressed: mode=\(mode), isKeyDown=\(isKeyDown)")
switch mode {
case .pushToTalk:
if isKeyDown {
startListening()
} else {
if currentState == .listening {
stopListening()
}
}
case .toggle:
if isKeyDown { // Only respond to key down in toggle mode
if currentState == .idle && !isToggleListening {
isToggleListening = true
startListening()
} else if currentState == .listening && isToggleListening {
isToggleListening = false
stopListening()
}
}
}
}
}
// MARK: - AudioEngineDelegate
extension AppController: AudioEngineDelegate {
public func audioEngine(_ engine: AudioEngine, didUpdateLevel level: Float) {
// Update HUD with new level
hudWindow?.updateLevel(level)
}
public func audioEngine(_ engine: AudioEngine, didCaptureAudio data: Data) {
logger.info("Audio capture completed: \(data.count) bytes")
// In Phase 2, this is where we'd send the data to STT
}
public func audioEngineDidStartCapture(_ engine: AudioEngine) {
logger.info("Audio engine started capture")
}
public func audioEngineDidStopCapture(_ engine: AudioEngine) {
logger.info("Audio engine stopped capture")
}
}

214
Sources/App/HUDWindow.swift Normal file
View file

@ -0,0 +1,214 @@
import SwiftUI
import AppKit
import CoreUtils
public enum HUDState {
case hidden
case listening(level: Float)
case processing
}
public class HUDWindow: NSPanel {
private var hostingView: NSHostingView<HUDContentView>?
public init() {
super.init(
contentRect: NSRect(x: 0, y: 0, width: 320, height: 160),
styleMask: [.nonactivatingPanel],
backing: .buffered,
defer: false
)
setupWindow()
setupContentView()
}
private func setupWindow() {
level = .floating
isOpaque = false
backgroundColor = NSColor.clear
hasShadow = true
isMovable = false
collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
}
private func setupContentView() {
let hudContentView = HUDContentView()
hostingView = NSHostingView(rootView: hudContentView)
if let hostingView = hostingView {
contentView = hostingView
}
}
public func show(state: HUDState) {
centerOnScreen()
if let hostingView = hostingView {
hostingView.rootView.updateState(state)
}
if !isVisible {
orderFront(nil)
alphaValue = 0
NSAnimationContext.runAnimationGroup({ context in
context.duration = 0.2
animator().alphaValue = 1.0
})
}
}
public func hide() {
guard isVisible else { return }
NSAnimationContext.runAnimationGroup({ context in
context.duration = 0.2
animator().alphaValue = 0
}, completionHandler: {
self.orderOut(nil)
})
}
public func updateLevel(_ level: Float) {
if let hostingView = hostingView {
hostingView.rootView.updateState(.listening(level: level))
}
}
private func centerOnScreen() {
guard let screen = NSScreen.main else { return }
let screenFrame = screen.visibleFrame
let windowSize = frame.size
let x = screenFrame.midX - windowSize.width / 2
let y = screenFrame.midY - windowSize.height / 2
setFrameOrigin(NSPoint(x: x, y: y))
}
override public func keyDown(with event: NSEvent) {
if event.keyCode == 53 { // Escape key
NotificationCenter.default.post(name: .hudEscapePressed, object: nil)
return
}
super.keyDown(with: event)
}
override public var canBecomeKey: Bool {
return true // Allow the window to receive key events
}
}
extension Notification.Name {
static let hudEscapePressed = Notification.Name("hudEscapePressed")
}
struct HUDContentView: View {
@State private var currentState: HUDState = .hidden
var body: some View {
ZStack {
RoundedRectangle(cornerRadius: 12)
.fill(.regularMaterial)
.overlay(
RoundedRectangle(cornerRadius: 12)
.stroke(Color.primary.opacity(0.1), lineWidth: 1)
)
VStack(spacing: 16) {
switch currentState {
case .hidden:
EmptyView()
case .listening(let level):
listeningView(level: level)
case .processing:
processingView
}
}
.padding(24)
}
.frame(width: 320, height: 160)
}
@ViewBuilder
private func listeningView(level: Float) -> some View {
VStack(spacing: 12) {
Image(systemName: "mic.fill")
.font(.system(size: 32))
.foregroundColor(.blue)
Text("Listening...")
.font(.headline)
.foregroundColor(.primary)
AudioLevelView(level: level)
.frame(height: 20)
Text("Press Esc to cancel")
.font(.caption)
.foregroundColor(.secondary)
}
}
@ViewBuilder
private var processingView: some View {
VStack(spacing: 12) {
ProgressView()
.scaleEffect(1.2)
Text("Processing...")
.font(.headline)
.foregroundColor(.primary)
Text("Please wait")
.font(.caption)
.foregroundColor(.secondary)
}
}
func updateState(_ state: HUDState) {
withAnimation(.easeInOut(duration: 0.3)) {
currentState = state
}
}
}
struct AudioLevelView: View {
let level: Float
private let barCount = 20
var body: some View {
HStack(spacing: 2) {
ForEach(0..<barCount, id: \.self) { index in
RoundedRectangle(cornerRadius: 1)
.fill(barColor(for: index))
.frame(width: 12, height: barHeight(for: index))
.animation(.easeInOut(duration: 0.1), value: level)
}
}
}
private func barHeight(for index: Int) -> CGFloat {
let threshold = Float(index) / Float(barCount - 1)
return level > threshold ? 20 : 4
}
private func barColor(for index: Int) -> Color {
let threshold = Float(index) / Float(barCount - 1)
if level > threshold {
if threshold < 0.6 {
return .green
} else if threshold < 0.8 {
return .orange
} else {
return .red
}
} else {
return .gray.opacity(0.3)
}
}
}

View file

@ -0,0 +1,152 @@
import Foundation
import AppKit
import Carbon
import CoreUtils
public enum HotkeyMode: String, CaseIterable {
case pushToTalk = "pushToTalk"
case toggle = "toggle"
public var displayName: String {
switch self {
case .pushToTalk:
return NSLocalizedString("hotkey.mode.push", comment: "Push-to-talk mode")
case .toggle:
return NSLocalizedString("hotkey.mode.toggle", comment: "Toggle mode")
}
}
}
public protocol HotkeyManagerDelegate: AnyObject {
func hotkeyPressed(mode: HotkeyMode, isKeyDown: Bool)
}
public class HotkeyManager: ObservableObject {
private let logger = Logger(category: "HotkeyManager")
public weak var delegate: HotkeyManagerDelegate?
@Published public var currentMode: HotkeyMode = .toggle
@Published public var isEnabled: Bool = false
private var hotKeyRef: EventHotKeyRef?
private var eventHandler: EventHandlerRef?
// Default hotkey: V (Command + Shift + V)
private let defaultKeyCode: UInt32 = 9 // V key
private let defaultModifiers: UInt32 = UInt32(cmdKey + shiftKey)
public init() {
setupEventHandler()
}
deinit {
unregisterHotkey()
if let handler = eventHandler {
RemoveEventHandler(handler)
}
}
public func enableHotkey() {
guard !isEnabled else { return }
logger.info("Enabling global hotkey")
let hotKeyID = EventHotKeyID(signature: OSType(0x4D575350), id: 1) // 'MWSP'
let status = RegisterEventHotKey(
defaultKeyCode,
defaultModifiers,
hotKeyID,
GetApplicationEventTarget(),
0,
&hotKeyRef
)
if status == noErr {
isEnabled = true
logger.info("Global hotkey registered successfully")
} else {
logger.error("Failed to register global hotkey: \(status)")
}
}
public func disableHotkey() {
guard isEnabled else { return }
logger.info("Disabling global hotkey")
unregisterHotkey()
isEnabled = false
}
private func unregisterHotkey() {
if let hotKeyRef = hotKeyRef {
UnregisterEventHotKey(hotKeyRef)
self.hotKeyRef = nil
}
}
private func setupEventHandler() {
let eventTypes: [EventTypeSpec] = [
EventTypeSpec(eventClass: OSType(kEventClassKeyboard), eventKind: OSType(kEventHotKeyPressed)),
EventTypeSpec(eventClass: OSType(kEventClassKeyboard), eventKind: OSType(kEventHotKeyReleased))
]
let callback: EventHandlerProcPtr = { (nextHandler, theEvent, userData) -> OSStatus in
guard let userData = userData else { return OSStatus(eventNotHandledErr) }
let manager = Unmanaged<HotkeyManager>.fromOpaque(userData).takeUnretainedValue()
var hotKeyID = EventHotKeyID()
let status = GetEventParameter(
theEvent,
OSType(kEventParamDirectObject),
OSType(typeEventHotKeyID),
nil,
MemoryLayout<EventHotKeyID>.size,
nil,
&hotKeyID
)
guard status == noErr else { return OSStatus(eventNotHandledErr) }
let eventKind = GetEventKind(theEvent)
let isKeyDown = eventKind == OSType(kEventHotKeyPressed)
DispatchQueue.main.async {
manager.handleHotkeyEvent(isKeyDown: isKeyDown)
}
return noErr
}
let selfPtr = Unmanaged.passUnretained(self).toOpaque()
let status = InstallEventHandler(
GetApplicationEventTarget(),
callback,
2,
eventTypes,
selfPtr,
&eventHandler
)
if status != noErr {
logger.error("Failed to install event handler: \(status)")
}
}
private func handleHotkeyEvent(isKeyDown: Bool) {
logger.debug("Hotkey event: \(isKeyDown ? "down" : "up"), mode: \(currentMode)")
switch currentMode {
case .pushToTalk:
// In push-to-talk mode, respond to both key down and up
delegate?.hotkeyPressed(mode: currentMode, isKeyDown: isKeyDown)
case .toggle:
// In toggle mode, only respond to key down
if isKeyDown {
delegate?.hotkeyPressed(mode: currentMode, isKeyDown: true)
}
}
}
}

View file

@ -0,0 +1,64 @@
import SwiftUI
import CoreUtils
@main
struct MenuWhisperApp: App {
@StateObject private var appController = AppController()
var body: some Scene {
MenuBarExtra("Menu-Whisper", systemImage: "mic") {
MenuBarContentView()
.environmentObject(appController)
.onAppear {
appController.start()
}
}
}
}
struct MenuBarContentView: View {
@EnvironmentObject var appController: AppController
var body: some View {
VStack(alignment: .leading, spacing: 4) {
Text("Menu-Whisper")
.font(.headline)
Text(appController.currentState.displayName)
.font(.subheadline)
.foregroundColor(stateColor)
if appController.currentState == .listening {
Text("Press ⌘⇧V or Esc to stop")
.font(.caption)
.foregroundColor(.secondary)
}
Divider()
Button("Preferences...") {
// TODO: Open preferences window in Phase 4
}
Button("Quit") {
NSApplication.shared.terminate(nil)
}
}
.padding(.horizontal, 4)
}
private var stateColor: Color {
switch appController.currentState {
case .idle:
return .primary
case .listening:
return .blue
case .processing:
return .orange
case .injecting:
return .green
case .error:
return .red
}
}
}

View file

@ -0,0 +1,51 @@
import Foundation
import AVFoundation
import AppKit
import CoreUtils
public class SoundManager: ObservableObject {
private let logger = Logger(category: "SoundManager")
@Published public var soundsEnabled: Bool = true
private var startSound: AVAudioPlayer?
private var stopSound: AVAudioPlayer?
public init() {
setupSounds()
}
private func setupSounds() {
// Use system sounds for now
// In a future version, we could bundle custom sound files
setupSystemSounds()
}
private func setupSystemSounds() {
// We'll use NSSound for system sounds since AVAudioPlayer requires files
// These are just placeholders - in a real implementation we'd bundle sound files
logger.info("Sound manager initialized with system sounds")
}
public func playStartSound() {
guard soundsEnabled else { return }
logger.debug("Playing start sound")
// Use a subtle system sound for start
NSSound(named: "Glass")?.play()
}
public func playStopSound() {
guard soundsEnabled else { return }
logger.debug("Playing stop sound")
// Use a different system sound for stop
NSSound(named: "Blow")?.play()
}
public func playErrorSound() {
logger.debug("Playing error sound")
// Always play error sound regardless of settings
NSSound(named: "Funk")?.play()
}
}

View file

@ -1,18 +0,0 @@
import SwiftUI
@main
struct MenuWhisperApp: App {
var body: some Scene {
MenuBarExtra("Menu-Whisper", systemImage: "mic") {
Text("Menu-Whisper")
Text("Idle")
Divider()
Button("Preferences...") {
// TODO: Open preferences
}
Button("Quit") {
NSApplication.shared.terminate(nil)
}
}
}
}