Basic Usage

​

Installation

uv add trugen-sdk
# or with GUI extras:
uv add trugen-sdk --extra display

# pip equivalent:
pip install trugen-sdk[display]

​

Requirements

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

​

TruGenClient

from trugen import TruGenClient

# Initialize with your API key
client = TruGenClient(api_key="your-api-key")

# Create a session with your Agent ID
session = await client.create_session(agent_id="your-agent-id")

​

TruGenSession

​

Connection

• await session.connect(): Connect to the streaming room and publish the local microphone.
• await session.disconnect(): Disconnect and cleanly release all hardware/stream resources.

​

Audio Output

• await session.enable_audio_output(): Activates speaker playback with built-in echo cancellation. Call this once after connect().

​

Video & Audio Generators

• session.video_frames_bgr(): Async generator yielding NumPy arrays (NDArray) in BGR format, ready for OpenCV.
• session.video_frames(): Async generator yielding raw LiveKit VideoFrame objects.
• session.audio_frames(): Async generator yielding raw LiveKit AudioFrame objects.

​

Low-Level Accessors

• session.get_video_track(): Returns the remote RemoteVideoTrack object (or None).
• session.get_audio_track(): Returns the remote RemoteAudioTrack object (or None).
• session.room: Returns the underlying livekit.rtc.Room instance for advanced operations.

​

Direct session usage (async only)

import asyncio
import cv2
import os
from trugen import TruGenClient

async def main():
    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()

    async for frame in session.video_frames_bgr():
        cv2.imshow("Avatar", frame)
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break

    await session.disconnect()
    cv2.destroyAllWindows()

if __name__ == "__main__":
    asyncio.run(main())

​

TruGenRunner

​

Basic setup

from trugen import TruGenClient, TruGenRunner

async def create_session():
    client = TruGenClient(api_key="…")
    session = await client.create_session(agent_id="…")
    await session.connect()
    await session.enable_audio_output()
    return session

runner = TruGenRunner(session_factory=create_session)

​

Controls

• runner.run(): Starts the runner and blocks the main thread to run the rendering loop.
• runner.stop(): Safely stops the background loop and disconnects the session (thread-safe).
• runner.toggle_mute(): Toggles the microphone mute state (thread-safe).

​

Properties & Accessors

• runner.mic_muted: Returns True if the microphone is currently muted.
• runner.session_state: Returns the current session state enum (TruGenState).
• runner.session: Access the active TruGenSession instance (returns None until connected).
• runner.get_caption(): Returns a tuple (text, timestamp) containing the last received caption chunk and the monotonic timestamp it arrived.

​

The frame callback

@runner.on_frame
def on_frame(frame):
    if frame is not None:
        cv2.imshow("Avatar", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        runner.stop()

​

Session states

if runner.session_state == TruGenState.CONNECTED:
    print("Live!")

​

Error handling

import asyncio
from trugen import TruGenClient

client = TruGenClient(api_key="invalid-key")

async def main():
    try:
        session = await client.create_session(agent_id="my-agent")
        await session.connect()
    except RuntimeError as e:
        print(f"Connection failed: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

asyncio.run(main())

​

Next steps