> ## 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.

# Installation

> Add WhisperKit and TTSKit to your Swift project

WhisperKit and TTSKit are separate library products in the same Swift package. Add the package once and choose the products you need.

## Prerequisites

### System Requirements

<AccordionGroup>
  <Accordion title="WhisperKit Requirements">
    * macOS 14.0 or later (for development)
    * Xcode 16.0 or later
    * Target platforms:
      * iOS 16.0+
      * macOS 13.0+
      * watchOS 10.0+
      * visionOS 1.0+
  </Accordion>

  <Accordion title="TTSKit Requirements">
    * macOS 15.0 or later (for development)
    * Xcode 16.0 or later
    * Target platforms:
      * iOS 18.0+
      * macOS 15.0+
  </Accordion>
</AccordionGroup>

### Device Recommendations

For optimal performance:

* **Minimum**: iPhone 12 or M1 Mac (for WhisperKit)
* **Recommended**: iPhone 14 Pro or M2 Mac or later
* Models automatically scale to device capabilities

<Note>
  WhisperKit automatically selects the best model variant for your device. Older devices will use smaller, faster models while newer devices can leverage larger, more accurate models.
</Note>

## Swift Package Manager (Xcode)

The easiest way to add WhisperKit to your project is through Xcode's Swift Package Manager integration.

<Steps>
  <Step title="Open Package Dependencies">
    In Xcode, navigate to **File > Add Package Dependencies...**
  </Step>

  <Step title="Enter Repository URL">
    Paste the WhisperKit repository URL:

    ```
    https://github.com/argmaxinc/whisperkit
    ```
  </Step>

  <Step title="Select Version">
    Choose the version range or specific version. We recommend using the latest release:

    * **Dependency Rule**: "Up to Next Major Version"
    * **Version**: 0.9.0 (or latest)
  </Step>

  <Step title="Choose Library Products">
    Select the libraries you need:

    * ✅ **WhisperKit** - for speech-to-text
    * ✅ **TTSKit** - for text-to-speech
    * Or select both if you need both features

    Click **Add Package**
  </Step>

  <Step title="Add to Target">
    Select your target and confirm the library products should be added to it.
  </Step>
</Steps>

## Swift Package Manager (Package.swift)

If you're building a Swift package or prefer editing `Package.swift` directly:

<Steps>
  <Step title="Add Package Dependency">
    Add WhisperKit to your `Package.swift` dependencies array:

    ```swift Package.swift theme={null}
    let package = Package(
        name: "YourPackage",
        platforms: [
            .iOS(.v16),
            .macOS(.v13),
        ],
        dependencies: [
            .package(
                url: "https://github.com/argmaxinc/WhisperKit.git", 
                from: "0.9.0"
            ),
        ],
        targets: [
            // Your targets here
        ]
    )
    ```
  </Step>

  <Step title="Add Target Dependencies">
    Add the library products to your target's dependencies:

    ```swift Package.swift theme={null}
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "WhisperKit", package: "WhisperKit"),  // Speech-to-text
            .product(name: "TTSKit", package: "WhisperKit"),      // Text-to-speech
        ]
    ),
    ```

    <Tip>
      Only include the products you need. If you only need speech recognition, omit TTSKit from your dependencies to reduce build times.
    </Tip>
  </Step>

  <Step title="Resolve Dependencies">
    Run the following command to fetch and resolve dependencies:

    ```bash theme={null}
    swift package resolve
    ```
  </Step>
</Steps>

## Command Line Interface (Homebrew)

For command-line usage, install the WhisperKit CLI tool:

```bash theme={null}
brew install whisperkit-cli
```

The CLI includes both WhisperKit and TTSKit functionality:

```bash theme={null}
# Transcribe audio
whisperkit-cli transcribe --audio-path audio.wav

# Generate speech
whisperkit-cli tts --text "Hello from WhisperKit" --play

# Start API server
whisperkit-cli serve --port 8080
```

## Build from Source

