Python SDK / Session
Session
A Session is returned by
ZeliClient.connect.
You don't construct it directly.
from zeli import SessionProperties
| Property | Type | Description |
|---|---|---|
session_id | str | Server-issued id for this session. |
avatar | str | None | Concrete avatar the server resolved. |
is_active | bool | False once the session is closed. |
has_control_channel | bool | True when the full control gateway is available (enables talk / talk streams / streaming events). |
Media
video_frames() -> AsyncIterator
Yields inbound video frames (PyAV VideoFrame). Use
frame.to_ndarray(format="rgb24").
audio_frames() -> AsyncIterator
Yields inbound audio frames (PyAV AudioFrame, 48 kHz stereo int16 PCM).
Both iterators end when the session closes. See Receiving media.
Driving the avatar
send_message(text, *, avatar=None)
Sends user text through the conversational model; the avatar speaks the reply.
Emits message/speech events. Falls back to an HTTP POST /api/chat when the
control gateway is absent. Raises ValueError on empty text.
talk(text, *, tone=None)
Speaks text directly through TTS, bypassing the model. Does not affect history.
Requires the control gateway (else raises SessionError). Optional tone
colours the delivery (e.g. "confident", "happy").
create_talk_stream(*, tone=None) -> TalkStream
Returns a TalkStream for pushing text incrementally.
Requires the control gateway.
interrupt()
Stops the avatar mid-utterance (barge-in). Emits TALK_STREAM_INTERRUPTED.
Talking to the avatar
start_voice(*, sample_rate=16000, avatar=None, voice=None, muted=False, timeout=15.0)
Opens the microphone socket and returns a VoiceSession. You push
PCM in; the SDK owns the socket and the protocol and does not capture a
microphone, which is a deliberate difference from the JavaScript SDK and is
argued on that page. Returns once the server is actually listening; a server that
accepts the socket and then refuses raises a VoiceSocketError carrying its own
close code.
voice
The microphone session currently open, or None. One at a time: the server holds
a single microphone slot per live session. Closing the session closes it too.
talk and create_talk_stream require the server's
control gateway. On a server without it they raise
SessionError. Check
session.has_control_channel and use send_message
instead, or upgrade the server.
Lifecycle
wait_until_closed()
Blocks until the session ends (server close, media failure, or close()).
close()
Tears the session down and releases all resources. Called automatically when the
session is used as an async with context manager.