dv-pipecat-ai 0.0.74.dev770__py3-none-any.whl → 0.0.82.dev776__py3-none-any.whl

pipecat/serializers/genesys.py

@@ -0,0 +1,95 @@
+import base64
+import json
+from typing import Optional
+
+from pydantic import BaseModel
+
+from pipecat.audio.utils import create_default_resampler, pcm_to_ulaw, ulaw_to_pcm
+from pipecat.frames.frames import (
+    AudioRawFrame,
+    Frame,
+    InputAudioRawFrame,
+    InputDTMFFrame,
+    KeypadEntry,
+    StartFrame,
+    StartInterruptionFrame,
+    TransportMessageFrame,
+    TransportMessageUrgentFrame,
+)
+from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType
+
+
+class GenesysFrameSerializer(FrameSerializer):
+    class InputParams(BaseModel):
+        genesys_sample_rate: int = 8000  # Default Genesys rate (8kHz)
+        sample_rate: Optional[int] = None  # Pipeline input rate
+
+    def __init__(self, session_id: str, params: InputParams = InputParams()):
+        self._session_id = session_id
+        self._params = params
+        self._genesys_sample_rate = self._params.genesys_sample_rate
+        self._sample_rate = 0  # Pipeline input rate
+        self._resampler = create_default_resampler()
+        self._seq = 1  # Sequence number for outgoing messages
+
+    @property
+    def type(self) -> FrameSerializerType:
+        return FrameSerializerType.TEXT
+
+    async def setup(self, frame: StartFrame):
+        self._sample_rate = self._params.sample_rate or frame.audio_in_sample_rate
+
+    async def serialize(self, frame: Frame) -> str | bytes | None:
+        if isinstance(frame, StartInterruptionFrame):
+            answer = {
+                "version": "2",
+                "type": "clearAudio",  # Or appropriate event for interruption
+                "seq": self._seq,
+                "id": self._session_id,
+            }
+            self._seq += 1
+            return json.dumps(answer)
+        elif isinstance(frame, AudioRawFrame):
+            data = frame.audio
+            # Convert PCM to 8kHz μ-law for Genesys
+            serialized_data = await pcm_to_ulaw(
+                data, frame.sample_rate, self._genesys_sample_rate, self._resampler
+            )
+            payload = base64.b64encode(serialized_data).decode("utf-8")
+            answer = {
+                "version": "2",
+                "type": "audio",
+                "seq": self._seq,
+                "id": self._session_id,
+                "media": {
+                    "payload": payload,
+                    "format": "PCMU",
+                    "rate": self._genesys_sample_rate,
+                },
+            }
+            self._seq += 1
+            return json.dumps(answer)
+        elif isinstance(frame, (TransportMessageFrame, TransportMessageUrgentFrame)):
+            return json.dumps(frame.message)
+
+    async def deserialize(self, data: str | bytes) -> Frame | None:
+        message = json.loads(data)
+        if message.get("type") == "audio":
+            payload_base64 = message["media"]["payload"]
+            payload = base64.b64decode(payload_base64)
+            # Convert Genesys 8kHz μ-law to PCM at pipeline input rate
+            deserialized_data = await ulaw_to_pcm(
+                payload, self._genesys_sample_rate, self._sample_rate, self._resampler
+            )
+            audio_frame = InputAudioRawFrame(
+                audio=deserialized_data, num_channels=1, sample_rate=self._sample_rate
+            )
+            return audio_frame
+        elif message.get("type") == "dtmf":
+            digit = message.get("dtmf", {}).get("digit")
+            try:
+                return InputDTMFFrame(KeypadEntry(digit))
+            except ValueError:
+                return None
+        else:
+            return None

