nika:tts_generate is the image pipeline’s sibling for audio: one file
lands under a permit-gated output_dir:, sha256-named, manifest beside it,
and audio bytes never ride workflow outputs — tasks pass a path and a
hash, not megabytes of base64.
The five providers
Keys and the local URL are engine config, never workflow args:
OPENAI_API_KEY / ELEVENLABS_API_KEY (or NIKA_-prefixed),
NIKA_TTS_LOCAL_URL (+ optional NIKA_TTS_LOCAL_API_KEY). nika doctor
prints a tts line naming what’s wired. The system voice needs neither.
Quickstart
Speak with no key: provider: system
Real speech, offline, with nothing to install on a Mac: provider: system
uses the host’s own synthesizer, macOS /usr/bin/say or Linux espeak-ng
(found in an absolute directory of the engine’s PATH).
- Nika starts the program itself, as part of the builtin: the workflow
needs no
permits.exec, andnika checknames the program in its plan. Each start is journaled as apermit_checkedframe on thebuiltinplane. The WAV still lands underoutput_dir:throughpermits.fs.write. - The text is spoken as text. It reaches the synthesizer on standard
input, and every
[[(whichsayreads as an embedded command andespeak-ngas phonemes) is broken by a space, so a script cannot mute the file. The audio is capped at 64 MiB. - No model choice. The model is the program (
sayorespeak-ng); any othermodel:is refused at check and at run.voice:is a host voice name (say -v '?'lists them on a Mac) and must be installed: a missing voice fails the call rather than reading with the default one. - No fallback. A host with no synthesizer fails
NIKA-BUILTIN-TTS_GENERATE-002, naming what is missing; Nika never switches to another provider. - Unpriced, never free. The voice bills no provider, so its cost is
reported as unpriced local work (
cost_usd: nullwithcost_unpriced: local_model), the way a local model’s is. It runs under any cost cap.
Honesty rules
- The extension follows the bytes. WAV
RIFF…WAVEand MP3 headers are sniffed; a mislabel is aformat_mismatch:warning, a non-audio payload is a hard error — never a corrupt file on disk. - Duration is exact or absent. WAV
duration_msis pure header math over the bytes actually present, so a streamed WAV whose header still carries a placeholder size reports its real length; MP3 duration is honestlynullrather than a frame-walking guess. text:caps at 4096 chars (the strictest wire’s limit, held portably) — fan longer scripts out withfor_eachover paragraphs.- Content credentials are detected, not verified: audio C2PA carriage
(RIFF
C2PA· MP3 GEOB) is surfaced ascontent_credentialsin output and manifest, the same contract as images. - Watermarking is declared, never byte-verified. The manifest’s
watermark_declaredis a catalog fact:elevenlabs→"synthid (provider-declared · not byte-verified)", every other provider →null— no such declaration, honestly absent.
Paid speech under a cost cap
Paid speech is billed per character of the text sent, at the rates of the engine’s dated price table (cost_basis: catalog_rate_x_characters, with the
date of the rates in cost_as_of):
Under
--max-cost-usd, a project ceiling: or a beat’s plafond:, a
literal text: is floored at launch, and a text that only the run renders is
judged on its rendered characters just before the request: nika check
marks it METERED — billed per character of the text the run renders, and
only a zero cap refuses it at launch. A call that fails after the provider
answered keeps what it billed.
OpenAI’s default voice, gpt-4o-mini-tts, has no price Nika can apply:
OpenAI prices it per token, and its speech response reports no usage. Nor
does a model id the table does not list, such as eleven_multilingual_v1. A
capped run refuses them before any request (NIKA-1709, or NIKA-1704 when
only the run decides the model), and nika arm shows a beat that uses them
UNREADY. Set model: tts-1 or tts-1-hd, use a priced ElevenLabs model, or
speak with provider: system, local or mock, which bill no provider.
Without a cap the call runs and is counted as unpriced
(Cost honesty).
The table bills list prices: an ElevenLabs plan’s prepaid characters are not
counted, so a cap can refuse speech your plan already covers. OpenAI shuts
down tts-1, tts-1-hd and gpt-4o-mini-tts on 2027-01-06.
Cookbook (proven against live APIs)
An LLM writes the script, another model speaks it — one run:Local CPU synthesis gets a 300s default timeout (
timeout_ms: up to
600000); clouds default to 120s. Sub-second values are refused — under 1s
is a typo’d unit.