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

pipecat/processors/filters/stt_mute_filter.py

@@ -32,6 +32,8 @@ from pipecat.frames.frames import (
     TranscriptionFrame,
     UserStartedSpeakingFrame,
     UserStoppedSpeakingFrame,
+    VADUserStartedSpeakingFrame,
+    VADUserStoppedSpeakingFrame,
 )
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
@@ -39,12 +41,17 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 class STTMuteStrategy(Enum):
     """Strategies determining when STT should be muted.
 
-    Attributes:
-        FIRST_SPEECH: Mute only during first detected bot speech
-        MUTE_UNTIL_FIRST_BOT_COMPLETE: Start muted and remain muted until first bot speech completes
-        FUNCTION_CALL: Mute during function calls
-        ALWAYS: Mute during all bot speech
-        CUSTOM: Allow custom logic via callback
+    Each strategy defines different conditions under which speech-to-text
+    processing should be temporarily disabled to prevent unwanted audio
+    processing during specific conversation states.
+
+    Parameters:
+        FIRST_SPEECH: Mute STT until the first bot speech is detected.
+        MUTE_UNTIL_FIRST_BOT_COMPLETE: Mute STT until the first bot completes speaking,
+        regardless of whether it is the first speech.
+        FUNCTION_CALL: Mute STT during function calls to prevent interruptions.
+        ALWAYS: Always mute STT when the bot is speaking.
+        CUSTOM: Use a custom callback to determine muting logic dynamically.
     """
 
     FIRST_SPEECH = "first_speech"
@@ -58,10 +65,15 @@ class STTMuteStrategy(Enum):
 class STTMuteConfig:
     """Configuration for STT muting behavior.
 
-    Args:
-        strategies: Set of muting strategies to apply
+    Defines which muting strategies to apply and provides optional custom
+    callback for advanced muting logic. Multiple strategies can be combined
+    to create sophisticated muting behavior.
+
+    Parameters:
+        strategies: Set of muting strategies to apply simultaneously.
         should_mute_callback: Optional callback for custom muting logic.
-            Only required when using STTMuteStrategy.CUSTOM
+            Only required when using STTMuteStrategy.CUSTOM. Called with
+            the STTMuteFilter instance to determine muting state.
 
     Note:
         MUTE_UNTIL_FIRST_BOT_COMPLETE and FIRST_SPEECH strategies should not be used together
@@ -69,10 +81,14 @@ class STTMuteConfig:
     """
 
     strategies: set[STTMuteStrategy]
-    # Optional callback for custom muting logic
     should_mute_callback: Optional[Callable[["STTMuteFilter"], Awaitable[bool]]] = None
 
     def __post_init__(self):
