@rookiestar/eng-lang-tutor 1.0.1

package/scripts/audio/tts/manager.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""
+TTS 管理器 - 通用入口，支持多 Provider
+
+提供统一的 TTS 接口，支持切换不同的 TTS 服务提供商。
+
+使用示例：
+    # 方式 1：从环境变量读取配置（默认使用 Edge-TTS）
+    manager = TTSManager.from_env()
+
+    # 方式 2：使用 Edge-TTS（默认，免费无需认证）
+    manager = TTSManager(provider="edge-tts")
+
+    # 方式 3：使用讯飞（需要认证）
+    manager = TTSManager(
+        provider="xunfei",
+        appid="xxx",
+        api_key="xxx",
+        api_secret="xxx"
+    )
+
+    # 合成单条语音
+    result = manager.synthesize("Hello", Path("output.mp3"))
+
+    # 为知识点生成所有音频
+    audio_info = manager.generate_keypoint_audio(keypoint)
+"""
+
+from pathlib import Path
+from typing import Dict, Any, Optional, Type, ClassVar
+from datetime import date, datetime
+import os
+import sys
+
+# 添加 scripts 目录到路径以导入 state_manager
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from .base import TTSProvider, TTSConfig, TTSResult
+from .providers.xunfei import XunFeiProvider
+from .providers.edge import EdgeTTSProvider
+
+try:
+    from ...core.state_manager import get_default_state_dir
+except ImportError:
+    from scripts.core.state_manager import get_default_state_dir
+
+
+# Provider 注册表
+PROVIDERS: Dict[str, Type[TTSProvider]] = {
+    "edge-tts": EdgeTTSProvider,  # 默认推荐
+    "xunfei": XunFeiProvider,     # 备选方案
+}
+
+
+class TTSManager:
+    """
+    TTS 管理器 - 统一入口
+
+    提供统一的 TTS 接口，支持：
+    - 多 Provider 切换
+    - 环境变量配置
+    - 知识点音频批量生成
+    """
+
+    # 支持的 Provider 列表
+    SUPPORTED_PROVIDERS: ClassVar[list] = list(PROVIDERS.keys())
+
+    def __init__(
+        self,
+        provider: str = "edge-tts",
+        data_dir: str = None,
+        config: Optional[TTSConfig] = None,
+        **credentials
+    ):
+        """
+        初始化 TTS 管理器
+
+        Args:
+            provider: Provider 名称（目前仅支持 "xunfei"）
+            data_dir: 数据目录（默认使用 OPENCLAW_STATE_DIR 或 ~/.openclaw/state/eng-lang-tutor/）
+            config: TTS 配置
+            **credentials: Provider 认证信息
+
+        示例:
+            # 讯飞（使用默认数据目录）
+            manager = TTSManager(provider="xunfei")
+
+            # 讯飞（直接传入密钥）
+            manager = TTSManager(
+                provider="xunfei",
+                appid="xxx",
+                api_key="xxx",
+                api_secret="xxx"
+            )
+        """
+        if provider not in PROVIDERS:
+            raise ValueError(
+                f"Unknown provider: {provider}. "
+                f"Available: {list(PROVIDERS.keys())}"
+            )
+
+        # 使用与 StateManager 相同的默认目录逻辑
+        if data_dir is None:
+            self.data_dir = get_default_state_dir()
+        else:
+            self.data_dir = Path(data_dir)
+
+        self.audio_dir = self.data_dir / "audio"
+        self.audio_dir.mkdir(parents=True, exist_ok=True)
+
+        self.provider_name = provider
+        self.config = config or TTSConfig()
+
+        # 初始化 Provider
+        self.provider: TTSProvider = PROVIDERS[provider](
+            config=self.config,
+            **credentials
+        )
+
+    @classmethod
+    def from_env(cls, provider: Optional[str] = None, **kwargs) -> "TTSManager":
+        """
+        从环境变量创建 TTS 管理器
+
+        环境变量格式：
+            TTS_PROVIDER=xunfei
+            XUNFEI_APPID=xxx
+            XUNFEI_API_KEY=xxx
+            XUNFEI_API_SECRET=xxx
+
+        Args:
+            provider: Provider 名称（可选，默认从 TTS_PROVIDER 环境变量读取）
+            **kwargs: 其他参数传递给构造函数
+
+        Returns:
+            TTSManager 实例
+        """
+        provider = provider or os.getenv("TTS_PROVIDER", "edge-tts")
+        return cls(provider=provider, **kwargs)
+
+    def switch_provider(self, provider: str, **credentials) -> None:
+        """
+        切换 Provider
+
+        Args:
+            provider: Provider 名称
+            **credentials: 新 Provider 的认证信息
+        """
+        if provider not in PROVIDERS:
+            raise ValueError(
+                f"Unknown provider: {provider}. "
+                f"Available: {list(PROVIDERS.keys())}"
+            )
+
+        self.provider_name = provider
+        self.provider = PROVIDERS[provider](
+            config=self.config,
+            **credentials
+        )
+
+    def synthesize(
+        self,
+        text: str,
+        output_path: Path,
+        voice: Optional[str] = None,
+        speed: Optional[float] = None
+    ) -> TTSResult:
+        """
+        合成单条语音
+
+        Args:
+            text: 要合成的文本
+            output_path: 输出文件路径
+            voice: 语音 ID（可选）
+            speed: 语速（可选，0.5-2.0）
+
+        Returns:
+            TTSResult: 合成结果
+        """
+        return self.provider.synthesize(text, output_path, voice, speed)
+
+    def generate_keypoint_audio(
+        self,
+        keypoint: Dict[str, Any],
+        target_date: Optional[date] = None
+    ) -> Dict[str, Any]:
+        """
+        为知识点生成所有音频
+
+        生成内容：
+        - 对话音频（按角色分文件，A=女声，B=男声）
+        - 表达音频（语速更慢，适合学习）
+
+        Args:
+            keypoint: 知识点数据
+            target_date: 目标日期（可选，默认今天）
+
+        Returns:
+            音频信息字典，包含 dialogue 和 expressions 列表
+        """
+        target_date = target_date or date.today()
+        date_str = target_date.strftime('%Y-%m-%d')
+
+        date_audio_dir = self.audio_dir / date_str
+        date_audio_dir.mkdir(parents=True, exist_ok=True)
+
+        audio_info = {
+            "dialogue": [],
+            "expressions": [],
+            "generated_at": datetime.now().isoformat(),
+            "provider": self.provider_name
+        }
+
+        # 1. 生成对话音频
+        for i, example in enumerate(keypoint.get("examples", [])):
+            for j, line in enumerate(example.get("dialogue", [])):
+                if ":" in line:
+                    speaker, text = line.split(":", 1)
+                    speaker = speaker.strip()
+                    text = text.strip()
+
+                    if not text:
+                        continue
+
+                    # A = 男声，B = 女声
+                    gender = "male" if speaker.upper() == "A" else "female"
+                    voice = self.provider.get_voice(gender)
+                    output_path = date_audio_dir / f"dialogue_{i}_{j}_{speaker}.mp3"
+
+                    result = self.synthesize(
+                        text=text,
+                        output_path=output_path,
+                        voice=voice
+                    )
+
+                    if result.success:
+                        audio_info["dialogue"].append({
+                            "speaker": speaker,
+                            "text": text,
+                            "audio_url": f"audio/{date_str}/{output_path.name}"
+                        })
+                    else:
+                        # 记录错误但不中断
+                        audio_info["dialogue"].append({
+                            "speaker": speaker,
+                            "text": text,
+                            "error": result.error_message
+                        })
+
+        # 2. 生成表达音频（语速更慢）
+        for i, expr in enumerate(keypoint.get("expressions", [])):
+            phrase = expr.get("phrase", "")
+            if not phrase:
+                continue
+
+            output_path = date_audio_dir / f"expression_{i+1}.mp3"
+            result = self.synthesize(
+                text=phrase,
+                output_path=output_path,
+                speed=0.7  # 更慢语速，适合学习
+            )
+
+            if result.success:
+                audio_info["expressions"].append({
+                    "text": phrase,
+                    "audio_url": f"audio/{date_str}/{output_path.name}"
+                })
+            else:
+                audio_info["expressions"].append({
+                    "text": phrase,
+                    "error": result.error_message
+                })
+
+        return audio_info
+
+    @classmethod
+    def list_supported_providers(cls) -> list:
+        """
+        列出所有支持的 Provider
+
+        Returns:
+            Provider 名称列表
+        """
+        return list(PROVIDERS.keys())
+
+    def list_voices(self) -> Dict[str, str]:
+        """
+        列出当前 Provider 支持的语音
+
+        Returns:
+            语音 ID -> 描述 的字典
+        """
+        return self.provider.list_voices()
+
+    def get_audio_path(self, date_str: str, filename: str) -> Path:
+        """
+        获取音频文件的完整路径
+
+        Args:
+            date_str: 日期字符串 (YYYY-MM-DD)
+            filename: 文件名
+
+        Returns:
+            完整文件路径
+        """
+        return self.audio_dir / date_str / filename

package/scripts/audio/tts/providers/__init__.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""
+TTS Providers - TTS 服务提供者实现
+"""
+
+from .xunfei import XunFeiProvider
+from .edge import EdgeTTSProvider
+
+__all__ = [
+    "XunFeiProvider",
+    "EdgeTTSProvider",
+]

