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

pipecat/processors/audio/audio_buffer_processor.py

@@ -4,12 +4,18 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Audio buffer processor for managing and synchronizing audio streams.
+
+This module provides an AudioBufferProcessor that handles buffering and synchronization
+of audio from both user input and bot output sources, with support for various audio
+configurations and event-driven processing.
+"""
+
 import time
 from typing import Optional
 
-from pipecat.audio.utils import create_default_resampler, interleave_stereo_audio, mix_audio
+from pipecat.audio.utils import create_stream_resampler, interleave_stereo_audio, mix_audio
 from pipecat.frames.frames import (
-    AudioRawFrame,
     BotStartedSpeakingFrame,
     BotStoppedSpeakingFrame,
     CancelFrame,
@@ -32,23 +38,19 @@ class AudioBufferProcessor(FrameProcessor):
     including sample rate conversion and mono/stereo output.
 
     Events:
-        on_audio_data: Triggered when buffer_size is reached, providing merged audio
-        on_track_audio_data: Triggered when buffer_size is reached, providing separate tracks
-        on_user_turn_audio_data: Triggered when user turn has ended, providing that user turn's audio
-        on_bot_turn_audio_data: Triggered when bot turn has ended, providing that bot turn's audio
 
-    Args:
-        sample_rate (Optional[int]): Desired output sample rate. If None, uses source rate
-        num_channels (int): Number of channels (1 for mono, 2 for stereo). Defaults to 1
-        buffer_size (int): Size of buffer before triggering events. 0 for no buffering
-        enable_turn_audio (bool): Whether turn audio event handlers should be triggered
+    - on_audio_data: Triggered when buffer_size is reached, providing merged audio
+    - on_track_audio_data: Triggered when buffer_size is reached, providing separate tracks
+    - on_user_turn_audio_data: Triggered when user turn has ended, providing that user turn's audio
+    - on_bot_turn_audio_data: Triggered when bot turn has ended, providing that bot turn's audio
 
     Audio handling:
-        - Mono output (num_channels=1): User and bot audio are mixed
-        - Stereo output (num_channels=2): User audio on left, bot audio on right
-        - Automatic resampling of incoming audio to match desired sample_rate
-        - Silence insertion for non-continuous audio streams
-        - Buffer synchronization between user and bot audio
+
+    - Mono output (num_channels=1): User and bot audio are mixed
+    - Stereo output (num_channels=2): User audio on left, bot audio on right
+    - Automatic resampling of incoming audio to match desired sample_rate
+    - Silence insertion for non-continuous audio streams
+    - Buffer synchronization between user and bot audio
     """
 
     def __init__(
@@ -61,6 +63,21 @@ class AudioBufferProcessor(FrameProcessor):
         enable_turn_audio: bool = False,
         **kwargs,
     ):
+        """Initialize the audio buffer processor.
+
+        Args:
+            sample_rate: Desired output sample rate. If None, uses source rate.
+            num_channels: Number of channels (1 for mono, 2 for stereo). Defaults to 1.
+            buffer_size: Size of buffer before triggering events. 0 for no buffering.
+            user_continuous_stream: Controls whether user audio is treated as a continuous
+                stream for buffering purposes.
+
+                .. deprecated:: 0.0.72
+                    This parameter no longer has any effect and will be removed in a future version.
+
+            enable_turn_audio: Whether turn audio event handlers should be triggered.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
         self._init_sample_rate = sample_rate
         self._sample_rate = 0
@@ -93,7 +110,8 @@ class AudioBufferProcessor(FrameProcessor):
 
         self._recording = False
 
-        self._resampler = create_default_resampler()
+        self._input_resampler = create_stream_resampler()
+        self._output_resampler = create_stream_resampler()
 
         self._register_event_handler("on_audio_data")
         self._register_event_handler("on_track_audio_data")
@@ -105,7 +123,7 @@ class AudioBufferProcessor(FrameProcessor):
         """Current sample rate of the audio processor.
 
         Returns:
-            int: The sample rate in Hz
+            The sample rate in Hz.
         """
         return self._sample_rate
 
@@ -114,7 +132,7 @@ class AudioBufferProcessor(FrameProcessor):
         """Number of channels in the audio output.
 
         Returns:
-            int: Number of channels (1 for mono, 2 for stereo)
+            Number of channels (1 for mono, 2 for stereo).
         """
         return self._num_channels
 
@@ -122,7 +140,7 @@ class AudioBufferProcessor(FrameProcessor):
         """Check if both user and bot audio buffers contain data.
 
         Returns:
-            bool: True if both buffers contain audio data
+            True if both buffers contain audio data.
         """
         return self._buffer_has_audio(self._user_audio_buffer) and self._buffer_has_audio(
             self._bot_audio_buffer
@@ -135,7 +153,7 @@ class AudioBufferProcessor(FrameProcessor):
         on the left channel and bot audio on the right channel.
 
         Returns:
-            bytes: Mixed audio data
+            Mixed audio data as bytes.
         """
         if self._num_channels == 1:
             return mix_audio(bytes(self._user_audio_buffer), bytes(self._bot_audio_buffer))
@@ -160,10 +178,16 @@ class AudioBufferProcessor(FrameProcessor):
         Calls audio handlers with any remaining buffered audio before stopping.
         """
         await self._call_on_audio_data_handler()
+        self._reset_recording()
         self._recording = False
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
-        """Process incoming audio frames and manage audio buffers."""
+        """Process incoming audio frames and manage audio buffers.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         # Update output sample rate if necessary.
@@ -172,8 +196,6 @@ class AudioBufferProcessor(FrameProcessor):
 
         if self._recording:
             await self._process_recording(frame)
-            if self._enable_turn_audio:
-                await self._process_turn_recording(frame)
 
         if isinstance(frame, (CancelFrame, EndFrame)):
             await self.stop_recording()
@@ -181,16 +203,19 @@ class AudioBufferProcessor(FrameProcessor):
         await self.push_frame(frame, direction)
 
     def _update_sample_rate(self, frame: StartFrame):
+        """Update the sample rate from the start frame."""
         self._sample_rate = self._init_sample_rate or frame.audio_out_sample_rate
         self._audio_buffer_size_1s = self._sample_rate * 2
 
     async def _process_recording(self, frame: Frame):
+        """Process audio frames for recording."""
+        resampled = None
         if isinstance(frame, InputAudioRawFrame):
             # Add silence if we need to.
             silence = self._compute_silence(self._last_user_frame_at)
             self._user_audio_buffer.extend(silence)
             # Add user audio.
-            resampled = await self._resample_audio(frame)
+            resampled = await self._resample_input_audio(frame)
             self._user_audio_buffer.extend(resampled)
             # Save time of frame so we can compute silence.
             self._last_user_frame_at = time.time()
@@ -199,15 +224,21 @@ class AudioBufferProcessor(FrameProcessor):
             silence = self._compute_silence(self._last_bot_frame_at)
             self._bot_audio_buffer.extend(silence)
             # Add bot audio.
-            resampled = await self._resample_audio(frame)
+            resampled = await self._resample_output_audio(frame)
             self._bot_audio_buffer.extend(resampled)
             # Save time of frame so we can compute silence.
             self._last_bot_frame_at = time.time()
 
         if self._buffer_size > 0 and len(self._user_audio_buffer) > self._buffer_size:
             await self._call_on_audio_data_handler()
+            self._reset_recording()
+
+        # Process turn recording with preprocessed data.
+        if self._enable_turn_audio:
+            await self._process_turn_recording(frame, resampled)
 
-    async def _process_turn_recording(self, frame: Frame):
+    async def _process_turn_recording(self, frame: Frame, resampled_audio: Optional[bytes] = None):
+        """Process frames for turn-based audio recording."""
         if isinstance(frame, UserStartedSpeakingFrame):
             self._user_speaking = True
         elif isinstance(frame, UserStoppedSpeakingFrame):
@@ -225,9 +256,8 @@ class AudioBufferProcessor(FrameProcessor):
             self._bot_speaking = False
             self._bot_turn_audio_buffer = bytearray()
 
-        if isinstance(frame, InputAudioRawFrame):
-            resampled = await self._resample_audio(frame)
-            self._user_turn_audio_buffer += resampled
+        if isinstance(frame, InputAudioRawFrame) and resampled_audio:
+            self._user_turn_audio_buffer.extend(resampled_audio)
             # In the case of the user, we need to keep a short buffer of audio
             # since VAD notification of when the user starts speaking comes
             # later.
@@ -237,11 +267,11 @@ class AudioBufferProcessor(FrameProcessor):
             ):
                 discarded = len(self._user_turn_audio_buffer) - self._audio_buffer_size_1s
                 self._user_turn_audio_buffer = self._user_turn_audio_buffer[discarded:]
-        elif self._bot_speaking and isinstance(frame, OutputAudioRawFrame):
-            resampled = await self._resample_audio(frame)
-            self._bot_turn_audio_buffer += resampled
+        elif self._bot_speaking and isinstance(frame, OutputAudioRawFrame) and resampled_audio:
+            self._bot_turn_audio_buffer.extend(resampled_audio)
 
     async def _call_on_audio_data_handler(self):
