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

pipecat/services/xtts/tts.py

@@ -4,12 +4,18 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""XTTS text-to-speech service implementation.
+
+This module provides integration with Coqui XTTS streaming server for
+text-to-speech synthesis using local Docker deployment.
+"""
+
 from typing import Any, AsyncGenerator, Dict, Optional
 
 import aiohttp
 from loguru import logger
 
-from pipecat.audio.utils import create_default_resampler
+from pipecat.audio.utils import create_stream_resampler
 from pipecat.frames.frames import (
     ErrorFrame,
     Frame,
@@ -31,6 +37,14 @@ from pipecat.utils.tracing.service_decorators import traced_tts
 
 
 def language_to_xtts_language(language: Language) -> Optional[str]:
+    """Convert a Language enum to XTTS language code.
+
+    Args:
+        language: The Language enum value to convert.
+
+    Returns:
+        The corresponding XTTS language code, or None if not supported.
+    """
     BASE_LANGUAGES = {
         Language.CS: "cs",
         Language.DE: "de",
@@ -70,6 +84,13 @@ def language_to_xtts_language(language: Language) -> Optional[str]:
 
 
 class XTTSService(TTSService):
+    """Coqui XTTS text-to-speech service.
+
+    Provides text-to-speech synthesis using a locally running Coqui XTTS
+    streaming server. Supports multiple languages and voice cloning through
+    studio speakers configuration.
+    """
+
     def __init__(
         self,
         *,
@@ -80,6 +101,16 @@ class XTTSService(TTSService):
         sample_rate: Optional[int] = None,
         **kwargs,
     ):
+        """Initialize the XTTS service.
+
+        Args:
+            voice_id: ID of the voice/speaker to use for synthesis.
+            base_url: Base URL of the XTTS streaming server.
+            aiohttp_session: HTTP session for making requests to the server.
+            language: Language for synthesis. Defaults to English.
+            sample_rate: Audio sample rate. If None, uses default.
+            **kwargs: Additional arguments passed to parent TTSService.
+        """
         super().__init__(sample_rate=sample_rate, **kwargs)
 
         self._settings = {
@@ -90,15 +121,33 @@ class XTTSService(TTSService):
         self._studio_speakers: Optional[Dict[str, Any]] = None
         self._aiohttp_session = aiohttp_session
 
-        self._resampler = create_default_resampler()
+        self._resampler = create_stream_resampler()
 
     def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True, as XTTS service supports metrics generation.
+        """
         return True
 
     def language_to_service_language(self, language: Language) -> Optional[str]:
+        """Convert a Language enum to XTTS service language format.
+
+        Args:
+            language: The language to convert.
+
+        Returns:
+            The XTTS-specific language code, or None if not supported.
+        """
         return language_to_xtts_language(language)
 
     async def start(self, frame: StartFrame):
+        """Start the XTTS service and load studio speakers.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._studio_speakers:
@@ -120,6 +169,14 @@ class XTTSService(TTSService):
 
     @traced_tts
     async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        """Generate speech from text using XTTS streaming server.
+
+        Args:
+            text: The text to synthesize into speech.
+
+        Yields:
+            Frame: Audio frames containing the synthesized speech.
+        """
         logger.debug(f"{self}: Generating TTS [{text}]")
 
         if not self._studio_speakers:

pipecat/sync/base_notifier.py

@@ -4,14 +4,33 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base notifier interface for Pipecat."""
+
 from abc import ABC, abstractmethod
 
 
 class BaseNotifier(ABC):
+    """Abstract base class for notification mechanisms.
+
+    Provides a standard interface for implementing notification and waiting
+    patterns used for event coordination and signaling between components
+    in the Pipecat framework.
+    """
+
     @abstractmethod
     async def notify(self):
+        """Send a notification signal.
+
+        Implementations should trigger any waiting coroutines or processes
+        that are blocked on this notifier.
+        """
         pass
 
     @abstractmethod
     async def wait(self):
+        """Wait for a notification signal.
+
+        Implementations should block until a notification is received
+        from the corresponding notify() call.
+        """
         pass

pipecat/sync/event_notifier.py

