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

{typecast_python-0.2.2 → typecast_python-0.3.1}/.gitignore

@@ -10,6 +10,8 @@
 .env.*.local
 *.env
 !.env.example
+config.yaml
+credentials.json
 
 # ----------------
 # Node.js / JavaScript
@@ -314,6 +316,9 @@ logs/
 # Audio output files (in root directories, not source code)
 *.wav
 *.mp3
+# Exception: shared test fixtures
+!test-fixtures/**/*.wav
+!test-fixtures/**/*.mp3
 # Note: Removed 'output.*' pattern as it incorrectly matches Output.java/Output.cs source files
 
 # ----------------

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

@@ -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.2.2 → typecast_python-0.3.1}/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,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.2.2 → typecast_python-0.3.1}/pyproject.toml

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

typecast_python-0.3.1/src/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_python-0.2.2 → typecast_python-0.3.1}/src/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_python-0.2.2 → typecast_python-0.3.1}/src/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).