+        """Call the audio data event handlers with buffered audio."""
         if not self.has_audio() or not self._recording:
             return
 
@@ -260,26 +290,37 @@ class AudioBufferProcessor(FrameProcessor):
             self._num_channels,
         )
 
-        self._reset_audio_buffers()
-
     def _buffer_has_audio(self, buffer: bytearray) -> bool:
+        """Check if a buffer contains audio data."""
         return buffer is not None and len(buffer) > 0
 
     def _reset_recording(self):
+        """Reset recording state and buffers."""
         self._reset_audio_buffers()
         self._last_user_frame_at = time.time()
         self._last_bot_frame_at = time.time()
 
     def _reset_audio_buffers(self):
+        """Reset all audio buffers to empty state."""
         self._user_audio_buffer = bytearray()
         self._bot_audio_buffer = bytearray()
         self._user_turn_audio_buffer = bytearray()
         self._bot_turn_audio_buffer = bytearray()
 
-    async def _resample_audio(self, frame: AudioRawFrame) -> bytes:
-        return await self._resampler.resample(frame.audio, frame.sample_rate, self._sample_rate)
+    async def _resample_input_audio(self, frame: InputAudioRawFrame) -> bytes:
+        """Resample audio frame to the target sample rate."""
+        return await self._input_resampler.resample(
+            frame.audio, frame.sample_rate, self._sample_rate
+        )
+
+    async def _resample_output_audio(self, frame: OutputAudioRawFrame) -> bytes:
+        """Resample audio frame to the target sample rate."""
+        return await self._output_resampler.resample(
+            frame.audio, frame.sample_rate, self._sample_rate
+        )
 
     def _compute_silence(self, from_time: float) -> bytes:
+        """Compute silence to insert based on time gap."""
         quiet_time = time.time() - from_time
         # We should get audio frames very frequently. We introduce silence only
         # if there's a big enough gap of 1s.

pipecat/processors/consumer_processor.py

@@ -4,21 +4,22 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Consumer processor for consuming frames from ProducerProcessor queues."""
+
 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
-from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue
 
 
 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.
+    """Frame processor that consumes frames from a ProducerProcessor's queue.
 
+    This processor passes through frames normally while also consuming frames
+    from a ProducerProcessor's queue. When frames are received from the producer
+    queue, they are optionally transformed and pushed in the specified direction.
     """
 
     def __init__(
@@ -29,6 +30,14 @@ class ConsumerProcessor(FrameProcessor):
         direction: FrameDirection = FrameDirection.DOWNSTREAM,
         **kwargs,
     ):
+        """Initialize the consumer processor.
+
+        Args:
+            producer: The producer processor to consume frames from.
+            transformer: Function to transform frames before pushing. Defaults to identity_transformer.
+            direction: Direction to push consumed frames. Defaults to DOWNSTREAM.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
         self._transformer = transformer
         self._direction = direction
@@ -36,6 +45,12 @@ class ConsumerProcessor(FrameProcessor):
         self._consumer_task: Optional[asyncio.Task] = None
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and handle lifecycle events.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction the frame is traveling.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, StartFrame):
@@ -48,19 +63,23 @@ class ConsumerProcessor(FrameProcessor):
         await self.push_frame(frame, direction)
 
     async def _start(self, _: StartFrame):
+        """Start the consumer task and register with the producer."""
         if not self._consumer_task:
-            self._queue: WatchdogQueue = self._producer.add_consumer()
+            self._queue = self._producer.add_consumer()
             self._consumer_task = self.create_task(self._consumer_task_handler())
 
     async def _stop(self, _: EndFrame):
+        """Stop the consumer task."""
         if self._consumer_task:
             await self.cancel_task(self._consumer_task)
 
     async def _cancel(self, _: CancelFrame):
+        """Cancel the consumer task."""
         if self._consumer_task:
             await self.cancel_task(self._consumer_task)
 
     async def _consumer_task_handler(self):
+        """Handle consuming frames from the producer queue."""
         while True:
             frame = await self._queue.get()
             new_frame = await self._transformer(frame)

