Add macOS Swift app source (apps/macos/ — SwiftUI menu-bar overlay + MLX sidecar)

apps/macos/Package.swift

@@ -0,0 +1,13 @@
+// swift-tools-version:5.9
+import PackageDescription
+
+let package = Package(
+    name: "BanhMi",
+    platforms: [.macOS(.v13)],
+    targets: [
+        .executableTarget(
+            name: "BanhMi",
+            path: "Sources/BanhMi"
+        )
+    ]
+)

apps/macos/README.md

@@ -0,0 +1,59 @@
+# Bánh mì chuyển ngữ — macOS App
+
+Menu bar app that captures system audio and shows live translated subtitles. Zero config — install, pick your language, forget about it.
+
+## Requirements
+
+- macOS 13 Ventura or later
+- Swift 5.9+ (ships with Xcode 15 / Command Line Tools)
+
+## Build & run
+
+```bash
+./build.sh
+open ".build/release/Bánh mì chuyển ngữ.app"
+```
+
+For debug builds:
+
+```bash
+CONFIG=debug ./build.sh
+```
+
+## Project layout
+
+```
+apps/macos/
+├── Package.swift              # Swift Package Manager manifest
+├── Sources/BanhMi/
+│   ├── main.swift             # NSApplication entry point
+│   ├── AppDelegate.swift      # Menu bar + popover wiring
+│   ├── Settings.swift         # Languages, text sizes, storage keys
+│   └── SettingsView.swift     # SwiftUI settings panel
+├── Resources/
+│   └── Info.plist             # LSUIElement = true (menu bar only, no dock)
+└── build.sh                   # Builds the .app bundle
+```
+
+## Current status (v0.2)
+
+- [x] Menu bar icon
+- [x] Click → settings popover
+- [x] Output language picker (16 languages)
+- [x] Subtitle size selector (S / M / L)
+- [x] Audio source picker (System audio / Microphone)
+- [x] Settings persist via `UserDefaults`
+- [x] Floating subtitle overlay (bottom-center, always on top, visible over fullscreen apps, click-through)
+- [x] Microphone capture (AVAudioEngine)
+- [x] System audio capture (ScreenCaptureKit)
+- [x] Live transcription via Apple Speech framework (on-device when supported)
+- [ ] Translation engine (Gemma 4 / Google Translate API)
+- [ ] Dual-language overlay (original + translation)
+
+## Permissions needed
+
+On first launch, macOS will prompt for:
+
+1. **Speech Recognition** — auto-prompt, click Allow
+2. **Screen Recording** (for system audio) — manual: System Settings → Privacy & Security → Screen Recording → enable Bánh mì chuyển ngữ, then quit & relaunch
+3. **Microphone** — only if you switch source to Microphone

apps/macos/Resources/Info.plist

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleName</key>
+    <string>Bánh mì chuyển ngữ</string>
+    <key>CFBundleDisplayName</key>
+    <string>Bánh mì chuyển ngữ</string>
+    <key>CFBundleIdentifier</key>
+    <string>vn.banhmi.chuyenngu</string>
+    <key>CFBundleExecutable</key>
+    <string>BanhMi</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.5</string>
+    <key>CFBundleVersion</key>
+    <string>5</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>13.0</string>
+    <key>LSUIElement</key>
+    <true/>
+    <key>NSHighResolutionCapable</key>
+    <true/>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Bánh mì chuyển ngữ listens to your microphone to show live transcriptions on screen.</string>
+    <key>NSScreenCaptureUsageDescription</key>
+    <string>Bánh mì chuyển ngữ captures system audio (via screen capture) to transcribe and translate what you hear.</string>
+</dict>
+</plist>

apps/macos/Sources/BanhMi/AppDelegate.swift

@@ -0,0 +1,62 @@
+import AppKit
+import SwiftUI
+
+@MainActor
+final class AppDelegate: NSObject, NSApplicationDelegate {
+    private var statusItem: NSStatusItem!
+    private var popover: NSPopover!
+    private let state = AppState.shared
+    private var overlay: SubtitleOverlayController!
+    private var controller: TranscriptionController!
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+
+        if let button = statusItem.button {
+            let image = NSImage(systemSymbolName: "waveform", accessibilityDescription: "Bánh mì chuyển ngữ")
+            image?.isTemplate = true
+            button.image = image
+            button.action = #selector(togglePopover(_:))
+            button.target = self
+        }
+
+        let rootView = SettingsView(state: state, onToggleEnabled: { [weak self] in
+            self?.toggleEnabled()
+        })
+        popover = NSPopover()
+        popover.contentSize = NSSize(width: 340, height: 520)
+        popover.behavior = .transient
+        popover.animates = true
+        popover.contentViewController = NSHostingController(rootView: rootView)
+
+        overlay = SubtitleOverlayController(state: state)
+        overlay.show()
+
+        controller = TranscriptionController(state: state)
+        Task { await controller.bootstrap() }
+    }
+
+    func applicationWillTerminate(_ notification: Notification) {
+        Task { await controller.shutdown() }
+    }
+
+    @objc private func togglePopover(_ sender: Any?) {
+        guard let button = statusItem.button else { return }
+        if popover.isShown {
+            popover.performClose(sender)
+        } else {
+            popover.show(relativeTo: button.bounds, of: button, preferredEdge: .minY)
+            popover.contentViewController?.view.window?.makeKey()
+        }
+    }
+
+    private func toggleEnabled() {
+        Task { @MainActor in
+            if state.isEnabled {
+                await controller.pause()
+            } else {
+                await controller.resume()
+            }
+        }
+    }
+}

apps/macos/Sources/BanhMi/AppState.swift

@@ -0,0 +1,283 @@
+import Foundation
+import Combine
+import AppKit
+
+/// One box of text in the overlay. A line is "live" while partials stream;
+/// once finalized it is locked and the next partials create a new line.
+struct SubtitleLine: Identifiable, Equatable {
+    let id: UUID
+    var text: String
+    var isFinal: Bool = false
+}
+
+/// Single source of truth for the running app.
+/// Views observe this, services write to it.
+@MainActor
+final class AppState: ObservableObject {
+    static let shared = AppState()
+
+    /// Maximum number of lines kept in the overlay buffer.
+    static let maxLines: Int = 3
+    /// Maximum words displayed per subtitle box. Slightly higher than the
+    /// recognizer's flush cap so translator expansion (e.g. Vietnamese often
+    /// expands vs. English) rarely triggers an extra re-split.
+    static let maxWordsPerLine: Int = 26
+    /// Short auto-hide delay for brief lines (≤ threshold words).
+    static let lineHideShortSeconds: TimeInterval = 3.0
+    /// Long auto-hide delay for longer lines (> threshold words).
+    static let lineHideLongSeconds: TimeInterval = 5.0
+    /// Word count threshold switching between short and long hide delays.
+    static let lineHideWordThreshold: Int = 10
+    /// When a new box arrives, older boxes have their remaining visible time
+    /// shortened to this value. Keeps the overlay "fresh" — old content fades
+    /// quickly once newer content pushes it up.
+    static let olderLineHideSeconds: TimeInterval = 1.2
+
+    // Accumulated raw text (for debugging/future use); the overlay does not
+    // render this directly anymore.
+    @Published var transcript: String = ""
+    /// Most recent translated text written by the translation pipeline.
+    @Published var translatedTranscript: String = ""
+
+    /// Stable lines currently shown in the overlay. New lines are appended;
+    /// old lines are removed via `expire(id:)` after their hide delay.
+    @Published private(set) var lines: [SubtitleLine] = []
+
+    @Published var isListening: Bool = false
+    @Published var isEnabled: Bool = true {
+        didSet { UserDefaults.standard.set(isEnabled, forKey: SettingsKey.isEnabled) }
+    }
+    @Published var statusMessage: String = "Starting…"
+    @Published var errorMessage: String?
+
+    /// Detected language of the incoming speech (BCP-47 base code). Nil until known.
+    @Published var detectedSourceLanguage: String?
+
+    // Persisted settings.
+    @Published var languageID: String {
+        didSet { UserDefaults.standard.set(languageID, forKey: SettingsKey.outputLanguage) }
+    }
+    @Published var textSize: TextSize {
+        didSet { UserDefaults.standard.set(textSize.rawValue, forKey: SettingsKey.textSize) }
+    }
+    @Published var audioSource: AudioSource {
+        didSet { UserDefaults.standard.set(audioSource.rawValue, forKey: SettingsKey.audioSource) }
+    }
+    @Published var asrEngine: ASREngine {
+        didSet { UserDefaults.standard.set(asrEngine.rawValue, forKey: SettingsKey.asrEngine) }
+    }
+
+    // Overlay geometry (persisted).
+    @Published var overlayWidth: CGFloat {
+        didSet { UserDefaults.standard.set(Double(overlayWidth), forKey: SettingsKey.overlayWidth) }
+    }
+    @Published var overlayOrigin: CGPoint? {
+        didSet {
+            if let p = overlayOrigin {
+                UserDefaults.standard.set(Double(p.x), forKey: SettingsKey.overlayOriginX)
+                UserDefaults.standard.set(Double(p.y), forKey: SettingsKey.overlayOriginY)
+            }
+        }
+    }
+
+    private var hideWorkByLine: [UUID: DispatchWorkItem] = [:]
+    /// Safety timer: if a live line hasn't been updated in this window, we
+    /// force-finalize it so it can fade out instead of sticking forever.
+    private var liveStaleTimer: DispatchWorkItem?
+    static let liveStaleSeconds: TimeInterval = 2.5
+
+    private init() {
+        let defaults = UserDefaults.standard
+        self.languageID = defaults.string(forKey: SettingsKey.outputLanguage) ?? SupportedLanguages.systemDefault
+        self.textSize = TextSize(rawValue: defaults.string(forKey: SettingsKey.textSize) ?? "") ?? .medium
+        self.audioSource = AudioSource(rawValue: defaults.string(forKey: SettingsKey.audioSource) ?? "") ?? .systemAudio
+        self.asrEngine = ASREngine(rawValue: defaults.string(forKey: SettingsKey.asrEngine) ?? "") ?? .gemmaMLX
+        if defaults.object(forKey: SettingsKey.isEnabled) != nil {
+            self.isEnabled = defaults.bool(forKey: SettingsKey.isEnabled)
+        } else {
+            self.isEnabled = true
+        }
+
+        let savedWidth = defaults.double(forKey: SettingsKey.overlayWidth)
+        self.overlayWidth = savedWidth > 0 ? CGFloat(savedWidth) : 900
+
+        if defaults.object(forKey: SettingsKey.overlayOriginX) != nil,
+           defaults.object(forKey: SettingsKey.overlayOriginY) != nil {
+            self.overlayOrigin = CGPoint(
+                x: defaults.double(forKey: SettingsKey.overlayOriginX),
+                y: defaults.double(forKey: SettingsKey.overlayOriginY)
+            )
+        } else {
+            self.overlayOrigin = nil
+        }
+    }
+
+    var currentLanguage: Language {
+        SupportedLanguages.named(languageID) ?? SupportedLanguages.all[0]
+    }
+
+    // MARK: - Live / finalized line management
+
+    /// Drive the overlay from streaming recognition updates.
+    /// - If there is an existing live (non-final) line, it is updated in place.
+    /// - If there isn't, a new live line is created.
+    /// - When `isFinal` is true, the last live line is locked and the next
+    ///   `showLive` call will start a new line.
+    func showLive(text: String, isFinal: Bool) {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        scheduleLiveStaleCheck()
+
+        // Split overly long text into at-most-maxWordsPerLine boxes. If the
+        // update produces multiple chunks, the last chunk is the "live" one
+        // we'll keep updating; earlier chunks are treated as finalized.
+        let chunks = Self.splitIntoChunks(trimmed, maxWords: Self.maxWordsPerLine)
+
+        // Case 1: last line is still live — either extend it or, if we've
+        // produced multiple chunks, lock it and append the new ones.
+        if let last = lines.last, last.isFinal == false {
+            if chunks.count == 1 {
+                // Update in place.
+                if lines[lines.count - 1].text != chunks[0] {
+                    lines[lines.count - 1].text = chunks[0]
+                }
+                if isFinal {
+                    lines[lines.count - 1].isFinal = true
+                    scheduleExpiry(for: lines[lines.count - 1])
+                }
+                return
+            } else {
+                // Chunks split — replace the live line with the first chunk
+                // (now final), then append the remaining chunks.
+                lines[lines.count - 1].text = chunks[0]
+                lines[lines.count - 1].isFinal = true
+                scheduleExpiry(for: lines[lines.count - 1])
+                for chunk in chunks.dropFirst() {
+                    appendNewLine(text: chunk, isFinal: isFinal)
+                }
+                return
+            }
+        }
+
+        // Case 2: no live line. Append each chunk as a new line; only the
+        // last becomes "live" (unless isFinal was requested).
+        for (idx, chunk) in chunks.enumerated() {
+            let final = isFinal || (idx < chunks.count - 1)
+            appendNewLine(text: chunk, isFinal: final)
+        }
+    }
+
+    private func appendNewLine(text: String, isFinal: Bool) {
+        // Accelerate fade on existing older lines so the new line stands out.
+        shortenOlderTimers()
+
+        let line = SubtitleLine(id: UUID(), text: text, isFinal: isFinal)
+        lines.append(line)
+        while lines.count > Self.maxLines {
+            let removed = lines.removeFirst()
+            hideWorkByLine.removeValue(forKey: removed.id)?.cancel()
+        }
+        if isFinal {
+            scheduleExpiry(for: line)
+        }
+        // Non-final lines don't schedule expiry yet; they get one when finalized.
+    }
+
+    /// Append a finalized utterance as one or more new boxes. Kept for
+    /// backwards compatibility; callers should prefer `showLive`.
+    func appendLine(_ text: String) {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+
+        let chunks = Self.splitIntoChunks(trimmed, maxWords: Self.maxWordsPerLine)
+        for chunk in chunks {
+            if let last = lines.last, last.text == chunk { continue }
+            // Before appending a new box, accelerate the fade-out of every
+            // existing box so stale content doesn't linger behind fresh text.
+            shortenOlderTimers()
+
+            let line = SubtitleLine(id: UUID(), text: chunk)
+            lines.append(line)
+            while lines.count > Self.maxLines {
+                let removed = lines.removeFirst()
+                hideWorkByLine.removeValue(forKey: removed.id)?.cancel()
+            }
+            scheduleExpiry(for: line)
+        }
+    }
+
+    /// Replace any pending hide timer on existing lines with a short one so
+    /// older boxes fade out quickly once a newer one arrives.
+    private func shortenOlderTimers() {
+        for existing in lines {
+            hideWorkByLine.removeValue(forKey: existing.id)?.cancel()
+            let work = DispatchWorkItem { [weak self] in
+                Task { @MainActor in self?.expire(id: existing.id) }
+            }
+            hideWorkByLine[existing.id] = work
+            DispatchQueue.main.asyncAfter(
+                deadline: .now() + Self.olderLineHideSeconds,
+                execute: work
+            )
+        }
+    }
+
+    /// Split text into successive chunks of at most `maxWords` whitespace-
+    /// separated words. Preserves original word order.
+    private static func splitIntoChunks(_ text: String, maxWords: Int) -> [String] {
+        let words = text.split(whereSeparator: { $0.isWhitespace }).map(String.init)
+        guard words.count > maxWords else { return [text] }
+        var chunks: [String] = []
+        var i = 0
+        while i < words.count {
+            let end = min(i + maxWords, words.count)
+            chunks.append(words[i..<end].joined(separator: " "))
+            i = end
+        }
+        return chunks
+    }
+
+    /// Remove all lines and cancel pending timers. Used on pause/stop.
+    func clearLines() {
+        hideWorkByLine.values.forEach { $0.cancel() }
+        hideWorkByLine.removeAll()
+        liveStaleTimer?.cancel()
+        liveStaleTimer = nil
+        lines.removeAll()
+    }
+
+    /// (Re)start the watchdog that force-finalizes a live line that stops
+    /// getting updates, so it can fade out instead of staying forever.
+    private func scheduleLiveStaleCheck() {
+        liveStaleTimer?.cancel()
+        let work = DispatchWorkItem { [weak self] in
+            Task { @MainActor in self?.forceFinalizeLive() }
+        }
+        liveStaleTimer = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + Self.liveStaleSeconds, execute: work)
+    }
+
+    private func forceFinalizeLive() {
+        guard let last = lines.last, last.isFinal == false else { return }
+        lines[lines.count - 1].isFinal = true
+        scheduleExpiry(for: lines[lines.count - 1])
+    }
+
+    private func scheduleExpiry(for line: SubtitleLine) {
+        let words = line.text.split(whereSeparator: { $0.isWhitespace }).count
+        let delay: TimeInterval = words > Self.lineHideWordThreshold
+            ? Self.lineHideLongSeconds
+            : Self.lineHideShortSeconds
+
+        let work = DispatchWorkItem { [weak self] in
+            Task { @MainActor in self?.expire(id: line.id) }
+        }
+        hideWorkByLine[line.id] = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
+    }
+
+    private func expire(id: UUID) {
+        hideWorkByLine.removeValue(forKey: id)
+        lines.removeAll { $0.id == id }
+    }
+}

