TextDecoder.decodeText force-unwraps cause crashes during repeated live transcription

[yw5aj]

Summary

TextDecoder.decodeText contains force-unwraps that crash the app during repeated rapid transcription calls (e.g., live transcription preview that re-transcribes every ~200ms).

Crash Stack

EXC_BREAKPOINT / SIGTRAP
_assertionFailure → TextDecoder.decodeText(from:using:sampler:options:callback:)
→ TranscribeTask.run → WhisperKit.transcribe → WhisperKit.transcribe(audioPath:)

Root Cause

Two force-unwraps in TextDecoder.decodeText (TextDecoder.swift):

1. Line 747: decoderInputs.initialPrompt.last! — crashes if initialPrompt is empty
2. Line 829: decoderOutput.logits! — crashes if logits is nil

These are fine for single-shot transcription but become problematic during sustained rapid calls where internal state can degrade.

Reproduction

• Create two WhisperKit instances (main + live)
• Call transcribe(audioPath:) on the live instance in a tight loop (~5-10 calls/sec) during recording
• After extended use (minutes to hours), the decoder state accumulates corruption and one of the force-unwraps hits nil

Environment

• WhisperKit v0.15.0
• macOS 26.2, Apple Silicon
• Model: openai_whisper-small
• Using separate WhisperKit instances for main and live transcription

Suggested Fix

Replace the force-unwraps with guard statements that throw errors instead of crashing:

// Line 747
guard let firstToken = decoderInputs.initialPrompt.last else {
    throw WhisperError.decodingFailed("initialPrompt is empty")
}
var nextToken: Int = firstToken

// Line 829
guard let logits = decoderOutput.logits else {
    throw WhisperError.decodingLogitsFailed("Logits output is nil")
}

This would allow callers to handle the error gracefully instead of crashing the entire app.

Related

I noticed #413 and #412 are addressing thread safety — this may be related to the same class of issues.

[ZachNagengast]

Can you explain a little more what you mean by "decoder state accumulates corruption"?

[yw5aj]

Thanks for the quick response, Zach!

Here's our setup:

• We create a separate WhisperKit instance dedicated to live transcription (distinct from our main instance used for final transcription)
• During recording, we call transcribe(audioPath:) on this live instance in a loop (~every 200ms), each time passing the full accumulated audio buffer so the user sees a real-time preview
• Each call is awaited before the next starts — no concurrent access to the same instance
• After sustained use (anywhere from minutes to hours of intermittent recordings), one of the force-unwraps in decodeText hits nil and crashes the app

We don't have direct visibility into what goes nil internally. Our best guess is that something in the KV cache or decoder state degrades over many sequential transcribe() calls without a full reinitialization. We tried reinitializing the live instance between recording sessions, which reduced but didn't eliminate the crashes.

Regardless of the root cause, replacing the force-unwraps with throwing guards would let us handle the error gracefully (skip the live preview pass and continue) instead of crashing the entire app.

[m13v]

we hit this in production running continuous transcription in a macOS voice agent. the crash happens most reliably when you stop and restart transcription rapidly (like toggling voice input on/off).

the force-unwrap in decodeText assumes the token-to-text mapping always succeeds, but during rapid start/stop cycles the decoder state can get out of sync - specifically when a previous transcription task's callback fires after a new session has already reset the decoder state.

replacing the force-unwraps with guard-let fixes the crash, but there's a subtler issue: even with guards, the decoder can silently produce garbage text for one segment after a rapid restart because the token buffer has stale state from the previous session. we added an explicit decoder state reset on transcription start (not just stop) which fixed both the crash and the stale output.

for the AudioStreamTranscriber path specifically, wrapping the decode in a do-catch and logging rather than crashing is probably the right short-term fix. in a live transcription context, dropping one segment is always better than crashing the app.

[m13v]

the voice agent where we hit this is Fazm: https://github.com/m13v/fazm (https://fazm.ai) - native Swift macOS, uses WhisperKit for continuous local transcription. the rapid start/stop pattern comes from voice activation toggling.

[m13v]

We hit this exact crash in Fazm during live transcription. Our transcription preview re-runs every ~500ms, so the rapid successive calls trigger the force-unwrap race condition.

Our workaround until this is fixed upstream: wrap the transcribe call in a serial DispatchQueue and add a guard that skips new transcription requests if one is already in flight. This prevents the concurrent access that triggers the force-unwrap on the internal decoder state.

The underlying issue seems to be that TextDecoder internal state is not thread-safe. The force-unwraps at lines 747 and 751 assume the decoder state is always valid, but concurrent calls can leave it in an intermediate state. Optional binding (if let) instead of force-unwrap would at least prevent the crash, even if it means a dropped transcription frame.

A serial queue with an isTranscribing guard was enough to eliminate the crash for us in production. Not ideal since you drop frames, but better than crashing.

[m13v]

Our transcription service that works around this with the serial queue pattern: https://github.com/m13v/fazm/blob/main/Desktop/Sources/TranscriptionService.swift

Built for Fazm (https://fazm.ai/gh), which does live transcription preview during voice input.