pipecat/processors/filters/frame_filter.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Frame filtering processor for the Pipecat framework."""
+
 from typing import Tuple, Type
 
 from pipecat.frames.frames import EndFrame, Frame, SystemFrame
@@ -11,7 +13,21 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class FrameFilter(FrameProcessor):
+    """A frame processor that filters frames based on their types.
+
+    This processor acts as a selective gate in the pipeline, allowing only
+    frames of specified types to pass through. System and end frames are
+    automatically allowed to pass through to maintain pipeline integrity.
+    """
+
     def __init__(self, types: Tuple[Type[Frame], ...]):
+        """Initialize the frame filter.
+
+        Args:
+            types: Tuple of frame types that should be allowed to pass through
+                   the filter. All other frame types (except SystemFrame and
+                   EndFrame) will be blocked.
+        """
         super().__init__()
         self._types = types
 
@@ -20,12 +36,19 @@ class FrameFilter(FrameProcessor):
     #
 
     def _should_passthrough_frame(self, frame):
+        """Determine if a frame should pass through the filter."""
         if isinstance(frame, self._types):
             return True
 
         return isinstance(frame, (EndFrame, SystemFrame))
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process an incoming frame and conditionally pass it through.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if self._should_passthrough_frame(frame):

pipecat/processors/filters/function_filter.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Function-based frame filtering for Pipecat pipelines.
+
+This module provides a processor that filters frames based on a custom function,
+allowing for flexible frame filtering logic in processing pipelines.
+"""
+
 from typing import Awaitable, Callable
 
 from pipecat.frames.frames import EndFrame, Frame, SystemFrame
@@ -11,11 +17,26 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class FunctionFilter(FrameProcessor):
+    """A frame processor that filters frames using a custom function.
+
+    This processor allows frames to pass through based on the result of a
+    user-provided filter function. System and end frames always pass through
+    regardless of the filter result.
+    """
+
     def __init__(
         self,
         filter: Callable[[Frame], Awaitable[bool]],
         direction: FrameDirection = FrameDirection.DOWNSTREAM,
     ):
+        """Initialize the function filter.
+
+        Args:
+            filter: An async function that takes a Frame and returns True if the
+                frame should pass through, False otherwise.
+            direction: The direction to apply filtering. Only frames moving in
+                this direction will be filtered. Defaults to DOWNSTREAM.
+        """
         super().__init__()
         self._filter = filter
         self._direction = direction
@@ -27,9 +48,18 @@ class FunctionFilter(FrameProcessor):
     # Ignore system frames, end frames and frames that are not following the
     # direction of this gate
     def _should_passthrough_frame(self, frame, direction):
+        """Check if a frame should pass through without filtering."""
+        # Ignore system frames, end frames and frames that are not following the
+        # direction of this gate
         return isinstance(frame, (SystemFrame, EndFrame)) or direction != self._direction
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process a frame through the filter.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction the frame is moving in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         passthrough = self._should_passthrough_frame(frame, direction)

pipecat/processors/filters/identity_filter.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Identity filter for transparent frame passthrough.
+
+This module provides a simple passthrough filter that forwards all frames
+without modification, useful for testing and pipeline composition.
+"""
+
 from pipecat.frames.frames import Frame
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
@@ -14,10 +20,14 @@ class IdentityFilter(FrameProcessor):
     This filter acts as a transparent passthrough, allowing all frames to flow
     through unchanged. It can be useful when testing `ParallelPipeline` to
     create pipelines that pass through frames (no frames should be repeated).
-
     """
 
     def __init__(self, **kwargs):
+        """Initialize the identity filter.
+
+        Args:
+            **kwargs: Additional arguments passed to the parent FrameProcessor.
+        """
         super().__init__(**kwargs)
 
     #
@@ -25,6 +35,11 @@ class IdentityFilter(FrameProcessor):
     #
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
-        """Process an incoming frame by passing it through unchanged."""
+        """Process an incoming frame by passing it through unchanged.
+
+        Args:
+            frame: The frame to process and forward.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
         await self.push_frame(frame, direction)

pipecat/processors/filters/null_filter.py

@@ -4,14 +4,31 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Null filter processor for blocking frame transmission.
+
+This module provides a frame processor that blocks all frames except
+system and end frames, useful for testing or temporarily stopping
+frame flow in a pipeline.
+"""
+
 from pipecat.frames.frames import EndFrame, Frame, SystemFrame
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class NullFilter(FrameProcessor):
-    """This filter doesn't allow passing any frames up or downstream."""
+    """A filter that blocks all frames except system and end frames.
+
+    This processor acts as a null filter, preventing frames from passing
+    through the pipeline while still allowing essential system and end
+    frames to maintain proper pipeline operation.
+    """
 
     def __init__(self, **kwargs):
+        """Initialize the null filter.
+
+        Args:
+            **kwargs: Additional arguments passed to parent FrameProcessor.
+        """
         super().__init__(**kwargs)
 
     #
@@ -19,6 +36,12 @@ class NullFilter(FrameProcessor):
     #
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames, only allowing system and end frames through.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, (SystemFrame, EndFrame)):