apps/macos/Sources/BanhMi/BanhMiMain.swift

@@ -0,0 +1,17 @@
+import AppKit
+
+@main
+struct BanhMiMain {
+    static func main() {
+        MainActor.assumeIsolated {
+            // Start the session logger early so we capture everything.
+            _ = SessionLogger.shared
+
+            let app = NSApplication.shared
+            let delegate = AppDelegate()
+            app.delegate = delegate
+            app.setActivationPolicy(.accessory)
+            app.run()
+        }
+    }
+}

apps/macos/Sources/BanhMi/GemmaMLXRecognizer.swift

@@ -0,0 +1,471 @@
+import Foundation
+@preconcurrency import AVFoundation
+import OSLog
+
+private let recLog = Logger(subsystem: "vn.banhmi.chuyenngu", category: "gemma-mlx")
+
+/// Offline speech recognition + translation via the Gemma 4 MLX sidecar.
+/// Conforms to the `AudioRecognizer` protocol so `TranscriptionController`
+/// can drive it the same way as any future engine.
+///
+/// Gemma's audio tower is encoder-based — it needs the full clip at once,
+/// so this isn't true streaming. We accumulate audio with an energy-based
+/// VAD and run inference once per detected utterance.
+@MainActor
+final class GemmaMLXRecognizer {
+    // Callbacks (AudioRecognizer surface)
+    var onStableUpdate: ((String, Bool, String?) -> Void)?
+    var onFinalUtterance: ((String, String?) -> Void)?
+    var onFinal: (() -> Void)?
+    var onError: ((Error) -> Void)?
+
+    private(set) var latestDetectedLanguage: String?
+
+    // VAD chunking — cut audio on speech boundaries rather than fixed windows
+    // so Gemma always sees complete utterances.
+    static let sampleRate: Double = 16_000
+    static let frameDurationSec: TimeInterval = 0.03            // 30 ms frames
+    static let minSpeechSec: TimeInterval = 0.6                 // drop sub-600ms utterances
+    static let maxSpeechSec: TimeInterval = 8.0                 // force flush after 8s
+    static let trailingSilenceSec: TimeInterval = 0.35          // silence that ends an utterance
+    static let speechActivationSec: TimeInterval = 0.15         // 150ms of voice to start a segment
+
+    /// Hysteresis thresholds for voice activity detection.
+    ///
+    /// A frame counts as voice only if its RMS is above `voiceActivateRMS`
+    /// (clear speech energy, not ambient room noise). A frame counts as
+    /// silence only if its RMS drops below `voiceDeactivateRMS`. Frames in
+    /// between leave the VAD state unchanged, which is what lets us span
+    /// brief quiet moments inside a word without losing speech context.
+    static let voiceActivateRMS: Float = 0.005     // >= this → voice
+    static let voiceDeactivateRMS: Float = 0.0015  // <  this → silence
+    /// Minimum overall chunk RMS — below this we skip the whole utterance
+    /// (pure noise / mic tap). Evaluated on the chunk before peak normalize.
+    static let silenceRMSThreshold: Float = 0.001
+
+    private let service: GemmaMLXService
+    private var targetLanguageName: String = "English"
+
+    // Audio conversion to 16 kHz int16 mono
+    private let desiredFormat: AVAudioFormat
+    private var converter: AVAudioConverter?
+    private var converterInputFormat: AVAudioFormat?
+
+    // VAD state machine
+    private var pcmBuffer = Data()           // all audio since start of current utterance (or since last flush)
+    private var isRunning = false
+    private var inFlight = false
+    private var inSpeech = false
+    private var speechRunSec: TimeInterval = 0    // accumulated voice-frames at start of utterance
+    private var silenceRunSec: TimeInterval = 0   // consecutive silence since last voice frame
+    private var utteranceSec: TimeInterval = 0    // length of current utterance
+
+    /// A queued or in-flight utterance with enough metadata to log metrics
+    /// and attach the saved WAV for offline review.
+    private struct PendingUtterance {
+        let pcm: Data
+        let rmsIn: Float
+        let rmsOut: Float
+        let durationSec: Double
+    }
+
+    /// Queue of preprocessed utterances waiting for Gemma. Keeping this
+    /// small — if the user speaks faster than the model, we drop the
+    /// *oldest* pending entry to keep overlay text fresh instead of lagging.
+    private var queue: [PendingUtterance] = []
+    private static let maxQueueDepth = 2
+
+    init(sidecarScriptPath: String,
+         pythonPath: String = "/usr/bin/env",
+         modelID: String = "unsloth/gemma-4-E2B-it-UD-MLX-4bit") throws {
+        self.desiredFormat = AVAudioFormat(
+            commonFormat: .pcmFormatInt16,
+            sampleRate: 16_000,
+            channels: 1,
+            interleaved: true
+        )!
+        // `/usr/bin/env python3 <script>` is the simplest launch that works with
+        // any user's python3 (venv, system, homebrew, etc).
+        self.service = try GemmaMLXService(
+            pythonPath: pythonPath == "/usr/bin/env" ? "/usr/bin/env" : pythonPath,
+            sidecarScript: sidecarScriptPath,
+            modelID: modelID
+        )
+    }
+
+    /// Configure target language. Source language is always auto-detected by
+    /// the model — hints are ignored here.
+    func configure(sourceLocale: Locale,
+                   targetLanguageCode: String,
+                   context: String = "") throws {
+        targetLanguageName = Self.targetLanguageName(from: targetLanguageCode)
+    }
+
+    /// Start processing. Waits until the sidecar has loaded the MLX model.
+    func startTask() throws {
+        guard !isRunning else { return }
+        isRunning = true
+        pcmBuffer.removeAll(keepingCapacity: true)
+        // Wait for sidecar ready asynchronously — don't block the caller.
+        Task { [weak self] in
+            do {
+                try await self?.service.waitUntilReady()
+            } catch {
+                self?.onError?(error)
+            }
+        }
+    }
+
+    func stop() {
+        isRunning = false
+        pcmBuffer.removeAll(keepingCapacity: false)
+        inSpeech = false
+        speechRunSec = 0
+        silenceRunSec = 0
+        utteranceSec = 0
+        queue.removeAll(keepingCapacity: false)
+        service.stop()
+    }
+
+    /// Feed an audio buffer. Converts to 16 kHz int16 mono, runs
+    /// energy-based VAD, and flushes a chunk to Gemma when we see a
+    /// complete utterance (voice + trailing silence, or hit max length).
+    func append(_ buffer: AVAudioPCMBuffer) {
+        guard isRunning else { return }
+        guard let int16Data = convertToInt16Mono16k(buffer), !int16Data.isEmpty else {
+            return
+        }
+        appendConverted(int16Data)
+    }
+
+    private func appendConverted(_ int16Data: Data) {
+        // Frame-based VAD walks the incoming int16 in 30ms frames.
+        let sr = Int(Self.sampleRate)
+        let frameSamples = Int(Double(sr) * Self.frameDurationSec)   // 480 @ 16kHz
+        let frameBytes = frameSamples * 2
+
+        // Keep a local working buffer so we can add frame-by-frame to pcmBuffer.
+        var remaining = int16Data
+        while remaining.count >= frameBytes {
+            let frame = remaining.prefix(frameBytes)
+            remaining.removeSubrange(remaining.startIndex..<remaining.index(remaining.startIndex, offsetBy: frameBytes))
+
+            let frameRMS = Self.chunkRMS(Data(frame))
+            // Hysteresis: voice frames must cross the higher activation bar;
+            // silence frames must drop below the lower deactivation bar.
+            // Ambient noise in between does nothing — it neither starts nor
+            // ends an utterance, which prevents the VAD from being stuck.
+            let isVoice = frameRMS >= Self.voiceActivateRMS
+            let isSilence = frameRMS < Self.voiceDeactivateRMS
+
+            if !inSpeech {
+                // Waiting for enough clear voice to start a new utterance.
+                if isVoice {
+                    speechRunSec += Self.frameDurationSec
+                    pcmBuffer.append(frame)
+                    if speechRunSec >= Self.speechActivationSec {
+                        inSpeech = true
+                        utteranceSec = speechRunSec
+                        silenceRunSec = 0
+                    }
+                } else {
+                    // Drop: no speech started yet.
+                    speechRunSec = 0
+                    pcmBuffer.removeAll(keepingCapacity: true)
+                }
+                continue
+            }
+
+            // inSpeech == true — we're mid-utterance. Keep accumulating.
+            pcmBuffer.append(frame)
+            utteranceSec += Self.frameDurationSec
+
+            if isVoice {
+                silenceRunSec = 0
+            } else if isSilence {
+                silenceRunSec += Self.frameDurationSec
+            }
+            // else: ambient (in-between) — keep existing silenceRunSec
+
+            let shouldFlush =
+                (silenceRunSec >= Self.trailingSilenceSec && utteranceSec >= Self.minSpeechSec) ||
+                (utteranceSec >= Self.maxSpeechSec)
+
+            if shouldFlush {
+                flushCurrentUtterance()
+            }
+        }
+    }
+
+    private func flushCurrentUtterance() {
+        let chunk = pcmBuffer
+        // Reset state so we can start a new utterance immediately.
+        pcmBuffer.removeAll(keepingCapacity: true)
+        inSpeech = false
+        speechRunSec = 0
+        silenceRunSec = 0
+        utteranceSec = 0
+
+        let rmsIn = Self.chunkRMS(chunk)
+        if rmsIn < Self.silenceRMSThreshold {
+            recLog.info("VAD flush: utterance too quiet (rms=\(rmsIn, format: .fixed(precision: 4))) — dropping")
+            return
+        }
+
+        let normalized = Self.preprocessForASR(chunk)
+        let rmsOut = Self.chunkRMS(normalized)
+        let durSec = Double(chunk.count / 2) / Self.sampleRate
+        recLog.info("VAD flush: utterance \(durSec, format: .fixed(precision: 2))s, rms_in=\(rmsIn, format: .fixed(precision: 4)) rms_out=\(rmsOut, format: .fixed(precision: 4))")
+
+        let pending = PendingUtterance(
+            pcm: normalized, rmsIn: rmsIn, rmsOut: rmsOut, durationSec: durSec,
+        )
+
+        if inFlight {
+            while queue.count >= Self.maxQueueDepth {
+                queue.removeFirst()
+                recLog.info("Queue full — dropping oldest pending utterance")
+            }
+            queue.append(pending)
+            return
+        }
+
+        inFlight = true
+        Task { [weak self] in
+            await self?.runInference(pending)
+        }
+    }
+
+    /// Kick off the next queued utterance once the current call returns.
+    private func drainQueue() {
+        guard !queue.isEmpty, !inFlight, isRunning else { return }
+        let next = queue.removeFirst()
+        inFlight = true
+        Task { [weak self] in
+            await self?.runInference(next)
+        }
+    }
+
+    // MARK: - Private
+
+    private func runInference(_ pending: PendingUtterance) async {
+        defer {
+            Task { @MainActor [weak self] in
+                self?.inFlight = false
+                self?.drainQueue()
+            }
+        }
+        do {
+            // Single-pass translate: half the inference time of
+            // transcribe_translate because Gemma is only prompted once.
+            // The overlay only ever shows translated text anyway.
+            let result = try await service.translate(
+                pcm16: pending.pcm,
+                sampleRate: 16_000,
+                targetLanguage: targetLanguageName
+            )
+            recLog.info("Sidecar returned: source=\"\(result.sourceText)\" translated=\"\(result.translatedText)\" latency=\(result.latencyMs)ms")
+            await MainActor.run { [weak self] in
+                guard let self else { return }
+                SessionLogger.shared.record(
+                    pcm16: pending.pcm,
+                    sampleRate: 16_000,
+                    rmsIn: pending.rmsIn,
+                    rmsOut: pending.rmsOut,
+                    durationSec: pending.durationSec,
+                    latencyMs: result.latencyMs,
+                    sourceText: result.sourceText,
+                    translatedText: result.translatedText,
+                    targetLang: self.targetLanguageName,
+                    engine: "gemma_mlx"
+                )
+                guard self.isRunning else { return }
+                let out = result.translatedText.isEmpty
+                    ? result.sourceText
+                    : result.translatedText
+                guard !out.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                    return
+                }
+                self.onStableUpdate?(out, true, self.latestDetectedLanguage)
+                self.onFinalUtterance?(out, self.latestDetectedLanguage)
+            }
+        } catch {
+            recLog.error("Sidecar call failed: \(String(describing: error))")
+            await MainActor.run { [weak self] in
+                guard let self else { return }
+                SessionLogger.shared.record(
+                    pcm16: pending.pcm,
+                    sampleRate: 16_000,
+                    rmsIn: pending.rmsIn,
+                    rmsOut: pending.rmsOut,
+                    durationSec: pending.durationSec,
+                    latencyMs: nil,
+                    sourceText: nil,
+                    translatedText: nil,
+                    targetLang: self.targetLanguageName,
+                    engine: "gemma_mlx",
+                    error: String(describing: error)
+                )
+                self.onError?(error)
+            }
+        }
+    }
+
+    /// Minimal ASR preprocessing for Gemma 4: DC removal + peak normalize.
+    ///
+    /// Notes on what we deliberately DON'T do:
+    ///   - No pre-emphasis: Gemma 4's USM Conformer audio tower operates on
+    ///     raw waveforms, not MFCC-style features. Pre-emphasis distorts the
+    ///     waveform's character enough that the model's language detector
+    ///     mis-identifies the input (e.g. English → "Korean").
+    ///   - No high-pass filter: would help classic ASR but here it sculpts
+    ///     formants the model uses and hurts accuracy.
+    /// The safe, minimal pipeline just centres the waveform and scales it
+    /// up so the model sees usable dynamic range.
+    private static func preprocessForASR(_ pcm: Data) -> Data {
+        guard pcm.count >= 4 else { return pcm }
+        let sampleCount = pcm.count / 2
+
+        // Decode to float
+        var samples = [Float](repeating: 0, count: sampleCount)
+        pcm.withUnsafeBytes { raw in
+            let ins = raw.bindMemory(to: Int16.self)
+            let scale = Float(1.0 / Float(Int16.max))
+            for i in 0..<sampleCount {
+                samples[i] = Float(ins[i]) * scale
+            }
+        }
+
+        // DC offset removal
+        var mean: Float = 0
+        for s in samples { mean += s }
+        mean /= Float(sampleCount)
+        if abs(mean) > 1e-5 {
+            for i in 0..<sampleCount { samples[i] -= mean }
+        }
+
+        // Peak normalize (target 0.85, cap gain to avoid amplifying noise)
+        var peak: Float = 0
+        for s in samples { peak = max(peak, abs(s)) }
+        if peak > 0 {
+            let target: Float = 0.85
+            let gain = min(target / peak, 30.0)
+            if gain > 1.0 {
+                for i in 0..<sampleCount { samples[i] *= gain }
+            }
+        }
+
+        // Re-encode to int16
+        var out = Data(count: pcm.count)
+        out.withUnsafeMutableBytes { outRaw in
+            let outs = outRaw.bindMemory(to: Int16.self)
+            for i in 0..<sampleCount {
+                let v = samples[i] * Float(Int16.max)
+                outs[i] = Int16(clamping: Int(v.rounded()))
+            }
+        }
+        return out
+    }
+
+    /// Peak-normalize int16 PCM so the loudest sample hits ~0.85 of full
+    /// scale. Leaves a small headroom to avoid clipping on transients.
+    /// Caps gain at 30x to prevent amplifying noise when there's no speech.
+    private static func peakNormalize(_ pcm: Data) -> Data {
+        guard pcm.count >= 2 else { return pcm }
+        let sampleCount = pcm.count / 2
+        var peak: Int16 = 0
+        pcm.withUnsafeBytes { raw in
+            let samples = raw.bindMemory(to: Int16.self)
+            for i in 0..<sampleCount {
+                let a = samples[i] == Int16.min ? Int16.max : abs(samples[i])
+                if a > peak { peak = a }
+            }
+        }
+        if peak == 0 { return pcm }
+        let targetPeak: Float = 0.85 * Float(Int16.max)
+        let rawGain = targetPeak / Float(peak)
+        let gain = min(rawGain, 30.0)  // cap to avoid blowing up noise
+        if gain <= 1.05 { return pcm }  // already loud enough
+
+        var out = Data(count: pcm.count)
+        out.withUnsafeMutableBytes { outRaw in
+            let outSamples = outRaw.bindMemory(to: Int16.self)
+            pcm.withUnsafeBytes { raw in
+                let inSamples = raw.bindMemory(to: Int16.self)
+                for i in 0..<sampleCount {
+                    let scaled = Float(inSamples[i]) * gain
+                    outSamples[i] = Int16(clamping: Int(scaled.rounded()))
+                }
+            }
+        }
+        return out
+    }
+
+    /// RMS amplitude of a chunk in [0, 1] range (int16 normalized to float).
+    private static func chunkRMS(_ pcm: Data) -> Float {
+        guard pcm.count >= 2 else { return 0 }
+        let sampleCount = pcm.count / 2
+        var sumSq: Double = 0
+        pcm.withUnsafeBytes { raw in
+            let samples = raw.bindMemory(to: Int16.self)
+            for i in 0..<sampleCount {
+                let s = Double(samples[i]) / Double(Int16.max)
+                sumSq += s * s
+            }
+        }
+        return Float(sqrt(sumSq / Double(sampleCount)))
+    }
+
+    /// Map a BCP-47 code (e.g. "vi", "zh-CN") to the English language name
+    /// Gemma expects in prompts.
+    private static func targetLanguageName(from code: String) -> String {
+        let lower = code.lowercased()
+        let table: [String: String] = [
+            "en": "English", "vi": "Vietnamese", "es": "Spanish",
+            "zh": "Chinese", "zh-cn": "Chinese", "zh-tw": "Chinese",
+            "ja": "Japanese", "ko": "Korean", "fr": "French",
+            "de": "German", "pt": "Portuguese", "ru": "Russian",
+            "ar": "Arabic", "hi": "Hindi", "id": "Indonesian",
+            "th": "Thai", "it": "Italian", "tr": "Turkish",
+        ]
+        if let name = table[lower] { return name }
+        let base = lower.split(separator: "-").first.map(String.init) ?? lower
+        return table[base] ?? "English"
+    }
+
+    private func convertToInt16Mono16k(_ buffer: AVAudioPCMBuffer) -> Data? {
+        let inputFormat = buffer.format
+        if converter == nil || converterInputFormat != inputFormat {
+            converter = AVAudioConverter(from: inputFormat, to: desiredFormat)
+            converterInputFormat = inputFormat
+            guard converter != nil else { return nil }
+        }
+        guard let converter else { return nil }
+
+        let capacity = AVAudioFrameCount(
+            Double(buffer.frameLength) *
+            desiredFormat.sampleRate / inputFormat.sampleRate
+        ) + 1024
+        guard let out = AVAudioPCMBuffer(
+            pcmFormat: desiredFormat, frameCapacity: capacity
+        ) else { return nil }
+
+        var submitted = false
+        let inputBlock: AVAudioConverterInputBlock = { _, status in
+            if submitted {
+                status.pointee = .noDataNow
+                return nil
+            }
+            submitted = true
+            status.pointee = .haveData
+            return buffer
+        }
+        var error: NSError?
+        let s = converter.convert(to: out, error: &error, withInputFrom: inputBlock)
+        if s == .error || error != nil { return nil }
+
+        guard let data = out.int16ChannelData?.pointee else { return nil }
+        let byteCount = Int(out.frameLength) * 2
+        return Data(bytes: data, count: byteCount)
+    }
+}