For development or to access the latest features:

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/argmaxinc/whisperkit.git
    cd whisperkit
    ```
  </Step>

  <Step title="Setup Environment">
    Install dependencies and setup the development environment:

    ```bash theme={null}
    make setup
    ```
  </Step>

  <Step title="Download Models">
    Download a specific model for testing:

    ```bash theme={null}
    # Download a single model
    make download-model MODEL=large-v3

    # Or download all models (requires significant disk space)
    make download-models
    ```

    <Warning>
      Ensure [git-lfs](https://git-lfs.com) is installed before downloading models:

      ```bash theme={null}
      brew install git-lfs
      git lfs install
      ```
    </Warning>
  </Step>

  <Step title="Build and Run">
    ```bash theme={null}
    # Run WhisperKit transcription
    swift run whisperkit-cli transcribe \
      --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
      --audio-path "path/to/audio.wav"

    # Run TTSKit generation
    swift run whisperkit-cli tts \
      --text "Hello from WhisperKit" \
      --play

    # Stream from microphone
    swift run whisperkit-cli transcribe \
      --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
      --stream
    ```
  </Step>
</Steps>

## Verify Installation

Create a simple test file to verify the installation:

<CodeGroup>
  ```swift iOS theme={null}
  import SwiftUI
  import WhisperKit
  import TTSKit

  struct ContentView: View {
      @State private var status = "Testing WhisperKit..."
      
      var body: some View {
          VStack {
              Text(status)
                  .padding()
          }
          .task {
              await testInstallation()
          }
      }
      
      func testInstallation() async {
          do {
              // Test WhisperKit
              let whisper = try await WhisperKit()
              status = "WhisperKit loaded: \(whisper.modelVariant)"
              
              // Test TTSKit
              let tts = try await TTSKit()
              status += "\nTTSKit loaded successfully!"
          } catch {
              status = "Error: \(error.localizedDescription)"
          }
      }
  }
  ```

  ```swift macOS theme={null}
  import Foundation
  import WhisperKit
  import TTSKit

  Task {
      do {
          // Test WhisperKit initialization
          print("Loading WhisperKit...")
          let whisper = try await WhisperKit()
          print("✅ WhisperKit loaded: \(whisper.modelVariant)")
          
          // Test TTSKit initialization
          print("Loading TTSKit...")
          let tts = try await TTSKit()
          print("✅ TTSKit loaded successfully!")
          
      } catch {
          print("❌ Error: \(error.localizedDescription)")
      }
  }

  RunLoop.main.run()
  ```
</CodeGroup>

<Note>
  The first time you initialize WhisperKit or TTSKit, it will automatically download the recommended model for your device. This may take several minutes depending on your internet connection.
</Note>

## Offline Usage

To bundle models with your app for offline usage:

<Steps>
  <Step title="Download Models">
    Use the CLI or Swift code to download models to a local directory:

    ```swift theme={null}
    let modelFolder = try await WhisperKit.download(
        variant: "large-v3",
        downloadBase: localCacheURL
    )
    ```
  </Step>

  <Step title="Add Models to Bundle">
    Add the downloaded model folders to your Xcode project:

    1. Drag the model folder into your project
    2. Ensure "Copy items if needed" is checked
    3. Add to your app target
  </Step>

  <Step title="Initialize with Local Path">
    ```swift theme={null}
    let modelPath = Bundle.main.resourceURL!
        .appendingPathComponent("openai_whisper-large-v3")
        .path

    let whisper = try await WhisperKit(
        modelFolder: modelPath,
        download: false  // Skip download, use local only
    )
    ```
  </Step>
</Steps>

<Warning>
  Model files can be large (up to 6 GB for large-v3). Consider app size limits and user experience when bundling models.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Build errors with Swift Package Manager">
    * Ensure Xcode 16.0+ is installed
    * Clean build folder: **Product > Clean Build Folder** (⇧⌘K)
    * Reset package caches: **File > Packages > Reset Package Caches**
    * Check minimum deployment target matches requirements
  </Accordion>

  <Accordion title="Model download fails">
    * Check internet connectivity
    * Verify HuggingFace Hub is accessible
    * Try setting a custom `downloadBase` URL
    * Check available disk space (models can be several GB)
  </Accordion>

  <Accordion title="Runtime errors on device">
    * Verify device meets minimum OS requirements
    * Check that the model variant is appropriate for device memory
    * Enable verbose logging: `WhisperKit(verbose: true)`
    * Check available memory and close other apps
  </Accordion>

  <Accordion title="CoreML compilation warnings">
    * First launch may show CoreML compilation messages - this is normal
    * Use `prewarmModels()` on first launch to compile models in background
    * Subsequent launches will be faster as compiled models are cached
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Build your first speech recognition and TTS app
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the complete API documentation
  </Card>
</CardGroup>