Skip to content
Back to search

koe

Free text-to-speech studio and MCP server: Microsoft neural voices plus offline Piper, Kokoro and Kitten. Any agent gets a local MP3 in one tool call, and the audio is ephemeral by design. Use the hosted instance or run your own.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/azeru548--koe/badge.svg)](/listings/azeru548--koe)

HTML

<a href="/listings/azeru548--koe"><img src="/api/listings/azeru548--koe/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 475 lines
  1. # Koe TTS Studio + MCP
  2. 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.
  3. It is built to be a **free public product**:
  4. ```
  5. agent / browser ──free tenant key──> TTS Studio ──> edge-tts ──> ephemeral MP3 zip
  6. │ │
  7. └── auto-registers on first use └── deletes audio after 15 minutes
  8. ```
  9. - **Multi-tenant** — every MCP install and every browser gets its own free key (issued server-side) with independent hourly/daily quotas.
  10. - **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.
  11. - **Ephemeral audio** — generated zips are deleted after 15 minutes; job metadata after 1 hour; a restart wipes all audio. Nothing depends on permanent storage.
  12. - **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.
  13. ## Use it from any agent (hosted MCP)
  14. 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.
  15. 1. Open <https://koe.kennedyazeru.space/mcp> and click **Create key** (the page solves the proof-of-work challenge for you).
  16. 2. Point your client at `https://koe.kennedyazeru.space/mcp` with `Authorization: Bearer <key>` (or `x-api-key: <key>`).
  17. 3. Ask the agent to call `studio_status`, then `generate_voiceover`.
  18. 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.
  19. 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.
  20. > **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.
  21. ---
  22. ## Free tier
  23. | | Registered free key | Anonymous (no key) | Admin (`API_KEY`) |
  24. | --- | --- | --- | --- |
  25. | Requests / hour | 60 | 20 | unlimited |
  26. | Words / hour | 2,000 | 500 | unlimited |
  27. | Words / day | 20,000 | 3,000 | unlimited |
  28. | Job visibility | own jobs only | own jobs only (per IP) | all jobs |
  29. Global safety rail: **6** concurrent jobs, a **20**-job queue, and **30,000** words/day across the whole instance.
  30. ### Scaling out
  31. Synthesis is a queue, and the queue lives in SQLite, so capacity is a matter of
  32. running more workers — not of running a bigger server process:
  33. ```bash
  34. # one process that serves HTTP only
  35. KOE_EMBED_WORKER=false node server.js
  36. # as many worker processes as you want, all against the same KOE_DB_PATH
  37. KOE_WORKERS=6 node worker.js
  38. KOE_WORKERS=6 node worker.js
  39. ```
  40. - The global concurrency limit (`KOE_GLOBAL_CONCURRENCY`) is enforced **inside the
  41. claim transaction**, so every process shares one budget. Two processes cannot
  42. both admit job number seven.
  43. - Jobs are claimed atomically (`queued` → `starting`), so no job runs twice, and
  44. a worker that dies mid-job is reaped and refunded after the job deadline.
  45. - Workers share the database file, so they must be on the same host or volume.
  46. The audio directory must be shared too, since `GET /download/:id` may be
  47. served by a process that did not synthesise the job.
  48. - Parts of one job synthesise in parallel (`KOE_PART_CONCURRENCY`, default 2), and
  49. identical `(text, voice, rate, pitch, engine)` requests are served from
  50. `output/cache/` instead of a fresh upstream call. That cache has a byte budget
  51. (`KOE_CACHE_MAX_MB`, default 256 MB) and is pruned oldest-first on every write,
  52. and again on every periodic sweep, so lowering the limit or inheriting files
  53. from an older run still converges on the budget.
  54. - A job's script is **not** stored in the database: `POST /tts` writes it to
  55. `output/work/<jobId>.parts.json` and the worker reads it from there. The row
  56. keeps counts and status only. If a worker is killed mid-job, the next boot
  57. re-queues the job from that file (with a fresh deadline) instead of failing it;
  58. only jobs whose script is missing are failed and refunded. The file is deleted
  59. on every terminal outcome — success, failure, deadline overrun, a reaped
  60. worker, or `DELETE /job/:id` — so only jobs that are still waiting or running
  61. hold one.
  62. Measured on the reference box (108-word jobs, edge engine): 2 workers ≈ 6 jobs/min,
  63. 6 workers ≈ 10–15 jobs/min. The upstream endpoint, not the CPU, is the ceiling —
  64. 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.
  65. All of these are environment variables (see below).
  66. ### How keys work
  67. 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.
  68. ```bash
  69. # 1. Ask which anti-abuse gate is active
  70. curl https://koe.kennedyazeru.space/keys/challenge
  71. # → { "mode": "pow", "challenge": "…", "pow": { "leadingZeroHexChars": 4 } }
  72. # (or { "mode": "turnstile", "sitekey": "…" } when Turnstile is configured)
  73. # 2. Solve it — proof-of-work: find a nonce whose sha256(challenge + nonce)
  74. # starts with 4 zero hex chars (~65k tries, well under a second) — and mint
  75. curl -X POST https://koe.kennedyazeru.space/keys \
  76. -H "Content-Type: application/json" \
  77. -d '{"challenge":"<from step 1>","nonce":"0f3a"}'
  78. # → 201 { "key": "koe_sk_9f2c…", "tenant": "…", "limits": {…} }
  79. # 3. Use it
  80. curl -H "x-api-key: koe_sk_..." -H "Content-Type: application/json" \
  81. -d '{"text":"Hello from Koe","voice":"en-US-AndrewNeural"}' \
  82. https://koe.kennedyazeru.space/tts
  83. ```
  84. - `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.
  85. - Challenges are single-use and expire after 5 minutes; a wrong or replayed one is `403 pow_challenge_invalid` / `pow_failed`.
  86. - With `TURNSTILE_SITEKEY` + `TURNSTILE_SECRET` set, the gate becomes Cloudflare Turnstile instead of proof-of-work (headless clients then need `TTS_API_KEY`).
  87. - 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).
  88. - 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.
  89. - `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.
  90. - `API_KEY` is an operator/admin key. It bypasses all limits and can see every tenant's jobs. Keep it private.
  91. ### Kill switch
  92. `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.
  93. ### Ephemeral audio
  94. - Audio zips live in `output/audio/` and are deleted after `KOE_AUDIO_TTL_SEC` (default **900 s**).
  95. - 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.
  96. - Previews are written to `output/previews/` and swept after `KOE_PREVIEW_TTL_SEC` (default **10 min**).
  97. - 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.
  98. - Script text is never stored on disk — only counts, voice, engine, status and timings.
  99. ---
  100. ## TTS Studio server (`server.js`)
  101. 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).
  102. ### Endpoints
  103. | Endpoint | Auth | Purpose |
  104. | --- | --- | --- |
  105. | `POST /tts` | key (or anon if allowed) | Submit a job → `{ jobId, parts, wordCount }` immediately |
  106. | `GET /job/:id` | key / same tenant | Job status |
  107. | `GET /jobs` | key / same tenant | Up to 100 recent jobs for this tenant |
  108. | `GET /download/:id` | key / same tenant | ZIP of parts; `409` not ready, `410` expired |
  109. | `GET /audio/:id` | key / same tenant, or signed `?dl=` | Single merged MP3/WAV; `409` not ready, `410` expired |
  110. | `POST /mcp` | key | Hosted MCP server (streamable HTTP, stateless, JSON responses) |
  111. | `GET /mcp` | public (HTML) | Human setup page for the MCP server |
  112. | `DELETE /job/:id` | key / same tenant | Delete job + audio |
  113. | `POST /tts-preview` | key (metered) | Stream an edge voice MP3 |
  114. | `POST /tts-preview-piper` | key (metered) | Stream a Piper WAV |
  115. | `POST /keys` | public (gated) | Mint a free key → `201 {key, tenant, limits}`; PoW or Turnstile gate, capped per IP/day |
  116. | `GET /keys/challenge` | public | Which gate to solve: `{mode:"pow"\|"turnstile", challenge?, sitekey?}` |
  117. | `POST /api/register` | public (gated) | Thin alias of `POST /keys` (same gate, same body) |
  118. | `GET /api/limits` | public | Public limit policy (no secrets) |
  119. | `GET /usage` | key | This caller's usage vs limits |
  120. | `GET /voices` | public | Voice catalog per engine: `?engine=edge\|piper\|kokoro\|kitten&lang=en` |
  121. | `GET /healthz` | public | Backend, engines, queue, limits, TTLs, and DB reachability |
  122. | `GET /health` | public | Alias of `/healthz` |
  123. | `GET /` | public | Redirects to `/mcp` |
  124. | `GET /studio` | public | Studio UI |
  125. | `GET /stats.html` | public shell | Operator analytics dashboard; data needs the admin key |
  126. | `GET /stats.json` | admin | Machine-readable counters used by the dashboard |
  127. | `GET /stats` | admin | Server-rendered operator report (`?key=` works) |
  128. 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.
  129. 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.
  130. ### Two backends
  131. - `TTS_BACKEND=native` — runs the `edge-tts` / `piper` CLIs directly (the production Docker image). Default when Docker is unavailable.
  132. - `TTS_BACKEND=docker` — shells out to the `edge-tts` / `piper-tts` Docker images (local dev). Auto-selected when the `docker` CLI exists.
  133. Docker invocations use `execFile` (no shell), so script text and voice ids are never interpreted as shell commands.
  134. ### Three engines
  135. All three sit behind one registry (`engines/index.js`) and one interface — `synthesize() -> { bytes, contentType }`, `listVoices()`, `healthy()`.
  136. | Engine | Where it runs | Output | Rate / pitch | Selected with |
  137. | --- | --- | --- | --- | --- |
  138. | **`edge`** *(default)* | `edge-tts` CLI (Microsoft neural, cloud) | MP3 | rate **and** pitch | `engine: "edge"` |
  139. | `piper` | `piper` CLI (offline on the host) | WAV | neither | `engine: "piper"` |
  140. | `kokoro` | **separate sidecar container** (Kokoro-82M, ONNX) | MP3 | rate only (clamped to 1.0–2.0), **pitch ignored** | `engine: "kokoro"` |
  141. | `kitten` | **separate sidecar container** (Kitten 15M–80M, ONNX int8) | WAV | rate only (0.5–2.0), **pitch ignored** | `engine: "kitten"` |
  142. `edge` is the default and behaves exactly as it always has; `KOE_DEFAULT_ENGINE` can override the default but is intentionally left unset.
  143. **The Kokoro sidecar is optional.** Start it with:
  144. ```bash
  145. docker compose up -d # starts the sidecar on 127.0.0.1:8880
  146. docker compose down # stops it
  147. docker compose logs -f # watch it warm up (first boot downloads the model)
  148. ```
  149. 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.
  150. Point the studio at a sidecar on another host with `KOKORO_BASE_URL` (default `http://127.0.0.1:8880`).
  151. 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.
  152. #### Kitten sidecar (tiny, WAV)
  153. Kitten TTS is the cheap local engine: the int8 nano checkpoint is ~25 MB,
  154. the measured sidecar RSS after a synthesis is **~155 MB**, and the image is
  155. ~300 MB — so it runs comfortably where Kokoro does not. It is roughly 6× faster
  156. than realtime for short text (measured: 18 words → 8.8 s of audio in 1.4 s).
  157. ```bash
  158. docker compose up -d --build kitten # builds ops/kitten, serves 127.0.0.1:8881
  159. docker compose logs -f kitten # first boot downloads the weights
  160. ```
  161. Same rules as Kokoro: the app works without it, and only `engine: "kitten"`
  162. requests answer `503 {"error":"tts_unavailable","engine":"kitten"}` while it is
  163. down (before any quota is charged). `GET /healthz` reports `engines.kitten`.
  164. - Base URL: `KITTEN_BASE_URL` (default `http://127.0.0.1:8881`).
  165. - Output is **WAV**, so jobs zip and merge exactly like piper's.
  166. - `rate` is passed to the sidecar as `speed` and clamped to 0.5–2.0; **pitch is
  167. ignored** (warned once).
  168. - One synthesis at a time inside the container, which is what keeps it inside
  169. its memory limit.
  170. - The image installs `kittenml` **without its torch/CUDA tree**: the int8 ONNX
  171. path never imports torch (verified), so the stock dependency set is 6.5 GB for
  172. nothing. See `ops/kitten/Dockerfile`.
  173. **Kitten voices** — the eight speakers every checkpoint ships. The sidecar is
  174. authoritative (`GET /voices`); this is the fallback list:
  175. `bella` `jasper` `luna` `bruno` `rosie` `hugo` `kiki` `leo`
  176. Ids are lowercase and never shared with edge, piper or Kokoro — passing a Kokoro
  177. id to `engine: "kitten"` is a `400` with the valid ids in the body.
  178. #### Kokoro voices
  179. 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.
  180. - **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`
  181. - **en-GB** (8): `bf_alice` `bf_emma` `bf_isabella` `bf_lily` `bm_daniel` `bm_fable` `bm_george` `bm_lewis`
  182. - **ja-JP** (5): `jf_alpha` `jf_gongitsune` `jf_nezumi` `jf_tebukuro` `jm_kumo`
  183. - **zh-CN** (8): `zf_xiaobei` `zf_xiaoni` `zf_xiaoxiao` `zf_xiaoyi` `zm_yunjian` `zm_yunxi` `zm_yunxia` `zm_yunyang`
  184. - **es-ES** (3): `ef_dora` `em_alex` `em_santa`
  185. - **fr-FR** (1): `ff_siwis`
  186. - **hi-IN** (4): `hf_alpha` `hf_beta` `hm_omega` `hm_psi`
  187. - **it-IT** (2): `if_sara` `im_nicola`
  188. - **pt-BR** (3): `pf_dora` `pm_alex` `pm_santa`
  189. The id prefix is `locale + gender` (`a`=American, `b`=British, `f`/`m`=female/male), so `bm_george` is a British male voice.
  190. ---
  191. ## Deploy on AWS (EC2 + Docker + Caddy)
  192. 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).
  193. **Short version**
  194. ```bash
  195. # on the instance
  196. sudo dnf install -y docker git
  197. sudo systemctl enable --now docker
  198. mkdir -p ~/koe-ops
  199. # copy ops/koe.env.example to ~/koe-ops/koe.env and fill in secrets
  200. # copy ops/rebuild.sh, ops/watchdog.sh, ops/disk-guard.sh, ops/backup.sh to ~/koe-ops/
  201. bash ~/koe-ops/rebuild.sh
  202. ```
  203. `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.
  204. 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`.
  205. **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.
  206. **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).
  207. > `render.yaml` remains in the repo as a legacy blueprint. It is not the production target.
  208. ---
  209. ## MCP server
  210. ### Hosted (recommended)
  211. 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.
  212. ### Local stdio (`mcp/`)
  213. 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.
  214. ```bash
  215. cd mcp
  216. npm install
  217. ```
  218. ### Register it
  219. Claude Desktop (`claude_desktop_config.json`):
  220. ```json
  221. {
  222. "mcpServers": {
  223. "koe-tts": {
  224. "command": "node",
  225. "args": ["C:/Users/User/koe/mcp/index.js"],
  226. "env": {
  227. "TTS_STUDIO_URL": "https://koe.kennedyazeru.space"
  228. }
  229. }
  230. }
  231. }
  232. ```
  233. Claude Code:
  234. ```bash
  235. claude mcp add koe-tts \
  236. -e TTS_STUDIO_URL=https://koe.kennedyazeru.space \
  237. -- node C:/Users/User/koe/mcp/index.js
  238. ```
  239. 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).
  240. ### Tools
  241. | Tool | What it does |
  242. | --- | --- |
  243. | `studio_status` | Pings `/health` and shows backend, engines, queue, limits, and your usage. Call first if something fails. |
  244. | `list_voices` | Voices by engine (`edge`/`piper`/`kokoro`/`kitten`) and optional language filter (`en`, `fr`, …). |
  245. | `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. |
  246. | `get_voiceover_status` | Job status by id (e.g. after a timeout). |
  247. | `list_recent_voiceovers` | Your last 10 jobs (tenant-isolated). |
  248. | `get_usage` | Requests/words this hour and today, limits, and reset times. |
  249. ### MCP environment variables
  250. | Var | Default | Meaning |
  251. | --- | --- | --- |
  252. | `TTS_STUDIO_URL` | `http://localhost:3000` | Base URL of the studio |
  253. | `TTS_API_KEY` | *(none)* | Optional explicit key; disables auto-registration |
  254. | `VOICEOVER_DIR` | `./voiceovers` | Where local audio files are saved |
  255. | `KOE_CREDENTIALS_FILE` | `~/.koe/credentials.json` | Where auto-registered free keys are stored |
  256. | `KOE_DISABLE_AUTO_REGISTER` | *(unset)* | Set to `1` to never mint a free key |
  257. Smoke-test the wiring without an agent:
  258. ```bash
  259. cd mcp && TTS_STUDIO_URL=http://localhost:3000 node test-client.js
  260. ```
  261. ---
  262. ## Server environment variables
  263. | Var | Default | Meaning |
  264. | --- | --- | --- |
  265. | `PORT` | `3000` | HTTP port |
  266. | `TTS_BACKEND` | auto | `native` or `docker` |
  267. | `KOKORO_BASE_URL` | `http://127.0.0.1:8880` | Where the optional Kokoro sidecar lives; the engine is unavailable when it does not answer |
  268. | `KITTEN_BASE_URL` | `http://127.0.0.1:8881` | Where the optional Kitten sidecar lives; same rule |
  269. | `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 |
  270. | `KOE_SECRET` | generated | **Set this in production.** Signs download links, hashed anon subjects and key ids (keys themselves are DB rows) |
  271. | `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 |
  272. | `API_KEY` | *(none)* | Admin key: unlimited, sees all jobs |
  273. | `KOE_REQUIRE_KEY` | `false` | Reject anonymous callers |
  274. | `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 |
  275. | `KOE_ALLOWED_ORIGINS` | *(none)* | Extra browser origins allowed by CORS (comma-separated). Same-origin, loopback origins and `file://` pages are always allowed |
  276. | `KOE_REGISTER_IP_DAY` | `3` | Free keys per IP per day |
  277. | `KOE_HOURLY_REQUESTS` | `60` | Requests/hour per key *(legacy name: `KOE_KEY_REQ_HOUR`)* |
  278. | `KOE_HOURLY_WORDS` | `2000` | Words/hour per key *(legacy: `KOE_KEY_WORDS_HOUR`)* |
  279. | `KOE_DAILY_WORDS` | `20000` | Words/day per key *(legacy: `KOE_KEY_WORDS_DAY`)* |
  280. | `KOE_ANON_REQ_HOUR` | `20` | Requests/hour per anonymous IP |
  281. | `KOE_ANON_WORDS_HOUR` | `500` | Words/hour per anonymous IP |
  282. | `KOE_ANON_WORDS_DAY` | `3000` | Words/day per anonymous IP |
  283. | `KOE_MAX_JOB_WORDS` | `2000` | Per-request word cap; larger jobs are `400` before counting *(legacy: `KOE_MAX_WORDS_PER_JOB`)* |
  284. | `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 |
  285. | `KOE_MAX_CHARS_PER_JOB` | `40000` | Per-request character cap (`413`) |
  286. | `KOE_MAX_CHARS_PER_PREVIEW` | `600` | Preview text cap |
  287. | `KOE_GLOBAL_CONCURRENCY` | `6` | Simultaneous upstream jobs |
  288. | `KOE_GLOBAL_QUEUE` | `20` | Max queued jobs |
  289. | `KOE_GLOBAL_DAILY_WORDS` | `30000` | Instance-wide hard daily word ceiling *(legacy: `KOE_GLOBAL_WORDS_DAY`)* |
  290. | `KOE_KILL_SWITCH` | `false` | `true` → `503 {"error":"temporarily_disabled"}` on every generation endpoint |
  291. | `TURNSTILE_SITEKEY` / `TURNSTILE_SECRET` | *(unset)* | Set **both** to swap the proof-of-work issuance gate for Cloudflare Turnstile |
  292. | `KOE_AUDIO_TTL_SEC` | `900` | Audio zip lifetime |
  293. | `KOE_JOB_TTL_SEC` | `3600` | Job metadata lifetime |
  294. | `KOE_PREVIEW_TTL_SEC` | `600` | Preview file lifetime |
  295. | `KOE_SWEEP_INTERVAL_SEC` | `60` | Cleanup sweep interval |
  296. | `KOE_COOLDOWN_SEC` | `60` | Base upstream failure cool-down (doubles, max 10 min) |
  297. | `KOE_STATE_FILE` | `.koe-state.json` | Only the generated `KOE_SECRET` fallback — counters live in SQLite |
  298. | `KOE_OUTPUT_DIR` | `./output` | Runtime audio/work/job directory |
  299. | `KOE_JOBS_FILE` | `output/jobs.json` | **Legacy** job file: imported into the database once at boot, then never written |
  300. | `KOE_EMBED_WORKER` | `true` | Run synthesis inside the server process; set `false` and run `node worker.js` to scale workers separately |
  301. | `KOE_WORKERS` | `KOE_GLOBAL_CONCURRENCY` | Worker loops per `worker.js` process |
  302. | `KOE_PART_CONCURRENCY` | `2` | Parts of one job synthesised in parallel |
  303. | `KOE_WORKER_POLL_MS` | `500` | How often an idle worker checks the queue |
  304. | `KOE_CACHE_MAX_MB` | `256` | Byte budget for the synthesis cache; oldest entries are pruned on write |
  305. | `KOE_STATS_FILE` | `.koe-stats.json` | Persisted traffic/voiceover counters used by `/stats` |
  306. | `KOE_PUBLIC_URL` | request origin | Absolute base used in hosted-MCP download links (set it if you run behind a proxy) |
  307. | `KOE_MCP_INLINE_AUDIO_MAX` | `3145728` | Max bytes of audio to inline in an MCP response; `0` returns only the link |
  308. | `KOE_MCP_POLL_MS` | `2000` | How often hosted `generate_voiceover` polls a job |
  309. | `KOE_DEFAULT_ENGINE` | `edge` | Default for callers that omit `engine`. Left unset in this deployment — edge stays the default |
  310. ## Operator analytics
  311. `/stats.html` is a public shell; its numbers come from the admin-only `/stats.json`. Open the page, paste `API_KEY`, and it reads:
  312. - **Traffic** — all HTTP hits, voiceover jobs, MCP calls, previews, downloads, and new keys, all-time and today.
  313. - **Product users** — unique subjects with a real product action (voiceover, MCP call, preview, download, or registration) in the last 5 minutes / hour / 24 hours.
  314. - **Visitors** — all unique subjects, including crawlers and page loads. The dashboard shows these separately so bot traffic cannot inflate the user count.
  315. - **Request sources** — top subjects by HTTP requests; **Voiceover users** — top subjects by words generated.
  316. - **Daily ledger** — 14 days of counters.
  317. 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.
  318. ---
  319. ## Notes
  320. - 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.
  321. - 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).
  322. - 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.
  323. ## Agent skill
  324. [`skills/koe-voiceover/SKILL.md`](skills/koe-voiceover/SKILL.md) packages this
  325. server as a portable `SKILL.md`: when to reach for a voiceover, how to get a free
  326. key, the tool table, script-formatting rules and the error table. Zip the folder
  327. to publish it to a skill marketplace.
  328. ## Support
  329. Koe is free and has no accounts, cards or paid APIs. Running it costs one small
  330. box and a domain, paid by one person. If it has been useful, you can
  331. [buy me a malt](https://buymeamalt.com/@azeru548) — naira checkout, which Buy Me a
  332. Coffee can't do for a Nigerian account.
  333. ## Licence
  334. Koe is free software under the **GNU Affero General Public License v3.0**
  335. (AGPL-3.0). © 2026 Azeru548. See [LICENSE](LICENSE) for the full text.
  336. You can use it, change it and run it — for your own videos, inside your
  337. company, or as part of a paid product. Two obligations are what make that safe
  338. for everyone:
  339. - **Share changes when you host it.** If you modify Koe and let other people use
  340. that modified version over a network — a public instance, a SaaS, an internal
  341. portal that other teams reach over HTTP — you must offer those users the
  342. complete corresponding source of your version, under the AGPL (§13). Running
  343. it privately for yourself or your own business requires no disclosure.
  344. - **Keep the notices.** Don't strip the copyright or the license, and mark a
  345. fork as changed (AGPL §5) — "based on Koe" is the fair way to say it.
  346. There is no warranty and no support contract. If the public instance is down or
  347. rate-limited, the license is what lets you run your own.
  348. ## What the license does not cover
  349. The AGPL covers this source code. It grants nothing for the **Koe name, the
  350. logo, or the domain `koe.kennedyazeru.space`**, and it does not permit presenting
  351. a fork as the official project or implying endorsement by it. If you run a
  352. public instance of your own, give it its own name — "based on Koe" is welcome,
  353. "Koe" as your brand is not. The hosted instance itself (its keys, its quota, its
  354. uptime) is not part of what this repository licenses.
  355. ## Contributing
  356. Issues and pull requests are welcome. For anything larger than a bug fix, open
  357. an issue first so the scope is agreed before you write code. Contributions are
  358. accepted under the project's AGPL-3.0 license — no CLA and no copyright
  359. assignment. Please keep keys, secrets and other people's audio out of issues and
  360. pull requests.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.