apps/macos/Sources/BanhMi/GemmaMLXService.swift

@@ -0,0 +1,271 @@
+import Foundation
+import AVFoundation
+
+/// Bridges the Swift app to the Python MLX sidecar process that runs
+/// Gemma 4 E2B UD-MLX-4bit locally on Apple Silicon. The sidecar loads
+/// the model once at startup; each request is a JSON line over stdin
+/// and a JSON line back over stdout.
+///
+/// Not a `TranslationService` — the sidecar takes *audio* in and emits
+/// transcript + translation, fully offline on-device.
+final class GemmaMLXService {
+    struct Result: Sendable {
+        let sourceText: String
+        let translatedText: String
+        let latencyMs: Int
+    }
+
+    enum ServiceError: Error, CustomStringConvertible {
+        case pythonNotFound
+        case sidecarScriptMissing(String)
+        case processNotStarted
+        case sidecarFailed(String)
+        case invalidResponse(String)
+
+        var description: String {
+            switch self {
+            case .pythonNotFound: return "python3 not found on PATH"
+            case .sidecarScriptMissing(let p): return "sidecar script missing: \(p)"
+            case .processNotStarted: return "sidecar process failed to start"
+            case .sidecarFailed(let msg): return "sidecar error: \(msg)"
+            case .invalidResponse(let s): return "sidecar invalid response: \(s)"
+            }
+        }
+    }
+
+    private let process: Process
+    private let stdinPipe = Pipe()
+    private let stdoutPipe = Pipe()
+    private let stderrPipe = Pipe()
+    private let readQueue = DispatchQueue(label: "gemma-mlx-read")
+    private let writeQueue = DispatchQueue(label: "gemma-mlx-write")
+    private var buffer = Data()
+    private var pendingResponses: [CheckedContinuation<String, Error>] = []
+    private let pendingLock = NSLock()
+
+    /// Creates and starts the sidecar process. The model loads lazily
+    /// inside the Python process — callers should await `waitUntilReady()`
+    /// before sending real work.
+    init(
+        pythonPath: String,
+        sidecarScript: String,
+        modelID: String = "unsloth/gemma-4-E2B-it-UD-MLX-4bit"
+    ) throws {
+        guard FileManager.default.fileExists(atPath: sidecarScript) else {
+            throw ServiceError.sidecarScriptMissing(sidecarScript)
+        }
+
+        process = Process()
+        process.executableURL = URL(fileURLWithPath: pythonPath)
+        if pythonPath.hasSuffix("/env") {
+            // `/usr/bin/env python3 <script>` — python3 must be first arg
+            process.arguments = ["python3", sidecarScript]
+        } else {
+            // Direct python3 binary — script is first arg
+            process.arguments = [sidecarScript]
+        }
+        process.standardInput = stdinPipe
+        process.standardOutput = stdoutPipe
+        process.standardError = stderrPipe
+
+        var env = ProcessInfo.processInfo.environment
+        env["GEMMA_MLX_MODEL"] = modelID
+        env["PYTHONUNBUFFERED"] = "1"
+        process.environment = env
+
+        try process.run()
+
+        // Read stdout continuously on a background queue
+        stdoutPipe.fileHandleForReading.readabilityHandler = { [weak self] h in
+            self?.handleStdoutChunk(h.availableData)
+        }
+        // Forward stderr to Console so we can see sidecar errors / progress
+        stderrPipe.fileHandleForReading.readabilityHandler = { h in
+            let data = h.availableData
+            guard !data.isEmpty,
+                  let s = String(data: data, encoding: .utf8) else { return }
+            let trimmed = s.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !trimmed.isEmpty {
+                NSLog("[gemma_sidecar] %@", trimmed)
+            }
+        }
+    }
+
+    deinit {
+        stop()
+    }
+
+    func stop() {
+        stdoutPipe.fileHandleForReading.readabilityHandler = nil
+        stderrPipe.fileHandleForReading.readabilityHandler = nil
+        if process.isRunning {
+            process.terminate()
+        }
+    }
+
+    /// Awaits the sidecar's first JSON line, which carries `{"event":"ready"}`.
+    func waitUntilReady() async throws {
+        let line = try await readNextLine()
+        guard let data = line.data(using: .utf8),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              obj["event"] as? String == "ready" else {
+            throw ServiceError.invalidResponse(line)
+        }
+    }
+
+    /// Writes an audio clip (int16 PCM or float32) to a temp WAV and
+    /// sends a transcribe+translate request. Returns both source and
+    /// translated text.
+    func transcribeAndTranslate(
+        audioFileURL: URL,
+        targetLanguage: String
+    ) async throws -> Result {
+        let req: [String: Any] = [
+            "task": "transcribe_translate",
+            "audio_path": audioFileURL.path,
+            "target_lang": targetLanguage,
+        ]
+        return try await send(req)
+    }
+
+    /// Convenience: writes an in-memory sample buffer to a temp WAV and
+    /// processes it. Caller owns the lifetime of the buffer data.
+    func transcribeAndTranslate(
+        pcm16: Data,
+        sampleRate: Double,
+        targetLanguage: String
+    ) async throws -> Result {
+        let url = try writeTempWAV(pcm16: pcm16, sampleRate: sampleRate)
+        defer { try? FileManager.default.removeItem(at: url) }
+        return try await transcribeAndTranslate(
+            audioFileURL: url, targetLanguage: targetLanguage,
+        )
+    }
+
+    /// Single-pass translate. Half the inference cost of
+    /// transcribe_translate because Gemma is only prompted once. Returns
+    /// only translated text — sourceText is empty.
+    func translate(
+        pcm16: Data,
+        sampleRate: Double,
+        targetLanguage: String
+    ) async throws -> Result {
+        let url = try writeTempWAV(pcm16: pcm16, sampleRate: sampleRate)
+        defer { try? FileManager.default.removeItem(at: url) }
+        let req: [String: Any] = [
+            "task": "translate",
+            "audio_path": url.path,
+            "target_lang": targetLanguage,
+        ]
+        return try await send(req)
+    }
+
+    // MARK: - Private
+
+    private func send(_ request: [String: Any]) async throws -> Result {
+        let data = try JSONSerialization.data(withJSONObject: request, options: [])
+        // Write request + newline
+        writeQueue.async { [weak self] in
+            guard let self else { return }
+            self.stdinPipe.fileHandleForWriting.write(data)
+            self.stdinPipe.fileHandleForWriting.write("\n".data(using: .utf8)!)
+        }
+        let responseLine = try await readNextLine()
+        guard let respData = responseLine.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: respData) as? [String: Any] else {
+            throw ServiceError.invalidResponse(responseLine)
+        }
+        if let ok = json["ok"] as? Bool, ok == false {
+            let msg = json["error"] as? String ?? "unknown"
+            throw ServiceError.sidecarFailed(msg)
+        }
+        let source = (json["source_text"] as? String) ?? ""
+        let translated = (json["translated_text"] as? String) ?? ""
+        let latency = (json["latency_ms"] as? Int) ?? 0
+        return Result(
+            sourceText: source,
+            translatedText: translated,
+            latencyMs: latency,
+        )
+    }
+
+    private func readNextLine() async throws -> String {
+        try await withCheckedThrowingContinuation { cont in
+            pendingLock.lock()
+            pendingResponses.append(cont)
+            pendingLock.unlock()
+            drainBuffer()
+        }
+    }
+
+    private func handleStdoutChunk(_ chunk: Data) {
+        guard !chunk.isEmpty else { return }
+        readQueue.async { [weak self] in
+            guard let self else { return }
+            self.buffer.append(chunk)
+            self.drainBuffer()
+        }
+    }
+
+    private func drainBuffer() {
+        readQueue.async { [weak self] in
+            guard let self else { return }
+            let newline: UInt8 = 0x0A
+            while let idx = self.buffer.firstIndex(of: newline) {
+                let lineData = self.buffer.prefix(upTo: idx)
+                self.buffer.removeSubrange(self.buffer.startIndex...idx)
+                let line = String(data: lineData, encoding: .utf8) ?? ""
+
+                self.pendingLock.lock()
+                let cont = self.pendingResponses.isEmpty
+                    ? nil
+                    : self.pendingResponses.removeFirst()
+                self.pendingLock.unlock()
+
+                cont?.resume(returning: line)
+            }
+        }
+    }
+
+    /// Writes 16-bit PCM samples to a minimal WAV file. Mono assumed.
+    private func writeTempWAV(pcm16: Data, sampleRate: Double) throws -> URL {
+        let tmpDir = FileManager.default.temporaryDirectory
+        let url = tmpDir.appendingPathComponent(
+            "banhmi-\(UUID().uuidString).wav"
+        )
+
+        var header = Data()
+        let dataSize = UInt32(pcm16.count)
+        let byteRate = UInt32(sampleRate) * 2  // 16-bit mono
+        let blockAlign: UInt16 = 2
+
+        header.append("RIFF".data(using: .ascii)!)
+        header.append(uint32LE(36 + dataSize))
+        header.append("WAVE".data(using: .ascii)!)
+        header.append("fmt ".data(using: .ascii)!)
+        header.append(uint32LE(16))               // Subchunk1Size
+        header.append(uint16LE(1))                // PCM
+        header.append(uint16LE(1))                // mono
+        header.append(uint32LE(UInt32(sampleRate)))
+        header.append(uint32LE(byteRate))
+        header.append(uint16LE(blockAlign))
+        header.append(uint16LE(16))               // bits per sample
+        header.append("data".data(using: .ascii)!)
+        header.append(uint32LE(dataSize))
+
+        var out = header
+        out.append(pcm16)
+        try out.write(to: url)
+        return url
+    }
+
+    private func uint16LE(_ v: UInt16) -> Data {
+        var le = v.littleEndian
+        return Data(bytes: &le, count: 2)
+    }
+
+    private func uint32LE(_ v: UInt32) -> Data {
+        var le = v.littleEndian
+        return Data(bytes: &le, count: 4)
+    }
+}

