Choose When the Model Starts Loading
Do not make every visitor download speech-model files simply because they opened an article. Let the user start the demo, or begin loading when the demo is close to the viewport and clearly explain what will be downloaded. Keep the article text and navigation available while the model initializes so a slow device does not turn the entire page into a wait screen.
Measure the actual assets in the deployed build before quoting a download size. A model's parameter count is not the same as its network transfer size: quantization, voice files, tokenizer data, compression, and browser runtime assets all affect what the visitor receives.
Progress UI
- Show phases such as “Preparing”, “Downloading voice files”, “Starting the audio engine”, and “Ready”.
- Show a percentage only when the download provides enough information to calculate one; otherwise use an indeterminate indicator.
- Keep the widget and surrounding page responsive while the model loads.
A single percentage can hide what is actually slow. A phase label helps users distinguish a network delay from browser initialization, and a short explanation can set expectations without promising a fixed completion time. For assistive technology, expose phase changes through a polite status message and avoid announcing every percentage increment.
Retries and Error States
- Explain whether the request failed during download, model preparation, or audio playback.
- Offer an explicit retry after the user can correct a likely network problem; do not retry forever in the background.
- Keep a small pre-rendered sample or text-only explanation available when the full model cannot start.
Before a retry, release any partial runtime state that the library does not reuse safely. If you support a smaller fallback model, label its voice or quality difference instead of silently switching. A useful error tells the person what to try next, such as reconnecting, closing memory-heavy tabs, or choosing the lightweight sample.
Caching and Storage
- Use stable, versioned asset URLs so browsers can reuse files and new model versions can invalidate old ones.
- Tell users that browser caches can be cleared or evicted; do not promise a permanent offline copy unless you implement one.
- Defer non-critical assets until they are needed.
Test both a cold visit and a warm visit with the same browser profile. On the first visit, confirm the page communicates the download and survives a reload or interrupted connection. On a later visit, confirm cached files reduce waiting without leaving the interface stuck on a stale “Downloading” state.
Accessibility
- Use a native progress element or a progress bar with a real value; do not invent a percentage when the total is unknown.
- Ensure keyboard focus stays predictable and visible during state changes.
- Announce meaningful status changes politely and provide a text error with a keyboard-accessible retry button.
Example State Flow
// Example state machine
idle → initializing → downloading (measured or indeterminate) → ready
↘ error with recovery action → retry
Keep the displayed state tied to the real loader events. If the model library exposes only “loading” and “ready”, use those labels rather than presenting separate phases that the application cannot verify.
Metrics to Watch
- Cold and warm time from a user action to the first playable result.
- Download success rate, failure stage, and user-initiated retry rate.
- Memory-related failures across the browsers and devices you support.
Measure these without collecting the text a visitor enters. If you add analytics, record coarse performance events such as the model version, load phase, and elapsed time, and describe that collection in the site's privacy policy.
Frequently Asked Questions
How do I show model loading progress?
Show phases such as Preparing and Downloading. Display a percentage only when the total can be measured; otherwise use an indeterminate indicator and a status message.
What if the download fails?
Offer an explicit retry after a likely network issue can be corrected, and keep a small pre-rendered sample or text-only fallback available.
How do I keep the page usable while loading?
Keep navigation and article text interactive, and start model loading on request or when the demo is near the viewport.
Related Articles
Author: Kokoro Web Team • Last updated 2026-10-15