Skip to main content

​
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 IntegrationVersion 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.

​
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: 
// Old way
let pipe = try await WhisperKit(
    modelFolder: "openai_whisper-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:
DeprecatedUse Instead
modelFolder parameterWhisperKitConfig(model:)
Direct initializer parametersWhisperKitConfig
Deprecated APIs will be removed in version 1.0.

​
Migrating from 0.7.x

​
Async/Await Required

Version 0.8.0+ requires Swift Concurrency: 
// Completion handler style
whisperKit.transcribe(audioPath: path) { result in
    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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us