apps/macos/Sources/BanhMi/MicrophoneCapture.swift

@@ -0,0 +1,45 @@
+import Foundation
+import AVFoundation
+
+/// Captures audio from the default input device (microphone).
+/// Emits `AVAudioPCMBuffer`s on a background queue via `onBuffer`.
+final class MicrophoneCapture {
+    private let engine = AVAudioEngine()
+    private(set) var isRunning = false
+
+    var onBuffer: ((AVAudioPCMBuffer, AVAudioTime) -> Void)?
+
+    func start() throws {
+        guard !isRunning else { return }
+
+        let input = engine.inputNode
+        let format = input.outputFormat(forBus: 0)
+
+        input.installTap(onBus: 0, bufferSize: 1024, format: format) { [weak self] buffer, when in
+            self?.onBuffer?(buffer, when)
+        }
+
+        engine.prepare()
+        try engine.start()
+        isRunning = true
+    }
+
+    func stop() {
+        guard isRunning else { return }
+        engine.inputNode.removeTap(onBus: 0)
+        engine.stop()
+        isRunning = false
+    }
+
+    static func requestPermission() async -> Bool {
+        await withCheckedContinuation { continuation in
+            AVCaptureDevice.requestAccess(for: .audio) { granted in
+                continuation.resume(returning: granted)
+            }
+        }
+    }
+
+    static var hasPermission: Bool {
+        AVCaptureDevice.authorizationStatus(for: .audio) == .authorized
+    }
+}

apps/macos/Sources/BanhMi/SessionLogger.swift

