typecast-python 0.3.3__py3-none-any.whl → 0.3.5__py3-none-any.whl

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/client.py

@@ -10,6 +10,7 @@ from ._voice_clone import (
     validate_clone_inputs,
     validate_custom_voice_id,
 )
+from .composer import SpeechComposer
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -22,8 +23,11 @@ from .exceptions import (
 )
 from .models import (
     CustomVoice,
+    LanguageCode,
+    Output,
     SubscriptionResponse,
     TTSModel,
+    TTSPrompt,
     TTSRequest,
     TTSRequestStream,
     TTSRequestWithTimestamps,
@@ -35,6 +39,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 +167,48 @@ class Typecast:
             format=response.headers.get("Content-Type", "audio/wav").split("/")[-1],
         )
 
+    def compose_speech(self) -> SpeechComposer:
+        """Build composed speech from multiple text and pause segments.
+
+        Text passed to ``say()`` may include pause markup such as ``<|0.3s|>``.
+        ``pause(seconds)`` also uses seconds, e.g. ``0.3`` for 300 ms.
+        """
+        return SpeechComposer(self.text_to_speech)
+
+    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/composer.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import io
+import math
+import re
+import struct
+import wave
+from dataclasses import dataclass
+from typing import Callable, Literal, Optional, Union
+
+from .models import LanguageCode, Output, TTSModel, TTSPrompt, TTSRequest, TTSResponse
+
+_PAUSE_TOKEN = re.compile(r"<\|(\d+(?:\.\d+)?)s\|>")
+
+
+@dataclass(frozen=True)
+class _TextPart:
+    kind: Literal["text"]
+    text: str
+
+
+@dataclass(frozen=True)
+class _PausePart:
+    kind: Literal["pause"]
+    seconds: float
+
+
+@dataclass(frozen=True)
+class _SpeechPart:
+    text: str
+    settings: "_ComposerSettings"
+
+
+@dataclass(frozen=True)
+class _WavSpec:
+    sample_rate: int
+    channels: int
+    sample_width: int
+
+
+@dataclass(frozen=True)
+class _ParsedWav:
+    spec: _WavSpec
+    samples: list[int]
+
+
+@dataclass(frozen=True)
+class _ComposerSettings:
+    voice_id: Optional[str] = None
+    model: Optional[Union[TTSModel, str]] = None
+    language: Optional[Union[LanguageCode, str]] = None
+    prompt: Optional[TTSPrompt] = None
+    output: Optional[Output] = None
+    seed: Optional[int] = None
+
+
+class SpeechComposer:
+    def __init__(self, text_to_speech: Callable[[TTSRequest], TTSResponse]):
+        self._text_to_speech = text_to_speech
+        self._defaults = _ComposerSettings()
+        self._parts: list[Union[_SpeechPart, _PausePart]] = []
+
+    def defaults(
+        self,
+        *,
+        voice_id: Optional[str] = None,
+        model: Optional[Union[TTSModel, str]] = None,
+        language: Optional[Union[LanguageCode, str]] = None,
+        prompt: Optional[TTSPrompt] = None,
+        output: Optional[Output] = None,
+        seed: Optional[int] = None,
+    ) -> "SpeechComposer":
+        self._defaults = _merge_settings(
+            self._defaults,
+            _ComposerSettings(
+                voice_id=voice_id,
+                model=model,
+                language=language,
+                prompt=prompt,
+                output=output,
+                seed=seed,
+            ),
+        )
+        return self
+
+    def say(
+        self,
+        text: str,
+        *,
+        voice_id: Optional[str] = None,
+        model: Optional[Union[TTSModel, str]] = None,
+        language: Optional[Union[LanguageCode, str]] = None,
+        prompt: Optional[TTSPrompt] = None,
+        output: Optional[Output] = None,
+        seed: Optional[int] = None,
+    ) -> "SpeechComposer":
+        settings = _merge_settings(
+            self._defaults,
+            _ComposerSettings(
+                voice_id=voice_id,
+                model=model,
+                language=language,
+                prompt=prompt,
+                output=output,
+                seed=seed,
+            ),
+        )
+        self._parts.append(_SpeechPart(text=text, settings=settings))
+        return self
+
+    def pause(self, seconds: float) -> "SpeechComposer":
+        """Insert silence between speech segments.
+
+        Args:
+            seconds: Duration in seconds. Use 0.3 for 300 ms, 3 for 3 seconds.
+        """
+        if not math.isfinite(seconds) or seconds <= 0:
+            raise ValueError("pause seconds must be greater than 0")
+        self._parts.append(_PausePart(kind="pause", seconds=seconds))
+        return self
+
+    def generate(self) -> TTSResponse:
+        plan = self._build_plan()
+        if not any(isinstance(part, _SpeechPart) for part in plan):
+            raise ValueError("at least one speech segment is required")
+
+        output_format = (
+            self._defaults.output.audio_format if self._defaults.output else "wav"
+        )
+        if output_format not in ("wav", "mp3"):
+            raise ValueError(f"unsupported composed speech output format: {output_format}")
+
+        wav_spec: Optional[_WavSpec] = None
+        output_samples: list[int] = []
+        for part in plan:
+            if isinstance(part, _PausePart):
+                if wav_spec is None:
+                    raise ValueError("pause cannot be the first composed part")
+                output_samples.extend(
+                    [0] * _seconds_to_samples(part.seconds, wav_spec.sample_rate)
+                )
+                continue
+
+            request = _settings_to_request(part.text, part.settings)
+            response = self._text_to_speech(request)
+            wav = _parse_wav(response.audio_data)
+            if wav_spec is not None and wav.spec != wav_spec:
+                raise ValueError("all composed WAV segments must use the same PCM format")
+            wav_spec = wav.spec
+            output_samples.extend(_trim_silence(wav.samples))
+
+        final_spec = wav_spec
+        assert final_spec is not None
+        wav_bytes = _encode_wav(output_samples, final_spec)
+        if output_format == "mp3":
+            raise ValueError("ffmpeg is required to encode composed speech as mp3")
+        return TTSResponse(
+            audio_data=wav_bytes,
+            duration=len(output_samples) / final_spec.sample_rate,
+            format="wav",
+        )
+
+    def _build_plan(self) -> list[Union[_SpeechPart, _PausePart]]:
+        plan: list[Union[_SpeechPart, _PausePart]] = []
+        for part in self._parts:
+            if isinstance(part, _PausePart):
+                plan.append(part)
+                continue
+            for parsed in parse_pause_markup(part.text):
+                if isinstance(parsed, _PausePart):
+                    plan.append(parsed)
+                    continue
+                if not parsed.text.strip():
+                    continue
+                if not part.settings.voice_id:
+                    raise ValueError("voice_id is required for composed speech segments")
+                if not part.settings.model:
+                    raise ValueError("model is required for composed speech segments")
+                plan.append(_SpeechPart(text=parsed.text, settings=part.settings))
+        return plan
+
+
+def parse_pause_markup(text: str) -> list[Union[_TextPart, _PausePart]]:
+    parts: list[Union[_TextPart, _PausePart]] = []
+    last_index = 0
+    for match in _PAUSE_TOKEN.finditer(text):
+        if match.start() > last_index:
+            parts.append(_TextPart(kind="text", text=text[last_index : match.start()]))
+        parts.append(_PausePart(kind="pause", seconds=float(match.group(1))))
+        last_index = match.end()
+    if last_index < len(text):
+        parts.append(_TextPart(kind="text", text=text[last_index:]))
+    return parts
+
+
+def _merge_settings(
+    base: _ComposerSettings,
+    override: _ComposerSettings,
+) -> _ComposerSettings:
+    return _ComposerSettings(
+        voice_id=override.voice_id if override.voice_id is not None else base.voice_id,
+        model=override.model if override.model is not None else base.model,
+        language=override.language if override.language is not None else base.language,
+        prompt=override.prompt if override.prompt is not None else base.prompt,
+        output=_merge_output(base.output, override.output),
+        seed=override.seed if override.seed is not None else base.seed,
+    )
+
+
+def _merge_output(base: Optional[Output], override: Optional[Output]) -> Optional[Output]:
+    if base is None and override is None:
+        return None
+    data = base.model_dump(exclude_none=True, exclude_unset=True) if base is not None else {}
+    if override is not None:
+        data.update(override.model_dump(exclude_none=True, exclude_unset=True))
+    return Output(**data)
+
+
+def _settings_to_request(text: str, settings: _ComposerSettings) -> TTSRequest:
+    output = _merge_output(settings.output, Output(audio_format="wav"))
+    return TTSRequest(
+        text=text,
+        voice_id=settings.voice_id or "",
+        model=settings.model if isinstance(settings.model, TTSModel) else TTSModel(settings.model),
+        language=settings.language,
+        prompt=settings.prompt,
+        output=output,
+        seed=settings.seed,
+    )
+
+
+def _parse_wav(data: bytes) -> _ParsedWav:
+    try:
+        with wave.open(io.BytesIO(data), "rb") as reader:
+            channels = reader.getnchannels()
+            sample_width = reader.getsampwidth()
+            sample_rate = reader.getframerate()
+            if channels != 1 or sample_width != 2:
+                raise ValueError("only mono 16-bit PCM WAV is supported for composed speech")
+            frames = reader.readframes(reader.getnframes())
+    except (EOFError, wave.Error) as exc:
+        raise ValueError("unsupported WAV data") from exc
+    samples = [
+        struct.unpack("<h", frames[offset : offset + 2])[0]
+        for offset in range(0, len(frames), 2)
+    ]
+    return _ParsedWav(
+        spec=_WavSpec(sample_rate=sample_rate, channels=channels, sample_width=sample_width),
+        samples=samples,
+    )
+
+
+def _encode_wav(samples: list[int], spec: _WavSpec) -> bytes:
+    payload = b"".join(struct.pack("<h", sample) for sample in samples)
+    out = io.BytesIO()
+    with wave.open(out, "wb") as writer:
+        writer.setnchannels(spec.channels)
+        writer.setsampwidth(spec.sample_width)
+        writer.setframerate(spec.sample_rate)
+        writer.writeframes(payload)
+    return out.getvalue()
+
+
+def _trim_silence(samples: list[int]) -> list[int]:
+    start = 0
+    end = len(samples)
+    while start < end and samples[start] == 0:
+        start += 1
+    while end > start and samples[end - 1] == 0:
+        end -= 1
+    return samples[start:end]
+
+
+def _seconds_to_samples(seconds: float, sample_rate: int) -> int:
+    return round(seconds * sample_rate)

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"])

