feat(openwispr): openwispr mac application

Author: tnfssc

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: macos-15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show Swift version
+        run: swift --version
+
+      - name: Run lint, build, and tests
+        run: ./scripts/check.sh

.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: macos-15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show Swift version
+        run: swift --version
+
+      - name: Build release package
+        run: ./scripts/package-release.sh "${{ github.ref_name }}"
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: OpenWispr-${{ github.ref_name }}
+          path: dist/*
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true
+          files: |
+            dist/*.zip
+            dist/*.sha256

.gitignore

@@ -0,0 +1,6 @@
+.build/
+dist/
+DerivedData/
+*.xcodeproj/
+*.xcworkspace/
+.DS_Store

Package.swift

@@ -0,0 +1,30 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+    name: "OpenWispr",
+    platforms: [
+        .macOS(.v14),
+    ],
+    products: [
+        .library(name: "OpenWisprCore", targets: ["OpenWisprCore"]),
+        .executable(name: "OpenWispr", targets: ["OpenWispr"]),
+        .executable(name: "OpenWisprSelfTest", targets: ["OpenWisprSelfTest"]),
+    ],
+    targets: [
+        .target(
+            name: "OpenWisprCore",
+            path: "Sources/OpenWisprCore"
+        ),
+        .executableTarget(
+            name: "OpenWispr",
+            dependencies: ["OpenWisprCore"],
+            path: "Sources/OpenWisprMac"
+        ),
+        .executableTarget(
+            name: "OpenWisprSelfTest",
+            dependencies: ["OpenWisprCore"],
+            path: "SelfTests"
+        ),
+    ]
+)

README.md

@@ -0,0 +1,92 @@
+# OpenWispr
+
+A native macOS menu bar dictation app inspired by the Linux `openwispr-gnome-extension` flow.
+
+## What it does
+
+- Menu bar mic app with `idle -> recording -> processing` states
+- Global hotkeys for toggle recording and hold-to-talk
+- STT providers:
+  - Local `whisper-cli`
+  - OpenAI endpoint
+  - Groq endpoint
+- Optional LLM transcript cleanup (OpenAI or Groq)
+- Optional FFmpeg silence trimming
+- Clipboard copy always + optional auto-paste (`Cmd+V` simulation)
+- Optional start-at-login toggle (when running as a bundled `.app`)
+
+## Dependencies (Homebrew)
+
+```bash
+brew install ffmpeg whisper-cpp
+```
+
+Expected default paths:
+
+- `ffmpeg`: `/opt/homebrew/bin/ffmpeg` (Apple Silicon)
+- `whisper-cli`: `/opt/homebrew/bin/whisper-cli` (Apple Silicon)
+
+If your binaries are elsewhere, set paths in app Settings.
+
+## Run
+
+```bash
+swift run OpenWispr
+```
+
+When running via `swift run`, macOS notifications are disabled automatically because this runtime is not a bundled `.app`.
+
+## Permissions
+
+For full behavior parity, macOS may prompt for:
+
+- Microphone access
+- Accessibility access (for synthetic paste)
+
+Start at login requires running the packaged `.app` (not `swift run`).
+
+## Local model
+
+For local STT, point `Local Model Path` to a valid Whisper model file, for example:
+
+`~/openwispr/models/ggml-base.en.bin`
+
+## Notes
+
+- This is a standalone macOS app codebase (not a GNOME extension port-in-place).
+- API keys are currently stored in user defaults for speed of iteration.
+
+## Packaging
+
+Create an unsigned `.app` zip locally:
+
+```bash
+./scripts/package-release.sh v0.1.0
+```
+
+Artifacts are written to `dist/`:
+
+- `OpenWispr-<tag>-macos-<arch>.zip`
+- `OpenWispr-<tag>-macos-<arch>.zip.sha256`
+
+This package is intentionally unsigned for now.
+
+## GitHub Releases
+
+Pushing any git tag triggers `.github/workflows/release.yml`, which will:
+
+- build the release package
+- upload it as a workflow artifact
+- create/update a GitHub Release for that tag with the zip + checksum attached
+
+## Tests and Linting
+
+```bash
+./scripts/lint.sh
+./scripts/test.sh
+./scripts/check.sh
+```
+
+- `scripts/lint.sh`: strict style checks using `swift format lint`.
+- `scripts/test.sh`: self-test executable for shortcut parsing, response parsing, and path resolution.
+- `scripts/check.sh`: lint + build + tests in one command.

SelfTests/main.swift

@@ -0,0 +1,76 @@
+import Carbon
+import Foundation
+import OpenWisprCore
+
+struct SelfTestRunner {
+  private(set) var failures = 0
+
+  mutating func expect(_ condition: @autoclosure () -> Bool, _ message: String) {
+    if condition() {
+      print("[pass] \(message)")
+    } else {
+      failures += 1
+      print("[fail] \(message)")
+    }
+  }
+
+  mutating func run() {
+    let parsedAngle = ShortcutParser.parse("<Control><Option>R")
+    expect(parsedAngle != nil, "Shortcut parser handles angle-bracket style")
+    expect(parsedAngle?.keyCode == UInt32(kVK_ANSI_R), "Shortcut parser maps key code")
+    expect(
+      parsedAngle?.modifiers == (UInt32(controlKey) | UInt32(optionKey)),
+      "Shortcut parser maps modifier flags"
+    )
+
+    expect(
+      ShortcutParser.parse("<Control><Option>") == nil, "Shortcut parser rejects missing key token")
+
+    if let sttData = "{\"text\":\"hello world\"}".data(using: .utf8) {
+      expect(
+        TranscriptParser.parseSTTResponse(data: sttData) == "hello world",
+        "STT parser extracts text")
+    } else {
+      failures += 1
+      print("[fail] STT parser test data could not be created")
+    }
+
+    if let llmData = "{\"choices\":[{\"message\":{\"content\":\" cleaned text \"}}]}".data(
+      using: .utf8)
+    {
+      expect(
+        TranscriptParser.parseLLMResponse(data: llmData) == "cleaned text",
+        "LLM parser extracts cleaned content")
+    } else {
+      failures += 1
+      print("[fail] LLM parser test data could not be created")
+    }
+
+    expect(
+      TranscriptParser.normalize("\"Hello\"") == "Hello",
+      "Transcript normalizer strips wrapping quotes")
+    expect(
+      TranscriptParser.normalize("```markdown\nHello\n```") == "Hello",
+      "Transcript normalizer strips code fences"
+    )
+
+    let expanded = PathResolver.expand("~/openwispr/model.bin")
+    expect(expanded.hasPrefix(NSHomeDirectory()), "Path resolver expands tilde prefix")
+
+    let unknownBinary = "openwispr-test-\(UUID().uuidString)"
+    expect(
+      PathResolver.resolveExecutable(unknownBinary) == unknownBinary,
+      "Path resolver preserves unknown executable names"
+    )
+
+    if failures == 0 {
+      print("\nAll self-tests passed.")
+    } else {
+      print("\nSelf-tests failed: \(failures)")
+      exit(1)
+    }
+  }
+}
+
+var runner = SelfTestRunner()
+runner.run()

Sources/OpenWisprCore/PathResolver.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+public enum PathResolver {
+  public static func expand(_ path: String) -> String {
+    (path as NSString).expandingTildeInPath
+  }
+
+  public static func resolveExecutable(_ path: String) -> String {
+    let expanded = expand(path)
+    if expanded.contains("/") {
+      return expanded
+    }
+
+    for candidate in ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin"] {
+      let full = "\(candidate)/\(expanded)"
+      if FileManager.default.fileExists(atPath: full) {
+        return full
+      }
+    }
+
+    return expanded
+  }
+}

Sources/OpenWisprCore/ShortcutParser.swift

@@ -0,0 +1,104 @@
+import Carbon
+import Foundation
+
+public struct KeyShortcut: Equatable {
+  public let keyCode: UInt32
+  public let modifiers: UInt32
+
+  public init(keyCode: UInt32, modifiers: UInt32) {
+    self.keyCode = keyCode
+    self.modifiers = modifiers
+  }
+}
+
+public enum ShortcutParser {
+  public static func parse(_ rawShortcut: String) -> KeyShortcut? {
+    let shortcut = rawShortcut.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !shortcut.isEmpty else {
+      return nil
+    }
+
+    let modifierTokens: [String]
+    let keyToken: String
+
+    if shortcut.contains("<") {
+      let regex = try? NSRegularExpression(pattern: "<([^>]+)>")
+      let nsRange = NSRange(shortcut.startIndex..<shortcut.endIndex, in: shortcut)
+      let matches = regex?.matches(in: shortcut, range: nsRange) ?? []
+
+      modifierTokens = matches.compactMap { match in
+        guard let range = Range(match.range(at: 1), in: shortcut) else { return nil }
+        return String(shortcut[range]).lowercased()
+      }
+
+      keyToken =
+        regex?.stringByReplacingMatches(in: shortcut, range: nsRange, withTemplate: "")
+        .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    } else if shortcut.contains("+") {
+      let parts = shortcut.split(separator: "+").map {
+        String($0).trimmingCharacters(in: .whitespacesAndNewlines)
+      }
+      guard let last = parts.last else {
+        return nil
+      }
+
+      modifierTokens = parts.dropLast().map { $0.lowercased() }
+      keyToken = last
+    } else {
+      modifierTokens = []
+      keyToken = shortcut
+    }
+
+    guard let keyCode = keyCodeForToken(keyToken) else {
+      return nil
+    }
+
+    var modifiers: UInt32 = 0
+    for token in modifierTokens {
+      switch token {
+      case "control", "ctrl", "primary":
+        modifiers |= UInt32(controlKey)
+      case "option", "alt", "mod1":
+        modifiers |= UInt32(optionKey)
+      case "shift":
+        modifiers |= UInt32(shiftKey)
+      case "command", "cmd", "super", "meta", "mod4":
+        modifiers |= UInt32(cmdKey)
+      default:
+        break
+      }
+    }
+
+    return KeyShortcut(keyCode: keyCode, modifiers: modifiers)
+  }
+
+  private static func keyCodeForToken(_ rawToken: String) -> UInt32? {
+    let token = rawToken.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+    guard !token.isEmpty else {
+      return nil
+    }
+
+    let keyMap: [String: UInt32] = [
+      "a": UInt32(kVK_ANSI_A), "b": UInt32(kVK_ANSI_B), "c": UInt32(kVK_ANSI_C),
+      "d": UInt32(kVK_ANSI_D), "e": UInt32(kVK_ANSI_E), "f": UInt32(kVK_ANSI_F),
+      "g": UInt32(kVK_ANSI_G), "h": UInt32(kVK_ANSI_H), "i": UInt32(kVK_ANSI_I),
+      "j": UInt32(kVK_ANSI_J), "k": UInt32(kVK_ANSI_K), "l": UInt32(kVK_ANSI_L),
+      "m": UInt32(kVK_ANSI_M), "n": UInt32(kVK_ANSI_N), "o": UInt32(kVK_ANSI_O),
+      "p": UInt32(kVK_ANSI_P), "q": UInt32(kVK_ANSI_Q), "r": UInt32(kVK_ANSI_R),
+      "s": UInt32(kVK_ANSI_S), "t": UInt32(kVK_ANSI_T), "u": UInt32(kVK_ANSI_U),
+      "v": UInt32(kVK_ANSI_V), "w": UInt32(kVK_ANSI_W), "x": UInt32(kVK_ANSI_X),
+      "y": UInt32(kVK_ANSI_Y), "z": UInt32(kVK_ANSI_Z),
+      "0": UInt32(kVK_ANSI_0), "1": UInt32(kVK_ANSI_1), "2": UInt32(kVK_ANSI_2),
+      "3": UInt32(kVK_ANSI_3), "4": UInt32(kVK_ANSI_4), "5": UInt32(kVK_ANSI_5),
+      "6": UInt32(kVK_ANSI_6), "7": UInt32(kVK_ANSI_7), "8": UInt32(kVK_ANSI_8),
+      "9": UInt32(kVK_ANSI_9),
+      "space": UInt32(kVK_Space),
+      "f1": UInt32(kVK_F1), "f2": UInt32(kVK_F2), "f3": UInt32(kVK_F3),
+      "f4": UInt32(kVK_F4), "f5": UInt32(kVK_F5), "f6": UInt32(kVK_F6),
+      "f7": UInt32(kVK_F7), "f8": UInt32(kVK_F8), "f9": UInt32(kVK_F9),
+      "f10": UInt32(kVK_F10), "f11": UInt32(kVK_F11), "f12": UInt32(kVK_F12),
+    ]
+
+    return keyMap[token]
+  }
+}