Skip to content

Sync fork with upstream remsky/Kokoro-FastAPI v0.9.0 #1

Closed

Description

@didevlab

Context

This repository is a fork of remsky/Kokoro-FastAPI. Upstream api/src/ is shipped verbatim and the fork layers its additions on top without patching it (NOTICE-fork.md):

  • server_addons/main.py imports api.src.main:app and mounts the fork router.
  • server_addons/router.py adds POST /v1/voices/save-combined, POST /v1/voices/sync-from-minio and POST /v1/voices/reload. It depends on api.src.inference.voice_manager.get_manager(), VoiceManager.load_voice, VoiceManager.list_voices, the private dict VoiceManager._voices and api.src.core.config.settings.voices_dir.
  • Dockerfile.gpu (CUDA 12.6.3, uv venv --python 3.10) and Dockerfile.cpu (python:3.10-slim) wrap the upstream Docker build steps and rewrite the entrypoint so that it seeds voices_dir from /app/voices-baked/ and launches server_addons.main:app via uv run.

The last upstream commit merged into the fork is 75a98b6 (2026-05-11, merge of upstream PR remsky#407), which predates upstream v0.3.0. Upstream's latest release is v0.9.0 (2026-09-10). gh api repos/remsky/Kokoro-FastAPI/compare/75a98b6...v0.9.0 reports the fork base 194 commits behind.

The model library has not moved: kokoro==0.9.4 and misaki==0.9.4 are still the latest on PyPI, and both upstream v0.9.0 and this fork's pyproject.toml already pin them. Both also pin torch==2.8.0.

Problem

The fork is missing upstream releases v0.3.0 through v0.9.0. That gap includes security fixes for a server that is exposed on the network:

  • v0.7.0: ReDoS in the text normalizer (URL/email/acronym patterns) and path traversal in _find_file (../ and absolute paths).
  • v0.7.2: starlette>=1.3.1, which covers the DoS-via-FileResponse CVEs.
  • v0.8.1: caps on total pause duration, input length and volume_multiplier, plus lang_code validation (GHSA-f64g-9jmv-pm22, OOM on public endpoints).

The fork is also missing correctness and quality fixes: UAX remsky#29 sentence segmentation (v0.8.2), stream cleanup on client disconnect (v0.9.0), FLAC tail truncation (v0.7.2), a WAV trailer click (v0.4.0), and a large set of normalizer improvements.

The longer the fork drifts, the harder each rebase gets, because upstream keeps reworking the files the fork wraps (Docker layout, entrypoint, voice handling).

Goal

The fork runs upstream remsky/Kokoro-FastAPI v0.9.0 under api/src/, with every fork-only route and operational delta still working. Both image flavours (-gpu, -cpu) build in CI and answer /health with 200. The POST /v1/audio/speech contract stays compatible with the nifty-star consumers.

Scope

  • Merge upstream tag v0.9.0 into master, keeping server_addons/, Dockerfile.gpu, Dockerfile.cpu, docker-compose.*.prod.yml, helm/, k8s/, .github/workflows/ci.yml, .env.example and the fork docs.
  • Resolve conflicts in upstream-owned files in favour of upstream, except where a fork delta is documented in NOTICE-fork.md.
  • Re-align Dockerfile.gpu and Dockerfile.cpu with the upstream v0.9.0 Docker build:
    • Python 3.12 (.python-version is 3.12 upstream).
    • Upstream removed docker/gpu/Dockerfile and keeps only docker/gpu/Dockerfile.optimized.
    • Bytecode compilation.
    • The upstream entrypoint now honours HOST/PORT and runs python -m uvicorn without uv run.
  • Keep the fork entrypoint steps: seed from /app/voices-baked/, optional model download, launch server_addons.main:app.
  • Re-validate the server_addons integration points against v0.9.0. A read-only check already found that get_manager, load_voice, list_voices, _voices: Dict[str, torch.Tensor] and settings.voices_dir / allow_local_voice_saving still exist.
  • Re-evaluate the overlap between save-combined and upstream POST /v1/audio/voices/combine, which accepts the weighted syntax a(2)+b(1) since v0.8.1. Decide whether save-combined should delegate its blend math to upstream (process_and_validate_voices / get_voices_path) or keep its own. Persisting into voices_dir remains fork-only either way.
  • Review new upstream settings that change defaults for fork consumers: debug routes gated behind a setting (v0.6.0), opt-in POST /dev/unload and auto-unload on timeout (v0.5.0/v0.8.2), and new input-length caps (v0.8.1). Document the relevant env vars in .env.example and docs/generation-parameters.md.
  • Update NOTICE-fork.md / README-fork.md with the upstream base version.

Out of scope

  • Adopting new upstream features in the nifty-star clients (multi-speaker inline, SSML, voice-clone tuner tab). They become available, but no consumer change is made here.
  • ROCm image flavour.
  • Bumping kokoro / misaki beyond 0.9.4 (no newer release exists).
  • The local, uncommitted switch from the ./voices bind mount to the named volume in docker-compose.gpu.prod.yml. That is a separate decision.

Functional requirements

  • FR1: POST /v1/audio/speech, GET /v1/audio/voices and POST /v1/audio/voices/combine follow upstream v0.9.0 behaviour.
  • FR2: POST /v1/voices/save-combined keeps its contract: request {voices, name, overwrite}; response {name, path, base_voices}; 400 on invalid name, unknown voice or zero weight sum; 409 on an existing name without overwrite.
  • FR3: POST /v1/voices/sync-from-minio, POST /v1/voices/reload and the KOKORO_SYNC_ON_START hook keep working.
  • FR4: ALLOW_LOCAL_VOICE_SAVING=true stays the image default.
  • FR5: A mounted voices_dir is still seeded from the baked voicepacks at boot.

Glossary (domain term → identifier)

Term Identifier (EN) Origin
voicepack blend persistence save_combined_voice, SaveCombinedRequest already used in server_addons/router.py
MinIO voicepack sync sync_voicepacks already used in server_addons/sync.py
baked voicepacks staging dir /app/voices-baked already used in Dockerfile.gpu / Dockerfile.cpu

No new identifiers are expected. If a new env var is needed, its name follows upstream's naming in api/src/core/config.py.

Spec rite

  • Workflow / schema: openspec, vanilla (no openspec/config.yaml)
  • Policy: required (fail-closed default; no spec_rite config in this repo)
  • Verdict: change required, id update-upstream-kokoro-fastapi-v0-9-0
  • Capabilities the delta touches: kokoro-tts-server, MODIFIED Inference Surface Inherited Verbatim (pin the inherited surface to upstream v0.9.0, weighted syntax on /v1/audio/voices/combine, new input caps). The Dockerfile requirements may also need a MODIFIED delta for the Python 3.12 base.

Technical requirements

  • TR1: Keep upstream api/src/ unpatched. Every fork delta stays in server_addons/, Dockerfile.*, ENV or ops manifests (NOTICE-fork.md).
  • TR2: Add a remsky git remote and merge the tag; do not cherry-pick or squash, so future syncs stay mergeable.
  • TR3: Replace the manager._voices.clear() access in server_addons/router.py with a public upstream API if v0.9.0 offers one (upstream v0.x "clear voice cache on unload"). Otherwise keep the guarded hasattr access.
  • TR4: Commits follow Conventional Commits, since semantic-release drives VERSION / CHANGELOG.md.

Acceptance criteria

  • git merge-base --is-ancestor v0.9.0 master succeeds (upstream tag fetched from remsky/Kokoro-FastAPI).
  • The api/tests suite passes under the v0.9.0 code (pytest, per pytest.ini).
  • New tests cover server_addons: save-combined (happy path, 400 invalid name, 400 unknown voice, 400 zero weight sum, 409 without overwrite) and reload. MinIO sync is tested with the client mocked.
  • Dockerfile.gpu and Dockerfile.cpu build in CI. Each container answers GET /health with 200 and lists the baked voices in GET /v1/audio/voices.
  • A smoke POST /v1/audio/speech with voice: "pf_dora(0.7)+pm_alex(0.3)" returns audio on the CPU image.
  • NOTICE-fork.md and README-fork.md state the upstream base version (v0.9.0).
  • OpenSpec change update-upstream-kokoro-fastapi-v0-9-0 passes openspec validate --strict.
  • New identifiers, routes, keys and event names follow the Glossary and code-locale.

Dependencies

  • The open OpenSpec change add-kokoro-tts-server-cpu-flavour (14/17 tasks, pending manual verification 5.1) should be archived first, or explicitly carried along, because both changes touch the Dockerfile requirements of kokoro-tts-server.
  • Upstream remsky/Kokoro-FastAPI tag v0.9.0.

Risks

  • Entrypoint and Dockerfile drift (upstream removed docker/gpu/Dockerfile and changed the entrypoint and Python version). Mitigation: rebuild both flavours in CI and run a /health and speech smoke test before release.
  • The private VoiceManager._voices may change shape later. Mitigation: TR3 plus a test that fails if cache invalidation stops working.
  • Behaviour changes from upstream normalizer/segmentation (UAX 🔄 Automatic master to develop merge failed remsky/Kokoro-FastAPI#29, dashes, phone numbers) alter generated audio for existing consumer scripts. Mitigation: listen-check a PT-BR sample with the ptbr_* blends, and note it in the release changelog.
  • New upstream input caps (v0.8.1) may reject long inputs the nifty-star sequencer sends today. Mitigation: check the cap values against the sequencer's chunk sizes; raise them through env if needed.
  • Upstream merge commits trigger semantic-release version bumps. Mitigation: merge with a single conventional feat/chore merge commit message.

Test strategy

  • Unit: the existing upstream suite under api/tests/ (pytest, pytest.ini, .coveragerc) plus new server_addons tests in the same framework, using FastAPI TestClient, a temp voices_dir and a mocked minio.Minio.
  • Integration: CI image builds for -gpu and -cpu (.github/workflows/ci.yml), then a manual docker compose -f docker-compose.cpu.prod.yml up with /health, /v1/audio/voices, /v1/voices/save-combined and /v1/audio/speech.

Affected files/components

  • api/, web/, docker/, pyproject.toml, uv.lock/requirements, .python-version: replaced by upstream v0.9.0.
  • Dockerfile.gpu, Dockerfile.cpu: Python 3.12 base, upstream build steps, entrypoint rewrite.
  • server_addons/router.py: cache invalidation and possible reuse of upstream blend helpers.
  • server_addons/ tests (new).
  • .env.example, docs/generation-parameters.md, NOTICE-fork.md, README-fork.md: new upstream env knobs and base version.
  • openspec/specs/kokoro-tts-server/spec.md (via the change delta).

Activity

  1. added a commit that references this issue on Oct 1, 2026
  2. didevlab commented on Oct 1, 2026

    @didevlab
    Author

    Implemented in #2 (merged as e21cd95 with a merge commit, so upstream ancestry is kept).

    # Criterion (short) Verdict Evidence
    1 v0.9.0 is an ancestor of master met git merge-base --is-ancestor upstream-v0.9.0 origin/master exits 0 after merge
    2 api/tests passes on v0.9.0 code met upstream CI command in python:3.12 with espeak-ng: 564 passed, 9 skipped, 19 deselected
    3 server_addons tests met pytest server_addons/tests: 30 passed
    4 both Dockerfiles build in CI, /health 200, voices listed pending CI local builds exit 0; CPU and GPU containers /health 200; CI run 36819112801 in progress
    5 weighted speech smoke on CPU image met 200, 34604 bytes MPEG audio
    6 NOTICE/README name v0.9.0 met NOTICE-fork.md:5, README-fork.md:4
    7 OpenSpec strict met Change 'update-upstream-kokoro-fastapi-v0-9-0' is valid
    8 identifiers follow Glossary / code-locale met only private English helpers added

    Finding fixed along the way: KOKORO_SYNC_ON_START had never run, because Starlette ignores on_event("startup") when the app has a lifespan. It is now chained into the upstream lifespan.

    Pending: archive the OpenSpec change update-upstream-kokoro-fastapi-v0-9-0 in an archive-only follow-up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions