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.

WhisperKit follows semantic versioning. Minor and patch releases maintain backward compatibility.

Current Version

The latest stable version is 0.9.0.

GitHub Releases

View all releases and changelog

Swift Package Index

Check compatibility and versions

Version 0.9.0

What’s New

TTSKit

TTSKit Integration

Version 0.9.0 introduces TTSKit as a new library product:

// 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 for usage.

Local Server

WhisperKit Local Server

OpenAI-compatible HTTP server:

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 for details.

Improvements

Other Improvements

• Enhanced streaming performance
• Better memory management
• Improved model loading
• CLI improvements
• Updated dependencies
• Bug fixes and stability improvements

Migration Steps

1. Update Package Dependency

   Update your Package.swift:

   dependencies: [
       .package(
           url: "https://github.com/argmaxinc/WhisperKit.git",
           from: "0.9.0"
       )
   ]
   
2. Add Library Products

   Choose which products you need:

   .target(
       name: "YourApp",
       dependencies: [
           "WhisperKit",  // Speech-to-text
           "TTSKit",      // Text-to-speech (new!)
       ]
   )
   
3. Update Imports

   No changes needed for existing WhisperKit code. For TTSKit:

   import TTSKit
   
   let tts = try await TTSKit()
   
4. Test Your App

   Build and test thoroughly:

   swift build
   swift test
   

Breaking Changes

Version 0.9.0 has no breaking changes for existing WhisperKit code.

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:

Before (0.8.x)

// Old way
let pipe = try await WhisperKit(
    modelFolder: "openai_whisper-large-v3"
)

After (0.9.0)

// New way
let pipe = try await WhisperKit(
    WhisperKitConfig(model: "large-v3")
)

Configuration Updates

Configuration is now centralized in WhisperKitConfig:

// 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:

Before (0.7.x)

// Completion handler style
whisperKit.transcribe(audioPath: path) { result in
    print(result.text)
}

After (0.8.0+)

// Async/await style
let result = try await pipe.transcribe(audioPath: path)
print(result.text)

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:

1. Check Model Compatibility

   Verify your model works with the current version:

   swift run whisperkit-cli transcribe \
     --model-path path/to/your/model \
     --audio-path test.wav
   
2. Regenerate if Needed

   If incompatible, regenerate using whisperkittools:

   pip install whisperkittools
   python -m whisperkittools.convert --model your-model
   
3. Update Repository

   Upload the updated model to HuggingFace:

   huggingface-cli upload username/repo model/
   

Platform-Specific Changes

macOS

macOS 15.0+ Required for TTSKit

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

#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+:

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

// Package.swift
swiftLanguageVersions: [.v5, .version("5.9")]

Platform Versions

Update your deployment targets:

// Package.swift
platforms: [
    .macOS(.v14),    // Was .v13
    .iOS(.v16),      // Was .v15
]

Testing After Migration

Common Migration Issues

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+)

Model loading fails

Solution:

1. Clear model cache:
   rm -rf ~/.cache/whisperkit/
   
2. Use new configuration:
   let config = WhisperKitConfig(model: "large-v3")
   let pipe = try await WhisperKit(config)
   
3. Check model name format (no openai_whisper- prefix needed)

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

Async/await conversion issues

Solution:

Wrap old code in Task:

// 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)
        }
    }
}

Rollback Instructions

If you need to rollback to a previous version:

1. Pin to Previous Version

   dependencies: [
       .package(
           url: "https://github.com/argmaxinc/WhisperKit.git",
           exact: "0.8.0"  // Specify exact version
       )
   ]
   
2. Update Dependencies

   swift package update
   
3. Test Thoroughly

   Ensure everything works before deploying.

Future Changes

Stay informed about upcoming changes by watching the GitHub repository and joining our Discord.

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

Discord

Get migration help from the community

GitHub Issues

Report migration problems

Email Support

Contact the team

Documentation

Browse the docs

Next Steps

Changelog

View detailed version history

FAQ

Common questions answered

Quick Start

Get started with the new version

API Reference

Explore the updated API