From 7bbac110842002dcdeace7acd6af7b4aeb00c940 Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Wed, 23 Apr 2025 14:13:20 -0400
Subject: [PATCH] Add docstrings to TelnyxFrameSerializer

---
 src/pipecat/serializers/telnyx.py | 77 +++++++++++++++++++++++++++++--
 1 file changed, 73 insertions(+), 4 deletions(-)

diff --git a/src/pipecat/serializers/telnyx.py b/src/pipecat/serializers/telnyx.py
index 0eb75c753..61a89c7f0 100644
--- a/src/pipecat/serializers/telnyx.py
+++ b/src/pipecat/serializers/telnyx.py
@@ -34,9 +34,40 @@ from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializer
 
 
 class TelnyxFrameSerializer(FrameSerializer):
+    """Serializer for Telnyx WebSocket protocol.
+
+    This serializer handles converting between Pipecat frames and Telnyx's WebSocket
+    media streams protocol. It supports audio conversion, DTMF events, and automatic
+    call termination.
+
+    When auto_hang_up is enabled (default), the serializer will automatically terminate
+    the Telnyx call when an EndFrame or CancelFrame is processed, but requires Telnyx
+    credentials to be provided.
+
+    Attributes:
+        _stream_id: The Telnyx Stream ID.
+        _call_control_id: The associated Telnyx Call Control ID.
+        _api_key: Telnyx API key for API access.
+        _params: Configuration parameters.
+        _telnyx_sample_rate: Sample rate used by Telnyx (typically 8kHz).
+        _sample_rate: Input sample rate for the pipeline.
+        _resampler: Audio resampler for format conversion.
+        _hangup_attempted: Flag to track if hang-up has been attempted.
+    """
+
     class InputParams(BaseModel):
-        telnyx_sample_rate: int = 8000  # Default Telnyx rate (8kHz)
-        sample_rate: Optional[int] = None  # Pipeline input rate
+        """Configuration parameters for TelnyxFrameSerializer.
+
+        Attributes:
+            telnyx_sample_rate: Sample rate used by Telnyx, defaults to 8000 Hz.
+            sample_rate: Optional override for pipeline input sample rate.
+            inbound_encoding: Audio encoding for data sent to Telnyx (e.g., "PCMU").
+            outbound_encoding: Audio encoding for data received from Telnyx (e.g., "PCMU").
+            auto_hang_up: Whether to automatically terminate call on EndFrame.
+        """
+
+        telnyx_sample_rate: int = 8000
+        sample_rate: Optional[int] = None
         inbound_encoding: str = "PCMU"
         outbound_encoding: str = "PCMU"
         auto_hang_up: bool = True
@@ -56,8 +87,8 @@ class TelnyxFrameSerializer(FrameSerializer):
             stream_id: The Stream ID for Telnyx.
             outbound_encoding: The encoding type for outbound audio (e.g., "PCMU").
             inbound_encoding: The encoding type for inbound audio (e.g., "PCMU").
-            call_control_id: The Call Control ID for the Telnyx call.
-            api_key: Your Telnyx API key.
+            call_control_id: The Call Control ID for the Telnyx call (optional, but required for auto hang-up).
+            api_key: Your Telnyx API key (required for auto hang-up).
             params: Configuration parameters.
         """
         self._stream_id = stream_id
@@ -75,12 +106,36 @@ class TelnyxFrameSerializer(FrameSerializer):
 
     @property
     def type(self) -> FrameSerializerType:
+        """Gets the serializer type.
+
+        Returns:
+            The serializer type, either TEXT or BINARY.
+        """
         return FrameSerializerType.TEXT
 
     async def setup(self, frame: StartFrame):
+        """Sets up the serializer with pipeline configuration.
+
+        Args:
+            frame: The StartFrame containing pipeline configuration.
+        """
         self._sample_rate = self._params.sample_rate or frame.audio_in_sample_rate
 
     async def serialize(self, frame: Frame) -> str | bytes | None:
+        """Serializes a Pipecat frame to Telnyx WebSocket format.
+
+        Handles conversion of various frame types to Telnyx WebSocket messages.
+        For EndFrames and CancelFrames, initiates call termination if auto_hang_up is enabled.
+
+        Args:
+            frame: The Pipecat frame to serialize.
+
+        Returns:
+            Serialized data as string or bytes, or None if the frame isn't handled.
+
+        Raises:
+            ValueError: If an unsupported encoding is specified.
+        """
         if (
             self._params.auto_hang_up
             and not self._hangup_attempted
@@ -153,6 +208,20 @@ class TelnyxFrameSerializer(FrameSerializer):
             logger.exception(f"Failed to hang up Telnyx call: {e}")
 
     async def deserialize(self, data: str | bytes) -> Frame | None:
+        """Deserializes Telnyx WebSocket data to Pipecat frames.
+
+        Handles conversion of Telnyx media events to appropriate Pipecat frames,
+        including audio data and DTMF keypresses.
+
+        Args:
+            data: The raw WebSocket data from Telnyx.
+
+        Returns:
+            A Pipecat frame corresponding to the Telnyx event, or None if unhandled.
+
+        Raises:
+            ValueError: If an unsupported encoding is specified.
+        """
         message = json.loads(data)
 
         if message["event"] == "media":