typecast-python 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

typecast/async_client.py

@@ -17,7 +17,9 @@ from .models import (
     SubscriptionResponse,
     TTSRequest,
     TTSRequestStream,
+    TTSRequestWithTimestamps,
     TTSResponse,
+    TTSWithTimestampsResponse,
     VoicesResponse,
     VoicesV2Filter,
     VoiceV2Response,
@@ -168,6 +170,48 @@ 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 voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API) asynchronously.
 

typecast/client.py

@@ -17,7 +17,9 @@ from .models import (
     SubscriptionResponse,
     TTSRequest,
     TTSRequestStream,
+    TTSRequestWithTimestamps,
     TTSResponse,
+    TTSWithTimestampsResponse,
     VoicesResponse,
     VoicesV2Filter,
     VoiceV2Response,
@@ -161,6 +163,45 @@ 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 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,7 +14,9 @@ from .tts import (
     TTSPrompt,
     TTSRequest,
     TTSRequestStream,
+    TTSRequestWithTimestamps,
     TTSResponse,
+    TTSWithTimestampsResponse,
 )
 from .voices import (
     AgeEnum,
@@ -25,28 +29,32 @@ from .voices import (
 )
 
 __all__ = [
-    "TTSRequest",
-    "TTSRequestStream",
-    "TTSModel",
-    "TTSPrompt",
-    "Prompt",
-    "PresetPrompt",
-    "SmartPrompt",
+    "AgeEnum",
+    "AlignmentSegmentCharacter",
+    "AlignmentSegmentWord",
+    "Credits",
     "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_python-0.2.1.dist-info → typecast_python-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.2.1
+Version: 0.3.0
 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,44 @@ 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.
+
 ---
 
 ## Supported Languages

{typecast_python-0.2.1.dist-info → typecast_python-0.3.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 typecast/__init__.py,sha256=3pdJqNkXCZ7svzqab4sBR_qwyoM5E2sPjfuci1g1Ub8,1047
-typecast/async_client.py,sha256=NJY2CWuCD3CVcqHuNwezIk39X8YTnkpQeJGdfhv6bqw,12341
-typecast/client.py,sha256=HzCSGDglsCz880x8lXesHFXQIcivc7KXImWiXehWvQc,10514
+typecast/async_client.py,sha256=vJ6pRVkdKBdiGQHsuMDsRTA9uQPLYucDxNDZBwr1nJk,14231
+typecast/client.py,sha256=0UZnK_OqYJFvd0MSjIogWFmnCVmrXMrfDSom9gih6oM,12261
 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/__init__.py,sha256=5XgoOyXO_z78hjpE4dBK-CE6SPhlnb00sFoIb4bW7Ys,1167
 typecast/models/error.py,sha256=XomIjx7jvlCjItqzJuCAT4mXC9jwTjxR8lLDUk6P8KA,152
 typecast/models/subscription.py,sha256=EIaAAo3cCRw8LYT_O6D9AVwxqIHrWCijzl4UTx7FZB8,894
-typecast/models/tts.py,sha256=clwrqky7CtcKjGtLY1h1hnyn2MXXJjXEaZ8iVZXK85c,6739
+typecast/models/tts.py,sha256=IDz4IN2d4MCkATB_rVlaEoMS7EgWlQsW0tIP8k67LHo,16001
 typecast/models/voices.py,sha256=VwmK_Ts17QccAaClGYqqstIGJ5RT9Qgj2kxqEoDr6z4,1659
-typecast_python-0.2.1.dist-info/METADATA,sha256=mbZU56hfyD5sMburfJOOLg8EjJo8iQVKQZAOp93rXe0,22881
-typecast_python-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-typecast_python-0.2.1.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
-typecast_python-0.2.1.dist-info/RECORD,,
+typecast_python-0.3.0.dist-info/METADATA,sha256=Q156X-kyJJr6qsQ7Sq_JscND1QBBTqcQ8OuTmVbiHOo,24197
+typecast_python-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+typecast_python-0.3.0.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
+typecast_python-0.3.0.dist-info/RECORD,,