processors: add ProducerProcessor and ConsumerProcessor

src/pipecat/processors/consumer_processor.py

@@ -0,0 +1,65 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+import asyncio
+from typing import Awaitable, Callable, Optional
+
+from pipecat.frames.frames import CancelFrame, EndFrame, Frame, StartFrame
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
+from pipecat.processors.producer_processor import ProducerProcessor, identity_transformer
+
+
+class ConsumerProcessor(FrameProcessor):
+    """This class passes-through frames and also consumes frames from a
+    producer's queue. When a frame from a producer queue is received it will be
+    pushed to the specified direction. The frames can be transformed into a
+    different type of frame before being pushed.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        producer: ProducerProcessor,
+        transformer: Callable[[Frame], Awaitable[Frame]] = identity_transformer,
+        direction: FrameDirection = FrameDirection.DOWNSTREAM,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self._transformer = transformer
+        self._direction = direction
+        self._queue: asyncio.Queue = producer.add_consumer()
+        self._consumer_task: Optional[asyncio.Task] = None
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        await super().process_frame(frame, direction)
+
+        if isinstance(frame, StartFrame):
+            await self._start(frame)
+        elif isinstance(frame, EndFrame):
+            await self._stop(frame)
+        elif isinstance(frame, CancelFrame):
+            await self._cancel(frame)
+
+        await self.push_frame(frame, direction)
+
+    async def _start(self, _: StartFrame):
+        if not self._consumer_task:
+            self._consumer_task = self.create_task(self._consumer_task_handler())
+
+    async def _stop(self, _: EndFrame):
+        if self._consumer_task:
+            await self.cancel_task(self._consumer_task)
+
+    async def _cancel(self, _: CancelFrame):
+        if self._consumer_task:
+            await self.cancel_task(self._consumer_task)
+
+    async def _consumer_task_handler(self):
+        while True:
+            frame = await self._queue.get()
+            new_frame = await self._transformer(frame)
+            await self.push_frame(new_frame, self._direction)

src/pipecat/processors/producer_processor.py

@@ -0,0 +1,73 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+import asyncio
+from typing import Awaitable, Callable, List
+
+from pipecat.frames.frames import Frame
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
+
+
+async def identity_transformer(frame: Frame):
+    return frame
+
+
+class ProducerProcessor(FrameProcessor):
+    """This class optionally passes-through received frames and decides if those
+    frames should be sent to consumers based on a user-defined filter. The
+    frames can be transformed into a different type of frame before being
+    sending them to the consumers. More than one consumer can be added.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        filter: Callable[[Frame], Awaitable[bool]],
+        transformer: Callable[[Frame], Awaitable[Frame]] = identity_transformer,
+        passthrough: bool = True,
+    ):
+        super().__init__()
+        self._filter = filter
+        self._transformer = transformer
+        self._passthrough = passthrough
+        self._consumers: List[asyncio.Queue] = []
+
+    def add_consumer(self):
+        """
+        Adds a new consumer and returns its associated queue.
+
+        Returns:
+            asyncio.Queue: The queue for the newly added consumer.
+        """
+        queue = asyncio.Queue()
+        self._consumers.append(queue)
+        return queue
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """
+        Processes an incoming frame and determines whether to produce it as a ProducerItem.
+
+        If the frame meets the produce criteria, it will be added to the consumer queues.
+        If passthrough is enabled, the frame will also be sent to consumers.
+
+        Args:
+            frame (Frame): The frame to process.
+            direction (FrameDirection): The direction of the frame.
+        """
+        await super().process_frame(frame, direction)
+
+        if await self._filter(frame):
+            await self._produce(frame)
+            if self._passthrough:
+                await self.push_frame(frame, direction)
+        else:
+            await self.push_frame(frame, direction)
+
+    async def _produce(self, frame: Frame):
+        for consumer in self._consumers:
+            new_frame = await self._transformer(frame)
+            await consumer.put(new_frame)