Can FluidVoice Use Local ASR Models Without an Internet Connection?

Yes. FluidVoice can run speech‑to‑text entirely offline when a compatible local Whisper model is pre‑installed and properly configured.

FluidVoice, an open‑source voice interface framework from altic-dev/FluidVoice, is designed with offline-first ASR architecture. The transcription pipeline delegates to WhisperProvider, which can load and execute GGUF‑format models locally without ever contacting a remote server. This article explains exactly how offline ASR works in FluidVoice, how to configure it, and which source files control the behavior.

---

How FluidVoice Enables Offline ASR

The core capability resides in ASRService.swift, which acts as a central observable routing transcription requests to configured providers. For local execution, WhisperProvider handles model discovery, validation, and inference without network dependencies.

Local Model Loading Mechanism

WhisperProvider searches the app-specific model directory for valid GGUF files:

• whisper-tiny.gguf — smallest, fastest, lowest accuracy
• whisper-base.gguf — balanced size and quality
• Qwen 3 multilingual models — extended language support

When a valid model is present, WhisperProvider instantiates the Whisper backend directly. The ModelDownloader component is bypassed entirely, ensuring zero network traffic.

Runtime Memory Validation

Before loading, WhisperProvider performs a memory-availability check (see lines 203–204 in WhisperProvider.swift). If the device cannot accommodate the selected model, the provider aborts with a clear error message. No silent fallback to online services occurs.

---

Configuring FluidVoice for Offline-Only Operation

Users control offline behavior through two mechanisms: model selection and download policy.

Selecting a Local Model Override

The VoiceEngineSettingsViewModel.swift exposes an enum for model overrides. Users can force a specific offline-compatible model regardless of network state.

// VoiceEngineSettingsViewModel.swift (simplified)
enum ModelOption: String, CaseIterable {
    case whisperTiny = "Whisper Tiny (offline)"
    case whisperBase = "Whisper Base (offline)"
    case qwenMultilingual = "Qwen 3 (offline)"
}

@Published var selectedModel: ModelOption = .whisperTiny {
    didSet { 
        ASRService.shared.setModelOverride(selectedModel) 
    }
}

The UI binds to this property via a SwiftUI Picker, giving users explicit control over which local model loads.

Disabling Automatic Downloads

To guarantee offline-only operation, disable the auto-download toggle in SettingsView.swift:

Toggle("Auto-download missing models", isOn: $settings.autoDownloadModels)
    .onChange(of: settings.autoDownloadModels) { enabled in
        ASRService.shared.autoDownloadEnabled = enabled
    }

When autoDownloadEnabled is false, WhisperProvider validates cached files, removes corrupted or legacy copies, and proceeds with local inference. No network requests are initiated.

---

Programmatic Configuration for Offline ASR

Developers integrating FluidVoice can hardcode offline behavior using WhisperProvider directly:

import Fluid

// Locate the default model storage directory
let modelDirectory = FileManager.default.urls(
    for: .applicationSupportDirectory,
    in: .userDomainMask
).first!

// Initialize provider with explicit local model selection
let provider = WhisperProvider(
    modelDirectory: modelDirectory,
    modelOverride: .whisperTiny  // Forces tiny.gguf, ignores network
)

// Bind to global ASR service
ASRService.shared.useProvider(provider)

// Begin transcription — completely offline
ASRService.shared.startTranscribing()

This pattern ensures predictable behavior in air-gapped environments or privacy-sensitive deployments.

---

Key Source Files Controlling Offline ASR

File	Responsibility
Sources/Fluid/Services/ASRService.swift	Central coordinator; routes requests to active provider
Sources/Fluid/Services/WhisperProvider.swift	GGUF model loading, memory checks, optional downloading
Sources/Fluid/UI/AISettings/VoiceEngineSettingsViewModel.swift	Model selection UI and override logic
Sources/Fluid/UI/SettingsView.swift	Auto-download toggle and user-facing settings

Understanding these files allows precise control over FluidVoice's ASR behavior in offline scenarios.

---

Summary

• FluidVoice supports fully offline ASR through WhisperProvider and local GGUF models.
• Model files must be placed in the application support directory before use.
• User settings in VoiceEngineSettingsViewModel and SettingsView control offline enforcement.
• Memory validation prevents crashes but never triggers network fallbacks.
• Developer APIs allow hardcoded offline configurations for embedded or secure deployments.

---

Frequently Asked Questions

Which ASR models work offline in FluidVoice?

FluidVoice supports any Whisper GGUF model and the Qwen 3 multilingual model for offline use. Common choices include whisper-tiny.gguf for speed and whisper-base.gguf for improved accuracy. The model file must be present in the app-specific model directory before transcription begins.

How does FluidVoice handle missing local models when offline?

If no valid model exists and the device is offline, WhisperProvider returns an error after validation. Since autoDownloadEnabled is disabled, no network request occurs. The transcription request fails gracefully with a descriptive message rather than falling back to cloud ASR.

Can I force FluidVoice to never use internet-based ASR?

Yes. Set ASRService.shared.autoDownloadEnabled = false programmatically, or disable "Auto-download missing models" in the Settings UI. Combine this with a modelOverride pointing to a pre-installed local model. With these two settings, WhisperProvider never attempts network access.

What happens if my device lacks RAM for the chosen model?

WhisperProvider performs a runtime memory check before model instantiation (lines 203–204 in WhisperProvider.swift). If available memory is insufficient, the provider aborts with a clear error. No partial loading or degraded performance occurs—you must select a smaller model or free system resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}