Python SDK — t2s
Text-to-speech from Python, with one-shot and streaming synthesis.
Install
Requires Python 3.10 or later. The package is imported as kotoba.
Configure
KotobaClient() reads its credentials and per-route URLs from environment
variables. For TTS you need:
Or pass them in code:
One URL covers every language. If one language is served by a separate deployment, register a language-specific route (it takes precedence for that language only):
Using the Kotoba apps on fal
The same SDK talks to the Kotoba apps published on fal. Use
your fal key as KOTOBA_API_KEY and point the service at its fal app; the
Authorization: Key … scheme is selected automatically for fal.run hosts:
An app that has been idle boots a GPU runner on the first request, which can take a few minutes; allow for that in the connect timeout or retry the first request.
One-shot synthesis
audio.to_wav() converts the underlying signal (pcm_f32 @ 24 kHz mono
unless you asked for another format) to a playable 16-bit WAV. The
AudioResult also exposes data, sample_rate, audio_format, and
content_type.
Available Japanese speakers: male-01 (default) and female-01. Pass
speaker_id=... to override (kotoba-sdk >= 0.2.2; older releases defaulted
to ja-man-m02-azawa, which current deployments reject with unknown_speaker_id):
Voice settings
voice_settings changes the speed, the pitch and the volume of the voice.
Every field is optional; an omitted field keeps its default. Requires
kotoba-sdk >= 0.3.0.
synthesize(...), synthesize_stream(...) and stream(...) accept it. The
server owns the ranges and rejects a value outside them with a
ProtocolError. kotoba.VoiceSettings is the matching TypedDict for static
type checking.
On a streaming session, stream(voice_settings=...) sets the default for
every response, and session.synthesize(..., voice_settings=...) overrides it
for one response, field by field; see
Streaming synthesis below.
Choosing an audio format
Pass audio_format= to pick the wire format and, for PCM, sample_rate=
(one of 8000 / 16000 / 24000):
The same audio_format / sample_rate kwargs are accepted by stream(...)
and synthesize_stream(...). Once the session is ready, session.sample_rate
and session.audio_format report the values the server negotiated.
Streaming synthesis
The full text is sent in a single frame; the server streams the synthesized audio back chunk-by-chunk, so you can play (or pipe to a speaker / WebRTC track) without waiting for the utterance to finish:
session.synthesize(text, response_id=None, voice_settings=None) sends the
whole text in one frame; session.cancel() aborts the in-flight response,
which then surfaces as done. One response runs at a time: read until done
before you call session.synthesize() again.
One session can speak several texts in sequence. The session’s
voice_settings apply to every response, and a response can override single
fields:
Long text. A response stops when it reaches the deployment’s length limit
(about two minutes of audio on fal kotoba-tts). This is not an error: the
audio already received is valid, and the done event carries
event.metadata["response"]["finish_reason"] == "length". Send long text as
several responses, for example one per paragraph. The max_length argument of
older releases is deprecated and ignored (kotoba-sdk >= 0.3.0).
synthesize_stream(...) flattens the loop when you only want PCM bytes:
Async
What’s in the box (TTS)
See the API reference for the on-the-wire protocol that this SDK wraps.