@rookiestar/eng-lang-tutor 1.0.1

package/scripts/audio/feishu_voice.py

@@ -0,0 +1,404 @@
+#!/usr/bin/env python3
+"""
+飞书语音消息发送模块
+
+将 TTS 生成的音频转换为飞书语音格式并发送。
+
+使用示例：
+    from scripts.feishu_voice import FeishuVoiceSender
+
+    sender = FeishuVoiceSender(app_id="xxx", app_secret="xxx")
+
+    # 发送单条语音
+    await sender.send_voice(
+        receive_id="ou_xxx",
+        text="Hello, nice to meet you!"
+    )
+
+    # 发送知识点音频
+    await sender.send_keypoint_voices(
+        receive_id="ou_xxx",
+        keypoint=keypoint,
+        audio_info=audio_info
+    )
+"""
+
+import os
+import asyncio
+import aiohttp
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+
+from .converter import AudioConverter, ConversionResult
+
+
+@dataclass
+class VoiceSendResult:
+    """语音发送结果"""
+    success: bool
+    message_id: Optional[str] = None
+    error_message: Optional[str] = None
+
+
+class FeishuVoiceSender:
+    """
+    飞书语音消息发送器
+
+    工作流程：
+    1. TTS 生成 MP3 音频
+    2. 转换为 Opus 格式（飞书推荐）
+    3. 上传到飞书素材库
+    4. 发送语音消息
+    """
+
+    FEISHU_API_BASE = "https://open.feishu.cn/open-apis"
+
+    def __init__(
+        self,
+        app_id: Optional[str] = None,
+        app_secret: Optional[str] = None,
+        tenant_key: Optional[str] = None,
+        audio_dir: Optional[Path] = None
+    ):
+        """
+        初始化飞书语音发送器
+
+        Args:
+            app_id: 飞书应用 ID（可从环境变量 FEISHU_APP_ID 读取）
+            app_secret: 飞书应用密钥（可从环境变量 FEISHU_APP_SECRET 读取）
+            tenant_key: 租户密钥（自建应用无需）
+            audio_dir: 音频缓存目录
+        """
+        self.app_id = app_id or os.getenv("FEISHU_APP_ID")
+        self.app_secret = app_secret or os.getenv("FEISHU_APP_SECRET")
+        self.tenant_key = tenant_key
+
+        if not self.app_id or not self.app_secret:
+            raise ValueError(
+                "Missing Feishu credentials. Set FEISHU_APP_ID and FEISHU_APP_SECRET "
+                "environment variables or pass them to constructor."
+            )
+
+        self.audio_dir = audio_dir or Path(
+            os.getenv("OPENCLAW_STATE_DIR", "~/.openclaw/state/eng-lang-tutor")
+        ).expanduser() / "audio"
+        self.audio_dir.mkdir(parents=True, exist_ok=True)
+
+        self.converter = AudioConverter()
+        self._access_token: Optional[str] = None
+        self._token_expires: float = 0
+
+    async def _get_access_token(self) -> str:
+        """获取飞书访问令牌"""
+        import time
+
+        # 检查缓存
+        if self._access_token and time.time() < self._token_expires:
+            return self._access_token
+
+        url = f"{self.FEISHU_API_BASE}/auth/v3/tenant_access_token/internal"
+        headers = {"Content-Type": "application/json"}
+        data = {
+            "app_id": self.app_id,
+            "app_secret": self.app_secret
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, headers=headers, json=data) as resp:
+                result = await resp.json()
+
+                if result.get("code") != 0:
+                    raise RuntimeError(f"Failed to get access token: {result}")
+
+                self._access_token = result["tenant_access_token"]
+                self._token_expires = time.time() + result.get("expire", 7200) - 300
+
+                return self._access_token
+
+    async def _upload_file(self, file_path: Path, file_type: str = "opus") -> str:
+        """
+        上传文件到飞书素材库
+
+        Args:
+            file_path: 文件路径
+            file_type: 文件类型
+
+        Returns:
+            file_key
+        """
+        token = await self._get_access_token()
+
+        url = f"{self.FEISHU_API_BASE}/im/v1/files"
+        headers = {"Authorization": f"Bearer {token}"}
+
+        async with aiohttp.ClientSession() as session:
+            with open(file_path, "rb") as f:
+                form = aiohttp.FormData()
+                form.add_field("file_type", file_type)
+                form.add_field("file_name", file_path.name)
+                form.add_field("file", f, filename=file_path.name)
+
+                async with session.post(url, headers=headers, data=form) as resp:
+                    result = await resp.json()
+
+                    if result.get("code") != 0:
+                        raise RuntimeError(f"Failed to upload file: {result}")
+
+                    return result["data"]["file_key"]
+
+    async def _send_file_message(
+        self,
+        receive_id: str,
+        file_key: str,
+        receive_id_type: str = "open_id"
+    ) -> str:
+        """
+        发送文件消息
+
+        Args:
+            receive_id: 接收者 ID
+            file_key: 文件 key
+            receive_id_type: 接收者 ID 类型
+
+        Returns:
+            message_id
+        """
+        token = await self._get_access_token()
+
+        url = f"{self.FEISHU_API_BASE}/im/v1/messages"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json"
+        }
+        params = {
+            "receive_id_type": receive_id_type
+        }
+        data = {
+            "receive_id": receive_id,
+            "msg_type": "file",
+            "content": f'{{"file_key": "{file_key}"}}'
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, headers=headers, params=params, json=data) as resp:
+                result = await resp.json()
+
+                if result.get("code") != 0:
+                    raise RuntimeError(f"Failed to send message: {result}")
+
+                return result["data"]["message_id"]
+
+    async def send_voice(
+        self,
+        receive_id: str,
+        audio_path: Path,
+        receive_id_type: str = "open_id",
+        auto_convert: bool = True,
+        delete_after_send: bool = False
+    ) -> VoiceSendResult:
+        """
+        发送语音消息
+
+        Args:
+            receive_id: 接收者 ID（open_id / user_id / union_id）
+            audio_path: 音频文件路径（MP3 或 Opus）
+            receive_id_type: 接收者 ID 类型
+            auto_convert: 是否自动转换为 Opus 格式
+            delete_after_send: 发送后是否删除临时文件
+
+        Returns:
+            VoiceSendResult
+        """
+        audio_path = Path(audio_path)
+        temp_file = None
+
+        try:
+            # 如果是 MP3，转换为 Opus
+            if auto_convert and audio_path.suffix.lower() == ".mp3":
+                opus_path = audio_path.with_suffix(".opus")
+                result = self.converter.convert_to_voice(
+                    input_path=audio_path,
+                    output_path=opus_path,
+                    format="opus",
+                    sample_rate=16000
+                )
+                if not result.success:
+                    return VoiceSendResult(
+                        success=False,
+                        error_message=f"Audio conversion failed: {result.error_message}"
+                    )
+                audio_path = opus_path
+                temp_file = opus_path if delete_after_send else None
+
+            # 上传文件
+            file_key = await self._upload_file(audio_path)
+
+            # 发送消息
+            message_id = await self._send_file_message(
+                receive_id=receive_id,
+                file_key=file_key,
+                receive_id_type=receive_id_type
+            )
+
+            return VoiceSendResult(
+                success=True,
+                message_id=message_id
+            )
+
+        except Exception as e:
+            return VoiceSendResult(
+                success=False,
+                error_message=str(e)
+            )
+        finally:
+            # 清理临时文件
+            if temp_file and temp_file.exists():
+                temp_file.unlink()
+
+    async def send_voice_from_text(
+        self,
+        receive_id: str,
+        text: str,
+        voice: str = "catherine",
+        speed: float = 0.9,
+        receive_id_type: str = "open_id"
+    ) -> VoiceSendResult:
+        """
+        从文本直接生成并发送语音
+
+        Args:
+            receive_id: 接收者 ID
+            text: 要转换的文本
+            voice: 音色
+            speed: 语速
+            receive_id_type: 接收者 ID 类型
+
+        Returns:
+            VoiceSendResult
+        """
+        from .tts import TTSManager
+
+        try:
+            # 生成 TTS 音频
+            manager = TTSManager.from_env()
+            output_path = self.audio_dir / f"temp_{hash(text)}.mp3"
+
+            result = manager.synthesize(
+                text=text,
+                output_path=output_path,
+                voice=voice,
+                speed=speed
+            )
+
+            if not result.success:
+                return VoiceSendResult(
+                    success=False,
+                    error_message=f"TTS failed: {result.error_message}"
+                )
+
+            # 发送语音
+            return await self.send_voice(
+                receive_id=receive_id,
+                audio_path=output_path,
+                receive_id_type=receive_id_type,
+                auto_convert=True,
+                delete_after_send=True
+            )
+
+        except Exception as e:
+            return VoiceSendResult(
+                success=False,
+                error_message=str(e)
+            )
+
+    async def send_keypoint_voices(
+        self,
+        receive_id: str,
+        keypoint: Dict[str, Any],
+        audio_info: Dict[str, Any],
+        receive_id_type: str = "open_id",
+        include_dialogue: bool = True,
+        include_expressions: bool = True
+    ) -> List[VoiceSendResult]:
+        """
+        发送知识点的所有语音
+
+        Args:
+            receive_id: 接收者 ID
+            keypoint: 知识点数据
+            audio_info: TTS 生成的音频信息
+            receive_id_type: 接收者 ID 类型
+            include_dialogue: 是否发送对话音频
+            include_expressions: 是否发送表达音频
+
+        Returns:
+            发送结果列表
+        """
+        results = []
+        date_str = audio_info.get("generated_at", "")[:10]  # YYYY-MM-DD
+
+        # 发送对话音频
+        if include_dialogue:
+            for item in audio_info.get("dialogue", []):
+                if "error" in item:
+                    results.append(VoiceSendResult(
+                        success=False,
+                        error_message=f"Dialogue generation failed: {item['error']}"
+                    ))
+                    continue
+
+                audio_url = item.get("audio_url", "")
+                if not audio_url:
+                    continue
+
+                # 解析路径：audio/YYYY-MM-DD/filename.opus
+                parts = audio_url.split("/")
+                audio_path = self.audio_dir / parts[1] / parts[2]
+
+                if not audio_path.exists():
+                    # 尝试 MP3 扩展名
+                    audio_path = audio_path.with_suffix(".mp3")
+
+                if audio_path.exists():
+                    speaker = item.get("speaker", "")
+                    text = item.get("text", "")
+
+                    result = await self.send_voice(
+                        receive_id=receive_id,
+                        audio_path=audio_path,
+                        receive_id_type=receive_id_type,
+                        auto_convert=True
+                    )
+                    results.append(result)
+
+        # 发送表达音频
+        if include_expressions:
+            for item in audio_info.get("expressions", []):
+                if "error" in item:
+                    results.append(VoiceSendResult(
+                        success=False,
+                        error_message=f"Expression generation failed: {item['error']}"
+                    ))
+                    continue
+
+                audio_url = item.get("audio_url", "")
+                if not audio_url:
+                    continue
+
+                parts = audio_url.split("/")
+                audio_path = self.audio_dir / parts[1] / parts[2]
+
+                if not audio_path.exists():
+                    audio_path = audio_path.with_suffix(".mp3")
+
+                if audio_path.exists():
+                    result = await self.send_voice(
+                        receive_id=receive_id,
+                        audio_path=audio_path,
+                        receive_id_type=receive_id_type,
+                        auto_convert=True
+                    )
+                    results.append(result)
+
+        return results