package/scripts/audio/tts/providers/edge.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Edge-TTS Provider 实现
+
+Microsoft Edge TTS 服务：
+- 完全免费，无需 API 密钥
+- 高质量 24kHz 神经语音
+- 支持多种美式英语发音人
+- 国内网络可能需要代理
+"""
+
+import asyncio
+import edge_tts
+from pathlib import Path
+from typing import Optional, ClassVar, Dict
+
+from ..base import TTSProvider, TTSConfig, TTSResult
+
+
+class EdgeTTSProvider(TTSProvider):
+    """
+    Microsoft Edge TTS Provider
+
+    支持的美式英语发音人：
+    - en-US-JennyNeural: 女声，友好亲切（推荐）
+    - en-US-AriaNeural: 女声，自信清晰
+    - en-US-EricNeural: 男声，专业理性（推荐）
+    - en-US-GuyNeural: 男声，热情活力
+    - en-US-AnaNeural: 女声，可爱随和
+    - en-US-ChristopherNeural: 男声，权威可靠
+
+    无需认证信息，直接使用。
+    """
+
+    PROVIDER_NAME: ClassVar[str] = "edge-tts"
+    DEFAULT_FEMALE_VOICE: ClassVar[str] = "en-US-JennyNeural"  # 友好亲切
+    DEFAULT_MALE_VOICE: ClassVar[str] = "en-US-EricNeural"     # 专业理性
+    # 角色音色映射：旁白-女声，对话A-男声，对话B-女声
+    DEFAULT_NARRATOR_VOICE: ClassVar[str] = "en-US-JennyNeural"    # 旁白 - 女声
+    DEFAULT_DIALOGUE_A_VOICE: ClassVar[str] = "en-US-EricNeural"   # 对话 A - 男声
+    DEFAULT_DIALOGUE_B_VOICE: ClassVar[str] = "en-US-JennyNeural"  # 对话 B - 女声
+
+    SUPPORTED_VOICES: ClassVar[Dict[str, str]] = {
+        "en-US-JennyNeural": "美式英语女声，友好亲切（推荐）",
+        "en-US-AriaNeural": "美式英语女声，自信清晰",
+        "en-US-EricNeural": "美式英语男声，专业理性（推荐）",
+        "en-US-GuyNeural": "美式英语男声，热情活力",
+        "en-US-AnaNeural": "美式英语女声，可爱随和",
+        "en-US-ChristopherNeural": "美式英语男声，权威可靠",
+        "en-US-MichelleNeural": "美式英语女声，友好舒适",
+        "en-US-RogerNeural": "美式英语男声，生动活泼",
+        "en-US-AndrewNeural": "美式英语男声，友好积极",
+        "en-US-BrianNeural": "美式英语男声，友好积极",
+        "en-US-EmmaNeural": "美式英语女声，友好积极",
+        "en-US-AvaNeural": "美式英语女声，友好积极",
+    }
+
+    def _validate_credentials(self) -> None:
+        """
+        验证认证信息
+
+        Edge-TTS 不需要认证信息，直接通过。
+        """
+        # Edge-TTS 不需要任何认证信息
+        pass
+
+    def synthesize(
+        self,
+        text: str,
+        output_path: Path,
+        voice: Optional[str] = None,
+        speed: Optional[float] = None
+    ) -> TTSResult:
+        """
+        合成语音
+
+        Args:
+            text: 要合成的文本
+            output_path: 输出文件路径（.mp3）
+            voice: 语音 ID（可选，默认使用女声）
+            speed: 语速（可选，0.5-2.0，1.0 = 正常）
+
+        Returns:
+            TTSResult: 合成结果
+        """
+        voice = voice or self.get_voice("female")
+        speed_val = speed or self.config.speed
+
+        # 将 speed (0.5-2.0) 转换为 edge-tts 的 rate 格式
+        # speed=1.0 -> rate="+0%"
+        # speed=0.7 -> rate="-30%" (更慢，适合学习)
+        # speed=1.5 -> rate="+50%" (更快)
+        rate_percent = int((speed_val - 1.0) * 100)
+        rate = f"{rate_percent:+d}%"
+
+        # 确保输出目录存在
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        async def _synthesize_async():
+            """异步合成语音"""
+            communicate = edge_tts.Communicate(text, voice, rate=rate)
+            await communicate.save(str(output_path))
+
+        try:
+            # 在同步上下文中运行异步代码
+            asyncio.run(_synthesize_async())
+            return TTSResult(success=True, audio_path=output_path)
+
+        except Exception as e:
+            return TTSResult(success=False, error_message=str(e))

package/scripts/audio/tts/providers/xunfei.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+讯飞 TTS Provider 实现
+
+讯飞开放平台语音合成服务：
+- 每日 500 分钟免费额度
+- 国内网络稳定直连
+- 支持美式英语发音人（catherine, henry）
+- WebSocket 流式接口
+"""
+
+import websocket
+import datetime
+import hashlib
+import base64
+import hmac
+import json
+import os
+import ssl
+import certifi
+from pathlib import Path
+from typing import Optional, ClassVar, Dict
+from urllib.parse import urlencode
+
+from ..base import TTSProvider, TTSConfig, TTSResult
+
+
+class XunFeiProvider(TTSProvider):
+    """
+    讯飞开放平台 TTS Provider
+
+    支持的美式英语发音人：
+    - catherine: 女声，自然流畅（推荐）
+    - henry: 男声，沉稳专业
+    - mary: 女声，新闻播报
+    - john: 男声，活力阳光
+
+    环境变量配置：
+    - XUNFEI_APPID: 应用 ID
+    - XUNFEI_API_KEY: API Key
+    - XUNFEI_API_SECRET: API Secret
+    """
+
+    PROVIDER_NAME: ClassVar[str] = "xunfei"
+    DEFAULT_FEMALE_VOICE: ClassVar[str] = "catherine"  # 美式英语女声
+    DEFAULT_MALE_VOICE: ClassVar[str] = "henry"        # 美式英语男声
+    # 角色音色映射：旁白-女声，对话A-男声，对话B-女声
+    DEFAULT_NARRATOR_VOICE: ClassVar[str] = "catherine"  # 旁白 - 女声
+    DEFAULT_DIALOGUE_A_VOICE: ClassVar[str] = "henry"    # 对话 A - 男声
+    DEFAULT_DIALOGUE_B_VOICE: ClassVar[str] = "catherine"  # 对话 B - 女声
+
+    SUPPORTED_VOICES: ClassVar[Dict[str, str]] = {
+        "catherine": "美式英语女声，自然流畅（推荐）",
+        "henry": "美式英语男声，沉稳专业",
+        "mary": "美式英语女声，新闻播报",
+        "john": "美式英语男声，活力阳光",
+    }
+
+    def _validate_credentials(self) -> None:
+        """
+        验证讯飞认证信息
+
+        优先使用传入的 credentials，其次从环境变量读取。
+
+        Raises:
+            ValueError: 认证信息缺失
+        """
+        required = ["appid", "api_key", "api_secret"]
+        for key in required:
+            if key not in self.credentials:
+                # 尝试从环境变量读取
+                env_key = f"XUNFEI_{key.upper()}"
+                if env_key in os.environ:
+                    self.credentials[key] = os.environ[env_key]
+                else:
+                    raise ValueError(
+                        f"Missing required credential: {key}. "
+                        f"Set XUNFEI_{key.upper()} environment variable or pass it to constructor."
+                    )
+
+    def _create_auth_url(self) -> str:
+        """
+        生成 WebSocket 鉴权 URL
+
+        Returns:
+            带鉴权参数的 WebSocket URL
+        """
+        date = datetime.datetime.now().strftime('%a, %d %b %Y %H:%M:%S GMT')
+        signature_origin = f"host: tts-api.xfyun.cn\ndate: {date}\nGET /v2/tts HTTP/1.1"
+        signature_sha = hmac.new(
+            self.credentials["api_secret"].encode('utf-8'),
+            signature_origin.encode('utf-8'),
+            digestmod=hashlib.sha256
+        ).digest()
+        signature = base64.b64encode(signature_sha).decode()
+        authorization = base64.b64encode(
+            f'api_key="{self.credentials["api_key"]}", algorithm="hmac-sha256", '
+            f'headers="host date request-line", signature="{signature}"'.encode()
+        ).decode()
+
+        params = urlencode({
+            "authorization": authorization,
+            "date": date,
+            "host": "tts-api.xfyun.cn"
+        })
+        return f'wss://tts-api.xfyun.cn/v2/tts?{params}'
+
+    def synthesize(
+        self,
+        text: str,
+        output_path: Path,
+        voice: Optional[str] = None,
+        speed: Optional[float] = None
+    ) -> TTSResult:
+        """
+        合成语音
+
+        Args:
+            text: 要合成的文本
+            output_path: 输出文件路径（.mp3）
+            voice: 语音 ID（可选，默认使用女声）
+            speed: 语速（可选，0.5-2.0，1.0 = 正常）
+
+        Returns:
+            TTSResult: 合成结果
+        """
+        voice = voice or self.get_voice("female")
+        # 讯飞语速范围 0-100，50 为正常
+        speed_val = speed or self.config.speed
+        speed_int = int(speed_val * 50)
+
+        audio_data = bytearray()
+        error_msg = None
+
+        def on_message(ws, message):
+            nonlocal error_msg
+            try:
+                data = json.loads(message)
+                if data.get("code") == 0:
+                    audio = data.get("data", {}).get("audio", "")
+                    status = data.get("data", {}).get("status", 0)
+                    if audio:
+                        audio_data.extend(base64.b64decode(audio))
+                    # status=2 表示合成完成，关闭连接
+                    if status == 2:
+                        ws.close()
+                else:
+                    error_msg = f"XunFei API error: code={data.get('code')}, message={data.get('message')}"
+            except json.JSONDecodeError as e:
+                error_msg = f"JSON decode error: {e}"
+
+        def on_error(ws, error):
+            nonlocal error_msg
+            error_msg = str(error)
+
+        def on_open(ws):
+            request = {
+                "common": {"app_id": self.credentials["appid"]},
+                "business": {
+                    "aue": "lame",      # MP3 格式
+                    "sfl": 1,           # 开启流式返回
+                    "auf": "audio/L16;rate=16000",
+                    "vcn": voice,       # 发音人
+                    "speed": speed_int, # 语速
+                    "volume": 50,       # 音量
+                    "pitch": 50,        # 音调
+                },
+                "data": {
+                    "status": 2,  # 一次性传输
+                    "text": str(base64.b64encode(text.encode('utf-8')), "UTF8")
+                }
+            }
+            ws.send(json.dumps(request))
+
+        try:
+            ws_url = self._create_auth_url()
+            ws = websocket.WebSocketApp(
+                ws_url,
+                on_message=on_message,
+                on_error=on_error,
+            )
+            ws.on_open = on_open
+            # 使用 certifi 提供的 SSL 证书
+            ws.run_forever(
+                sslopt={"cert_reqs": ssl.CERT_REQUIRED, "ca_certs": certifi.where()}
+            )
+
+            if error_msg:
+                return TTSResult(success=False, error_message=error_msg)
+
+            if not audio_data:
+                return TTSResult(success=False, error_message="No audio data received")
+
+            # 确保输出目录存在
+            output_path = Path(output_path)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # 保存音频文件
+            with open(output_path, "wb") as f:
+                f.write(audio_data)
+
+            return TTSResult(success=True, audio_path=output_path)
+
+        except Exception as e:
+            return TTSResult(success=False, error_message=str(e))

