Skip to content

Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more

Setup an onboarding journey for new users

grohith327a225a7794619
diff --git a/Sources/Fluid/AppDelegate.swift b/Sources/Fluid/AppDelegate.swift
index 24bba4c3..1c4e2c5c 100644
--- a/Sources/Fluid/AppDelegate.swift
+++ b/Sources/Fluid/AppDelegate.swift
@@ -23,16 +23,19 @@ class AppDelegate: NSObject, NSApplicationDelegate {
// Repository: https://github.com/altic-dev/Fluid-oss
self.updater = AppUpdater(owner: "altic-dev", repo: "Fluid-oss")
- // Request accessibility permissions for global hotkey monitoring
- self.requestAccessibilityPermissions()
-
// Initialize app settings (dock visibility, etc.)
SettingsStore.shared.initializeAppSettings()
AnalyticsService.shared.bootstrap()
- let isFirstOpen = AnalyticsIdentityStore.shared.ensureFirstOpenRecorded()
- if isFirstOpen {
+ let isTrueFirstOpen = AnalyticsIdentityStore.shared.ensureFirstOpenRecorded()
+ SettingsStore.shared.bootstrapOnboardingState(isTrueFirstOpen: isTrueFirstOpen)
+
+ if SettingsStore.shared.shouldPromptAccessibilityOnLaunch {
+ self.requestAccessibilityPermissions()
+ }
+
+ if isTrueFirstOpen {
AnalyticsService.shared.capture(.appFirstOpen)
}
AnalyticsService.shared.capture(
diff --git a/Sources/Fluid/ContentView.swift b/Sources/Fluid/ContentView.swift
index 1a837017..c2f6345a 100644
--- a/Sources/Fluid/ContentView.swift
+++ b/Sources/Fluid/ContentView.swift
@@ -142,13 +142,19 @@ struct ContentView: View {
var body: some View {
let layout = AnyView(
- NavigationSplitView(columnVisibility: self.$columnVisibility) {
- self.sidebarView
- .navigationSplitViewColumnWidth(min: 220, ideal: 250, max: 300)
- } detail: {
- self.detailView
+ Group {
+ if self.settings.shouldShowOnboarding {
+ self.onboardingOnlyView
+ } else {
+ NavigationSplitView(columnVisibility: self.$columnVisibility) {
+ self.sidebarView
+ .navigationSplitViewColumnWidth(min: 220, ideal: 250, max: 300)
+ } detail: {
+ self.detailView
+ }
+ .navigationSplitViewStyle(.balanced)
+ }
}
- .navigationSplitViewStyle(.balanced)
)
let tracked = layout.withMouseTracking(self.mouseTracker)
@@ -551,12 +557,14 @@ struct ContentView: View {
self.selectedSidebarItem = .customDictionary
}
.toolbar {
- ToolbarItem(placement: .primaryAction) {
- Button(action: self.openIssueReportingPage) {
- Image(systemName: "ladybug.fill")
+ if !self.settings.shouldShowOnboarding {
+ ToolbarItem(placement: .primaryAction) {
+ Button(action: self.openIssueReportingPage) {
+ Image(systemName: "ladybug.fill")
+ }
+ .help("Report an issue")
+ .accessibilityLabel("Report an issue")
}
- .help("Report an issue")
- .accessibilityLabel("Report an issue")
}
}
.overlay(alignment: .center) {}
@@ -725,6 +733,7 @@ struct ContentView: View {
private func handleMenuBarNavigation(_ destination: MenuBarNavigationDestination?) {
guard let destination else { return }
defer { menuBarManager.requestedNavigationDestination = nil }
+ guard !self.settings.shouldShowOnboarding else { return }
switch destination {
case .preferences:
@@ -919,6 +928,31 @@ struct ContentView: View {
}
}
+ private var onboardingOnlyView: some View {
+ OnboardingFlowView(
+ currentStep: Binding(
+ get: { self.settings.onboardingCurrentStep },
+ set: { self.settings.onboardingCurrentStep = $0 }
+ ),
+ accessibilityEnabled: self.accessibilityEnabled,
+ markAISkipped: {
+ self.settings.onboardingAISkipped = true
+ },
+ markPlaygroundValidated: {
+ self.settings.onboardingPlaygroundValidated = true
+ self.settings.playgroundUsed = true
+ self.playgroundUsed = true
+ },
+ finishOnboarding: {
+ self.completeOnboardingIfPossible()
+ },
+ openAccessibilitySettings: self.openAccessibilitySettings,
+ menuBarManager: self.menuBarManager,
+ theme: self.theme
+ )
+ .environmentObject(self.appServices)
+ }
+
// MARK: - Welcome Guide
private var welcomeView: some View {
@@ -2213,6 +2247,44 @@ struct ContentView: View {
}
}
+ private var onboardingVoiceModelReady: Bool {
+ self.asr.isAsrReady || self.asr.modelsExistOnDisk || SettingsStore.shared.selectedSpeechModel.isInstalled
+ }
+
+ private var onboardingMicrophoneReady: Bool {
+ self.asr.micStatus == .authorized
+ }
+
+ private var onboardingAccessibilityReady: Bool {
+ self.accessibilityEnabled
+ }
+
+ private var onboardingAIReady: Bool {
+ self.settings.onboardingAISkipped || DictationAIPostProcessingGate.isConfigured()
+ }
+
+ private var onboardingPlaygroundReady: Bool {
+ self.settings.onboardingPlaygroundValidated
+ }
+
+ private var canCompleteOnboarding: Bool {
+ self.onboardingVoiceModelReady &&
+ self.onboardingMicrophoneReady &&
+ self.onboardingAccessibilityReady &&
+ self.onboardingAIReady &&
+ self.onboardingPlaygroundReady
+ }
+
+ @MainActor
+ private func completeOnboardingIfPossible() {
+ guard self.canCompleteOnboarding else { return }
+
+ self.settings.onboardingCompleted = true
+
+ let isOnboarded = self.asr.isAsrReady || self.asr.modelsExistOnDisk
+ self.selectedSidebarItem = isOnboarded ? .preferences : .welcome
+ }
+
private func labelFor(status: AVAuthorizationStatus) -> String {
switch status {
case .authorized: return "Microphone: Authorized"
diff --git a/Sources/Fluid/Persistence/SettingsStore.swift b/Sources/Fluid/Persistence/SettingsStore.swift
index d28a174b..9284d124 100644
--- a/Sources/Fluid/Persistence/SettingsStore.swift
+++ b/Sources/Fluid/Persistence/SettingsStore.swift
@@ -60,6 +60,10 @@ final class SettingsStore: ObservableObject {
static let updatePromptSnoozedUntil = "UpdatePromptSnoozedUntil"
static let snoozedUpdateVersion = "SnoozedUpdateVersion"
static let playgroundUsed = "PlaygroundUsed"
+ static let onboardingCompleted = "OnboardingCompleted"
+ static let onboardingCurrentStep = "OnboardingCurrentStep"
+ static let onboardingAISkipped = "OnboardingAISkipped"
+ static let onboardingPlaygroundValidated = "OnboardingPlaygroundValidated"
// Command Mode Keys
static let commandModeSelectedModel = "CommandModeSelectedModel"
@@ -1311,6 +1315,95 @@ final class SettingsStore: ObservableObject {
set { self.defaults.set(newValue, forKey: Keys.playgroundUsed) }
}
+ var onboardingCompleted: Bool {
+ get {
+ if self.defaults.object(forKey: Keys.onboardingCompleted) == nil {
+ return true
+ }
+ return self.defaults.bool(forKey: Keys.onboardingCompleted)
+ }
+ set {
+ objectWillChange.send()
+ self.defaults.set(newValue, forKey: Keys.onboardingCompleted)
+ }
+ }
+
+ var onboardingCurrentStep: Int {
+ get {
+ let raw = self.defaults.integer(forKey: Keys.onboardingCurrentStep)
+ return max(0, min(4, raw))
+ }
+ set {
+ objectWillChange.send()
+ let clamped = max(0, min(4, newValue))
+ self.defaults.set(clamped, forKey: Keys.onboardingCurrentStep)
+ }
+ }
+
+ var onboardingAISkipped: Bool {
+ get { self.defaults.bool(forKey: Keys.onboardingAISkipped) }
+ set {
+ objectWillChange.send()
+ self.defaults.set(newValue, forKey: Keys.onboardingAISkipped)
+ }
+ }
+
+ var onboardingPlaygroundValidated: Bool {
+ get { self.defaults.bool(forKey: Keys.onboardingPlaygroundValidated) }
+ set {
+ objectWillChange.send()
+ self.defaults.set(newValue, forKey: Keys.onboardingPlaygroundValidated)
+ }
+ }
+
+ var shouldShowOnboarding: Bool {
+ !self.onboardingCompleted
+ }
+
+ var shouldPromptAccessibilityOnLaunch: Bool {
+ !self.shouldShowOnboarding
+ }
+
+ func bootstrapOnboardingState(isTrueFirstOpen: Bool) {
+ guard self.defaults.object(forKey: Keys.onboardingCompleted) == nil else { return }
+
+ objectWillChange.send()
+
+ let hasLegacyUsageSignals = self.hasLegacyUsageSignals()
+ let shouldShowForThisInstall = isTrueFirstOpen && !hasLegacyUsageSignals
+
+ if shouldShowForThisInstall {
+ self.defaults.set(false, forKey: Keys.onboardingCompleted)
+ self.defaults.set(0, forKey: Keys.onboardingCurrentStep)
+ self.defaults.set(false, forKey: Keys.onboardingAISkipped)
+ self.defaults.set(false, forKey: Keys.onboardingPlaygroundValidated)
+ } else {
+ self.defaults.set(true, forKey: Keys.onboardingCompleted)
+ self.defaults.set(0, forKey: Keys.onboardingCurrentStep)
+ self.defaults.set(false, forKey: Keys.onboardingAISkipped)
+ self.defaults.set(false, forKey: Keys.onboardingPlaygroundValidated)
+ }
+ }
+
+ func resetOnboardingProgress() {
+ objectWillChange.send()
+ self.defaults.set(false, forKey: Keys.onboardingCompleted)
+ self.defaults.set(0, forKey: Keys.onboardingCurrentStep)
+ self.defaults.set(false, forKey: Keys.onboardingAISkipped)
+ self.defaults.set(false, forKey: Keys.onboardingPlaygroundValidated)
+ self.defaults.set(false, forKey: Keys.playgroundUsed)
+ }
+
+ private func hasLegacyUsageSignals() -> Bool {
+ if self.defaults.object(forKey: Keys.playgroundUsed) != nil { return true }
+ if self.defaults.object(forKey: Keys.hotkeyShortcutKey) != nil { return true }
+ if self.defaults.object(forKey: Keys.selectedSpeechModel) != nil { return true }
+ if self.defaults.object(forKey: Keys.selectedProviderID) != nil { return true }
+ if self.defaults.object(forKey: Keys.customDictionaryEntries) != nil { return true }
+ if !self.savedProviders.isEmpty { return true }
+ return false
+ }
+
// MARK: - Command Mode Settings
var commandModeSelectedModel: String? {
diff --git a/Sources/Fluid/Services/ASRService.swift b/Sources/Fluid/Services/ASRService.swift
index 81b72c27..c695651e 100644
--- a/Sources/Fluid/Services/ASRService.swift
+++ b/Sources/Fluid/Services/ASRService.swift
@@ -1944,7 +1944,7 @@ final class ASRService: ObservableObject {
self.isDownloadingModel = true
self.isLoadingModel = false
self.downloadProgress = nil
- self.startParakeetDownloadProgressMonitor()
+ self.stopDownloadProgressMonitor()
DebugLogger.shared.info("⬇️ DOWNLOADING model...", source: "ASRService")
}
}
@@ -1958,8 +1958,9 @@ final class ASRService: ObservableObject {
progressHandler: { [weak self] progress in
DispatchQueue.main.async {
let clamped = max(0.0, min(1.0, progress))
- self?.downloadProgress = clamped
- externalProgressHandler?(clamped)
+ let monotonic = max(self?.downloadProgress ?? 0.0, clamped)
+ self?.downloadProgress = monotonic
+ externalProgressHandler?(monotonic)
}
}
)
diff --git a/Sources/Fluid/Services/FluidAudioProvider.swift b/Sources/Fluid/Services/FluidAudioProvider.swift
index e9301d95..5274f5fe 100644
--- a/Sources/Fluid/Services/FluidAudioProvider.swift
+++ b/Sources/Fluid/Services/FluidAudioProvider.swift
@@ -2,6 +2,18 @@ import Foundation
#if arch(arm64)
import FluidAudio
+private actor DownloadProgressSink {
+ private let handler: ((Double) -> Void)?
+
+ init(handler: ((Double) -> Void)?) {
+ self.handler = handler
+ }
+
+ func emit(_ progress: Double) {
+ self.handler?(progress)
+ }
+}
+
/// TranscriptionProvider implementation using FluidAudio (optimized for Apple Silicon)
/// This wraps the existing FluidAudio-based ASR for use on Apple Silicon Macs.
final class FluidAudioProvider: TranscriptionProvider {
@@ -41,7 +53,26 @@ final class FluidAudioProvider: TranscriptionProvider {
source: "FluidAudioProvider"
)
DebugLogger.shared.debug("FluidAudioProvider: target cache directory=\(cacheDirectory.path)", source: "FluidAudioProvider")
- progressHandler?(0.05)
+ let progressSink = DownloadProgressSink(handler: progressHandler)
+ await progressSink.emit(0.05)
+
+ // AsrModels.downloadAndLoad() is a single await without granular callbacks.
+ // Emit synthetic incremental progress so the UI updates smoothly during long downloads.
+ let progressTicker = Task(priority: .utility) {
+ var stagedProgress = 0.05
+ let stageCap = 0.82
+ while !Task.isCancelled {
+ try? await Task.sleep(nanoseconds: 250_000_000)
+ if Task.isCancelled { break }
+ if stagedProgress >= stageCap { continue }
+
+ let remaining = stageCap - stagedProgress
+ let step = max(0.008, remaining * 0.12)
+ stagedProgress = min(stageCap, stagedProgress + step)
+ await progressSink.emit(stagedProgress)
+ }
+ }
+ defer { progressTicker.cancel() }
let loadStart = Date()
// Download and load models
@@ -53,17 +84,19 @@ final class FluidAudioProvider: TranscriptionProvider {
// Default to v3 (Multilingual)
models = try await AsrModels.downloadAndLoad(version: .v3)
}
+ progressTicker.cancel()
DebugLogger.shared.debug(
"FluidAudioProvider: Models downloadAndLoad returned in \(String(format: "%.2f", Date().timeIntervalSince(loadStart)))s",
source: "FluidAudioProvider"
)
- progressHandler?(0.70)
+ await progressSink.emit(0.88)
// Streaming manager: lightweight, no vocab boosting → avoids CTC/ANE contention
// that causes intermittent SIGTRAP crashes during streaming inference.
let streamingManager = AsrManager(config: ASRConfig.default)
try await streamingManager.initialize(models: models)
DebugLogger.shared.debug("FluidAudioProvider: Streaming AsrManager initialized", source: "FluidAudioProvider")
+ await progressSink.emit(0.94)
self.isWordBoostingActive = false
self.boostedVocabularyTermsCount = 0
@@ -109,9 +142,10 @@ final class FluidAudioProvider: TranscriptionProvider {
self.streamingAsrManager = streamingManager
self.finalAsrManager = finalManager
+ await progressSink.emit(0.98)
self.isReady = true
- progressHandler?(1.0)
+ await progressSink.emit(1.0)
DebugLogger.shared.info(
"FluidAudioProvider: Models ready [isWordBoostingActive=\(self.isWordBoostingActive), terms=\(self.boostedVocabularyTermsCount)]",
source: "FluidAudioProvider"
diff --git a/Sources/Fluid/UI/AISettings/VoiceEngineSettingsViewModel.swift b/Sources/Fluid/UI/AISettings/VoiceEngineSettingsViewModel.swift
index 0768d68e..884f5724 100644
--- a/Sources/Fluid/UI/AISettings/VoiceEngineSettingsViewModel.swift
+++ b/Sources/Fluid/UI/AISettings/VoiceEngineSettingsViewModel.swift
@@ -129,7 +129,7 @@ final class VoiceEngineSettingsViewModel: ObservableObject {
Task { @MainActor in
// Only update progress if we're still downloading this specific model
guard let self, self.downloadingModel?.id == downloadingModelId else { return }
- self.downloadProgress = progress
+ self.downloadProgress = max(self.downloadProgress, progress)
}
})
diff --git a/Sources/Fluid/UI/AISettingsView+SpeechRecognition.swift b/Sources/Fluid/UI/AISettingsView+SpeechRecognition.swift
index 47718e9a..2dce538a 100644
--- a/Sources/Fluid/UI/AISettingsView+SpeechRecognition.swift
+++ b/Sources/Fluid/UI/AISettingsView+SpeechRecognition.swift
@@ -11,8 +11,13 @@ extension VoiceEngineSettingsView {
// MARK: - Speech Recognition Card
var speechRecognitionCard: some View {
- let activeModel = self.settings.selectedSpeechModel
- let otherModels = self.viewModel.filteredSpeechModels.filter { $0 != activeModel }
+ let selectedModel = self.settings.selectedSpeechModel
+ let activeModel = selectedModel.isInstalled ? selectedModel : nil
+ let hasActiveModel = activeModel != nil
+ let otherModels = self.viewModel.filteredSpeechModels.filter { model in
+ guard let activeModel else { return true }
+ return model != activeModel
+ }
return ThemedCard(hoverEffect: false) {
VStack(alignment: .leading, spacing: 14) {
@@ -102,18 +107,30 @@ extension VoiceEngineSettingsView {
// Active + Other models list
VStack(alignment: .leading, spacing: 10) {
- VStack(alignment: .leading, spacing: 6) {
- Text("Active Model")
- .font(.callout)
- .fontWeight(.semibold)
- .foregroundStyle(.secondary)
- self.speechModelCard(for: activeModel)
+ if let activeModel {
+ VStack(alignment: .leading, spacing: 6) {
+ Text("Active Model")
+ .font(.callout)
+ .fontWeight(.semibold)
+ .foregroundStyle(.secondary)
+ self.speechModelCard(for: activeModel)
+ }
+ } else {
+ VStack(alignment: .leading, spacing: 6) {
+ Text("Active Model")
+ .font(.callout)
+ .fontWeight(.semibold)
+ .foregroundStyle(.secondary)
+ Label("No active model yet. Download and activate one below.", systemImage: "arrow.down.circle")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
}
Divider().padding(.vertical, 2)
VStack(alignment: .leading, spacing: 6) {
- Text("Other Models")
+ Text(hasActiveModel ? "Other Models" : "Available Models")
.font(.callout)
.fontWeight(.semibold)
.foregroundStyle(.secondary)
@@ -283,7 +300,8 @@ extension VoiceEngineSettingsView {
func speechModelCard(for model: SettingsStore.SpeechModel) -> some View {
let isSelected = self.viewModel.previewSpeechModel == model
- let isActive = self.viewModel.isActiveSpeechModel(model)
+ let isConfiguredActive = self.viewModel.isActiveSpeechModel(model)
+ let isActive = isConfiguredActive && model.isInstalled
return HStack(alignment: .top, spacing: 10) {
Circle()
@@ -344,7 +362,7 @@ extension VoiceEngineSettingsView {
.font(.caption2)
.foregroundStyle(.secondary)
}
- } else if (self.viewModel.asr.isDownloadingModel || self.viewModel.asr.isLoadingModel) && isActive && !self.viewModel.asr.isAsrReady {
+ } else if (self.viewModel.asr.isDownloadingModel || self.viewModel.asr.isLoadingModel) && isConfiguredActive && !self.viewModel.asr.isAsrReady {
// Active model is loading/downloading (for Activate flow)
VStack(alignment: .trailing, spacing: 4) {
if let progress = self.viewModel.asr.downloadProgress, self.viewModel.asr.isDownloadingModel {
@@ -364,7 +382,7 @@ extension VoiceEngineSettingsView {
}
} else if model.isInstalled {
HStack(spacing: 8) {
- if isActive {
+ if isConfiguredActive {
let isLoading = (self.viewModel.asr.isLoadingModel || self.viewModel.asr.isDownloadingModel) && !self.viewModel.asr.isAsrReady
Text(isLoading ? "Loading…" : "Active")
.font(.caption2)
diff --git a/Sources/Fluid/UI/SettingsView.swift b/Sources/Fluid/UI/SettingsView.swift
index b324becc..7b61f0db 100644
--- a/Sources/Fluid/UI/SettingsView.swift
+++ b/Sources/Fluid/UI/SettingsView.swift
@@ -1077,6 +1077,23 @@ struct SettingsView: View {
Text("Crash diagnostics are written to Library/Logs/Fluid/Fluid.log by default.")
.font(.caption)
.foregroundStyle(.secondary)
+
+ #if DEBUG
+ Divider().padding(.vertical, 8)
+
+ Button(role: .destructive) {
+ self.settings.resetOnboardingProgress()
+ DebugLogger.shared.info("Developer action: onboarding reset", source: "SettingsView")
+ } label: {
+ Label("Reset Onboarding (Dev)", systemImage: "arrow.counterclockwise")
+ }
+ .buttonStyle(.bordered)
+ .controlSize(.regular)
+
+ Text("Developer-only action. Immediately re-enters first-run onboarding flow.")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ #endif
}
}
.padding(16)
diff --git a/Sources/Fluid/UI/WelcomeView.swift b/Sources/Fluid/UI/WelcomeView.swift
index d61e3f2d..fc079de8 100644
--- a/Sources/Fluid/UI/WelcomeView.swift
+++ b/Sources/Fluid/UI/WelcomeView.swift
@@ -532,3 +532,740 @@ struct WelcomeView: View {
}
}
}
+
+struct OnboardingFlowView: View {
+ @EnvironmentObject var appServices: AppServices
+ private var asr: ASRService { self.appServices.asr }
+ @ObservedObject private var settings = SettingsStore.shared
+
+ @Binding var currentStep: Int
+ let accessibilityEnabled: Bool
+ let markAISkipped: () -> Void
+ let markPlaygroundValidated: () -> Void
+ let finishOnboarding: () -> Void
+ let openAccessibilitySettings: () -> Void
+ let menuBarManager: MenuBarManager
+ let theme: AppTheme
+
+ @State private var playgroundText: String = ""
+ @State private var isPlaygroundRecording: Bool = false
+
+ private enum Step: Int, CaseIterable {
+ case voiceModel = 0
+ case microphone = 1
+ case accessibility = 2
+ case aiEnhancement = 3
+ case playground = 4
+
+ var title: String {
+ switch self {
+ case .voiceModel:
+ return "Download Voice Model"
+ case .microphone:
+ return "Grant Microphone Access"
+ case .accessibility:
+ return "Enable Accessibility"
+ case .aiEnhancement:
+ return "Set Up AI Enhancement"
+ case .playground:
+ return "Run Playground Test"
+ }
+ }
+
+ var subtitle: String {
+ switch self {
+ case .voiceModel:
+ return CPUArchitecture.isAppleSilicon
+ ? "Recommended for your Mac: Parakeet TDT v3. Download it once to continue."
+ : "Recommended for your Mac: Whisper. Download it once to continue."
+ case .microphone:
+ return "Allow FluidVoice to capture audio from your microphone."
+ case .accessibility:
+ return "Allow FluidVoice to type transcriptions into other apps."
+ case .aiEnhancement:
+ return "Optional: Configure AI post-processing or skip this step."
+ case .playground:
+ return "Record a quick sample to validate your setup before finishing."
+ }
+ }
+ }
+
+ private var step: Step {
+ Step(rawValue: self.currentStep) ?? .voiceModel
+ }
+
+ private var progressValue: Double {
+ Double(self.step.rawValue + 1) / Double(Step.allCases.count)
+ }
+
+ private var recommendedOnboardingModel: SettingsStore.SpeechModel {
+ CPUArchitecture.isAppleSilicon ? .parakeetTDT : .whisperBase
+ }
+
+ private var recommendedOnboardingModelDisplayName: String {
+ CPUArchitecture.isAppleSilicon ? "Parakeet TDT v3" : "Whisper"
+ }
+
+ private var recommendedModelReasonText: String {
+ CPUArchitecture.isAppleSilicon
+ ? "Best for Apple Silicon: highest speed and accuracy for daily dictation."
+ : "Best for Intel Macs: dependable Whisper quality with broad compatibility."
+ }
+
+ private var onboardingModelOptions: [SettingsStore.SpeechModel] {
+ let candidates: [SettingsStore.SpeechModel] = CPUArchitecture.isAppleSilicon
+ ? [.parakeetTDT, .parakeetTDTv2, .whisperBase, .whisperSmall]
+ : [.whisperBase, .whisperTiny, .whisperSmall, .whisperMedium]
+
+ var seenModelIDs = Set<String>()
+ return candidates.filter { model in
+ guard SettingsStore.SpeechModel.availableModels.contains(model) else { return false }
+ return seenModelIDs.insert(model.id).inserted
+ }
+ }
+
+ private var onboardingAlternativeModels: [SettingsStore.SpeechModel] {
+ self.onboardingModelOptions.filter { $0 != self.recommendedOnboardingModel }
+ }
+
+ private var isRecommendedModelSelected: Bool {
+ self.isOnboardingModelSelected(self.recommendedOnboardingModel)
+ }
+
+ private var isRecommendedModelDownloaded: Bool {
+ self.isOnboardingModelDownloaded(self.recommendedOnboardingModel)
+ }
+
+ private var isPreparingRecommendedModel: Bool {
+ self.isPreparingOnboardingModel(self.recommendedOnboardingModel)
+ }
+
+ private var isRecommendedModelReady: Bool {
+ self.isOnboardingModelReady(self.recommendedOnboardingModel)
+ }
+
+ private var isVoiceModelReady: Bool {
+ self.isOnboardingModelReady(self.settings.selectedSpeechModel)
+ }
+
+ private var isMicrophoneReady: Bool {
+ self.asr.micStatus == .authorized
+ }
+
+ private var isAccessibilityReady: Bool {
+ self.accessibilityEnabled
+ }
+
+ private var isAIReady: Bool {
+ self.settings.onboardingAISkipped || DictationAIPostProcessingGate.isConfigured()
+ }
+
+ private var isPlaygroundReady: Bool {
+ self.settings.onboardingPlaygroundValidated
+ }
+
+ private var canContinue: Bool {
+ switch self.step {
+ case .voiceModel:
+ return self.isVoiceModelReady
+ case .microphone:
+ return self.isMicrophoneReady
+ case .accessibility:
+ return self.isAccessibilityReady
+ case .aiEnhancement:
+ return self.isAIReady
+ case .playground:
+ return self.isPlaygroundReady
+ }
+ }
+
+ private var primaryButtonTitle: String {
+ switch self.step {
+ case .playground:
+ return "Finish Setup"
+ case .aiEnhancement:
+ return "Continue to Playground"
+ default:
+ return "Continue"
+ }
+ }
+
+ var body: some View {
+ VStack(spacing: 0) {
+ self.header
+ Divider()
+ self.stepContent
+ .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+ Divider()
+ self.footer
+ }
+ .background {
+ ZStack {
+ self.theme.palette.windowBackground
+ .opacity(0.98)
+ .ignoresSafeArea()
+
+ Rectangle()
+ .fill(self.theme.materials.window)
+ .opacity(0.75)
+ .ignoresSafeArea()
+ }
+ }
+ .onAppear {
+ Task { @MainActor in
+ self.asr.micStatus = AVCaptureDevice.authorizationStatus(for: .audio)
+ await self.asr.checkIfModelsExistAsync()
+ }
+ }
+ }
+
+ private var header: some View {
+ VStack(alignment: .leading, spacing: 12) {
+ Text("Welcome to FluidVoice")
+ .font(.title2.weight(.bold))
+ .foregroundStyle(self.theme.palette.primaryText)
+
+ Text(self.step.subtitle)
+ .font(.subheadline)
+ .foregroundStyle(self.theme.palette.secondaryText)
+
+ HStack {
+ Text("Step \(self.step.rawValue + 1) of \(Step.allCases.count)")
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(.secondary)
+ Spacer()
+ Text(self.step.title)
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(self.theme.palette.accent)
+ }
+
+ ProgressView(value: self.progressValue)
+ .tint(self.theme.palette.accent)
+ }
+ .padding(24)
+ }
+
+ @ViewBuilder
+ private var stepContent: some View {
+ switch self.step {
+ case .voiceModel:
+ self.voiceModelStep
+ case .microphone:
+ self.microphoneStep
+ case .accessibility:
+ self.accessibilityStep
+ case .aiEnhancement:
+ self.aiEnhancementStep
+ case .playground:
+ self.playgroundStep
+ }
+ }
+
+ private var voiceModelStep: some View {
+ ScrollView {
+ VStack(alignment: .leading, spacing: 16) {
+ ThemedCard(style: .standard) {
+ VStack(alignment: .leading, spacing: 14) {
+ HStack(spacing: 10) {
+ Image(systemName: self.isVoiceModelReady ? "checkmark.circle.fill" : "cpu")
+ .foregroundStyle(self.isVoiceModelReady ? Color.fluidGreen : self.theme.palette.accent)
+
+ VStack(alignment: .leading, spacing: 3) {
+ Text("Recommended for this Mac: \(self.recommendedOnboardingModelDisplayName)")
+ .font(.body.weight(.semibold))
+ .foregroundStyle(self.theme.palette.primaryText)
+
+ Text(self.recommendedModelReasonText)
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+
+ Spacer()
+ }
+
+ HStack(spacing: 10) {
+ Label(self.recommendedOnboardingModel.downloadSize, systemImage: "internaldrive")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+
+ Text(self.recommendedOnboardingModel.languageSupport)
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+
+ if self.isPreparingRecommendedModel {
+ VStack(alignment: .leading, spacing: 6) {
+ if self.asr.isDownloadingModel, let progress = self.asr.downloadProgress {
+ ProgressView(value: progress)
+ .tint(self.theme.palette.accent)
+ Text("Downloading \(Int(progress * 100))%")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ } else {
+ HStack(spacing: 8) {
+ ProgressView()
+ .controlSize(.small)
+ Text("Loading model…")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ }
+ }
+ }
+
+ HStack(spacing: 10) {
+ if self.isRecommendedModelReady {
+ Label(
+ "Model downloaded and loaded",
+ systemImage: "checkmark.seal.fill"
+ )
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(Color.fluidGreen)
+ } else if self.isRecommendedModelDownloaded {
+ Label(
+ self.isRecommendedModelSelected ? "Model downloaded. Click to finish loading." : "Model downloaded",
+ systemImage: "arrow.triangle.2.circlepath"
+ )
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(.secondary)
+ } else {
+ Label("Model not downloaded yet", systemImage: "arrow.down.circle")
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(.secondary)
+ }
+
+ Spacer()
+
+ Button(self.onboardingModelActionButtonTitle(for: self.recommendedOnboardingModel)) {
+ self.prepareOnboardingModel(self.recommendedOnboardingModel)
+ }
+ .buttonStyle(.borderedProminent)
+ .tint(self.theme.palette.accent)
+ .disabled(self.asr.isRunning || self.isPreparingRecommendedModel || self.isRecommendedModelReady)
+ }
+
+ if self.isVoiceModelReady && !self.isRecommendedModelSelected {
+ Text("A different model is already configured. You can continue, or switch to the recommended model.")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+
+ if !self.onboardingAlternativeModels.isEmpty {
+ Divider().padding(.vertical, 2)
+
+ Text("Other popular options")
+ .font(.subheadline.weight(.semibold))
+ .foregroundStyle(self.theme.palette.primaryText)
+
+ VStack(spacing: 8) {
+ ForEach(Array(self.onboardingAlternativeModels.prefix(3))) { model in
+ self.onboardingModelOptionRow(for: model)
+ }
+ }
+ }
+
+ Text("You can switch models later in Voice Engine settings.")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ .padding(16)
+ }
+ }
+ .padding(24)
+ }
+ }
+
+ private var microphoneStep: some View {
+ ScrollView {
+ VStack(alignment: .leading, spacing: 16) {
+ ThemedCard(style: .standard) {
+ VStack(alignment: .leading, spacing: 14) {
+ HStack(spacing: 10) {
+ Circle()
+ .fill(self.isMicrophoneReady ? Color.fluidGreen : self.theme.palette.warning)
+ .frame(width: 10, height: 10)
+
+ Text(self.isMicrophoneReady ? "Microphone access granted" : "Microphone access required")
+ .font(.body.weight(.medium))
+ .foregroundStyle(self.isMicrophoneReady ? .primary : self.theme.palette.warning)
+
+ Spacer()
+
+ if !self.isMicrophoneReady {
+ Button(self.microphoneActionButtonTitle) {
+ self.handleMicrophoneAction()
+ }
+ .buttonStyle(.borderedProminent)
+ .tint(self.theme.palette.accent)
+ }
+ }
+
+ if !self.isMicrophoneReady {
+ VStack(alignment: .leading, spacing: 6) {
+ Text("How to enable microphone access")
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(.secondary)
+
+ if self.asr.micStatus == .notDetermined {
+ Text("1. Click \"Grant Access\"")
+ Text("2. Choose \"Allow\" in the system dialog")
+ } else {
+ Text("1. Click \"Open Settings\"")
+ Text("2. Find FluidVoice in the microphone list")
+ Text("3. Toggle FluidVoice on")
+ }
+ }
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ }
+ .padding(16)
+ }
+ }
+ .padding(24)
+ }
+ }
+
+ private var accessibilityStep: some View {
+ ScrollView {
+ VStack(alignment: .leading, spacing: 16) {
+ ThemedCard(style: .standard) {
+ VStack(alignment: .leading, spacing: 14) {
+ HStack(spacing: 10) {
+ Circle()
+ .fill(self.isAccessibilityReady ? Color.fluidGreen : self.theme.palette.warning)
+ .frame(width: 10, height: 10)
+
+ Text(self.isAccessibilityReady ? "Accessibility enabled" : "Accessibility permission required")
+ .font(.body.weight(.medium))
+ .foregroundStyle(self.isAccessibilityReady ? .primary : self.theme.palette.warning)
+
+ Spacer()
+
+ if !self.isAccessibilityReady {
+ Button("Enable Accessibility") {
+ self.openAccessibilitySettings()
+ }
+ .buttonStyle(.borderedProminent)
+ .tint(self.theme.palette.accent)
+ }
+ }
+
+ if !self.isAccessibilityReady {
+ VStack(alignment: .leading, spacing: 6) {
+ Text("How to enable accessibility")
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(.secondary)
+ Text("1. Click \"Enable Accessibility\"")
+ Text("2. Add or enable FluidVoice in Accessibility")
+ Text("3. Return here and continue")
+ }
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ }
+ .padding(16)
+ }
+ }
+ .padding(24)
+ }
+ }
+
+ private var aiEnhancementStep: some View {
+ VStack(alignment: .leading, spacing: 10) {
+ HStack(spacing: 8) {
+ Image(systemName: self.isAIReady ? "checkmark.circle.fill" : "sparkles")
+ .foregroundStyle(self.isAIReady ? Color.fluidGreen : self.theme.palette.accent)
+ Text(self.isAIReady
+ ? "AI enhancement is ready (or skipped)"
+ : "Configure AI enhancement or skip to continue")
+ .font(.subheadline.weight(.medium))
+ .foregroundStyle(self.isAIReady ? Color.fluidGreen : .secondary)
+ }
+ .padding(.horizontal, 24)
+ .padding(.top, 16)
+
+ AIEnhancementSettingsScreen(menuBarManager: self.menuBarManager, theme: self.theme)
+ }
+ }
+
+ private var playgroundStep: some View {
+ ScrollView {
+ VStack(alignment: .leading, spacing: 16) {
+ ThemedCard(style: .standard) {
+ VStack(alignment: .leading, spacing: 14) {
+ HStack {
+ Text("Quick Playground Test")
+ .font(.headline)
+ Spacer()
+ if self.isPlaygroundRecording {
+ Text("Recording...")
+ .font(.caption.weight(.semibold))
+ .foregroundStyle(.red)
+ }
+ }
+
+ Button(self.isPlaygroundRecording ? "Stop Recording" : "Start Recording") {
+ self.togglePlaygroundRecording()
+ }
+ .buttonStyle(PremiumButtonStyle(isRecording: self.isPlaygroundRecording))
+ .disabled(self.asr.micStatus != .authorized)
+
+ TextEditor(text: Binding(
+ get: { self.playgroundText },
+ set: { _ in }
+ ))
+ .font(.body)
+ .frame(height: 170)
+ .padding(10)
+ .background(
+ RoundedRectangle(cornerRadius: 8, style: .continuous)
+ .fill(self.theme.palette.cardBackground)
+ .overlay(
+ RoundedRectangle(cornerRadius: 8, style: .continuous)
+ .stroke(self.theme.palette.cardBorder.opacity(0.6), lineWidth: 1)
+ )
+ )
+ .scrollContentBackground(.hidden)
+
+ if self.isPlaygroundReady {
+ HStack(spacing: 6) {
+ Image(systemName: "checkmark.circle.fill")
+ .foregroundStyle(Color.fluidGreen)
+ Text("Playground test passed. You can finish setup.")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ } else {
+ Text("Record a short sample and confirm transcription appears here.")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ }
+ .padding(16)
+ }
+ }
+ .padding(24)
+ }
+ }
+
+ private var footer: some View {
+ HStack(spacing: 10) {
+ if self.step.rawValue > 0 {
+ Button("Back") {
+ self.goBack()
+ }
+ .buttonStyle(.bordered)
+ }
+
+ Spacer()
+
+ if self.step == .aiEnhancement {
+ Button("Skip for now") {
+ self.markAISkipped()
+ self.goNext()
+ }
+ .buttonStyle(.bordered)
+ }
+
+ Button(self.primaryButtonTitle) {
+ self.handlePrimaryAction()
+ }
+ .buttonStyle(.borderedProminent)
+ .tint(self.theme.palette.accent)
+ .disabled(!self.canContinue)
+ }
+ .padding(20)
+ }
+
+ private var microphoneActionButtonTitle: String {
+ switch self.asr.micStatus {
+ case .notDetermined:
+ return "Grant Access"
+ case .denied, .restricted:
+ return "Open Settings"
+ default:
+ return "Grant Access"
+ }
+ }
+
+ private func isOnboardingModelSelected(_ model: SettingsStore.SpeechModel) -> Bool {
+ self.settings.selectedSpeechModel == model
+ }
+
+ private func isOnboardingModelReady(_ model: SettingsStore.SpeechModel) -> Bool {
+ self.isOnboardingModelSelected(model) && model.isInstalled && self.asr.isAsrReady
+ }
+
+ private func isOnboardingModelDownloaded(_ model: SettingsStore.SpeechModel) -> Bool {
+ model.isInstalled || (self.isOnboardingModelSelected(model) && (self.asr.isAsrReady || self.asr.modelsExistOnDisk))
+ }
+
+ private func isPreparingOnboardingModel(_ model: SettingsStore.SpeechModel) -> Bool {
+ self.isOnboardingModelSelected(model) && (self.asr.isDownloadingModel || (self.asr.isLoadingModel && !self.asr.isAsrReady))
+ }
+
+ private func onboardingModelActionButtonTitle(for model: SettingsStore.SpeechModel) -> String {
+ let isSelected = self.isOnboardingModelSelected(model)
+ let isDownloaded = self.isOnboardingModelDownloaded(model)
+ let isReady = self.isOnboardingModelReady(model)
+
+ if self.isPreparingOnboardingModel(model) {
+ return self.asr.isLoadingModel ? "Loading..." : "Downloading..."
+ }
+ if isReady {
+ return "Ready"
+ }
+ if isDownloaded {
+ return isSelected ? "Load" : "Use"
+ }
+ return isSelected ? "Download" : "Use & Download"
+ }
+
+ private func prepareOnboardingModel(_ model: SettingsStore.SpeechModel) {
+ guard !self.asr.isRunning else { return }
+
+ if self.settings.selectedSpeechModel != model {
+ self.settings.selectedSpeechModel = model
+ self.asr.resetTranscriptionProvider()
+ }
+
+ Task { @MainActor in
+ do {
+ try await self.asr.ensureAsrReady()
+ } catch {
+ DebugLogger.shared.error("Failed to prepare onboarding voice model \(model.displayName): \(error)", source: "OnboardingFlowView")
+ }
+ await self.asr.checkIfModelsExistAsync()
+ }
+ }
+
+ private func onboardingModelOptionRow(for model: SettingsStore.SpeechModel) -> some View {
+ let isSelected = self.isOnboardingModelSelected(model)
+ let isDownloaded = self.isOnboardingModelDownloaded(model)
+ let isPreparing = self.isPreparingOnboardingModel(model)
+ let isReady = self.isOnboardingModelReady(model)
+
+ return VStack(alignment: .leading, spacing: 8) {
+ HStack(alignment: .top, spacing: 10) {
+ VStack(alignment: .leading, spacing: 4) {
+ HStack(spacing: 6) {
+ Text(model.displayName)
+ .font(.callout.weight(.semibold))
+ .foregroundStyle(self.theme.palette.primaryText)
+
+ if isSelected {
+ Text("Selected")
+ .font(.caption2.weight(.semibold))
+ .padding(.horizontal, 6)
+ .padding(.vertical, 2)
+ .background(Capsule().fill(self.theme.palette.accent.opacity(0.18)))
+ .foregroundStyle(self.theme.palette.accent)
+ }
+ }
+
+ Text(model.cardDescription)
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ .lineLimit(2)
+
+ HStack(spacing: 10) {
+ Label(model.downloadSize, systemImage: "internaldrive")
+ .font(.caption2)
+ .foregroundStyle(.secondary)
+ Text(model.languageSupport)
+ .font(.caption2)
+ .foregroundStyle(.secondary)
+ }
+ }
+
+ Spacer(minLength: 8)
+
+ Button(self.onboardingModelActionButtonTitle(for: model)) {
+ self.prepareOnboardingModel(model)
+ }
+ .buttonStyle(.bordered)
+ .controlSize(.small)
+ .disabled(self.asr.isRunning || isPreparing || isReady)
+ }
+
+ if isPreparing {
+ if self.asr.isDownloadingModel, let progress = self.asr.downloadProgress {
+ ProgressView(value: progress)
+ .tint(self.theme.palette.accent)
+ Text("Downloading \(Int(progress * 100))%")
+ .font(.caption2)
+ .foregroundStyle(.secondary)
+ } else {
+ Text("Loading model...")
+ .font(.caption2)
+ .foregroundStyle(.secondary)
+ }
+ } else if isReady {
+ Label("Downloaded and loaded", systemImage: "checkmark.circle.fill")
+ .font(.caption2.weight(.semibold))
+ .foregroundStyle(Color.fluidGreen)
+ } else if isDownloaded {
+ Label(isSelected ? "Downloaded. Click Load to finish." : "Downloaded", systemImage: "arrow.triangle.2.circlepath")
+ .font(.caption2.weight(.semibold))
+ .foregroundStyle(.secondary)
+ }
+ }
+ .padding(10)
+ .background(
+ RoundedRectangle(cornerRadius: 10, style: .continuous)
+ .fill(self.theme.palette.cardBackground.opacity(isSelected ? 0.82 : 0.55))
+ .overlay(
+ RoundedRectangle(cornerRadius: 10, style: .continuous)
+ .stroke(
+ isSelected ? self.theme.palette.accent.opacity(0.45) : self.theme.palette.cardBorder.opacity(0.32),
+ lineWidth: 1
+ )
+ )
+ )
+ }
+
+ private func handleMicrophoneAction() {
+ if self.asr.micStatus == .notDetermined {
+ self.asr.requestMicAccess()
+ } else {
+ self.asr.openSystemSettingsForMic()
+ }
+ }
+
+ private func goBack() {
+ self.currentStep = max(0, self.currentStep - 1)
+ }
+
+ private func goNext() {
+ self.currentStep = min(Step.allCases.count - 1, self.currentStep + 1)
+ }
+
+ private func handlePrimaryAction() {
+ if self.step == .playground {
+ if !self.settings.onboardingPlaygroundValidated {
+ self.markPlaygroundValidated()
+ }
+ self.finishOnboarding()
+ return
+ }
+ self.goNext()
+ }
+
+ private func togglePlaygroundRecording() {
+ Task { @MainActor in
+ if self.isPlaygroundRecording {
+ let transcribed = await self.asr.stop()
+ self.isPlaygroundRecording = false
+ self.playgroundText = ASRService.applyGAAVFormatting(transcribed)
+ if !self.playgroundText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+ self.markPlaygroundValidated()
+ }
+ } else {
+ self.playgroundText = ""
+ await self.asr.start()
+ self.isPlaygroundRecording = self.asr.isRunning
+ }
+ }
+ }
+}