> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trugen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List all events

> Complete reference of all events emitted by the TruGen Python SDK.

Register listener callbacks on a `TruGenSession` via `@session.on()` or on a `TruGenRunner` via `@runner.on_event()`. Both accept either a `TruGenEvent` enum value or a string event name.

## Enum-based events (`TruGenEvent`)

<ResponseField name="STATE_CHANGED" type="state: TruGenState">
  Fired when the session state changes (e.g., to `CONNECTED`, `DISCONNECTED`).
</ResponseField>

<ResponseField name="CONNECTION_ESTABLISHED" type="void">
  Fired when the WebRTC connection is successfully established.
</ResponseField>

<ResponseField name="CONNECTION_CLOSED" type="reason: DisconnectReason">
  Fired when the session room disconnects.
</ResponseField>

<ResponseField name="VIDEO_STREAM_STARTED" type="track: RemoteVideoTrack">
  Fired when the remote video track from the avatar is subscribed.
</ResponseField>

<ResponseField name="AUDIO_STREAM_STARTED" type="track: RemoteAudioTrack">
  Fired when the remote audio track from the avatar is subscribed.
</ResponseField>

<ResponseField name="INPUT_AUDIO_STREAM_STARTED" type="void">
  Fired when the local microphone audio stream begins publishing.
</ResponseField>

<ResponseField name="AGENT_SPEAKING_STARTED" type="void">
  Fired when the avatar starts speaking.
</ResponseField>

<ResponseField name="AGENT_SPEAKING_ENDED" type="void">
  Fired when the avatar stops speaking.
</ResponseField>

<ResponseField name="USER_SPEECH_STARTED" type="void">
  Fired when the user starts speaking. Useful for showing an active listening indicator.
</ResponseField>

<ResponseField name="USER_SPEECH_ENDED" type="void">
  Fired when the user finishes speaking.
</ResponseField>

<ResponseField name="TEXT_CHUNK_RECEIVED" type="text: str">
  Fired when a real-time transcription / caption chunk is received.
</ResponseField>

<ResponseField name="MIC_PERMISSION_PENDING" type="void">
  Fired when microphone permission is being requested.
</ResponseField>

<ResponseField name="MIC_PERMISSION_GRANTED" type="void">
  Fired when microphone permission has been granted.
</ResponseField>

<ResponseField name="MIC_PERMISSION_DENIED" type="void">
  Fired when microphone permission has been denied.
</ResponseField>

<ResponseField name="ERROR" type="error: Exception">
  Fired when a session or connection error occurs.
</ResponseField>

## String-based events

Some events don't have a dedicated enum entry — subscribe by string name instead.

<ResponseField name={`"user.transcription_received"`} type="text: str">
  Fired when the user completes a final utterance (the fully committed transcript, not a streaming chunk).
</ResponseField>

<ResponseField name={`"agent.transcription_final"`} type="text: str">
  Fired when the agent completes a final utterance. Use alongside `TEXT_CHUNK_RECEIVED` for streaming captions plus finalized transcripts.
</ResponseField>

<ResponseField name={`"connection.reconnecting"`} type="void">
  Fired when a transient network reconnection begins.
</ResponseField>

<ResponseField name={`"connection.reconnected"`} type="void">
  Fired when a network reconnection completes.
</ResponseField>

<ResponseField name={`"connection.quality_changed"`} type="(participant, quality)">
  Fired when a participant's connection quality changes.
</ResponseField>

## Runner-only decorators

These fire on the main thread and are only available on `TruGenRunner`:

<ResponseField name="@runner.on_frame" type="frame: numpy.ndarray | None">
  Called with each new BGR video frame (a NumPy array) or `None` when no frame is currently available.
</ResponseField>

<ResponseField name="@runner.on_caption" type="text: str">
  Called with each streaming caption chunk as it arrives.
</ResponseField>

<ResponseField name="@runner.on_state" type="state: TruGenState">
  Called on every session state transition.
</ResponseField>

## Session states (`TruGenState`)

| Enum Value                 | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `TruGenState.INITIALIZING` | Session created but not yet connected            |
| `TruGenState.CONNECTING`   | WebRTC handshake and connection in progress      |
| `TruGenState.CONNECTED`    | Connection established; actively streaming media |
| `TruGenState.DISCONNECTED` | Session ended and connection closed              |
| `TruGenState.ERROR`        | Unrecoverable error occurred                     |