pipecat-asterisk 0.1.0__py3-none-any.whl

pipecat_asterisk/__init__.py

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2026, Nikolai Shakin
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+from .serializer.serializer import AsteriskFrameSerializer
+from .transport.transport import AsteriskWebsocketTransport
+
+__all__ = ["AsteriskFrameSerializer", "AsteriskWebsocketTransport"]

pipecat_asterisk/serializer/__init__.py

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2026, Nikolai Shakin
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+from .protocol import AsteriskWSProtocol
+from .serializer import AsteriskFrameSerializer
+
+__all__ = ["AsteriskWSProtocol", "AsteriskFrameSerializer"]

pipecat_asterisk/serializer/protocol.py

@@ -0,0 +1,80 @@
+#
+# Copyright (c) 2026, Nikolai Shakin
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+from loguru import logger
+import json
+
+
+class AsteriskWSProtocol:
+    """Asterisk WebSocket protocol handler.
+
+    The protocol learns Asterisk web_socket channel subprotocol (json or plain-text) based on the first event "MEDIA_START", if it is not set explicitly.
+    It parses events accordingly to the identified subprotocol and returns dictionary objects.
+    It builds commands to Asterisk in the identified subprotocol.
+    """
+
+    def __init__(self, subprotocol: str | None = None):
+        self._sub_protocol = subprotocol
+        if self._sub_protocol is not None and self._sub_protocol not in [
+            "json",
+            "plain-text",
+        ]:
+            raise ValueError(
+                f"Invalid subprotocol for AsteriskWSProtocol: {self._sub_protocol}, it should be either 'json' or 'plain-text' or None for autodetect."
+            )
+        if self._sub_protocol is None:
+            logger.debug(
+                "Asterisk subprotocol ['json' or 'plain-text'] is not defined, we will try to learn it automatically based on 'MEDIA_START' event."
+            )
+
+    def parse(self, event: str) -> dict | None:
+        """Parses the event from Asterisk WebSocket channel and return a dictionary object."""
+        if self._sub_protocol is None:
+            # If subprotocol is not set, we attempt to identify the format based on the first event we receive, which should be "MEDIA_START"
+            if "MEDIA_START" in event:
+                try:
+                    json.loads(event)
+                    self._sub_protocol = "json"
+                    logger.debug(
+                        "Identified Asterisk subprotocol as JSON based on MEDIA_START event format."
+                    )
+                except json.JSONDecodeError:
+                    self._sub_protocol = "plain-text"
+                    logger.debug(
+                        "Identified Asterisk subprotocol as plain-text based on MEDIA_START event format. Notice: In plain-text format you will not be able to read Asterisk channel variables."
+                    )
+            else:
+                logger.warning(
+                    f'We tried to auto-detect the Asterisk subprotocol but, received the event before "MEDIA_START". Event: {event}'
+                )
+                return None
+
+        if self._sub_protocol == "json":
+            try:
+                return json.loads(event)
+            except json.JSONDecodeError as e:
+                logger.error(
+                    f"Failed to parse Asterisk WebSocket event as JSON: {event}"
+                )
+                raise e
+        else:
+            event_entries = event.split(" ")
+            if event_entries[0] == "":
+                logger.warning(f"Received empty event from Asterisk WebSocket channel.")
+                return None
+            event_dict = {"event": event_entries.pop(0)}
+            for entry in event_entries:
+                if ":" in entry:
+                    key, value = entry.split(":", 1)
+                    event_dict[key] = value
+            return event_dict
+
+    def build(self, command: str) -> str:
+        """Returns a properly formatted command for Asterisk WebSocket channel based on the identified subprotocol."""
+        if self._sub_protocol == "plain-text":
+            return command
+        else:
+            return f'{{"command": "{command}"}}'

pipecat_asterisk/serializer/serializer.py

