Repository navigation
Description
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.pyimportsapi.src.main:appand mounts the fork router.server_addons/router.pyaddsPOST /v1/voices/save-combined,POST /v1/voices/sync-from-minioandPOST /v1/voices/reload. It depends onapi.src.inference.voice_manager.get_manager(),VoiceManager.load_voice,VoiceManager.list_voices, the private dictVoiceManager._voicesandapi.src.core.config.settings.voices_dir.Dockerfile.gpu(CUDA 12.6.3,uv venv --python 3.10) andDockerfile.cpu(python:3.10-slim) wrap the upstream Docker build steps and rewrite the entrypoint so that it seedsvoices_dirfrom/app/voices-baked/and launchesserver_addons.main:appviauv 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-FileResponseCVEs. - v0.8.1: caps on total pause duration, input length and
volume_multiplier, pluslang_codevalidation (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.0intomaster, keepingserver_addons/,Dockerfile.gpu,Dockerfile.cpu,docker-compose.*.prod.yml,helm/,k8s/,.github/workflows/ci.yml,.env.exampleand 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.gpuandDockerfile.cpuwith the upstream v0.9.0 Docker build:- Python 3.12 (
.python-versionis3.12upstream). - Upstream removed
docker/gpu/Dockerfileand keeps onlydocker/gpu/Dockerfile.optimized. - Bytecode compilation.
- The upstream entrypoint now honours
HOST/PORTand runspython -m uvicornwithoutuv run.
- Python 3.12 (
- Keep the fork entrypoint steps: seed from
/app/voices-baked/, optional model download, launchserver_addons.main:app. - Re-validate the
server_addonsintegration points against v0.9.0. A read-only check already found thatget_manager,load_voice,list_voices,_voices: Dict[str, torch.Tensor]andsettings.voices_dir/allow_local_voice_savingstill exist. - Re-evaluate the overlap between
save-combinedand upstreamPOST /v1/audio/voices/combine, which accepts the weighted syntaxa(2)+b(1)since v0.8.1. Decide whethersave-combinedshould delegate its blend math to upstream (process_and_validate_voices/get_voices_path) or keep its own. Persisting intovoices_dirremains 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/unloadand 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.exampleanddocs/generation-parameters.md. - Update
NOTICE-fork.md/README-fork.mdwith 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/misakibeyond0.9.4(no newer release exists). - The local, uncommitted switch from the
./voicesbind mount to the named volume indocker-compose.gpu.prod.yml. That is a separate decision.
Functional requirements
- FR1:
POST /v1/audio/speech,GET /v1/audio/voicesandPOST /v1/audio/voices/combinefollow upstream v0.9.0 behaviour. - FR2:
POST /v1/voices/save-combinedkeeps 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 withoutoverwrite. - FR3:
POST /v1/voices/sync-from-minio,POST /v1/voices/reloadand theKOKORO_SYNC_ON_STARThook keep working. - FR4:
ALLOW_LOCAL_VOICE_SAVING=truestays the image default. - FR5: A mounted
voices_diris 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 (noopenspec/config.yaml) - Policy:
required(fail-closed default; nospec_riteconfig in this repo) - Verdict: change required, id
update-upstream-kokoro-fastapi-v0-9-0 - Capabilities the delta touches:
kokoro-tts-server, MODIFIEDInference Surface Inherited Verbatim(pin the inherited surface to upstreamv0.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 inserver_addons/,Dockerfile.*, ENV or ops manifests (NOTICE-fork.md). - TR2: Add a
remskygit remote and merge the tag; do not cherry-pick or squash, so future syncs stay mergeable. - TR3: Replace the
manager._voices.clear()access inserver_addons/router.pywith a public upstream API if v0.9.0 offers one (upstream v0.x "clear voice cache on unload"). Otherwise keep the guardedhasattraccess. - TR4: Commits follow Conventional Commits, since semantic-release drives
VERSION/CHANGELOG.md.
Acceptance criteria
-
git merge-base --is-ancestor v0.9.0 mastersucceeds (upstream tag fetched fromremsky/Kokoro-FastAPI). - The
api/testssuite passes under the v0.9.0 code (pytest, perpytest.ini). - New tests cover
server_addons:save-combined(happy path, 400 invalid name, 400 unknown voice, 400 zero weight sum, 409 without overwrite) andreload. MinIO sync is tested with the client mocked. -
Dockerfile.gpuandDockerfile.cpubuild in CI. Each container answersGET /healthwith 200 and lists the baked voices inGET /v1/audio/voices. - A smoke
POST /v1/audio/speechwithvoice: "pf_dora(0.7)+pm_alex(0.3)"returns audio on the CPU image. -
NOTICE-fork.mdandREADME-fork.mdstate the upstream base version (v0.9.0). - OpenSpec change
update-upstream-kokoro-fastapi-v0-9-0passesopenspec 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 ofkokoro-tts-server. - Upstream
remsky/Kokoro-FastAPItagv0.9.0.
Risks
- Entrypoint and Dockerfile drift (upstream removed
docker/gpu/Dockerfileand changed the entrypoint and Python version). Mitigation: rebuild both flavours in CI and run a/healthand speech smoke test before release. - The private
VoiceManager._voicesmay 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/choremerge commit message.
Test strategy
- Unit: the existing upstream suite under
api/tests/(pytest,pytest.ini,.coveragerc) plus newserver_addonstests in the same framework, using FastAPITestClient, a tempvoices_dirand a mockedminio.Minio. - Integration: CI image builds for
-gpuand-cpu(.github/workflows/ci.yml), then a manualdocker compose -f docker-compose.cpu.prod.yml upwith/health,/v1/audio/voices,/v1/voices/save-combinedand/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
chore(release): 0.6.0 [skip ci]
didevlab commentedon Oct 1, 2026
Implemented in #2 (merged as e21cd95 with a merge commit, so upstream ancestry is kept).
git merge-base --is-ancestor upstream-v0.9.0 origin/masterexits 0 after mergeapi/testspasses on v0.9.0 codepython:3.12with espeak-ng:564 passed, 9 skipped, 19 deselectedserver_addonstestspytest server_addons/tests:30 passed/health200, voices listed/health200; CI run 36819112801 in progressNOTICE-fork.md:5,README-fork.md:4Change 'update-upstream-kokoro-fastapi-v0-9-0' is validFinding fixed along the way:
KOKORO_SYNC_ON_STARThad never run, because Starlette ignoreson_event("startup")when the app has alifespan. It is now chained into the upstream lifespan.Pending: archive the OpenSpec change
update-upstream-kokoro-fastapi-v0-9-0in an archive-only follow-up.