Types & Errors

from kugelaudio import KugelAudio
from kugelaudio.exceptions import (
    KugelAudioError,
    AuthenticationError,
    RateLimitError,
    InsufficientCreditsError,
    ValidationError,
    NotFoundError,
    ServerRestartingError,
)
# ConnectionError is exported from the package root as KugelAudioConnectionError
from kugelaudio import KugelAudioConnectionError

try:
    audio = client.tts.generate(text="Hello!", voice_id=1071)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded, please wait")
except InsufficientCreditsError:
    print("Not enough credits, please top up")
except NotFoundError:
    print("Voice, model, or dictionary not found")
except ValidationError as e:
    print(f"Invalid request: {e}")
except ServerRestartingError as e:
    print(f"Server restarting, retry in {e.retry_after}s")
except KugelAudioConnectionError as e:
    print(f"WebSocket/network error: {e}")
except KugelAudioError as e:
    print(f"API error: {e}")

class AudioChunk:
    audio: bytes          # Raw bytes in the requested output format
    index: int            # Chunk index (0-based)
    sample_rate: int      # Requested sample rate (24000 by default)
    samples: int          # Number of samples in chunk

    @property
    def duration_seconds(self) -> float:
        """Duration of this chunk in seconds."""

    def to_float32(self) -> list[float]:
        """Convert PCM16 output to float32 samples in [-1.0, 1.0]."""

class AudioResponse:
    audio: bytes                          # Complete bytes in the requested output format
    sample_rate: int                      # Sample rate of the returned audio
    samples: int                          # Total samples
    duration_ms: float                    # Duration in milliseconds
    generation_ms: float                  # Generation time in milliseconds
    rtf: float                            # Real-time factor
    word_timestamps: list[WordTimestamp]  # Per-word timing (when word_timestamps=True)
    usage: SessionUsage | None            # Per-request usage (audio time + charge); None if not reported

    @property
    def duration_seconds(self) -> float:
        """Duration in seconds."""

    def to_float32(self) -> list[float]:
        """Convert PCM16 output to float32 samples in [-1.0, 1.0]."""

    def save(self, path: str, format: str = "wav") -> None:
        """Save audio to a file. format is 'wav' or 'raw' (headerless PCM)."""

    def to_wav_bytes(self) -> bytes:
        """Wrap PCM16 output in a WAV header."""

class WordTimestamp:
    word: str          # The aligned word
    start_ms: int      # Start time in milliseconds (relative to chunk)
    end_ms: int        # End time in milliseconds (relative to chunk)
    char_start: int    # Start character offset in original text
    char_end: int      # End character offset in original text
    score: float       # Compatibility field; currently always 1.0

    @property
    def duration_ms(self) -> int:
        """end_ms - start_ms."""

class SessionUsage:
    audio_seconds: float          # Audio generated (the unit we bill on)
    cost_cents: float | None      # Actual charge in EUR cents; None if undetermined
    currency: str | None          # Currency of cost_cents ("eur"); set only when cost_cents is
    characters: int | None        # Input characters; omitted on multi-context per-context usage
    model_id: str | None          # Model that produced the audio

    @property
    def cost_available(self) -> bool:
        """True when an authoritative charge was returned (cost_cents is not None)."""

class Model:
    id: str                   # e.g. 'kugel-3'
    name: str                 # Human-readable name
    description: str          # Model description
    parameters: str           # Parameter-count label (e.g. '7B')
    max_input_length: int     # Maximum input characters (default 5000)
    sample_rate: int          # Output sample rate (default 24000)

class StreamConfig:
    voice_id: int | None = None  # SDK-optional; required before synthesis
    model_id: str | None = None
    cfg_scale: float = 2.0
    output_format: str | None = None  # e.g. "pcm_24000", "ulaw_8000", "alaw_8000"
    temperature: float | None = None
    max_new_tokens: int = 2048
    sample_rate: int = 24000
    flush_timeout_ms: int = 500
    max_buffer_length: int = 1000
    normalize: bool = True
    language: str | None = None
    word_timestamps: bool = False
    chunk_length_schedule: list[int] | None = None  # default [5, 80, 150, 250]
    auto_mode: bool | None = None
    speed: float = 1.0
    dictionary_ids: list[int] | None = None  # requires project_id
    project_id: int | None = None  # project whose dictionaries apply

class Dictionary:
    id: int
    project_id: int
    name: str
    description: str | None = None
    language: str | None = None
    is_active: bool = True
    created_at: str | None = None
    updated_at: str | None = None

class DictionaryEntry:
    id: int
    dictionary_id: int
    word: str
    replacement: str
    ipa: str | None = None
    case_sensitive: bool = False
    created_at: str | None = None
    updated_at: str | None = None

class DictionaryEntryList:      # paginated response from entries.list()
    entries: list[DictionaryEntry]
    total: int
    limit: int
    offset: int

class BulkReplaceResult:        # returned by entries.replace_all()
    upserted: int
    deleted: int
    total: int

from kugelaudio.models import VoiceAge, VoiceCategory, VoiceSex

class VoiceCategory(str, Enum):
    NARRATIVE_STORY, CONVERSATIONAL, CHARACTERS_ANIMATION, SOCIAL_MEDIA,
    ENTERTAINMENT_TV, ADVERTISEMENT, INFORMATIVE_EDUCATIONAL,  # sent by the API
    CLONED,  # returned for a voice with no category set
    PREMADE, DESIGNED, NARRATIVE, CHARACTERS  # older values, never returned today

class VoiceSex(str, Enum):
    MALE, FEMALE, NEUTRAL

class VoiceAge(str, Enum):
    YOUNG, MIDDLE_AGED, MIDDLE_AGE, OLD

class VoiceListResponse:
    voices: List[Voice]   # Voices on this page
    total: int            # Total number of matching voices
    limit: int            # Page size used
    offset: int           # Offset used

class Voice:
    id: int                                # Voice ID
    name: str                              # Voice name
    description: str | None = None
    category: VoiceCategory | None = None  # see Enums
    sex: VoiceSex | None = None
    age: VoiceAge | None = None
    quality: str = "mid"
    supported_languages: list[str] = []    # ['en', 'de', ...]
    sample_text: str | None = None
    avatar_url: str | None = None          # Avatar image URL
    sample_url: str | None = None          # Sample audio URL
    is_public: bool = False
    verified: bool = False

class VoiceDetail:
    id: int
    name: str
    description: str = ""
    generative_voice_description: str = ""
    supported_languages: list[str] = []
    category: VoiceCategory | None = None
    age: VoiceAge | None = None
    sex: VoiceSex | None = None
    quality: str = "mid"                   # 'low', 'mid', 'high'
    is_public: bool = False
    verified: bool = False
    pending_verification: bool = False
    sample_url: str | None = None
    avatar_url: str | None = None
    sample_text: str = ""

class VoiceReference:
    id: int
    voice_id: int
    name: str = ""
    reference_text: str = ""
    s3_path: str = ""
    audio_url: str | None = None
    is_generated: bool = False

class TranscriptionResponse:
    text: str                        # OpenAI-compatible transcript field
    transcript: str                  # KugelAudio's transcript field (same text)
    language: str                    # Language reported by the server
    duration_s: float                # Audio duration in seconds
    model: str                       # Always "luchs-1"
    model_revision: str | None       # Immutable checkpoint revision
    word_alternatives: list[WordAlternatives]  # Alternative spellings for uncertain words
    raw: dict                        # The unparsed response body

class WordAlternatives:
    raw_word_index: int
    word: str
    alternatives: list[SpellingAlternative]  # each has spelling: str, probability: float