@@ -0,0 +1,186 @@
+import Foundation
+import OSLog
+
+/// Per-session logger. Each time the app launches we start a new session
+/// directory under `~/Library/Logs/BanhMi/session-<timestamp>/` that holds:
+///   - `session.jsonl`  — one line per utterance with timing + transcripts
+///   - `utt-NNN.wav`    — the exact audio we sent to Gemma (post-preprocess)
+///
+/// Call `record(...)` from the recognizer once per model round-trip.
+/// Open the folder from the Settings popover to review a run.
+@MainActor
+final class SessionLogger {
+    static let shared = SessionLogger()
+
+    private let log = Logger(subsystem: "vn.banhmi.chuyenngu", category: "session-log")
+    private let queue = DispatchQueue(label: "session-logger", qos: .utility)
+    private let fm = FileManager.default
+    private let sessionDir: URL
+    private let jsonlURL: URL
+    private var utteranceIndex: Int = 0
+    private var isoFormatter: ISO8601DateFormatter = {
+        let f = ISO8601DateFormatter()
+        f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return f
+    }()
+
+    private init() {
+        // ~/Library/Logs/BanhMi/session-2026-04-22T00-05-12Z/
+        let libraryLogs = fm.urls(for: .libraryDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("Logs")
+            .appendingPathComponent("BanhMi")
+        let ts = Self.timestampSlug(Date())
+        sessionDir = libraryLogs.appendingPathComponent("session-\(ts)")
+        jsonlURL = sessionDir.appendingPathComponent("session.jsonl")
+
+        try? fm.createDirectory(at: sessionDir, withIntermediateDirectories: true)
+        // Write a tiny header line so jq can read it too
+        let header: [String: Any] = [
+            "event": "session_start",
+            "ts": isoFormatter.string(from: Date()),
+            "session_dir": sessionDir.path,
+        ]
+        appendJSON(header)
+        log.info("Session log: \(self.sessionDir.path, privacy: .public)")
+    }
+
+    /// Open this session's folder in Finder. Safe to call from the UI.
+    func revealInFinder() {
+        NSWorkspace.shared.open(sessionDir)
+    }
+
+    var sessionDirectory: URL { sessionDir }
+
+    /// Record one utterance round-trip.
+    /// - Parameters:
+    ///   - pcm16: the exact int16 PCM we sent to Gemma (post-preprocess)
+    ///   - sampleRate: audio sample rate (typically 16000)
+    ///   - rmsIn:  RMS of the raw utterance before preprocessing
+    ///   - rmsOut: RMS after preprocessing
+    ///   - durationSec: utterance length
+    ///   - latencyMs: sidecar round-trip time
+    ///   - sourceText: transcript Gemma returned
+    ///   - translatedText: translation Gemma returned (may equal source)
+    ///   - targetLang: target language name
+    ///   - error: non-nil if the call failed
+    func record(
+        pcm16: Data,
+        sampleRate: Double,
+        rmsIn: Float,
+        rmsOut: Float,
+        durationSec: Double,
+        latencyMs: Int?,
+        sourceText: String?,
+        translatedText: String?,
+        targetLang: String,
+        engine: String,
+        error: String? = nil
+    ) {
+        // Snapshot state that needs MainActor access before jumping queues
+        let index = utteranceIndex
+        utteranceIndex += 1
+
+        let nowStr = isoFormatter.string(from: Date())
+        let wavName = String(format: "utt-%04d.wav", index)
+        let wavURL = sessionDir.appendingPathComponent(wavName)
+
+        queue.async { [weak self] in
+            guard let self else { return }
+            // Write WAV
+            Self.writeWAV(pcm16: pcm16, sampleRate: sampleRate, to: wavURL)
+
+            // Write JSONL entry
+            var entry: [String: Any] = [
+                "event": "utterance",
+                "ts": nowStr,
+                "idx": index,
+                "engine": engine,
+                "audio": wavName,
+                "dur_sec": Self.round2(durationSec),
+                "rms_in":  Self.round4(Double(rmsIn)),
+                "rms_out": Self.round4(Double(rmsOut)),
+                "target_lang": targetLang,
+            ]
+            if let latencyMs { entry["gemma_ms"] = latencyMs }
+            if let sourceText, !sourceText.isEmpty { entry["source"] = sourceText }
+            if let translatedText, !translatedText.isEmpty { entry["translated"] = translatedText }
+            if let error { entry["error"] = error }
+
+            self.appendJSONFromQueue(entry)
+        }
+    }
+
+    // MARK: - File writers
+
+    private func appendJSON(_ obj: [String: Any]) {
+        queue.async { [weak self] in self?.appendJSONFromQueue(obj) }
+    }
+
+    private func appendJSONFromQueue(_ obj: [String: Any]) {
+        guard let data = try? JSONSerialization.data(
+            withJSONObject: obj,
+            options: [.withoutEscapingSlashes, .sortedKeys]
+        ) else { return }
+        var line = data
+        line.append(UInt8(ascii: "\n"))
+        if let handle = try? FileHandle(forWritingTo: jsonlURL) {
+            handle.seekToEndOfFile()
+            handle.write(line)
+            try? handle.close()
+        } else {
+            try? line.write(to: jsonlURL, options: [.atomic])
+        }
+    }
+
+    private static func writeWAV(pcm16: Data, sampleRate: Double, to url: URL) {
+        var out = Data()
+        let dataSize = UInt32(pcm16.count)
+        let sr = UInt32(sampleRate)
+        let byteRate = sr * 2
+        func u16(_ v: UInt16) -> Data {
+            var le = v.littleEndian
+            return Data(bytes: &le, count: 2)
+        }
+        func u32(_ v: UInt32) -> Data {
+            var le = v.littleEndian
+            return Data(bytes: &le, count: 4)
+        }
+        out.append("RIFF".data(using: .ascii)!)
+        out.append(u32(36 + dataSize))
+        out.append("WAVE".data(using: .ascii)!)
+        out.append("fmt ".data(using: .ascii)!)
+        out.append(u32(16))
+        out.append(u16(1))          // PCM
+        out.append(u16(1))          // mono
+        out.append(u32(sr))
+        out.append(u32(byteRate))
+        out.append(u16(2))          // block align
+        out.append(u16(16))         // bits per sample
+        out.append("data".data(using: .ascii)!)
+        out.append(u32(dataSize))
+        out.append(pcm16)
+        try? out.write(to: url, options: [.atomic])
+    }
+
+    // MARK: - Helpers
+
+    private static func timestampSlug(_ date: Date) -> String {
+        let f = DateFormatter()
+        f.locale = Locale(identifier: "en_US_POSIX")
+        f.timeZone = TimeZone(secondsFromGMT: 0)
+        f.dateFormat = "yyyy-MM-dd'T'HH-mm-ss'Z'"
+        return f.string(from: date)
+    }
+
+    private static func round2(_ v: Double) -> Double {
+        (v * 100).rounded() / 100
+    }
+
+    private static func round4(_ v: Double) -> Double {
+        (v * 10_000).rounded() / 10_000
+    }
+}
+
+#if canImport(AppKit)
+import AppKit
+#endif

apps/macos/Sources/BanhMi/Settings.swift

@@ -0,0 +1,118 @@
+import Foundation
+import CoreGraphics
+
+enum TextSize: String, CaseIterable, Identifiable {
+    case small = "S"
+    case medium = "M"
+    case large = "L"
+
+    var id: String { rawValue }
+
+    var displayName: String {
+        switch self {
+        case .small: return "Small"
+        case .medium: return "Medium"
+        case .large: return "Large"
+        }
+    }
+
+    var pointSize: CGFloat {
+        switch self {
+        case .small: return 20
+        case .medium: return 28
+        case .large: return 40
+        }
+    }
+}
+
+enum ASREngine: String, CaseIterable, Identifiable {
+    case gemmaMLX     // Fully offline Gemma 4 on Apple Silicon via MLX 4-bit
+
+    var id: String { rawValue }
+
+    var displayName: String {
+        switch self {
+        case .gemmaMLX: return "Gemma 4 (offline)"
+        }
+    }
+
+    var iconName: String {
+        switch self {
+        case .gemmaMLX: return "cpu.fill"
+        }
+    }
+}
+
+enum AudioSource: String, CaseIterable, Identifiable {
+    case systemAudio
+    case microphone
+
+    var id: String { rawValue }
+
+    var displayName: String {
+        switch self {
+        case .systemAudio: return "System audio"
+        case .microphone: return "Microphone"
+        }
+    }
+
+    var iconName: String {
+        switch self {
+        case .systemAudio: return "speaker.wave.2.fill"
+        case .microphone: return "mic.fill"
+        }
+    }
+}
+
+struct Language: Identifiable, Hashable {
+    let id: String           // App-level tag used for storage (BCP-47 simple form)
+    let name: String
+    let nativeName: String
+    let speechLocale: String // BCP-47 locale identifier used as a recognition hint
+}
+
+enum SupportedLanguages {
+    static let all: [Language] = [
+        Language(id: "en",    name: "English",              nativeName: "English",            speechLocale: "en-US"),
+        Language(id: "vi",    name: "Vietnamese",           nativeName: "Tiếng Việt",         speechLocale: "vi-VN"),
+        Language(id: "es",    name: "Spanish",              nativeName: "Español",            speechLocale: "es-ES"),
+        Language(id: "zh-CN", name: "Chinese (Simplified)", nativeName: "简体中文",            speechLocale: "zh-CN"),
+        Language(id: "ja",    name: "Japanese",             nativeName: "日本語",              speechLocale: "ja-JP"),
+        Language(id: "ko",    name: "Korean",               nativeName: "한국어",              speechLocale: "ko-KR"),
+        Language(id: "fr",    name: "French",               nativeName: "Français",           speechLocale: "fr-FR"),
+        Language(id: "de",    name: "German",               nativeName: "Deutsch",            speechLocale: "de-DE"),
+        Language(id: "pt",    name: "Portuguese",           nativeName: "Português",          speechLocale: "pt-BR"),
+        Language(id: "ru",    name: "Russian",              nativeName: "Русский",            speechLocale: "ru-RU"),
+        Language(id: "ar",    name: "Arabic",               nativeName: "العربية",             speechLocale: "ar-SA"),
+        Language(id: "hi",    name: "Hindi",                nativeName: "हिन्दी",              speechLocale: "hi-IN"),
+        Language(id: "id",    name: "Indonesian",           nativeName: "Bahasa Indonesia",   speechLocale: "id-ID"),
+        Language(id: "th",    name: "Thai",                 nativeName: "ไทย",                speechLocale: "th-TH"),
+        Language(id: "it",    name: "Italian",              nativeName: "Italiano",           speechLocale: "it-IT"),
+        Language(id: "tr",    name: "Turkish",              nativeName: "Türkçe",             speechLocale: "tr-TR"),
+    ]
+
+    static func named(_ id: String) -> Language? {
+        all.first { $0.id == id }
+    }
+
+    static var systemDefault: String {
+        let preferred = Locale.preferredLanguages.first ?? "en"
+        let code = Locale(identifier: preferred).language.languageCode?.identifier ?? "en"
+        let region = Locale(identifier: preferred).language.region?.identifier
+        let tag = region.map { "\(code)-\($0)" } ?? code
+        if all.contains(where: { $0.id == tag }) { return tag }
+        if all.contains(where: { $0.id == code }) { return code }
+        return "en"
+    }
+}
+
+enum SettingsKey {
+    static let outputLanguage = "outputLanguage"
+    static let textSize = "textSize"
+    static let audioSource = "audioSource"
+    static let asrEngine = "asrEngine"
+    static let isEnabled = "isEnabled"
+    static let overlayWidth = "overlayWidth"
+    static let overlayOriginX = "overlayOriginX"
+    static let overlayOriginY = "overlayOriginY"
+}

apps/macos/Sources/BanhMi/SettingsView.swift

@@ -0,0 +1,170 @@
+import SwiftUI
+
+struct SettingsView: View {
+    @ObservedObject var state: AppState
+    let onToggleEnabled: () -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 18) {
+            header
+            Divider()
+            transcriptionControl
+            audioSourceSection
+            engineSection
+            languageSection
+            textSizeSection
+            Spacer()
+            footer
+        }
+        .padding(20)
+        .frame(width: 340, height: 520)
+    }
+
+    private var header: some View {
+        HStack(spacing: 10) {
+            Image(systemName: "waveform.circle")
+                .font(.system(size: 28))
+                .foregroundStyle(.secondary)
+            VStack(alignment: .leading, spacing: 2) {
+                Text("Bánh mì chuyển ngữ")
+                    .font(.headline)
+                Text(state.statusMessage)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+            }
+            Spacer()
+        }
+    }
+
+    private var transcriptionControl: some View {
+        Button {
+            onToggleEnabled()
+        } label: {
+            HStack(spacing: 8) {
+                Image(systemName: state.isEnabled ? "pause.circle.fill" : "play.circle.fill")
+                    .font(.system(size: 18))
+                Text(state.isEnabled ? "Pause transcription" : "Resume transcription")
+                    .fontWeight(.medium)
+                Spacer()
+            }
+            .frame(maxWidth: .infinity)
+            .padding(.vertical, 10)
+            .padding(.horizontal, 14)
+            .background(
+                RoundedRectangle(cornerRadius: 10, style: .continuous)
+                    .fill(state.isEnabled ? Color.orange.opacity(0.15) : Color.green.opacity(0.18))
+            )
+            .foregroundStyle(state.isEnabled ? Color.orange : Color.green)
+        }
+        .buttonStyle(.plain)
+    }
+
+    private var audioSourceSection: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Label("Audio source", systemImage: "waveform.badge.plus")
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+            Picker("", selection: $state.audioSource) {
+                ForEach(AudioSource.allCases) { source in
+                    Label(source.displayName, systemImage: source.iconName)
+                        .tag(source)
+                }
+            }
+            .labelsHidden()
+            .pickerStyle(.segmented)
+            if state.audioSource == .systemAudio {
+                Text("System audio uses macOS Screen Recording. You'll be asked to approve once — the grant is remembered for this build.")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+    }
+
+    private var engineSection: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Label("Speech engine", systemImage: "cpu")
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+            Picker("", selection: $state.asrEngine) {
+                ForEach(ASREngine.allCases) { engine in
+                    Label(engine.displayName, systemImage: engine.iconName)
+                        .tag(engine)
+                }
+            }
+            .labelsHidden()
+            .pickerStyle(.segmented)
+            if state.asrEngine == .gemmaMLX {
+                Text("Gemma 4 runs fully offline on Apple Silicon (~4.8 GB). First launch downloads the model.")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+    }
+
+    private var languageSection: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Label("Your language", systemImage: "globe")
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+            Picker("", selection: $state.languageID) {
+                ForEach(SupportedLanguages.all) { lang in
+                    Text(lang.nativeName).tag(lang.id)
+                }
+            }
+            .labelsHidden()
+            .pickerStyle(.menu)
+        }
+    }
+
+    private var textSizeSection: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Label("Subtitle size", systemImage: "textformat.size")
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+            Picker("", selection: $state.textSize) {
+                ForEach(TextSize.allCases) { size in
+                    Text(size.rawValue).tag(size)
+                }
+            }
+            .labelsHidden()
+            .pickerStyle(.segmented)
+            Text(state.textSize.displayName)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    private var footer: some View {
+        HStack {
+            Button("Quit") {
+                NSApplication.shared.terminate(nil)
+            }
+            .keyboardShortcut("q", modifiers: .command)
+
+            Button {
+                SessionLogger.shared.revealInFinder()
+            } label: {
+                Label("Logs", systemImage: "doc.text.magnifyingglass")
+            }
+            .buttonStyle(.borderless)
+            .font(.caption)
+
+            Spacer()
+
+            if let error = state.errorMessage {
+                Text(error)
+                    .font(.caption2)
+                    .foregroundStyle(.red)
+                    .lineLimit(2)
+                    .frame(maxWidth: 200, alignment: .trailing)
+            } else {
+                Text("v0.5")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+}

apps/macos/Sources/BanhMi/SubtitleOverlay.swift

@@ -0,0 +1,215 @@
+import AppKit
+import SwiftUI
+import Combine
+
+/// A borderless, always-on-top panel that hosts the draggable/resizable
+/// subtitle bubble. Mouse events outside the bubble pass through to apps below.
+final class SubtitleOverlayPanel: NSPanel {
+    init() {
+        super.init(
+            contentRect: NSRect(x: 0, y: 0, width: 900, height: 220),
+            styleMask: [.borderless, .nonactivatingPanel],
+            backing: .buffered,
+            defer: false
+        )
+
+        isOpaque = false
+        backgroundColor = .clear
+        hasShadow = false
+        level = .screenSaver
+        ignoresMouseEvents = false
+        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .ignoresCycle]
+        isMovableByWindowBackground = false
+        hidesOnDeactivate = false
+        isReleasedWhenClosed = false
+    }
+
+    override var canBecomeKey: Bool { false }
+    override var canBecomeMain: Bool { false }
+}
+
+/// Hosting view that only captures mouse events on opaque SwiftUI content.
+/// Clear/background areas fall through to the app underneath.
+final class ClickThroughHostingView<Content: View>: NSHostingView<Content> {
+    override func hitTest(_ point: NSPoint) -> NSView? {
+        guard let hit = super.hitTest(point) else { return nil }
+        // If the hit view is this root host (transparent zones), pass through.
+        if hit === self { return nil }
+        return hit
+    }
+}
+
+@MainActor
+final class SubtitleOverlayController {
+    static let defaultWidth: CGFloat = 900
+    static let defaultHeight: CGFloat = 220
+    static let minWidth: CGFloat = 360
+    static let maxWidth: CGFloat = 1600
+
+    private let panel: SubtitleOverlayPanel
+    private let state: AppState
+    private var cancellables = Set<AnyCancellable>()
+
+    init(state: AppState) {
+        self.state = state
+        self.panel = SubtitleOverlayPanel()
+
+        let root = SubtitleView(
+            state: state,
+            onDrag: { [weak self] delta in self?.dragPanel(by: delta) }
+        )
+        let host = ClickThroughHostingView(rootView: root)
+        host.translatesAutoresizingMaskIntoConstraints = true
+        panel.contentView = host
+
+        NotificationCenter.default.addObserver(
+            forName: NSApplication.didChangeScreenParametersNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            Task { @MainActor in self?.clampToScreen() }
+        }
+    }
+
+    func show() {
+        applyInitialFrame()
+        panel.orderFrontRegardless()
+    }
+
+    func hide() {
+        panel.orderOut(nil)
+    }
+
+    private func applyInitialFrame() {
+        guard let screen = NSScreen.main else { return }
+        let visible = screen.visibleFrame
+        let width = clampWidth(state.overlayWidth)
+        let height = Self.defaultHeight
+
+        let x: CGFloat
+        let y: CGFloat
+        if let saved = state.overlayOrigin {
+            x = saved.x
+            y = saved.y
+        } else {
+            x = visible.midX - width / 2
+            y = visible.minY + 60
+        }
+        panel.setFrame(NSRect(x: x, y: y, width: width, height: height), display: true, animate: false)
+        clampToScreen()
+    }
+
+    private func dragPanel(by delta: CGSize) {
+        var frame = panel.frame
+        // SwiftUI drag deltas: +x right, +y down. AppKit window coords: +y up.
+        frame.origin.x += delta.width
+        frame.origin.y -= delta.height
+        panel.setFrame(frame, display: true)
+        clampToScreen()
+        state.overlayOrigin = CGPoint(x: panel.frame.origin.x, y: panel.frame.origin.y)
+    }
+
+    private func clampWidth(_ w: CGFloat) -> CGFloat {
+        min(Self.maxWidth, max(Self.minWidth, w))
+    }
+
+    private func clampToScreen() {
+        guard let screen = NSScreen.main else { return }
+        let visible = screen.visibleFrame
+        var frame = panel.frame
+        frame.origin.x = min(max(frame.origin.x, visible.minX), visible.maxX - frame.width)
+        frame.origin.y = min(max(frame.origin.y, visible.minY), visible.maxY - frame.height)
+        panel.setFrame(frame, display: true)
+    }
+}
+
+// MARK: - SwiftUI content
+
+struct SubtitleView: View {
+    @ObservedObject var state: AppState
+    let onDrag: (CGSize) -> Void
+
+    // Track last drag translation so we can emit incremental deltas.
+    @State private var dragLast: CGSize = .zero
+
+    var body: some View {
+        ZStack(alignment: .bottom) {
+            Color.clear
+            VStack {
+                Spacer()
+                content
+            }
+        }
+    }
+
+    @ViewBuilder
+    private var content: some View {
+        if let error = state.errorMessage {
+            errorBubble(error)
+        } else if !state.lines.isEmpty {
+            lineStack
+        }
+    }
+
+    /// Stack of stable subtitle lines. Newest is at the bottom; older lines
+    /// appear above it, fade, and get pushed up as new lines arrive.
+    private var lineStack: some View {
+        VStack(spacing: 6) {
+            ForEach(Array(state.lines.enumerated()), id: \.element.id) { index, line in
+                let age = state.lines.count - 1 - index // 0 = newest
+                lineBubble(text: line.text, age: age)
+                    .transition(.asymmetric(
+                        insertion: .move(edge: .bottom).combined(with: .opacity),
+                        removal: .move(edge: .top).combined(with: .opacity)
+                    ))
+            }
+        }
+        .padding(.horizontal, 8)
+        .animation(.easeInOut(duration: 0.35), value: state.lines.map(\.id))
+        .gesture(
+            DragGesture(minimumDistance: 2)
+                .onChanged { value in
+                    let incremental = CGSize(
+                        width: value.translation.width - dragLast.width,
+                        height: value.translation.height - dragLast.height
+                    )
+                    dragLast = value.translation
+                    onDrag(incremental)
+                }
+                .onEnded { _ in dragLast = .zero }
+        )
+    }
+
+    private func lineBubble(text: String, age: Int) -> some View {
+        // Older lines dim slightly so the eye locks onto the newest.
+        let opacity = max(0.45, 1.0 - Double(age) * 0.25)
+        return Text(text)
+            .font(.system(size: state.textSize.pointSize, weight: .semibold, design: .rounded))
+            .foregroundStyle(.white)
+            .multilineTextAlignment(.center)
+            .lineLimit(3)
+            .padding(.horizontal, 24)
+            .padding(.vertical, 10)
+            .background(
+                RoundedRectangle(cornerRadius: 14, style: .continuous)
+                    .fill(Color.black.opacity(0.72))
+            )
+            .shadow(color: .black.opacity(0.35), radius: 8, y: 3)
+            .opacity(opacity)
+    }
+
+    private func errorBubble(_ message: String) -> some View {
+        Text(message)
+            .font(.system(size: 14, weight: .medium, design: .rounded))
+            .foregroundStyle(.white)
+            .multilineTextAlignment(.center)
+            .padding(.horizontal, 20)
+            .padding(.vertical, 10)
+            .background(
+                RoundedRectangle(cornerRadius: 12, style: .continuous)
+                    .fill(Color.red.opacity(0.8))
+            )
+    }
+
+}
+

apps/macos/Sources/BanhMi/SystemAudioCapture.swift

@@ -0,0 +1,120 @@
+import Foundation
+import AVFoundation
+import ScreenCaptureKit
+import CoreMedia
+import CoreGraphics
+
+/// Captures system audio (anything playing through macOS output) via ScreenCaptureKit.
+/// Requires Screen Recording permission.
+final class SystemAudioCapture: NSObject, SCStreamOutput, SCStreamDelegate {
+    private var stream: SCStream?
+    private let audioQueue = DispatchQueue(label: "vn.banhmi.audioQueue")
+    private(set) var isRunning = false
+
+    var onBuffer: ((AVAudioPCMBuffer, AVAudioTime) -> Void)?
+    var onError: ((Error) -> Void)?
+
+    func start() async throws {
+        guard !isRunning else { return }
+
+        // Explicitly request Screen Recording access. This forces macOS to
+        // show the prompt on first use (menu-bar apps otherwise sometimes
+        // have SCShareableContent fail silently). If this returns false,
+        // the user has denied access and we surface a clear error instead
+        // of failing without feedback.
+        if CGPreflightScreenCaptureAccess() == false {
+            let granted = CGRequestScreenCaptureAccess()
+            if granted == false {
+                throw NSError(
+                    domain: "SystemAudioCapture",
+                    code: 403,
+                    userInfo: [NSLocalizedDescriptionKey:
+                        "Screen Recording permission is required for system audio. Open System Settings → Privacy & Security → Screen & System Audio Recording, enable Bánh mì chuyển ngữ, then relaunch the app."]
+                )
+            }
+        }
+
+        // Pick any display — we capture the full display's audio output.
+        let content = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
+        guard let display = content.displays.first else {
+            throw NSError(domain: "SystemAudioCapture", code: 1,
+                          userInfo: [NSLocalizedDescriptionKey: "No display found."])
+        }
+
+        let filter = SCContentFilter(display: display, excludingWindows: [])
+
+        let config = SCStreamConfiguration()
+        config.capturesAudio = true
+        config.sampleRate = 48_000
+        config.channelCount = 2
+        config.excludesCurrentProcessAudio = true
+        // Minimal video config — we don't use video frames but the stream requires
+        // a reasonable configuration.
+        config.width = 2
+        config.height = 2
+        config.minimumFrameInterval = CMTime(value: 1, timescale: 1)
+        config.queueDepth = 5
+
+        let stream = SCStream(filter: filter, configuration: config, delegate: self)
+        try stream.addStreamOutput(self, type: .audio, sampleHandlerQueue: audioQueue)
+        try await stream.startCapture()
+
+        self.stream = stream
+        self.isRunning = true
+    }
+
+    func stop() async {
+        guard let stream else { return }
+        do {
+            try await stream.stopCapture()
+        } catch {
+            // Non-fatal; we're tearing down anyway.
+        }
+        self.stream = nil
+        self.isRunning = false
+    }
+
+    // MARK: - SCStreamOutput
+
+    func stream(_ stream: SCStream, didOutputSampleBuffer sampleBuffer: CMSampleBuffer, of type: SCStreamOutputType) {
+        guard type == .audio, sampleBuffer.isValid, sampleBuffer.numSamples > 0 else { return }
+        guard let pcmBuffer = Self.pcmBuffer(from: sampleBuffer) else { return }
+
+        let audioTime = AVAudioTime(hostTime: mach_absolute_time())
+        onBuffer?(pcmBuffer, audioTime)
+    }
+
+    // MARK: - SCStreamDelegate
+
+    func stream(_ stream: SCStream, didStopWithError error: Error) {
+        isRunning = false
+        onError?(error)
+    }
+
+    // MARK: - Helpers
+
+    /// Converts a CMSampleBuffer (from ScreenCaptureKit) into an AVAudioPCMBuffer.
+    private static func pcmBuffer(from sampleBuffer: CMSampleBuffer) -> AVAudioPCMBuffer? {
+        guard let formatDescription = CMSampleBufferGetFormatDescription(sampleBuffer),
+              let asbdPointer = CMAudioFormatDescriptionGetStreamBasicDescription(formatDescription) else {
+            return nil
+        }
+
+        var asbd = asbdPointer.pointee
+        guard let format = AVAudioFormat(streamDescription: &asbd) else { return nil }
+
+        let numSamples = AVAudioFrameCount(CMSampleBufferGetNumSamples(sampleBuffer))
+        guard let pcmBuffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: numSamples) else {
+            return nil
+        }
+        pcmBuffer.frameLength = numSamples
+
+        let status = CMSampleBufferCopyPCMDataIntoAudioBufferList(
+            sampleBuffer,
+            at: 0,
+            frameCount: Int32(numSamples),
+            into: pcmBuffer.mutableAudioBufferList
+        )
+        return status == noErr ? pcmBuffer : nil
+    }
+}

