dv-pipecat-ai 0.0.82.dev857__py3-none-any.whl → 0.0.85.dev837__py3-none-any.whl

pipecat/runner/utils.py

@@ -99,16 +99,47 @@ async def parse_telephony_websocket(websocket: WebSocket):
         tuple: (transport_type: str, call_data: dict)
 
         call_data contains provider-specific fields:
-        - Twilio: {"stream_id": str, "call_id": str}
-        - Telnyx: {"stream_id": str, "call_control_id": str, "outbound_encoding": str}
-        - Plivo: {"stream_id": str, "call_id": str}
-        - Exotel: {"stream_id": str, "call_id": str, "account_sid": str}
+
+        - Twilio::
+
+            {
+                "stream_id": str,
+                "call_id": str,
+                "body": dict
+            }
+
+        - Telnyx::
+
+            {
+                "stream_id": str,
+                "call_control_id": str,
+                "outbound_encoding": str,
+                "from": str,
+                "to": str,
+            }
+
+        - Plivo::
+
+            {
+                "stream_id": str,
+                "call_id": str,
+            }
+
+        - Exotel::
+
+            {
+                "stream_id": str,
+                "call_id": str,
+                "account_sid": str,
+                "from": str,
+                "to": str,
+            }
 
     Example usage::
 
         transport_type, call_data = await parse_telephony_websocket(websocket)
-        if transport_type == "telnyx":
-            outbound_encoding = call_data["outbound_encoding"]
+        if transport_type == "twilio":
+            user_id = call_data["body"]["user_id"]
     """
     # Read first two messages
     start_data = websocket.iter_text()
@@ -151,9 +182,12 @@ async def parse_telephony_websocket(websocket: WebSocket):
         # Extract provider-specific data
         if transport_type == "twilio":
             start_data = call_data_raw.get("start", {})
+            body_data = start_data.get("customParameters", {})
             call_data = {
                 "stream_id": start_data.get("streamSid"),
                 "call_id": start_data.get("callSid"),
+                # All custom parameters
+                "body": body_data,
             }
 
         elif transport_type == "telnyx":
@@ -163,6 +197,8 @@ async def parse_telephony_websocket(websocket: WebSocket):
                 "outbound_encoding": call_data_raw.get("start", {})
                 .get("media_format", {})
                 .get("encoding"),
+                "from": call_data_raw.get("start", {}).get("from", ""),
+                "to": call_data_raw.get("start", {}).get("to", ""),
             }
 
         elif transport_type == "plivo":
@@ -178,6 +214,8 @@ async def parse_telephony_websocket(websocket: WebSocket):
                 "stream_id": start_data.get("stream_sid"),
                 "call_id": start_data.get("call_sid"),
                 "account_sid": start_data.get("account_sid"),
+                "from": start_data.get("from", ""),
+                "to": start_data.get("to", ""),
             }
 
         else:
@@ -275,6 +313,7 @@ def _smallwebrtc_sdp_cleanup_ice_candidates(text: str, pattern: str) -> str:
     Returns:
         Cleaned SDP text with filtered ICE candidates.
     """
+    logger.debug("Removing unsupported ICE candidates from SDP")
     result = []
     lines = text.splitlines()
     for line in lines:
@@ -283,7 +322,7 @@ def _smallwebrtc_sdp_cleanup_ice_candidates(text: str, pattern: str) -> str:
                 result.append(line)
         else:
             result.append(line)
-    return "\r\n".join(result)
+    return "\r\n".join(result) + "\r\n"
 
 
 def _smallwebrtc_sdp_cleanup_fingerprints(text: str) -> str:
@@ -295,15 +334,16 @@ def _smallwebrtc_sdp_cleanup_fingerprints(text: str) -> str:
     Returns:
         SDP text with sha-384 and sha-512 fingerprints removed.
     """
+    logger.debug("Removing unsupported fingerprints from SDP")
     result = []
     lines = text.splitlines()
     for line in lines:
         if not re.search("sha-384", line) and not re.search("sha-512", line):
             result.append(line)
-    return "\r\n".join(result)
+    return "\r\n".join(result) + "\r\n"
 
 
-def smallwebrtc_sdp_munging(sdp: str, host: str) -> str:
+def smallwebrtc_sdp_munging(sdp: str, host: Optional[str]) -> str:
     """Apply SDP modifications for SmallWebRTC compatibility.
 
     Args:
@@ -314,7 +354,8 @@ def smallwebrtc_sdp_munging(sdp: str, host: str) -> str:
         Modified SDP string with fingerprint and ICE candidate cleanup.
     """
     sdp = _smallwebrtc_sdp_cleanup_fingerprints(sdp)
-    sdp = _smallwebrtc_sdp_cleanup_ice_candidates(sdp, host)
+    if host:
+        sdp = _smallwebrtc_sdp_cleanup_ice_candidates(sdp, host)
     return sdp
 
 

pipecat/serializers/__init__.py

@@ -1,18 +1,22 @@
 from .base_serializer import FrameSerializer, FrameSerializerType
 from .convox import ConVoxFrameSerializer
+from .custom import CustomFrameSerializer
 from .exotel import ExotelFrameSerializer
 from .plivo import PlivoFrameSerializer
 from .telnyx import TelnyxFrameSerializer
 from .twilio import TwilioFrameSerializer
+from .vi import VIFrameSerializer
 
 __all__ = [
     "FrameSerializer",
-    "FrameSerializerType", 
+    "FrameSerializerType",
     "ConVoxFrameSerializer",
+    "CustomFrameSerializer",
     "ExotelFrameSerializer",
     "PlivoFrameSerializer",
     "TelnyxFrameSerializer",
     "TwilioFrameSerializer",
+    "VIFrameSerializer",
 ]
 
 # Optional imports

pipecat/serializers/asterisk.py

@@ -1,4 +1,6 @@
 # asterisk_ws_serializer.py
+"""Frame serializer for Asterisk WebSocket communication."""
+
 import base64
 import json
 from typing import Literal, Optional
@@ -12,8 +14,8 @@ from pipecat.frames.frames import (
     EndFrame,
     Frame,
     InputAudioRawFrame,
+    InterruptionFrame,
     StartFrame,
-    StartInterruptionFrame,
     TransportMessageFrame,
     TransportMessageUrgentFrame,
 )
@@ -21,6 +23,8 @@ from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializer
 
 
 class AsteriskFrameSerializer(FrameSerializer):
+    """Serializes Pipecat frames to/from Asterisk WebSocket JSON messages."""
+
     class InputParams(BaseModel):
         """Configuration parameters for AsteriskFrameSerializer.
 
@@ -39,6 +43,12 @@ class AsteriskFrameSerializer(FrameSerializer):
         auto_hang_up: bool = False  # no-op here; adapter handles hangup
 
     def __init__(self, stream_id: str, params: Optional[InputParams] = None):
+        """Initialize the Asterisk frame serializer.
+
+        Args:
+            stream_id: Unique identifier for the media stream.
+            params: Configuration parameters for the serializer.
+        """
         self._stream_id = stream_id
         self._params = params or AsteriskFrameSerializer.InputParams()
         self._tel_rate = self._params.telephony_sample_rate
@@ -49,13 +59,16 @@ class AsteriskFrameSerializer(FrameSerializer):
 
     @property
     def type(self) -> FrameSerializerType:
+        """Return the serializer type (TEXT for JSON messages)."""
         return FrameSerializerType.TEXT  # we send/recv JSON strings
 
     async def setup(self, frame: StartFrame):
+        """Setup the serializer with audio parameters from the StartFrame."""
         self._sample_rate = self._params.sample_rate or frame.audio_in_sample_rate
 
     # Pipecat -> Adapter (play to caller)
     async def serialize(self, frame: Frame) -> str | bytes | None:
+        """Serialize Pipecat frames to Asterisk WebSocket JSON messages."""
         # On pipeline end, ask bridge to hang up
         if (
             self._params.auto_hang_up
@@ -64,7 +77,7 @@ class AsteriskFrameSerializer(FrameSerializer):
         ):
             self._hangup_sent = True
             return json.dumps({"event": "hangup"})
-        if isinstance(frame, StartInterruptionFrame):
+        if isinstance(frame, InterruptionFrame):
             return json.dumps({"event": "clear", "streamId": self._stream_id})
         if isinstance(frame, AudioRawFrame):
             pcm = frame.audio
@@ -114,6 +127,7 @@ class AsteriskFrameSerializer(FrameSerializer):
 
     # Adapter -> Pipecat (audio from caller)
     async def deserialize(self, data: str | bytes) -> Frame | None:
+        """Deserialize Asterisk WebSocket JSON messages to Pipecat frames."""
         try:
             msg = json.loads(data)
         except Exception:

pipecat/serializers/convox.py

@@ -4,9 +4,11 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""ConVox WebSocket frame serializer for audio streaming and call management."""
+
 import base64
-import datetime
 import json
+from datetime import datetime, timezone
 from typing import Optional
 
 from loguru import logger
@@ -20,9 +22,9 @@ from pipecat.frames.frames import (
     Frame,
     InputAudioRawFrame,
     InputDTMFFrame,
+    InterruptionFrame,
     KeypadEntry,
     StartFrame,
-    StartInterruptionFrame,
     TransportMessageFrame,
     TransportMessageUrgentFrame,
 )
@@ -99,6 +101,7 @@ class ConVoxFrameSerializer(FrameSerializer):
         """Serializes a Pipecat frame to ConVox WebSocket format.
 
         Handles conversion of various frame types to ConVox WebSocket messages.
+        For EndFrames, initiates call termination if auto_hang_up is enabled.
 
         Args:
             frame: The Pipecat frame to serialize.
@@ -106,7 +109,15 @@ class ConVoxFrameSerializer(FrameSerializer):
         Returns:
             Serialized data as JSON string, or None if the frame isn't handled.
         """
-        if isinstance(frame, StartInterruptionFrame):
+        if (
+            self._params.auto_hang_up
+            and not self._call_ended
+            and isinstance(frame, (EndFrame, CancelFrame))
+        ):
+            self._call_ended = True
+            # Return the callEnd event to be sent via the WebSocket
+            return await self._send_call_end_event()
+        elif isinstance(frame, InterruptionFrame):
             # Clear/interrupt command for ConVox
             message = {
                 "event": "clear",
@@ -138,7 +149,7 @@ class ConVoxFrameSerializer(FrameSerializer):
             payload = base64.b64encode(serialized_data).decode("ascii")
 
             # ConVox expects play_audio event format according to the documentation
-            timestamp = datetime.datetime.now().isoformat()
+            timestamp = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
 
             message = {
                 "event": "play_audio",
@@ -164,6 +175,32 @@ class ConVoxFrameSerializer(FrameSerializer):
 
         return None
 
+    async def _send_call_end_event(self):
+        """Send a callEnd event to ConVox to terminate the call.
+
+        This method is called when auto_hang_up is enabled and an EndFrame or
+        CancelFrame is received, similar to the logic in end_call_handler.py.
+        """
+        try:
+            call_end_event = {
+                "event": "callEnd",
+                "details": {
+                    "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+                    "direction": "WSS",
+                    "message": "Event trigger request",
+                },
+            }
+
+            logger.info(
+                f"ConVox auto_hang_up: Sending callEnd event for stream_id: {self._stream_id}, call_id: {self._call_id}"
+            )
+            # Note: The actual sending will be handled by the transport layer
+            # when this method returns the JSON string
+            return json.dumps(call_end_event)
+        except Exception as e:
+            logger.error(f"ConVox auto_hang_up: Failed to create callEnd event: {e}")
+            return None
+
     async def deserialize(self, data: str | bytes) -> Frame | None:
         """Deserializes ConVox WebSocket data to Pipecat frames.
 