@@ -0,0 +1,468 @@
+#
+# Copyright (c) 2026, Nikolai Shakin
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+import inspect
+from typing import Awaitable, Callable, Optional, cast
+from loguru import logger
+from pipecat.audio.dtmf.types import KeypadEntry
+from pipecat.audio.utils import create_stream_resampler
+from pipecat.frames.frames import (
+    CancelFrame,
+    EndFrame,
+    Frame,
+    InputAudioRawFrame,
+    InputDTMFFrame,
+    InputTransportMessageFrame,
+    InterruptionFrame,
+    OutputAudioRawFrame,
+    StartFrame,
+)
+from pipecat.serializers.base_serializer import FrameSerializer
+
+from .protocol import AsteriskWSProtocol
+
+
+class AsteriskCommandFrame(Frame):
+    """A frame representing a command to be sent to Asterisk WebSocket channel."""
+
+    def __init__(self, cmd: str):
+        self.cmd = cmd
+
+
+class AsteriskFrameSerializer(FrameSerializer):
+    """Asterisk WebSocket Serializer: Serializer for Asterisk WebSocket channel.
+
+    This serializer handles converting between Pipecat frames and Asterisk's WebSocket
+    channel events/commands and binary audio data and vice versa.
+        Asterisk to Pipecat:
+            - when DTMF detected on Asterisk websocket channel we send InputDTMFFrame to Pipecat.
+            - when MEDIA_START event is received we send InputTransportMessageFrame to Pipecat with the event message as the payload,
+                so the pipeline can use the information provided in that event (e.g., channel variables) and also know when the media starts flowing.
+            - when MEDIA_XOFF event is received we log a warning that Asterisk is asking us to pause sending media, normally it should not happen if the transport implements flow control correctly.
+            - when MEDIA_XON event is received we log that Asterisk is ready to receive media again after a MEDIA_XOFF event, again it's for information, it's not used.
+            - when QUEUE_DRAINED event is received we send InputTransportMessageFrame to Pipecat with the event message as the payload,
+                so the pipeline can know when Asterisk finished processing all the queued media, which might be useful to know when Asterisk finished playing all the TTS audio.
+            - when binary audio data is received on Asterisk websocket channel we convert it to InputAudioRawFrame and send to Pipecat, after resampling if needed.
+        Pipecat to Asterisk:
+            - when an EndFrame or CancelFrame is processed we send HANGUP to Asterisk websocket channel.
+            - when an InterruptionFrame is processed we send FLUSH_MEDIA to Asterisk websocket channel.
+            - when an OutputAudioRawFrame is processed we send the raw audio bytes to Asterisk websocket channel, after resampling if needed.
+
+        Some of the event handlers are just placeholders for now, they just log the received events, but they can be extended if needed.
+        In case you need to add more event handlers you can add more methods with the naming convention "_ev_{event_name.lower()}"
+        and they will be called automatically when the corresponding event is received from Asterisk.
+        The same applies for frame handlers, you can add more methods with the naming convention "_frame_{frame_type.lower()}"
+        and they will be called automatically when the corresponding frame type is processed in serialize method.
+    """
+
+    # Asterisk slin sample rates supported by default, you can check it on your Asterisk with CLI>'core show codecs audio'
+    SUPPORTED_SAMPLE_RATES = [12, 16, 24, 32, 44, 48, 96, 192, 128]  # kHz
+
+    def __init__(self, sample_rate: int = 0):
+        """Initialize the Asterisk WebSocket Serializer.
+
+        Args:
+            sample_rate: Sample rate in kHz used by Asterisk, defaults to 0 (will be populated during setup or from MEDIA_START event).
+        """
+
+        self._asterisk_ws_proto = AsteriskWSProtocol()
+        self._input_resampler = None  # Will be initialized if resampling is needed
+        self._output_resampler = None  # Will be initialized if resampling is needed
+        self._pipeline_in_sample_rate = 0  # What rate should we send to the pipeline (and STT-like processors). Will be populated during setup
+        self._pipeline_out_sample_rate = 0  # What rate should we expect to receive from TTS-like processors. Will be populated during setup
+        self._asterisk_sample_rate = int(
+            sample_rate
+        )  # What sample rate is used in Asterisk websocket channel. If 0, will be populated during setup or from MEDIA_START event
+
+    def _handle_event(self, message: dict) -> Frame | None:
+        """Call the event handler if the handler is defined in the class, otherwise return None.
+
+        The handler methods should be named as "_ev_{event_name.lower()}" and should take the event message as a dictionary and return a Frame or None.
+
+        Args:
+            message: The event message as a dictionary.
+        """
+
+        message_type = message.get("event", None)
+        if message_type is None:
+            logger.warning(
+                f"Received Asterisk WebSocket message without 'event' field: {message}"
+            )
+            return None
+        handler = getattr(self, f"_ev_{message_type.lower()}", None)
+        if callable(handler):
+            typed_handler = cast(Callable[[dict], Frame | None], handler)
+            return typed_handler(message)
+        else:
+            logger.info(f"Received unhandled Asterisk WebSocket event: {message}")
+            return None
+
+    ### Asterisk Event handlers ###
+
+    def _ev_media_start(self, message: dict) -> Frame | None:
+        """MEDIA_START event handler.
+
+        MEDIA_START event is the first one we receive from Asterisk.
+        There are a few potentially useful parameters provided by Asterisk in the MEDIA_START event message:
+          connection_id: A UUID that will be set on the MEDIA_WEBSOCKET_CONNECTION_ID channel variable.
+          channel: The channel name on Asterisk.
+          channel_id: The channel's unique id on Asterisk.
+          format: The audio format set on the channel.
+          optimal_frame_size: The optimal frame size from Astersisk's perspective.
+          ptime: The packet size in milliseconds.
+          channel_variables: An object containing the variables currently set on the channel.
+          The latest can be very handy for moving data from dialplan/channel variables to Pipecat.
+          However, it's only available in JSON subprotocol, in plain-text subprotocol you will not have access to channel variables.
+          So if you need channel variables make sure to use JSON subprotocol on Asterisk WebSocket channel.
+        We send MEDIA_START event object to the pipeline as InputTransportMessageFrame, so the pipeline "knows" about the media parameters.
+
+        Args:
+            message: The dictionary representing of the MEDIA_START event message from Asterisk.
+        """
+        # Check if codec is slin
+        format = message.get("format", "").strip().lower()
+        if not format.startswith("slin"):
+            # Some Pipecat transports do transcoding on the fly in Pipecat, but this one doesn't for two reasons:
+            #   1. Pipecat AudioFrame has to be in slin format, and Asterisk can send all the flavors of slin out-of-the-box.
+            #   2. Asterisk is way more efficient in transcoding, it makes no sense to send non-slin audio to Pipecat and transcoding it there.
+            raise ValueError(
+                f"Unsupported audio format in Asterisk MEDIA_START event: [{message.get('format')}], we only support slin format for now. Please use make sure that Asterisk channel is configured to use slin[12..192]."
+            )
+
+        # Check if sample rate is defined
+        if self._asterisk_sample_rate == 0:
+            sample_rate = format[4:]
+            if sample_rate:
+                if not sample_rate.isdigit():
+                    raise ValueError(
+                        f"Invalid sample rate in Asterisk MEDIA_START event: [{sample_rate}] kHz. Sample rate should be a number in kHz, e.g., 'slin16' for 16000 Hz sample rate."
+                    )
+                # Check if sample rate is in the supported list, if not raise an error
+                sample_rate = int(sample_rate)
+                if sample_rate not in self.SUPPORTED_SAMPLE_RATES:
+                    raise ValueError(
+                        f"Unsupported sample rate in Asterisk MEDIA_START event: [{sample_rate}] kHz. Supported sample rates for slin format are {self.SUPPORTED_SAMPLE_RATES} kHz."
+                    )
+            else:
+                sample_rate = 8
+
+            self._asterisk_sample_rate = sample_rate * 1000
+
+        logger.info(f"Received MEDIA_START event from Asterisk: {message}")
+
+        # Check if input resampling is needed
+        if self._pipeline_in_sample_rate != self._asterisk_sample_rate:
+            logger.warning(
+                f"Asterisk sample rate: ({self._asterisk_sample_rate} Hz) != pipeline input sample rate ({self._pipeline_in_sample_rate} Hz). Please, try to avoid resampling when possible."
+            )
+            self._input_resampler = self.create_resampler("input")
+
+        # Check if output resampling is needed
+        if self._pipeline_out_sample_rate != self._asterisk_sample_rate:
+            logger.warning(
+                f"Asterisk sample rate: ({self._asterisk_sample_rate} Hz) != pipeline output sample rate ({self._pipeline_out_sample_rate} Hz). Please, try to avoid resampling when possible."
+            )
+            self._output_resampler = self.create_resampler("output")
+
+        return InputTransportMessageFrame(message=message)
+
+    def _ev_media_xoff(self, message: dict) -> Frame | None:
+        """MEDIA_XOFF event handler.
+
+        The Asterisk's websocket channel driver will send this event when the frame queue length reaches the high water (XOFF) level.
+        Any media sent after this has a high probability of being dropped. We don't use them in our flow control implementation,
+        but getting this message means that our flow control implementation failed to keep the remote buffer under the high water mark, so we log a warning about it.
+
+        Args:
+            message: The dictionary representing of the MEDIA_XOFF event message from Asterisk.
+        """
+        logger.error(
+            f"Received MEDIA_XOFF event from Asterisk: {message}. Oops, we hit the high water mark, probably Asterisk will drop the following audio frames."
+        )
+        return None
+
+    def _ev_media_xon(self, message: dict) -> Frame | None:
+        """MEDIA_XON event handler.
+
+        The Asterisk's websocket channel driver will send this event when the frame queue length drops below the low water (XON) level.
+        The app can then resume sending media. Again, out transport implements flow control to avoid reaching this point
+        and it doesn't rely on these events for implementing flow control.
+
+        Args:
+            message: The dictionary representing of the MEDIA_XON event message from Asterisk.
+        """
+        logger.debug(
+            f"Received MEDIA_XON event from Asterisk: {message}. Asterisk audio buffer is ready to receive audio again."
+        )
+        return None
+
+    def _ev_dtmf_end(self, message: dict) -> Frame | None:
+        """DTMF_END event handler.
+
+        Handles DTMF_END events from Asterisk and converts them to InputDTMFFrame.
+
+        Args:
+            message: The dictionary representing of the DTMF_END event message from Asterisk.
+
+        Returns:
+            An InputDTMFFrame if a valid DTMF digit is found, otherwise None.
+        """
+        digit = message.get("digit")
+        if digit:
+            try:
+                return InputDTMFFrame(KeypadEntry(digit))
+            except ValueError:
+                # Handle case where string doesn't match any enum value
+                logger.warning(f"Invalid DTMF digit received: {digit}")
+                return None
+        return None
+
+    def _ev_queue_drained(self, message: dict) -> Frame | None:
+        # TODO: add REPORT_QUEUE_DRAINED support in the transport
+        """QUEUE_DRAINED event handler.
+
+        Handles QUEUE_DRAINED events from Asterisk. This event indicates that Asterisk has processed all the queued media.
+        We will only receive this event if we requested it by sending "REPORT_QUEUE_DRAINED", and only once per one "REPORT_QUEUE_DRAINED".
+        Effectively, this means that Asterisk stopped playing audio to the channel(bot stopped speaking), which might be good to know in Pipecat.
+        However, sending "REPORT_QUEUE_DRAINED" is currently (April 2026) not used by the transport, so you unlikely will receive this event.
+
+        Args:
+            message: The dictionary representing of the QUEUE_DRAINED event message from Asterisk.
+        """
+        logger.debug(
+            f"Received QUEUE_DRAINED event from Asterisk: {message}. Asterisk has processed all the queued media."
+        )
+        return InputTransportMessageFrame(message=message)
+
+    #### Pipecat Frame handlers ####
+
+    async def _frame_outputaudiorawframe(
+        self, frame: OutputAudioRawFrame
+    ) -> Optional[bytes]:
+        """OutputAudioRawFrame handler.
+
+        This handler extracts raw audio bytes from the OutputAudioRawFrame, resamples it if needed, and returns the raw audio bytes to be sent to Asterisk WebSocket channel.
+
+        Args:
+            frame: The OutputAudioRawFrame to be processed.
+        """
+
+        data = frame.audio
+
+        if not data or len(data) == 0:
+            logger.debug("OutputAudioRawFrame contains no audio data to serialize.")
+            return None
+
+        if self._pipeline_out_sample_rate != frame.sample_rate:
+            logger.warning(
+                f"OutputAudioRawFrame sample rate ({frame.sample_rate} Hz) != pipeline output sample rate ({self._pipeline_out_sample_rate} Hz). We can't resample the audio frame properly."
+            )
+
+        if frame.num_channels != 1:
+            logger.warning(
+                f"OutputAudioRawFrame has {frame.num_channels} channels, but Asterisk WebSocket channel only supports mono audio. We can't send this audio frame to Asterisk."
+            )
+            return None
+
+        if self._asterisk_sample_rate == self._pipeline_out_sample_rate:
+            logger.trace("Forwarding audio frame without resampling.")
+            return data
+        else:
+            if self._output_resampler is None:
+                logger.warning(
+                    "Resampling is required but output resampler is not initialized, we can't resample the audio."
+                )
+                return None
+            else:
+                logger.trace(
+                    f"Resampling audio from {self._pipeline_out_sample_rate} Hz to Asterisk sample rate {self._asterisk_sample_rate} Hz before sending to Asterisk."
+                )
+                resampled_audio = await self._output_resampler(data)
+                if resampled_audio is None or len(resampled_audio) == 0:
+                    logger.trace("Resampled audio contains no data.")
+                    return None
+                return resampled_audio
+
+    def _frame_asteriskcommandframe(self, frame: AsteriskCommandFrame) -> str:
+        """AsteriskCommandFrame handler.
+
+        Returns properly formatted arbitrary command for Asterisk WebSocket channel when an AsteriskCommandFrame is processed, using the command string provided in the frame.
+
+        Args:
+            frame: The AsteriskCommandFrame to be processed.
+        """
+        return self._asterisk_ws_proto.build(frame.cmd)
+
+    def _frame_endframe(self, frame: EndFrame) -> str:
+        """EndFrame handler. Terminate the call on Asterisk by sending HANGUP command when an EndFrame is processed.
+
+        Returns properly formatted HANGUP command for Asterisk WebSocket channel when an EndFrame is processed, indicating that the call should be terminated.
+
+        Args:
+            frame: The EndFrame to be processed.
+        """
+        return self._asterisk_ws_proto.build("HANGUP")
+
+    def _frame_cancelframe(self, frame: CancelFrame) -> str:
+        """CancelFrame handler. Terminate the call on Asterisk by sending HANGUP command when a CancelFrame is processed.
+
+        Returns properly formatted HANGUP command for Asterisk WebSocket channel when a CancelFrame is processed, indicating that the call should be terminated.
+
+        Args:
+            frame: The CancelFrame to be processed.
+        """
+        return self._asterisk_ws_proto.build("HANGUP")
+
+    def _frame_interruptionframe(self, frame: InterruptionFrame) -> str:
+        """InterruptionFrame handler.
+
+        Returns properly formatted FLUSH_MEDIA command for Asterisk WebSocket channel when an InterruptionFrame is processed,
+        indicating that the buffered media on Asterisk should be flushed (bot stops speaking immediately).
+
+        Args:
+            frame: The InterruptionFrame to be processed.
+        """
+        return self._asterisk_ws_proto.build("FLUSH_MEDIA")
+
+    ### Utility methods ###
+
+    def create_resampler(self, direction: str) -> Callable[[bytes], Awaitable[bytes]]:
+        """Create a resampler function to convert audio between different sample rates.
+
+        Args:
+            input_sample_rate: The sample rate of the input audio.
+            output_sample_rate: The sample rate of the output audio.
+
+        Returns:
+            A function that takes raw audio bytes as input and returns resampled audio bytes.
+        """
+
+        if direction not in ["input", "output"]:
+            raise ValueError(
+                f"Invalid direction for resampler: {direction}, it should be either 'input' or 'output'."
+            )
+
+        if direction == "input":
+            resampler_input_rate = self._asterisk_sample_rate
+            resampler_output_rate = self._pipeline_in_sample_rate
+        else:
+            resampler_input_rate = self._pipeline_out_sample_rate
+            resampler_output_rate = self._asterisk_sample_rate
+
+        if resampler_input_rate == resampler_output_rate:
+            # No resampling needed, return dummy function
+            logger.warning(
+                f"Dummy resampler created for [{direction}] direction, in_rate ({resampler_input_rate} Hz), out_rate ({resampler_output_rate} Hz)."
+            )
+
+            async def dummy(audio) -> bytes:
+                return audio
+
+            return dummy
+        else:
+            # Create the stateful instance of resampler
+            resampler = create_stream_resampler()
+
+            # Wrapper for that instance
+            async def wrap_resample(audio) -> bytes:
+                return await resampler.resample(
+                    audio, resampler_input_rate, resampler_output_rate
+                )
+
+            return wrap_resample
+
+    ### FrameSerializer interface implementation ###
+
+    async def setup(self, frame: StartFrame):
+        """Initialize the serializer with startup configuration.
+
+        Defined to set the pipeline input sample rate for resampling.
+
+        Args:
+            frame: StartFrame containing initialization parameters.
+        """
+        self._pipeline_in_sample_rate = frame.audio_in_sample_rate
+        self._pipeline_out_sample_rate = frame.audio_out_sample_rate
+
+        if self._pipeline_in_sample_rate != self._pipeline_out_sample_rate:
+            logger.warning(
+                f"Pipeline input sample rate ({self._pipeline_in_sample_rate} Hz) != output sample rate ({self._pipeline_out_sample_rate} Hz). Please try to avoid resampling when possible."
+            )
+
+    async def serialize(self, frame: Frame) -> str | bytes | None:
+        """Convert a frame to its serialized representation suitable for Asterisk WebSocket channel.
+
+        Args:
+            frame: The frame to serialize.
+
+        Returns:
+            Serialized frame data as string, bytes, or None if serialization fails.
+        """
+        handler = getattr(self, f"_frame_{type(frame).__name__.lower()}", None)
+        if callable(handler):
+            result = handler(frame)
+            if inspect.isawaitable(result):
+                return cast(str | bytes | None, await result)
+            else:
+                return cast(str | bytes | None, result)
+        else:
+            logger.trace(
+                f"Received unhandled frame type in Asterisk WebSocket serializer: {type(frame)}. Frame: {frame}"
+            )
+            return None
+
+    async def deserialize(self, data: str | bytes) -> Frame | None:
+        """Convert serialized data from Asterisk's websocket channel to a frame object.
+
+        Args:
+            data: Serialized frame data as string or bytes.
+
+        Returns:
+            Reconstructed Frame object, or None if deserialization fails.
+        """
+
+        # Handle audio
+        if isinstance(data, bytes):
+            # Check if input resampling is needed
+            if self._pipeline_in_sample_rate != self._asterisk_sample_rate:
+                if self._input_resampler is None:
+                    logger.warning(
+                        "Resampling is required but input resampler is not initialized, we can't resample the audio frame."
+                    )
+                    return None
+                else:
+                    logger.trace(
+                        f"Resampling audio from Asterisk sample rate {self._asterisk_sample_rate} Hz to pipeline input sample rate {self._pipeline_in_sample_rate} Hz."
+                    )
+                    resampled_audio = await self._input_resampler(data)
+                    if resampled_audio is None or len(resampled_audio) == 0:
+                        logger.trace("Resampled audio contains no data.")
+                        return None
+            else:
+                logger.trace("Forwarding audio from Asterisk without resampling.")
+                resampled_audio = data
+            return InputAudioRawFrame(
+                audio=resampled_audio,
+                num_channels=1,
+                sample_rate=self._pipeline_in_sample_rate,
+            )
+
+        # Handle events
+        elif isinstance(data, str):
+            event = self._asterisk_ws_proto.parse(data)
+
+            if event is not None:
+                return self._handle_event(event)
+            else:
+                logger.warning(
+                    f"Failed to parse Asterisk WebSocket event from data: {data}"
+                )
+                return None
+        else:
+            logger.warning(
+                f"Received data of unsupported type from Asterisk WebSocket channel: {type(data)}. Data: {data}"
+            )
+            return None