pipecat/serializers/livekit.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""LiveKit frame serializer for Pipecat."""
+
 import ctypes
 import pickle
 
@@ -21,11 +23,33 @@ except ModuleNotFoundError as e:
 
 
 class LivekitFrameSerializer(FrameSerializer):
+    """Serializer for converting between Pipecat frames and LiveKit audio frames.
+
+    This serializer handles the conversion of Pipecat's OutputAudioRawFrame objects
+    to LiveKit AudioFrame objects for transmission, and the reverse conversion
+    for received audio data.
+    """
+
     @property
     def type(self) -> FrameSerializerType:
+        """Get the serializer type.
+
+        Returns:
+            The serializer type indicating binary serialization.
+        """
         return FrameSerializerType.BINARY
 
     async def serialize(self, frame: Frame) -> str | bytes | None:
+        """Serialize a Pipecat frame to LiveKit AudioFrame format.
+
+        Args:
+            frame: The Pipecat frame to serialize. Only OutputAudioRawFrame
+                  instances are supported.
+
+        Returns:
+            Pickled LiveKit AudioFrame bytes if frame is OutputAudioRawFrame,
+            None otherwise.
+        """
         if not isinstance(frame, OutputAudioRawFrame):
             return None
         audio_frame = AudioFrame(
@@ -37,6 +61,15 @@ class LivekitFrameSerializer(FrameSerializer):
         return pickle.dumps(audio_frame)
 
     async def deserialize(self, data: str | bytes) -> Frame | None:
+        """Deserialize LiveKit AudioFrame data to a Pipecat frame.
+
+        Args:
+            data: Pickled data containing a LiveKit AudioFrame.
+
+        Returns:
+            InputAudioRawFrame containing the deserialized audio data,
+            or None if deserialization fails.
+        """
         audio_frame: AudioFrame = pickle.loads(data)["frame"]
         return InputAudioRawFrame(
             audio=bytes(audio_frame.data),

pipecat/serializers/plivo.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Plivo WebSocket frame serializer for audio streaming."""
+
 import base64
 import json
 from typing import Optional
@@ -11,7 +13,7 @@ from typing import Optional
 from loguru import logger
 from pydantic import BaseModel
 
-from pipecat.audio.utils import create_default_resampler, pcm_to_ulaw, ulaw_to_pcm
+from pipecat.audio.utils import create_stream_resampler, pcm_to_ulaw, ulaw_to_pcm
 from pipecat.frames.frames import (
     AudioRawFrame,
     CancelFrame,
@@ -38,22 +40,12 @@ class PlivoFrameSerializer(FrameSerializer):
     When auto_hang_up is enabled (default), the serializer will automatically terminate
     the Plivo call when an EndFrame or CancelFrame is processed, but requires Plivo
     credentials to be provided.
-
-    Attributes:
-        _stream_id: The Plivo Stream ID.
-        _call_id: The associated Plivo Call ID.
-        _auth_id: Plivo auth ID for API access.
-        _auth_token: Plivo authentication token for API access.
-        _params: Configuration parameters.
-        _plivo_sample_rate: Sample rate used by Plivo (typically 8kHz).
-        _sample_rate: Input sample rate for the pipeline.
-        _resampler: Audio resampler for format conversion.
     """
 
     class InputParams(BaseModel):
         """Configuration parameters for PlivoFrameSerializer.
 
-        Attributes:
+        Parameters:
             plivo_sample_rate: Sample rate used by Plivo, defaults to 8000 Hz.
             sample_rate: Optional override for pipeline input sample rate.
             auto_hang_up: Whether to automatically terminate call on EndFrame.
@@ -89,7 +81,8 @@ class PlivoFrameSerializer(FrameSerializer):
         self._plivo_sample_rate = self._params.plivo_sample_rate
         self._sample_rate = 0  # Pipeline input rate
 
-        self._resampler = create_default_resampler()
+        self._input_resampler = create_stream_resampler()
+        self._output_resampler = create_stream_resampler()
         self._hangup_attempted = False
 
     @property
@@ -137,8 +130,12 @@ class PlivoFrameSerializer(FrameSerializer):
 
             # Output: Convert PCM at frame's rate to 8kHz μ-law for Plivo
             serialized_data = await pcm_to_ulaw(
-                data, frame.sample_rate, self._plivo_sample_rate, self._resampler
+                data, frame.sample_rate, self._plivo_sample_rate, self._output_resampler
             )
+            if serialized_data is None or len(serialized_data) == 0:
+                # Ignoring in case we don't have audio
+                return None
+
             payload = base64.b64encode(serialized_data).decode("utf-8")
             answer = {
                 "event": "playAudio",
@@ -232,8 +229,12 @@ class PlivoFrameSerializer(FrameSerializer):
 
             # Input: Convert Plivo's 8kHz μ-law to PCM at pipeline input rate
             deserialized_data = await ulaw_to_pcm(
-                payload, self._plivo_sample_rate, self._sample_rate, self._resampler
+                payload, self._plivo_sample_rate, self._sample_rate, self._input_resampler
             )
+            if deserialized_data is None or len(deserialized_data) == 0:
+                # Ignoring in case we don't have audio
+                return None
+
             audio_frame = InputAudioRawFrame(
                 audio=deserialized_data, num_channels=1, sample_rate=self._sample_rate
             )

pipecat/serializers/protobuf.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Protobuf frame serialization for Pipecat."""
+
 import dataclasses
 import json
 
@@ -22,13 +24,25 @@ from pipecat.frames.frames import (
 from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType
 
 
-# Data class for converting transport messages into Protobuf format.
 @dataclasses.dataclass
 class MessageFrame:
+    """Data class for converting transport messages into Protobuf format.
+
+    Parameters:
+        data: JSON-encoded message data for transport.
+    """
+
     data: str
 
 
 class ProtobufFrameSerializer(FrameSerializer):
+    """Serializer for converting Pipecat frames to/from Protocol Buffer format.
+
+    Provides efficient binary serialization for frame transport over network
+    connections. Supports text, audio, transcription, and message frames with
+    automatic conversion between transport message types.
+    """
+
     SERIALIZABLE_TYPES = {
         TextFrame: "text",
         OutputAudioRawFrame: "audio",
@@ -46,13 +60,27 @@ class ProtobufFrameSerializer(FrameSerializer):
     DESERIALIZABLE_FIELDS = {v: k for k, v in DESERIALIZABLE_TYPES.items()}
 
     def __init__(self):
+        """Initialize the Protobuf frame serializer."""
         pass
 
     @property
     def type(self) -> FrameSerializerType:
+        """Get the serializer type.
+
+        Returns:
+            FrameSerializerType.BINARY indicating binary serialization format.
+        """
         return FrameSerializerType.BINARY
 
     async def serialize(self, frame: Frame) -> str | bytes | None:
+        """Serialize a frame to Protocol Buffer binary format.
+
+        Args:
+            frame: The frame to serialize.
+
+        Returns:
+            Serialized frame as bytes, or None if frame type is not serializable.
+        """
         # Wrapping this messages as a JSONFrame to send
         if isinstance(frame, (TransportMessageFrame, TransportMessageUrgentFrame)):
             frame = MessageFrame(
@@ -75,6 +103,14 @@ class ProtobufFrameSerializer(FrameSerializer):
         return proto_frame.SerializeToString()
 
     async def deserialize(self, data: str | bytes) -> Frame | None:
+        """Deserialize Protocol Buffer binary data to a frame.
+
+        Args:
+            data: Binary protobuf data to deserialize.
+
+        Returns:
+            Deserialized frame instance, or None if deserialization fails.
+        """
         proto = frame_protos.Frame.FromString(data)
         which = proto.WhichOneof("frame")
         if which not in self.DESERIALIZABLE_FIELDS:

pipecat/serializers/telnyx.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Telnyx WebSocket frame serializer for Pipecat."""
+
 import base64
 import json
 from typing import Optional
@@ -14,7 +16,7 @@ from pydantic import BaseModel
 
 from pipecat.audio.utils import (
     alaw_to_pcm,
-    create_default_resampler,
+    create_stream_resampler,
     pcm_to_alaw,
     pcm_to_ulaw,
     ulaw_to_pcm,
@@ -43,22 +45,12 @@ class TelnyxFrameSerializer(FrameSerializer):
     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):
         """Configuration parameters for TelnyxFrameSerializer.
 
-        Attributes:
+        Parameters:
             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").
@@ -101,7 +93,8 @@ class TelnyxFrameSerializer(FrameSerializer):
         self._telnyx_sample_rate = self._params.telnyx_sample_rate
         self._sample_rate = 0  # Pipeline input rate
 
-        self._resampler = create_default_resampler()
+        self._input_resampler = create_stream_resampler()
+        self._output_resampler = create_stream_resampler()
         self._hangup_attempted = False
 
     @property
@@ -153,15 +146,19 @@ class TelnyxFrameSerializer(FrameSerializer):
             # Output: Convert PCM at frame's rate to 8kHz encoded for Telnyx
             if self._params.inbound_encoding == "PCMU":
                 serialized_data = await pcm_to_ulaw(
-                    data, frame.sample_rate, self._telnyx_sample_rate, self._resampler
+                    data, frame.sample_rate, self._telnyx_sample_rate, self._output_resampler
                 )
             elif self._params.inbound_encoding == "PCMA":
                 serialized_data = await pcm_to_alaw(
-                    data, frame.sample_rate, self._telnyx_sample_rate, self._resampler
+                    data, frame.sample_rate, self._telnyx_sample_rate, self._output_resampler
                 )
             else:
                 raise ValueError(f"Unsupported encoding: {self._params.inbound_encoding}")
 
+            if serialized_data is None or len(serialized_data) == 0:
+                # Ignoring in case we don't have audio
+                return None
+
             payload = base64.b64encode(serialized_data).decode("utf-8")
             answer = {
                 "event": "media",
@@ -257,18 +254,22 @@ class TelnyxFrameSerializer(FrameSerializer):
                     payload,
                     self._telnyx_sample_rate,
                     self._sample_rate,
-                    self._resampler,
+                    self._input_resampler,
                 )
             elif self._params.outbound_encoding == "PCMA":
                 deserialized_data = await alaw_to_pcm(
                     payload,
                     self._telnyx_sample_rate,
                     self._sample_rate,
-                    self._resampler,
+                    self._input_resampler,
                 )
             else:
                 raise ValueError(f"Unsupported encoding: {self._params.outbound_encoding}")
 
+            if deserialized_data is None or len(deserialized_data) == 0:
+                # Ignoring in case we don't have audio
+                return None
+
             audio_frame = InputAudioRawFrame(
                 audio=deserialized_data, num_channels=1, sample_rate=self._sample_rate
             )

pipecat/serializers/twilio.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Twilio Media Streams WebSocket protocol serializer for Pipecat."""
+
 import base64
 import json
 from typing import Optional
@@ -11,7 +13,7 @@ from typing import Optional
 from loguru import logger
 from pydantic import BaseModel
 
-from pipecat.audio.utils import create_default_resampler, pcm_to_ulaw, ulaw_to_pcm
+from pipecat.audio.utils import create_stream_resampler, pcm_to_ulaw, ulaw_to_pcm
 from pipecat.frames.frames import (
     AudioRawFrame,
     CancelFrame,
@@ -38,22 +40,12 @@ class TwilioFrameSerializer(FrameSerializer):
     When auto_hang_up is enabled (default), the serializer will automatically terminate
     the Twilio call when an EndFrame or CancelFrame is processed, but requires Twilio
     credentials to be provided.
-
-    Attributes:
-        _stream_sid: The Twilio Media Stream SID.
-        _call_sid: The associated Twilio Call SID.
-        _account_sid: Twilio account SID for API access.
-        _auth_token: Twilio authentication token for API access.
-        _params: Configuration parameters.
-        _twilio_sample_rate: Sample rate used by Twilio (typically 8kHz).
-        _sample_rate: Input sample rate for the pipeline.
-        _resampler: Audio resampler for format conversion.
     """
 
     class InputParams(BaseModel):
         """Configuration parameters for TwilioFrameSerializer.
 
-        Attributes:
+        Parameters:
             twilio_sample_rate: Sample rate used by Twilio, defaults to 8000 Hz.
             sample_rate: Optional override for pipeline input sample rate.
             auto_hang_up: Whether to automatically terminate call on EndFrame.
@@ -89,7 +81,8 @@ class TwilioFrameSerializer(FrameSerializer):
         self._twilio_sample_rate = self._params.twilio_sample_rate
         self._sample_rate = 0  # Pipeline input rate
 
-        self._resampler = create_default_resampler()
+        self._input_resampler = create_stream_resampler()
+        self._output_resampler = create_stream_resampler()
         self._hangup_attempted = False
 
     @property
@@ -137,11 +130,12 @@ class TwilioFrameSerializer(FrameSerializer):
 
             # Output: Convert PCM at frame's rate to 8kHz μ-law for Twilio
             serialized_data = await pcm_to_ulaw(
-                data, frame.sample_rate, self._twilio_sample_rate, self._resampler
+                data, frame.sample_rate, self._twilio_sample_rate, self._output_resampler
             )
             if serialized_data is None or len(serialized_data) == 0:
                 # Ignoring in case we don't have audio
                 return None
+            
             payload = base64.b64encode(serialized_data).decode("utf-8")
             answer = {
                 "event": "media",
@@ -195,8 +189,26 @@ class TwilioFrameSerializer(FrameSerializer):
                 async with session.post(endpoint, auth=auth, data=params) as response:
                     if response.status == 200:
                         logger.info(f"Successfully terminated Twilio call {call_sid}")
+                    elif response.status == 404:
+                        # Handle the case where the call has already ended
+                        # Error code 20404: "The requested resource was not found"
+                        # Source: https://www.twilio.com/docs/errors/20404
+                        try:
+                            error_data = await response.json()
+                            if error_data.get("code") == 20404:
+                                logger.debug(f"Twilio call {call_sid} was already terminated")
+                                return
+                        except:
+                            pass  # Fall through to log the raw error
+
+                        # Log other 404 errors
+                        error_text = await response.text()
+                        logger.error(
+                            f"Failed to terminate Twilio call {call_sid}: "
+                            f"Status {response.status}, Response: {error_text}"
+                        )
                     else:
-                        # Get the error details for better debugging
+                        # Log other errors
                         error_text = await response.text()
                         logger.error(
                             f"Failed to terminate Twilio call {call_sid}: "
@@ -225,8 +237,12 @@ class TwilioFrameSerializer(FrameSerializer):
 
             # Input: Convert Twilio's 8kHz μ-law to PCM at pipeline input rate
             deserialized_data = await ulaw_to_pcm(
-                payload, self._twilio_sample_rate, self._sample_rate, self._resampler
+                payload, self._twilio_sample_rate, self._sample_rate, self._input_resampler
             )
+            if deserialized_data is None or len(deserialized_data) == 0:
+                # Ignoring in case we don't have audio
+                return None
+
             audio_frame = InputAudioRawFrame(
                 audio=deserialized_data, num_channels=1, sample_rate=self._sample_rate
             )

pipecat/services/ai_service.py

@@ -32,12 +32,14 @@ class AIService(FrameProcessor):
     settings handling, session properties, and frame processing lifecycle.
     Subclasses should implement specific AI functionality while leveraging
     this base infrastructure.
-
-    Args:
-            **kwargs: Additional arguments passed to the parent FrameProcessor.
     """
 
     def __init__(self, **kwargs):
+        """Initialize the AI service.
+
+        Args:
+            **kwargs: Additional arguments passed to the parent FrameProcessor.
+        """
         super().__init__(**kwargs)
         self._model_name: str = ""
         self._settings: Dict[str, Any] = {}