Managing Model Files

Argmax SDK includes the ModelStore utility to streamline picking, downloading and compiling the model of your choice in your application.

Picking the Model

Argmax SDK includes the WhisperKitPro framework that works with the following model repositories out-of-the-box:

• .openSourceRepo: OpenAI Whisper (Open-source Version)
• .proRepo: OpenAI Whisper
• .parakeetRepo: Nvidia Parakeet

This section shows you when and how to switch between them.

Nvidia Parakeet v2

This model is 9x faster than Whisper Large v3 Turbo on English speech-to-text and achieves slightly higher accuracy.

We recommend using this model for all applications that are English-only. Here is the WhisperKitProConfig for this model:

let config = WhisperKitProConfig(
    model: "parakeet-v2_476MB",
    modelRepo: .parakeetRepo
)

Nvidia Parakeet v3

This model achieves the same speed as Nvidia Parakeet v2 but supports 25 European languages with dynamic switching: en, de, es, fr, nl, it, da, et, fi, el, hu, lv, lt, mt, pl, pt, ro, sk, sl, sv, ru, uk, bg, hr, cs.

We recommend using this model for all applications that require at least one of the 25 languages from above other than the English-only scenario. Here is the WhisperKitProConfig for this model:

let config = WhisperKitProConfig(
    model: "parakeet-v3_494MB",
    modelRepo: .parakeetRepo
)

OpenAI Whisper Large v3 Turbo

.openSourceRepo hosts the original Argmax WhisperKit models. .proRepo hosts Whisper models that are further optimized for speed and energy-efficiency compared to their .openSourceRepo counterparts. During this upgrade, accuracy remains identical while speed and energy-efficiency improve significantly.

In order to use the upgraded Whisper models, simply switch to .proRepo in your initial configuration code:

. Here is the WhisperKitProConfig for this model:

let config = WhisperKitProConfig(
    model: "large-v3-v20240930_626MB",
    modelRepo: .proRepo
)

Downloading the Model

Initialize Argmax SDK

Argmax SDK requires initialization with an Argmax API key (starts with ax_***, not axst_***) to unlock Pro models and features.

We recommend fetching your API key securely from your backend in production. However, we provide a simple obfuscator to protect against casual inspection and static analysis tools.

Assuming you use ObfuscatedKeyProvider.generateCodeExample to obfuscate your API key, you may initialize Argmax SDK as follows:

var keyProvider = ObfuscatedKeyProvider(mask: 37)  // placeholder values
keyProvider.apiKeyObfuscated = [4, 5, 6]  // placeholder values
 
guard let apiKey = keyProvider.apiKey else {
    fatalError("Missing API key")
}
 
await ArgmaxSDK.with(ArgmaxConfig(apiKey: apiKey))

Note that ArgmaxSDK.with(ArgmaxConfig(apiKey: apiKey)) requires an internet connection during first use and at least once every 30 days to maintain an active license. See this documentation page to learn more.

Initiate Download

ModelStore implements a robust model downloader. On iOS and iPadOS, this model downloader persists progress across foreground-to-background and background-to-foreground app transitions. It evens persists the download progress after the app is killed.

let modelStore = ModelStore(config:config)  // `config` from "Picking the Model"
 
do {
    let result = try await modelStore.downloadModelInBackground()
 
    switch result {
    case .started(let downloadId):
        print("Download started: \(downloadId)")
    case .resumed(let downloadId):
        print("Resuming existing download: \(downloadId)")
    case .alreadyInProgress(let downloadId):
        print("Download already running: \(downloadId)")
    case .alreadyComplete(let modelPath):
        print("Model already downloaded at: \(modelPath)")
    }
} catch {
    print("Failed to start download: \(error)")
}

Query State

modelStore.getBackgroundDownloadState returns the following state:

public struct BackgroundDownloadState {
    let downloadId: String
    let modelVariant: String
    let repoId: String
    var files: [BackgroundFileDownload]
    var status: BackgroundDownloadStatus  // .pending, .downloading, .paused, .completed, .failed
    let startedAt: Date
    var completedAt: Date?
    var overallProgress: Double  // 0.0 to 1.0
}

Here is a simple way to query download state:

// Get all active downloads
let downloads = modelStore.activeBackgroundDownloads
 
// Get state for first active download
if let download = downloads.first {
    print("Progress: \(download.overallProgress)")
    print("Files completed: \(download.completedFileCount)/\(download.totalFileCount)")
}

or

import Combine
 
var cancellables = Set<AnyCancellable>()
 
modelStore.backgroundDownloadsPublisher
    .receive(on: DispatchQueue.main)
    .sink { downloads in
        for download in downloads {
            print("\(download.modelVariant): \(Int(download.overallProgress * 100))%")
            print("Status: \(download.status)")
 
            // Individual file progress
            for file in download.files {
                print("  \(file.destinationURL.lastPathComponent): \(file.status)")
            }
        }
    }
    .store(in: &cancellables)

Pause and Resume

modelStore.pauseBackgroundDownload(downloadId)

do {
    try await modelStore.resumeBackgroundDownload(downloadId)
} catch {
    print("Failed to resume: \(error)")
}

Cancel

modelStore.cancelBackgroundDownload(downloadId, deleteProgress: false)

Compiling the Model

The downloaded model can now be compiled automatically during the first WhisperKitPro initialization:

let whisperKitPro = try await WhisperKitPro(config) // same config used during `Downloading the Model`

This may take anywhere from 15 seconds (for Parakeet models) to 90 seconds (for Whisper models). Background compilation is not yet implemented and this step must be done while the app is in the foreground.