# What Is the TranscriptionProvider Protocol in FluidVoice? A Swift ASR Architecture Guide

> Explore the TranscriptionProvider protocol in FluidVoice a Swift ASR architecture. Seamlessly integrate Apple Intelligence Whisper or custom back-ends without altering your code.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: architecture
- Published: 2026-07-07

---

**The `TranscriptionProvider` protocol is a Swift abstraction that standardizes speech-to-text (ASR) functionality across different transcription engines, enabling FluidVoice to swap between Apple Intelligence, Whisper, and custom back-ends without modifying UI or business logic.**

The `TranscriptionProvider` protocol serves as the architectural backbone for FluidVoice's pluggable speech recognition system. Defined in [`Sources/Fluid/Services/TranscriptionProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/TranscriptionProvider.swift), this protocol establishes a unified contract that any concrete ASR engine must fulfill. By decoupling the transcription implementation from the application's core logic, FluidVoice achieves true modularity across diverse hardware and AI back-ends.

## Core API Requirements of the TranscriptionProvider Protocol

### Essential Properties and State Checks

Every conforming type must provide three fundamental properties that enable the UI to make intelligent decisions about provider selection:

- **`name`**: A human-readable string identifying the provider (e.g., "Whisper" or "Apple Speech Analyzer")
- **`isAvailable`**: A boolean indicating hardware compatibility (e.g., Apple Silicon vs. Intel constraints)
- **`isReady`**: A boolean reflecting whether model files have been downloaded and initialized

### Model Preparation and Lifecycle Management

The `prepare(progressHandler:)` method handles asynchronous model initialization, accepting an optional closure that receives `ModelPreparationProgress` updates. This enables consistent progress bars across different download and optimization strategies. Additional lifecycle helpers include:

- **`modelsExistOnDisk()`**: Verifies local model presence before attempting initialization
- **`clearCache()`**: Removes cached data to free storage
- **`shouldClearCacheAfterCancellation`**: Determines cleanup behavior when users cancel transcription

### Transcription Methods

The protocol defines multiple transcription entry points to optimize for different use cases:

- **`transcribe(_:)`**: Performs full transcription on 16 kHz mono PCM samples, returning `ASRTranscriptionResult`
- **`transcribeStreaming(_:)`**: Optional method for low-latency live dictation
- **`transcribeFinal(_:)`**: Optional method optimized for final-output quality
- **`transcribeDictionaryTraining(_:)`**: Optional method specifically for dictionary training scenarios

### File-Based Transcription

Providers capable of handling long-form audio natively implement:

- **`prefersNativeFileTranscription`**: Boolean indicating native file support
- **`transcribeFile(at:)`**: Direct file path transcription, bypassing FluidVoice's generic chunk-and-merge logic

## Why the TranscriptionProvider Protocol Matters for FluidVoice

### Modular Architecture Without UI Coupling

By programming against the `TranscriptionProvider` interface rather than concrete implementations, FluidVoice isolates ASR dependencies. The UI layer in `AISettingsView+SpeechRecognition.swift` interacts with `any TranscriptionProvider` existentials, allowing seamless swapping between [`WhisperProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/WhisperProvider.swift) and [`AppleSpeechAnalyzerProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AppleSpeechAnalyzerProvider.swift) without recompilation of view code.

### Unified Result Types Across Engines

All providers return standardized `ASRTranscriptionResult` objects containing text and confidence scores. This uniformity enables downstream components like [`TranscriptionHistoryStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/TranscriptionHistoryStore.swift) to persist and display results identically, regardless of whether the source is on-device Whisper or cloud-based Apple Intelligence.

### Hardware Abstraction via CPUArchitecture

The protocol leverages the `CPUArchitecture` helper to abstract hardware differences between Apple Silicon and Intel Macs. Concrete implementations can make architecture-specific optimizations internally while presenting a consistent interface to the rest of the application.

## Implementing and Using the TranscriptionProvider Protocol

### Consuming a Provider in Application Code

```swift
// Assuming provider conforms to TranscriptionProvider
guard provider.isAvailable && provider.isReady else {
    return
}

// Prepare with progress reporting
try await provider.prepare { progress in
    // Update UI with progress.fractionCompleted
}

// Transcribe 16kHz mono PCM samples
let result = try await provider.transcribe(audioSamples)
print("Text: \(result.text), Confidence: \(result.confidence)")

```

### Creating a Custom Provider Implementation

```swift
import Foundation

struct CustomASRProvider: TranscriptionProvider {
    var name: String { "CustomASR" }
    var isAvailable: Bool { true }
    var isReady: Bool { /* check model files */ false }
    
    func prepare(progressHandler: ((ModelPreparationProgress) -> Void)?) async throws {
        progressHandler?(.downloading(0.5))
        // Download and load model...
        progressHandler?(.loading)
    }
    
    func transcribe(_ samples: [Float]) async throws -> ASRTranscriptionResult {
        // Inference logic here
        return ASRTranscriptionResult(text: "Hello", confidence: 0.95)
    }
}

```

### Using Providers in SwiftUI Views

```swift
struct TranscriptionView: View {
    @State private var transcription = ""
    let provider: any TranscriptionProvider

    var body: some View {
        VStack {
            Text(transcription)
            Button("Start") {
                Task {
                    try await provider.prepare { _ in }
                    let result = try await provider.transcribeStreaming(samples)
                    transcription = result.text
                }
            }
        }
    }
}

```

## Summary

- The `TranscriptionProvider` protocol in [`Sources/Fluid/Services/TranscriptionProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/TranscriptionProvider.swift) defines a standardized contract for ASR engines in FluidVoice.
- It abstracts hardware differences, model lifecycle, and transcription methods behind a unified Swift interface.
- Concrete implementations like `WhisperProvider` and `AppleSpeechAnalyzerProvider` enable plug-and-play architecture without UI changes.
- Standardized `ASRTranscriptionResult` types ensure consistent data flow to persistence layers like `TranscriptionHistoryStore`.
- Optional streaming methods (`transcribeStreaming`, `transcribeFinal`) allow providers to optimize for specific latency versus accuracy trade-offs.

## Frequently Asked Questions

### What file defines the TranscriptionProvider protocol in FluidVoice?

The protocol is defined in [`Sources/Fluid/Services/TranscriptionProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/TranscriptionProvider.swift). This file contains the core interface, default method implementations, and associated types like `ModelPreparationProgress` that enable consistent progress reporting across different ASR back-ends.

### How does FluidVoice handle different transcription engines uniformly?

By programming against the `TranscriptionProvider` protocol using Swift existentials (`any TranscriptionProvider`), the application treats Whisper, Apple Speech Analyzer, and custom back-ends identically. All providers return the same `ASRTranscriptionResult` type, ensuring UI components and `TranscriptionHistoryStore` remain agnostic to the underlying ASR implementation.

### What is the difference between transcribe() and transcribeStreaming() in the protocol?

The `transcribe(_:)` method performs complete transcription on a buffer of 16 kHz mono PCM samples, optimized for accuracy over speed. The `transcribeStreaming(_:)` method provides an optional pathway for real-time, low-latency dictation where intermediate results are acceptable. Default protocol extensions fall back to `transcribe(_:)` if streaming methods are unimplemented.

### How does the protocol support model preparation and download progress?

The `prepare(progressHandler:)` method accepts a closure that receives `ModelPreparationProgress` enum values (downloading, loading, etc.). This allows FluidVoice to display consistent progress indicators in `AISettingsView+SpeechRecognition.swift` regardless of whether the provider downloads gigabyte-sized Whisper models or initializes Apple's built-in speech analyzer.