{typecast_python-0.3.3.dist-info → typecast_python-0.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.3.3
+Version: 0.3.5
 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.dist-info → typecast_python-0.3.5.dist-info}/RECORD

@@ -1,16 +1,17 @@
 typecast/__init__.py,sha256=3pdJqNkXCZ7svzqab4sBR_qwyoM5E2sPjfuci1g1Ub8,1047
 typecast/_voice_clone.py,sha256=TN2tbB3b5lC5uFCBnbERhz37bNJlbv6VZ-vj70EfTs4,3464
-typecast/async_client.py,sha256=ctttygbdJWZV-cAlfYSX-PBeg3e7uMHgnPFK1uao4aw,17438
-typecast/client.py,sha256=_YsMmt9Foe8HxkADyiEjFejsQdvmwDOpf4ydqy85Kn0,15413
+typecast/async_client.py,sha256=5Tz6j2waj4XHgHhoaxM__W3YcJxUS7r8Wc3RkZA-LBc,18645
+typecast/client.py,sha256=U2X_TEesBxBBvm9ta8M9mZS7ofkx0iXIBqh1k_5mX2I,17834
+typecast/composer.py,sha256=r1kpRGlSJ1s4C1PkE7yIpGwnKtxYfIdFSLWaf8v1RAQ,9422
 typecast/conf.py,sha256=yfOHYZDvIshWWMriN5wE0GFPR8AX3zv4Rg2655OvA9Q,724
 typecast/exceptions.py,sha256=Y0ZzYebe8zOSOSAHbXfKR0G_RJgdmZXxi15Z7ZxPLIk,1568
 typecast/utils.py,sha256=XuNuX7gW8_CGKqZ-cv_tKlPVMPBluAYJBw2clwmjIMI,708
 typecast/models/__init__.py,sha256=UEPUjg86fpCMXUvAzcNgxSPPhuPwCY9aQbzK3w90Fj0,1203
 typecast/models/error.py,sha256=XomIjx7jvlCjItqzJuCAT4mXC9jwTjxR8lLDUk6P8KA,152
 typecast/models/subscription.py,sha256=EIaAAo3cCRw8LYT_O6D9AVwxqIHrWCijzl4UTx7FZB8,894
-typecast/models/tts.py,sha256=IDz4IN2d4MCkATB_rVlaEoMS7EgWlQsW0tIP8k67LHo,16001
+typecast/models/tts.py,sha256=uZ8QEevpAnRF-W4_hoEx4EA1WP1TN0ZJIak1OYE1ThQ,16370
 typecast/models/voices.py,sha256=-EXP35jDy7_G30k5bDnVrFJHp6svEDTA5jJ8oHAgXNQ,2310
-typecast_python-0.3.3.dist-info/METADATA,sha256=-FDDF0giScZ4XJPbqkV5cOUutwNA-9j-4CrsQP_rRYU,25530
-typecast_python-0.3.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-typecast_python-0.3.3.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
-typecast_python-0.3.3.dist-info/RECORD,,
+typecast_python-0.3.5.dist-info/METADATA,sha256=el2lM6XISdSo4t5q84f9bttUey6qPsJ3_iHVT_twXN0,25530
+typecast_python-0.3.5.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+typecast_python-0.3.5.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
+typecast_python-0.3.5.dist-info/RECORD,,