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

pipecat/transports/base_transport.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base transport classes for Pipecat.
+
+This module provides the foundation for transport implementations including
+parameter configuration and abstract base classes for input/output transport
+functionality.
+"""
+
 from abc import abstractmethod
 from typing import List, Mapping, Optional
 
@@ -18,6 +25,95 @@ from pipecat.utils.base_object import BaseObject
 
 
 class TransportParams(BaseModel):
+    """Configuration parameters for transport implementations.
+
+    Parameters:
+        camera_in_enabled: Enable camera input (deprecated, use video_in_enabled).
+
+            .. deprecated:: 0.0.66
+               The `camera_in_enabled` parameter is deprecated, use
+               `video_in_enabled` instead.
+
+        camera_out_enabled: Enable camera output (deprecated, use video_out_enabled).
+
+            .. deprecated:: 0.0.66
+               The `camera_out_enabled` parameter is deprecated, use
+               `video_out_enabled` instead.
+
+        camera_out_is_live: Enable real-time camera output (deprecated).
+
+            .. deprecated:: 0.0.66
+               The `camera_out_is_live` parameter is deprecated, use
+               `video_out_is_live` instead.
+
+        camera_out_width: Camera output width in pixels (deprecated).
+
+            .. deprecated:: 0.0.66
+               The `camera_out_width` parameter is deprecated, use
+               `video_out_width` instead.
+
+        camera_out_height: Camera output height in pixels (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_height` parameter is deprecated, use
+                `video_out_height` instead.
+
+        camera_out_bitrate: Camera output bitrate in bits per second (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_bitrate` parameter is deprecated, use
+                `video_out_bitrate` instead.
+
+        camera_out_framerate: Camera output frame rate in FPS (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_framerate` parameter is deprecated, use
+                `video_out_framerate` instead.
+
+        camera_out_color_format: Camera output color format string (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_color_format` parameter is deprecated, use
+                `video_out_color_format` instead.
+
+        audio_out_enabled: Enable audio output streaming.
+        audio_out_sample_rate: Output audio sample rate in Hz.
+        audio_out_channels: Number of output audio channels.
+        audio_out_bitrate: Output audio bitrate in bits per second.
+        audio_out_10ms_chunks: Number of 10ms chunks to buffer for output.
+        audio_out_mixer: Audio mixer instance or destination mapping.
+        audio_out_destinations: List of audio output destination identifiers.
+        audio_in_enabled: Enable audio input streaming.
+        audio_in_sample_rate: Input audio sample rate in Hz.
+        audio_in_channels: Number of input audio channels.
+        audio_in_filter: Audio filter to apply to input audio.
+        audio_in_stream_on_start: Start audio streaming immediately on transport start.
+        audio_in_passthrough: Pass through input audio frames downstream.
+        video_in_enabled: Enable video input streaming.
+        video_out_enabled: Enable video output streaming.
+        video_out_is_live: Enable real-time video output streaming.
+        video_out_width: Video output width in pixels.
+        video_out_height: Video output height in pixels.
+        video_out_bitrate: Video output bitrate in bits per second.
+        video_out_framerate: Video output frame rate in FPS.
+        video_out_color_format: Video output color format string.
+        video_out_destinations: List of video output destination identifiers.
+        vad_enabled: Enable Voice Activity Detection (deprecated).
+
+            .. deprecated:: 0.0.66
+               The `vad_enabled` parameter is deprecated, use `audio_in_enabled`
+               and `TransportParams.vad_analyzer` instead.
+
+        vad_audio_passthrough: Enable VAD audio passthrough (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `vad_audio_passthrough` parameter is deprecated, use `audio_in_passthrough`
+                instead.
+
+        vad_analyzer: Voice Activity Detection analyzer instance.
+        turn_analyzer: Turn-taking analyzer instance for conversation management.
+    """
+
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
     camera_in_enabled: bool = False
@@ -57,6 +153,12 @@ class TransportParams(BaseModel):
 
 
 class BaseTransport(BaseObject):
+    """Base class for transport implementations.
+
+    Provides the foundation for transport classes that handle media streaming,
+    including input and output frame processors for audio and video data.
+    """
+
     def __init__(
         self,
         *,
@@ -64,14 +166,31 @@ class BaseTransport(BaseObject):
         input_name: Optional[str] = None,
         output_name: Optional[str] = None,
     ):
+        """Initialize the base transport.
+
+        Args:
+            name: Optional name for the transport instance.
+            input_name: Optional name for the input processor.
+            output_name: Optional name for the output processor.
+        """
         super().__init__(name=name)
         self._input_name = input_name
         self._output_name = output_name
 
     @abstractmethod
     def input(self) -> FrameProcessor:
+        """Get the input frame processor for this transport.
+
+        Returns:
+            The frame processor that handles incoming frames.
+        """
         pass
 
     @abstractmethod
     def output(self) -> FrameProcessor:
+        """Get the output frame processor for this transport.
+
+        Returns:
+            The frame processor that handles outgoing frames.
+        """
         pass

pipecat/transports/local/audio.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Local audio transport implementation for Pipecat.
+
+This module provides a local audio transport that uses PyAudio for real-time
+audio input and output through the system's default audio devices.
+"""
+
 import asyncio
 from concurrent.futures import ThreadPoolExecutor
 from typing import Optional
@@ -27,14 +33,33 @@ except ModuleNotFoundError as e:
 
 
 class LocalAudioTransportParams(TransportParams):
+    """Configuration parameters for local audio transport.
+
+    Parameters:
+        input_device_index: PyAudio device index for audio input. If None, uses default.
+        output_device_index: PyAudio device index for audio output. If None, uses default.
+    """
+
     input_device_index: Optional[int] = None
     output_device_index: Optional[int] = None
 
 
 class LocalAudioInputTransport(BaseInputTransport):
+    """Local audio input transport using PyAudio.
+
+    Captures audio from the system's audio input device and converts it to
+    InputAudioRawFrame objects for processing in the pipeline.
+    """
+
     _params: LocalAudioTransportParams
 
     def __init__(self, py_audio: pyaudio.PyAudio, params: LocalAudioTransportParams):
+        """Initialize the local audio input transport.
+
+        Args:
+            py_audio: PyAudio instance for audio device management.
+            params: Transport configuration parameters.
+        """
         super().__init__(params)
         self._py_audio = py_audio
 
@@ -42,6 +67,11 @@ class LocalAudioInputTransport(BaseInputTransport):
         self._sample_rate = 0
 
     async def start(self, frame: StartFrame):
+        """Start the audio input stream.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._in_stream:
@@ -64,6 +94,7 @@ class LocalAudioInputTransport(BaseInputTransport):
         await self.set_transport_ready(frame)
 
     async def cleanup(self):
+        """Stop and cleanup the audio input stream."""
         await super().cleanup()
         if self._in_stream:
             self._in_stream.stop_stream()
@@ -71,6 +102,7 @@ class LocalAudioInputTransport(BaseInputTransport):
             self._in_stream = None
 
     def _audio_in_callback(self, in_data, frame_count, time_info, status):
+        """Callback function for PyAudio input stream."""
         frame = InputAudioRawFrame(
             audio=in_data,
             sample_rate=self._sample_rate,
@@ -83,9 +115,21 @@ class LocalAudioInputTransport(BaseInputTransport):
 
 
 class LocalAudioOutputTransport(BaseOutputTransport):
+    """Local audio output transport using PyAudio.
+
+    Plays audio frames through the system's audio output device by converting
+    OutputAudioRawFrame objects to playable audio data.
+    """
+
     _params: LocalAudioTransportParams
 
     def __init__(self, py_audio: pyaudio.PyAudio, params: LocalAudioTransportParams):
+        """Initialize the local audio output transport.
+
+        Args:
+            py_audio: PyAudio instance for audio device management.
+            params: Transport configuration parameters.
+        """
         super().__init__(params)
         self._py_audio = py_audio
 
@@ -97,6 +141,11 @@ class LocalAudioOutputTransport(BaseOutputTransport):
         self._executor = ThreadPoolExecutor(max_workers=1)
 
     async def start(self, frame: StartFrame):
+        """Start the audio output stream.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._out_stream:
@@ -116,6 +165,7 @@ class LocalAudioOutputTransport(BaseOutputTransport):
         await self.set_transport_ready(frame)
 
     async def cleanup(self):
+        """Stop and cleanup the audio output stream."""
         await super().cleanup()
         if self._out_stream:
             self._out_stream.stop_stream()
@@ -123,6 +173,11 @@ class LocalAudioOutputTransport(BaseOutputTransport):
             self._out_stream = None
 
     async def write_audio_frame(self, frame: OutputAudioRawFrame):
+        """Write an audio frame to the output stream.
+
+        Args:
+            frame: The audio frame to write to the output device.
+        """
         if self._out_stream:
             await self.get_event_loop().run_in_executor(
                 self._executor, self._out_stream.write, frame.audio
@@ -130,7 +185,18 @@ class LocalAudioOutputTransport(BaseOutputTransport):
 
 
 class LocalAudioTransport(BaseTransport):
+    """Complete local audio transport with input and output capabilities.
+
+    Provides a unified interface for local audio I/O using PyAudio, supporting
+    both audio capture and playback through the system's audio devices.
+    """
+
     def __init__(self, params: LocalAudioTransportParams):
+        """Initialize the local audio transport.
+
+        Args:
+            params: Transport configuration parameters.
+        """
         super().__init__()
         self._params = params
         self._pyaudio = pyaudio.PyAudio()
@@ -143,11 +209,21 @@ class LocalAudioTransport(BaseTransport):
     #
 
     def input(self) -> FrameProcessor:
+        """Get the input frame processor for this transport.
+
+        Returns:
+            The audio input transport processor.
+        """
         if not self._input:
             self._input = LocalAudioInputTransport(self._pyaudio, self._params)
         return self._input
 
     def output(self) -> FrameProcessor:
+        """Get the output frame processor for this transport.
+
+        Returns:
+            The audio output transport processor.
+        """
         if not self._output:
             self._output = LocalAudioOutputTransport(self._pyaudio, self._params)
         return self._output

pipecat/transports/local/tk.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Tkinter-based local transport implementation for Pipecat.
+
+This module provides a local transport using Tkinter for video display and
+PyAudio for audio I/O, suitable for desktop applications and testing.
+"""
+
 import asyncio
 import tkinter as tk
 from concurrent.futures import ThreadPoolExecutor
@@ -40,20 +46,44 @@ except ModuleNotFoundError as e:
 
 
 class TkTransportParams(TransportParams):
+    """Configuration parameters for Tkinter transport.
+
+    Parameters:
+        audio_input_device_index: PyAudio device index for audio input. If None, uses default.
+        audio_output_device_index: PyAudio device index for audio output. If None, uses default.
+    """
+
     audio_input_device_index: Optional[int] = None
     audio_output_device_index: Optional[int] = None
 
 
 class TkInputTransport(BaseInputTransport):
+    """Tkinter-based audio input transport.
+
+    Captures audio from the system's audio input device using PyAudio and
+    converts it to InputAudioRawFrame objects for pipeline processing.
+    """
+
     _params: TkTransportParams
 
     def __init__(self, py_audio: pyaudio.PyAudio, params: TkTransportParams):
+        """Initialize the Tkinter input transport.
+
+        Args:
+            py_audio: PyAudio instance for audio device management.
+            params: Transport configuration parameters.
+        """
         super().__init__(params)
         self._py_audio = py_audio
         self._in_stream = None
         self._sample_rate = 0
 
     async def start(self, frame: StartFrame):
+        """Start the audio input stream.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._in_stream:
@@ -76,6 +106,7 @@ class TkInputTransport(BaseInputTransport):
         await self.set_transport_ready(frame)
 
     async def cleanup(self):
+        """Stop and cleanup the audio input stream."""
         await super().cleanup()
         if self._in_stream:
             self._in_stream.stop_stream()
@@ -83,6 +114,7 @@ class TkInputTransport(BaseInputTransport):
             self._in_stream = None
 
     def _audio_in_callback(self, in_data, frame_count, time_info, status):
+        """Callback function for PyAudio input stream."""
         frame = InputAudioRawFrame(
             audio=in_data,
             sample_rate=self._sample_rate,
@@ -95,9 +127,22 @@ class TkInputTransport(BaseInputTransport):
 
 
 class TkOutputTransport(BaseOutputTransport):
+    """Tkinter-based audio and video output transport.
+
+    Plays audio through PyAudio and displays video frames in a Tkinter window,
+    providing a complete multimedia output solution for desktop applications.
+    """
+
     _params: TkTransportParams
 
     def __init__(self, tk_root: tk.Tk, py_audio: pyaudio.PyAudio, params: TkTransportParams):
+        """Initialize the Tkinter output transport.
+
+        Args:
+            tk_root: The root Tkinter window for video display.
+            py_audio: PyAudio instance for audio device management.
+            params: Transport configuration parameters.
+        """
         super().__init__(params)
         self._py_audio = py_audio
         self._out_stream = None
@@ -115,6 +160,11 @@ class TkOutputTransport(BaseOutputTransport):
         self._image_label.pack()
 
     async def start(self, frame: StartFrame):
+        """Start the audio output stream.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._out_stream:
@@ -134,6 +184,7 @@ class TkOutputTransport(BaseOutputTransport):
         await self.set_transport_ready(frame)
 
     async def cleanup(self):
+        """Stop and cleanup the audio output stream."""
         await super().cleanup()
         if self._out_stream:
             self._out_stream.stop_stream()
@@ -141,15 +192,26 @@ class TkOutputTransport(BaseOutputTransport):
             self._out_stream = None
 
     async def write_audio_frame(self, frame: OutputAudioRawFrame):
+        """Write an audio frame to the output stream.
+
+        Args:
+            frame: The audio frame to write to the output device.
+        """
         if self._out_stream:
             await self.get_event_loop().run_in_executor(
                 self._executor, self._out_stream.write, frame.audio
             )
 
     async def write_video_frame(self, frame: OutputImageRawFrame):
+        """Write a video frame to the Tkinter display.
+
+        Args:
+            frame: The video frame to display in the Tkinter window.
+        """
         self.get_event_loop().call_soon(self._write_frame_to_tk, frame)
 
     def _write_frame_to_tk(self, frame: OutputImageRawFrame):
+        """Write frame data to the Tkinter image label."""
         width = frame.size[0]
         height = frame.size[1]
         data = f"P6 {width} {height} 255 ".encode() + frame.image
@@ -162,7 +224,19 @@ class TkOutputTransport(BaseOutputTransport):
 
 
 class TkLocalTransport(BaseTransport):
+    """Complete Tkinter-based local transport with audio and video capabilities.
+
+    Provides a unified interface for local multimedia I/O using Tkinter for video
+    display and PyAudio for audio, suitable for desktop applications and testing.
+    """
+
     def __init__(self, tk_root: tk.Tk, params: TkTransportParams):
+        """Initialize the Tkinter local transport.
+
+        Args:
+            tk_root: The root Tkinter window for video display.
+            params: Transport configuration parameters.
+        """
         super().__init__()
         self._tk_root = tk_root
         self._params = params
@@ -176,11 +250,21 @@ class TkLocalTransport(BaseTransport):
     #
 
     def input(self) -> TkInputTransport:
+        """Get the input frame processor for this transport.
+
+        Returns:
+            The Tkinter input transport processor.
+        """
         if not self._input:
             self._input = TkInputTransport(self._pyaudio, self._params)
         return self._input
 
     def output(self) -> TkOutputTransport:
+        """Get the output frame processor for this transport.
+
+        Returns:
+            The Tkinter output transport processor.
+        """
         if not self._output:
             self._output = TkOutputTransport(self._tk_root, self._pyaudio, self._params)
         return self._output