@rookiestar/eng-lang-tutor 1.0.3 → 1.0.5

package/npm-scripts/install.js

@@ -5,23 +5,99 @@
  *
  * This script runs automatically after npm install and:
  * 1. Installs the skill to ~/.openclaw/skills/eng-lang-tutor/
- * 2. Migrates data from old data/ directory if needed (handled by Python code)
+ * 2. Creates Python venv and installs dependencies
+ * 3. Checks for system dependencies (ffmpeg)
+ * 4. Migrates data from old data/ directory if needed (handled by Python code)
  */
 
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const { execSync, spawn } = require('child_process');
 
 const SKILL_NAME = 'eng-lang-tutor';
 const SKILLS_DIR = path.join(os.homedir(), '.openclaw', 'skills');
 const SKILL_TARGET = path.join(SKILLS_DIR, SKILL_NAME);
+const VENV_DIR = path.join(os.homedir(), '.venvs', SKILL_NAME);
 
 // Get the package root directory
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 
+function checkFfmpeg() {
+  try {
+    execSync('ffmpeg -version', { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function setupPythonVenv() {
+  const requirementsPath = path.join(SKILL_TARGET, 'requirements.txt');
+
+  // Check if requirements.txt exists
+  if (!fs.existsSync(requirementsPath)) {
+    console.log('⚠️  requirements.txt not found, skipping Python setup\n');
+    return false;
+  }
+
+  // Check if venv already exists and has dependencies
+  const venvPython = path.join(VENV_DIR, 'bin', 'python');
+  const venvPip = path.join(VENV_DIR, 'bin', 'pip');
+
+  if (fs.existsSync(venvPython) && fs.existsSync(venvPip)) {
+    // Check if websocket-client is installed (key dependency)
+    try {
+      execSync(`${venvPython} -c "import websocket"`, { stdio: 'ignore' });
+      console.log('✓ Python venv already set up with dependencies\n');
+      return true;
+    } catch (e) {
+      console.log('→ Updating Python dependencies...');
+    }
+  } else {
+    console.log('→ Creating Python virtual environment...');
+    try {
+      execSync(`python3 -m venv ${VENV_DIR}`, { stdio: 'inherit' });
+      console.log('✓ Created venv at ' + VENV_DIR);
+    } catch (e) {
+      console.log('⚠️  Failed to create venv: ' + e.message);
+      return false;
+    }
+  }
+
+  // Install dependencies
+  console.log('→ Installing Python dependencies...');
+  try {
+    execSync(`${venvPip} install -q -r ${requirementsPath}`, { stdio: 'inherit' });
+    console.log('✓ Python dependencies installed\n');
+    return true;
+  } catch (e) {
+    console.log('⚠️  Failed to install Python dependencies: ' + e.message);
+    console.log('   You may need to run manually:');
+    console.log(`   ${venvPip} install -r ${requirementsPath}\n`);
+    return false;
+  }
+}
+
 function install() {
   console.log(`\n📦 Setting up ${SKILL_NAME} skill...\n`);
 
+  // Check for ffmpeg
+  const hasFfmpeg = checkFfmpeg();
+  if (!hasFfmpeg) {
+    console.log('⚠️  WARNING: ffmpeg is not installed. Audio generation will not work.');
+    console.log('   Install it with:');
+    if (process.platform === 'darwin') {
+      console.log('     brew install ffmpeg');
+    } else if (process.platform === 'linux') {
+      console.log('     sudo apt-get install ffmpeg   # Debian/Ubuntu');
+      console.log('     sudo yum install ffmpeg       # RHEL/CentOS');
+    }
+    console.log('');
+  } else {
+    console.log('✓ ffmpeg is installed\n');
+  }
+
   // Create skills directory if it doesn't exist
   if (!fs.existsSync(SKILLS_DIR)) {
     fs.mkdirSync(SKILLS_DIR, { recursive: true });
@@ -75,6 +151,9 @@ function install() {
 
   console.log(`✓ Copied ${copiedCount} items to ${SKILL_TARGET}`);
 
+  // Setup Python venv and install dependencies
+  setupPythonVenv();
+
   // Show post-install message
   console.log(`
 ╔═══════════════════════════════════════════════════════════════╗
@@ -84,21 +163,20 @@ function install() {
 ║  ${SKILL_NAME} has been installed to:                          ║
 ║  ${SKILL_TARGET}
 ║                                                               ║
-║  Next steps:                                                  ║
-║  1. Install Python dependencies:                              ║
-║     pip install -r ${SKILL_TARGET}/requirements.txt           ║
+║  Python venv:                                                 ║
+║     ${VENV_DIR}                                               ║
 ║                                                               ║
-║  2. Restart your OpenClaw agent                               ║
+║  Usage:                                                       ║
+║     ${VENV_DIR}/bin/python ${SKILL_TARGET}/scripts/cli.py     ║
 ║                                                               ║
-║  3. Configure through onboarding (first time only)            ║
+║  Or use the wrapper script:                                   ║
+║     ${SKILL_TARGET}/scripts/eng-lang-tutor                    ║
 ║                                                               ║
 ║  Data location:                                               ║
 ║     ~/.openclaw/state/eng-lang-tutor/                         ║
-║     (or set OPENCLAW_STATE_DIR env var)                       ║
 ║                                                               ║
-║  Commands:                                                    ║
-║     npx eng-lang-tutor install    - Reinstall skill           ║
-║     npx eng-lang-tutor uninstall  - Remove skill              ║
+║  Environment variables (required for TTS):                    ║
+║     XUNFEI_APPID, XUNFEI_API_KEY, XUNFEI_API_SECRET           ║
 ║                                                               ║
 ╚═══════════════════════════════════════════════════════════════╝
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rookiestar/eng-lang-tutor",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "English language tutor skill for OpenClaw - Learn authentic American English expressions with gamification",
   "keywords": [
     "english",

package/requirements.txt

@@ -1,5 +1,7 @@
 # Core dependencies
 websocket-client>=1.6.0  # For XunFei TTS WebSocket API
+certifi>=2024.0.0        # SSL certificate bundle for HTTPS/WebSocket connections
+aiohttp>=3.8.0           # Async HTTP client for Feishu API
 
 # Optional: Edge-TTS support (uncomment if needed)
 # edge-tts>=6.1.0
@@ -7,3 +9,8 @@ websocket-client>=1.6.0  # For XunFei TTS WebSocket API
 # Development dependencies
 pytest>=7.0.0
 pytest-asyncio>=0.21.0
+
+# System dependencies (must be installed separately):
+# - ffmpeg: Required for audio composition
+#   macOS: brew install ffmpeg
+#   Ubuntu/Debian: sudo apt-get install ffmpeg

package/scripts/audio_composer.py

@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+"""
+知识点音频合成器 - 将多个音频片段合并为单个文件
+
+音频结构：
+- expressions: 引导语 [1s] 内容 [2s]
+- alternatives: 引导语 [1s] 内容 [2s]
+- dialogues: 引导语 [1s] 对话行1 [0.5s] 对话行2 ...
+
+使用示例：
+    from scripts.audio_composer import AudioComposer
+    from scripts.tts import TTSManager
+
+    tts = TTSManager.from_env()
+    composer = AudioComposer(tts)
+
+    result = composer.compose_keypoint_audio(keypoint, Path("output.mp3"))
+"""
+
+import subprocess
+import tempfile
+import shutil
+from pathlib import Path
+from typing import Optional, List
+from dataclasses import dataclass
+
+try:
+    from .tts import TTSManager
+except ImportError:
+    from tts import TTSManager
+
+
+@dataclass
+class CompositionResult:
+    """音频合成结果"""
+    success: bool
+    audio_path: Optional[Path] = None
+    duration_seconds: Optional[float] = None
+    error_message: Optional[str] = None
+
+
+class AudioComposer:
+    """
+    知识点音频合成器
+
+    将 expressions + alternatives + dialogues 合并为单个音频文件
+    """
+
+    def __init__(
+        self,
+        tts_manager: TTSManager,
+        ffmpeg_path: Optional[str] = None
+    ):
+        """
+        初始化音频合成器
+
+        Args:
+            tts_manager: TTS 管理器实例
+            ffmpeg_path: ffmpeg 可执行文件路径（默认自动检测）
+        """
+        self.tts = tts_manager
+        self.ffmpeg_path = ffmpeg_path or shutil.which("ffmpeg")
+        if not self.ffmpeg_path:
+            raise RuntimeError(
+                "ffmpeg not found. Install it with: brew install ffmpeg (macOS) "
+                "or apt-get install ffmpeg (Ubuntu)"
+            )
+
+        # 创建临时目录用于存放中间文件
+        self.temp_dir = Path(tempfile.mkdtemp(prefix="audio_composer_"))
+
+    def __del__(self):
+        """清理临时目录"""
+        if hasattr(self, 'temp_dir') and self.temp_dir.exists():
+            shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def compose_keypoint_audio(
+        self,
+        keypoint: dict,
+        output_path: Path,
+        lead_in_silence: float = 1.0,   # 引导语后留白
+        section_silence: float = 2.0,   # 内容后留白（段落间隔）
+        dialogue_silence: float = 0.5,  # 对话行之间留白
+        narrator_voice: str = "henry",  # 旁白音色（男声）
+        voice_a: str = "mary",          # 对话 A 音色（女声）
+        voice_b: str = "henry",         # 对话 B 音色（男声，沉稳）
+        speed: float = 0.9              # 语速
+    ) -> CompositionResult:
+        """
+        合成知识点音频
+
+        Args:
+            keypoint: 知识点数据
+            output_path: 输出文件路径
+            lead_in_silence: 引导语后留白时长（秒）
+            section_silence: 内容后留白时长（秒）
+            dialogue_silence: 对话行之间留白时长（秒）
+            narrator_voice: 旁白音色
+            voice_a: 对话 A 角色音色
+            voice_b: 对话 B 角色音色
+            speed: 语速
+
+        Returns:
+            CompositionResult: 合成结果
+        """
+        try:
+            output_path = Path(output_path)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+            segments: List[Path] = []
+            segment_index = 0
+
+            # 1. Expressions 部分
+            expressions = keypoint.get("expressions", [])
+            if expressions:
+                # 引导语
+                lead_in = self._synthesize_segment(
+                    text="Key expressions",
+                    voice=narrator_voice,
+                    speed=speed,
+                    index=segment_index
+                )
+                segments.append(lead_in)
+                segment_index += 1
+
+                # 引导语后留白
+                silence_1s = self._generate_silence(lead_in_silence)
+                segments.append(silence_1s)
+
+                # 内容
+                phrases = [expr.get("phrase", "") for expr in expressions]
+                content_text = ". ".join(p for p in phrases if p)
+                if content_text:
+                    content = self._synthesize_segment(
+                        text=content_text,
+                        voice=narrator_voice,
+                        speed=speed,
+                        index=segment_index
+                    )
+                    segments.append(content)
+                    segment_index += 1
+
+                # 内容后留白
+                silence_2s = self._generate_silence(section_silence)
+                segments.append(silence_2s)
+
+            # 2. Alternatives 部分
+            alternatives = keypoint.get("alternatives", [])
+            if alternatives:
+                # 引导语
+                lead_in = self._synthesize_segment(
+                    text="You can also say",
+                    voice=narrator_voice,
+                    speed=speed,
+                    index=segment_index
+                )
+                segments.append(lead_in)
+                segment_index += 1
+
+                # 引导语后留白
+                silence_1s = self._generate_silence(lead_in_silence)
+                segments.append(silence_1s)
+
+                # 内容
+                content_text = ". ".join(alt for alt in alternatives if alt)
+                if content_text:
+                    content = self._synthesize_segment(
+                        text=content_text,
+                        voice=narrator_voice,
+                        speed=speed,
+                        index=segment_index
+                    )
+                    segments.append(content)
+                    segment_index += 1
+
+                # 内容后留白
+                silence_2s = self._generate_silence(section_silence)
+                segments.append(silence_2s)
+
+            # 3. Dialogues 部分
+            examples = keypoint.get("examples", [])
+            if examples:
+                # 引导语
+                lead_in = self._synthesize_segment(
+                    text="Dialogue",
+                    voice=narrator_voice,
+                    speed=speed,
+                    index=segment_index
+                )
+                segments.append(lead_in)
+                segment_index += 1
+
+                # 引导语后留白
+                silence_1s = self._generate_silence(lead_in_silence)
+                segments.append(silence_1s)
+
+                # 对话内容
+                silence_05s = self._generate_silence(dialogue_silence)
+                for example in examples:
+                    dialogue = example.get("dialogue", [])
+                    for line in dialogue:
+                        if ":" in line:
+                            speaker, text = line.split(":", 1)
+                            speaker = speaker.strip()
+                            text = text.strip()
+
+                            if not text:
+                                continue
+
+                            # A = henry (男声), B = catherine (女声)
+                            voice = voice_a if speaker.upper() == "A" else voice_b
+
+                            segment = self._synthesize_segment(
+                                text=text,
+                                voice=voice,
+                                speed=speed,
+                                index=segment_index
+                            )
+                            segments.append(segment)
+                            segment_index += 1
+
+                            # 对话行之间留白
+                            segments.append(silence_05s)
+
+            if not segments:
+                return CompositionResult(
+                    success=False,
+                    error_message="No audio content to compose"
+                )
+
+            # 4. 拼接所有片段
+            final_audio = self._concatenate_segments(segments, output_path)
+
+            # 5. 获取时长
+            duration = self._get_duration(final_audio)
+
+            return CompositionResult(
+                success=True,
+                audio_path=final_audio,
+                duration_seconds=duration
+            )
+
+        except Exception as e:
+            return CompositionResult(
+                success=False,
+                error_message=str(e)
+            )
+
+    def _synthesize_segment(
+        self,
+        text: str,
+        voice: str,
+        speed: float,
+        index: int
+    ) -> Path:
+        """
+        合成单个音频片段
+
+        Args:
+            text: 文本
+            voice: 音色
+            speed: 语速
+            index: 片段索引
+
+        Returns:
+            音频文件路径
+        """
+        output_path = self.temp_dir / f"segment_{index}.mp3"
+
+        result = self.tts.synthesize(
+            text=text,
+            output_path=output_path,
+            voice=voice,
+            speed=speed
+        )
+
+        if not result.success:
+            raise RuntimeError(f"TTS synthesis failed: {result.error_message}")
+
+        return output_path
+
+    def _generate_silence(self, duration: float) -> Path:
+        """
+        生成空白音频
+
+        Args:
+            duration: 时长（秒）
+
+        Returns:
+            空白音频文件路径
+        """
+        output_path = self.temp_dir / f"silence_{duration}.mp3"
+
+        if output_path.exists():
+            return output_path
+
+        cmd = [
+            self.ffmpeg_path,
+            "-f", "lavfi",
+            "-i", f"anullsrc=r=16000:cl=mono",
+            "-t", str(duration),
+            "-y",
+            str(output_path)
+        ]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to generate silence: {result.stderr}")
+
+        return output_path
+
+    def _concatenate_segments(
+        self,
+        segments: List[Path],
+        output_path: Path
+    ) -> Path:
+        """
+        拼接多个音频片段
+
+        Args:
+            segments: 音频片段路径列表
+            output_path: 输出文件路径
+
+        Returns:
+            拼接后的音频文件路径
+        """
+        # 创建文件列表
+        list_file = self.temp_dir / "concat_list.txt"
+        with open(list_file, "w") as f:
+            for seg in segments:
+                # 需要转义路径中的特殊字符
+                escaped_path = str(seg).replace("'", "'\\''")
+                f.write(f"file '{escaped_path}'\n")
+
+        cmd = [
+            self.ffmpeg_path,
+            "-f", "concat",
+            "-safe", "0",
+            "-i", str(list_file),
+            "-c", "copy",
+            "-y",
+            str(output_path)
+        ]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=120
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to concatenate audio: {result.stderr}")
+
+        return output_path
+
+    def _get_duration(self, audio_path: Path) -> float:
+        """
+        获取音频时长
+
+        Args:
+            audio_path: 音频文件路径
+
+        Returns:
+            时长（秒）
+        """
+        cmd = [
+            self.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, ..."
+        import re
+        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