typecast-python 0.3.3__tar.gz → 0.3.4__tar.gz

{typecast_python-0.3.3 → typecast_python-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.3.3
+Version: 0.3.4
 Summary: Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices
 Project-URL: Homepage, https://typecast.ai
 Project-URL: Documentation, https://typecast.ai/docs/overview

{typecast_python-0.3.3 → typecast_python-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "typecast-python"
-version = "0.3.3"
+version = "0.3.4"
 description = "Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices"
 authors = [
     {name = "Neosapience", email = "help@typecast.ai"}

{typecast_python-0.3.3 → typecast_python-0.3.4}/src/typecast/async_client.py

@@ -1,3 +1,4 @@
+import asyncio
 from pathlib import Path
 from typing import AsyncIterator, BinaryIO, Optional, Union
 from urllib.parse import quote
@@ -11,6 +12,8 @@ from ._voice_clone import (
     validate_custom_voice_id,
 )
 from .client import _guess_audio_mime
+from .client import _output_with_inferred_format
+from .client import _validate_output_path
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -23,8 +26,11 @@ from .exceptions import (
 )
 from .models import (
     CustomVoice,
+    LanguageCode,
+    Output,
     SubscriptionResponse,
     TTSModel,
+    TTSPrompt,
     TTSRequest,
     TTSRequestStream,
     TTSRequestWithTimestamps,
@@ -141,6 +147,38 @@ class AsyncTypecast:
                 format=response.headers.get("Content-Type", "audio/wav").split("/")[-1],
             )
 
+    async def generate_to_file(
+        self,
+        path: Union[str, Path],
+        *,
+        text: str,
+        voice_id: str,
+        model: TTSModel = TTSModel.SSFM_V30,
+        language: Optional[Union[LanguageCode, str]] = None,
+        prompt: Optional[TTSPrompt] = None,
+        output: Optional[Output] = None,
+        seed: Optional[int] = None,
+    ) -> TTSResponse:
+        """Convert text to speech and write the audio bytes to a file.
+
+        Browse available API voices at
+        ``https://typecast.ai/developers/api/voices``.
+        """
+        output_path = _validate_output_path(path)
+        response = await self.text_to_speech(
+            TTSRequest(
+                text=text,
+                voice_id=voice_id,
+                model=model,
+                language=language,
+                prompt=prompt,
+                output=_output_with_inferred_format(output, path),
+                seed=seed,
+            )
+        )
+        await asyncio.to_thread(output_path.write_bytes, response.audio_data)
+        return response
+
     async def text_to_speech_stream(
         self, request: TTSRequestStream, chunk_size: int = 8192
     ) -> AsyncIterator[bytes]:

{typecast_python-0.3.3 → typecast_python-0.3.4}/src/typecast/client.py

@@ -22,8 +22,11 @@ from .exceptions import (
 )
 from .models import (
     CustomVoice,
+    LanguageCode,
+    Output,
     SubscriptionResponse,
     TTSModel,
+    TTSPrompt,
     TTSRequest,
     TTSRequestStream,
     TTSRequestWithTimestamps,
@@ -35,6 +38,33 @@ from .models import (
 )
 
 
+def _infer_audio_format_from_path(path: Union[str, Path]) -> Optional[str]:
+    suffix = Path(path).suffix.lower()
+    if suffix == ".mp3":
+        return "mp3"
+    if suffix == ".wav":
+        return "wav"
+    return None
+
+
+def _output_with_inferred_format(
+    output: Optional[Output],
+    path: Union[str, Path],
+) -> Optional[Output]:
+    audio_format = _infer_audio_format_from_path(path)
+    if audio_format is None or (output is not None and output.audio_format is not None):
+        return output
+    if output is None:
+        return Output(audio_format=audio_format)
+    return output.model_copy(update={"audio_format": audio_format})
+
+
+def _validate_output_path(path: Union[str, Path]) -> Path:
+    if isinstance(path, str) and not path.strip():
+        raise ValueError("path cannot be empty")
+    return Path(path)
+
+
 def _guess_audio_mime(filename: str) -> str:
     """Guess audio MIME type from filename extension; fall back to octet-stream."""
     lower = filename.lower()
@@ -136,6 +166,40 @@ class Typecast:
             format=response.headers.get("Content-Type", "audio/wav").split("/")[-1],
         )
 
+    def generate_to_file(
+        self,
+        path: Union[str, Path],
+        *,
+        text: str,
+        voice_id: str,
+        model: TTSModel = TTSModel.SSFM_V30,
+        language: Optional[Union[LanguageCode, str]] = None,
+        prompt: Optional[TTSPrompt] = None,
+        output: Optional[Output] = None,
+        seed: Optional[int] = None,
+    ) -> TTSResponse:
+        """Convert text to speech and write the audio bytes to a file.
+
+        ``model`` defaults to ``ssfm-v30``. If ``output.audio_format`` is not
+        set, the format is inferred from a ``.mp3`` or ``.wav`` extension.
+        Browse available API voices at
+        ``https://typecast.ai/developers/api/voices``.
+        """
+        output_path = _validate_output_path(path)
+        response = self.text_to_speech(
+            TTSRequest(
+                text=text,
+                voice_id=voice_id,
+                model=model,
+                language=language,
+                prompt=prompt,
+                output=_output_with_inferred_format(output, path),
+                seed=seed,
+            )
+        )
+        output_path.write_bytes(response.audio_data)
+        return response
+
     def text_to_speech_stream(
         self, request: TTSRequestStream, chunk_size: int = 8192
     ) -> Iterator[bytes]:

{typecast_python-0.3.3 → typecast_python-0.3.4}/src/typecast/models/tts.py

@@ -158,7 +158,11 @@ class TTSRequest(BaseModel):
     model_config = ConfigDict(json_schema_extra={"exclude_none": True})
 
     voice_id: str = Field(
-        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+        description=(
+            "Voice ID. Browse available API voices at "
+            "https://typecast.ai/developers/api/voices."
+        ),
+        examples=["tc_62a8975e695ad26f7fb514d1"],
     )
     text: str = Field(description="Text", examples=["Hello. How are you?"])
     model: TTSModel = Field(description="Voice model name", examples=["ssfm-v21"])
@@ -202,7 +206,11 @@ class TTSRequestStream(BaseModel):
     model_config = ConfigDict(json_schema_extra={"exclude_none": True})
 
     voice_id: str = Field(
-        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+        description=(
+            "Voice ID. Browse available API voices at "
+            "https://typecast.ai/developers/api/voices."
+        ),
+        examples=["tc_62a8975e695ad26f7fb514d1"],
     )
     text: str = Field(description="Text", examples=["Hello. How are you?"])
     model: TTSModel = Field(description="Voice model name", examples=["ssfm-v21"])
@@ -253,7 +261,11 @@ class TTSRequestWithTimestamps(BaseModel):
     model_config = ConfigDict(json_schema_extra={"exclude_none": True})
 
     voice_id: str = Field(
-        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+        description=(
+            "Voice ID. Browse available API voices at "
+            "https://typecast.ai/developers/api/voices."
+        ),
+        examples=["tc_62a8975e695ad26f7fb514d1"],
     )
     text: str = Field(description="Text", examples=["Hello. How are you?"])
     model: TTSModel = Field(description="Voice model name", examples=["ssfm-v30"])