@@ -4,18 +4,42 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Event-based notifier implementation using asyncio Event primitives."""
+
 import asyncio
 
 from pipecat.sync.base_notifier import BaseNotifier
 
 
 class EventNotifier(BaseNotifier):
+    """Event-based notifier using asyncio.Event for task synchronization.
+
+    Provides a simple notification mechanism where one task can signal
+    an event and other tasks can wait for that event to occur. The event
+    is automatically cleared after each wait operation.
+    """
+
     def __init__(self):
+        """Initialize the event notifier.
+
+        Creates an internal asyncio.Event for managing notifications.
+        """
         self._event = asyncio.Event()
 
     async def notify(self):
+        """Signal the event to notify waiting tasks.
+
+        Sets the internal event, causing any tasks waiting on this
+        notifier to be awakened.
+        """
         self._event.set()
 
     async def wait(self):
+        """Wait for the event to be signaled.
+
+        Blocks until another task calls notify(). Automatically clears
+        the event after being awakened so subsequent calls will wait
+        for the next notification.
+        """
         await self._event.wait()
         self._event.clear()

pipecat/tests/utils.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Testing utilities for Pipecat pipeline components."""
+
 import asyncio
 from dataclasses import dataclass
 from typing import Any, Awaitable, Callable, Dict, List, Optional, Sequence, Tuple
@@ -24,15 +26,27 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 @dataclass
 class SleepFrame(SystemFrame):
-    """This frame is used by test framework to introduce some sleep time before
-    the next frame is pushed. This is useful to control system frames vs data or
-    control frames.
+    """A system frame that introduces a sleep delay in the test pipeline.
+
+    This frame is used by the test framework to control timing between
+    frame processing, allowing tests to separate system frames from
+    data or control frames.
+
+    Parameters:
+        sleep: Duration to sleep in seconds before processing the next frame.
     """
 
-    sleep: float = 0.1
+    sleep: float = 0.2
 
 
 class HeartbeatsObserver(BaseObserver):
+    """Observer that monitors heartbeat frames from a specific processor.
+
+    This observer watches for HeartbeatFrames from a target processor and
+    invokes a callback when they are detected, useful for testing timing
+    and lifecycle events.
+    """
+
     def __init__(
         self,
         *,
@@ -40,11 +54,23 @@ class HeartbeatsObserver(BaseObserver):
         heartbeat_callback: Callable[[FrameProcessor, HeartbeatFrame], Awaitable[None]],
         **kwargs,
     ):
+        """Initialize the heartbeats observer.
+
+        Args:
+            target: The frame processor to monitor for heartbeat frames.
+            heartbeat_callback: Async callback function to invoke when heartbeats are detected.
+            **kwargs: Additional arguments passed to the parent observer.
+        """
         super().__init__(**kwargs)
         self._target = target
         self._callback = heartbeat_callback
 
     async def on_push_frame(self, data: FramePushed):
+        """Handle frame push events and detect heartbeats from target processor.
+
+        Args:
+            data: The frame push event data containing source and frame information.
+        """
         src = data.source
         frame = data.frame
 
@@ -53,6 +79,13 @@ class HeartbeatsObserver(BaseObserver):
 
 
 class QueuedFrameProcessor(FrameProcessor):
+    """A processor that captures frames in a queue for testing purposes.
+
+    This processor intercepts frames flowing in a specific direction and
+    stores them in a queue for later inspection during testing, while
+    still allowing the frames to continue through the pipeline.
+    """
+
     def __init__(
         self,
         *,
@@ -60,12 +93,25 @@ class QueuedFrameProcessor(FrameProcessor):
         queue_direction: FrameDirection,
         ignore_start: bool = True,
     ):
-        super().__init__()
+        """Initialize the queued frame processor.
+
+        Args:
+            queue: The asyncio queue to store captured frames.
+            queue_direction: The direction of frames to capture (UPSTREAM or DOWNSTREAM).
+            ignore_start: Whether to ignore StartFrames when capturing.
+        """
+        super().__init__(enable_direct_mode=True)
         self._queue = queue
         self._queue_direction = queue_direction
         self._ignore_start = ignore_start
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames and capture them in the queue if they match the direction.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction the frame is flowing.
+        """
         await super().process_frame(frame, direction)
 
         if direction == self._queue_direction:
@@ -85,6 +131,28 @@ async def run_test(
     start_metadata: Optional[Dict[str, Any]] = None,
     send_end_frame: bool = True,
 ) -> Tuple[Sequence[Frame], Sequence[Frame]]:
+    """Run a test pipeline with the specified processor and validate frame flow.
+
+    This function creates a test pipeline with the given processor, sends the
+    specified frames through it, and validates that the expected frames are
+    received in both upstream and downstream directions.
+
+    Args:
+        processor: The frame processor to test.
+        frames_to_send: Sequence of frames to send through the processor.
+        expected_down_frames: Expected frame types flowing downstream (optional).
+        expected_up_frames: Expected frame types flowing upstream (optional).
+        ignore_start: Whether to ignore StartFrames in frame validation.
+        observers: Optional list of observers to attach to the pipeline.
+        start_metadata: Optional metadata to include with the StartFrame.
+        send_end_frame: Whether to send an EndFrame at the end of the test.
+
+    Returns:
+        Tuple containing (downstream_frames, upstream_frames) that were received.
+
+    Raises:
+        AssertionError: If the received frames don't match the expected frame types.
+    """
     observers = observers or []
     start_metadata = start_metadata or {}
 

pipecat/transcriptions/language.py

@@ -4,13 +4,23 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Language code enumerations for Pipecat.
+
+This module provides comprehensive language code constants following ISO 639
+and BCP 47 standards, supporting both language-only and language-region
+combinations for various speech and text processing services.
+"""
+
 import sys
 from enum import Enum
 
 if sys.version_info < (3, 11):
 
     class StrEnum(str, Enum):
+        """String enumeration base class for Python < 3.11 compatibility."""
+
         def __new__(cls, value):
+            """Create a new instance of the StrEnum."""
             obj = str.__new__(cls, value)
             obj._value_ = value
             return obj
@@ -19,6 +29,14 @@ else:
 
 
 class Language(StrEnum):
+    """Language codes for speech and text processing services.
+
+    Provides comprehensive language code constants following ISO 639 and BCP 47
+    standards. Includes both language-only codes (e.g., 'en') and language-region
+    combinations (e.g., 'en-US') to support various speech synthesis, recognition,
+    and translation services.
+    """
+
     # Afrikaans
     AF = "af"
     AF_ZA = "af-ZA"
@@ -127,6 +145,9 @@ class Language(StrEnum):
     EN_US = "en-US"
     EN_ZA = "en-ZA"
 
+    # Esperanto
+    EO = "eo"
+
     # Spanish
     ES = "es"
     ES_AR = "es-AR"
@@ -456,6 +477,9 @@ class Language(StrEnum):
     # Tatar
     TT = "tt"
 
+    # Uyghur
+    UG = "ug"
+
     # Ukrainian
     UK = "uk"
     UK_UA = "uk-UA"

pipecat/transports/base_input.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base input transport implementation for Pipecat.
+
+This module provides the BaseInputTransport class which handles audio and video
+input processing, including VAD, turn analysis, and interruption management.
+"""
+
 import asyncio
 from concurrent.futures import ThreadPoolExecutor
 from typing import Optional
