"""TTS 服务抽象接口 (Port).

新增 TTS 供应商时，实现本接口即可。
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from pathlib import Path


class TtsService(ABC):
    """TTS 服务抽象基类.

    所有 TTS 供应商（Mock / 阿里云 / 讯飞 等）都需要实现本接口。
    """

    @abstractmethod
    def synthesize(
        self,
        text: str,
        *,
        voice_id: str = "",
        speed: float = 1.0,
        pitch: float = 0.0,
        output_path: Path | None = None,
        sample_rate: int = 22050,
        format: str = "wav",
    ) -> Path:
        """文本转语音合成.

        Args:
            text: 输入文本
            voice_id: 音色 ID
            speed: 语速 (0.5 ~ 2.0)
            pitch: 语调（半音，-12 ~ 12）
            output_path: 输出文件路径（None 则自动生成）
            sample_rate: 采样率
            format: 输出格式 (wav/mp3)

        Returns:
            输出音频文件路径

        Raises:
            TtsError: 合成失败
        """
        ...

    @abstractmethod
    def estimate_duration(self, text: str, *, speed: float = 1.0) -> float:
        """预估音频时长（秒）.

        用于在实际合成前估算时长，方便时间轴对齐。

        Args:
            text: 输入文本
            speed: 语速

        Returns:
            预估时长（秒）
        """
        ...

    @property
    @abstractmethod
    def provider_name(self) -> str:
        """供应商名称."""
        ...

    def available_voices(self) -> list[str]:
        """支持的音色 ID 列表."""
        return []


class TtsError(Exception):
    """TTS 合成异常."""

    pass