fix(onboarding): Parakeet model download — real progress, integrity verification, corrupt-cache repair - #246
Merged
Conversation
…erification, corrupt-cache repair
A fresh install could land in a permanently stuck state: a torn first-run
download leaves the FluidAudio repo folder present, FluidAudio's single-file
presence gate then skips the download forever, and MLModel.load fails on every
launch with a raw 'Unable to load model: file://…' in the menu bar — while
onboarding showed a green 'Your speech model is ready' (folder-presence ==
installed) and offered no repair.
- ParakeetModelIntegrity (core, tested): per-variant required-file manifests
(unified tiers incl. per-tier encoder suffix, EOU) + generic mlmodelc
coremldata.bin rule for the multilingual layout. 'Installed' now means
verified complete everywhere (AppState, tracker, onboarding, Models pane).
- Real download progress: FluidAudio 0.15.5's ProgressHandler threaded through
ParakeetBridge → engine readiness (throttled per whole percent) → menu bar
percentage, onboarding determinate bar + percent caption, Models pane status.
Compile phase reported as .loading ('Optimizing the model for your Mac…').
- Corrupt-cache auto-repair: a load failure with files present purges the
variant's repo folder and redownloads once, inside the single-flight load
task. Typed ParakeetBridgeError (download vs load; cancellation passes
through untouched) maps failures to user copy — no more file:// URLs in UI.
- Honest failure flag: prefetch failure now reported whenever the engine is
still current (present-but-corrupt included); onboarding precedence flipped
so a failure outranks bytes-on-disk (failed card + Retry, not a green lie).
- Settings → Models: per-variant verified badges, live download/compile/failure
status row, and an explicit 'Redownload Model' repair button.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
initcore0
added a commit
that referenced
this pull request
Aug 4, 2026
…ch TDT v3 and CTC biasing models (#247) PR #246 closed the torn-cache trap (FluidAudio's presence-only download gate skips redownload over a torn cache forever) for the STREAMING variants only. The batch path had both gaps: - ParakeetBridge.loadBatch now threads FluidAudio's ProgressHandler through (same ParakeetLoadPhase seam as loadStreamSession) and rethrows as the typed ParakeetBridgeError, cancellation passing through untyped. - ParakeetFileEngine.loadTaskOnMain gets the purge-and-redownload-once repair inside the single-flight load task: a .load failure with the parakeet-tdt-0.6b-v3 repo folder present purges it and retries once. Download errors and cancellation never purge. Real download percentages + verified-completeness-based initial status flow to onWorkerStatus. - ParakeetVocabularyBiaser.ensureLoaded gets the same repair for the CTC-WS model (parakeet-ctc-110m-coreml), still fail-open; a cancelled transcription no longer latches loadFailed. The manifest also requires tokenizer.json, which FluidAudio's own gate never checks (models load, tokenization fails). - ParakeetModelIntegrity: batch + CTC repo manifests and an explicit-manifest verdict overload (core, tested); FluidAudioModelsLocator repo-folder verdict helper; ParakeetProgressThrottle shared by both engines. Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem (field report, fresh Mac)
Menu bar: "Model unavailable — Unable to load model: file:///Users/…/FluidAudio/Models/parakeet-unified-en-0.6b/parakeet_unified_encoder_st…" — permanently, on every launch.
Root cause chain:
.mlmodelcdirectory present but incomplete.fileExistscheck on that directory → the download is skipped forever.MLModel.loadthrows; the raw CoreML error (with thefile://path) leaked verbatim into the menu bar.ProgressHandleron every entry point we use).Fix
ParakeetModelIntegrity(core, unit-tested) — per-variant required-file manifests (unified tiers incl. the per-tier encoder suffix, EOU) + a genericcoremldata.bin-per-.mlmodelcrule for the multilingual layout. Installed = verified complete everywhere (prefetch, readiness tracker, onboarding, Models pane).ProgressHandlerthreaded throughParakeetBridge→ engine readiness (throttled to whole percents) → menu-bar percentage, onboarding determinate bar + percent caption, Models-pane status row. The CoreML compile phase reports as.loading("Optimizing the model for your Mac…").ParakeetBridgeError(download vs load) maps every failure to user copy; nofile://in the UI.parakeetPrefetchFailednow fires whenever the still-current engine failed (present-but-corrupt included), and onboarding precedence is flipped: failure outranks bytes-on-disk (Retry card instead of the green lie).Tests
ParakeetModelIntegrityTests(manifests, torn-bundle detection, tier-encoder mismatch, generic multilingual rule, verdict→badge mapping, no-file-URL copy guard).OnboardingModelStatusTests: failure-beats-installed (fails without the fix), real-fraction pass-through, zero-progress-stays-indeterminate.swift test: 2700 tests green../build.sh(full) andscripts/dev-app.sh(lean) both build.Not covered by automation: the engine repair path itself (FluidAudio is app-only, outside
swift test) — needs a live pass: deletecoremldata.binfrom the encoder bundle under~/Library/Application Support/FluidAudio/Models/parakeet-unified-en-0.6b/and relaunch; the app should purge, redownload with a visible percentage, and land Ready.🤖 Generated with Claude Code