package/scripts/audio/tts/__init__.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""
+TTS Module - Text-to-Speech integration for eng-lang-tutor
+
+Provides a unified interface for multiple TTS providers:
+- XunFei (讯飞): Free tier with 500 min/day, stable in China
+- Edge-TTS: Completely free, requires VPN in China
+
+Usage:
+    from scripts.tts import TTSManager
+
+    # Using XunFei (from environment variables)
+    manager = TTSManager.from_env()
+
+    # Using Edge-TTS (no credentials needed)
+    manager = TTSManager(provider="edge-tts")
+
+    # Generate audio for keypoint
+    audio_info = manager.generate_keypoint_audio(keypoint)
+"""
+
+from .manager import TTSManager
+from .base import TTSProvider, TTSConfig, TTSResult
+
+__all__ = [
+    "TTSManager",
+    "TTSProvider",
+    "TTSConfig",
+    "TTSResult",
+]

package/scripts/audio/tts/base.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+TTS Provider 抽象基类 - 所有 TTS 服务必须实现此接口
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, ClassVar
+from pathlib import Path
+
+
+# 支持的语速选项
+SPEED_OPTIONS = {
+    0.5: "非常慢 (Very Slow) - 初学者跟读",
+    0.7: "慢速 (Slow) - 学习发音",
+    0.9: "正常 (Normal) - 日常学习（推荐）",
+    1.3: "快速 (Fast) - 听力挑战",
+    1.7: "非常快 (Very Fast) - 进阶训练",
+}
+
+
+@dataclass
+class TTSConfig:
+    """通用 TTS 配置"""
+    # 语速（0.5, 0.7, 0.9, 1.3, 1.7）
+    speed: float = 0.9
+    # 输出格式
+    output_format: str = "mp3"
+    # 角色音色映射（可选，为空则使用 provider 默认值）
+    # 旁白 - 女声
+    narrator_voice: str = ""
+    # 对话 A - 男声
+    dialogue_a_voice: str = ""
+    # 对话 B - 女声
+    dialogue_b_voice: str = ""
+    # 兼容旧配置
+    female_voice: str = ""
+    male_voice: str = ""
+
+
+@dataclass
+class TTSResult:
+    """TTS 合成结果"""
+    success: bool
+    audio_path: Optional[Path] = None
+    error_message: Optional[str] = None
+    duration_seconds: Optional[float] = None
+
+
+class TTSProvider(ABC):
+    """
+    TTS 服务提供者抽象基类
+
+    所有 TTS 服务（讯飞、Edge-TTS 等）必须继承此类并实现抽象方法。
+    """
+
+    # 类属性：各 provider 的默认配置
+    PROVIDER_NAME: ClassVar[str] = "base"
+    DEFAULT_FEMALE_VOICE: ClassVar[str] = ""
+    DEFAULT_MALE_VOICE: ClassVar[str] = ""
+    # 默认角色音色映射
+    DEFAULT_NARRATOR_VOICE: ClassVar[str] = ""    # 旁白 - 女声
+    DEFAULT_DIALOGUE_A_VOICE: ClassVar[str] = ""  # 对话 A - 男声
+    DEFAULT_DIALOGUE_B_VOICE: ClassVar[str] = ""  # 对话 B - 女声
+    SUPPORTED_VOICES: ClassVar[Dict[str, str]] = {}  # voice_id -> description
+
+    def __init__(self, config: Optional[TTSConfig] = None, **credentials):
+        """
+        初始化 TTS Provider
+
+        Args:
+            config: TTS 配置
+            **credentials: Provider 特定的认证信息（api_key, appid 等）
+        """
+        self.config = config or TTSConfig()
+        self.credentials = credentials
+        self._validate_credentials()
+
+    @abstractmethod
+    def _validate_credentials(self) -> None:
+        """
+        验证认证信息是否完整
+
+        Raises:
+            ValueError: 认证信息缺失或无效
+        """
+        pass
+
+    @abstractmethod
+    def synthesize(
+        self,
+        text: str,
+        output_path: Path,
+        voice: Optional[str] = None,
+        speed: Optional[float] = None
+    ) -> TTSResult:
+        """
+        合成语音
+
+        Args:
+            text: 要合成的文本
+            output_path: 输出文件路径
+            voice: 语音 ID（可选，使用配置中的默认值）
+            speed: 语速（可选，使用配置中的默认值）
+
+        Returns:
+            TTSResult: 合成结果
+        """
+        pass
+
+    def get_voice(self, gender: str = "female") -> str:
+        """
+        获取指定性别的语音 ID（兼容旧接口）
+
+        Args:
+            gender: 性别 ("female" 或 "male")
+
+        Returns:
+            语音 ID
+        """
+        if gender == "female":
+            return self.config.female_voice or self.DEFAULT_FEMALE_VOICE
+        return self.config.male_voice or self.DEFAULT_MALE_VOICE
+
+    def get_voice_by_role(self, role: str) -> str:
+        """
+        获取指定角色的语音 ID
+
+        Args:
+            role: 角色 ("narrator", "dialogue_a", "dialogue_b")
+
+        Returns:
+            语音 ID
+        """
+        if role == "narrator":
+            return self.config.narrator_voice or self.DEFAULT_NARRATOR_VOICE or self.DEFAULT_FEMALE_VOICE
+        elif role == "dialogue_a":
+            return self.config.dialogue_a_voice or self.DEFAULT_DIALOGUE_A_VOICE or self.DEFAULT_MALE_VOICE
+        elif role == "dialogue_b":
+            return self.config.dialogue_b_voice or self.DEFAULT_DIALOGUE_B_VOICE or self.DEFAULT_FEMALE_VOICE
+        else:
+            return self.get_voice("female")
+
+    @classmethod
+    def list_voices(cls) -> Dict[str, str]:
+        """
+        列出所有支持的语音
+
+        Returns:
+            语音 ID -> 描述 的字典
+        """
+        return cls.SUPPORTED_VOICES.copy()
+
+    @classmethod
+    def get_default_voices(cls) -> Dict[str, str]:
+        """
+        获取默认的角色音色映射
+
+        Returns:
+            角色 -> 默认语音 ID 的字典
+        """
+        return {
+            "narrator": cls.DEFAULT_NARRATOR_VOICE or cls.DEFAULT_FEMALE_VOICE,
+            "dialogue_a": cls.DEFAULT_DIALOGUE_A_VOICE or cls.DEFAULT_MALE_VOICE,
+            "dialogue_b": cls.DEFAULT_DIALOGUE_B_VOICE or cls.DEFAULT_FEMALE_VOICE,
+        }