pipecat/serializers/custom.py

@@ -0,0 +1,257 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Custom/External telephony serializer for Pipecat with Ringg AI WebSocket API. Customers will directly connect to Ringg AI WebSocket API."""
+
+import base64
+import json
+import uuid
+from typing import Optional
+
+from loguru import logger
+from pydantic import BaseModel
+
+from pipecat.audio.utils import (
+    alaw_to_pcm,
+    create_stream_resampler,
+    pcm_to_alaw,
+    pcm_to_ulaw,
+    ulaw_to_pcm,
+)
+from pipecat.frames.frames import (
+    AudioRawFrame,
+    CallTransferFrame,
+    CancelFrame,
+    EndFrame,
+    Frame,
+    InputAudioRawFrame,
+    InterruptionFrame,
+    StartFrame,
+    TransportMessageFrame,
+    TransportMessageUrgentFrame,
+)
+from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType
+
+
+class CustomFrameSerializer(FrameSerializer):
+    """Serializer for Custom/External telephony WebSocket protocol (Ringg AI API).
+
+    This serializer handles converting between Pipecat frames and the Ringg AI
+    WebSocket protocol for external/custom telephony providers. It supports
+    PCMU (μ-law), PCMA (A-law), and PCM codecs with automatic conversion.
+
+    Supported events:
+    - start: Initialize call with agent configuration
+    - media: Bidirectional audio streaming
+    - clear: Clear audio buffers (interruption)
+    - call_transfer: Transfer call to another number
+    - hang_up: End call notification
+
+    Audio format:
+    - Sample Rate: Configurable (default 8kHz)
+    - Channels: Mono (1 channel)
+    - Bit Depth: 16-bit
+    - Encoding: Little-endian
+    - Payload Encoding: Base64
+    - Supported Codecs: PCMU (μ-law), PCMA (A-law), PCM (raw)
+    """
+
+    class InputParams(BaseModel):
+        """Configuration parameters for CustomFrameSerializer.
+
+        Parameters:
+            custom_sample_rate: Sample rate used by external client, defaults to 8000 Hz.
+            sample_rate: Optional override for pipeline input sample rate.
+            codec: Audio codec - "pcmu" (μ-law), "pcma" (A-law), or "pcm" (raw PCM).
+        """
+
+        custom_sample_rate: int = 8000
+        sample_rate: Optional[int] = None
+        codec: str = "pcmu"  # "pcmu" or "pcm"
+
+    def __init__(
+        self, stream_sid: str, call_sid: Optional[str] = None, params: Optional[InputParams] = None
+    ):
+        """Initialize the CustomFrameSerializer.
+
+        Args:
+            stream_sid: The stream identifier from external client.
+            call_sid: The call identifier from external client.
+            params: Configuration parameters.
+        """
+        self._stream_sid = stream_sid
+        self._call_sid = call_sid
+        self._params = params or CustomFrameSerializer.InputParams()
+
+        self._custom_sample_rate = self._params.custom_sample_rate
+        self._sample_rate = 0  # Pipeline input rate
+        self._codec = self._params.codec.lower()
+
+        self._input_resampler = create_stream_resampler()
+        self._output_resampler = create_stream_resampler()
+
+    @property
+    def type(self) -> FrameSerializerType:
+        """Gets the serializer type.
+
+        Returns:
+            The serializer type, TEXT for JSON-based protocol.
+        """
+        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 Custom telephony WebSocket format.
+
+        Handles conversion of various frame types to Ringg AI WebSocket messages.
+
+        Args:
+            frame: The Pipecat frame to serialize.
+
+        Returns:
+            Serialized data as JSON string, or None if the frame isn't handled.
+        """
+        if isinstance(frame, InterruptionFrame):
+            # Send clear event to instruct client to discard buffered audio
+            answer = {"event": "clear", "stream_sid": self._stream_sid}
+            return json.dumps(answer)
+
+        elif isinstance(frame, CallTransferFrame):
+            # Send call_transfer event to transfer the call to another number
+            answer = {
+                "event": "call_transfer",
+                "call_sid": self._call_sid or self._stream_sid,
+                "to": frame.target,
+            }
+            return json.dumps(answer)
+
+        elif isinstance(frame, (EndFrame, CancelFrame)):
+            # Send hang_up event to end the call
+            answer = {"event": "hang_up", "stream_sid": self._stream_sid}
+            return json.dumps(answer)
+
+        elif isinstance(frame, AudioRawFrame):
+            data = frame.audio
+
+            # Convert audio based on codec
+            if self._codec == "pcmu":
+                # Convert PCM to μ-law for PCMU codec
+                serialized_data = await pcm_to_ulaw(
+                    data, frame.sample_rate, self._custom_sample_rate, self._output_resampler
+                )
+            elif self._codec == "pcma":
+                # Convert PCM to A-law for PCMA codec
+                serialized_data = await pcm_to_alaw(
+                    data, frame.sample_rate, self._custom_sample_rate, self._output_resampler
+                )
+            else:  # pcm
+                # Resample PCM to target sample rate
+                serialized_data = await self._output_resampler.resample(
+                    data, frame.sample_rate, self._custom_sample_rate
+                )
+
+            if serialized_data is None or len(serialized_data) == 0:
+                # Skip if no audio data
+                return None
+
+            payload = base64.b64encode(serialized_data).decode("ascii")
+            answer = {
+                "event": "media",
+                "stream_sid": self._stream_sid,
+                "media": {"payload": payload},
+            }
+
+            return json.dumps(answer)
+
+        elif isinstance(frame, (TransportMessageFrame, TransportMessageUrgentFrame)):
+            return json.dumps(frame.message)
+
+        return None
+
+    async def deserialize(self, data: str | bytes) -> Frame | None:
+        """Deserializes Custom telephony WebSocket data to Pipecat frames.
+
+        Handles conversion of Ringg AI WebSocket events to appropriate Pipecat frames.
+
+        Args:
+            data: The raw WebSocket data from external client.
+
+        Returns:
+            A Pipecat frame corresponding to the event, or None if unhandled.
+        """
+        try:
+            message = json.loads(data)
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse JSON message: {e}")
+            return None
+
+        event = message.get("event")
+
+        if event == "media":
+            media = message.get("media", {})
+            payload_base64 = media.get("payload")
+            uuid = message.get("uuid")
+
+            if not payload_base64:
+                logger.warning("Media event missing payload")
+                return None
+
+            try:
+                payload = base64.b64decode(payload_base64)
+            except Exception as e:
+                logger.error(f"Failed to decode base64 payload: {e}")
+                return None
+
+            # Convert audio based on codec
+            if self._codec == "pcmu":
+                # Convert μ-law to PCM
+                deserialized_data = await ulaw_to_pcm(
+                    payload, self._custom_sample_rate, self._sample_rate, self._input_resampler
+                )
+            elif self._codec == "pcma":
+                # Convert A-law to PCM
+                deserialized_data = await alaw_to_pcm(
+                    payload, self._custom_sample_rate, self._sample_rate, self._input_resampler
+                )
+            else:  # pcm
+                # Resample PCM to pipeline sample rate
+                deserialized_data = await self._input_resampler.resample(
+                    payload,
+                    self._custom_sample_rate,
+                    self._sample_rate,
+                )
+
+            if deserialized_data is None or len(deserialized_data) == 0:
+                # Skip if no audio data
+                return None
+
+            audio_frame = InputAudioRawFrame(
+                audio=deserialized_data,
+                num_channels=1,  # Mono audio
+                sample_rate=self._sample_rate,
+            )
+            return audio_frame
+
+        elif event == "start":
+            # Log start event but don't generate a frame (handled by WebSocketService)
+            logger.debug(f"Received start event for stream {self._stream_sid}")
+            return None
+
+        elif event == "clear":
+            # External client requesting to clear our audio buffers
+            logger.debug(f"Received clear event for stream {self._stream_sid}")
+            return None
+
+        else:
+            logger.debug(f"Unhandled event type: {event} for stream {self._stream_sid}")
+            return None