apps/macos/Sources/BanhMi/TranscriptionController.swift

@@ -0,0 +1,362 @@
+import Foundation
+import AVFoundation
+import AppKit
+import Combine
+import OSLog
+
+/// Engine-agnostic recognizer surface implemented by GemmaMLXRecognizer.
+/// Keeps TranscriptionController free of per-engine branches.
+@MainActor
+protocol AudioRecognizer: AnyObject {
+    var onStableUpdate: ((String, Bool, String?) -> Void)? { get set }
+    var onFinalUtterance: ((String, String?) -> Void)? { get set }
+    var onFinal: (() -> Void)? { get set }
+    var onError: ((Error) -> Void)? { get set }
+    func configure(sourceLocale: Locale, targetLanguageCode: String, context: String) throws
+    func startTask() throws
+    func append(_ buffer: AVAudioPCMBuffer)
+    func stop()
+}
+
+extension GemmaMLXRecognizer: AudioRecognizer {}
+
+/// Orchestrates audio capture + streaming recognition (Gemma 4 MLX
+/// offline) and publishes stable updates to `AppState`. Optimized for
+/// sub-second end-to-end latency.
+@MainActor
+final class TranscriptionController {
+    private let state: AppState
+    private let mic = MicrophoneCapture()
+    private let system = SystemAudioCapture()
+
+    private var recognizer: AudioRecognizer?
+    private var cancellables = Set<AnyCancellable>()
+    private var recognitionRestartWork: DispatchWorkItem?
+
+    private var activeSource: AudioSource?
+    private var configuredLanguageID: String?
+    private var configuredEngine: ASREngine?
+
+    private let log = Logger(subsystem: "vn.banhmi.chuyenngu", category: "stt")
+
+    init(state: AppState) {
+        self.state = state
+
+        system.onError = { [weak self] error in
+            Task { @MainActor in
+                guard let self else { return }
+                self.state.errorMessage = "System audio stopped: \(error.localizedDescription)"
+                await self.stopAll()
+                self.state.isListening = false
+                self.state.statusMessage = "Paused"
+            }
+        }
+
+        let forward: (AVAudioPCMBuffer, AVAudioTime) -> Void = { [weak self] buf, _ in
+            self?.recognizer?.append(buf)
+        }
+        mic.onBuffer = forward
+        system.onBuffer = forward
+
+        state.$audioSource
+            .dropFirst()
+            .removeDuplicates()
+            .sink { [weak self] _ in
+                Task { await self?.handleSettingsChange() }
+            }
+            .store(in: &cancellables)
+
+        state.$languageID
+            .dropFirst()
+            .removeDuplicates()
+            .sink { [weak self] _ in
+                Task { await self?.handleSettingsChange() }
+            }
+            .store(in: &cancellables)
+
+        state.$asrEngine
+            .dropFirst()
+            .removeDuplicates()
+            .sink { [weak self] _ in
+                Task { await self?.handleSettingsChange() }
+            }
+            .store(in: &cancellables)
+    }
+
+    // MARK: - Public API
+
+    func bootstrap() async {
+        if state.isEnabled {
+            await start()
+        } else {
+            state.statusMessage = "Paused"
+        }
+    }
+
+    func resume() async {
+        state.isEnabled = true
+        await start()
+    }
+
+    func pause() async {
+        state.isEnabled = false
+        await stopAll()
+        state.isListening = false
+        state.transcript = ""
+        state.translatedTranscript = ""
+        state.detectedSourceLanguage = nil
+        state.clearLines()
+        state.statusMessage = "Paused"
+    }
+
+    func shutdown() async {
+        recognitionRestartWork?.cancel()
+        await stopAll()
+    }
+
+    // MARK: - Start / stop
+
+    private func start() async {
+        state.errorMessage = nil
+        state.transcript = ""
+        state.translatedTranscript = ""
+        state.detectedSourceLanguage = nil
+        state.clearLines()
+        state.statusMessage = "Starting…"
+
+        let recognizer: AudioRecognizer
+        switch state.asrEngine {
+        case .gemmaMLX:
+            guard let sidecarPath = Self.findSidecarScript() else {
+                state.statusMessage = "Gemma sidecar not found"
+                state.errorMessage = "Expected gemma_sidecar.py under apps/macos/scripts/. Rebuild with ./build.sh."
+                state.isListening = false
+                return
+            }
+            let pythonPath = Self.findPythonWithMLX()
+                ?? "/usr/bin/env"  // last-ditch fallback
+            do {
+                recognizer = try GemmaMLXRecognizer(
+                    sidecarScriptPath: sidecarPath,
+                    pythonPath: pythonPath
+                )
+                state.statusMessage = "Loading Gemma 4 (first launch ~1 min)…"
+            } catch {
+                state.isListening = false
+                state.statusMessage = "Could not start Gemma"
+                state.errorMessage = error.localizedDescription
+                return
+            }
+        }
+
+        wireCallbacks(on: recognizer)
+        self.recognizer = recognizer
+
+        do {
+            try recognizer.configure(
+                sourceLocale: Locale(identifier: state.currentLanguage.speechLocale),
+                targetLanguageCode: baseLanguageCode(state.languageID),
+                context: ""
+            )
+            try recognizer.startTask()
+        } catch {
+            self.recognizer = nil
+            state.isListening = false
+            state.statusMessage = "Could not start \(state.asrEngine.displayName)"
+            state.errorMessage = error.localizedDescription
+            return
+        }
+
+        switch state.audioSource {
+        case .microphone:
+            await startMicrophone()
+        case .systemAudio:
+            await startSystemAudio()
+        }
+        configuredLanguageID = state.languageID
+        configuredEngine = state.asrEngine
+    }
+
+    /// Locate a python3 interpreter that has `mlx-vlm` importable. Launched
+    /// .app bundles don't inherit shell PATH, so we search known locations.
+    private static func findPythonWithMLX() -> String? {
+        let candidates: [String] = [
+            // 1) User override
+            ProcessInfo.processInfo.environment["BANHMI_PYTHON"] ?? "",
+            // 2) Unsloth's installer venv (recommended path)
+            (NSHomeDirectory() as NSString)
+                .appendingPathComponent(".unsloth/unsloth_gemma4_mlx/bin/python3"),
+            // 3) Project venv (dev machine)
+            "/Users/duytran10/Documents/Others/Any2AnyModels/venv_local/bin/python3",
+            // 4) Homebrew python3
+            "/opt/homebrew/bin/python3",
+            // 5) System python3 (unlikely to have mlx-vlm, but try)
+            "/usr/bin/python3",
+        ].filter { !$0.isEmpty }
+
+        let fm = FileManager.default
+        for candidate in candidates where fm.isExecutableFile(atPath: candidate) {
+            // Quick check: does this python import mlx_vlm?
+            let probe = Process()
+            probe.executableURL = URL(fileURLWithPath: candidate)
+            probe.arguments = ["-c", "import mlx_vlm"]
+            probe.standardOutput = Pipe()
+            probe.standardError = Pipe()
+            do {
+                try probe.run()
+                probe.waitUntilExit()
+                if probe.terminationStatus == 0 {
+                    return candidate
+                }
+            } catch {
+                continue
+            }
+        }
+        return nil
+    }
+
+    /// Locate the Gemma sidecar Python script. Looks in the repo layout first
+    /// (useful during development from the build dir) and then inside the
+    /// installed .app bundle Resources.
+    private static func findSidecarScript() -> String? {
+        let fm = FileManager.default
+        // 1) Bundled under Resources/scripts/gemma_sidecar.py
+        if let bundled = Bundle.main.resourceURL?
+            .appendingPathComponent("scripts/gemma_sidecar.py").path,
+           fm.fileExists(atPath: bundled) {
+            return bundled
+        }
+        // 2) Dev path: apps/macos/scripts/gemma_sidecar.py relative to binary
+        if let exe = Bundle.main.executableURL {
+            let dev = exe
+                .deletingLastPathComponent()   // Contents/MacOS
+                .deletingLastPathComponent()   // Contents
+                .deletingLastPathComponent()   // <App>.app
+                .deletingLastPathComponent()   // parent
+                .appendingPathComponent("scripts/gemma_sidecar.py").path
+            if fm.fileExists(atPath: dev) { return dev }
+        }
+        // 3) Absolute fallback during development
+        let repoGuess = "/Users/duytran10/Documents/Others/Any2AnyModels/apps/macos/scripts/gemma_sidecar.py"
+        if fm.fileExists(atPath: repoGuess) { return repoGuess }
+        return nil
+    }
+
+    private func startMicrophone() async {
+        let granted = MicrophoneCapture.hasPermission
+            ? true
+            : await MicrophoneCapture.requestPermission()
+        guard granted else {
+            recognizer?.stop()
+            recognizer = nil
+            state.statusMessage = "Microphone not authorized"
+            state.errorMessage = "Enable in System Settings → Privacy & Security → Microphone."
+            state.isListening = false
+            return
+        }
+
+        do {
+            try mic.start()
+            activeSource = .microphone
+            state.isListening = true
+            state.statusMessage = "Listening to microphone"
+        } catch {
+            recognizer?.stop()
+            recognizer = nil
+            state.isListening = false
+            state.statusMessage = "Could not start microphone"
+            state.errorMessage = error.localizedDescription
+        }
+    }
+
+    private func startSystemAudio() async {
+        do {
+            try await system.start()
+            activeSource = .systemAudio
+            state.isListening = true
+            state.statusMessage = "Listening to system audio"
+        } catch {
+            recognizer?.stop()
+            recognizer = nil
+            state.isListening = false
+            state.statusMessage = "Could not capture system audio"
+            let message = error.localizedDescription.lowercased()
+            if message.contains("tcc") || message.contains("declined") || message.contains("permission") {
+                state.errorMessage = "Grant Screen Recording in System Settings → Privacy & Security → Screen Recording, then relaunch."
+            } else {
+                state.errorMessage = error.localizedDescription
+            }
+        }
+    }
+
+    private func stopAll() async {
+        recognitionRestartWork?.cancel()
+        recognitionRestartWork = nil
+        mic.stop()
+        await system.stop()
+        recognizer?.stop()
+        recognizer = nil
+        activeSource = nil
+        configuredLanguageID = nil
+        configuredEngine = nil
+    }
+
+    // MARK: - Wiring
+
+    private func wireCallbacks(on recognizer: AudioRecognizer) {
+        recognizer.onStableUpdate = { [weak self] text, isFinal, detected in
+            guard let self else { return }
+            if self.state.errorMessage != nil {
+                self.state.errorMessage = nil
+            }
+            if let detected { self.state.detectedSourceLanguage = detected }
+            self.state.translatedTranscript = text
+            self.state.showLive(text: text, isFinal: isFinal)
+        }
+        recognizer.onFinalUtterance = { _, _ in
+            // No-op: onStableUpdate with isFinal=true already drove the UI.
+        }
+        recognizer.onFinal = {}
+        recognizer.onError = { [weak self] error in
+            guard let self else { return }
+            self.state.errorMessage = error.localizedDescription
+            self.scheduleRecognitionRestart(delay: 2.0)
+        }
+    }
+
+    private func baseLanguageCode(_ id: String) -> String {
+        return id
+    }
+
+    // MARK: - Settings-triggered updates
+
+    private func handleSettingsChange() async {
+        guard state.isEnabled else { return }
+        let sourceChanged = state.audioSource != activeSource
+        let languageChanged = state.languageID != configuredLanguageID
+        let engineChanged = state.asrEngine != configuredEngine
+        guard sourceChanged || languageChanged || engineChanged else { return }
+
+        await stopAll()
+        await start()
+    }
+
+    private func scheduleRecognitionRestart(delay: TimeInterval) {
+        recognitionRestartWork?.cancel()
+        let work = DispatchWorkItem { [weak self] in
+            Task { @MainActor in
+                guard let self,
+                      self.state.isEnabled,
+                      self.activeSource != nil,
+                      let recognizer = self.recognizer else { return }
+                do {
+                    try recognizer.startTask()
+                } catch {
+                    self.state.errorMessage = error.localizedDescription
+                }
+            }
+        }
+        recognitionRestartWork = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
+    }
+}

