pipecat-rtzr

Streaming Korean speech-to-text for Pipecat, using the RTZR (Return Zero) VITO WebSocket API.

Status: alpha (0.1.0). Unit and mock-server tests run without credentials. Streaming, Finalize, EOS, token refresh and reconnect were checked against the live RTZR service on 2026-10-21 with short synthesized Korean clips (see scripts/live_check.py). Not yet tried with real telephone audio or long calls.

RTZR's sommers_ko model is tuned for Korean telephone audio (8 kHz), which makes it a good fit for call-center voice agents.

Installation

pip install pipecat-rtzr

Prerequisites

• An RTZR account. Create a client in the RTZR Developers Console to get a client_id and client_secret (new accounts include free minutes).
• Set the credentials as environment variables:

export RTZR_CLIENT_ID=...
export RTZR_CLIENT_SECRET=...

Usage

from pipecat_rtzr import RTZRSTTService

stt = RTZRSTTService(
    settings=RTZRSTTService.Settings(
        domain="CALL",
        use_punctuation=True,
        keywords=[("리턴제로", 3.0), "상담원"],
    ),
)

pipeline = Pipeline([transport.input(), stt, user_aggregator, llm, tts, transport.output()])

See example.py for a complete bot, and example_mock.py for a run that needs no credentials.

Behavior

• Audio is streamed as 16-bit mono PCM (LINEAR16, 8 to 48 kHz).
• Partial results become InterimTranscriptionFrames; completed utterances become TranscriptionFrames.
• When the VAD reports the end of speech, a Finalize message closes the utterance right away (vad_force_finalize=True, the default).
• The access token is cached and refreshed before it expires. A rejected handshake (HTTP 401) fetches a new token and retries once.
• Idle connections are kept alive with silent audio (RTZR closes sockets after 60 s without audio).
• On shutdown the service sends EOS so the last utterance is flushed, and waits up to eos_flush_timeout seconds (default 2) for its final transcript when one is still open.
• If the socket drops, the service reconnects automatically. Audio of the utterance that was in progress when the socket dropped is not replayed, so that utterance is lost.
• Changing a setting at runtime reconnects the stream.

Settings

Streaming concurrency is limited by your RTZR plan (5 channels on the free tier).

Development

uv venv && uv pip install -e . pytest pytest-asyncio ruff
pytest          # unit tests and mock-server integration tests, no credentials needed
ruff check . && ruff format --check .

Compatibility

Tested with Pipecat 1.13.0 and Python 3.12 (Windows).

License

BSD 2-Clause.