typecast-python 0.3.4__py3-none-any.whl → 0.3.6__py3-none-any.whl

typecast/async_client.py

@@ -191,8 +191,7 @@ class AsyncTypecast:
 
         Args:
             request: Streaming TTS request. Uses `OutputStream`, which omits
-                `volume` and `target_lufs` (not supported by the streaming
-                endpoint).
+                `volume` (not supported by the streaming endpoint).
             chunk_size: Maximum bytes returned per yielded chunk.
 
         Yields:

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,
@@ -166,6 +167,14 @@ 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],
@@ -216,8 +225,7 @@ class Typecast:
 
         Args:
             request: Streaming TTS request. Uses `OutputStream`, which omits
-                `volume` and `target_lufs` (not supported by the streaming
-                endpoint).
+                `volume` (not supported by the streaming endpoint).
             chunk_size: Maximum bytes returned per yielded chunk.
 
         Yields:

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

@@ -183,9 +183,8 @@ class TTSResponse(BaseModel):
 class OutputStream(BaseModel):
     """Audio output settings for streaming mode.
 
-    Streaming mode does not support `volume` or `target_lufs` because the
-    server has to commit each chunk before the full waveform is known.
-    Passing either field raises a validation error so misuse fails fast.
+    Streaming mode does not support `volume`, but it supports `target_lufs`
+    for absolute loudness normalization.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -195,12 +194,18 @@ class OutputStream(BaseModel):
     audio_format: Optional[str] = Field(
         default="wav", description="Audio format", examples=["wav", "mp3"]
     )
+    target_lufs: Optional[float] = Field(
+        default=None,
+        ge=-70.0,
+        le=0.0,
+        description="Target loudness in LUFS for streaming output normalization (-70 to 0).",
+    )
 
 
 class TTSRequestStream(BaseModel):
     """Request body for `POST /v1/text-to-speech/stream`.
 
-    Mirrors `TTSRequest` but uses `OutputStream` (no volume / target_lufs).
+    Mirrors `TTSRequest` but uses `OutputStream` (no volume).
     """
 
     model_config = ConfigDict(json_schema_extra={"exclude_none": True})

{typecast_python-0.3.4.dist-info → typecast_python-0.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.3.4
+Version: 0.3.6
 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.4.dist-info → typecast_python-0.3.6.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=5Tz6j2waj4XHgHhoaxM__W3YcJxUS7r8Wc3RkZA-LBc,18645
-typecast/client.py,sha256=oMjYK6NEYivY5ICSst-ZKH13ORnbzfGGlC_ZLhxk_PM,17461
+typecast/async_client.py,sha256=OwCqOUa82xvcSTbMYkRHsw_QK828gshrOV7IZotV8Ig,18611
+typecast/client.py,sha256=befvVQUzZXJ0E_almTW9aKyi2HvcjrdDirucbdd2E6U,17800
+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=uZ8QEevpAnRF-W4_hoEx4EA1WP1TN0ZJIak1OYE1ThQ,16370
+typecast/models/tts.py,sha256=W2Bp9M-xPJPODlk89P9CnLA2fwb__4SR4yoMkG_O8kA,16453
 typecast/models/voices.py,sha256=-EXP35jDy7_G30k5bDnVrFJHp6svEDTA5jJ8oHAgXNQ,2310
-typecast_python-0.3.4.dist-info/METADATA,sha256=TS2HvMhG4jAK_Y7r_dQK2Kiun3gz696PXUsuGDWZgyA,25530
-typecast_python-0.3.4.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-typecast_python-0.3.4.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
-typecast_python-0.3.4.dist-info/RECORD,,
+typecast_python-0.3.6.dist-info/METADATA,sha256=lK8mTT7BBgfvCThmHehW0tCutsi8_yIPF6U6QoHmUX4,25530
+typecast_python-0.3.6.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+typecast_python-0.3.6.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
+typecast_python-0.3.6.dist-info/RECORD,,