Overview
Pipecat provides an event system that lets you hook into lifecycle changes across the framework — pipeline state transitions, service connections, transport activity, conversation turns, errors, and more.
Events are available on most Pipecat objects (anything that inherits from BaseObject). You register handlers using the @event_handler decorator, and Pipecat calls them automatically when things happen.
@task.event_handler("on_pipeline_started")
async def on_pipeline_started(task, frame):
print("Pipeline is running!")
@tts.event_handler("on_connected")
async def on_tts_connected(service):
print(f"TTS service connected: {service}")
Registering Event Handlers
Use the @event_handler decorator on the object that emits the event:
@object.event_handler("event_name")
async def handler(object, ...):
# Handle the event
...
async def my_handler(object, ...):
...
object.add_event_handler("event_name", my_handler)
async or synchronous functions — Pipecat detects which and calls them appropriately.
Multiple Handlers
You can register multiple handlers for the same event. They execute in the order they were registered:
@task.event_handler("on_pipeline_finished")
async def log_finished(task, frame):
print("Pipeline finished (handler 1)")
@task.event_handler("on_pipeline_finished")
async def cleanup(task, frame):
print("Cleaning up (handler 2)")
Synchronous vs Asynchronous Events
Events are either synchronous or asynchronous, depending on how the component registered them internally:
-
Synchronous events (
sync=True) run the handler inline — the caller waits for the handler to complete before continuing. These are used for events that must complete immediately, such as frame processing hooks and error handling. Synchronous event handlers should execute fast to avoid blocking the pipeline.
-
Asynchronous events (default) run the handler in a background
asyncio.Task. The caller continues immediately. These are used for events where you might do I/O, logging, or other work that shouldn’t block the pipeline.
You don’t need to choose — the sync/async behavior is determined by the component, not by your handler. Your handler can be an async def or a regular def regardless.
Events Reference
The table below lists all events available in Pipecat, grouped by component. Click through to the linked documentation for full details including handler signatures and usage examples.
Pipeline
Events on PipelineTask.
| Event | Description |
|---|
on_pipeline_started | Pipeline has started processing |
on_pipeline_finished | Pipeline reached a terminal state (stopped, ended, or cancelled) |
on_pipeline_error | An error frame reached the pipeline task |
on_frame_reached_upstream | A filtered frame type reached the pipeline source |
on_frame_reached_downstream | A filtered frame type reached the pipeline sink |
on_idle_timeout | No activity detected within the idle timeout period |
Frame Processor
Events on every FrameProcessor. Since all services, transports, and processors inherit from FrameProcessor, these events are available on any processor in your pipeline.
| Event | Description |
|---|
on_error | An error occurred in this processor |
on_before_process_frame | A frame is about to be processed |
on_after_process_frame | A frame has just been processed |
on_before_push_frame | A frame is about to be pushed to the next processor |
on_after_push_frame | A frame has just been pushed to the next processor |
Turn Management
Events on context aggregators from LLMContextAggregatorPair.
| Event | Emitter | Description |
|---|
on_user_turn_started | user_aggregator | User begins speaking |
on_user_turn_stopped | user_aggregator | User finishes speaking (includes transcript) |
on_user_turn_stop_timeout | user_aggregator | User turn ended due to timeout |
on_user_turn_idle | user_aggregator | User has been idle for configured timeout |
on_user_mute_started | user_aggregator | User input was muted |
on_user_mute_stopped | user_aggregator | User input was unmuted |
on_assistant_turn_started | assistant_aggregator | Assistant begins responding |
on_assistant_turn_stopped | assistant_aggregator | Assistant finishes responding (includes transcript) |
on_assistant_thought | assistant_aggregator | Assistant produced a thought (reasoning models) |
STT Services
Events on STT service instances. Available on all WebSocket-based STT services. See Service Events for details.
| Event | Description |
|---|
on_connected | WebSocket connection established |
on_disconnected | WebSocket connection closed |
on_connection_error | WebSocket connection error occurred |
| Event | Description |
|---|
on_speech_started | Speech detected in audio stream |
on_utterance_end | End of utterance detected |
| Event | Description |
|---|
on_start_of_turn | Start of a new turn detected |
on_turn_resumed | A previously paused turn has resumed |
on_end_of_turn | End of turn detected |
on_eager_end_of_turn | Early end-of-turn prediction |
on_update | Transcript updated |
| Event | Description |
|---|
on_speakers_result | Speaker identification result received |
| Event | Description |
|---|
on_speech_started | Speech detected |
on_speech_stopped | Speech stopped |
on_utterance_end | End of utterance detected |
TTS Services
Events on TTS service instances. Available on all WebSocket-based TTS services. See Service Events for details.
| Event | Description |
|---|
on_connected | WebSocket connection established |
on_disconnected | WebSocket connection closed |
on_connection_error | WebSocket connection error occurred |
on_tts_request | A TTS synthesis request is being sent |
LLM Services
Events on LLM service instances. See Service Events for details.
| Event | Description |
|---|
on_function_calls_started | LLM has started making function/tool calls |
on_completion_timeout | LLM response timed out |
| Event | Description |
|---|
on_conversation_item_created | A new conversation item was created |
on_conversation_item_updated | A conversation item was updated |
Daily Transport
Events on DailyTransport instances.
| Event | Description |
|---|
on_joined | Bot joined the room |
on_left | Bot left the room |
on_error | Transport error occurred |
on_call_state_updated | Call state changed |
on_client_connected | A participant connected |
on_client_disconnected | A participant disconnected |
on_first_participant_joined | First participant joined the room |
on_participant_joined | A participant joined |
on_participant_left | A participant left |
on_participant_updated | A participant’s state was updated |
on_active_speaker_changed | Active speaker changed |
on_app_message | App message received |
on_transcription_message | Transcription message received |
on_recording_started | Recording started |
on_recording_stopped | Recording stopped |
on_recording_error | Recording error occurred |
on_dialin_connected | Dial-in call connected |
on_dialin_ready | Dial-in SIP endpoint ready |
on_dialin_stopped | Dial-in call stopped |
on_dialin_error | Dial-in error occurred |
on_dialin_warning | Dial-in warning |
on_dialout_answered | Dial-out call answered |
on_dialout_connected | Dial-out call connected |
on_dialout_stopped | Dial-out call stopped |
on_dialout_error | Dial-out error occurred |
on_dialout_warning | Dial-out warning |
on_before_leave | About to leave the room (sync) |
LiveKit Transport
Events on LiveKitTransport instances.
| Event | Description |
|---|
on_connected | Connected to the room |
on_disconnected | Disconnected from the room |
on_participant_connected | A participant connected |
on_participant_disconnected | A participant disconnected |
on_first_participant_joined | First participant joined |
on_audio_track_subscribed | Audio track subscribed |
on_audio_track_unsubscribed | Audio track unsubscribed |
on_video_track_subscribed | Video track subscribed |
on_video_track_unsubscribed | Video track unsubscribed |
on_data_received | Data message received |
on_call_state_updated | Call state changed |
on_before_disconnect | About to disconnect (sync) |
WebSocket Transports
Events on WebSocket transport instances.
WebSocketServerTransport:
| Event | Description |
|---|
on_client_connected | Client connected |
on_client_disconnected | Client disconnected |
on_session_timeout | Session timed out |
on_websocket_ready | WebSocket server is ready |
| Event | Description |
|---|
on_client_connected | Client connected |
on_client_disconnected | Client disconnected |
on_session_timeout | Session timed out |
| Event | Description |
|---|
on_connected | Connected to server |
on_disconnected | Disconnected from server |
Other Transports
SmallWebRTCTransport:
| Event | Description |
|---|
on_client_connected | Client connected |
on_client_disconnected | Client disconnected |
on_app_message | App message received |
| Event | Description |
|---|
on_client_connected | Client connected |
on_client_disconnected | Client disconnected |
Utilities
ServiceSwitcher:
| Event | Description |
|---|
on_service_switched | Active service was switched |
| Event | Description |
|---|
on_transcript_update | Transcript was updated |
| Event | Description |
|---|
on_audio_data | Audio data available |
on_track_audio_data | Per-track audio data available |
on_user_turn_audio_data | User turn audio data available |
on_bot_turn_audio_data | Bot turn audio data available |
| Event | Description |
|---|
on_bot_started | Bot started |
on_client_ready | Client is ready |
on_client_message | Client message received |
Observers
TurnTrackingObserver:
| Event | Description |
|---|
on_turn_started | A conversation turn started |
on_turn_ended | A conversation turn ended |
| Event | Description |
|---|
on_latency_measured | Latency measurement available |
Extensions
VoicemailDetector:
| Event | Description |
|---|
on_conversation_detected | Live conversation detected (not voicemail) |
on_voicemail_detected | Voicemail detected |
| Event | Description |
|---|
on_conversation_detected | Live conversation detected |
on_ivr_status_changed | IVR navigation status changed |
