feat: add support for references parameter in TTS conversion methods

Signed-off-by: James Ding <jamesding365@gmail.com>

Author: twangodev

src/fishaudio/resources/tts.py

@@ -2,7 +2,7 @@
 
 import asyncio
 from concurrent.futures import ThreadPoolExecutor
-from typing import AsyncIterable, Iterable, Iterator, Optional, Union
+from typing import AsyncIterable, Iterable, Iterator, List, Optional, Union
 
 import ormsgpack
 from httpx_ws import AsyncWebSocketSession, WebSocketSession, aconnect_ws, connect_ws
@@ -13,6 +13,7 @@
     CloseEvent,
     FlushEvent,
     Model,
+    ReferenceAudio,
     StartEvent,
     TextEvent,
     TTSConfig,
@@ -59,6 +60,7 @@ def convert(
         *,
         text: str,
         reference_id: Optional[str] = None,
+        references: List[ReferenceAudio] = [],
         config: TTSConfig = TTSConfig(),
         model: Model = "s1",
         request_options: Optional[RequestOptions] = None,
@@ -69,6 +71,7 @@ def convert(
         Args:
             text: Text to synthesize
             reference_id: Voice reference ID (overridden by config.reference_id if set)
+            references: Reference audio samples (overridden by config.references if set)
             config: TTS configuration (audio settings, voice, model parameters)
             model: TTS model to use
             request_options: Request-level overrides
@@ -78,7 +81,7 @@ def convert(
 
         Example:
             ```python
-            from fishaudio import FishAudio, TTSConfig
+            from fishaudio import FishAudio, TTSConfig, ReferenceAudio
 
             client = FishAudio(api_key="...")
 
@@ -88,6 +91,12 @@ def convert(
             # With reference_id parameter
             audio = client.tts.convert(text="Hello world", reference_id="your_model_id")
 
+            # With references parameter
+            audio = client.tts.convert(
+                text="Hello world",
+                references=[ReferenceAudio(audio=audio_bytes, text="sample")]
+            )
+
             # Custom configuration
             config = TTSConfig(format="wav", mp3_bitrate=192)
             audio = client.tts.convert(text="Hello world", config=config)
@@ -104,6 +113,10 @@ def convert(
         if request.reference_id is None and reference_id is not None:
             request.reference_id = reference_id
 
+        # Use parameter references only if config doesn't have any
+        if not request.references and references:
+            request.references = references
+
         payload = request.model_dump(exclude_none=True)
 
         # Make request with streaming
@@ -125,6 +138,7 @@ def stream_websocket(
         text_stream: Iterable[Union[str, TextEvent, FlushEvent]],
         *,
         reference_id: Optional[str] = None,
+        references: List[ReferenceAudio] = [],
         config: TTSConfig = TTSConfig(),
         model: Model = "s1",
         max_workers: int = 10,
@@ -137,6 +151,7 @@ def stream_websocket(
         Args:
             text_stream: Iterator of text chunks to stream
             reference_id: Voice reference ID (overridden by config.reference_id if set)
+            references: Reference audio samples (overridden by config.references if set)
             config: TTS configuration (audio settings, voice, model parameters)
             model: TTS model to use
             max_workers: ThreadPoolExecutor workers for concurrent sender
@@ -146,7 +161,7 @@ def stream_websocket(
 
         Example:
             ```python
-            from fishaudio import FishAudio, TTSConfig
+            from fishaudio import FishAudio, TTSConfig, ReferenceAudio
 
             client = FishAudio(api_key="...")
 
@@ -165,6 +180,14 @@ def text_generator():
                 for audio_chunk in client.tts.stream_websocket(text_generator(), reference_id="your_model_id"):
                     f.write(audio_chunk)
 
+            # With references parameter
+            with open("output.mp3", "wb") as f:
+                for audio_chunk in client.tts.stream_websocket(
+                    text_generator(),
+                    references=[ReferenceAudio(audio=audio_bytes, text="sample")]
+                ):
+                    f.write(audio_chunk)
+
             # Custom configuration
             config = TTSConfig(format="wav", latency="normal")
             with open("output.wav", "wb") as f:
@@ -179,6 +202,10 @@ def text_generator():
         if tts_request.reference_id is None and reference_id is not None:
             tts_request.reference_id = reference_id
 
+        # Use parameter references only if config doesn't have any
+        if not tts_request.references and references:
+            tts_request.references = references
+
         executor = ThreadPoolExecutor(max_workers=max_workers)
 
         try:
@@ -224,6 +251,7 @@ async def convert(
         *,
         text: str,
         reference_id: Optional[str] = None,
+        references: List[ReferenceAudio] = [],
         config: TTSConfig = TTSConfig(),
         model: Model = "s1",
         request_options: Optional[RequestOptions] = None,
@@ -234,6 +262,7 @@ async def convert(
         Args:
             text: Text to synthesize
             reference_id: Voice reference ID (overridden by config.reference_id if set)
+            references: Reference audio samples (overridden by config.references if set)
             config: TTS configuration (audio settings, voice, model parameters)
             model: TTS model to use
             request_options: Request-level overrides
@@ -243,7 +272,7 @@ async def convert(
 
         Example:
             ```python
-            from fishaudio import AsyncFishAudio, TTSConfig
+            from fishaudio import AsyncFishAudio, TTSConfig, ReferenceAudio
 
             client = AsyncFishAudio(api_key="...")
 
@@ -253,6 +282,12 @@ async def convert(
             # With reference_id parameter
             audio = await client.tts.convert(text="Hello world", reference_id="your_model_id")
 
+            # With references parameter
+            audio = await client.tts.convert(
+                text="Hello world",
+                references=[ReferenceAudio(audio=audio_bytes, text="sample")]
+            )
+
             # Custom configuration
             config = TTSConfig(format="wav", mp3_bitrate=192)
             audio = await client.tts.convert(text="Hello world", config=config)
@@ -269,6 +304,10 @@ async def convert(
         if request.reference_id is None and reference_id is not None:
             request.reference_id = reference_id
 
+        # Use parameter references only if config doesn't have any
+        if not request.references and references:
+            request.references = references
+
         payload = request.model_dump(exclude_none=True)
 
         # Make request with streaming
@@ -290,6 +329,7 @@ async def stream_websocket(
         text_stream: AsyncIterable[Union[str, TextEvent, FlushEvent]],
         *,
         reference_id: Optional[str] = None,
+        references: List[ReferenceAudio] = [],
         config: TTSConfig = TTSConfig(),
         model: Model = "s1",
     ):
@@ -301,6 +341,7 @@ async def stream_websocket(
         Args:
             text_stream: Async iterator of text chunks to stream
             reference_id: Voice reference ID (overridden by config.reference_id if set)
+            references: Reference audio samples (overridden by config.references if set)
             config: TTS configuration (audio settings, voice, model parameters)
             model: TTS model to use
 
@@ -309,7 +350,7 @@ async def stream_websocket(
 
         Example:
             ```python
-            from fishaudio import AsyncFishAudio, TTSConfig
+            from fishaudio import AsyncFishAudio, TTSConfig, ReferenceAudio
 
             client = AsyncFishAudio(api_key="...")
 
@@ -328,6 +369,14 @@ async def text_generator():
                 async for audio_chunk in client.tts.stream_websocket(text_generator(), reference_id="your_model_id"):
                     await f.write(audio_chunk)
 
+            # With references parameter
+            async with aiofiles.open("output.mp3", "wb") as f:
+                async for audio_chunk in client.tts.stream_websocket(
+                    text_generator(),
+                    references=[ReferenceAudio(audio=audio_bytes, text="sample")]
+                ):
+                    await f.write(audio_chunk)
+
             # Custom configuration
             config = TTSConfig(format="wav", latency="normal")
             async with aiofiles.open("output.wav", "wb") as f:
@@ -342,6 +391,10 @@ async def text_generator():
         if tts_request.reference_id is None and reference_id is not None:
             tts_request.reference_id = reference_id
 
+        # Use parameter references only if config doesn't have any
+        if not tts_request.references and references:
+            tts_request.references = references
+
         ws: AsyncWebSocketSession
         async with aconnect_ws(
             "/v1/tts/live",

tests/unit/test_tts.py

@@ -135,6 +135,46 @@ def test_convert_with_references(self, tts_client, mock_client_wrapper):
         assert payload["references"][0]["text"] == "Sample 1"
         assert payload["references"][1]["text"] == "Sample 2"
 
+    def test_convert_with_references_parameter(self, tts_client, mock_client_wrapper):
+        """Test TTS with references as direct parameter."""
+        mock_response = Mock()
+        mock_response.iter_bytes.return_value = iter([b"audio"])
+        mock_client_wrapper.request.return_value = mock_response
+
+        references = [
+            ReferenceAudio(audio=b"ref_audio_1", text="Sample 1"),
+            ReferenceAudio(audio=b"ref_audio_2", text="Sample 2"),
+        ]
+
+        list(tts_client.convert(text="Hello", references=references))
+
+        # Verify references in payload
+        call_args = mock_client_wrapper.request.call_args
+        payload = ormsgpack.unpackb(call_args[1]["content"])
+        assert len(payload["references"]) == 2
+        assert payload["references"][0]["text"] == "Sample 1"
+        assert payload["references"][1]["text"] == "Sample 2"
+
+    def test_convert_config_references_overrides_parameter(
+        self, tts_client, mock_client_wrapper
+    ):
+        """Test that config.references overrides parameter references."""
+        mock_response = Mock()
+        mock_response.iter_bytes.return_value = iter([b"audio"])
+        mock_client_wrapper.request.return_value = mock_response
+
+        config_refs = [ReferenceAudio(audio=b"config_audio", text="Config")]
+        param_refs = [ReferenceAudio(audio=b"param_audio", text="Param")]
+
+        config = TTSConfig(references=config_refs)
+        list(tts_client.convert(text="Hello", references=param_refs, config=config))
+
+        # Verify config references take precedence
+        call_args = mock_client_wrapper.request.call_args
+        payload = ormsgpack.unpackb(call_args[1]["content"])
+        assert len(payload["references"]) == 1
+        assert payload["references"][0]["text"] == "Config"
+
     def test_convert_with_different_backend(self, tts_client, mock_client_wrapper):
         """Test TTS with different backend/model."""
         mock_response = Mock()
@@ -364,6 +404,66 @@ async def async_iter_bytes():
         payload = ormsgpack.unpackb(call_args[1]["content"])
         assert payload["reference_id"] == "voice_from_config"
 
+    @pytest.mark.asyncio
+    async def test_convert_with_references_parameter(
+        self, async_tts_client, async_mock_client_wrapper
+    ):
+        """Test async TTS with references as direct parameter."""
+        mock_response = Mock()
+
+        async def async_iter_bytes():
+            yield b"audio"
+
+        mock_response.aiter_bytes = async_iter_bytes
+        async_mock_client_wrapper.request = AsyncMock(return_value=mock_response)
+
+        references = [
+            ReferenceAudio(audio=b"ref_audio_1", text="Sample 1"),
+            ReferenceAudio(audio=b"ref_audio_2", text="Sample 2"),
+        ]
+
+        audio_chunks = []
+        async for chunk in async_tts_client.convert(
+            text="Hello", references=references
+        ):
+            audio_chunks.append(chunk)
+
+        # Verify references in payload
+        call_args = async_mock_client_wrapper.request.call_args
+        payload = ormsgpack.unpackb(call_args[1]["content"])
+        assert len(payload["references"]) == 2
+        assert payload["references"][0]["text"] == "Sample 1"
+        assert payload["references"][1]["text"] == "Sample 2"
+
+    @pytest.mark.asyncio
+    async def test_convert_config_references_overrides_parameter(
+        self, async_tts_client, async_mock_client_wrapper
+    ):
+        """Test that config.references overrides parameter references (async)."""
+        mock_response = Mock()
+
+        async def async_iter_bytes():
+            yield b"audio"
+
+        mock_response.aiter_bytes = async_iter_bytes
+        async_mock_client_wrapper.request = AsyncMock(return_value=mock_response)
+
+        config_refs = [ReferenceAudio(audio=b"config_audio", text="Config")]
+        param_refs = [ReferenceAudio(audio=b"param_audio", text="Param")]
+
+        config = TTSConfig(references=config_refs)
+        audio_chunks = []
+        async for chunk in async_tts_client.convert(
+            text="Hello", references=param_refs, config=config
+        ):
+            audio_chunks.append(chunk)
+
+        # Verify config references take precedence
+        call_args = async_mock_client_wrapper.request.call_args
+        payload = ormsgpack.unpackb(call_args[1]["content"])
+        assert len(payload["references"]) == 1
+        assert payload["references"][0]["text"] == "Config"
+
     @pytest.mark.asyncio
     async def test_convert_with_prosody(
         self, async_tts_client, async_mock_client_wrapper