Trugen AITruGen AI
← Back to PlayBook

Examples

July 8, 2026

Real-time Avatar Streaming using Python SDK

TGTruGen AIbeginner
View on PyPI ↗

Overview

This guide walks through the official TruGen AI Python SDK (trugen-sdk v1.1.0 on PyPI) for real-time AI avatar streaming.

All WebRTC and audio/video processing complexity (LiveKit, Acoustic Echo Cancellation, decoding, threading) is handled under the hood. You only need to import from trugen.

What you'll build

A Python app where:

  • A TruGen avatar streams synchronized audio and video in real time
  • Your microphone is published into the session
  • Speaker playback includes built-in acoustic echo cancellation
  • Video frames are available as OpenCV-ready BGR arrays via TruGenRunner

Prerequisites

  • Python 3.10+
  • TruGen API key
  • TruGen agent ID

Project setup

1. Install from PyPI

# Using uv (recommended)
uv add trugen-sdk

# With optional display utilities (for OpenCV and audio playback testing)
uv add trugen-sdk --extra display

# Using pip
pip install trugen-sdk

# With optional display utilities (for OpenCV and audio playback testing)
pip install trugen-sdk[display]

Package page: https://pypi.org/project/trugen-sdk/1.1.0/

2. Configure credentials

Set your API authentication credentials in a .env file or export them in your environment:

export TRUGEN_API_KEY="your-api-key"
export TRUGEN_AGENT_ID="your-agent-id"

3. Quick start — OpenCV video display with TruGenRunner

For most UI/desktop applications, TruGenRunner spawns a background event loop thread for the session and serves BGR video frames and state to the main thread safely.

import cv2
import os
from trugen import TruGenClient, TruGenRunner

# 1. Define how to connect to the session
async def create_session():
    client = TruGenClient(api_key=os.getenv("TRUGEN_API_KEY", ""))
    session = await client.create_session(agent_id=os.getenv("TRUGEN_AGENT_ID", ""))
    await session.connect()
    await session.enable_audio_output()  # Speaker + AEC in one call
    return session

# 2. Initialize the runner
runner = TruGenRunner(session_factory=create_session)

# 3. Handle incoming frames
@runner.on_frame
def show_frame(frame):
    if frame is not None:
        cv2.imshow("TruGen Avatar", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        runner.stop()

# 4. Start rendering loop (blocks main thread)
if __name__ == "__main__":
    runner.run()
    cv2.destroyAllWindows()

4. Run the app

python your_script.py

Press q in the video window to end the session.

Event hooks

Register handlers on TruGenRunner for captions, session state, and transcripts:

from trugen import TruGenState

@runner.on_caption
def on_caption(text: str):
    # Fired for each caption chunk as it arrives
    pass

@runner.on_state
def on_state(state: TruGenState):
    print(f"Status: {state.value}")

@runner.on_event("user.transcription_received")
def on_user_transcript(text: str):
    print(f"[User]  {text}")

@runner.on_event("agent.transcription_final")
def on_agent_transcript(text: str):
    print(f"[Agent] {text}")

You can also attach handlers directly on TruGenSession with @session.on() when not using TruGenRunner.

SDK reference (v1.1.0)

| Component | Purpose | | --- | --- | | TruGenClient | Entry point — create_session(agent_id=...) with your API key | | TruGenSession | Active WebRTC room — connect(), enable_audio_output(), video_frames_bgr(), mic control | | TruGenRunner | Thread-safe wrapper for GUI/desktop rendering — run(), stop(), on_frame |

Key session methods from the SDK:

  • await session.connect() — join the room and publish the local microphone
  • await session.enable_audio_output() — speaker playback with echo cancellation
  • session.video_frames_bgr() — async generator of OpenCV-ready BGR frames
  • runner.toggle_mute() — thread-safe microphone mute toggle

Detailed examples

The SDK repository includes interactive GUI examples referenced in the v1.1.0 release notes:

  • examples/basic_session_ui.py — status bar, mic indicators, and floating captions
  • examples/advanced_session_ui.py — WAV audio injection, reconnect handling, and complete transcripts

Repository: https://github.com/trugenai/python-sdk

Requirements

  • Python 3.10+
  • Core dependencies: livekit (>=0.11.0), aiohttp (>=3.8.0), python-dotenv (>=1.0.0)
  • Optional [display] extra: opencv-python (>=4.8.0), sounddevice (>=0.4.6), numpy (>=1.24.0)

Result

  • A working realtime avatar session from Python without managing WebRTC directly
  • Live video rendering with OpenCV via TruGenRunner
  • Event-driven access to captions and transcripts

Links