pipecat/serializers/exotel.py

@@ -20,10 +20,10 @@ from pipecat.frames.frames import (
     Frame,
     InputAudioRawFrame,
     InputDTMFFrame,
+    InterruptionFrame,
+    OutputTransportMessageFrame,
+    OutputTransportMessageUrgentFrame,
     StartFrame,
-    StartInterruptionFrame,
-    TransportMessageFrame,
-    TransportMessageUrgentFrame,
 )
 from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType
 
@@ -98,7 +98,7 @@ class ExotelFrameSerializer(FrameSerializer):
         Returns:
             Serialized data as string or bytes, or None if the frame isn't handled.
         """
-        if isinstance(frame, StartInterruptionFrame):
+        if isinstance(frame, InterruptionFrame):
             answer = {"event": "clear", "streamSid": self._stream_sid}
             return json.dumps(answer)
         elif isinstance(frame, AudioRawFrame):
@@ -121,7 +121,7 @@ class ExotelFrameSerializer(FrameSerializer):
             }
 
             return json.dumps(answer)
-        elif isinstance(frame, (TransportMessageFrame, TransportMessageUrgentFrame)):
+        elif isinstance(frame, (OutputTransportMessageFrame, OutputTransportMessageUrgentFrame)):
             return json.dumps(frame.message)
 
         return None

pipecat/serializers/livekit.py

@@ -25,11 +25,31 @@ except ModuleNotFoundError as e:
 class LivekitFrameSerializer(FrameSerializer):
     """Serializer for converting between Pipecat frames and LiveKit audio frames.
 
