Improve docstrings for services and processors (#2087)

src/pipecat/services/fish/tts.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Fish Audio text-to-speech service implementation.
+
+This module provides integration with Fish Audio's real-time TTS WebSocket API
+for streaming text-to-speech synthesis with customizable voice parameters.
+"""
+
 import uuid
 from typing import AsyncGenerator, Literal, Optional
 
@@ -39,7 +45,23 @@ FishAudioOutputFormat = Literal["opus", "mp3", "pcm", "wav"]
 
 
 class FishAudioTTSService(InterruptibleTTSService):
+    """Fish Audio text-to-speech service with WebSocket streaming.
+
+    Provides real-time text-to-speech synthesis using Fish Audio's WebSocket API.
+    Supports various audio formats, customizable prosody controls, and streaming
+    audio generation with interruption handling.
+    """
+
     class InputParams(BaseModel):
+        """Input parameters for Fish Audio TTS configuration.
+
+        Parameters:
+            language: Language for synthesis. Defaults to English.
+            latency: Latency mode ("normal" or "balanced"). Defaults to "normal".
+            prosody_speed: Speech speed multiplier (0.5-2.0). Defaults to 1.0.
+            prosody_volume: Volume adjustment in dB. Defaults to 0.
+        """
+
         language: Optional[Language] = Language.EN
         latency: Optional[str] = "normal"  # "normal" or "balanced"
         prosody_speed: Optional[float] = 1.0  # Speech speed (0.5-2.0)
@@ -55,6 +77,16 @@ class FishAudioTTSService(InterruptibleTTSService):
         params: Optional[InputParams] = None,
         **kwargs,
     ):
+        """Initialize the Fish Audio TTS service.
+
+        Args:
+            api_key: Fish Audio API key for authentication.
+            model: Reference ID of the voice model to use for synthesis.
+            output_format: Audio output format. Defaults to "pcm".
+            sample_rate: Audio sample rate. If None, uses default.
+            params: Additional input parameters for voice customization.
+            **kwargs: Additional arguments passed to the parent service.
+        """
         super().__init__(
             push_stop_frames=True,
             pause_frame_processing=True,
@@ -85,23 +117,48 @@ class FishAudioTTSService(InterruptibleTTSService):
         self.set_model_name(model)
 
     def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True, as Fish Audio service supports metrics generation.
+        """
         return True
 
     async def set_model(self, model: str):
+        """Set the TTS model (reference ID).
+
+        Args:
+            model: The reference ID of the voice model to use.
+        """
         self._settings["reference_id"] = model
         await super().set_model(model)
         logger.info(f"Switching TTS model to: [{model}]")
 
     async def start(self, frame: StartFrame):
+        """Start the Fish Audio TTS service.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
         self._settings["sample_rate"] = self.sample_rate
         await self._connect()
 
     async def stop(self, frame: EndFrame):
+        """Stop the Fish Audio TTS service.
+
+        Args:
+            frame: The end frame.
+        """
         await super().stop(frame)
         await self._disconnect()
 
     async def cancel(self, frame: CancelFrame):
+        """Cancel the Fish Audio TTS service.
+
+        Args:
+            frame: The cancel frame.
+        """
         await super().cancel(frame)
         await self._disconnect()
 
@@ -191,6 +248,14 @@ class FishAudioTTSService(InterruptibleTTSService):
 
     @traced_tts
     async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        """Generate speech from text using Fish Audio's streaming API.
+
+        Args:
+            text: The text to synthesize into speech.
+
+        Yields:
+            Frame: Audio frames and control frames for the synthesized speech.
+        """
         logger.debug(f"{self}: Generating Fish TTS: [{text}]")
         try:
             if not self._websocket or self._websocket.closed: