Python SDK — s2st
Speech-to-speech translation from Python, WebSocket streaming.
Install
Requires Python 3.10 or later. The package is imported as kotoba.
For live-microphone examples, install with the optional mic extra
(pulls in sounddevice, which needs PortAudio on the system):
Configure
KotobaClient() reads its credentials and per-route URLs from environment
variables. For S2ST you need:
Or pass them in code:
One URL covers every language pair. If one pair is served by a separate deployment, register it at runtime (it takes precedence for that pair 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 translation
translate(...) consumes a finished audio file and returns the
translated audio plus the source-side transcript:
translate() feeds the file at realtime pace (40 ms chunks), so wall time is
roughly the audio duration. result.audio is PCM16 @ 24 kHz (see
result.sample_rate and result.audio_format); result.transcript_target
is not populated by the current server.
Streaming translation
Use client.s2st.stream(...) for live audio in / live audio out — both
transcript deltas and synthesized chunks surface as the server produces
them:
Tuning latency with delay
Both stream(...) and translate(...) accept an optional delay
parameter — an integer in the range 0–20 that controls how many
tokens of context the server buffers before emitting translated audio.
Higher values give the model more lookahead (better translation
quality); lower values reduce latency. Omit it to keep the server
default.
Async
Both entry points have async equivalents via AsyncKotobaClient:
For a runnable mic demo see examples/s2st_mic_async.py in the SDK repo
(needs the mic extra — sounddevice — and PortAudio).
What’s in the box (S2ST)
See the API reference for the on-the-wire protocol that this SDK wraps.