"""ASR（语音识别）服务接口 — Port 层。"""

from __future__ import annotations

from abc import ABC, abstractmethod
from pathlib import Path
from typing import Optional

from packages.domain.subtitle import SubtitleTimeline


class ASRService(ABC):
    """ASR 服务抽象接口。

    不同的 ASR 后端（Whisper、阿里云、腾讯云等）实现此接口，
    上层业务代码只依赖接口，不依赖具体实现。
    """

    @abstractmethod
    def transcribe(
        self,
        audio_path: Path,
        language: Optional[str] = None,
        with_word_timestamps: bool = True,
    ) -> SubtitleTimeline:
        """将音频文件转写为带时间轴的字幕。

        Args:
            audio_path: 音频文件路径（支持 wav/mp3/m4a 等常见格式）
            language: 指定语言代码（zh/en/ja 等），None 表示自动检测
            with_word_timestamps: 是否返回词级时间戳

        Returns:
            SubtitleTimeline 字幕时间轴对象

        Raises:
            ASRServiceError: 识别服务调用失败
        """
        ...


class ASRServiceError(Exception):
    """ASR 服务调用异常。"""

    def __init__(self, message: str, provider: str = "unknown"):
        self.provider = provider
        super().__init__(f"[{provider}] {message}")