+    .. deprecated:: 0.0.90
+
+        This class is deprecated and will be removed in a future version.
+        Please use LiveKitTransport instead, which handles audio streaming
+        and frame conversion natively.
+
     This serializer handles the conversion of Pipecat's OutputAudioRawFrame objects
     to LiveKit AudioFrame objects for transmission, and the reverse conversion
     for received audio data.
     """
 
+    def __init__(self):
+        """Initialize the LiveKit frame serializer."""
+        super().__init__()
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "LivekitFrameSerializer is deprecated and will be removed in a future version. "
+                "Please use LiveKitTransport instead, which handles audio streaming natively.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
     @property
     def type(self) -> FrameSerializerType:
         """Get the serializer type.

pipecat/serializers/plivo.py

@@ -22,10 +22,10 @@ from pipecat.frames.frames import (
     Frame,
     InputAudioRawFrame,
     InputDTMFFrame,
+    InterruptionFrame,
+    OutputTransportMessageFrame,
+    OutputTransportMessageUrgentFrame,
     StartFrame,
-    StartInterruptionFrame,
-    TransportMessageFrame,
-    TransportMessageUrgentFrame,
 )
 from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType
 
@@ -122,7 +122,7 @@ class PlivoFrameSerializer(FrameSerializer):
             self._hangup_attempted = True
             await self._hang_up_call()
             return None
-        elif isinstance(frame, StartInterruptionFrame):
+        elif isinstance(frame, InterruptionFrame):
             answer = {"event": "clearAudio", "streamId": self._stream_id}
             return json.dumps(answer)
         elif isinstance(frame, AudioRawFrame):
@@ -148,7 +148,7 @@ class PlivoFrameSerializer(FrameSerializer):
             }
 
             return json.dumps(answer)
-        elif isinstance(frame, (TransportMessageFrame, TransportMessageUrgentFrame)):
+        elif isinstance(frame, (OutputTransportMessageFrame, OutputTransportMessageUrgentFrame)):
             return json.dumps(frame.message)
 
         # Return None for unhandled frames