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

# Migration Guide

> Upgrade to the latest version of WhisperKit

## Overview

This guide helps you migrate between major versions of WhisperKit and TTSKit, highlighting breaking changes and new features.

<Note>
  WhisperKit follows semantic versioning. Minor and patch releases maintain backward compatibility.
</Note>

## Current Version

The latest stable version is **0.9.0**.

<CardGroup cols={2}>
  <Card title="GitHub Releases" icon="github" href="https://github.com/argmaxinc/WhisperKit/releases">
    View all releases and changelog
  </Card>

  <Card title="Swift Package Index" icon="swift" href="https://swiftpackageindex.com/argmaxinc/WhisperKit">
    Check compatibility and versions
  </Card>
</CardGroup>

## Version 0.9.0

### What's New

<Tabs>
  <Tab title="TTSKit">
    **TTSKit Integration**

    Version 0.9.0 introduces TTSKit as a new library product:

    ```swift theme={null}
    // Add TTSKit to your target
    .target(
        name: "YourApp",
        dependencies: ["WhisperKit", "TTSKit"]
    )
    ```

    Features:

    * On-device text-to-speech
    * Qwen3 TTS models (0.6B and 1.7B)
    * Real-time streaming playback
    * 9 voices, 10 languages
    * Style instructions (1.7B model)

    See [TTSKit Guide](/ttskit/overview) for usage.
  </Tab>

  <Tab title="Local Server">
    **WhisperKit Local Server**

    OpenAI-compatible HTTP server:

    ```bash theme={null}
    BUILD_ALL=1 swift run whisperkit-cli serve
    ```

    Features:

    * OpenAI Audio API compatibility
    * Server-Sent Events (SSE) streaming
    * Python, Swift, and curl clients
    * Auto-generated OpenAPI spec

    See [Local Server Guide](/advanced/local-server) for details.
  </Tab>

  <Tab title="Improvements">
    **Other Improvements**

    * Enhanced streaming performance
    * Better memory management
    * Improved model loading
    * CLI improvements
    * Updated dependencies
    * Bug fixes and stability improvements
  </Tab>
</Tabs>

### Migration Steps

<Steps>
  <Step title="Update Package Dependency">
    Update your `Package.swift`:

    ```swift theme={null}
    dependencies: [
        .package(
            url: "https://github.com/argmaxinc/WhisperKit.git",
            from: "0.9.0"
        )
    ]
    ```
  </Step>

  <Step title="Add Library Products">
    Choose which products you need:

    ```swift theme={null}
    .target(
        name: "YourApp",
        dependencies: [
            "WhisperKit",  // Speech-to-text
            "TTSKit",      // Text-to-speech (new!)
        ]
    )
    ```
  </Step>

  <Step title="Update Imports">
    No changes needed for existing WhisperKit code. For TTSKit:

    ```swift theme={null}
    import TTSKit

    let tts = try await TTSKit()
    ```
  </Step>

  <Step title="Test Your App">
    Build and test thoroughly:

    ```bash theme={null}
    swift build
    swift test
    ```
  </Step>
</Steps>

### Breaking Changes

<Warning>
  Version 0.9.0 has **no breaking changes** for existing WhisperKit code.
</Warning>

All existing APIs remain compatible. TTSKit is a new addition.

## Migrating from 0.8.x

### Model Repository Changes

The model repository structure has been updated:

<Tabs>
  <Tab title="Before (0.8.x)">
    ```swift theme={null}
    // Old way
    let pipe = try await WhisperKit(
        modelFolder: "openai_whisper-large-v3"
    )
    ```
  </Tab>

  <Tab title="After (0.9.0)">
    ```swift theme={null}
    // New way
    let pipe = try await WhisperKit(
        WhisperKitConfig(model: "large-v3")
    )
    ```
  </Tab>
</Tabs>

### Configuration Updates

Configuration is now centralized in `WhisperKitConfig`:

```swift theme={null}
// 0.9.0 - Cleaner configuration
let config = WhisperKitConfig(
    model: "large-v3",
    modelRepo: "argmaxinc/whisperkit-coreml",
    computeUnits: .cpuAndNeuralEngine,
    verbose: true
)
let pipe = try await WhisperKit(config)
```

### Deprecated APIs

These APIs are deprecated but still functional:

| Deprecated                    | Use Instead                |
| ----------------------------- | -------------------------- |
| `modelFolder` parameter       | `WhisperKitConfig(model:)` |
| Direct initializer parameters | `WhisperKitConfig`         |

Deprecated APIs will be removed in version 1.0.

## Migrating from 0.7.x

### Async/Await Required

Version 0.8.0+ requires Swift Concurrency:

<Tabs>
  <Tab title="Before (0.7.x)">
    ```swift theme={null}
    // Completion handler style
    whisperKit.transcribe(audioPath: path) { result in
        print(result.text)
    }
    ```
  </Tab>

  <Tab title="After (0.8.0+)">
    ```swift theme={null}
    // Async/await style
    let result = try await pipe.transcribe(audioPath: path)
    print(result.text)
    ```
  </Tab>
</Tabs>

### Minimum Version Requirements

* **macOS**: 14.0+ (was 13.0)
* **iOS**: 16.0+ (was 15.0)
* **Xcode**: 16.0+ (was 15.0)
* **Swift**: 5.9+ (was 5.7)

