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

pipecat/processors/frame_processor.py

@@ -4,11 +4,18 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Frame processing pipeline infrastructure for Pipecat.
+
+This module provides the core frame processing system that enables building
+audio/video processing pipelines. It includes frame processors, pipeline
+management, and frame flow control mechanisms.
+"""
+
 import asyncio
 import traceback
 from dataclasses import dataclass
 from enum import Enum
-from typing import Awaitable, Callable, Coroutine, List, Optional, Sequence
+from typing import Any, Awaitable, Callable, Coroutine, List, Optional, Sequence, Tuple
 
 from loguru import logger
 
@@ -28,51 +35,132 @@ from pipecat.frames.frames import (
     SystemFrame,
 )
 from pipecat.metrics.metrics import LLMTokenUsage, MetricsData
-from pipecat.observers.base_observer import BaseObserver, FramePushed
+from pipecat.observers.base_observer import BaseObserver, FrameProcessed, FramePushed
 from pipecat.processors.metrics.frame_processor_metrics import FrameProcessorMetrics
 from pipecat.utils.asyncio.task_manager import BaseTaskManager
-from pipecat.utils.asyncio.watchdog_event import WatchdogEvent
-from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue
 from pipecat.utils.base_object import BaseObject
 
 
 class FrameDirection(Enum):
+    """Direction of frame flow in the processing pipeline.
+
+    Parameters:
+        DOWNSTREAM: Frames flowing from input to output.
+        UPSTREAM: Frames flowing back from output to input.
+    """
+
     DOWNSTREAM = 1
     UPSTREAM = 2
 
 
+FrameCallback = Callable[["FrameProcessor", Frame, FrameDirection], Awaitable[None]]
+
+
 @dataclass
 class FrameProcessorSetup:
+    """Configuration parameters for frame processor initialization.
+
+    Parameters:
+        clock: The clock instance for timing operations.
+        task_manager: The task manager for handling async operations.
+        observer: Optional observer for monitoring frame processing events.
+    """
+
     clock: BaseClock
     task_manager: BaseTaskManager
     observer: Optional[BaseObserver] = None
-    watchdog_timers_enabled: bool = False
+
+
+class FrameProcessorQueue(asyncio.PriorityQueue):
+    """A priority queue for systems frames and other frames.
+
+    This is a specialized queue for frame processors that separates and
+    prioritizes system frames over other frames. It ensures that `SystemFrame`
+    objects are processed before any other frames by using a priority queue.
+
+    """
+
+    HIGH_PRIORITY = 1
+    LOW_PRIORITY = 2
+
+    def __init__(self):
+        """Initialize the FrameProcessorQueue.
+
+        Args:
+            manager (BaseTaskManager): The task manager used by the internal watchdog queues.
+
+        """
+        super().__init__()
+        self.__high_counter = 0
+        self.__low_counter = 0
+
+    async def put(self, item: Tuple[Frame, FrameDirection, FrameCallback]):
+        """Put an item into the priority queue.
+
+        System frames (`SystemFrame`) have higher priority than any other
+        frames. If a non-frame item (e.g. a watchdog cancellation sentinel) is
+        provided it will have the highest priority.
+
+        Args:
+            item (Any): The item to enqueue.
+
+        """
+        frame, _, _ = item
+        if isinstance(frame, SystemFrame):
+            self.__high_counter += 1
+            await super().put((self.HIGH_PRIORITY, self.__high_counter, item))
+        else:
+            self.__low_counter += 1
+            await super().put((self.LOW_PRIORITY, self.__low_counter, item))
+
+    async def get(self) -> Any:
+        """Retrieve the next item from the queue.
+
+        System frames are prioritized. If both queues are empty, this method
+        waits until an item is available.
+
+        Returns:
+            Any: The next item from the system or main queue.
+
+        """
+        _, _, item = await super().get()
+        return item
 
 
 class FrameProcessor(BaseObject):
+    """Base class for all frame processors in the pipeline.
+
+    Frame processors are the building blocks of Pipecat pipelines, they can be
+    linked to form complex processing pipelines. They receive frames, process
+    them, and pass them to the next or previous processor in the chain.  Each
+    frame processor guarantees frame ordering and processes frames in its own
+    task. System frames are also processed in a separate task which guarantees
+    frame priority.
+
+    """
+
     def __init__(
         self,
         *,
         name: Optional[str] = None,
-        enable_watchdog_logging: Optional[bool] = None,
-        enable_watchdog_timers: Optional[bool] = None,
+        enable_direct_mode: bool = False,
         metrics: Optional[FrameProcessorMetrics] = None,
-        watchdog_timeout_secs: Optional[float] = None,
         **kwargs,
     ):
-        super().__init__(name=name)
-        self._parent: Optional["FrameProcessor"] = None
+        """Initialize the frame processor.
+
+        Args:
+            name: Optional name for this processor instance.
+            enable_direct_mode: Whether to process frames immediately or use internal queues.
+            metrics: Optional metrics collector for this processor.
+            **kwargs: Additional arguments passed to parent class.
+        """
+        super().__init__(name=name, **kwargs)
         self._prev: Optional["FrameProcessor"] = None
         self._next: Optional["FrameProcessor"] = None
 
-        # Enable watchdog timers for all tasks created by this frame processor.
-        self._enable_watchdog_timers = enable_watchdog_timers
-
-        # Enable watchdog logging for all tasks created by this frame processor.
-        self._enable_watchdog_logging = enable_watchdog_logging
-
-        # Allow this frame processor to control their tasks timeout.
-        self._watchdog_timeout_secs = watchdog_timeout_secs
+        # Enable direct mode to skip queues and process frames right away.
+        self._enable_direct_mode = enable_direct_mode
 
         # Clock
         self._clock: Optional[BaseClock] = None
@@ -104,201 +192,396 @@ class FrameProcessor(BaseObject):
         self._metrics = metrics or FrameProcessorMetrics()
         self._metrics.set_processor_name(self.name)
 
-        # Processors have an input queue. The input queue will be processed
-        # immediately (default) or it will block if `pause_processing_frames()`
-        # is called. To resume processing frames we need to call
-        # `resume_processing_frames()` which will wake up the event.
-        self.__should_block_frames = False
-        self.__input_event = None
+        # Processors have an input priority queue which stores any type of
+        # frames in order. System frames have higher priority than any other
+        # frames, so they will be returned first from the queue.
+        #
+        # If a system frame is obtained it will be processed immediately any
+        # other type of frame (data and control) will be put in a separate queue
+        # for later processing. This guarantees that each frame processor will
+        # always process system frames before any other frame in the queue.
+
+        # The input task that handles all types of frames. It processes system
+        # frames right away and queues non-system frames for later processing.
+        self.__should_block_system_frames = False
+        self.__input_event: Optional[asyncio.Event] = None
         self.__input_frame_task: Optional[asyncio.Task] = None
 
-        # Every processor in Pipecat should only output frames from a single
-        # task. This avoid problems like audio overlapping. System frames are the
-        # exception to this rule. This create this task.
-        self.__push_frame_task: Optional[asyncio.Task] = None
+        # The process task processes non-system frames.  Non-system frames will
+        # be processed as soon as they are received by the processing task
+        # (default) or they will block if `pause_processing_frames()` is
+        # called. To resume processing frames we need to call
+        # `resume_processing_frames()` which will wake up the event.
+        self.__should_block_frames = False
+        self.__process_event: Optional[asyncio.Event] = None
+        self.__process_frame_task: Optional[asyncio.Task] = None
         self.logger = logger  # Will later be replaced with a bound logger
 
     @property
     def id(self) -> int:
+        """Get the unique identifier for this processor.
+
+        Returns:
+            The unique integer ID of this processor.
+        """
         return self._id
 
     @property
     def name(self) -> str:
+        """Get the name of this processor.
+
+        Returns:
+            The name of this processor instance.
+        """
         return self._name
 
+    @property
+    def processors(self) -> List["FrameProcessor"]:
+        """Return the list of sub-processors contained within this processor.
+
+        Only compound processors (e.g. pipelines and parallel pipelines) have
+        sub-processors. Non-compound processors will return an empty list.
+
+        Returns:
+            The list of sub-processors if this is a compound processor.
+        """
+        return []
+
+    @property
+    def entry_processors(self) -> List["FrameProcessor"]:
+        """Return the list of entry processors for this processor.
+
+        Entry processors are the first processors in a compound processor
+        (e.g. pipelines, parallel pipelines). Note that pipelines can also be an
+        entry processor as pipelines are processors themselves. Non-compound
+        processors will simply return an empty list.
+
+        Returns:
+            The list of entry processors.
+        """
+        return []
+
+    @property
+    def next(self) -> Optional["FrameProcessor"]:
+        """Get the next processor.
+
+        Returns:
+            The next processor, or None if there's no next processor.
+        """
+        return self._next
+
+    @property
+    def previous(self) -> Optional["FrameProcessor"]:
+        """Get the previous processor.
+
+        Returns:
+            The previous processor, or None if there's no previous processor.
+        """
+        return self._prev
+
     @property
     def interruptions_allowed(self):
+        """Check if interruptions are allowed for this processor.
+
+        Returns:
+            True if interruptions are allowed.
+        """
         return self._allow_interruptions
 
     @property
     def metrics_enabled(self):
+        """Check if metrics collection is enabled.
+
+        Returns:
+            True if metrics collection is enabled.
+        """
         return self._enable_metrics
 
     @property
     def usage_metrics_enabled(self):
+        """Check if usage metrics collection is enabled.
+
+        Returns:
+            True if usage metrics collection is enabled.
+        """
         return self._enable_usage_metrics
 
     @property
     def report_only_initial_ttfb(self):
+        """Check if only initial TTFB should be reported.
+
+        Returns:
+            True if only initial time-to-first-byte should be reported.
+        """
         return self._report_only_initial_ttfb
 
     @property
     def interruption_strategies(self) -> Sequence[BaseInterruptionStrategy]:
+        """Get the interruption strategies for this processor.
+
+        Returns:
+            Sequence of interruption strategies.
+        """
         return self._interruption_strategies
 
     @property
     def task_manager(self) -> BaseTaskManager:
+        """Get the task manager for this processor.
+
+        Returns:
+            The task manager instance.
+
+        Raises:
+            Exception: If the task manager is not initialized.
+        """
         if not self._task_manager:
             raise Exception(f"{self} TaskManager is still not initialized.")
         return self._task_manager
 
+    def processors_with_metrics(self):
+        """Return processors that can generate metrics.
+
+        Recursively collects all processors that support metrics generation,
+        including those from nested processors.
+
+        Returns:
+            List of frame processors that can generate metrics.
+        """
+        return []
+
     def can_generate_metrics(self) -> bool:
+        """Check if this processor can generate metrics.
+
+        Returns:
+            True if this processor can generate metrics.
+        """
         return False
 
     def set_core_metrics_data(self, data: MetricsData):
+        """Set core metrics data for this processor.
+
+        Args:
+            data: The metrics data to set.
+        """
         self._metrics.set_core_metrics_data(data)
 
     async def start_ttfb_metrics(self):
+        """Start time-to-first-byte metrics collection."""
         if self.can_generate_metrics() and self.metrics_enabled:
             await self._metrics.start_ttfb_metrics(self._report_only_initial_ttfb)
 
     async def stop_ttfb_metrics(self):
+        """Stop time-to-first-byte metrics collection and push results."""
         if self.can_generate_metrics() and self.metrics_enabled:
             frame = await self._metrics.stop_ttfb_metrics()
             if frame:
                 await self.push_frame(frame)
 
     async def start_processing_metrics(self):
+        """Start processing metrics collection."""
         if self.can_generate_metrics() and self.metrics_enabled:
             await self._metrics.start_processing_metrics()
 
     async def stop_processing_metrics(self):
+        """Stop processing metrics collection and push results."""
         if self.can_generate_metrics() and self.metrics_enabled:
             frame = await self._metrics.stop_processing_metrics()
             if frame:
                 await self.push_frame(frame)
 
     async def start_llm_usage_metrics(self, tokens: LLMTokenUsage):
+        """Start LLM usage metrics collection.
+
+        Args:
+            tokens: Token usage information for the LLM.
+        """
         if self.can_generate_metrics() and self.usage_metrics_enabled:
             frame = await self._metrics.start_llm_usage_metrics(tokens)
             if frame:
                 await self.push_frame(frame)
 
     async def start_tts_usage_metrics(self, text: str):
+        """Start TTS usage metrics collection.
+
+        Args:
+            text: The text being processed by TTS.
+        """
         if self.can_generate_metrics() and self.usage_metrics_enabled:
             frame = await self._metrics.start_tts_usage_metrics(text)
             if frame:
                 await self.push_frame(frame)
 
     async def stop_all_metrics(self):
+        """Stop all active metrics collection."""
         await self.stop_ttfb_metrics()
         await self.stop_processing_metrics()
 
-    def create_task(
-        self,
-        coroutine: Coroutine,
-        name: Optional[str] = None,
-        *,
-        enable_watchdog_logging: Optional[bool] = None,
-        enable_watchdog_timers: Optional[bool] = None,
-        watchdog_timeout_secs: Optional[float] = None,
-    ) -> asyncio.Task:
+    def create_task(self, coroutine: Coroutine, name: Optional[str] = None) -> asyncio.Task:
+        """Create a new task managed by this processor.
+
+        Args:
+            coroutine: The coroutine to run in the task.
+            name: Optional name for the task.
+
+        Returns:
+            The created asyncio task.
+        """
         if name:
             name = f"{self}::{name}"
         else:
             name = f"{self}::{coroutine.cr_code.co_name}"
-        return self.task_manager.create_task(
-            coroutine,
-            name,
-            enable_watchdog_logging=(
-                enable_watchdog_logging
-                if enable_watchdog_logging
-                else self._enable_watchdog_logging
-            ),
-            enable_watchdog_timers=(
-                enable_watchdog_timers if enable_watchdog_timers else self._enable_watchdog_timers
-            ),
-            watchdog_timeout=(
-                watchdog_timeout_secs if watchdog_timeout_secs else self._watchdog_timeout_secs
-            ),
-        )
+        return self.task_manager.create_task(coroutine, name)
 
     async def cancel_task(self, task: asyncio.Task, timeout: Optional[float] = None):
+        """Cancel a task managed by this processor.
+
+        Args:
+            task: The task to cancel.
+            timeout: Optional timeout for task cancellation.
+        """
         await self.task_manager.cancel_task(task, timeout)
 
     async def wait_for_task(self, task: asyncio.Task, timeout: Optional[float] = None):
-        await self.task_manager.wait_for_task(task, timeout)
+        """Wait for a task to complete.
+
+        .. deprecated:: 0.0.81
+            This function is deprecated, use `await task` or
+            `await asyncio.wait_for(task, timeout) instead.
+
+        Args:
+            task: The task to wait for.
+            timeout: Optional timeout for waiting.
+        """
+        import warnings
+
+        warnings.warn(
+            "`FrameProcessor.wait_for_task()` is deprecated. "
+            "Use `await task` or `await asyncio.wait_for(task, timeout)` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
-    def reset_watchdog(self):
-        self.task_manager.task_reset_watchdog()
+        if timeout:
+            await asyncio.wait_for(task, timeout)
+        else:
+            await task
 
     async def setup(self, setup: FrameProcessorSetup):
+        """Set up the processor with required components.
+
+        Args:
+            setup: Configuration object containing setup parameters.
+        """
         self._clock = setup.clock
         self._task_manager = setup.task_manager
         self._observer = setup.observer
-        self._watchdog_timers_enabled = (
-            self._enable_watchdog_timers
-            if self._enable_watchdog_timers
-            else setup.watchdog_timers_enabled
-        )
+
+        # Create processing tasks.
+        self.__create_input_task()
+
         if self._metrics is not None:
             await self._metrics.setup(self._task_manager)
 
     async def cleanup(self):
+        """Clean up processor resources."""
         await super().cleanup()
         await self.__cancel_input_task()
-        await self.__cancel_push_task()
+        await self.__cancel_process_task()
         if self._metrics is not None:
             await self._metrics.cleanup()
 
     def link(self, processor: "FrameProcessor"):
+        """Link this processor to the next processor in the pipeline.
+
+        Args:
+            processor: The processor to link to.
+        """
         self._next = processor
         processor._prev = self
         self.logger.debug(f"Linking {self} -> {self._next}")
 
-    def get_event_loop(self) -> asyncio.AbstractEventLoop:
-        return self.task_manager.get_event_loop()
-
-    def set_parent(self, parent: "FrameProcessor"):
-        self._parent = parent
+    def get_clock(self) -> BaseClock:
+        """Get the clock used by this processor.
 
-    def get_parent(self) -> Optional["FrameProcessor"]:
-        return self._parent
+        Returns:
+            The clock instance.
 
-    def get_clock(self) -> BaseClock:
+        Raises:
+            Exception: If the clock is not initialized.
+        """
         if not self._clock:
             raise Exception(f"{self} Clock is still not initialized.")
         return self._clock
 
+    def get_event_loop(self) -> asyncio.AbstractEventLoop:
+        """Get the event loop used by this processor.
+
+        Returns:
+            The asyncio event loop.
+        """
+        return self.task_manager.get_event_loop()
+
     async def queue_frame(
         self,
         frame: Frame,
         direction: FrameDirection = FrameDirection.DOWNSTREAM,
-        callback: Optional[
-            Callable[["FrameProcessor", Frame, FrameDirection], Awaitable[None]]
-        ] = None,
+        callback: Optional[FrameCallback] = None,
     ):
+        """Queue a frame for processing.
+
+        Args:
+            frame: The frame to queue.
+            direction: The direction of frame flow.
+            callback: Optional callback to call after processing.
+        """
         # If we are cancelling we don't want to process any other frame.
         if self._cancelling:
             return
 
-        if isinstance(frame, SystemFrame):
-            # We don't want to queue system frames.
-            await self.process_frame(frame, direction)
+        if self._enable_direct_mode:
+            await self.__process_frame(frame, direction, callback)
         else:
-            # We queue everything else.
             await self.__input_queue.put((frame, direction, callback))
 
     async def pause_processing_frames(self):
+        """Pause processing of queued frames."""
         self.logger.trace(f"{self}: pausing frame processing")
         self.__should_block_frames = True
 
+    async def pause_processing_system_frames(self):
+        """Pause processing of queued system frames."""
+        logger.trace(f"{self}: pausing system frame processing")
+        self.__should_block_system_frames = True
+
     async def resume_processing_frames(self):
+        """Resume processing of queued frames."""
         self.logger.trace(f"{self}: resuming frame processing")
+        if self.__process_event:
+            self.__process_event.set()
+
+    async def resume_processing_system_frames(self):
+        """Resume processing of queued system frames."""
+        self.logger.trace(f"{self}: resuming system frame processing")
         if self.__input_event:
             self.__input_event.set()
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process a frame.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow.
+        """
+        if self._observer:
+            timestamp = self._clock.get_time() if self._clock else 0
+            data = FrameProcessed(
+                processor=self,
+                frame=frame,
+                direction=direction,
+                timestamp=timestamp,
+            )
+            await self._observer.on_process_frame(data)
+
         if isinstance(frame, StartFrame):
             await self.__start(frame)
         elif isinstance(frame, StartInterruptionFrame):
@@ -314,18 +597,33 @@ class FrameProcessor(BaseObject):
             await self.__resume(frame)
 
     async def push_error(self, error: ErrorFrame):
+        """Push an error frame upstream.
+
+        Args:
+            error: The error frame to push.
+        """
+        if not error.processor:
+            error.processor = self
         await self.push_frame(error, FrameDirection.UPSTREAM)
 
     async def push_frame(self, frame: Frame, direction: FrameDirection = FrameDirection.DOWNSTREAM):
+        """Push a frame to the next processor in the pipeline.
+
+        Args:
+            frame: The frame to push.
+            direction: The direction to push the frame.
+        """
         if not self._check_started(frame):
             return
 
-        if isinstance(frame, SystemFrame):
-            await self.__internal_push_frame(frame, direction)
-        else:
-            await self.__push_queue.put((frame, direction))
+        await self.__internal_push_frame(frame, direction)
 
     async def __start(self, frame: StartFrame):
+        """Handle the start frame to initialize processor state.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         self.__started = True
         self._allow_interruptions = frame.allow_interruptions
         self._enable_metrics = frame.enable_metrics
@@ -336,19 +634,32 @@ class FrameProcessor(BaseObject):
             self.logger = logger.bind(call_id=frame.metadata["call_id"])
             self._metrics.set_logger(self.logger)
         self._report_only_initial_ttfb = frame.report_only_initial_ttfb
-        self.__create_input_task()
-        self.__create_push_task()
+        self.__create_process_task()
 
     async def __cancel(self, frame: CancelFrame):
+        """Handle the cancel frame to stop processor operation.
+
+        Args:
+            frame: The cancel frame.
+        """
         self._cancelling = True
-        await self.__cancel_input_task()
-        await self.__cancel_push_task()
+        await self.__cancel_process_task()
 
     async def __pause(self, frame: FrameProcessorPauseFrame | FrameProcessorPauseUrgentFrame):
+        """Handle pause frame to pause processor operation.
+
+        Args:
+            frame: The pause frame.
+        """
         if frame.processor.name == self.name:
             await self.pause_processing_frames()
 
     async def __resume(self, frame: FrameProcessorResumeFrame | FrameProcessorResumeUrgentFrame):
+        """Handle resume frame to resume processor operation.
+
+        Args:
+            frame: The resume frame.
+        """
         if frame.processor.name == self.name:
             await self.resume_processing_frames()
 
@@ -357,29 +668,31 @@ class FrameProcessor(BaseObject):
     #
 
     async def _start_interruption(self):
+        """Start handling an interruption by cancelling current tasks."""
         try:
-            # Cancel the push frame task. This will stop pushing frames downstream.
-            await self.__cancel_push_task()
-
-            # Cancel the input task. This will stop processing queued frames.
-            await self.__cancel_input_task()
+            # Cancel the process task. This will stop processing queued frames.
+            await self.__cancel_process_task()
         except Exception as e:
             self.logger.exception(
                 f"Uncaught exception in {self} when handling _start_interruption: {e}"
             )
             await self.push_error(ErrorFrame(str(e)))
 
-        # Create a new input queue and task.
-        self.__create_input_task()
-
-        # Create a new output queue and task.
-        self.__create_push_task()
+        # Create a new process queue and task.
+        self.__create_process_task()
 
     async def _stop_interruption(self):
+        """Stop handling an interruption."""
         # Nothing to do right now.
         pass
 
     async def __internal_push_frame(self, frame: Frame, direction: FrameDirection):
+        """Internal method to push frames to adjacent processors.
+
+        Args:
+            frame: The frame to push.
+            direction: The direction to push the frame.
+        """
         try:
             timestamp = self._clock.get_time() if self._clock else 0
             if direction == FrameDirection.DOWNSTREAM and self._next:
@@ -415,60 +728,104 @@ class FrameProcessor(BaseObject):
             await self.push_error(ErrorFrame(str(e)))
 
     def _check_started(self, frame: Frame):
+        """Check if the processor has been started.
+
+        Args:
+            frame: The frame being processed.
+
+        Returns:
+            True if the processor has been started.
+        """
         if not self.__started:
             logger.error(f"{self} Trying to process {frame} but StartFrame not received yet")
         return self.__started
 
     def __create_input_task(self):
+        """Create the frame input processing task."""
+        if self._enable_direct_mode:
+            return
+
         if not self.__input_frame_task:
-            self.__should_block_frames = False
-            if not self.__input_event:
-                self.__input_event = WatchdogEvent(self.task_manager)
-            self.__input_event.clear()
-            self.__input_queue = WatchdogQueue(self.task_manager)
+            self.__input_event = asyncio.Event()
+            self.__input_queue = FrameProcessorQueue()
             self.__input_frame_task = self.create_task(self.__input_frame_task_handler())
 
     async def __cancel_input_task(self):
+        """Cancel the frame input processing task."""
         if self.__input_frame_task:
             await self.cancel_task(self.__input_frame_task)
             self.__input_frame_task = None
 
+    def __create_process_task(self):
+        """Create the non-system frame processing task."""
+        if self._enable_direct_mode:
+            return
+
+        if not self.__process_frame_task:
+            self.__should_block_frames = False
+            self.__process_event = asyncio.Event()
+            self.__process_queue = asyncio.Queue()
+            self.__process_frame_task = self.create_task(self.__process_frame_task_handler())
+
+    async def __cancel_process_task(self):
+        """Cancel the non-system frame processing task."""
+        if self.__process_frame_task:
+            await self.cancel_task(self.__process_frame_task)
+            self.__process_frame_task = None
+
+    async def __process_frame(
+        self, frame: Frame, direction: FrameDirection, callback: Optional[FrameCallback]
+    ):
+        try:
+            # Process the frame.
+            await self.process_frame(frame, direction)
+            # If this frame has an associated callback, call it now.
+            if callback:
+                await callback(self, frame, direction)
+        except Exception as e:
+            logger.exception(f"{self}: error processing frame: {e}")
+            await self.push_error(ErrorFrame(str(e)))
+
     async def __input_frame_task_handler(self):
-        """Handle frames from the input queue."""
-        my_queue = self.__input_queue
+        """Handle frames from the input queue.
+
+        It only processes system frames. Other frames are queue for another task
+        to execute.
+
+        """
         while True:
-            if self.__should_block_frames and self.__input_event:
-                logger.trace(f"{self}: frame processing paused")
+            if self.__should_block_system_frames and self.__input_event:
+                logger.trace(f"{self}: system frame processing paused")
                 await self.__input_event.wait()
                 self.__input_event.clear()
+                self.__should_block_system_frames = False
+                logger.trace(f"{self}: system frame processing resumed")
+
+            (frame, direction, callback) = await self.__input_queue.get()
+
+            if isinstance(frame, SystemFrame):
+                await self.__process_frame(frame, direction, callback)
+            elif self.__process_queue:
+                await self.__process_queue.put((frame, direction, callback))
+            else:
+                raise RuntimeError(
+                    f"{self}: __process_queue is None when processing frame {frame.name}"
+                )
+
+            self.__input_queue.task_done()
+
+    async def __process_frame_task_handler(self):
+        """Handle non-system frames from the process queue."""
+        while True:
+            if self.__should_block_frames and self.__process_event:
+                logger.trace(f"{self}: frame processing paused")
+                await self.__process_event.wait()
+                self.__process_event.clear()
                 self.__should_block_frames = False
                 logger.trace(f"{self}: frame processing resumed")
 
-            (frame, direction, callback) = await my_queue.get()
-            try:
-                # Process the frame.
-                await self.process_frame(frame, direction)
-                # If this frame has an associated callback, call it now.
-                if callback:
-                    await callback(self, frame, direction)
-            except Exception as e:
-                self.logger.exception(f"{self}: error processing frame: {e}")
-                await self.push_error(ErrorFrame(str(e)))
-            finally:
-                my_queue.task_done()
-
-    def __create_push_task(self):
-        if not self.__push_frame_task:
-            self.__push_queue = WatchdogQueue(self.task_manager)
-            self.__push_frame_task = self.create_task(self.__push_frame_task_handler())
-
-    async def __cancel_push_task(self):
-        if self.__push_frame_task:
-            await self.cancel_task(self.__push_frame_task)
-            self.__push_frame_task = None
-
-    async def __push_frame_task_handler(self):
-        while True:
-            (frame, direction) = await self.__push_queue.get()
-            await self.__internal_push_frame(frame, direction)
-            self.__push_queue.task_done()
+            (frame, direction, callback) = await self.__process_queue.get()
+
+            await self.__process_frame(frame, direction, callback)
+
+            self.__process_queue.task_done()