Koe MCP Server
by Azeru548
README.md
# Koe TTS Studio + MCP
A self-hosted text-to-speech studio (Microsoft neural voices via edge-tts, optional offline Piper, Kokoro and Kitten) and an **MCP server** so agents can generate voiceovers on demand — free, no ElevenLabs.
It is built to be a **free public product**:
```
agent / browser ──free tenant key──> TTS Studio ──> edge-tts ──> ephemeral MP3 zip
│ │
└── auto-registers on first use └── deletes audio after 15 minutes
```
- **Multi-tenant** — every MCP install and every browser gets its own free key (issued server-side) with independent hourly/daily quotas.
- **Rate-limited** — per-key and per-IP limits, a bounded global queue, a global daily word budget, and a circuit breaker for upstream (Microsoft) failures.
- **Ephemeral audio** — generated zips are deleted after 15 minutes; job metadata after 1 hour; a restart wipes all audio. Nothing depends on permanent storage.
- **One small SQLite file** — issued keys and every counter live in `KOE_DB_PATH` (`./koe.db` by default), so limits survive restarts and a key is revocable by deleting its row. Keys are persisted as SHA-256 hashes, never plaintext, so a dumped database cannot be replayed as live keys. `KOE_SECRET` still signs download links and hashed subjects.
## Use it from any agent (hosted MCP)
The public instance runs at **<https://koe.kennedyazeru.space>**. The **hosted MCP server** is at `https://koe.kennedyazeru.space/mcp`. Agents connect by URL — no install, no local Node, no config file. The same URL serves a human setup page in a browser.
1. Open <https://koe.kennedyazeru.space/mcp> and click **Create key** (the page solves the proof-of-work challenge for you).
2. Point your client at `https://koe.kennedyazeru.space/mcp` with `Authorization: Bearer <key>` (or `x-api-key: <key>`).
3. Ask the agent to call `studio_status`, then `generate_voiceover`.
Works with Claude custom connectors (static request header, currently beta), Claude Code (`--transport http`), Cursor, or any streamable-HTTP MCP client. The endpoint is **stateless** and returns JSON (no SSE required), which keeps it compatible with a reverse proxy and ephemeral container disk.
Because the audio lives on the server rather than the caller's disk, hosted `generate_voiceover` returns a **short-lived signed download URL** (`/audio/:id?dl=…`, no API key needed) plus inline audio for short clips. The local stdio server below is still available for developers and saves files directly.
> **Building an agent?** [AGENTS.md](AGENTS.md) is the full agent-facing reference: exact MCP tool schemas, response shapes, recipes, error handling and the raw HTTP API. [DESIGN.md](DESIGN.md) records the visual system and the analytics measurement language.
---
## Free tier
| | Registered free key | Anonymous (no key) | Admin (`API_KEY`) |
| --- | --- | --- | --- |
| Requests / hour | 60 | 20 | unlimited |
| Words / hour | 2,000 | 500 | unlimited |
| Words / day | 20,000 | 3,000 | unlimited |
| Job visibility | own jobs only | own jobs only (per IP) | all jobs |
Global safety rail: **6** concurrent jobs, a **20**-job queue, and **30,000** words/day across the whole instance.
### Scaling out
Synthesis is a queue, and the queue lives in SQLite, so capacity is a matter of
running more workers — not of running a bigger server process:
```bash
# one process that serves HTTP only
KOE_EMBED_WORKER=false node server.js
# as many worker processes as you want, all against the same KOE_DB_PATH
KOE_WORKERS=6 node worker.js
KOE_WORKERS=6 node worker.js
```
- The global concurrency limit (`KOE_GLOBAL_CONCURRENCY`) is enforced **inside the
claim transaction**, so every process shares one budget. Two processes cannot
both admit job number seven.
- Jobs are claimed atomically (`queued` → `starting`), so no job runs twice, and
a worker that dies mid-job is reaped and refunded after the job deadline.
- Workers share the database file, so they must be on the same host or volume.
The audio directory must be shared too, since `GET /download/:id` may be
served by a process that did not synthesise the job.
- Parts of one job synthesise in parallel (`KOE_PART_CONCURRENCY`, default 2), and
identical `(text, voice, rate, pitch, engine)` requests are served from
`output/cache/` instead of a fresh upstream call. That cache has a byte budget
(`KOE_CACHE_MAX_MB`, default 256 MB) and is pruned oldest-first on every write,
and again on every periodic sweep, so lowering the limit or inheriting files
from an older run still converges on the budget.
- A job's script is **not** stored in the database: `POST /tts` writes it to
`output/work/<jobId>.parts.json` and the worker reads it from there. The row
keeps counts and status only. If a worker is killed mid-job, the next boot
re-queues the job from that file (with a fresh deadline) instead of failing it;
only jobs whose script is missing are failed and refunded. The file is deleted
on every terminal outcome — success, failure, deadline overrun, a reaped
worker, or `DELETE /job/:id` — so only jobs that are still waiting or running
hold one.
Measured on the reference box (108-word jobs, edge engine): 2 workers ≈ 6 jobs/min,
6 workers ≈ 10–15 jobs/min. The upstream endpoint, not the CPU, is the ceiling —
raise `KOE_GLOBAL_CONCURRENCY` carefully and watch for 403/429s. One job may be at most **2,000 words / 40,000 characters** — and **900 words on kitten**, which cannot finish more than that inside the 300 s job deadline, so a longer kitten script is a `400` before anything is charged. Free keys are capped at **3 per IP per day**. Previews are metered too and limited to 600 characters.
All of these are environment variables (see below).
### How keys work
Keys are issued **server-side**: `POST /keys` writes an opaque `koe_sk_<32 hex>` record into SQLite, and every request validates against that table. Nothing client-side can be counted.
```bash
# 1. Ask which anti-abuse gate is active
curl https://koe.kennedyazeru.space/keys/challenge
# → { "mode": "pow", "challenge": "…", "pow": { "leadingZeroHexChars": 4 } }
# (or { "mode": "turnstile", "sitekey": "…" } when Turnstile is configured)
# 2. Solve it — proof-of-work: find a nonce whose sha256(challenge + nonce)
# starts with 4 zero hex chars (~65k tries, well under a second) — and mint
curl -X POST https://koe.kennedyazeru.space/keys \
-H "Content-Type: application/json" \
-d '{"challenge":"<from step 1>","nonce":"0f3a"}'
# → 201 { "key": "koe_sk_9f2c…", "tenant": "…", "limits": {…} }
# 3. Use it
curl -H "x-api-key: koe_sk_..." -H "Content-Type: application/json" \
-d '{"text":"Hello from Koe","voice":"en-US-AndrewNeural"}' \
https://koe.kennedyazeru.space/tts
```
- `POST /api/register` is a thin alias of `POST /keys` — same gate, same `201 {key}` body, so older callers keep working instead of getting a 404.
- Challenges are single-use and expire after 5 minutes; a wrong or replayed one is `403 pow_challenge_invalid` / `pow_failed`.
- With `TURNSTILE_SITEKEY` + `TURNSTILE_SECRET` set, the gate becomes Cloudflare Turnstile instead of proof-of-work (headless clients then need `TTS_API_KEY`).
- Keys are rows, so they are revocable: delete the row (or wipe `KOE_DB_PATH`) and the key stops working on the next request. The studio UI and the MCP client re-mint automatically when a stored key starts returning `401` — see [MIGRATION-v3-keys.md](MIGRATION-v3-keys.md).
- Rows hold `sha256(key)`, never the key itself. A database from a build that stored raw keys is upgraded on open: each plaintext row is rewritten as its digest in place, so existing keys keep working and no plaintext secret is left on disk.
- `KOE_REQUIRE_KEY=true` rejects anonymous calls. The bundled MCP server and studio UI register a key automatically, so end users never see this step.
- `API_KEY` is an operator/admin key. It bypasses all limits and can see every tenant's jobs. Keep it private.
### Kill switch
`KOE_KILL_SWITCH=true` answers `503 {"error":"temporarily_disabled"}` on `POST /tts`, `POST /tts-preview*` and `POST /mcp` **before** auth, quota, queueing or any upstream work. Flip it in the environment and restart to stop all generation instantly; everything else (health, key issuance, usage, dashboards) keeps answering.
### Ephemeral audio
- Audio zips live in `output/audio/` and are deleted after `KOE_AUDIO_TTL_SEC` (default **900 s**).
- Job metadata lives in the SQLite `jobs` table (`KOE_DB_PATH`) and is pruned after `KOE_JOB_TTL_SEC` (default **1 hour**). A legacy `output/jobs.json` is imported once on boot and then ignored.
- Previews are written to `output/previews/` and swept after `KOE_PREVIEW_TTL_SEC` (default **10 min**).
- On boot all audio/preview/work files are deleted; jobs that were mid-flight are marked failed. `GET /download/:id` returns `410` once audio expires.
- Script text is never stored on disk — only counts, voice, engine, status and timings.
---
## TTS Studio server (`server.js`)
Local usage: `npm install && node server.js` → <http://localhost:3000>. `/` redirects to the MCP setup page at `/mcp`; the studio UI is served at `/studio`. It talks to the same origin (or `http://localhost:3000` when opened as a file).
### Endpoints
| Endpoint | Auth | Purpose |
| --- | --- | --- |
| `POST /tts` | key (or anon if allowed) | Submit a job → `{ jobId, parts, wordCount }` immediately |
| `GET /job/:id` | key / same tenant | Job status |
| `GET /jobs` | key / same tenant | Up to 100 recent jobs for this tenant |
| `GET /download/:id` | key / same tenant | ZIP of parts; `409` not ready, `410` expired |
| `GET /audio/:id` | key / same tenant, or signed `?dl=` | Single merged MP3/WAV; `409` not ready, `410` expired |
| `POST /mcp` | key | Hosted MCP server (streamable HTTP, stateless, JSON responses) |
| `GET /mcp` | public (HTML) | Human setup page for the MCP server |
| `DELETE /job/:id` | key / same tenant | Delete job + audio |
| `POST /tts-preview` | key (metered) | Stream an edge voice MP3 |
| `POST /tts-preview-piper` | key (metered) | Stream a Piper WAV |
| `POST /keys` | public (gated) | Mint a free key → `201 {key, tenant, limits}`; PoW or Turnstile gate, capped per IP/day |
| `GET /keys/challenge` | public | Which gate to solve: `{mode:"pow"\|"turnstile", challenge?, sitekey?}` |
| `POST /api/register` | public (gated) | Thin alias of `POST /keys` (same gate, same body) |
| `GET /api/limits` | public | Public limit policy (no secrets) |
| `GET /usage` | key | This caller's usage vs limits |
| `GET /voices` | public | Voice catalog per engine: `?engine=edge\|piper\|kokoro\|kitten&lang=en` |
| `GET /healthz` | public | Backend, engines, queue, limits, TTLs, and DB reachability |
| `GET /health` | public | Alias of `/healthz` |
| `GET /` | public | Redirects to `/mcp` |
| `GET /studio` | public | Studio UI |
| `GET /stats.html` | public shell | Operator analytics dashboard; data needs the admin key |
| `GET /stats.json` | admin | Machine-readable counters used by the dashboard |
| `GET /stats` | admin | Server-rendered operator report (`?key=` works) |
Auth accepts `x-api-key: <key>`, `Authorization: Bearer <key>`, or `?key=<key>`. `POST /mcp` always needs a live key row (or the admin key). Status codes: `400` validation or a job over `KOE_MAX_JOB_WORDS`, `401 {"error":"invalid_key"}` missing/unknown key, `403` another tenant's job or a failed issuance gate, `404` unknown, `409` not ready, `410` audio expired, `413` script over the 40,000-char cap, `429 {"reason":…}` rate/queue/global limit, `503 {"error":"temporarily_disabled"}` kill switch, engine unavailable or upstream cool-down.
Rejections carry a `reason` (`hourly_requests`, `hourly_words`, `daily_words`, `global_daily_words`, `job_too_long`, `kill_switch`, `queue_full`, `invalid_key`, `mint_cap`) and, for limits, a `retryAfterSeconds` reset window.
### Two backends
- `TTS_BACKEND=native` — runs the `edge-tts` / `piper` CLIs directly (the production Docker image). Default when Docker is unavailable.
- `TTS_BACKEND=docker` — shells out to the `edge-tts` / `piper-tts` Docker images (local dev). Auto-selected when the `docker` CLI exists.
Docker invocations use `execFile` (no shell), so script text and voice ids are never interpreted as shell commands.
### Three engines
All three sit behind one registry (`engines/index.js`) and one interface — `synthesize() -> { bytes, contentType }`, `listVoices()`, `healthy()`.
| Engine | Where it runs | Output | Rate / pitch | Selected with |
| --- | --- | --- | --- | --- |
| **`edge`** *(default)* | `edge-tts` CLI (Microsoft neural, cloud) | MP3 | rate **and** pitch | `engine: "edge"` |
| `piper` | `piper` CLI (offline on the host) | WAV | neither | `engine: "piper"` |
| `kokoro` | **separate sidecar container** (Kokoro-82M, ONNX) | MP3 | rate only (clamped to 1.0–2.0), **pitch ignored** | `engine: "kokoro"` |
| `kitten` | **separate sidecar container** (Kitten 15M–80M, ONNX int8) | WAV | rate only (0.5–2.0), **pitch ignored** | `engine: "kitten"` |
`edge` is the default and behaves exactly as it always has; `KOE_DEFAULT_ENGINE` can override the default but is intentionally left unset.
**The Kokoro sidecar is optional.** Start it with:
```bash
docker compose up -d # starts the sidecar on 127.0.0.1:8880
docker compose down # stops it
docker compose logs -f # watch it warm up (first boot downloads the model)
```
The app works fine without it — edge and piper are untouched, and only `engine: "kokoro"` requests are rejected with `503 {"error":"tts_unavailable","engine":"kokoro"}` (returned within 10s, before any quota is charged). `GET /healthz` stays `200` either way and reports `engines.kokoro: false` while it is down.
Point the studio at a sidecar on another host with `KOKORO_BASE_URL` (default `http://127.0.0.1:8880`).
Note the sidecar ignores pitch entirely, and rates below `1.0` are clamped up to `1.0` (it accepts `speed` only in `1.0–2.0`) — a warning is logged once if either happens.
#### Kitten sidecar (tiny, WAV)
Kitten TTS is the cheap local engine: the int8 nano checkpoint is ~25 MB,
the measured sidecar RSS after a synthesis is **~155 MB**, and the image is
~300 MB — so it runs comfortably where Kokoro does not. It is roughly 6× faster
than realtime for short text (measured: 18 words → 8.8 s of audio in 1.4 s).
```bash
docker compose up -d --build kitten # builds ops/kitten, serves 127.0.0.1:8881
docker compose logs -f kitten # first boot downloads the weights
```
Same rules as Kokoro: the app works without it, and only `engine: "kitten"`
requests answer `503 {"error":"tts_unavailable","engine":"kitten"}` while it is
down (before any quota is charged). `GET /healthz` reports `engines.kitten`.
- Base URL: `KITTEN_BASE_URL` (default `http://127.0.0.1:8881`).
- Output is **WAV**, so jobs zip and merge exactly like piper's.
- `rate` is passed to the sidecar as `speed` and clamped to 0.5–2.0; **pitch is
ignored** (warned once).
- One synthesis at a time inside the container, which is what keeps it inside
its memory limit.
- The image installs `kittenml` **without its torch/CUDA tree**: the int8 ONNX
path never imports torch (verified), so the stock dependency set is 6.5 GB for
nothing. See `ops/kitten/Dockerfile`.
**Kitten voices** — the eight speakers every checkpoint ships. The sidecar is
authoritative (`GET /voices`); this is the fallback list:
`bella` `jasper` `luna` `bruno` `rosie` `hugo` `kiki` `leo`
Ids are lowercase and never shared with edge, piper or Kokoro — passing a Kokoro
id to `engine: "kitten"` is a `400` with the valid ids in the body.
#### Kokoro voices
Kokoro voice ids are **not** shared with edge/piper: passing an edge voice to `engine: "kokoro"` is a `400` listing the first 20 valid kokoro ids (and the reverse). The live list comes from the sidecar (`GET /v1/audio/voices`); if it is unreachable the built-in catalog below is served instead.
- **en-US** (20): `af_heart` `af_alloy` `af_aoede` `af_bella` `af_jessica` `af_kore` `af_nicole` `af_nova` `af_river` `af_sarah` `af_sky` `am_adam` `am_echo` `am_eric` `am_fenrir` `am_liam` `am_michael` `am_onyx` `am_puck` `am_santa`
- **en-GB** (8): `bf_alice` `bf_emma` `bf_isabella` `bf_lily` `bm_daniel` `bm_fable` `bm_george` `bm_lewis`
- **ja-JP** (5): `jf_alpha` `jf_gongitsune` `jf_nezumi` `jf_tebukuro` `jm_kumo`
- **zh-CN** (8): `zf_xiaobei` `zf_xiaoni` `zf_xiaoxiao` `zf_xiaoyi` `zm_yunjian` `zm_yunxi` `zm_yunxia` `zm_yunyang`
- **es-ES** (3): `ef_dora` `em_alex` `em_santa`
- **fr-FR** (1): `ff_siwis`
- **hi-IN** (4): `hf_alpha` `hf_beta` `hm_omega` `hm_psi`
- **it-IT** (2): `if_sara` `im_nicola`
- **pt-BR** (3): `pf_dora` `pm_alex` `pm_santa`
The id prefix is `locale + gender` (`a`=American, `b`=British, `f`/`m`=female/male), so `bm_george` is a British male voice.
---
## Deploy on AWS (EC2 + Docker + Caddy)
Production is a single EC2 instance running the `koe` container behind Caddy, with a Let's Encrypt certificate and two systemd timers (watchdog and disk guard). The complete runbook is in **[DEPLOY.md](DEPLOY.md)**; the reusable scripts and unit files are in **[ops/](ops/)**. Pushes to `main` can also deploy automatically once CI passes, and a deploy can be started by hand from the Actions tab — both go through Systems Manager, so the instance needs no open SSH port and GitHub stores no AWS key. The opt-in setup (OIDC role, instance profile, repository variables) is in [DEPLOY.md §6](DEPLOY.md#6-update-production).
**Short version**
```bash
# on the instance
sudo dnf install -y docker git
sudo systemctl enable --now docker
mkdir -p ~/koe-ops
# copy ops/koe.env.example to ~/koe-ops/koe.env and fill in secrets
# copy ops/rebuild.sh, ops/watchdog.sh, ops/disk-guard.sh, ops/backup.sh to ~/koe-ops/
bash ~/koe-ops/rebuild.sh
```
`rebuild.sh` clones/pulls the repo, builds the image, recreates `koe` on `127.0.0.1:8080`, and starts Caddy. `KOE_SECRET` must stay stable — it signs download links and every hashed subject id. `API_KEY` is the operator key used by `/stats`, `/stats.json`, and the analytics dashboard.
The Docker image installs Node 20 + `edge-tts` and best-effort Piper. It keeps runtime data (`state.json`, `stats.json`, and `koe.db` — which now also holds the job queue) on a mounted volume so a container recreate does not wipe issued keys, usage counters or job metadata — set `KOE_DB_PATH=/data/koe.db` alongside `KOE_STATE_FILE`/`KOE_JOBS_FILE`/`KOE_STATS_FILE`.
**The container runs as the unprivileged `node` user (uid 1000).** `rebuild.sh` hands the data directory to that uid before starting. If you launch the image by hand with a bind mount, make it writable first (`sudo chown -R 1000:1000 ./data`), or the app cannot open its database.
**Back up `/data/koe.db`.** It holds every issued key, mint cap and counter; audio and jobs are disposable. `ops/backup.sh` takes a verified, retention-limited snapshot with SQLite's online backup API — see [DEPLOY.md §8](DEPLOY.md#backups-the-one-thing-that-cannot-be-regenerated).
> `render.yaml` remains in the repo as a legacy blueprint. It is not the production target.
---
## MCP server
### Hosted (recommended)
Already running at `POST /mcp` on your deployment — see [Use it from any agent](#use-it-from-any-agent-hosted-mcp) above. There is nothing to install and no environment variables to set; the caller's free key scopes every tool call. `GET /mcp` is the human setup page.
### Local stdio (`mcp/`)
Runs the same tools as a local process. It talks to a studio (local or hosted) and saves generated audio to a **local file path**, which is handy for video pipelines.
```bash
cd mcp
npm install
```
### Register it
Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"koe-tts": {
"command": "node",
"args": ["C:/Users/User/koe/mcp/index.js"],
"env": {
"TTS_STUDIO_URL": "https://koe.kennedyazeru.space"
}
}
}
}
```
Claude Code:
```bash
claude mcp add koe-tts \
-e TTS_STUDIO_URL=https://koe.kennedyazeru.space \
-- node C:/Users/User/koe/mcp/index.js
```
No key is required in the config. On first use the MCP asks `GET /keys/challenge`, answers the proof-of-work, mints the key with `POST /keys`, saves it in `~/.koe/credentials.json` (keyed by studio URL), and reuses it. Each user/install therefore gets an independent quota. If the studio starts answering `401` (for example after an upgrade that invalidates old keys), the client clears the stored key and mints a fresh one automatically. Set `TTS_API_KEY` only if you want to force a specific key (for example the operator's admin key).
### Tools
| Tool | What it does |
| --- | --- |
| `studio_status` | Pings `/health` and shows backend, engines, queue, limits, and your usage. Call first if something fails. |
| `list_voices` | Voices by engine (`edge`/`piper`/`kokoro`/`kitten`) and optional language filter (`en`, `fr`, …). |
| `generate_voiceover` | Narrates `text`, polls the job, then either saves and **merges parts into one MP3/WAV** locally (stdio) or returns a **signed download URL + inline audio** (hosted). Retries briefly on queue-full/cool-down. |
| `get_voiceover_status` | Job status by id (e.g. after a timeout). |
| `list_recent_voiceovers` | Your last 10 jobs (tenant-isolated). |
| `get_usage` | Requests/words this hour and today, limits, and reset times. |
### MCP environment variables
| Var | Default | Meaning |
| --- | --- | --- |
| `TTS_STUDIO_URL` | `http://localhost:3000` | Base URL of the studio |
| `TTS_API_KEY` | *(none)* | Optional explicit key; disables auto-registration |
| `VOICEOVER_DIR` | `./voiceovers` | Where local audio files are saved |
| `KOE_CREDENTIALS_FILE` | `~/.koe/credentials.json` | Where auto-registered free keys are stored |
| `KOE_DISABLE_AUTO_REGISTER` | *(unset)* | Set to `1` to never mint a free key |
Smoke-test the wiring without an agent:
```bash
cd mcp && TTS_STUDIO_URL=http://localhost:3000 node test-client.js
```
---
## Server environment variables
| Var | Default | Meaning |
| --- | --- | --- |
| `PORT` | `3000` | HTTP port |
| `TTS_BACKEND` | auto | `native` or `docker` |
| `KOKORO_BASE_URL` | `http://127.0.0.1:8880` | Where the optional Kokoro sidecar lives; the engine is unavailable when it does not answer |
| `KITTEN_BASE_URL` | `http://127.0.0.1:8881` | Where the optional Kitten sidecar lives; same rule |
| `KOE_ENGINE_CONCURRENCY` | `kokoro=1,kitten=1` | Per-engine in-flight ceiling. A sidecar at its cap is skipped in the claim transaction, so it cannot hold global slots while edge callers wait. `kokoro=2,kitten=1` raises one, empty disables the ceiling |
| `KOE_SECRET` | generated | **Set this in production.** Signs download links, hashed anon subjects and key ids (keys themselves are DB rows) |
| `KOE_DB_PATH` | `./koe.db` | SQLite file holding issued keys and every counter (`keys`, `usage`, `mint_ips`, `global_usage`). One connection per process; restarts resume from it |
| `API_KEY` | *(none)* | Admin key: unlimited, sees all jobs |
| `KOE_REQUIRE_KEY` | `false` | Reject anonymous callers |
| `KOE_TRUST_PROXY` | `loopback` | Which peers may set `X-Forwarded-For`. The default trusts only the local reverse proxy, so a directly-connected client cannot spoof its IP to dodge per-IP limits. `false` disables trust; a number counts hops |
| `KOE_ALLOWED_ORIGINS` | *(none)* | Extra browser origins allowed by CORS (comma-separated). Same-origin, loopback origins and `file://` pages are always allowed |
| `KOE_REGISTER_IP_DAY` | `3` | Free keys per IP per day |
| `KOE_HOURLY_REQUESTS` | `60` | Requests/hour per key *(legacy name: `KOE_KEY_REQ_HOUR`)* |
| `KOE_HOURLY_WORDS` | `2000` | Words/hour per key *(legacy: `KOE_KEY_WORDS_HOUR`)* |
| `KOE_DAILY_WORDS` | `20000` | Words/day per key *(legacy: `KOE_KEY_WORDS_DAY`)* |
| `KOE_ANON_REQ_HOUR` | `20` | Requests/hour per anonymous IP |
| `KOE_ANON_WORDS_HOUR` | `500` | Words/hour per anonymous IP |
| `KOE_ANON_WORDS_DAY` | `3000` | Words/day per anonymous IP |
| `KOE_MAX_JOB_WORDS` | `2000` | Per-request word cap; larger jobs are `400` before counting *(legacy: `KOE_MAX_WORDS_PER_JOB`)* |
| `KOE_ENGINE_MAX_WORDS` | `kitten=900` | Per-engine word cap, checked before the sidecar probe and before quota is charged. Kitten synthesizes at ~3 words/s, so more than ~900 words cannot finish inside the 300 s job deadline; a longer kitten job is a `400`. Same format as `KOE_ENGINE_CONCURRENCY`, empty disables |
| `KOE_MAX_CHARS_PER_JOB` | `40000` | Per-request character cap (`413`) |
| `KOE_MAX_CHARS_PER_PREVIEW` | `600` | Preview text cap |
| `KOE_GLOBAL_CONCURRENCY` | `6` | Simultaneous upstream jobs |
| `KOE_GLOBAL_QUEUE` | `20` | Max queued jobs |
| `KOE_GLOBAL_DAILY_WORDS` | `30000` | Instance-wide hard daily word ceiling *(legacy: `KOE_GLOBAL_WORDS_DAY`)* |
| `KOE_KILL_SWITCH` | `false` | `true` → `503 {"error":"temporarily_disabled"}` on every generation endpoint |
| `TURNSTILE_SITEKEY` / `TURNSTILE_SECRET` | *(unset)* | Set **both** to swap the proof-of-work issuance gate for Cloudflare Turnstile |
| `KOE_AUDIO_TTL_SEC` | `900` | Audio zip lifetime |
| `KOE_JOB_TTL_SEC` | `3600` | Job metadata lifetime |
| `KOE_PREVIEW_TTL_SEC` | `600` | Preview file lifetime |
| `KOE_SWEEP_INTERVAL_SEC` | `60` | Cleanup sweep interval |
| `KOE_COOLDOWN_SEC` | `60` | Base upstream failure cool-down (doubles, max 10 min) |
| `KOE_STATE_FILE` | `.koe-state.json` | Only the generated `KOE_SECRET` fallback — counters live in SQLite |
| `KOE_OUTPUT_DIR` | `./output` | Runtime audio/work/job directory |
| `KOE_JOBS_FILE` | `output/jobs.json` | **Legacy** job file: imported into the database once at boot, then never written |
| `KOE_EMBED_WORKER` | `true` | Run synthesis inside the server process; set `false` and run `node worker.js` to scale workers separately |
| `KOE_WORKERS` | `KOE_GLOBAL_CONCURRENCY` | Worker loops per `worker.js` process |
| `KOE_PART_CONCURRENCY` | `2` | Parts of one job synthesised in parallel |
| `KOE_WORKER_POLL_MS` | `500` | How often an idle worker checks the queue |
| `KOE_CACHE_MAX_MB` | `256` | Byte budget for the synthesis cache; oldest entries are pruned on write |
| `KOE_STATS_FILE` | `.koe-stats.json` | Persisted traffic/voiceover counters used by `/stats` |
| `KOE_PUBLIC_URL` | request origin | Absolute base used in hosted-MCP download links (set it if you run behind a proxy) |
| `KOE_MCP_INLINE_AUDIO_MAX` | `3145728` | Max bytes of audio to inline in an MCP response; `0` returns only the link |
| `KOE_MCP_POLL_MS` | `2000` | How often hosted `generate_voiceover` polls a job |
| `KOE_DEFAULT_ENGINE` | `edge` | Default for callers that omit `engine`. Left unset in this deployment — edge stays the default |
## Operator analytics
`/stats.html` is a public shell; its numbers come from the admin-only `/stats.json`. Open the page, paste `API_KEY`, and it reads:
- **Traffic** — all HTTP hits, voiceover jobs, MCP calls, previews, downloads, and new keys, all-time and today.
- **Product users** — unique subjects with a real product action (voiceover, MCP call, preview, download, or registration) in the last 5 minutes / hour / 24 hours.
- **Visitors** — all unique subjects, including crawlers and page loads. The dashboard shows these separately so bot traffic cannot inflate the user count.
- **Request sources** — top subjects by HTTP requests; **Voiceover users** — top subjects by words generated.
- **Daily ledger** — 14 days of counters.
Counters persist to `KOE_STATS_FILE` (default `.koe-stats.json`; `/data/stats.json` in the production container). Anonymous visitor ids are keyed HMACs from `guard.anonSubject()`, never raw IPs. Older raw-IP records are migrated on load. Job and audio data remain ephemeral.
---
## Notes
- edge-tts is free but unofficial (Microsoft's consumer endpoint); occasional throttling is expected. The circuit breaker pauses new work briefly instead of hammering it.
- Very long scripts are split into ~3000-char parts by the studio; the MCP merges them back into a single file (MP3s concatenated, WAVs re-muxed properly).
- Tests: `npm test` (115 tests: guard limits, key auth and hashing, tenant isolation, validation, ephemeral cleanup, analytics privacy/accounting, engine adapters, Kokoro sidecar behaviour, hosted MCP handshake and signed audio links). CI runs them on push and on the Docker build.
## Agent skill
[`skills/koe-voiceover/SKILL.md`](skills/koe-voiceover/SKILL.md) packages this
server as a portable `SKILL.md`: when to reach for a voiceover, how to get a free
key, the tool table, script-formatting rules and the error table. Zip the folder
to publish it to a skill marketplace.
## Support
Koe is free and has no accounts, cards or paid APIs. Running it costs one small
box and a domain, paid by one person. If it has been useful, you can
[buy me a malt](https://buymeamalt.com/@azeru548) — naira checkout, which Buy Me a
Coffee can't do for a Nigerian account.
## Licence
Koe is free software under the **GNU Affero General Public License v3.0**
(AGPL-3.0). © 2026 Azeru548. See [LICENSE](LICENSE) for the full text.
You can use it, change it and run it — for your own videos, inside your
company, or as part of a paid product. Two obligations are what make that safe
for everyone:
- **Share changes when you host it.** If you modify Koe and let other people use
that modified version over a network — a public instance, a SaaS, an internal
portal that other teams reach over HTTP — you must offer those users the
complete corresponding source of your version, under the AGPL (§13). Running
it privately for yourself or your own business requires no disclosure.
- **Keep the notices.** Don't strip the copyright or the license, and mark a
fork as changed (AGPL §5) — "based on Koe" is the fair way to say it.
There is no warranty and no support contract. If the public instance is down or
rate-limited, the license is what lets you run your own.
## What the license does not cover
The AGPL covers this source code. It grants nothing for the **Koe name, the
logo, or the domain `koe.kennedyazeru.space`**, and it does not permit presenting
a fork as the official project or implying endorsement by it. If you run a
public instance of your own, give it its own name — "based on Koe" is welcome,
"Koe" as your brand is not. The hosted instance itself (its keys, its quota, its
uptime) is not part of what this repository licenses.
## Contributing
Issues and pull requests are welcome. For anything larger than a bug fix, open
an issue first so the scope is agreed before you write code. Contributions are
accepted under the project's AGPL-3.0 license — no CLA and no copyright
assignment. Please keep keys, secrets and other people's audio out of issues and
pull requests.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues