feat: add WebSocket options for configurable timeouts and message limits in TTS streaming

Author: twangodev

src/fishaudio/core/websocket_options.py

@@ -5,14 +5,26 @@
 
 class WebSocketOptions:
     """
-    Options that can be provided to configure WebSocket connections.
+    Options for configuring WebSocket connections.
+
+    These options are passed directly to httpx_ws's connect_ws/aconnect_ws functions.
+    For complete documentation, see https://frankie567.github.io/httpx-ws/reference/httpx_ws/
 
     Attributes:
-        keepalive_ping_timeout_seconds: Maximum time to wait for a pong response
-            to a keepalive ping before considering the connection dead (default: 20s)
-        keepalive_ping_interval_seconds: Interval between keepalive pings (default: 20s)
-        max_message_size_bytes: Maximum size for incoming messages (default: 65,536 bytes)
-        queue_size: Size of the message receive queue (default: 512)
+        keepalive_ping_timeout_seconds: Maximum delay the client will wait for an answer
+            to its Ping event. If the delay is exceeded, WebSocketNetworkError will be
+            raised and the connection closed. Default: 20 seconds.
+        keepalive_ping_interval_seconds: Interval at which the client will automatically
+            send a Ping event to keep the connection alive. Set to None to disable this
+            mechanism. Default: 20 seconds.
+        max_message_size_bytes: Message size in bytes to receive from the server.
+            Default: 65536 bytes (64 KiB).
+        queue_size: Size of the queue where received messages will be held until they
+            are consumed. If the queue is full, the client will stop receiving messages
+            from the server until the queue has room available. Default: 512.
+
+    Note:
+        Parameter descriptions adapted from httpx_ws documentation.
     """
 
     def __init__(

src/fishaudio/resources/tts.py

@@ -232,13 +232,16 @@ def stream_websocket(
             config: TTS configuration (audio settings, voice, model parameters)
             model: TTS model to use
             max_workers: ThreadPoolExecutor workers for concurrent sender
+            ws_options: WebSocket connection options for configuring timeouts, message size limits, etc.
+                Useful for long-running generations that may exceed default timeout values.
+                See WebSocketOptions class for available parameters.
 
         Returns:
             Iterator of audio bytes
 
         Example:
             ```python
-            from fishaudio import FishAudio, TTSConfig, ReferenceAudio
+            from fishaudio import FishAudio, TTSConfig, ReferenceAudio, WebSocketOptions
 
             client = FishAudio(api_key="...")
 
@@ -274,6 +277,16 @@ def text_generator():
                 ):
                     f.write(audio_chunk)
 
+            # With WebSocket options for long-running generations
+            # Useful if you're generating very long responses that may take >20 seconds
+            ws_options = WebSocketOptions(keepalive_ping_timeout_seconds=60.0)
+            with open("output.mp3", "wb") as f:
+                for audio_chunk in client.tts.stream_websocket(
+                    text_generator(),
+                    ws_options=ws_options
+                ):
+                    f.write(audio_chunk)
+
             # Parameters override config values
             config = TTSConfig(format="mp3", latency="balanced")
             with open("output.wav", "wb") as f:
@@ -523,13 +536,16 @@ async def stream_websocket(
             speed: Speech speed multiplier, e.g. 1.5 for 1.5x speed (overrides config.prosody.speed if provided)
             config: TTS configuration (audio settings, voice, model parameters)
             model: TTS model to use
+            ws_options: WebSocket connection options for configuring timeouts, message size limits, etc.
+                Useful for long-running generations that may exceed default timeout values.
+                See WebSocketOptions class for available parameters.
 
         Returns:
             Async iterator of audio bytes
 
         Example:
             ```python
-            from fishaudio import AsyncFishAudio, TTSConfig, ReferenceAudio
+            from fishaudio import AsyncFishAudio, TTSConfig, ReferenceAudio, WebSocketOptions
 
             client = AsyncFishAudio(api_key="...")
 
@@ -565,6 +581,16 @@ async def text_generator():
                 ):
                     await f.write(audio_chunk)
 
+            # With WebSocket options for long-running generations
+            # Useful if you're generating very long responses that may take >20 seconds
+            ws_options = WebSocketOptions(keepalive_ping_timeout_seconds=60.0)
+            async with aiofiles.open("output.mp3", "wb") as f:
+                async for audio_chunk in client.tts.stream_websocket(
+                    text_generator(),
+                    ws_options=ws_options
+                ):
+                    await f.write(audio_chunk)
+
             # Parameters override config values
             config = TTSConfig(format="mp3", latency="balanced")
             async with aiofiles.open("output.wav", "wb") as f: