From 3fce88555fc2aba5ac5dea80e218100a5b12c43c Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Fri, 13 Feb 2026 09:39:44 -0500 Subject: [PATCH] Improve events docstrings --- src/pipecat/services/deepgram/flux/stt.py | 14 +++++ src/pipecat/services/deepgram/stt.py | 11 ++++ src/pipecat/services/sarvam/stt.py | 12 ++++ src/pipecat/services/speechmatics/stt.py | 10 ++++ src/pipecat/transports/daily/transport.py | 55 +++++++++++++++++++ src/pipecat/transports/heygen/transport.py | 11 ++++ src/pipecat/transports/livekit/transport.py | 35 ++++++++++++ .../transports/smallwebrtc/transport.py | 12 ++++ src/pipecat/transports/tavus/transport.py | 11 ++++ src/pipecat/transports/websocket/client.py | 11 ++++ src/pipecat/transports/websocket/fastapi.py | 12 ++++ src/pipecat/transports/websocket/server.py | 13 +++++ 12 files changed, 207 insertions(+) diff --git a/src/pipecat/services/deepgram/flux/stt.py b/src/pipecat/services/deepgram/flux/stt.py index 547eca0de..5b091862c 100644 --- a/src/pipecat/services/deepgram/flux/stt.py +++ b/src/pipecat/services/deepgram/flux/stt.py @@ -73,6 +73,20 @@ class DeepgramFluxSTTService(WebsocketSTTService): Provides real-time speech recognition using Deepgram's WebSocket API with Flux capabilities. Supports configurable models, VAD events, and various audio processing options including advanced turn detection and EagerEndOfTurn events for improved conversational AI performance. + + Event handlers available (in addition to WebsocketSTTService events): + + - on_speech_started(service): Deepgram detected start of speech + - on_utterance_end(service): Deepgram detected end of utterance + - on_end_of_turn(service): Deepgram detected end of turn (EOT) + - on_eager_end_of_turn(service): Deepgram predicted end of turn (EagerEOT) + - on_turn_resumed(service): User resumed speaking after EagerEOT + + Example:: + + @stt.event_handler("on_end_of_turn") + async def on_end_of_turn(service): + ... """ class InputParams(BaseModel): diff --git a/src/pipecat/services/deepgram/stt.py b/src/pipecat/services/deepgram/stt.py index 0f79499ba..c4f72e6c3 100644 --- a/src/pipecat/services/deepgram/stt.py +++ b/src/pipecat/services/deepgram/stt.py @@ -50,6 +50,17 @@ class DeepgramSTTService(STTService): Provides real-time speech recognition using Deepgram's WebSocket API. Supports configurable models, languages, and various audio processing options. + + Event handlers available (in addition to STTService events): + + - on_speech_started(service): Deepgram detected start of speech + - on_utterance_end(service): Deepgram detected end of utterance + + Example:: + + @stt.event_handler("on_speech_started") + async def on_speech_started(service): + ... """ def __init__( diff --git a/src/pipecat/services/sarvam/stt.py b/src/pipecat/services/sarvam/stt.py index aae1ae243..13277fe96 100644 --- a/src/pipecat/services/sarvam/stt.py +++ b/src/pipecat/services/sarvam/stt.py @@ -134,6 +134,18 @@ class SarvamSTTService(STTService): """Sarvam speech-to-text service. Provides real-time speech recognition using Sarvam's WebSocket API. + + Event handlers available (in addition to STTService events): + + - on_connected(service): Connected to Sarvam WebSocket + - on_disconnected(service): Disconnected from Sarvam WebSocket + - on_connection_error(service, error): Connection error occurred + + Example:: + + @stt.event_handler("on_connected") + async def on_connected(service): + ... """ class InputParams(BaseModel): diff --git a/src/pipecat/services/speechmatics/stt.py b/src/pipecat/services/speechmatics/stt.py index ca949a9fd..72f3f3990 100644 --- a/src/pipecat/services/speechmatics/stt.py +++ b/src/pipecat/services/speechmatics/stt.py @@ -86,6 +86,16 @@ class SpeechmaticsSTTService(STTService): This service provides real-time speech-to-text transcription using the Speechmatics API. It supports partial and final transcriptions, multiple languages, various audio formats, and speaker diarization. + + Event handlers available (in addition to STTService events): + + - on_speakers_result(service, speakers): Speaker diarization results received + + Example:: + + @stt.event_handler("on_speakers_result") + async def on_speakers_result(service, speakers): + ... """ # Export related classes as class attributes diff --git a/src/pipecat/transports/daily/transport.py b/src/pipecat/transports/daily/transport.py index 20a0be29f..e3b246253 100644 --- a/src/pipecat/transports/daily/transport.py +++ b/src/pipecat/transports/daily/transport.py @@ -2039,6 +2039,61 @@ class DailyTransport(BaseTransport): Provides comprehensive Daily integration including audio/video streaming, transcription, recording, dial-in/out functionality, and real-time communication features for conversational AI applications. + + Event handlers available: + + - on_joined: Called when the bot joins the room. Args: (data: dict) + - on_left: Called when the bot leaves the room. + - on_before_leave: [sync] Called just before the bot leaves the room. + - on_error: Called when a transport error occurs. Args: (error: str) + - on_call_state_updated: Called when the call state changes. Args: (state: str) + - on_first_participant_joined: Called when the first participant joins. + Args: (participant: dict) + - on_participant_joined: Called when any participant joins. + Args: (participant: dict) + - on_participant_left: Called when a participant leaves. + Args: (participant: dict, reason: str) + - on_participant_updated: Called when a participant's state changes. + Args: (participant: dict) + - on_client_connected: Called when a participant connects (alias for + on_participant_joined). Args: (participant: dict) + - on_client_disconnected: Called when a participant disconnects (alias for + on_participant_left). Args: (participant: dict) + - on_active_speaker_changed: Called when the active speaker changes. + Args: (participant: dict) + - on_app_message: Called when an app message is received. + Args: (message: Any, sender: str) + - on_transcription_message: Called when a transcription message is received. + Args: (message: dict) + - on_recording_started: Called when recording starts. Args: (status: str) + - on_recording_stopped: Called when recording stops. Args: (stream_id: str) + - on_recording_error: Called when a recording error occurs. + Args: (stream_id: str, message: str) + - on_dialin_connected: Called when a dial-in call connects. Args: (data: dict) + - on_dialin_ready: Called when the SIP endpoint is ready. + Args: (sip_endpoint: str) + - on_dialin_stopped: Called when a dial-in call stops. Args: (data: dict) + - on_dialin_error: Called when a dial-in error occurs. Args: (data: dict) + - on_dialin_warning: Called when a dial-in warning occurs. Args: (data: dict) + - on_dialout_answered: Called when a dial-out call is answered. Args: (data: dict) + - on_dialout_connected: Called when a dial-out call connects. Args: (data: dict) + - on_dialout_stopped: Called when a dial-out call stops. Args: (data: dict) + - on_dialout_error: Called when a dial-out error occurs. Args: (data: dict) + - on_dialout_warning: Called when a dial-out warning occurs. Args: (data: dict) + + Example:: + + @transport.event_handler("on_first_participant_joined") + async def on_first_participant_joined(transport, participant): + await task.queue_frame(TTSSpeakFrame("Hello!")) + + @transport.event_handler("on_participant_left") + async def on_participant_left(transport, participant, reason): + await task.queue_frame(EndFrame()) + + @transport.event_handler("on_app_message") + async def on_app_message(transport, message, sender): + logger.info(f"Message from {sender}: {message}") """ def __init__( diff --git a/src/pipecat/transports/heygen/transport.py b/src/pipecat/transports/heygen/transport.py index 2ff1c7d56..dbeded3e5 100644 --- a/src/pipecat/transports/heygen/transport.py +++ b/src/pipecat/transports/heygen/transport.py @@ -289,6 +289,17 @@ class HeyGenTransport(BaseTransport): When used, the Pipecat bot joins the same virtual room as the HeyGen Avatar and the user. This is achieved by using `HeyGenTransport`, which initiates the conversation via `HeyGenApi` and obtains a room URL that all participants connect to. + + Event handlers available: + + - on_client_connected(transport, participant): Participant connected to the session + - on_client_disconnected(transport, participant): Participant disconnected from the session + + Example:: + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, participant): + ... """ def __init__( diff --git a/src/pipecat/transports/livekit/transport.py b/src/pipecat/transports/livekit/transport.py index ab7325c68..1902e7cd3 100644 --- a/src/pipecat/transports/livekit/transport.py +++ b/src/pipecat/transports/livekit/transport.py @@ -950,6 +950,41 @@ class LiveKitTransport(BaseTransport): Provides comprehensive LiveKit integration including audio streaming, data messaging, participant management, and room event handling for conversational AI applications. + + Event handlers available: + + - on_connected: Called when the bot connects to the room. + - on_disconnected: Called when the bot disconnects from the room. + - on_before_disconnect: [sync] Called just before the bot disconnects. + - on_call_state_updated: Called when the call state changes. Args: (state: str) + - on_first_participant_joined: Called when the first participant joins. + Args: (participant_id: str) + - on_participant_connected: Called when a participant connects. + Args: (participant_id: str) + - on_participant_disconnected: Called when a participant disconnects. + Args: (participant_id: str) + - on_participant_left: Called when a participant leaves. + Args: (participant_id: str, reason: str) + - on_audio_track_subscribed: Called when an audio track is subscribed. + Args: (participant_id: str) + - on_audio_track_unsubscribed: Called when an audio track is unsubscribed. + Args: (participant_id: str) + - on_video_track_subscribed: Called when a video track is subscribed. + Args: (participant_id: str) + - on_video_track_unsubscribed: Called when a video track is unsubscribed. + Args: (participant_id: str) + - on_data_received: Called when data is received from a participant. + Args: (data: bytes, participant_id: str) + + Example:: + + @transport.event_handler("on_first_participant_joined") + async def on_first_participant_joined(transport, participant_id): + await task.queue_frame(TTSSpeakFrame("Hello!")) + + @transport.event_handler("on_participant_disconnected") + async def on_participant_disconnected(transport, participant_id): + await task.queue_frame(EndFrame()) """ def __init__( diff --git a/src/pipecat/transports/smallwebrtc/transport.py b/src/pipecat/transports/smallwebrtc/transport.py index 4389ff5d9..dc91588a3 100644 --- a/src/pipecat/transports/smallwebrtc/transport.py +++ b/src/pipecat/transports/smallwebrtc/transport.py @@ -864,6 +864,18 @@ class SmallWebRTCTransport(BaseTransport): Provides bidirectional audio and video streaming over WebRTC connections with support for application messaging and connection event handling. + + Event handlers available: + + - on_client_connected(transport, client): Client connected to WebRTC session + - on_client_disconnected(transport, client): Client disconnected from WebRTC session + - on_client_message(transport, message, client): Received a data channel message + + Example:: + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, client): + ... """ def __init__( diff --git a/src/pipecat/transports/tavus/transport.py b/src/pipecat/transports/tavus/transport.py index 8e91e2713..c8a79d386 100644 --- a/src/pipecat/transports/tavus/transport.py +++ b/src/pipecat/transports/tavus/transport.py @@ -661,6 +661,17 @@ class TavusTransport(BaseTransport): When used, the Pipecat bot joins the same virtual room as the Tavus Avatar and the user. This is achieved by using `TavusTransportClient`, which initiates the conversation via `TavusApi` and obtains a room URL that all participants connect to. + + Event handlers available: + + - on_client_connected(transport, participant): Participant connected to the session + - on_client_disconnected(transport, participant): Participant disconnected from the session + + Example:: + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, participant): + ... """ def __init__( diff --git a/src/pipecat/transports/websocket/client.py b/src/pipecat/transports/websocket/client.py index e24352575..b5b99ee97 100644 --- a/src/pipecat/transports/websocket/client.py +++ b/src/pipecat/transports/websocket/client.py @@ -471,6 +471,17 @@ class WebsocketClientTransport(BaseTransport): Provides a complete WebSocket client transport implementation with input and output capabilities, connection management, and event handling. + + Event handlers available: + + - on_connected(transport): Connected to WebSocket server + - on_disconnected(transport): Disconnected from WebSocket server + + Example:: + + @transport.event_handler("on_connected") + async def on_connected(transport): + ... """ def __init__( diff --git a/src/pipecat/transports/websocket/fastapi.py b/src/pipecat/transports/websocket/fastapi.py index d4f5809d9..f52123e52 100644 --- a/src/pipecat/transports/websocket/fastapi.py +++ b/src/pipecat/transports/websocket/fastapi.py @@ -534,6 +534,18 @@ class FastAPIWebsocketTransport(BaseTransport): Provides bidirectional WebSocket communication with frame serialization, session management, and event handling for client connections and timeouts. + + Event handlers available: + + - on_client_connected(transport, websocket): Client WebSocket connected + - on_client_disconnected(transport, websocket): Client WebSocket disconnected + - on_session_timeout(transport, websocket): Session timed out + + Example:: + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, websocket): + ... """ def __init__( diff --git a/src/pipecat/transports/websocket/server.py b/src/pipecat/transports/websocket/server.py index 16964cb9b..e5f628fa4 100644 --- a/src/pipecat/transports/websocket/server.py +++ b/src/pipecat/transports/websocket/server.py @@ -421,6 +421,19 @@ class WebsocketServerTransport(BaseTransport): Provides a complete WebSocket server implementation with separate input and output transports, client connection management, and event handling for real-time audio and data streaming applications. + + Event handlers available: + + - on_client_connected(transport, websocket): Client WebSocket connected + - on_client_disconnected(transport, websocket): Client WebSocket disconnected + - on_session_timeout(transport, websocket): Session timed out + - on_websocket_ready(transport): WebSocket server is ready to accept connections + + Example:: + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, websocket): + ... """ def __init__(