package/scripts/audio/utils.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""
+共享音频工具函数
+
+提供音频处理相关的通用功能，避免代码重复。
+"""
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+def get_ffmpeg_path() -> str:
+    """
+    获取 FFmpeg 可执行文件路径
+
+    Returns:
+        FFmpeg 路径
+
+    Raises:
+        RuntimeError: 如果未找到 FFmpeg
+    """
+    ffmpeg_path = shutil.which("ffmpeg")
+    if not ffmpeg_path:
+        raise RuntimeError(
+            "ffmpeg not found. Install it with: brew install ffmpeg (macOS) "
+            "or apt-get install ffmpeg (Ubuntu)"
+        )
+    return ffmpeg_path
+
+
+def get_audio_duration(audio_path: Path, ffmpeg_path: Optional[str] = None) -> float:
+    """
+    获取音频文件时长
+
+    Args:
+        audio_path: 音频文件路径
+        ffmpeg_path: FFmpeg 可执行文件路径（可选，默认自动检测）
+
+    Returns:
+        时长（秒），如果无法解析则返回 0.0
+    """
+    if ffmpeg_path is None:
+        ffmpeg_path = get_ffmpeg_path()
+
+    cmd = [
+        ffmpeg_path,
+        "-i", str(audio_path),
+        "-hide_banner",
+        "-f", "null",
+        "-"
+    ]
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    # 从 stderr 中解析时长，格式: "  Duration: 00:00:03.45, ..."
+    match = re.search(r"Duration: (\d+):(\d+):(\d+\.?\d*)", result.stderr)
+    if match:
+        hours, minutes, seconds = match.groups()
+        return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
+    return 0.0

package/scripts/cli/__init__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""CLI tools: command-line interface and command parsing."""
+
+from .cli import main
+from .command_parser import CommandParser
+
+__all__ = ['main', 'CommandParser']