"""
TTS 引擎基础接口定义
"""
from abc import ABC, abstractmethod
from typing import Optional
from io import BytesIO


class TTSEngine(ABC):
    """
    抽象 TTS 引擎基类
    
    所有 TTS 引擎实现都应继承此类并实现所有抽象方法。
    """

    @abstractmethod
    async def synthesize(
        self,
        text: str,
        language: str = "zh-CN",
        voice: Optional[str] = None,
        rate: float = 1.0,
        pitch: float = 1.0,
    ) -> BytesIO:
        """
        将文本合成为语音

        Args:
            text: 要合成的文本
            language: 语言代码，默认 zh-CN (中文)
            voice: 声音/发音人 ID，如果为 None 则使用默认声音
            rate: 语速，1.0 为正常速度，范围通常为 0.5-2.0
            pitch: 音调，1.0 为正常音调，范围通常为 0.5-2.0

        Returns:
            BytesIO 对象，包含合成后的音频数据
        """
        pass

    @abstractmethod
    async def get_supported_voices(self, language: str = "zh-CN") -> list[dict]:
        """
        获取指定语言支持的声音列表

        Args:
            language: 语言代码

        Returns:
            声音列表，每个元素是包含 name、voice_id 等信息的字典
        """
        pass

    @abstractmethod
    def get_engine_name(self) -> str:
        """
        获取引擎名称

        Returns:
            引擎名称
        """
        pass

    @abstractmethod
    def get_engine_version(self) -> str:
        """
        获取引擎版本

        Returns:
            版本号
        """
        pass