pipecat_asterisk/transport/__init__.py

@@ -0,0 +1,10 @@
+#
+# Copyright (c) 2026, Nikolai Shakin
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+from .transport import AsteriskWebsocketTransport
+from .flow_controller import FlowController
+
+__all__ = ["AsteriskWebsocketTransport", "FlowController"]

pipecat_asterisk/transport/flow_controller.py

@@ -0,0 +1,172 @@
+#
+# Copyright (c) 2026, Nikolai Shakin
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+import asyncio
+from loguru import logger
+import time
+from pipecat.transports.websocket.fastapi import (
+    FastAPIWebsocketClient,
+)
+
+
+class FlowController:
+    """Controls the flow of audio frames sent over the WebSocket connection.
+
+    It manages a local buffer and estimates the utilization of the remote buffer
+    on the Asterisk side to prevent buffer overflow and audio under-runs. Audio
+    chunks are dispatched in batches based on configured low and high water marks,
+    ensuring smooth playback while respecting WebSocket message size limits.
+    """
+
+    # Percentages of the remote buffer size to use as low and high water marks for flow control.
+    REMOTE_BUFFER_LOW_WATER = 0.1
+    REMOTE_BUFFER_HIGH_WATER = 0.8
+
+    # Size of the remote buffer in frames(or audio chunks) of psize. It's currently (Apr 2026) hardcoded on Asterisk side.
+    REMOTE_BUFFER_SIZE = 1000
+
+    # Minimum number of bytes to send when the remote buffer is in working range (between low and high water marks).
+    # We don't need to send data in small chunks in every tick if the buffer is loaded on the remote side.
+    # 50 frames is about 1 second of audio at 20ms ptime, so after we reached the low water mark we will send audio in batches of at least one second of audio.
+    # So with the default values we will have at least 20ms*1000*0.1 = 2 seconds of audio in the remote buffer before we start sending audio in batches,
+    # and we will send at least 1 second of audio every time we send while the remote buffer is between 20% and 80% full.
+    # If the remote buffer is above 80% full we will stop sending until it goes below 80% again.
+    # If the remote buffer is below 20% full we will send whatever we have in the local buffer without waiting for the minimum batch size to be reached,
+    # to quickly fill the remote buffer and avoid buffer under-utilization.
+    MIN_BATCH = 50
+
+    # Based on Asterisk documentation.The maximum websocket message size the underlying websocket code can handle is 65500 bytes.
+    # We need to ensure we don't exceed this limit when sending audio chunks. However, if the size is 65500 - it kills the session with the following error
+    # DEBUG[22367][C-00000050]: chan_websocket.c:1107 read_from_ws_and_queue: WebSocket/pipecat/0xfffee4009f58: WebSocket read error
+    # To be safe we use 50000 bytes, it worked in tests without issues.
+    MAX_WS_SEND = 50000
+
+    def __init__(
+        self, ptime: int, psize: int, websocket_client: FastAPIWebsocketClient
+    ):
+        self._ptime = ptime  # Audio chunk duration. In milliseconds
+        self._psize = psize  # Audio chunk size. In bytes
+        self._websocket_client = websocket_client
+        self._local_buffer = bytearray()
+        self._remote_buffer_low_water = (
+            self.REMOTE_BUFFER_LOW_WATER * self.REMOTE_BUFFER_SIZE * self._psize
+        )
+        self._remote_buffer_high_water = (
+            self.REMOTE_BUFFER_HIGH_WATER * self.REMOTE_BUFFER_SIZE * self._psize
+        )
+        self._remote_buffer_utilization = 0.0  # In bytes, but it has to be float otherwise it will drift badly due to integer division
+        self._min_batch = self.MIN_BATCH * self._psize
+        # Start the flow control task
+        self._flow_control = asyncio.create_task(self.flow_control())
+
+    def __call__(self, chunk: bytes) -> None:
+        """Add an audio chunk to the local buffer
+
+        It handles arbitrary sized audio chunks but it's expected that the audio chunks are passed properly sampled.
+        No modifications are made on the audio chunks content after they are passed to the flow controller.
+
+        Args:
+            chunk: The audio chunk to add to the local buffer.
+
+        """
+        self._local_buffer.extend(chunk)
+        logger.trace(
+            f"Buffered {len(chunk)} bytes to local buffer. Local buffer size: {len(self._local_buffer)} bytes."
+        )
+
+    async def flow_control(self):
+        """Keep track of the remote buffer utilization and send audio whenever possible.
+
+        The method runs an infinite loop that:
+            - Calculate the remote buffer utilization using monotonic time instead of async sleeping time to avoid drift.
+            - Implement the flow control logic based on the remote buffer utilization and local buffer size.
+            - Sends audio chunks whenever the remote buffer utilization is below the low water mark and there are audio chunks in the local buffer, but never exceed the high water mark or the websocket maximum message size.
+        """
+
+        last_tick = time.monotonic()
+        while True:
+            await asyncio.sleep(
+                self._ptime / 1000
+            )  # Sleep for the duration of one audio chunk
+            current_time = time.monotonic()
+            elapsed_time = current_time - last_tick
+            self._remote_buffer_utilization = max(
+                0,
+                self._remote_buffer_utilization
+                - (self._psize * 1000 / self._ptime) * elapsed_time,
+            )
+            last_tick = current_time
+
+            # Flow control logic
+            # First check if we have something in the local buffer
+            if len(self._local_buffer) > 0:
+                # If the remote buffer is under the low water mark we send whatever we have in the local buffer
+                if self._remote_buffer_utilization < self._remote_buffer_low_water:
+                    await self.send_chunks()
+
+                # If the remote buffer is in working range (between the low and high water marks)
+                # we  only send if we have more than _min_batch bytes of audio in the local buffer to avoid sending small chunks on every tick
+                elif (
+                    self._remote_buffer_utilization < self._remote_buffer_high_water
+                ) and (len(self._local_buffer) >= self._min_batch):
+                    await self.send_chunks()
+                # If the remote buffer is above the high water mark we don't send anything and wait for the next tick to see if the remote buffer utilization has decreased enough to send more audio
+
+    async def send_chunks(self):
+        """Send audio chunks from the local buffer to websocket (effectively to the remote buffer on the Asterisk side).
+
+        The method:
+            - Sends as much bytes from the local buffer as possible but not more than remote buffer high water mark and websocket maximum message size.
+            - Updates the remote buffer utilization accordingly.
+        """
+
+        # Calculate the number of bytes to send
+        bytes_to_send = int(
+            min(
+                len(self._local_buffer),
+                self._remote_buffer_high_water - self._remote_buffer_utilization,
+            )
+        )
+        bytes_to_send = min(
+            bytes_to_send, self.MAX_WS_SEND
+        )  # Ensure we don't exceed the websocket maximum message size
+        if bytes_to_send > 0:
+            # Take the bytes to send from the local buffer
+            chunk = self._local_buffer[:bytes_to_send]
+            del self._local_buffer[:bytes_to_send]
+
+            # Send the chunk to the websocket
+            await self._websocket_client.send(chunk)
+            # Update the remote buffer utilization
+            self._remote_buffer_utilization += len(chunk)
+            logger.debug(
+                f"Sent {len(chunk)} bytes to websocket. Remote buffer utilization: {self._remote_buffer_utilization:.0f} bytes, {self._remote_buffer_utilization / (self._psize * self.REMOTE_BUFFER_SIZE) * 100:.1f}%."
+            )
+
+    def close(self, gracefully: bool = False):
+        """Cancel the flow control task and optionally wait for the local buffer to be sent before cancelling.
+
+        Args:
+            gracefully: If True, wait for the local buffer to be sent before cancelling the flow control
+        """
+        if self._flow_control:
+            if gracefully:
+                logger.info(
+                    f"Gracefully closing flow controller. Waiting for local buffer to be sent..."
+                )
+                while len(self._local_buffer) > 0:
+                    time.sleep(
+                        self._ptime / 1000
+                    )  # Sleep for the duration of one audio chunk to give the flow control loop time to send the remaining audio in the local buffer
+            self._flow_control.cancel()
+
+    def drop_buffer(self):
+        """Drop any buffered audio in the local buffer and reset remote buffer utilization to zero.
+
+        This is used when an interruption/stop/cancel frame is processed to avoid replaying stale audio.
+        """
+        self._local_buffer.clear()
+        self._remote_buffer_utilization = 0.0

pipecat_asterisk/transport/transport.py

@@ -0,0 +1,192 @@
+#
+# Copyright (c) 2026, Nikolai Shakin
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+from fastapi import WebSocket
+from loguru import logger
+from pipecat.transports.websocket.fastapi import (
+    FastAPIWebsocketClient,
+    FastAPIWebsocketOutputTransport,
+    FastAPIWebsocketTransport,
+    FastAPIWebsocketParams,
+)
+from pipecat.processors.frame_processor import FrameDirection
+from pipecat.frames.frames import (
+    Frame,
+    InterruptionFrame,
+    CancelFrame,
+    StopFrame,
+    InputTransportMessageFrame,
+    OutputAudioRawFrame,
+)
+
+from .flow_controller import FlowController
+from ..serializer.serializer import AsteriskFrameSerializer, AsteriskCommandFrame
+
+
+class AsteriskWebsocketOutputTransport(FastAPIWebsocketOutputTransport):
+    """Subclass of FastAPIWebsocketOutputTransport to handle Asterisk WebSocket channel communication."""
+
+    def __init__(
+        self,
+        transport: "AsteriskWebsocketTransport",
+        client: FastAPIWebsocketClient,
+        params: FastAPIWebsocketParams | None = None,
+        name: str | None = None,
+    ):
+        if params is None:
+            params = FastAPIWebsocketParams(
+                serializer=AsteriskFrameSerializer(),
+                audio_in_enabled=True,
+                audio_out_enabled=True,
+            )
+        super().__init__(transport, client, params)
+        self._flow_controller = None
+
+    async def _media_start_handler(self, frame: InputTransportMessageFrame):
+        """Handle the MEDIA_START event.
+
+        Initializes the flow controller with ptime and psize values from the MEDIA_START event data.
+        Sends a START_MEDIA_BUFFERING command to Asterisk to enable audio buffering.
+        """
+
+        ptime = int(frame.message.get("ptime", 0))
+        psize = int(frame.message.get("optimal_frame_size", 0))
+
+        if ptime <= 0 or psize <= 0:
+            logger.error(
+                f"Invalid ptime ({ptime}) or psize ({psize}) in MEDIA_START event {frame.message}. Cannot initialize flow controller."
+            )
+            return
+
+        self._flow_controller = FlowController(ptime, psize, self._client)
+
+        logger.debug(
+            f"Initialized flow controller with ptime={ptime} ms, psize={psize} bytes. Remote buffer low water mark: {self._flow_controller._remote_buffer_low_water} bytes, high water mark: {self._flow_controller._remote_buffer_high_water} bytes."
+        )
+
+        # Send START_MEDIA_BUFFERING command to Asterisk WebSocket channel to enable audio buffering on the Asterisk side
+        if self._client.is_closing or not self._client.is_connected:
+            logger.warning(
+                f"Cannot send START_MEDIA_BUFFERING command because the WebSocket client is closing or already closed."
+            )
+            return
+        if not self._params.serializer:
+            logger.error(
+                f"Cannot send START_MEDIA_BUFFERING command because no serializer is set in the transport parameters."
+            )
+            return
+        try:
+            cmd = await self._params.serializer.serialize(
+                AsteriskCommandFrame("START_MEDIA_BUFFERING")
+            )
+            if cmd:
+                await self._client.send(cmd)
+                logger.info(
+                    f"Sent START_MEDIA_BUFFERING command to Asterisk WebSocket channel to enable audio buffering."
+                )
+        except Exception as e:
+            logger.error(
+                f"{self} exception sending START_MEDIA_BUFFERING: {e.__class__.__name__} ({e})"
+            )
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process outgoing frames.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
+        await super().process_frame(frame, direction)
+
+        if isinstance(frame, (InterruptionFrame, CancelFrame, StopFrame)):
+            # Drop any buffered audio in local and remote buffers to avoid replaying stale PCM
+            if self._flow_controller:
+                self._flow_controller.drop_buffer()
+        elif (
+            isinstance(frame, InputTransportMessageFrame)
+            and frame.message.get("event", None) == "MEDIA_START"
+        ):
+            await self._media_start_handler(frame)
+
+    async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
+        """Write an audio frame into local buffer.
+
+        The method overrides parent class method. Effectively the audio frame is passed to the flow controller
+        instead of writing them directly to the websocket. Formally, this method doesn't write audio frames as the name suggests.
+
+        Args:
+            frame: The output audio frame to write.
+
+        Returns:
+            True if the audio frame was "written" (passed to the flow controller) successfully, False otherwise.
+        """
+
+        if self._client.is_closing or not self._client.is_connected:
+            logger.warning(
+                f"Cannot write audio frame because the WebSocket client is closing or already closed."
+            )
+            return False
+
+        if not self._params.serializer:
+            logger.error(
+                f"Serializer is not set in transport parameters. Cannot write audio frame."
+            )
+            return False
+
+        if self._flow_controller is None:
+            logger.error(
+                f"Flow controller is not initialized. Cannot write audio frame."
+            )
+            return False
+
+        frame = OutputAudioRawFrame(
+            audio=frame.audio,
+            sample_rate=frame.sample_rate,
+            num_channels=frame.num_channels,
+        )
+
+        try:
+            payload = await self._params.serializer.serialize(frame)
+            if payload:
+                if type(payload) == bytes:
+                    self._flow_controller(payload)
+                    return True
+                else:
+                    logger.error(
+                        f"Serialized audio frame is not bytes. Got {type(payload)} instead. Cannot write audio frame."
+                    )
+                    return False
+            else:
+                logger.trace(
+                    f"Serializer returned None or empty payload. Cannot write audio frame."
+                )
+                return False
+        except Exception as e:
+            logger.error(f"{self} exception sending data: {e.__class__.__name__} ({e})")
+            return False
+
+
+class AsteriskWebsocketTransport(FastAPIWebsocketTransport):
+    """Subclass of FastAPIWebsocketTransport to handle Asterisk WebSocket channel communication."""
+
+    def __init__(
+        self,
+        websocket: WebSocket,
+        params: FastAPIWebsocketParams | None = None,
+        input_name: str | None = None,
+        output_name: str | None = None,
+    ):
+        if params is None:
+            params = FastAPIWebsocketParams(
+                serializer=AsteriskFrameSerializer(),
+                audio_in_enabled=True,
+                audio_out_enabled=True,
+            )
+        super().__init__(websocket, params, input_name, output_name)
+
+        self._output = AsteriskWebsocketOutputTransport(
+            self, self._client, params, name=output_name
+        )

pipecat_asterisk-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: pipecat-asterisk
+Version: 0.1.0
+Summary: This package provides a WebSocket transport for integrating Pipecat applications with Asterisk websocket channel, enabling real-time audio streaming and signalling interaction between Asterisk and Pipecat applications.
+Author: Nikolai  Shakin
+Author-email: Nikolai  Shakin <nikolay.n.shakin@gmail.com>
+License: BSD-2-Clause
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: pipecat-ai>=1.1.0
+Requires-Dist: websockets>=15.0.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pipecat-asterisk
+
+A [Pipecat](https://github.com/pipecat-ai/pipecat) community integration for Asterisk. 
+This repository provides a transport and frame serializer to connect your Asterisk with Pipecat pipelines.
+
+## Features
+
+- **`AsteriskWebsocketTransport`**: Handles raw audio streaming and lifecycle events natively with Asterisk.
+- **`AsteriskFrameSerializer`**: Serializer to translate Asterisk websocket JSON or plain-text payloads and raw(audio) payloads into Pipecat frames.
+- **Flow Control**: Built-in logic to manage buffer utilization between the Pipecat application and Asterisk.
+
+## Installation
+
+```bash
+uv add pipecat-asterisk
+```
+*(Or use `pip install pipecat-asterisk` if you are using `pip` for dependency management)*
+
+## Usage
+
+Here is a basic example of how to integrate the Asterisk WebSocket transport into a Pipecat pipeline:
+
+```python
+from fastapi import FastAPI, WebSocket
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.task import PipelineTask
+from pipecat_asterisk import AsteriskWebsocketTransport
+
+app = FastAPI()
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+    
+    # Initialize the Asterisk Transport
+    ws_transport = AsteriskWebsocketTransport(websocket=websocket)
+    
+    # Build your Pipecat pipeline
+    pipeline = Pipeline([
+        ws_transport.input(),
+        # ... other pipeline components (VAD, LLM, TTS, etc.)
+        ws_transport.output(),
+    ])
+    
+    task = PipelineTask(pipeline)
+    
+    # Run the pipeline
+    # ...
+```
+
+## Running the Example
+
+An example Gemini-based voice bot is provided in `examples/pipecat_asterisk/`.
+
+### 1. Configure Asterisk
+The `examples/pipecat_asterisk/` directory includes a `docker-compose.yml` and Asterisk configuration files in `etc/` to easily spin up a local Asterisk testing environment. After the Docker container is running you can connect any sip client to `localhost:5060` with the credentials specified in `etc/asterisk/pjsip.conf` (user: `1`, password: `1`). There are a few extensions configured in `etc/asterisk/extensions.conf` that you can use to test the bot, every extension represents a respective sampling rate.
+
+```
+exten = 8,1,Dial(WebSocket/pipecat/c(slin))
+exten = 12,1,Dial(WebSocket/pipecat/c(slin12))
+exten = 16,1,Dial(WebSocket/pipecat/c(slin16))
+exten = 24,1,Dial(WebSocket/pipecat/c(slin24))
+...
+```
+
+To run the Asterisk server with the provided configuration:
+
+```bash
+cd examples/pipecat_asterisk
+docker-compose up -d
+```
+
+### 2. Set API Keys
+The example uses Google's Gemini for conversational AI. Create a `.env` file or export your key directly:
+
+```bash
+export GOOGLE_API_KEY="your-google-api-key"
+```
+
+### 3. Run the application
+Run the WebSocket server:
+```bash
+uv sync
+uv run examples/pipecat_asterisk/ws_server.py
+```
+
+## Compatibility
+
+- Tested with **Pipecat v1.1.0**
+- Requires **Python 3.12+**
+
+## Internal Architecture
+
+The transport and the serializer are designed to work with `slin` encoded audio, because Asterisk natively supports all the flavors of `slin` and Pipecat's audio frames require to be slin-encoded.
+If you need to use a different codec, you can transcode on the Asterisk side, it's computationally more efficient and simplifies the transport and serializer logic.
+
+Serializer and the transport implementation are based on the [Asterisk websocket channel documentation](https://docs.asterisk.org/Configuration/Channel-Drivers/WebSocket/).
+
+The transport supports flow control logic to manage the buffer utilization between the Pipecat application and Asterisk. This ensures that we don't overwhelm the Asterisk server with too much data at once, while also ensuring that we send data as soon as there is capacity in the remote buffer. The output transport create an instance of flow controller and adds serialized (and resampled if needed) audio frames to the flow controller. The flow controller then decides when to send data to Asterisk based on the current buffer utilization and the amount of data in the local buffer. The flow control logic is as follows: 
+
+### Flow control logic
+```mermaid
+flowchart TD
+    C{Remote buffer utilization < <br>low water}
+    C -->|yes| D{There are bytes in local buffer}
+    C -->|no| H{Remote buffer utilization > <br>high water}
+    H -->|yes| E[Skip]
+    D -->|yes| F[Send up to MAX_WS_SEND <br> bytes from local buffer]
+    D -->|no| E
+    H -->|no| I{Do we have more than <br>MIN_BATCH bytes in local <br>buffer}
+    I -->|yes| F
+    I -->|no| E
+```

pipecat_asterisk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pipecat_asterisk/__init__.py,sha256=4h0wX0LetaHTL7QqfGZbVU0v5f6iWPQ4_YxbAjhb2J0,272
+pipecat_asterisk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pipecat_asterisk/serializer/__init__.py,sha256=eJMxpL0FnIPY4-Ullm6BNQXCbgslINycj-kz9iu4iaw,234
+pipecat_asterisk/serializer/protocol.py,sha256=iEyAr4VzvL2NlZQsYdVWqbkXPVhXRVTkceFYE4sJBUU,3445
+pipecat_asterisk/serializer/serializer.py,sha256=H3OxesEUhGdnEGGozsgroVKK-dvMJk9wBHc9Vh6cnN4,22640
+pipecat_asterisk/transport/__init__.py,sha256=jUJ0IiK5QY3ZM4hvWbh021HBlpanKp6ceDRf5GYAnu4,238
+pipecat_asterisk/transport/flow_controller.py,sha256=YysxpQJe2hc0trM4IqnXQ1_J6AqZu--UNFu8U-YqiZU,8774
+pipecat_asterisk/transport/transport.py,sha256=ost-poEsTdSt_YpoLN_sm6pWwfRiPAqAsoZNtWobqa0,7239
+pipecat_asterisk-0.1.0.dist-info/WHEEL,sha256=jROcLULcdzropX2J55opKw4UHhPFREZax2XzS-Mvpxs,80
+pipecat_asterisk-0.1.0.dist-info/METADATA,sha256=jz_CGKpR0RI_ApvOvixpd_i8eIgqOh3fAEs_m5EapdY,5186
+pipecat_asterisk-0.1.0.dist-info/RECORD,,

pipecat_asterisk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.0
+Root-Is-Purelib: true
+Tag: py3-none-any