How do I show model loading progress?

Use a determinate progress bar with percentage and human‑readable states like Initializing, Downloading, Compiling.

What if the download fails?

Offer a one‑click retry with exponential backoff and a low‑bandwidth fallback clip.

How do I keep the page usable while loading?

Keep the rest of the article interactive; defer non‑critical assets until after first interaction.

Embedding TTS Demos: UX for 150MB Models, Progress Bars, and Resilience

Large model downloads can feel slow without feedback. This guide shows how to embed Kokoro demos with smooth progress indicators, retry logic, accessibility, and caching hints so users stay engaged while the first load completes.

Progress UI

Show determinate progress with percentage and human‑readable states (e.g., “Initializing”, “Downloading”, “Compiling”).
Keep the widget interactive: allow reading the article while loading.

Retries and Error States

Provide one‑click retry with exponential backoff.
Offer a low‑bandwidth fallback (smaller voice sample or pre‑rendered clip).

Caching and Storage

Use HTTP caching effectively; version model URLs to control invalidation.
Defer non‑critical assets until after first interaction.

Accessibility

Expose progress via role="progressbar" and aria-valuenow.
Ensure keyboard focus stays predictable and visible during state changes.

Example States

// Example state machine
idle → initializing → downloading (0–100%) → compiling → ready → error → retry

Metrics to Watch

First‑load to ready (cold) vs warm cache time.
Retry rate and error categories.
Engagement while loading (scroll depth, time on page).

Author: Kokoro Web Team • Last updated 2025‑01‑15