apps/macos/Sources/BanhMi/TranslationService.swift

@@ -0,0 +1,122 @@
+import Foundation
+
+/// Translates text between languages. Implementations may call remote APIs
+/// or a local Gemma 4 model.
+protocol TranslationService: AnyObject {
+    /// Returns translated text. Throws on transport/auth errors.
+    /// Implementations should return the original text if `from == to`.
+    func translate(_ text: String, from: String, to: String) async throws -> String
+}
+
+/// Fallback that never translates — the UI will simply show the transcript
+/// unchanged. Used when no translation backend is configured.
+final class PassthroughTranslator: TranslationService {
+    func translate(_ text: String, from: String, to: String) async throws -> String {
+        return text
+    }
+}
+
+/// Free, keyless translator backed by Google's public `translate_a/single`
+/// endpoint. Rate-limited and unofficial — use as a zero-config fallback until
+/// Gemma 4 / an authenticated API is wired in.
+final class FreeGoogleTranslator: TranslationService {
+    private let session: URLSession
+
+    init(session: URLSession = .shared) {
+        self.session = session
+    }
+
+    func translate(_ text: String, from: String, to: String) async throws -> String {
+        guard !text.isEmpty else { return text }
+        let src = Self.shortCode(from)
+        let tgt = Self.shortCode(to)
+        guard src != tgt else { return text }
+
+        var components = URLComponents(string: "https://translate.googleapis.com/translate_a/single")!
+        components.queryItems = [
+            URLQueryItem(name: "client", value: "gtx"),
+            URLQueryItem(name: "sl", value: src.isEmpty ? "auto" : src),
+            URLQueryItem(name: "tl", value: tgt),
+            URLQueryItem(name: "dt", value: "t"),
+            URLQueryItem(name: "q", value: text)
+        ]
+        guard let url = components.url else { return text }
+
+        var request = URLRequest(url: url)
+        request.setValue("Mozilla/5.0", forHTTPHeaderField: "User-Agent")
+
+        let (data, response) = try await session.data(for: request)
+        guard let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode) else {
+            return text
+        }
+        // Response shape: [[["translated","original",...],...],...]
+        guard let outer = try? JSONSerialization.jsonObject(with: data) as? [Any],
+              let sentences = outer.first as? [Any] else {
+            return text
+        }
+        var out = ""
+        for entry in sentences {
+            if let parts = entry as? [Any], let piece = parts.first as? String {
+                out += piece
+            }
+        }
+        return out.isEmpty ? text : out
+    }
+
+    /// Reduce "en-US" → "en" for the translate endpoint (with a few exceptions).
+    private static func shortCode(_ id: String) -> String {
+        let lower = id.lowercased()
+        // Google expects these specific regional codes.
+        if lower.hasPrefix("zh-cn") { return "zh-CN" }
+        if lower.hasPrefix("zh-tw") { return "zh-TW" }
+        if lower.hasPrefix("pt-br") { return "pt" }
+        if let dash = lower.firstIndex(of: "-") {
+            return String(lower[..<dash])
+        }
+        return lower
+    }
+}
+
+/// Google Cloud Translation v2 — simple REST call. Returns the original
+/// text on any network/parsing failure so the overlay keeps updating.
+final class GoogleTranslator: TranslationService {
+    private let apiKey: String
+    private let session: URLSession
+
+    init(apiKey: String, session: URLSession = .shared) {
+        self.apiKey = apiKey
+        self.session = session
+    }
+
+    func translate(_ text: String, from: String, to: String) async throws -> String {
+        guard !apiKey.isEmpty else { return text }
+        guard from != to else { return text }
+
+        var components = URLComponents(string: "https://translation.googleapis.com/language/translate/v2")!
+        components.queryItems = [
+            URLQueryItem(name: "key", value: apiKey),
+            URLQueryItem(name: "q", value: text),
+            URLQueryItem(name: "source", value: from),
+            URLQueryItem(name: "target", value: to),
+            URLQueryItem(name: "format", value: "text")
+        ]
+        guard let url = components.url else { return text }
+
+        var request = URLRequest(url: url)
+        request.httpMethod = "POST"
+
+        let (data, response) = try await session.data(for: request)
+        guard let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode) else {
+            return text
+        }
+
+        guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let dataField = json["data"] as? [String: Any],
+              let translations = dataField["translations"] as? [[String: Any]],
+              let first = translations.first,
+              let translated = first["translatedText"] as? String else {
+            return text
+        }
+        return translated
+    }
+}

