Skip to content

fix: gate model downloads and phonemize local speech - #2914

Merged
numnx merged 1 commit into
devfrom
fix/kokoro-phonemization
Jul 11, 2026
Merged

fix: gate model downloads and phonemize local speech#2914
numnx merged 1 commit into
devfrom
fix/kokoro-phonemization

Conversation

@numnx

@numnx numnx commented Jul 11, 2026

Copy link
Copy Markdown
Collaborator

What changed

  • require explicit acceptance of the current upstream license identifier before every speech or embedding model download
  • expose license, provenance, commercial-use status, terms links, and download size in Settings -> AI Models
  • fail closed when a built-in catalog entry lacks approved commercial-use metadata
  • require custom embedding entries to declare an HTTPS license URL and confirm commercial use
  • replace Piper Lessac and Alba with public-domain-trained LJSpeech and Cori bundles, including legacy settings migration
  • download the pinned phonemizer only on opt-in, verify its SHA-256, and execute it as a separate process
  • feed Kokoro American/British IPA with punctuation and compatibility normalization instead of raw graphemes
  • reuse existing non-empty bundle files so an existing Kokoro install only fetches the new runtime/notices
  • mark a selected but incomplete speech bundle as Repair required
  • update canonical and public speech/embedding documentation

Why

Kokoro expects phoneme tokens. Machines without a system espeak-ng binary silently fell back to English spelling, which mapped to unrelated model tokens and made voices such as Bella sound foreign or unintelligible. Downloads also needed a consistent opt-in license boundary suitable for an MIT open-source application.

Validation

  • pnpm run ci
    • quality guardrails passed
    • dependency audit passed with no known high-severity vulnerabilities
    • typecheck/lint passed
    • backend coverage: 407 files, 5,193 passed, 7 skipped
    • dashboard tests: 229 files, 2,039 passed, 2 skipped
    • production build passed
  • pnpm run check:docs-web passed
  • real pinned phonemizer artifact hash matched and produced American-English IPA for Bella with punctuation preserved
  • /health and /ready returned healthy/ready after restarting the local runtime
  • live catalog response contained only commercially usable built-in entries
  • dashboard visual check passed at 1440x1100 for license cards, Repair required, and the Accept & Download dialog

Risk and rollback

Risk is concentrated in the new download acceptance contract and phonemizer subprocess. Existing clients that call download endpoints directly must send the catalog's acceptedLicenseId. Existing Kokoro weights are reused, but the bundle remains unavailable until the small runtime is accepted and downloaded. Legacy Piper selections migrate to LJSpeech or Cori.

Rollback by reverting this PR. Cached model files remain outside the application package and can be removed through the catalog. Reverting would restore the previous phonemization fallback, so it should be used only if the new runtime causes an operational regression.

@numnx
numnx merged commit 2cb8e2c into dev Jul 11, 2026
40 checks passed
@numnx
numnx deleted the fix/kokoro-phonemization branch July 11, 2026 10:27
@numnx numnx mentioned this pull request Jul 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant