typecast-python 0.2.2__tar.gz → 0.3.0__tar.gz

{typecast_python-0.2.2 → typecast_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.2.2
+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.2 → typecast_python-0.3.0}/README.md

@@ -28,6 +28,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)
@@ -224,6 +225,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.2 → typecast_python-0.3.0}/pyproject.toml

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

{typecast_python-0.2.2 → typecast_python-0.3.0}/src/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_python-0.2.2 → typecast_python-0.3.0}/src/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_python-0.2.2 → typecast_python-0.3.0}/src/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_python-0.3.0/src/typecast/models/tts.py

@@ -0,0 +1,449 @@
+from enum import Enum
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class TTSModel(str, Enum):
+    SSFM_V21 = "ssfm-v21"
+    SSFM_V30 = "ssfm-v30"
+
+
+class LanguageCode(str, Enum):
+    """ISO 639-3 language codes supported by Typecast API
+
+    ssfm-v21: 27 languages
+    ssfm-v30: 37 languages (includes all v21 languages plus additional ones)
+    """
+
+    ENG = "eng"  # English
+    KOR = "kor"  # Korean
+    SPA = "spa"  # Spanish
+    DEU = "deu"  # German
+    FRA = "fra"  # French
+    ITA = "ita"  # Italian
+    POL = "pol"  # Polish
+    NLD = "nld"  # Dutch
+    RUS = "rus"  # Russian
+    JPN = "jpn"  # Japanese
+    ELL = "ell"  # Greek
+    TAM = "tam"  # Tamil
+    TGL = "tgl"  # Tagalog
+    FIN = "fin"  # Finnish
+    ZHO = "zho"  # Chinese
+    SLK = "slk"  # Slovak
+    ARA = "ara"  # Arabic
+    HRV = "hrv"  # Croatian
+    UKR = "ukr"  # Ukrainian
+    IND = "ind"  # Indonesian
+    DAN = "dan"  # Danish
+    SWE = "swe"  # Swedish
+    MSA = "msa"  # Malay
+    CES = "ces"  # Czech
+    POR = "por"  # Portuguese
+    BUL = "bul"  # Bulgarian
+    RON = "ron"  # Romanian
+    # ssfm-v30 additional languages
+    BEN = "ben"  # Bengali
+    HIN = "hin"  # Hindi
+    HUN = "hun"  # Hungarian
+    NAN = "nan"  # Min Nan
+    NOR = "nor"  # Norwegian
+    PAN = "pan"  # Punjabi
+    THA = "tha"  # Thai
+    TUR = "tur"  # Turkish
+    VIE = "vie"  # Vietnamese
+    YUE = "yue"  # Cantonese
+
+
+class EmotionPreset(str, Enum):
+    """Emotion preset types
+
+    ssfm-v21: normal, happy, sad, angry
+    ssfm-v30: normal, happy, sad, angry, whisper, toneup, tonedown
+    """
+
+    NORMAL = "normal"
+    HAPPY = "happy"
+    SAD = "sad"
+    ANGRY = "angry"
+    WHISPER = "whisper"  # ssfm-v30 only
+    TONEUP = "toneup"  # ssfm-v30 only
+    TONEDOWN = "tonedown"  # ssfm-v30 only
+
+
+class Prompt(BaseModel):
+    """Emotion and style settings for ssfm-v21 model"""
+
+    emotion_preset: Optional[str] = Field(
+        default="normal",
+        description="Emotion preset",
+        examples=["normal", "happy", "sad", "angry"],
+    )
+    emotion_intensity: Optional[float] = Field(default=1.0, ge=0.0, le=2.0)
+
+
+class PresetPrompt(BaseModel):
+    """Preset-based emotion control for ssfm-v30 model"""
+
+    emotion_type: Literal["preset"] = Field(
+        default="preset",
+        description="Must be 'preset' for preset-based emotion control",
+    )
+    emotion_preset: Optional[str] = Field(
+        default="normal",
+        description="Emotion preset to apply",
+        examples=["normal", "happy", "sad", "angry", "whisper", "toneup", "tonedown"],
+    )
+    emotion_intensity: Optional[float] = Field(default=1.0, ge=0.0, le=2.0)
+
+
+class SmartPrompt(BaseModel):
+    """Context-aware emotion inference for ssfm-v30 model"""
+
+    emotion_type: Literal["smart"] = Field(
+        default="smart",
+        description="Must be 'smart' for context-aware emotion inference",
+    )
+    previous_text: Optional[str] = Field(
+        default=None,
+        description="Text that comes BEFORE the main text (max 2000 chars)",
+        max_length=2000,
+    )
+    next_text: Optional[str] = Field(
+        default=None,
+        description="Text that comes AFTER the main text (max 2000 chars)",
+        max_length=2000,
+    )
+
+
+# Union type for all prompt types
+TTSPrompt = Union[Prompt, PresetPrompt, SmartPrompt]
+
+
+class Output(BaseModel):
+    volume: Optional[int] = Field(
+        default=100,
+        ge=0,
+        le=200,
+        description="Volume (0-200). Cannot be used together with target_lufs.",
+    )
+    target_lufs: Optional[float] = Field(
+        default=None,
+        ge=-70.0,
+        le=0.0,
+        description="Target loudness in LUFS for absolute loudness normalization (-70 to 0). Cannot be used together with volume.",
+    )
+    audio_pitch: Optional[int] = Field(default=0, ge=-12, le=12)
+    audio_tempo: Optional[float] = Field(default=1.0, ge=0.5, le=2.0)
+    audio_format: Optional[str] = Field(
+        default="wav", description="Audio format", examples=["wav", "mp3"]
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def check_volume_and_target_lufs(cls, data: dict) -> dict:
+        if isinstance(data, dict):
+            target_lufs = data.get("target_lufs")
+            volume = data.get("volume")
+            volume_explicitly_set = "volume" in data
+            if target_lufs is not None and volume is not None and volume_explicitly_set:
+                raise ValueError("volume and target_lufs cannot be used together")
+            if target_lufs is not None and not volume_explicitly_set:
+                data["volume"] = None
+        return data
+
+
+class TTSRequest(BaseModel):
+    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-v21"])
+    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
+
+
+class TTSResponse(BaseModel):
+    audio_data: bytes
+    duration: float
+    format: str = "wav"
+
+
+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.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    audio_pitch: Optional[int] = Field(default=0, ge=-12, le=12)
+    audio_tempo: Optional[float] = Field(default=1.0, ge=0.5, le=2.0)
+    audio_format: Optional[str] = Field(
+        default="wav", description="Audio format", examples=["wav", "mp3"]
+    )
+
+
+class TTSRequestStream(BaseModel):
+    """Request body for `POST /v1/text-to-speech/stream`.
+
+    Mirrors `TTSRequest` but uses `OutputStream` (no volume / target_lufs).
+    """
+
+    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-v21"])
+    language: Optional[Union[LanguageCode, str]] = Field(
+        None, description="Language code (ISO 639-3)", examples=["eng"]
+    )
+    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.2/src/typecast/models/tts.py

@@ -1,214 +0,0 @@
-from enum import Enum
-from typing import Literal, Optional, Union
-
-from pydantic import BaseModel, ConfigDict, Field, model_validator
-
-
-class TTSModel(str, Enum):
-    SSFM_V21 = "ssfm-v21"
-    SSFM_V30 = "ssfm-v30"
-
-
-class LanguageCode(str, Enum):
-    """ISO 639-3 language codes supported by Typecast API
-
-    ssfm-v21: 27 languages
-    ssfm-v30: 37 languages (includes all v21 languages plus additional ones)
-    """
-
-    ENG = "eng"  # English
-    KOR = "kor"  # Korean
-    SPA = "spa"  # Spanish
-    DEU = "deu"  # German
-    FRA = "fra"  # French
-    ITA = "ita"  # Italian
-    POL = "pol"  # Polish
-    NLD = "nld"  # Dutch
-    RUS = "rus"  # Russian
-    JPN = "jpn"  # Japanese
-    ELL = "ell"  # Greek
-    TAM = "tam"  # Tamil
-    TGL = "tgl"  # Tagalog
-    FIN = "fin"  # Finnish
-    ZHO = "zho"  # Chinese
-    SLK = "slk"  # Slovak
-    ARA = "ara"  # Arabic
-    HRV = "hrv"  # Croatian
-    UKR = "ukr"  # Ukrainian
-    IND = "ind"  # Indonesian
-    DAN = "dan"  # Danish
-    SWE = "swe"  # Swedish
-    MSA = "msa"  # Malay
-    CES = "ces"  # Czech
-    POR = "por"  # Portuguese
-    BUL = "bul"  # Bulgarian
-    RON = "ron"  # Romanian
-    # ssfm-v30 additional languages
-    BEN = "ben"  # Bengali
-    HIN = "hin"  # Hindi
-    HUN = "hun"  # Hungarian
-    NAN = "nan"  # Min Nan
-    NOR = "nor"  # Norwegian
-    PAN = "pan"  # Punjabi
-    THA = "tha"  # Thai
-    TUR = "tur"  # Turkish
-    VIE = "vie"  # Vietnamese
-    YUE = "yue"  # Cantonese
-
-
-class EmotionPreset(str, Enum):
-    """Emotion preset types
-
-    ssfm-v21: normal, happy, sad, angry
-    ssfm-v30: normal, happy, sad, angry, whisper, toneup, tonedown
-    """
-
-    NORMAL = "normal"
-    HAPPY = "happy"
-    SAD = "sad"
-    ANGRY = "angry"
-    WHISPER = "whisper"  # ssfm-v30 only
-    TONEUP = "toneup"  # ssfm-v30 only
-    TONEDOWN = "tonedown"  # ssfm-v30 only
-
-
-class Prompt(BaseModel):
-    """Emotion and style settings for ssfm-v21 model"""
-
-    emotion_preset: Optional[str] = Field(
-        default="normal",
-        description="Emotion preset",
-        examples=["normal", "happy", "sad", "angry"],
-    )
-    emotion_intensity: Optional[float] = Field(default=1.0, ge=0.0, le=2.0)
-
-
-class PresetPrompt(BaseModel):
-    """Preset-based emotion control for ssfm-v30 model"""
-
-    emotion_type: Literal["preset"] = Field(
-        default="preset",
-        description="Must be 'preset' for preset-based emotion control",
-    )
-    emotion_preset: Optional[str] = Field(
-        default="normal",
-        description="Emotion preset to apply",
-        examples=["normal", "happy", "sad", "angry", "whisper", "toneup", "tonedown"],
-    )
-    emotion_intensity: Optional[float] = Field(default=1.0, ge=0.0, le=2.0)
-
-
-class SmartPrompt(BaseModel):
-    """Context-aware emotion inference for ssfm-v30 model"""
-
-    emotion_type: Literal["smart"] = Field(
-        default="smart",
-        description="Must be 'smart' for context-aware emotion inference",
-    )
-    previous_text: Optional[str] = Field(
-        default=None,
-        description="Text that comes BEFORE the main text (max 2000 chars)",
-        max_length=2000,
-    )
-    next_text: Optional[str] = Field(
-        default=None,
-        description="Text that comes AFTER the main text (max 2000 chars)",
-        max_length=2000,
-    )
-
-
-# Union type for all prompt types
-TTSPrompt = Union[Prompt, PresetPrompt, SmartPrompt]
-
-
-class Output(BaseModel):
-    volume: Optional[int] = Field(
-        default=100,
-        ge=0,
-        le=200,
-        description="Volume (0-200). Cannot be used together with target_lufs.",
-    )
-    target_lufs: Optional[float] = Field(
-        default=None,
-        ge=-70.0,
-        le=0.0,
-        description="Target loudness in LUFS for absolute loudness normalization (-70 to 0). Cannot be used together with volume.",
-    )
-    audio_pitch: Optional[int] = Field(default=0, ge=-12, le=12)
-    audio_tempo: Optional[float] = Field(default=1.0, ge=0.5, le=2.0)
-    audio_format: Optional[str] = Field(
-        default="wav", description="Audio format", examples=["wav", "mp3"]
-    )
-
-    @model_validator(mode="before")
-    @classmethod
-    def check_volume_and_target_lufs(cls, data: dict) -> dict:
-        if isinstance(data, dict):
-            target_lufs = data.get("target_lufs")
-            volume = data.get("volume")
-            volume_explicitly_set = "volume" in data
-            if target_lufs is not None and volume is not None and volume_explicitly_set:
-                raise ValueError("volume and target_lufs cannot be used together")
-            if target_lufs is not None and not volume_explicitly_set:
-                data["volume"] = None
-        return data
-
-
-class TTSRequest(BaseModel):
-    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-v21"])
-    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
-
-
-class TTSResponse(BaseModel):
-    audio_data: bytes
-    duration: float
-    format: str = "wav"
-
-
-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.
-    """
-
-    model_config = ConfigDict(extra="forbid")
-
-    audio_pitch: Optional[int] = Field(default=0, ge=-12, le=12)
-    audio_tempo: Optional[float] = Field(default=1.0, ge=0.5, le=2.0)
-    audio_format: Optional[str] = Field(
-        default="wav", description="Audio format", examples=["wav", "mp3"]
-    )
-
-
-class TTSRequestStream(BaseModel):
-    """Request body for `POST /v1/text-to-speech/stream`.
-
-    Mirrors `TTSRequest` but uses `OutputStream` (no volume / target_lufs).
-    """
-
-    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-v21"])
-    language: Optional[Union[LanguageCode, str]] = Field(
-        None, description="Language code (ISO 639-3)", examples=["eng"]
-    )
-    prompt: Optional[TTSPrompt] = None
-    output: Optional[OutputStream] = None
-    seed: Optional[int] = None