+        """Validate configuration after initialization.
+
+        Raises:
+            ValueError: If incompatible strategies are used together.
+        """
         if (
             STTMuteStrategy.MUTE_UNTIL_FIRST_BOT_COMPLETE in self.strategies
             and STTMuteStrategy.FIRST_SPEECH in self.strategies
@@ -86,15 +102,18 @@ class STTMuteFilter(FrameProcessor):
     """A processor that handles STT muting and interruption control.
 
     This processor combines STT muting and interruption control as a coordinated
-    feature. When STT is muted, interruptions are automatically disabled.
-
-    Args:
-        config: Configuration specifying muting strategies
-        stt_service: STT service instance (deprecated, will be removed in future version)
-        **kwargs: Additional arguments passed to parent class
+    feature. When STT is muted, interruptions are automatically disabled by
+    suppressing VAD-related frames. This prevents unwanted speech detection
+    during bot speech, function calls, or other specified conditions.
     """
 
     def __init__(self, *, config: STTMuteConfig, **kwargs):
+        """Initialize the STT mute filter.
+
+        Args:
+            config: Configuration specifying muting strategies and behavior.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
         self._config = config
         self._first_speech_handled = False
@@ -105,18 +124,23 @@ class STTMuteFilter(FrameProcessor):
 
     @property
     def is_muted(self) -> bool:
-        """Returns whether STT is currently muted."""
+        """Check if STT is currently muted.
+
+        Returns:
+            True if STT is currently muted and audio frames are being suppressed.
+        """
         return self._is_muted
 
     async def _handle_mute_state(self, should_mute: bool):
-        """Handles both STT muting and interruption control."""
+        """Handle STT muting and interruption control state changes."""
         if should_mute != self.is_muted:
             self.logger.debug(f"STTMuteFilter {'muting' if should_mute else 'unmuting'}")
             self._is_muted = should_mute
-            await self.push_frame(STTMuteFrame(mute=should_mute))
+            await self.push_frame(STTMuteFrame(mute=should_mute), FrameDirection.UPSTREAM)
+            await self.push_frame(STTMuteFrame(mute=should_mute), FrameDirection.DOWNSTREAM)
 
     async def _should_mute(self) -> bool:
-        """Determines if STT should be muted based on current state and strategy."""
+        """Determine if STT should be muted based on current state and strategies."""
         for strategy in self._config.strategies:
             match strategy:
                 case STTMuteStrategy.FUNCTION_CALL:
@@ -145,7 +169,16 @@ class STTMuteFilter(FrameProcessor):
         return False
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
-        """Processes incoming frames and manages muting state."""
+        """Process incoming frames and manage muting state.
+
+        Monitors conversation state through frame types and applies muting
+        strategies accordingly. Suppresses VAD-related frames when muted
+        while allowing other frames to pass through.
+
+        Args:
+            frame: The incoming frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         # Determine if we need to change mute state based on frame type
@@ -181,6 +214,8 @@ class STTMuteFilter(FrameProcessor):
         suppression_types = (
             StartInterruptionFrame,
             StopInterruptionFrame,
+            VADUserStartedSpeakingFrame,
+            VADUserStoppedSpeakingFrame,
             UserStartedSpeakingFrame,
             UserStoppedSpeakingFrame,
             InterimTranscriptionFrame,

pipecat/processors/filters/wake_check_filter.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Wake phrase detection filter for Pipecat transcription processing.
+
+This module provides a frame processor that filters transcription frames,
+only allowing them through after wake phrases have been detected. Includes
+keepalive functionality to maintain conversation flow after wake detection.
+"""
+
 import re
 import time
 from enum import Enum
@@ -16,23 +23,53 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class WakeCheckFilter(FrameProcessor):
-    """This filter looks for wake phrases in the transcription frames and only passes through frames
-    after a wake phrase has been detected. It also has a keepalive timeout to allow for a brief
-    period of continued conversation after a wake phrase has been detected.
+    """Frame processor that filters transcription frames based on wake phrase detection.
+
+    This filter monitors transcription frames for configured wake phrases and only
+    passes frames through after a wake phrase has been detected. Maintains a
+    keepalive timeout to allow continued conversation after wake detection.
     """
 
     class WakeState(Enum):
+        """Enumeration of wake detection states.
+
+        Parameters:
+            IDLE: No wake phrase detected, filtering active.
+            AWAKE: Wake phrase detected, allowing frames through.
+        """
+
         IDLE = 1
         AWAKE = 2
 
     class ParticipantState:
+        """State tracking for individual participants.
+
+        Parameters:
+            participant_id: Unique identifier for the participant.
+            state: Current wake state (IDLE or AWAKE).
+            wake_timer: Timestamp of last wake phrase detection.
+            accumulator: Accumulated text for wake phrase matching.
+        """
+
         def __init__(self, participant_id: str):
+            """Initialize participant state.
+
+            Args:
+                participant_id: Unique identifier for the participant.
+            """
             self.participant_id = participant_id
             self.state = WakeCheckFilter.WakeState.IDLE
             self.wake_timer = 0.0
             self.accumulator = ""
 
     def __init__(self, wake_phrases: List[str], keepalive_timeout: float = 3):
+        """Initialize the wake phrase filter.
+
+        Args:
+            wake_phrases: List of wake phrases to detect in transcriptions.
+            keepalive_timeout: Duration in seconds to keep passing frames after
+                wake detection. Defaults to 3 seconds.
+        """
         super().__init__()
         self._participant_states = {}
         self._keepalive_timeout = keepalive_timeout
@@ -44,6 +81,12 @@ class WakeCheckFilter(FrameProcessor):
             self._wake_patterns.append(pattern)
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames, filtering transcriptions based on wake detection.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         try:

pipecat/processors/filters/wake_notifier_filter.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Wake notifier filter for conditional frame-based notifications."""
+
 from typing import Awaitable, Callable, Tuple, Type
 
 from pipecat.frames.frames import Frame
@@ -12,10 +14,11 @@ from pipecat.sync.base_notifier import BaseNotifier
 
 
 class WakeNotifierFilter(FrameProcessor):
-    """This processor expects a list of frame types and will execute a given
-    callback predicate when a frame of any of those type is being processed. If
-    the callback returns true the notifier will be notified.
+    """Frame processor that conditionally triggers notifications based on frame types and filters.
 
+    This processor monitors frames of specified types and executes a callback predicate
+    when such frames are processed. If the callback returns True, the associated
+    notifier is triggered, allowing for conditional wake-up or notification scenarios.
     """
 
     def __init__(
@@ -26,12 +29,27 @@ class WakeNotifierFilter(FrameProcessor):
         filter: Callable[[Frame], Awaitable[bool]],
         **kwargs,
     ):
+        """Initialize the wake notifier filter.
+
+        Args:
+            notifier: The notifier to trigger when conditions are met.
+            types: Tuple of frame types to monitor for potential notifications.
+            filter: Async callback that determines whether to trigger notification.
+                   Should return True to trigger notification, False otherwise.
+            **kwargs: Additional arguments passed to parent FrameProcessor.
+        """
         super().__init__(**kwargs)
         self._notifier = notifier
         self._types = types
         self._filter = filter
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames and conditionally trigger notifications.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, self._types) and await self._filter(frame):