"""Abstract TTS backend interface."""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import List

import numpy as np


@dataclass(frozen=True)
class Voice:
    """A speaker/voice exposed by a backend."""

    name: str
    language_code: str
    description: str = ""


@dataclass
class SynthesisResult:
    """Output of a single synthesis call: mono float32 audio at a known rate."""

    audio: np.ndarray
    sample_rate_hz: int


class TTSBackend(ABC):
    """Common interface for every TTS engine."""

    #: Short identifier stored in dataset metadata (e.g. "google_cloud_tts").
    source: str = "tts"

    @abstractmethod
    def prepare(self) -> None:
        """Validate credentials, download models and list voices.

        Must raise if the backend cannot be used.
        """

    @abstractmethod
    def voices(self) -> List[Voice]:
        """Return the selected voices to synthesize with."""

    @abstractmethod
    def synthesize(self, text: str, voice: Voice) -> SynthesisResult:
        """Synthesize ``text`` with ``voice`` into mono float32 audio."""