> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argmaxinc/WhisperKit/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Selection

> Choose and download the right Whisper model for your application

# Model Selection

WhisperKit supports all official OpenAI Whisper model variants, from tiny to large-v3. Choosing the right model involves balancing accuracy, speed, and memory usage based on your application's requirements.

## Available Models

Whisper models come in different sizes, each with multilingual and English-only variants:

### Model Variants

<AccordionGroup>
  <Accordion title="Tiny (39M parameters)">
    **Best for:** Real-time streaming, constrained devices, quick prototyping

    * Fastest inference
    * Lowest memory footprint (\~75 MB)
    * Acceptable accuracy for clear audio
    * Available: `tiny` (multilingual), `tiny.en` (English-only)

    ```swift theme={null}
    let whisperKit = try await WhisperKit(model: "tiny")
    ```
  </Accordion>

  <Accordion title="Base (74M parameters)">
    **Best for:** Mobile apps, moderate accuracy requirements

    * Good balance of speed and accuracy
    * Memory footprint \~140 MB
    * Suitable for most mobile applications
    * Available: `base`, `base.en`

    ```swift theme={null}
    let whisperKit = try await WhisperKit(model: "base")
    ```
  </Accordion>

  <Accordion title="Small (244M parameters)">
    **Best for:** Production applications, higher accuracy needs

    * Good accuracy for production use
    * Memory footprint \~460 MB
    * Slower than base but more accurate
    * Available: `small`, `small.en`

    ```swift theme={null}
    let whisperKit = try await WhisperKit(model: "small")
    ```
  </Accordion>

  <Accordion title="Medium (769M parameters)">
    **Best for:** High accuracy requirements, server-side processing

    * Very good accuracy
    * Memory footprint \~1.5 GB
    * Slower inference
    * Available: `medium`, `medium.en`

    ```swift theme={null}
    let whisperKit = try await WhisperKit(model: "medium")
    ```
  </Accordion>

  <Accordion title="Large (1550M parameters)">
    **Best for:** Maximum accuracy, offline batch processing

    * Best accuracy
    * Memory footprint \~3 GB
    * Slowest inference
    * Available: `large`, `large-v2`, `large-v3`

    ```swift theme={null}
    let whisperKit = try await WhisperKit(model: "large-v3")
    ```
  </Accordion>
</AccordionGroup>

See [ModelVariant](~/workspace/source/Sources/WhisperKit/Core/Models.swift:41-90)

## ModelVariant Enum

```swift theme={null}
public enum ModelVariant: CustomStringConvertible {
    case tiny
    case tinyEn
    case base
    case baseEn
    case small
    case smallEn
    case medium
    case mediumEn
    case large
    case largev2
    case largev3
    
    var isMultilingual: Bool {
        // Returns true for multilingual models
        // Returns false for .en variants
    }
}
```

## Recommended Models

WhisperKit provides device-specific recommendations:

### Get Recommended Models

```swift theme={null}
// Get locally computed recommendations
let localSupport = WhisperKit.recommendedModels()
print("Default model: \(localSupport.default)")
print("Supported models: \(localSupport.supported)")

// Get recommendations from remote config
let remoteSupport = await WhisperKit.recommendedRemoteModels(
    from: "argmaxinc/whisperkit-coreml"
)
print("Recommended: \(remoteSupport.default)")
```

See [WhisperKit.recommendedModels](~/workspace/source/Sources/WhisperKit/Core/WhisperKit.swift:157-161) and [WhisperKit.recommendedRemoteModels](~/workspace/source/Sources/WhisperKit/Core/WhisperKit.swift:163-180)

### Device-Specific Recommendations

Recommendations are based on device hardware:

```swift theme={null}
let deviceName = WhisperKit.deviceName()
print("Running on: \(deviceName)")

// Example device identifiers:
// - "iPhone15,2" (iPhone 14 Pro)
// - "iPad13,16" (iPad Pro M2)
// - "Mac14,2" (Mac Studio M2)
```

See [WhisperKit.deviceName](~/workspace/source/Sources/WhisperKit/Core/WhisperKit.swift:142-155)

## Downloading Models

### Automatic Download

By default, WhisperKit downloads models automatically:

```swift theme={null}
// Downloads and loads the default recommended model
let whisperKit = try await WhisperKit()

// Downloads a specific model
let whisperKit = try await WhisperKit(model: "base")
```

See [WhisperKitConfig.download](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:71)

### Manual Download

Download a model without initializing WhisperKit:

```swift theme={null}
let modelFolder = try await WhisperKit.download(
    variant: "large-v3",
    from: "argmaxinc/whisperkit-coreml",
    progressCallback: { progress in
        print("Downloaded: \(progress.fractionCompleted * 100)%")
    }
)

print("Model saved to: \(modelFolder.path)")
```

See [WhisperKit.download](~/workspace/source/Sources/WhisperKit/Core/WhisperKit.swift:244-300)

### List Available Models

```swift theme={null}
let availableModels = try await WhisperKit.fetchAvailableModels(
    from: "argmaxinc/whisperkit-coreml"
)

print("Available models:")
for model in availableModels {
    print("  - \(model)")
}
```

See [WhisperKit.fetchAvailableModels](~/workspace/source/Sources/WhisperKit/Core/WhisperKit.swift:219-242)

## Local Models

Use pre-downloaded or bundled models:

```swift theme={null}
// Use a local model folder
let whisperKit = try await WhisperKit(
    modelFolder: "/path/to/model/folder",
    download: false  // Disable automatic download
)
```

See [WhisperKitConfig.modelFolder](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:19)

### Bundle Models in App

```swift theme={null}
// Get bundled model path
guard let modelPath = Bundle.main.path(
    forResource: "openai_whisper-base",
    ofType: nil
) else {
    fatalError("Model not found in bundle")
}

let whisperKit = try await WhisperKit(
    modelFolder: modelPath,
    download: false
)
```

<Warning>
  Bundling large models increases app size significantly. Consider downloading on first launch instead.
</Warning>

## Model Repositories

WhisperKit downloads models from Hugging Face repositories:

### Default Repository

```swift theme={null}
// Default: argmaxinc/whisperkit-coreml
let whisperKit = try await WhisperKit(model: "base")
```

### Custom Repository

```swift theme={null}
let whisperKit = try await WhisperKit(
    model: "base",
    modelRepo: "your-username/your-repo",
    modelToken: "hf_your_token_here"  // If repo is private
)
```

See [WhisperKitConfig.modelRepo](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:13)

### Custom Endpoint

```swift theme={null}
let config = WhisperKitConfig(
    model: "base",
    modelEndpoint: "https://your-custom-endpoint.com"
)

let whisperKit = try await WhisperKit(config)
```

See [WhisperKitConfig.modelEndpoint](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:17)

## Download Configuration

### Background Downloads

Enable background downloads for large models:

```swift theme={null}
let whisperKit = try await WhisperKit(
    model: "large-v3",
    useBackgroundDownloadSession: true
)
```

See [WhisperKitConfig.useBackgroundDownloadSession](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:73)

### Custom Download Location

```swift theme={null}
let customBase = FileManager.default.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first!

let whisperKit = try await WhisperKit(
    model: "base",
    downloadBase: customBase
)
```

See [WhisperKitConfig.downloadBase](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:10)

## Model States and Loading

### Prewarming Models

Prewarm models to reduce peak memory usage:

```swift theme={null}
let whisperKit = try await WhisperKit(
    model: "medium",
    prewarm: true  // Load and unload models sequentially
)
```

See [WhisperKitConfig.prewarm](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:42-66)

<Info>
  **Prewarming** loads models one at a time to trigger Core ML specialization without high peak memory. This doubles load time but reduces memory pressure.
</Info>

### Deferred Loading

```swift theme={null}
// Download but don't load models yet
let whisperKit = try await WhisperKit(
    model: "base",
    load: false
)

// Load later when needed
try await whisperKit.loadModels()
```

See [WhisperKitConfig.load](~/workspace/source/Sources/WhisperKit/Core/Configurations.swift:69)

### Unload Models

```swift theme={null}
// Free memory when models aren't needed
await whisperKit.unloadModels()

// Reload when needed
try await whisperKit.loadModels()
```

See [WhisperKit.unloadModels](~/workspace/source/Sources/WhisperKit/Core/WhisperKit.swift:499-511)

## Multilingual vs English-only

### When to Use Multilingual Models

* Transcribing content in multiple languages
* Language is unknown in advance
* Need automatic language detection
* Translation to English (`.translate` task)

```swift theme={null}
let whisperKit = try await WhisperKit(model: "base")  // Multilingual

let (language, _) = try await whisperKit.detectLanguage(
    audioPath: "audio.wav"
)
print("Detected: \(language)")
```

### When to Use English-only Models

* Only transcribing English audio
* Slightly faster inference
* Marginally better English accuracy

```swift theme={null}
let whisperKit = try await WhisperKit(model: "base.en")

var options = DecodingOptions(language: "en")
let results = try await whisperKit.transcribe(
    audioPath: "audio.wav",
    decodeOptions: options
)
```

## Model Performance Comparison

<Note>
  Performance varies by device. These are approximate values for reference.
</Note>

| Model    | Size   | Parameters | Relative Speed | Memory   | Accuracy  |
| -------- | ------ | ---------- | -------------- | -------- | --------- |
| tiny     | 75 MB  | 39M        | 32x            | \~150 MB | Good      |
| base     | 140 MB | 74M        | 16x            | \~250 MB | Better    |
| small    | 460 MB | 244M       | 6x             | \~600 MB | Very Good |
| medium   | 1.5 GB | 769M       | 2x             | \~1.8 GB | Excellent |
| large-v3 | 3 GB   | 1550M      | 1x             | \~3.2 GB | Best      |

## Selection Guidelines

<CardGroup cols={2}>
  <Card title="Real-time Streaming" icon="podcast">
    **Recommended:** tiny, base

    Fast enough to transcribe live audio without lag on most devices.
  </Card>

  <Card title="Mobile Apps" icon="mobile">
    **Recommended:** base, small

    Balance of accuracy and app size. Consider on-demand download instead of bundling.
  </Card>

  <Card title="High Accuracy" icon="bullseye">
    **Recommended:** medium, large-v3

    Best for offline processing, server deployments, or high-end devices.
  </Card>

  <Card title="Constrained Devices" icon="memory">
    **Recommended:** tiny

    Only option for devices with limited memory or older hardware.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/whisperkit/configuration">
    Configure compute options and advanced settings
  </Card>

  <Card title="Transcription" icon="file-audio" href="/whisperkit/transcription">
    Start transcribing with your selected model
  </Card>
</CardGroup>