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

pipecat/services/azure/tts.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Azure Cognitive Services Text-to-Speech service implementations."""
+
 import asyncio
 from typing import AsyncGenerator, Optional
 
@@ -21,8 +23,8 @@ from pipecat.frames.frames import (
 from pipecat.services.azure.common import language_to_azure_language
 from pipecat.services.tts_service import TTSService
 from pipecat.transcriptions.language import Language
-from pipecat.utils.utils import detect_language_from_script
 from pipecat.utils.tracing.service_decorators import traced_tts
+from pipecat.utils.utils import detect_language_from_script
 
 try:
     from azure.cognitiveservices.speech import (
@@ -40,6 +42,15 @@ except ModuleNotFoundError as e:
 
 
 def sample_rate_to_output_format(sample_rate: int) -> SpeechSynthesisOutputFormat:
+    """Convert sample rate to Azure speech synthesis output format.
+
+    Args:
+        sample_rate: Sample rate in Hz.
+
+    Returns:
+        Corresponding Azure SpeechSynthesisOutputFormat enum value.
+        Defaults to Raw24Khz16BitMonoPcm if sample rate not found.
+    """
     sample_rate_map = {
         8000: SpeechSynthesisOutputFormat.Raw8Khz16BitMonoPcm,
         16000: SpeechSynthesisOutputFormat.Raw16Khz16BitMonoPcm,
@@ -52,7 +63,36 @@ def sample_rate_to_output_format(sample_rate: int) -> SpeechSynthesisOutputForma
 
 
 class AzureBaseTTSService(TTSService):
+    """Base class for Azure Cognitive Services text-to-speech implementations.
+
+    Provides common functionality for Azure TTS services including SSML
+    construction, voice configuration, and parameter management.
+    """
+
+    # Define SSML escape mappings based on SSML reserved characters
+    # See - https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-synthesis-markup-structure
+    SSML_ESCAPE_CHARS = {
+        "&": "&",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&apos;",
+    }
+
     class InputParams(BaseModel):
+        """Input parameters for Azure TTS voice configuration.
+
+        Parameters:
+            emphasis: Emphasis level for speech ("strong", "moderate", "reduced").
+            language: Language for synthesis. Defaults to English (US).
+            pitch: Voice pitch adjustment (e.g., "+10%", "-5Hz", "high").
+            rate: Speech rate multiplier. Defaults to "1.05".
+            role: Voice role for expression (e.g., "YoungAdultFemale").
+            style: Speaking style (e.g., "cheerful", "sad", "excited").
+            style_degree: Intensity of the speaking style (0.01 to 2.0).
+            volume: Volume level (e.g., "+20%", "loud", "x-soft").
+        """
+
         emphasis: Optional[str] = None
         language: Optional[Language] = Language.EN_US
         pitch: Optional[str] = None
@@ -75,6 +115,16 @@ class AzureBaseTTSService(TTSService):
         params: Optional[InputParams] = None,
         **kwargs,
     ):
+        """Initialize the Azure TTS service with configuration parameters.
+
+        Args:
+            api_key: Azure Cognitive Services subscription key.
+            region: Azure region identifier (e.g., "eastus", "westus2").
+            voice: Voice name to use for synthesis. Defaults to "en-US-SaraNeural".
+            sample_rate: Audio sample rate in Hz. If None, uses service default.
+            params: Voice and synthesis parameters configuration.
+            **kwargs: Additional arguments passed to parent TTSService.
+        """
         super().__init__(sample_rate=sample_rate, **kwargs)
 
         params = params or AzureBaseTTSService.InputParams()
@@ -138,9 +188,22 @@ class AzureBaseTTSService(TTSService):
         logger.debug(f"Final additional language map: {self._additional_lang_map}")
 
     def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True, as Azure TTS service supports metrics generation.
+        """
         return True
 
     def language_to_service_language(self, language: Language) -> Optional[str]:
+        """Convert a Language enum to Azure language format.
+
+        Args:
+            language: The language to convert.
+
+        Returns:
+            The Azure-specific language code, or None if not supported.
+        """
         return language_to_azure_language(language)
 
     def _construct_ssml(self, text: str) -> str:
@@ -162,6 +225,10 @@ class AzureBaseTTSService(TTSService):
             )
 
         # 3. Construct SSML with the selected language and voice
+
+        # Escape special characters
+        escaped_text = self._escape_text(text)
+
         ssml = (
             f"<speak version='1.0' xml:lang='{target_language}' "
             "xmlns='http://www.w3.org/2001/10/synthesis' "
@@ -193,10 +260,10 @@ class AzureBaseTTSService(TTSService):
 
         if "Multilingual" in target_voice:
             ssml += f"<lang xml:lang='{target_language}'>"
-            ssml += text
+            ssml += escaped_text
             ssml += "</lang>"
         else:
-            ssml += text
+            ssml += escaped_text
 
         if self._settings["emphasis"]:
             ssml += "</emphasis>"
@@ -210,9 +277,42 @@ class AzureBaseTTSService(TTSService):
 
         return ssml
 
+    def _escape_text(self, text: str) -> str:
+        """Escapes XML/SSML reserved characters according to Microsoft documentation.
+
+        This method escapes the following characters:
+        - & becomes &amp;
+        - < becomes &lt;
+        - > becomes &gt;
+        - " becomes &quot;
+        - ' becomes &apos;
+
+        Args:
+            text: The text to escape.
+
+        Returns:
+            The escaped text.
+        """
+        escaped_text = text
+        for char, escape_code in AzureBaseTTSService.SSML_ESCAPE_CHARS.items():
+            escaped_text = escaped_text.replace(char, escape_code)
+        return escaped_text
+
 
 class AzureTTSService(AzureBaseTTSService):
+    """Azure Cognitive Services streaming TTS service.
+
+    Provides real-time text-to-speech synthesis using Azure's WebSocket-based
+    streaming API. Audio chunks are streamed as they become available for
+    lower latency playback.
+    """
+
     def __init__(self, **kwargs):
+        """Initialize the Azure streaming TTS service.
+
+        Args:
+            **kwargs: All arguments passed to AzureBaseTTSService parent class.
+        """
         super().__init__(**kwargs)
         self._speech_config = None
         self._speech_synthesizer = None
@@ -220,6 +320,11 @@ class AzureTTSService(AzureBaseTTSService):
         self._clear_audio = False
 
     async def start(self, frame: StartFrame):
+        """Start the Azure TTS service and initialize speech synthesizer.
+
+        Args:
+            frame: Start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._speech_config:
@@ -250,12 +355,12 @@ class AzureTTSService(AzureBaseTTSService):
         self._speech_synthesizer.synthesis_canceled.connect(self._handle_canceled)
 
     def _handle_synthesizing(self, evt):
-        """Handle audio chunks as they arrive"""
+        """Handle audio chunks as they arriv."""
         if evt.result and evt.result.audio_data:
             self._audio_queue.put_nowait(evt.result.audio_data)
 
     def _handle_completed(self, evt):
-        """Handle synthesis completion"""
+        """Handle synthesis completion."""
         self._audio_queue.put_nowait(None)  # Signal completion
 
     def _handle_canceled(self, evt):
@@ -263,29 +368,30 @@ class AzureTTSService(AzureBaseTTSService):
         self.logger.error(f"Speech synthesis canceled: {evt.result.cancellation_details.reason}")
         self._audio_queue.put_nowait(None)
 
-    async def clear_azure_audio(self):
-        self.logger.debug("Flushing audio")
-        self._clear_audio = True
-        if self._speech_synthesizer is not None:
-            future = self._speech_synthesizer.stop_speaking_async()
-
-            async def wait_for_future_completion():
-                loop = self.get_event_loop()
-                await loop.run_in_executor(None, future.get)
-
-            task = self.create_task(wait_for_future_completion())
-            await self.wait_for_task(task)
-        while not self._audio_queue.empty():
-            try:
-                self._audio_queue.get_nowait()
-            except asyncio.QueueEmpty:
-                break
-        self._clear_audio = False
+    async def flush_audio(self):
+        """Flush any pending audio data."""
+        logger.trace(f"{self}: flushing audio")
 
     @traced_tts
     async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        """Generate speech from text using Azure's streaming synthesis.
+
+        Args:
+            text: The text to synthesize into speech.
+
+        Yields:
+            Frame: Audio frames containing synthesized speech data.
+        """
         text = text.lstrip()
         self.logger.debug(f"{self}: Generating TTS [{text}]")
+
+        # Clear the audio queue in case there's still audio in it, causing the next audio response
+        # to be cut off by the 'None' element returned at the end of the previous audio synthesis.
+        # Empty the audio queue before processing the new text
+        while not self._audio_queue.empty():
+            self._audio_queue.get_nowait()
+            self._audio_queue.task_done()
+
         try:
             if self._speech_synthesizer is None:
                 error_msg = "Speech synthesizer not initialized."
@@ -324,12 +430,29 @@ class AzureTTSService(AzureBaseTTSService):
 
 
 class AzureHttpTTSService(AzureBaseTTSService):
+    """Azure Cognitive Services HTTP-based TTS service.
+
+    Provides text-to-speech synthesis using Azure's HTTP API for simpler,
+    non-streaming synthesis. Suitable for use cases where streaming is not
+    required and simpler integration is preferred.
+    """
+
     def __init__(self, **kwargs):
+        """Initialize the Azure HTTP TTS service.
+
+        Args:
+            **kwargs: All arguments passed to AzureBaseTTSService parent class.
+        """
         super().__init__(**kwargs)
         self._speech_config = None
         self._speech_synthesizer = None
 
     async def start(self, frame: StartFrame):
+        """Start the Azure HTTP TTS service and initialize speech synthesizer.
+
+        Args:
+            frame: Start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._speech_config:
@@ -349,6 +472,14 @@ class AzureHttpTTSService(AzureBaseTTSService):
 
     @traced_tts
     async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        """Generate speech from text using Azure's HTTP synthesis API.
+
+        Args:
+            text: The text to synthesize into speech.
+
+        Yields:
+            Frame: Audio frames containing the complete synthesized speech.
+        """
         logger.debug(f"{self}: Generating TTS [{text}]")
 
         await self.start_ttfb_metrics()

pipecat/services/cartesia/stt.py

@@ -4,12 +4,17 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Cartesia Speech-to-Text service implementation.
+
+This module provides a WebSocket-based STT service that integrates with
+the Cartesia Live transcription API for real-time speech recognition.
+"""
+
 import asyncio
 import json
 import urllib.parse
 from typing import AsyncGenerator, Optional
 
-import websockets
 from loguru import logger
 
 from pipecat.frames.frames import (
@@ -28,8 +33,23 @@ from pipecat.transcriptions.language import Language
 from pipecat.utils.time import time_now_iso8601
 from pipecat.utils.tracing.service_decorators import traced_stt
 
+try:
+    import websockets
+    from websockets.asyncio.client import connect as websocket_connect
+    from websockets.protocol import State
+except ModuleNotFoundError as e:
+    logger.error(f"Exception: {e}")
+    logger.error("In order to use Cartesia, you need to `pip install pipecat-ai[cartesia]`.")
+    raise Exception(f"Missing module: {e}")
+
 
 class CartesiaLiveOptions:
+    """Configuration options for Cartesia Live STT service.
+
+    Manages transcription parameters including model selection, language,
+    audio encoding format, and sample rate settings.
+    """
+
     def __init__(
         self,
         *,
@@ -39,6 +59,15 @@ class CartesiaLiveOptions:
         sample_rate: int = 16000,
         **kwargs,
     ):
+        """Initialize CartesiaLiveOptions with default or provided parameters.
+
+        Args:
+            model: The transcription model to use. Defaults to "ink-whisper".
+            language: Target language for transcription. Defaults to English.
+            encoding: Audio encoding format. Defaults to "pcm_s16le".
+            sample_rate: Audio sample rate in Hz. Defaults to 16000.
+            **kwargs: Additional parameters for the transcription service.
+        """
         self.model = model
         self.language = language
         self.encoding = encoding
@@ -46,6 +75,11 @@ class CartesiaLiveOptions:
         self.additional_params = kwargs
 
     def to_dict(self):
+        """Convert options to dictionary format.
+
+        Returns:
+            Dictionary containing all configuration parameters.
+        """
         params = {
             "model": self.model,
             "language": self.language if isinstance(self.language, str) else self.language.value,
@@ -56,19 +90,48 @@ class CartesiaLiveOptions:
         return params
 
     def items(self):
+        """Get configuration items as key-value pairs.
+
+        Returns:
+            Iterator of (key, value) tuples for all configuration parameters.
+        """
         return self.to_dict().items()
 
     def get(self, key, default=None):
+        """Get a configuration value by key.
+
+        Args:
+            key: The configuration parameter name to retrieve.
+            default: Default value if key is not found.
+
+        Returns:
+            The configuration value or default if not found.
+        """
         if hasattr(self, key):
             return getattr(self, key)
         return self.additional_params.get(key, default)
 
     @classmethod
     def from_json(cls, json_str: str) -> "CartesiaLiveOptions":
+        """Create options from JSON string.
+
+        Args:
+            json_str: JSON string containing configuration parameters.
+
+        Returns:
+            New CartesiaLiveOptions instance with parsed parameters.
+        """
         return cls(**json.loads(json_str))
 
 
 class CartesiaSTTService(STTService):
+    """Speech-to-text service using Cartesia Live API.
+
+    Provides real-time speech transcription through WebSocket connection
+    to Cartesia's Live transcription service. Supports both interim and
+    final transcriptions with configurable models and languages.
+    """
+
     def __init__(
         self,
         *,
@@ -78,6 +141,15 @@ class CartesiaSTTService(STTService):
         live_options: Optional[CartesiaLiveOptions] = None,
         **kwargs,
     ):
+        """Initialize CartesiaSTTService with API key and options.
+
+        Args:
+            api_key: Authentication key for Cartesia API.
+            base_url: Custom API endpoint URL. If empty, uses default.
+            sample_rate: Audio sample rate in Hz. Defaults to 16000.
+            live_options: Configuration options for transcription service.
+            **kwargs: Additional arguments passed to parent STTService.
+        """
         sample_rate = sample_rate or (live_options.sample_rate if live_options else None)
         super().__init__(sample_rate=sample_rate, **kwargs)
 
@@ -108,23 +180,51 @@ class CartesiaSTTService(STTService):
         self._receiver_task = None
 
     def can_generate_metrics(self) -> bool:
+        """Check if the service can generate processing metrics.
+
+        Returns:
+            True, indicating metrics are supported.
+        """
         return True
 
     async def start(self, frame: StartFrame):
+        """Start the STT service and establish connection.
+
+        Args:
+            frame: Frame indicating service should start.
+        """
         await super().start(frame)
         await self._connect()
 
     async def stop(self, frame: EndFrame):
+        """Stop the STT service and close connection.
+
+        Args:
+            frame: Frame indicating service should stop.
+        """
         await super().stop(frame)
         await self._disconnect()
 
     async def cancel(self, frame: CancelFrame):
+        """Cancel the STT service and close connection.
+
+        Args:
+            frame: Frame indicating service should be cancelled.
+        """
         await super().cancel(frame)
         await self._disconnect()
 
     async def run_stt(self, audio: bytes) -> AsyncGenerator[Frame, None]:
+        """Process audio data for speech-to-text transcription.
+
+        Args:
+            audio: Raw audio bytes to transcribe.
+
+        Yields:
+            None - transcription results are handled via WebSocket responses.
+        """
         # If the connection is closed, due to timeout, we need to reconnect when the user starts speaking again
-        if not self._connection or self._connection.closed:
+        if not self._connection or self._connection.state is State.CLOSED:
             await self._connect()
 
         await self._connection.send(audio)
@@ -137,7 +237,7 @@ class CartesiaSTTService(STTService):
         headers = {"Cartesia-Version": "2025-04-16", "X-API-Key": self._api_key}
 
         try:
-            self._connection = await websockets.connect(ws_url, extra_headers=headers)
+            self._connection = await websocket_connect(ws_url, additional_headers=headers)
             # Setup the receiver task to handle the incoming messages from the Cartesia server
             if self._receiver_task is None or self._receiver_task.done():
                 self._receiver_task = asyncio.create_task(self._receive_messages())
@@ -148,7 +248,7 @@ class CartesiaSTTService(STTService):
     async def _receive_messages(self):
         try:
             while True:
-                if not self._connection or self._connection.closed:
+                if not self._connection or self._connection.state is State.CLOSED:
                     break
 
                 message = await self._connection.recv()
@@ -197,14 +297,24 @@ class CartesiaSTTService(STTService):
             await self.stop_ttfb_metrics()
             if is_final:
                 await self.push_frame(
-                    TranscriptionFrame(transcript, "", time_now_iso8601(), language)
+                    TranscriptionFrame(
+                        transcript,
+                        self._user_id,
+                        time_now_iso8601(),
+                        language,
+                    )
                 )
                 await self._handle_transcription(transcript, is_final, language)
                 await self.stop_processing_metrics()
             else:
                 # For interim transcriptions, just push the frame without tracing
                 await self.push_frame(
-                    InterimTranscriptionFrame(transcript, "", time_now_iso8601(), language)
+                    InterimTranscriptionFrame(
+                        transcript,
+                        self._user_id,
+                        time_now_iso8601(),
+                        language,
+                    )
                 )
 
     async def _disconnect(self):
@@ -218,22 +328,29 @@ class CartesiaSTTService(STTService):
                 logger.exception(f"Unexpected exception while cancelling task: {e}")
             self._receiver_task = None
 
-        if self._connection and self._connection.open:
+        if self._connection and self._connection.state is State.OPEN:
             logger.debug("Disconnecting from Cartesia")
 
             await self._connection.close()
             self._connection = None
 
     async def start_metrics(self):
+        """Start performance metrics collection for transcription processing."""
         await self.start_ttfb_metrics()
         await self.start_processing_metrics()
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and handle speech events.
+
+        Args:
+            frame: The frame to process.
+            direction: Direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, UserStartedSpeakingFrame):
             await self.start_metrics()
         elif isinstance(frame, UserStoppedSpeakingFrame):
             # Send finalize command to flush the transcription session
-            if self._connection and self._connection.open:
+            if self._connection and self._connection.state is State.OPEN:
                 await self._connection.send("finalize")