@@ -28,6 +34,7 @@ from pipecat.frames.frames import (
     InputAudioRawFrame,
     InputImageRawFrame,
     MetricsFrame,
+    SpeechControlParamsFrame,
     StartFrame,
     StartInterruptionFrame,
     StopFrame,
@@ -47,7 +54,20 @@ AUDIO_INPUT_TIMEOUT_SECS = 0.5
 
 
 class BaseInputTransport(FrameProcessor):
+    """Base class for input transport implementations.
+
+    Handles audio and video input processing including Voice Activity Detection,
+    turn analysis, audio filtering, and user interaction management. Supports
+    interruption handling and provides hooks for transport-specific implementations.
+    """
+
     def __init__(self, params: TransportParams, **kwargs):
+        """Initialize the base input transport.
+
+        Args:
+            params: Transport configuration parameters.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
 
         self._params = params
@@ -115,25 +135,54 @@ class BaseInputTransport(FrameProcessor):
             self._params.video_out_color_format = self._params.camera_out_color_format
 
     def enable_audio_in_stream_on_start(self, enabled: bool) -> None:
+        """Enable or disable audio streaming on transport start.
+
+        Args:
+            enabled: Whether to start audio streaming immediately on transport start.
+        """
         self.logger.debug(f"Enabling audio on start. {enabled}")
         self._params.audio_in_stream_on_start = enabled
 
     async def start_audio_in_streaming(self):
+        """Start audio input streaming.
+
+        Override in subclasses to implement transport-specific audio streaming.
+        """
         pass
 
     @property
     def sample_rate(self) -> int:
+        """Get the current audio sample rate.
+
+        Returns:
+            The sample rate in Hz.
+        """
         return self._sample_rate
 
     @property
     def vad_analyzer(self) -> Optional[VADAnalyzer]:
+        """Get the Voice Activity Detection analyzer.
+
+        Returns:
+            The VAD analyzer instance if configured, None otherwise.
+        """
         return self._params.vad_analyzer
 
     @property
     def turn_analyzer(self) -> Optional[BaseTurnAnalyzer]:
+        """Get the turn-taking analyzer.
+
+        Returns:
+            The turn analyzer instance if configured, None otherwise.
+        """
         return self._params.turn_analyzer
 
     async def start(self, frame: StartFrame):
+        """Start the input transport and initialize components.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         self._paused = False
         self._user_speaking = False
 
@@ -147,11 +196,23 @@ class BaseInputTransport(FrameProcessor):
         if self._params.turn_analyzer:
             self._params.turn_analyzer.set_sample_rate(self._sample_rate)
 
+        if self._params.vad_analyzer or self._params.turn_analyzer:
+            vad_params = self._params.vad_analyzer.params if self._params.vad_analyzer else None
+            turn_params = self._params.turn_analyzer.params if self._params.turn_analyzer else None
+
+            speech_frame = SpeechControlParamsFrame(vad_params=vad_params, turn_params=turn_params)
+            await self.push_frame(speech_frame)
+
         # Start audio filter.
         if self._params.audio_in_filter:
             await self._params.audio_in_filter.start(self._sample_rate)
 
     async def stop(self, frame: EndFrame):
+        """Stop the input transport and cleanup resources.
+
+        Args:
+            frame: The end frame signaling transport shutdown.
+        """
         # Cancel and wait for the audio input task to finish.
         await self._cancel_audio_task()
         # Stop audio filter.
@@ -159,6 +220,11 @@ class BaseInputTransport(FrameProcessor):
             await self._params.audio_in_filter.stop()
 
     async def pause(self, frame: StopFrame):
+        """Pause the input transport temporarily.
+
+        Args:
+            frame: The stop frame signaling transport pause.
+        """
         self._paused = True
         # Cancel task so we clear the queue
         await self._cancel_audio_task()
@@ -166,19 +232,38 @@ class BaseInputTransport(FrameProcessor):
         self._create_audio_task()
 
     async def cancel(self, frame: CancelFrame):
+        """Cancel the input transport and stop all processing.
+
+        Args:
+            frame: The cancel frame signaling immediate cancellation.
+        """
         # Cancel and wait for the audio input task to finish.
         await self._cancel_audio_task()
 
     async def set_transport_ready(self, frame: StartFrame):
-        """To be called when the transport is ready to stream."""
+        """Called when the transport is ready to stream.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         # Create audio input queue and task if needed.
         self._create_audio_task()
 
     async def push_video_frame(self, frame: InputImageRawFrame):
+        """Push a video frame downstream if video input is enabled.
+
+        Args:
+            frame: The input video frame to process.
+        """
         if self._params.video_in_enabled and not self._paused:
             await self.push_frame(frame)
 
     async def push_audio_frame(self, frame: InputAudioRawFrame):
+        """Push an audio frame to the processing queue if audio input is enabled.
+
+        Args:
+            frame: The input audio frame to process.
+        """
         if self._params.audio_in_enabled and not self._paused:
             await self._audio_in_queue.put(frame)
 
@@ -187,6 +272,12 @@ class BaseInputTransport(FrameProcessor):
     #
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and handle transport-specific logic.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         # Specific system frames
@@ -216,6 +307,13 @@ class BaseInputTransport(FrameProcessor):
         elif isinstance(frame, VADParamsUpdateFrame):
             if self.vad_analyzer:
                 self.vad_analyzer.set_params(frame.params, bot_logger=self.logger)
+                speech_frame = SpeechControlParamsFrame(
+                    vad_params=frame.params,
+                    turn_params=self._params.turn_analyzer.params
+                    if self._params.turn_analyzer
+                    else None,
+                )
+                await self.push_frame(speech_frame)
         elif isinstance(frame, SystemFrame):
             await self.push_frame(frame, direction)
         # Control frames
@@ -238,12 +336,14 @@ class BaseInputTransport(FrameProcessor):
     #
 
     async def _handle_bot_interruption(self, frame: BotInterruptionFrame):
+        """Handle bot interruption frames."""
         self.logger.debug("Bot interruption")
         if self.interruptions_allowed:
             await self._start_interruption()
             await self.push_frame(StartInterruptionFrame())
 
     async def _handle_user_interruption(self, frame: Frame):
+        """Handle user interruption events based on speaking state."""
         if isinstance(frame, UserStartedSpeakingFrame):
             self.logger.debug("User started speaking")
             self._user_speaking = True
@@ -281,9 +381,11 @@ class BaseInputTransport(FrameProcessor):
     #
 
     async def _handle_bot_started_speaking(self, frame: BotStartedSpeakingFrame):
+        """Update bot speaking state when bot starts speaking."""
         self._bot_speaking = True
 
     async def _handle_bot_stopped_speaking(self, frame: BotStoppedSpeakingFrame):
+        """Update bot speaking state when bot stops speaking."""
         self._bot_speaking = False
 
     #
@@ -291,16 +393,19 @@ class BaseInputTransport(FrameProcessor):
     #
 
     def _create_audio_task(self):
+        """Create the audio processing task if audio input is enabled."""
         if not self._audio_task and self._params.audio_in_enabled:
             self._audio_in_queue = asyncio.Queue()
             self._audio_task = self.create_task(self._audio_task_handler())
 
     async def _cancel_audio_task(self):
+        """Cancel and cleanup the audio processing task."""
         if self._audio_task:
             await self.cancel_task(self._audio_task)
             self._audio_task = None
 
     async def _vad_analyze(self, audio_frame: InputAudioRawFrame) -> VADState:
+        """Analyze audio frame for voice activity."""
         state = VADState.QUIET
         if self.vad_analyzer:
             state = await self.get_event_loop().run_in_executor(
@@ -309,6 +414,7 @@ class BaseInputTransport(FrameProcessor):
         return state
 
     async def _handle_vad(self, audio_frame: InputAudioRawFrame, vad_state: VADState):
+        """Handle Voice Activity Detection results and generate appropriate frames."""
         new_vad_state = await self._vad_analyze(audio_frame)
         if (
             new_vad_state != vad_state
@@ -339,18 +445,21 @@ class BaseInputTransport(FrameProcessor):
         return vad_state
 
     async def _handle_end_of_turn(self):
+        """Handle end-of-turn analysis and generate prediction results."""
         if self.turn_analyzer:
             state, prediction = await self.turn_analyzer.analyze_end_of_turn()
             await self._handle_prediction_result(prediction)
             await self._handle_end_of_turn_complete(state)
 
     async def _handle_end_of_turn_complete(self, state: EndOfTurnState):
+        """Handle completion of end-of-turn analysis."""
         if state == EndOfTurnState.COMPLETE:
             await self._handle_user_interruption(UserStoppedSpeakingFrame())
 
     async def _run_turn_analyzer(
         self, frame: InputAudioRawFrame, vad_state: VADState, previous_vad_state: VADState
     ):
+        """Run turn analysis on audio frame and handle results."""
         is_speech = vad_state == VADState.SPEAKING or vad_state == VADState.STARTING
         # If silence exceeds threshold, we are going to receive EndOfTurnState.COMPLETE
         end_of_turn_state = self._params.turn_analyzer.append_audio(frame.audio, is_speech)
@@ -361,6 +470,7 @@ class BaseInputTransport(FrameProcessor):
             await self._handle_end_of_turn()
 
     async def _audio_task_handler(self):
+        """Main audio processing task handler for VAD and turn analysis."""
         vad_state: VADState = VADState.QUIET
         while True:
             try:
@@ -395,13 +505,7 @@ class BaseInputTransport(FrameProcessor):
                     if self._params.turn_analyzer:
                         self._params.turn_analyzer.clear()
                     await self._handle_user_interruption(UserStoppedSpeakingFrame())
-            finally:
-                self.reset_watchdog()
 
     async def _handle_prediction_result(self, result: MetricsData):
-        """Handle a prediction result event from the turn analyzer.
-
-        Args:
-            result: The prediction result MetricsData.
-        """
+        """Handle a prediction result event from the turn analyzer."""
         await self.push_frame(MetricsFrame(data=[result]))