KokoDrop

KokoDrop is a local Kokoro text-to-speech tool for developers, builders, and AI-agent workflows.

It runs a warm local HTTP service, exposes a scriptable CLI, and includes an Electron desktop/menu-bar app for turning text into local WAV or MP3 files. KokoDrop is local-first: text and generated audio stay on your machine unless you choose to move or share them.

Features

• Local FastAPI service on 127.0.0.1:8777.
• POST /synthesize endpoint for agent and app integrations.
• Chunked long-form synthesis with live audio preview streaming via POST /synthesize/stream.
• kokoro-tts CLI wrapper for one-command synthesis.
• kokoro-doctor diagnostics for service, launchd, logs, and output state.
• macOS launchd helper scripts for keeping the service available.
• Electron full app and menu-bar conversion surfaces.
• Local filesystem output with returned paths, metadata, and checksums.

Status

KokoDrop is an early open-source prototype. The core local service/CLI path has been used successfully, but fresh public-release verification, screenshots, retention policy, and packaging review are still in progress.

Requirements

• macOS for launchd and Electron packaging workflows.
• Python >=3.10,<3.13.
• uv for Python environment/dependency setup.
• espeak-ng for broader language support.
• Node.js/npm for Electron app development.

On macOS, the bootstrap script installs espeak-ng with Homebrew if it is missing.

Install

git clone <repo-url> kokodrop
cd kokodrop
./scripts/bootstrap.sh

The bootstrap script creates .venv, installs the Python package in editable mode, and downloads the spaCy model used by the Kokoro dependency stack.

If you prefer to run steps manually:

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/python -m spacy download en_core_web_sm

Start the service

./scripts/start.sh
./scripts/status.sh
./scripts/kokoro-doctor

The service listens on http://127.0.0.1:8777 by default and writes development output to var/output/.

To run the service directly without launchd:

KOKORO_TTS_OUTPUT_DIR="$PWD/var/output" \
KOKORO_TTS_LOG_DIR="$PWD/var/log" \
  ./.venv/bin/python -m kokoro_tool.server

Stop the launchd-managed service with:

./scripts/stop.sh

CLI usage

./scripts/kokoro-tts "Kokoro is ready." --voice af_heart --lang a --auto-title
./scripts/kokoro-tts "Save this as MP3." --format mp3 --json
./scripts/kokoro-tts "Long text..." --stream
./scripts/kokoro-tts "Long text..." --stream --format mp3 --chunk-max-chars 2000

The CLI starts the service if needed, sends the synthesis request, and prints the generated output path or JSON metadata. Use --stream to show chunk progress for long-form synthesis.

HTTP API

Health check:

curl http://127.0.0.1:8777/health

Synthesize audio:

curl -X POST http://127.0.0.1:8777/synthesize \
  -H 'content-type: application/json' \
  -d '{
    "text": "Kokoro is ready for local agent workflows.",
    "voice": "af_heart",
    "lang_code": "a",
    "auto_title": true,
    "format": "wav"
  }'

The synthesis response includes output path, filename, format, sample rate, size, checksum, creation time, voice, language, speed, text length, chunk metadata, and a local audio URL. Use POST /synthesize/stream for server-sent progress and live audio preview events that end with the same final metadata. See docs/API.md for request and response details.

Electron app

Run the development app:

npm --prefix electron-app install
npm --prefix electron-app run dev

Build a local macOS package only when you are intentionally testing packaging:

./scripts/package-mac.sh

Packaging can be slow and may produce large artifacts under release/.

Repository map

Path	Purpose
src/kokoro_tool/	Python FastAPI service, client, config, and Kokoro engine wrapper.
scripts/	Bootstrap, launchd start/stop/status, CLI wrappers, diagnostics, packaging.
launchd/	macOS LaunchAgent plist.
electron-app/	Electron desktop and menu-bar app.
packaging/	PyInstaller backend and model resource packaging.
release/	Generated release artifacts; verify freshness before publishing.
var/output/	Generated development audio files; ignored except .gitkeep.
var/log/	Development service logs; ignored except .gitkeep.

Privacy and security notes

• The default service host is 127.0.0.1; do not bind it to a public interface without a security review.
• Treat input text, generated audio, and logs as potentially sensitive local data.
• Generated filenames may include text-derived titles when auto_title is enabled.
• Do not commit generated audio, logs, .env*, tokens, private keys, service-account files, .npmrc, .netrc, or other credentials.
• See SECURITY.md for vulnerability reporting guidance.

Contributing

Contributions are welcome after the public repo is published. Please read CONTRIBUTING.md, keep changes small, and report the checks you ran.

Public development and CI must not depend on any private companion repository.

License

MIT. See LICENSE.