Skip to navigation

Python SDK — t2s

Text-to-speech from Python, with one-shot and streaming synthesis.

Install

pip install kotoba-sdk

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:

VariablePurpose
KOTOBA_API_KEYAPI key, sent as Authorization: Bearer … on the WebSocket handshake; the SDK picks the auth scheme from the endpoint host automatically
KOTOBA_TTS_URLWebSocket URL for TTS, e.g. wss://.../tts; the language is chosen per session

Or pass them in code:

import kotoba
client = kotoba.KotobaClient(
api_key="kotoba-...",
tts_ws_url="wss://.../tts",
)

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):

kotoba.register_endpoint("tts", None, "ko", "wss://.../tts-ko")

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:

export KOTOBA_API_KEY=<fal key>
export KOTOBA_TTS_URL=wss://fal.run/Kotoba-Technologies/kotoba-tts/v2/tts/ws

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

import kotoba
client = kotoba.KotobaClient()
audio = client.tts.synthesize("こんにちは、世界。", language="ja")
audio.to_wav("hello.wav")

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):

audio = client.tts.synthesize(
"こんにちは、世界。",
language="ja",
speaker_id="female-01",
)

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.

FieldMeaningRange on fal kotoba-ttsDefault
speedSpeaking-rate multiplier0.7 to 1.51.0
pitchPitch shift in semitones-4 to 40
volumeVolume multiplier0 to 2.01.0
audio = client.tts.synthesize(
"こんにちは、世界。",
language="ja",
voice_settings={"speed": 1.2, "pitch": -2},
)

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):

audio_formatSample rateNotes
pcm_f32 (default)8 / 16 / 24 kHz (default 24)32-bit float PCM; to_wav() works
pcm168 / 16 / 24 kHz (default 24)16-bit PCM; to_wav() works
mulawfixed 8 kHzG.711 μ-law, what Twilio Media Streams expect; to_wav() works
opusfixed 24 kHzSelf-contained Ogg/Opus stream; write result.data to a .ogg file — to_wav() raises ValueError
# 8 kHz G.711 mu-law for Twilio Media Streams
audio = client.tts.synthesize("こんにちは、世界。", language="ja", audio_format="mulaw")
audio.to_wav("hello_mulaw.wav")
# 16 kHz 16-bit PCM
audio = client.tts.synthesize(
"こんにちは、世界。", language="ja", audio_format="pcm16", sample_rate=16000
)
# Ogg/Opus — save the raw bytes
audio = client.tts.synthesize("こんにちは、世界。", language="ja", audio_format="opus")
with open("hello.ogg", "wb") as f:
f.write(audio.data)

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:

with client.tts.stream(language="ja") as session:
session.synthesize("こんにちは。本日はよろしくお願いします。")
for event in session:
if event.type == "audio_chunk":
handle(event.audio) # pcm_f32 @ 24 kHz unless you passed audio_format=
elif event.type == "done":
break

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:

with client.tts.stream(language="ja", voice_settings={"speed": 1.2, "volume": 0.8}) as session:
# The second response is also 2 semitones lower; both keep speed 1.2 and volume 0.8.
for text, voice in [("いらっしゃいませ。", None), ("少々お待ちください。", {"pitch": -2})]:
session.synthesize(text, voice_settings=voice)
for event in session: # the loop ends after this response's `done`
if event.type == "audio_chunk":
handle(event.audio)

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:

for pcm in client.tts.synthesize_stream("こんにちは、世界。", language="ja"):
speaker.write(pcm)

Async

import asyncio
import kotoba
async def main() -> None:
async with kotoba.AsyncKotobaClient() as client:
async with client.tts.stream(language="ja") as session:
await session.synthesize("こんにちは。")
async for event in session:
if event.type == "audio_chunk":
await play(event.audio)
elif event.type == "done":
break
asyncio.run(main())

What’s in the box (TTS)

SymbolWhat
client.tts.synthesize(text, language, ...)One-shot synthesis → AudioResult (speaker_id, audio_format, sample_rate, voice_settings)
client.tts.stream(language, ...)Streaming session you drive manually
client.tts.synthesize_stream(text, language, ...)Single text → audio-chunk iterator
kotoba.VoiceSettingsspeed / pitch / volume for a session or one response

See the API reference for the on-the-wire protocol that this SDK wraps.