typecast-python 0.2.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

typecast/_voice_clone.py

@@ -0,0 +1,89 @@
+"""Internal helpers for instant cloning (sync/async shared)."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import BinaryIO, Union
+
+CLONING_MAX_FILE_SIZE = 25 * 1024 * 1024  # must match typecast-api `cloning_max_file_size`
+NAME_MIN_LENGTH = 1
+NAME_MAX_LENGTH = 30
+ALLOWED_CLONE_MODELS = frozenset({"ssfm-v21", "ssfm-v30"})
+CUSTOM_VOICE_ID_PREFIX = "uc_"
+
+AudioInput = Union[str, Path, bytes, BinaryIO]
+
+
+def normalize_clone_model(model: object) -> str:
+    """Coerce ``model`` to its string form and reject values outside the API contract.
+
+    Accepts a ``TTSModel`` enum (uses ``.value``) or a string. Raises ``ValueError``
+    when the resolved value is not in :data:`ALLOWED_CLONE_MODELS` so callers fail
+    fast client-side instead of relying on a 422 from the API.
+    """
+    model_str = model.value if hasattr(model, "value") else str(model)
+    if model_str not in ALLOWED_CLONE_MODELS:
+        allowed = ", ".join(sorted(ALLOWED_CLONE_MODELS))
+        raise ValueError(f"model must be one of: {allowed}; got {model_str!r}")
+    return model_str
+
+
+def validate_custom_voice_id(voice_id: str) -> None:
+    """Reject non-custom voice ids before they reach the DELETE endpoint."""
+    if not isinstance(voice_id, str) or not voice_id.startswith(CUSTOM_VOICE_ID_PREFIX):
+        raise ValueError(
+            f"voice_id must start with {CUSTOM_VOICE_ID_PREFIX!r}; got {voice_id!r}"
+        )
+
+
+def validate_clone_inputs(audio: AudioInput, name: str) -> tuple[bytes, str]:
+    """Pre-validate `clone_voice` inputs and return (audio_bytes, filename).
+
+    Args:
+        audio: One of file path (str/Path), raw bytes, or readable binary file object.
+        name: Voice name (1-30 chars).
+
+    Returns:
+        (audio_bytes, filename) — filename is derived from the path/file object,
+        or defaults to "audio.wav" when caller passes raw bytes.
+
+    Raises:
+        ValueError: name length out of range or file too large.
+        FileNotFoundError: path argument refers to a non-existent file.
+        TypeError: audio is none of the accepted types.
+    """
+    if not (NAME_MIN_LENGTH <= len(name) <= NAME_MAX_LENGTH):
+        raise ValueError(
+            f"name must be {NAME_MIN_LENGTH}-{NAME_MAX_LENGTH} characters; got {len(name)}"
+        )
+
+    if isinstance(audio, (str, Path)):
+        path = Path(audio)
+        if not path.exists() or not path.is_file():
+            raise FileNotFoundError(f"audio file not found: {path}")
+        audio_bytes = path.read_bytes()
+        filename = path.name
+    elif isinstance(audio, (bytes, bytearray)):
+        audio_bytes = bytes(audio)
+        filename = "audio.wav"
+    elif hasattr(audio, "read"):
+        audio_bytes = audio.read()
+        if isinstance(audio_bytes, bytearray):
+            audio_bytes = bytes(audio_bytes)
+        if not isinstance(audio_bytes, bytes):
+            raise TypeError(
+                "audio file object must be opened in binary mode and return bytes"
+            )
+        raw_name = getattr(audio, "name", None) or "audio.wav"
+        filename = os.path.basename(str(raw_name).replace("\\", "/"))
+    else:
+        raise TypeError(
+            "audio must be a file path (str/Path), bytes, or readable binary file object"
+        )
+
+    if len(audio_bytes) > CLONING_MAX_FILE_SIZE:
+        raise ValueError(
+            f"audio file exceeds 25MB limit; got {len(audio_bytes)} bytes"
+        )
+
+    return audio_bytes, filename

typecast/async_client.py

@@ -1,8 +1,16 @@
-from typing import AsyncIterator, Optional
+from pathlib import Path
+from typing import AsyncIterator, BinaryIO, Optional, Union
+from urllib.parse import quote
 
 import aiohttp
 
 from . import conf
+from ._voice_clone import (
+    normalize_clone_model,
+    validate_clone_inputs,
+    validate_custom_voice_id,
+)
+from .client import _guess_audio_mime
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -14,10 +22,14 @@ from .exceptions import (
     UnprocessableEntityError,
 )
 from .models import (
+    CustomVoice,
     SubscriptionResponse,
+    TTSModel,
     TTSRequest,
     TTSRequestStream,
+    TTSRequestWithTimestamps,
     TTSResponse,
+    TTSWithTimestampsResponse,
     VoicesResponse,
     VoicesV2Filter,
     VoiceV2Response,
@@ -59,7 +71,9 @@ class AsyncTypecast:
         self.session: Optional[aiohttp.ClientSession] = None
 
     async def __aenter__(self):
-        headers = {"Content-Type": "application/json"}
+        # Auth header at session scope; per-request Content-Type is set by aiohttp
+        # (json= auto-sets application/json, data=FormData() auto-sets multipart).
+        headers = {}
         if self.api_key:
             headers["X-API-KEY"] = self.api_key
         self.session = aiohttp.ClientSession(headers=headers)
@@ -168,6 +182,119 @@ class AsyncTypecast:
             async for chunk in response.content.iter_chunked(chunk_size):
                 yield chunk
 
+    async def text_to_speech_with_timestamps(
+        self,
+        request: TTSRequestWithTimestamps,
+        granularity: Optional[str] = None,
+    ) -> TTSWithTimestampsResponse:
+        """Async version of ``Typecast.text_to_speech_with_timestamps``.
+
+        Args:
+            request: Request body (same shape as ``TTSRequest``).
+            granularity: Optional ``"word"`` or ``"char"`` filter.
+
+        Returns:
+            ``TTSWithTimestampsResponse`` with helpers ``to_srt()``,
+            ``to_vtt()``, ``save_audio()``.
+
+        Raises:
+            TypecastError: If the client session is not initialized
+                (i.e. used outside ``async with``).
+            ValueError: If ``granularity`` is not ``None``, ``"word"``, or ``"char"``.
+            BadRequestError, UnauthorizedError, PaymentRequiredError,
+            NotFoundError, UnprocessableEntityError, RateLimitError,
+            InternalServerError, TypecastError: per HTTP status.
+        """
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+        if granularity not in (None, "word", "char"):
+            raise ValueError(
+                f"granularity must be None, 'word', or 'char'; got {granularity!r}"
+            )
+        endpoint = "/v1/text-to-speech/with-timestamps"
+        params = {"granularity": granularity} if granularity else None
+        async with self.session.post(
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            params=params,
+        ) as response:
+            if response.status != 200:
+                text = await response.text()
+                self._handle_error(response.status, text)
+            data = await response.json()
+        return TTSWithTimestampsResponse.model_validate(data)
+
+    async def clone_voice(
+        self,
+        audio: Union[str, Path, bytes, BinaryIO],
+        name: str,
+        model: Union[str, "TTSModel"],
+    ) -> CustomVoice:
+        """Create a quick-cloned custom voice from an audio sample (async).
+
+        Args:
+            audio: Audio sample. Accepts file path (str/Path), raw bytes,
+                or a readable binary file object. Max 25 MB.
+            name: Voice name, 1-30 characters.
+            model: Engine model. ``"ssfm-v21"`` or ``"ssfm-v30"`` (or ``TTSModel`` enum).
+
+        Returns:
+            ``CustomVoice`` with ``voice_id`` (uc_ prefix), ``name``, and ``model``.
+
+        Raises:
+            ValueError: name length out of range or audio exceeds 25 MB.
+            FileNotFoundError: ``audio`` is a path to a non-existent file.
+            TypecastError: client session not initialized or HTTP error.
+        """
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+
+        audio_bytes, filename = validate_clone_inputs(audio, name)
+        model_str = normalize_clone_model(model)
+
+        form = aiohttp.FormData()
+        form.add_field("name", name)
+        form.add_field("model", model_str)
+        form.add_field(
+            "file",
+            audio_bytes,
+            filename=filename,
+            content_type=_guess_audio_mime(filename),
+        )
+        timeout = aiohttp.ClientTimeout(total=300, connect=10)
+        async with self.session.post(
+            f"{self.host}/v1/voices/clone",
+            data=form,
+            timeout=timeout,
+        ) as response:
+            if response.status != 200:
+                text = await response.text()
+                self._handle_error(response.status, text)
+            body = await response.json()
+            return CustomVoice.model_validate(body)
+
+    async def delete_voice(self, voice_id: str) -> None:
+        """Soft-delete a custom voice (async).
+
+        Args:
+            voice_id: Voice identifier with ``uc_`` prefix.
+
+        Raises:
+            TypecastError subclasses: per HTTP status from the API.
+        """
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+
+        validate_custom_voice_id(voice_id)
+        timeout = aiohttp.ClientTimeout(total=60, connect=10)
+        async with self.session.delete(
+            f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
+            timeout=timeout,
+        ) as response:
+            if response.status not in (200, 204):
+                text = await response.text()
+                self._handle_error(response.status, text)
+
     async def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API) asynchronously.
 

typecast/client.py

@@ -1,8 +1,15 @@
-from typing import Iterator, Optional
+from pathlib import Path
+from typing import BinaryIO, Iterator, Optional, Union
+from urllib.parse import quote
 
 import requests
 
 from . import conf
+from ._voice_clone import (
+    normalize_clone_model,
+    validate_clone_inputs,
+    validate_custom_voice_id,
+)
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -14,16 +21,30 @@ from .exceptions import (
     UnprocessableEntityError,
 )
 from .models import (
+    CustomVoice,
     SubscriptionResponse,
+    TTSModel,
     TTSRequest,
     TTSRequestStream,
+    TTSRequestWithTimestamps,
     TTSResponse,
+    TTSWithTimestampsResponse,
     VoicesResponse,
     VoicesV2Filter,
     VoiceV2Response,
 )
 
 
+def _guess_audio_mime(filename: str) -> str:
+    """Guess audio MIME type from filename extension; fall back to octet-stream."""
+    lower = filename.lower()
+    if lower.endswith(".wav"):
+        return "audio/wav"
+    if lower.endswith(".mp3"):
+        return "audio/mpeg"
+    return "application/octet-stream"
+
+
 class Typecast:
     """Synchronous client for the Typecast Text-to-Speech API.
 
@@ -161,6 +182,106 @@ class Typecast:
         finally:
             response.close()
 
+    def text_to_speech_with_timestamps(
+        self,
+        request: TTSRequestWithTimestamps,
+        granularity: Optional[str] = None,
+    ) -> TTSWithTimestampsResponse:
+        """Synthesize speech and return base64 audio + alignment timestamps.
+
+        Args:
+            request: Request body (same shape as `TTSRequest`).
+            granularity: Optional ``"word"`` or ``"char"`` to filter the
+                returned alignment arrays. Omit to receive both.
+
+        Returns:
+            ``TTSWithTimestampsResponse`` with ``audio`` (base64),
+            ``words``, ``characters``, and helper methods ``to_srt()``,
+            ``to_vtt()``, and ``save_audio()``.
+
+        Raises:
+            ValueError: If ``granularity`` is not ``None``, ``"word"``, or ``"char"``.
+            BadRequestError, UnauthorizedError, PaymentRequiredError,
+            NotFoundError, UnprocessableEntityError, RateLimitError,
+            InternalServerError, TypecastError: per HTTP status.
+        """
+        if granularity not in (None, "word", "char"):
+            raise ValueError(
+                f"granularity must be None, 'word', or 'char'; got {granularity!r}"
+            )
+        endpoint = "/v1/text-to-speech/with-timestamps"
+        params = {"granularity": granularity} if granularity else None
+        response = self.session.post(
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            params=params,
+            timeout=(10, 300),
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return TTSWithTimestampsResponse.model_validate(response.json())
+
+    def clone_voice(
+        self,
+        audio: Union[str, Path, bytes, BinaryIO],
+        name: str,
+        model: Union[str, "TTSModel"],
+    ) -> CustomVoice:
+        """Create a quick-cloned custom voice from an audio sample.
+
+        Args:
+            audio: Audio sample. Accepts file path (str/Path), raw bytes,
+                or a readable binary file object. Max 25 MB.
+            name: Voice name, 1-30 characters.
+            model: Engine model. ``"ssfm-v21"`` or ``"ssfm-v30"`` (or ``TTSModel`` enum).
+
+        Returns:
+            ``CustomVoice`` with ``voice_id`` (uc_ prefix), ``name``, and ``model``.
+            Use ``voice_id`` directly with ``text_to_speech`` to synthesize.
+
+        Raises:
+            ValueError: name length out of range or audio exceeds 25 MB.
+            FileNotFoundError: ``audio`` is a path to a non-existent file.
+            TypecastError subclasses: per HTTP status from the API.
+        """
+        audio_bytes, filename = validate_clone_inputs(audio, name)
+        model_str = normalize_clone_model(model)
+
+        files = {
+            "file": (filename, audio_bytes, _guess_audio_mime(filename)),
+        }
+        data = {"name": name, "model": model_str}
+        # Remove the session-level Content-Type so requests can set the
+        # correct multipart/form-data boundary for this request.
+        response = self.session.post(
+            f"{self.host}/v1/voices/clone",
+            files=files,
+            data=data,
+            headers={"Content-Type": None},
+            timeout=(10, 300),
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return CustomVoice.model_validate(response.json())
+
+    def delete_voice(self, voice_id: str) -> None:
+        """Soft-delete a custom voice.
+
+        Args:
+            voice_id: Voice identifier with ``uc_`` prefix (returned by ``clone_voice``).
+
+        Raises:
+            TypecastError subclasses: per HTTP status from the API
+                (e.g., ``NotFoundError`` if the voice doesn't exist or isn't owned).
+        """
+        validate_custom_voice_id(voice_id)
+        response = self.session.delete(
+            f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
+            timeout=(10, 60),
+        )
+        if response.status_code not in (200, 204):
+            self._handle_error(response.status_code, response.text)
+
     def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API).
 

typecast/models/__init__.py

@@ -1,6 +1,8 @@
 from .error import Error
 from .subscription import Credits, Limits, PlanTier, SubscriptionResponse
 from .tts import (
+    AlignmentSegmentCharacter,
+    AlignmentSegmentWord,
     EmotionPreset,
     LanguageCode,
     Output,
@@ -12,10 +14,13 @@ from .tts import (
     TTSPrompt,
     TTSRequest,
     TTSRequestStream,
+    TTSRequestWithTimestamps,
     TTSResponse,
+    TTSWithTimestampsResponse,
 )
 from .voices import (
     AgeEnum,
+    CustomVoice,
     GenderEnum,
     ModelInfo,
     UseCaseEnum,
@@ -25,28 +30,33 @@ from .voices import (
 )
 
 __all__ = [
-    "TTSRequest",
-    "TTSRequestStream",
-    "TTSModel",
-    "TTSPrompt",
-    "Prompt",
-    "PresetPrompt",
-    "SmartPrompt",
+    "AgeEnum",
+    "AlignmentSegmentCharacter",
+    "AlignmentSegmentWord",
+    "Credits",
+    "CustomVoice",
     "EmotionPreset",
+    "Error",
+    "GenderEnum",
+    "LanguageCode",
+    "Limits",
+    "ModelInfo",
     "Output",
     "OutputStream",
+    "PlanTier",
+    "Prompt",
+    "PresetPrompt",
+    "SmartPrompt",
+    "SubscriptionResponse",
+    "TTSModel",
+    "TTSPrompt",
+    "TTSRequest",
+    "TTSRequestStream",
+    "TTSRequestWithTimestamps",
     "TTSResponse",
-    "VoicesResponse",
+    "TTSWithTimestampsResponse",
+    "UseCaseEnum",
     "VoiceV2Response",
+    "VoicesResponse",
     "VoicesV2Filter",
-    "ModelInfo",
-    "GenderEnum",
-    "AgeEnum",
-    "UseCaseEnum",
-    "Error",
-    "LanguageCode",
-    "PlanTier",
-    "Credits",
-    "Limits",
-    "SubscriptionResponse",
 ]

typecast/models/tts.py

@@ -212,3 +212,238 @@ class TTSRequestStream(BaseModel):
     prompt: Optional[TTSPrompt] = None
     output: Optional[OutputStream] = None
     seed: Optional[int] = None
+
+
+class AlignmentSegmentWord(BaseModel):
+    """A single word-level alignment segment between transcript and audio."""
+
+    text: str = Field(description="Text fragment (with attached punctuation).")
+    start: float = Field(ge=0, description="Start time in seconds.")
+    end: float = Field(ge=0, description="End time in seconds.")
+
+    @model_validator(mode="after")
+    def _validate_span(self):
+        if self.end < self.start:
+            raise ValueError("end must be greater than or equal to start")
+        return self
+
+
+class AlignmentSegmentCharacter(BaseModel):
+    """A single character-level alignment segment between transcript and audio."""
+
+    text: str = Field(description="Character fragment (with punctuation/whitespace).")
+    start: float = Field(ge=0, description="Start time in seconds.")
+    end: float = Field(ge=0, description="End time in seconds.")
+
+    @model_validator(mode="after")
+    def _validate_span(self):
+        if self.end < self.start:
+            raise ValueError("end must be greater than or equal to start")
+        return self
+
+
+class TTSRequestWithTimestamps(BaseModel):
+    """Request body for `POST /v1/text-to-speech/with-timestamps`.
+
+    Mirrors `TTSRequest` (voice_id, text, model, language, prompt, output, seed).
+    The optional `granularity` query parameter is *not* part of this body — pass
+    it as a method argument to `text_to_speech_with_timestamps()`.
+    """
+
+    model_config = ConfigDict(json_schema_extra={"exclude_none": True})
+
+    voice_id: str = Field(
+        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+    )
+    text: str = Field(description="Text", examples=["Hello. How are you?"])
+    model: TTSModel = Field(description="Voice model name", examples=["ssfm-v30"])
+    language: Optional[Union[LanguageCode, str]] = Field(
+        None, description="Language code (ISO 639-3)", examples=["eng"]
+    )
+    prompt: Optional[TTSPrompt] = None
+    output: Optional[Output] = None
+    seed: Optional[int] = None
+
+
+# --- timestamp captioning helpers (module-level, shared by SRT/VTT) ---
+
+_SENTENCE_TERMINATORS = (".", "?", "!", "。", "？", "！")
+_MAX_CAPTION_SECONDS = 7.0
+_MAX_CAPTION_CHARS = 42
+
+
+def _segments_for_captioning(words, characters):
+    """Pick which segment list to use, returning (segments, word_mode) tuple.
+
+    - words with >= 2 entries -> words (word_mode=True: join parts with space)
+    - else if characters with >= 1 entry -> characters (word_mode=False: concat directly)
+    - single-entry words with no characters -> words (word_mode=True, one cue)
+    - else -> ValueError
+
+    Raises ValueError if more than 50% of segments have empty text (defense-in-depth:
+    the server contract should never produce majority-empty alignment arrays).
+    """
+    if words and len(words) >= 2:
+        segs = words
+    elif characters and len(characters) >= 1:
+        return characters, False
+    elif words and len(words) == 1 and not characters:
+        segs = words  # English single-cue is still valid
+    else:
+        raise ValueError("no alignment segments to caption from")
+
+    empty_count = sum(1 for s in segs if not s.text.strip())
+    if empty_count > len(segs) / 2:
+        raise ValueError("alignment segments contain empty text")
+    return segs, True
+
+
+def _group_into_cues(
+    segments,
+    word_mode: bool = False,
+    max_seconds: float = _MAX_CAPTION_SECONDS,
+    max_chars: int = _MAX_CAPTION_CHARS,
+):
+    """Group segments into caption cues using shared rules:
+    - Split on sentence terminator at end of segment text.
+    - Split BEFORE appending if adding the segment would push the cue past
+      max_seconds or max_chars (hard cap). Defaults follow BBC/Netflix subtitle
+      guidelines (7.0s / 42 chars).
+
+    word_mode=True: parts are joined with a single space.
+    word_mode=False: parts are concatenated directly.
+
+    Returns list[(text, start, end)] tuples.
+    """
+    cues = []
+    cur_text_parts = []
+    cur_start = None
+    last_end = None
+
+    def _joined():
+        if word_mode:
+            return " ".join(cur_text_parts).strip()
+        return "".join(cur_text_parts).strip()
+
+    def _flush(end_time):
+        text = _joined()
+        if text:
+            cues.append((text, cur_start, end_time))
+
+    for seg in segments:
+        if cur_text_parts and cur_start is not None and last_end is not None:
+            if word_mode:
+                would_be_text = " ".join([*cur_text_parts, seg.text]).strip()
+            else:
+                would_be_text = "".join([*cur_text_parts, seg.text]).strip()
+            would_exceed_seconds = (seg.end - cur_start) > max_seconds
+            would_exceed_chars = len(would_be_text) > max_chars
+            if would_exceed_seconds or would_exceed_chars:
+                _flush(last_end)
+                cur_text_parts = []
+                cur_start = None
+
+        if cur_start is None:
+            cur_start = seg.start
+        cur_text_parts.append(seg.text)
+        last_end = seg.end
+
+        ends_in_sentence = seg.text.rstrip().endswith(_SENTENCE_TERMINATORS)
+        if ends_in_sentence:
+            _flush(seg.end)
+            cur_text_parts = []
+            cur_start = None
+
+    if cur_text_parts and last_end is not None:
+        _flush(last_end)
+    return cues
+
+
+def _format_srt_time(seconds: float) -> str:
+    total_ms = int(round(seconds * 1000))
+    hh, rem = divmod(total_ms, 3600 * 1000)
+    mm, rem = divmod(rem, 60 * 1000)
+    ss, ms = divmod(rem, 1000)
+    return f"{hh:02d}:{mm:02d}:{ss:02d},{ms:03d}"
+
+
+def _format_vtt_time(seconds: float) -> str:
+    """Format time for WebVTT format: HH:MM:SS.mmm (dot decimal, not comma)."""
+    total_ms = int(round(seconds * 1000))
+    hh, rem = divmod(total_ms, 3600 * 1000)
+    mm, rem = divmod(rem, 60 * 1000)
+    ss, ms = divmod(rem, 1000)
+    return f"{hh:02d}:{mm:02d}:{ss:02d}.{ms:03d}"
+
+
+class TTSWithTimestampsResponse(BaseModel):
+    """Response payload for `POST /v1/text-to-speech/with-timestamps`.
+
+    Contains base64-encoded audio plus optional word/character alignment arrays.
+    Helper methods (`save_audio()`, `to_srt()`, `to_vtt()`) are added in
+    subsequent tasks.
+    """
+
+    audio: str = Field(description="Base64-encoded audio bytes.")
+    audio_format: Literal["wav", "mp3"] = Field(description="Audio encoding format.")
+    audio_duration: float = Field(description="Length of audio in seconds.")
+    words: Optional[list[AlignmentSegmentWord]] = Field(
+        default=None,
+        description="Word-level timestamps; null when granularity=char.",
+    )
+    characters: Optional[list[AlignmentSegmentCharacter]] = Field(
+        default=None,
+        description="Character-level timestamps; null when granularity=word.",
+    )
+
+    @property
+    def audio_bytes(self) -> bytes:
+        """Return decoded audio bytes from the base64 `audio` field."""
+        import base64
+        return base64.b64decode(self.audio, validate=True)
+
+    def save_audio(self, path: str) -> None:
+        """Write decoded audio bytes to `path`."""
+        with open(path, "wb") as f:
+            f.write(self.audio_bytes)
+
+    def to_srt(self, max_seconds: float = 7.0, max_chars: int = 42) -> str:
+        """Return SRT-formatted caption string for this TTS response.
+
+        Uses word-level segments when words has >= 2 entries; falls back to
+        character-level segments otherwise (e.g. jpn/zho collapsed words).
+        Cues are split on sentence terminators (. ? ! 。 ？ ！) or when a cue
+        would exceed max_seconds or max_chars. Default values follow BBC/Netflix
+        subtitle guidelines (7.0s / 42 chars).
+        """
+        segments, word_mode = _segments_for_captioning(self.words, self.characters)
+        cues = _group_into_cues(segments, word_mode=word_mode, max_seconds=max_seconds, max_chars=max_chars)
+        if not cues:
+            raise ValueError("no alignment segments to caption from")
+        lines = []
+        for idx, (text, start, end) in enumerate(cues, start=1):
+            lines.append(str(idx))
+            lines.append(f"{_format_srt_time(start)} --> {_format_srt_time(end)}")
+            lines.append(text)
+            lines.append("")
+        return "\n".join(lines) + "\n"
+
+    def to_vtt(self, max_seconds: float = 7.0, max_chars: int = 42) -> str:
+        """Return WebVTT-formatted caption string for this TTS response.
+
+        Uses word-level segments when words has >= 2 entries; falls back to
+        character-level segments otherwise (e.g. jpn/zho collapsed words).
+        Cues are split on sentence terminators (. ? ! 。 ？ ！) or when a cue
+        would exceed max_seconds or max_chars. Default values follow BBC/Netflix
+        subtitle guidelines (7.0s / 42 chars).
+        """
+        segments, word_mode = _segments_for_captioning(self.words, self.characters)
+        cues = _group_into_cues(segments, word_mode=word_mode, max_seconds=max_seconds, max_chars=max_chars)
+        if not cues:
+            raise ValueError("no alignment segments to caption from")
+        lines = ["WEBVTT", ""]
+        for text, start, end in cues:
+            lines.append(f"{_format_vtt_time(start)} --> {_format_vtt_time(end)}")
+            lines.append(text)
+            lines.append("")
+        return "\n".join(lines) + "\n"

typecast/models/voices.py

@@ -1,7 +1,7 @@
 from enum import Enum
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from .tts import TTSModel
 
@@ -75,3 +75,18 @@ class VoicesV2Filter(BaseModel):
     gender: Optional[GenderEnum] = None
     age: Optional[AgeEnum] = None
     use_cases: Optional[UseCaseEnum] = None
+
+
+class CustomVoice(BaseModel):
+    """Quick-cloned custom voice returned by `POST /v1/voices/clone`.
+
+    Attributes:
+        voice_id: Custom voice identifier with `uc_` prefix.
+            Use this value as `voice_id` in `text_to_speech` / `text_to_speech_with_timestamps`.
+        name: Human-readable name (1-30 chars).
+        model: Engine model the voice was cloned for (`ssfm-v21` or `ssfm-v30`).
+    """
+
+    voice_id: str = Field(..., description="Custom voice identifier (uc_ prefix)")
+    name: str = Field(..., description="Human-readable voice name")
+    model: str = Field(..., description="Engine model: ssfm-v21 or ssfm-v30")

{typecast_python-0.2.2.dist-info → typecast_python-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.2.2
+Version: 0.3.1
 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
@@ -269,6 +269,7 @@ Convert text to lifelike speech using AI-powered voices
   - [Voice Discovery](#voice-discovery)
   - [Emotion Control](#emotion-control)
   - [Async Client](#async-client)
+  - [Timestamp TTS](#timestamp-tts)
 - [Supported Languages](#supported-languages)
 - [Error Handling](#error-handling)
 - [License](#license)
@@ -465,6 +466,91 @@ async def main():
 asyncio.run(main())
 ```
 
+### Timestamp TTS
+
+Use `text_to_speech_with_timestamps()` to receive base64 audio plus
+word/character-level timestamps aligned with the synthesized speech. The
+result object exposes `save_audio()`, `to_srt()`, and `to_vtt()` helpers
+so you can finish the typical "audio + subtitles" flow in one line.
+
+```python
+from typecast import Typecast
+from typecast.models import TTSRequestWithTimestamps
+
+client = Typecast(api_key="YOUR_API_KEY")
+resp = client.text_to_speech_with_timestamps(
+    TTSRequestWithTimestamps(
+        voice_id="tc_60e5426de8b95f1d3000d7b5",
+        text="Hello. How are you?",
+        model="ssfm-v30",
+        language="eng",
+    ),
+)
+resp.save_audio("hello.wav")
+print(resp.to_srt())   # SRT subtitles
+print(resp.to_vtt())   # WebVTT subtitles
+```
+
+Caption splits follow BBC/Netflix subtitle guidelines: 7s/42-char cue maximums.
+
+```python
+# Real-time karaoke / highlight: iterate the words array directly.
+for w in resp.words or []:
+    print(f"[{w.start:.2f}s - {w.end:.2f}s] {w.text}")
+```
+
+Pass `granularity="word"` or `granularity="char"` to receive only one of
+the two alignment arrays. For non-whitespace languages (Japanese,
+Chinese), pair with `granularity="char"` — word-level alignment will
+collapse the entire sentence into a single segment.
+
+### Instant cloning
+
+Clone a custom voice from a short audio sample (≤ 25 MB), then use it just like any built-in voice. The cloned voice ID has a `uc_` prefix and works with `text_to_speech` directly.
+
+```python
+from typecast import Typecast
+from typecast.models import TTSRequest
+
+client = Typecast(api_key="YOUR_API_KEY")
+
+# 1) Clone
+voice = client.clone_voice(
+    audio="path/to/sample.wav",   # str path | Path | bytes | file object
+    name="my-voice",               # 1-30 chars
+    model="ssfm-v30",              # or "ssfm-v21"
+)
+print(voice.voice_id)              # uc_64a1b2...
+
+# 2) Synthesize with the cloned voice
+audio = client.text_to_speech(TTSRequest(
+    text="Hello from my cloned voice!",
+    voice_id=voice.voice_id,
+    model="ssfm-v30",
+))
+with open("output.wav", "wb") as f:
+    f.write(audio.audio_data)
+
+# 3) Delete when done
+client.delete_voice(voice.voice_id)
+```
+
+**Limits**
+
+- Audio file: max 25 MB. Supported formats: WAV, MP3.
+- Voice name: 1–30 characters.
+- Model: `ssfm-v21` or `ssfm-v30`.
+
+**Async usage** is identical via `AsyncTypecast`:
+
+```python
+from typecast import AsyncTypecast
+
+async with AsyncTypecast(api_key="YOUR_API_KEY") as client:
+    voice = await client.clone_voice(audio="sample.wav", name="my-voice", model="ssfm-v30")
+    await client.delete_voice(voice.voice_id)
+```
+
 ---
 
 ## Supported Languages

typecast_python-0.3.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+typecast/__init__.py,sha256=3pdJqNkXCZ7svzqab4sBR_qwyoM5E2sPjfuci1g1Ub8,1047
+typecast/_voice_clone.py,sha256=TN2tbB3b5lC5uFCBnbERhz37bNJlbv6VZ-vj70EfTs4,3464
+typecast/async_client.py,sha256=8mab1ai_P1TdQilR1l29n5Cg40F7lN960shODemXXWs,17287
+typecast/client.py,sha256=PRFF7hj8Ih88dRl0ZiLcRRD8N4ofPPbYMZAKpk_b89w,15212
+typecast/conf.py,sha256=Fn_T4XW7BaHRnj0tP11BT5at3Y-db7oGcbBA_E1fmF0,479
+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/voices.py,sha256=-EXP35jDy7_G30k5bDnVrFJHp6svEDTA5jJ8oHAgXNQ,2310
+typecast_python-0.3.1.dist-info/METADATA,sha256=pBQbgmi4_SX07Dx5RKO-YPBXMDAPyZwcQXDO3JWoQV4,25529
+typecast_python-0.3.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+typecast_python-0.3.1.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
+typecast_python-0.3.1.dist-info/RECORD,,

typecast_python-0.2.2.dist-info/RECORD

@@ -1,15 +0,0 @@
-typecast/__init__.py,sha256=3pdJqNkXCZ7svzqab4sBR_qwyoM5E2sPjfuci1g1Ub8,1047
-typecast/async_client.py,sha256=NJY2CWuCD3CVcqHuNwezIk39X8YTnkpQeJGdfhv6bqw,12341
-typecast/client.py,sha256=HzCSGDglsCz880x8lXesHFXQIcivc7KXImWiXehWvQc,10514
-typecast/conf.py,sha256=Fn_T4XW7BaHRnj0tP11BT5at3Y-db7oGcbBA_E1fmF0,479
-typecast/exceptions.py,sha256=Y0ZzYebe8zOSOSAHbXfKR0G_RJgdmZXxi15Z7ZxPLIk,1568
-typecast/utils.py,sha256=XuNuX7gW8_CGKqZ-cv_tKlPVMPBluAYJBw2clwmjIMI,708
-typecast/models/__init__.py,sha256=uvDWzZPo01mjHreUtlHBMYiuZ84Tb02LzU3ZpszYg1I,923
-typecast/models/error.py,sha256=XomIjx7jvlCjItqzJuCAT4mXC9jwTjxR8lLDUk6P8KA,152
-typecast/models/subscription.py,sha256=EIaAAo3cCRw8LYT_O6D9AVwxqIHrWCijzl4UTx7FZB8,894
-typecast/models/tts.py,sha256=clwrqky7CtcKjGtLY1h1hnyn2MXXJjXEaZ8iVZXK85c,6739
-typecast/models/voices.py,sha256=VwmK_Ts17QccAaClGYqqstIGJ5RT9Qgj2kxqEoDr6z4,1659
-typecast_python-0.2.2.dist-info/METADATA,sha256=2c0Er6ggl9ZnPbr9iyFUAIBLvZdsxH9kHDIwRIEdTOU,22881
-typecast_python-0.2.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-typecast_python-0.2.2.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
-typecast_python-0.2.2.dist-info/RECORD,,