Overview
Pipecat services emit events for connection lifecycle management and service-specific activity. These events let you monitor WebSocket connections, handle errors, and react to service behavior.
Connection Events
All WebSocket-based STT and TTS services share a common set of connection events. These are emitted by the base STTService and TTSService classes, so they work the same way regardless of which provider you use.
Events Summary
| Event | Available On | Description |
|---|
on_connected | STT, TTS | WebSocket connection established |
on_disconnected | STT, TTS | WebSocket connection closed |
on_connection_error | STT, TTS | WebSocket connection error occurred |
on_connected
Fired when the service’s WebSocket connection is established. This is useful for logging, monitoring connection health, or triggering actions that depend on the service being ready.
@stt.event_handler("on_connected")
async def on_stt_connected(service):
print(f"STT connected: {service.name}")
@tts.event_handler("on_connected")
async def on_tts_connected(service):
print(f"TTS connected: {service.name}")
| Parameter | Type | Description |
|---|
service | STTService / TTSService | The service instance |
Not all STT and TTS services use WebSocket connections. HTTP-based services (e.g., Azure TTS, Google TTS) do not emit connection events.
on_disconnected
Fired when the service’s WebSocket connection is closed, whether due to normal shutdown or an error.
@stt.event_handler("on_disconnected")
async def on_stt_disconnected(service):
print(f"STT disconnected: {service.name}")
| Parameter | Type | Description |
|---|
service | STTService / TTSService | The service instance |
on_connection_error
Fired when a WebSocket connection error occurs. The error is also pushed as an ErrorFrame through the pipeline.
@tts.event_handler("on_connection_error")
async def on_tts_connection_error(service, error):
print(f"TTS connection error: {error}")
| Parameter | Type | Description |
|---|
service | STTService / TTSService | The service instance |
error | str | The error message |
WebSocket-based services automatically reconnect with exponential backoff (3 retries, 4-10s waits) when connection errors occur. The on_connection_error event fires for each failed attempt.
TTS Events
on_tts_request
Fired just before a TTS synthesis request is sent to the service. This is useful for logging, monitoring, or modifying behavior based on what text is being synthesized.
@tts.event_handler("on_tts_request")
async def on_tts_request(service, context_id, text):
print(f"TTS synthesizing ({context_id}): {text}")
| Parameter | Type | Description |
|---|
service | TTSService | The TTS service instance |
context_id | str | The context ID for this TTS request |
text | str | The prepared text about to be synthesized |
LLM Events
on_function_calls_started
Fired when the LLM starts making function (tool) calls. This event is emitted before the function calls are executed.
@llm.event_handler("on_function_calls_started")
async def on_function_calls_started(service, function_calls):
for call in function_calls:
print(f"LLM calling function: {call.function_name}")
| Parameter | Type | Description |
|---|
service | LLMService | The LLM service instance |
function_calls | list | List of function call objects from the LLM |
on_completion_timeout
Fired when an LLM completion request times out. This can happen with slow models or large context windows. The timeout is also pushed as an error frame.
@llm.event_handler("on_completion_timeout")
async def on_completion_timeout(service):
print("LLM completion timed out — consider increasing timeout or reducing context")
| Parameter | Type | Description |
|---|
service | LLMService | The LLM service instance |