apps/macos/build.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+APP_NAME="Bánh mì chuyển ngữ"
+EXEC_NAME="BanhMi"
+CONFIG="${CONFIG:-release}"
+BUILD_DIR=".build/$CONFIG"
+STAGE_BUNDLE="$BUILD_DIR/$APP_NAME.app"
+
+# The app is installed outside Dropbox so TCC permissions (Screen Recording,
+# Microphone) survive across rebuilds. Dropbox rewrites xattrs/mtimes during
+# sync and silently invalidates ad-hoc signatures — that's what was causing
+# macOS to re-prompt for permissions.
+INSTALL_DIR="${INSTALL_DIR:-$HOME/Applications}"
+INSTALLED_BUNDLE="$INSTALL_DIR/$APP_NAME.app"
+
+echo "▸ Building $CONFIG binary..."
+swift build -c "$CONFIG"
+
+echo "▸ Assembling app bundle in staging..."
+rm -rf "$STAGE_BUNDLE"
+mkdir -p "$STAGE_BUNDLE/Contents/MacOS"
+mkdir -p "$STAGE_BUNDLE/Contents/Resources"
+
+cp "$BUILD_DIR/$EXEC_NAME" "$STAGE_BUNDLE/Contents/MacOS/$EXEC_NAME"
+cp Resources/Info.plist "$STAGE_BUNDLE/Contents/Info.plist"
+
+echo "▸ Signing staging bundle…"
+ENTITLEMENTS_FILE="$(mktemp -t banhmi-entitlements).plist"
+cat > "$ENTITLEMENTS_FILE" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.device.audio-input</key>
+    <true/>
+</dict>
+</plist>
+PLIST
+
+# Prefer an "Apple Development" identity from Xcode — it gives the bundle a
+# stable code-signing identity, so macOS TCC (Screen Recording, Microphone)
+# grants persist across rebuilds. Falls back to ad-hoc if not found.
+SIGN_IDENTITY="$(security find-identity -v 2>/dev/null \
+    | awk '/Apple Development/ {print $2; exit}')"
+if [[ -z "$SIGN_IDENTITY" ]]; then
+    # Fallback: first valid identity of any kind (Xcode-managed dev certs
+    # sometimes only show as UUID labels instead of the friendly name).
+    SIGN_IDENTITY="$(security find-identity -v 2>/dev/null \
+        | awk '/^ *[0-9]+\)/ {print $2; exit}')"
+fi
+if [[ -z "$SIGN_IDENTITY" ]]; then
+    echo "  ⚠️  No code-signing identity found — falling back to ad-hoc."
+    echo "      TCC permissions will reset on every rebuild."
+    SIGN_IDENTITY="-"
+else
+    echo "  ↳ Using signing identity: $SIGN_IDENTITY"
+fi
+
+codesign --force --deep --sign "$SIGN_IDENTITY" \
+  --options runtime \
+  --entitlements "$ENTITLEMENTS_FILE" \
+  "$STAGE_BUNDLE"
+rm -f "$ENTITLEMENTS_FILE"
+
+echo "▸ Installing to $INSTALLED_BUNDLE (outside Dropbox)…"
+mkdir -p "$INSTALL_DIR"
+
+# If the bundle already exists and the signatures match, skip copying so TCC
+# keeps its grant for the exact same on-disk identity. If they differ, we
+# atomically replace the installed bundle and re-apply TCC (user will need to
+# re-grant only when the executable actually changed).
+STAGE_HASH="$(codesign -dvvv "$STAGE_BUNDLE" 2>&1 | awk -F'=' '/^CDHash=/{print $2}')"
+INSTALLED_HASH=""
+if [[ -d "$INSTALLED_BUNDLE" ]]; then
+    INSTALLED_HASH="$(codesign -dvvv "$INSTALLED_BUNDLE" 2>&1 | awk -F'=' '/^CDHash=/{print $2}' || true)"
+fi
+
+if [[ -n "$INSTALLED_HASH" && "$STAGE_HASH" == "$INSTALLED_HASH" ]]; then
+    echo "  ↳ Signature unchanged — keeping existing install."
+else
+    rm -rf "$INSTALLED_BUNDLE"
+    cp -R "$STAGE_BUNDLE" "$INSTALLED_BUNDLE"
+    echo "  ↳ Installed new build."
+    if [[ "$SIGN_IDENTITY" == "-" ]]; then
+        echo "  ⚠️  Ad-hoc signed — macOS may re-prompt for Screen Recording / Microphone."
+    fi
+fi
+
+echo ""
+echo "✓ Installed: $INSTALLED_BUNDLE"
+echo ""
+echo "Run with:"
+echo "  open \"$INSTALLED_BUNDLE\""

apps/macos/scripts/gemma_sidecar.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""
+Gemma 4 MLX sidecar for the macOS Bánh mì chuyển ngữ app.
+
+Reads NDJSON requests from stdin, one per line. Each request describes an
+audio clip (either file path or raw PCM over stdin) and a task. Writes
+NDJSON responses to stdout.
+
+Request format (JSON, one per line):
+    {"task": "transcribe_translate",
+     "audio_path": "/tmp/clip.wav",
+     "target_lang": "Vietnamese"}
+
+Response format (JSON, one per line):
+    {"ok": true,
+     "source_text": "...",
+     "translated_text": "...",
+     "latency_ms": 1234}
+
+On error:
+    {"ok": false, "error": "..."}
+
+The model is loaded once at startup so subsequent requests are fast.
+
+Usage from Swift:
+    let proc = Process()
+    proc.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+    proc.arguments = ["python3", "/path/to/gemma_sidecar.py"]
+    // Write one JSON object + newline per request, read back one JSON per line.
+"""
+
+import json
+import os
+import sys
+import tempfile
+import time
+
+
+MODEL_ID_DEFAULT = "unsloth/gemma-4-E2B-it-UD-MLX-4bit"
+
+
+def eprint(*args, **kwargs):
+    print(*args, file=sys.stderr, flush=True, **kwargs)
+
+
+def load_model(model_id: str):
+    from mlx_vlm import load, generate, apply_chat_template
+    model, processor = load(model_id)
+    config = getattr(model, "config", None)
+    return model, processor, config, generate, apply_chat_template
+
+
+def run_prompt(bundle, audio_path: str, prompt_text: str, max_tokens: int = 256) -> str:
+    model, processor, config, generate, apply_chat_template = bundle
+    formatted = apply_chat_template(processor, config, prompt_text, num_audios=1)
+    result = generate(
+        model, processor, formatted,
+        audio=audio_path,
+        max_tokens=max_tokens,
+        temperature=0.0,
+        verbose=False,
+    )
+    return (result.text if hasattr(result, "text") else str(result)).strip()
+
+
+def handle(req: dict, bundle) -> dict:
+    task = req.get("task", "transcribe")
+    audio_path = req.get("audio_path")
+    target_lang = req.get("target_lang")
+    max_tokens = int(req.get("max_tokens", 256))
+
+    if not audio_path or not os.path.exists(audio_path):
+        return {"ok": False, "error": f"audio_path missing or not found: {audio_path!r}"}
+
+    # Save each received chunk to /tmp so we can inspect what we actually sent
+    try:
+        import shutil
+        shutil.copy(audio_path, "/tmp/banhmi_last_chunk.wav")
+        eprint(f"[sidecar] chunk {os.path.getsize(audio_path)} bytes -> /tmp/banhmi_last_chunk.wav")
+    except Exception as exc:
+        eprint(f"[sidecar] debug copy failed: {exc}")
+
+    t0 = time.time()
+
+    if task == "transcribe":
+        text = run_prompt(bundle, audio_path, "Transcribe this audio", max_tokens)
+        return {
+            "ok": True,
+            "source_text": text,
+            "translated_text": None,
+            "latency_ms": int((time.time() - t0) * 1000),
+        }
+
+    if task == "translate":
+        if not target_lang:
+            return {"ok": False, "error": "target_lang required for translate task"}
+        prompt = (
+            f"Translate the speech in this audio into {target_lang}. "
+            f"The speaker may be using any language — detect it and translate. "
+            f"If the speech is already in {target_lang}, output the speech as-is. "
+            f"Reply with only the {target_lang} text, no explanations or quotes."
+        )
+        translated = run_prompt(bundle, audio_path, prompt, max_tokens)
+        return {
+            "ok": True,
+            "source_text": None,
+            "translated_text": translated,
+            "latency_ms": int((time.time() - t0) * 1000),
+        }
+
+    if task == "transcribe_translate":
+        if not target_lang:
+            return {"ok": False, "error": "target_lang required"}
+        # Two calls: original + translation. Run them sequentially.
+        translate_prompt = (
+            f"Translate the speech in this audio into {target_lang}. "
+            f"The speaker may be using any language — detect it and translate. "
+            f"If the speech is already in {target_lang}, output the speech as-is. "
+            f"Reply with only the {target_lang} text, no explanations or quotes."
+        )
+        translated = run_prompt(bundle, audio_path, translate_prompt, max_tokens)
+        source = run_prompt(bundle, audio_path, "Transcribe this audio", max_tokens)
+        return {
+            "ok": True,
+            "source_text": source,
+            "translated_text": translated,
+            "latency_ms": int((time.time() - t0) * 1000),
+        }
+
+    return {"ok": False, "error": f"unknown task: {task}"}
+
+
+def main():
+    model_id = os.environ.get("GEMMA_MLX_MODEL", MODEL_ID_DEFAULT)
+    eprint(f"[sidecar] loading {model_id}")
+    bundle = load_model(model_id)
+    eprint(f"[sidecar] ready — awaiting requests on stdin")
+
+    # Emit a "ready" message so the host knows the model is loaded.
+    print(json.dumps({"event": "ready", "model": model_id}), flush=True)
+
+    # Tempdir for audio uploads if needed
+    with tempfile.TemporaryDirectory(prefix="gemma_sidecar_") as tmpdir:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                req = json.loads(line)
+            except json.JSONDecodeError as exc:
+                print(json.dumps({"ok": False, "error": f"invalid JSON: {exc}"}), flush=True)
+                continue
+            try:
+                resp = handle(req, bundle)
+            except Exception as exc:
+                resp = {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
+            print(json.dumps(resp, ensure_ascii=False), flush=True)
+
+
+if __name__ == "__main__":
+    main()