## Migrating Custom Models

### Update Model Format

If you have custom CoreML models from older versions:

<Steps>
  <Step title="Check Model Compatibility">
    Verify your model works with the current version:

    ```bash theme={null}
    swift run whisperkit-cli transcribe \
      --model-path path/to/your/model \
      --audio-path test.wav
    ```
  </Step>

  <Step title="Regenerate if Needed">
    If incompatible, regenerate using [whisperkittools](https://github.com/argmaxinc/whisperkittools):

    ```bash theme={null}
    pip install whisperkittools
    python -m whisperkittools.convert --model your-model
    ```
  </Step>

  <Step title="Update Repository">
    Upload the updated model to HuggingFace:

    ```bash theme={null}
    huggingface-cli upload username/repo model/
    ```
  </Step>
</Steps>

## Platform-Specific Changes

### macOS

**macOS 15.0+ Required for TTSKit**

While WhisperKit works on macOS 14.0+, TTSKit requires macOS 15.0+:

```swift theme={null}
#if os(macOS)
if #available(macOS 15.0, *) {
    let tts = try await TTSKit()
}
#endif
```

### iOS

**iOS 18.0+ Required for TTSKit**

Similarly, TTSKit on iOS requires iOS 18.0+:

```swift theme={null}
#if os(iOS)
if #available(iOS 18.0, *) {
    let tts = try await TTSKit()
}
#endif
```

WhisperKit continues to support iOS 16.0+.

## Dependency Updates

### Swift Version

Minimum Swift version is now **5.9**:

```swift theme={null}
// Package.swift
swiftLanguageVersions: [.v5, .version("5.9")]
```

### Platform Versions

Update your deployment targets:

```swift theme={null}
// Package.swift
platforms: [
    .macOS(.v14),    // Was .v13
    .iOS(.v16),      // Was .v15
]
```

## Testing After Migration

<Checklist>
  * [ ] App builds without warnings
  * [ ] All tests pass
  * [ ] Model loading works
  * [ ] Transcription accuracy unchanged
  * [ ] Performance metrics acceptable
  * [ ] Memory usage stable
  * [ ] Test on target devices
  * [ ] Verify streaming functionality
  * [ ] Check error handling
</Checklist>

## Common Migration Issues

<AccordionGroup>
  <Accordion title="Build errors after updating">
    **Solution:**

    1. Clean build folder: `⌘⇧K` in Xcode
    2. Reset package cache: `File > Packages > Reset Package Caches`
    3. Delete derived data: `rm -rf ~/Library/Developer/Xcode/DerivedData`
    4. Update to latest Xcode (16.0+)
  </Accordion>

  <Accordion title="Model loading fails">
    **Solution:**

    1. Clear model cache:
       ```bash theme={null}
       rm -rf ~/.cache/whisperkit/
       ```
    2. Use new configuration:
       ```swift theme={null}
       let config = WhisperKitConfig(model: "large-v3")
       let pipe = try await WhisperKit(config)
       ```
    3. Check model name format (no `openai_whisper-` prefix needed)
  </Accordion>

  <Accordion title="Performance regression">
    **Solution:**

    1. Check compute units configuration
    2. Try distilled models for better performance
    3. Profile memory usage
    4. Verify thermal throttling not occurring
    5. Compare with benchmarks
  </Accordion>

  <Accordion title="Async/await conversion issues">
    **Solution:**

    Wrap old code in Task:

    ```swift theme={null}
    // Old completion handler
    func transcribe(completion: @escaping (Result) -> Void) {
        // Old code
    }

    // New async/await wrapper
    func transcribe() async throws -> Result {
        return try await withCheckedThrowingContinuation { continuation in
            transcribe { result in
                continuation.resume(returning: result)
            }
        }
    }
    ```
  </Accordion>
</AccordionGroup>

## Rollback Instructions

If you need to rollback to a previous version:

<Steps>
  <Step title="Pin to Previous Version">
    ```swift theme={null}
    dependencies: [
        .package(
            url: "https://github.com/argmaxinc/WhisperKit.git",
            exact: "0.8.0"  // Specify exact version
        )
    ]
    ```
  </Step>

  <Step title="Update Dependencies">
    ```bash theme={null}
    swift package update
    ```
  </Step>

  <Step title="Test Thoroughly">
    Ensure everything works before deploying.
  </Step>
</Steps>

## Future Changes

<Note>
  Stay informed about upcoming changes by watching the [GitHub repository](https://github.com/argmaxinc/WhisperKit) and joining our [Discord](https://discord.gg/G5F5GZGecC).
</Note>

### Version 1.0 Roadmap

Planned for version 1.0:

* Removal of deprecated APIs
* Stable API guarantees
* Additional model formats
* Enhanced streaming capabilities
* More TTS voices and languages

## Getting Help

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.gg/G5F5GZGecC">
    Get migration help from the community
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/argmaxinc/WhisperKit/issues">
    Report migration problems
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:info@argmaxinc.com">
    Contact the team
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Browse the docs
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Changelog" icon="clock-rotate-left" href="/resources/changelog">
    View detailed version history
  </Card>

  <Card title="FAQ" icon="circle-question" href="/resources/faq">
    Common questions answered
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get started with the new version
  </Card>

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