@rookiestar/eng-lang-tutor 1.0.18 → 1.1.0

package/package.json

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

package/scripts/audio/converter.py

@@ -197,6 +197,95 @@ class AudioConverter:
         return results
 
 
+    def convert_to_feishu_voice(
+        self,
+        input_path: Path,
+        output_path: Optional[Path] = None,
+        sample_rate: int = 16000,
+        bitrate: str = "24k"
+    ) -> ConversionResult:
+        """
+        将音频转换为飞书语音气泡格式 (.m4a + libopus 编码)
+
+        这个格式组合的特点：
+        - 文件扩展名: .m4a (MP4 容器)
+        - 音频编码: libopus
+        - 飞书插件会探测文件头，识别 libopus 编码触发语音气泡
+        - 其他平台作为普通音频附件播放
+
+        Args:
+            input_path: 输入文件路径
+            output_path: 输出文件路径（可选，默认同目录更换扩展名为 .m4a）
+            sample_rate: 采样率（默认 16000）
+            bitrate: 比特率（默认 24k）
+
+        Returns:
+            ConversionResult: 转换结果
+        """
+        input_path = Path(input_path)
+        if not input_path.exists():
+            return ConversionResult(
+                success=False,
+                error_message=f"Input file not found: {input_path}"
+            )
+
+        # 确定输出路径
+        if output_path is None:
+            output_path = input_path.with_suffix(".m4a")
+        else:
+            output_path = Path(output_path)
+
+        # 确保输出目录存在
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # 构建 ffmpeg 命令
+        # 使用 -c:a libopus 编码，输出到 .m4a 容器
+        cmd = [
+            self.ffmpeg_path,
+            "-i", str(input_path),
+            "-c:a", "libopus",          # Opus 编码器
+            "-ar", str(sample_rate),    # 采样率
+            "-ac", "1",                 # 单声道
+            "-b:a", bitrate,            # 比特率
+            "-y",                       # 覆盖输出文件
+            str(output_path)
+        ]
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=60
+            )
+
+            if result.returncode != 0:
+                return ConversionResult(
+                    success=False,
+                    error_message=f"ffmpeg error: {result.stderr}"
+                )
+
+            # 获取音频时长
+            duration = get_audio_duration(output_path, self.ffmpeg_path)
+
+            return ConversionResult(
+                success=True,
+                output_path=output_path,
+                duration_seconds=duration
+            )
+
+        except subprocess.TimeoutExpired:
+            return ConversionResult(
+                success=False,
+                error_message="Conversion timeout (>60s)"
+            )
+        except Exception as e:
+            return ConversionResult(
+                success=False,
+                error_message=str(e)
+            )
+
+
 # 便捷函数
 def convert_mp3_to_opus(
     input_path: Path,
@@ -219,3 +308,24 @@ def convert_mp3_to_opus(
         format="opus",
         sample_rate=16000
     )
+
+
+def convert_to_feishu_voice(
+    input_path: Path,
+    output_path: Optional[Path] = None
+) -> ConversionResult:
+    """
+    将音频转换为飞书语音气泡格式 (.m4a + libopus)
+
+    Args:
+        input_path: 输入文件路径
+        output_path: 输出路径（可选，默认 .m4a）
+
+    Returns:
+        ConversionResult
+    """
+    converter = AudioConverter()
+    return converter.convert_to_feishu_voice(
+        input_path=input_path,
+        output_path=output_path
+    )

package/scripts/core/state_manager.py

@@ -355,11 +355,11 @@ class StateManager:
                 - error_message: str (if failed)
         """
         try:
-            from .audio_composer import AudioComposer
-            from .tts import TTSManager
+            from ..audio.composer import AudioComposer
+            from ..audio.tts import TTSManager
         except ImportError:
-            from audio_composer import AudioComposer
-            from tts import TTSManager
+            from audio.composer import AudioComposer
+            from audio.tts import TTSManager
 
         if target_date is None:
             target_date = date.today()
@@ -377,50 +377,74 @@ class StateManager:
         date_str = target_date.strftime('%Y-%m-%d')
         media_dir = Path.home() / '.openclaw' / 'media' / 'eng-lang-tutor' / date_str
         media_dir.mkdir(parents=True, exist_ok=True)
-        output_path = media_dir / "keypoint_full.mp3"
+
+        # Intermediate MP3 and final Opus paths
+        mp3_path = media_dir / "keypoint_full.mp3"
+        opus_path = media_dir / "keypoint_full.opus"
 
         try:
             # Initialize TTS and composer (handle both package and direct imports)
             try:
-                from .audio_composer import AudioComposer
-                from .tts import TTSManager
+                from ..audio.composer import AudioComposer
+                from ..audio.tts import TTSManager
+                from ..audio.converter import convert_mp3_to_opus
             except ImportError:
-                from audio_composer import AudioComposer
-                from tts import TTSManager
+                from audio.composer import AudioComposer
+                from audio.tts import TTSManager
+                from audio.converter import convert_mp3_to_opus
 
             tts = TTSManager.from_env()
             composer = AudioComposer(tts)
 
-            # Compose audio directly to media directory
-            result = composer.compose_keypoint_audio(keypoint, output_path)
-
-            if result.success:
-                # Path relative to ~/.openclaw/media/ for message tool
-                audio_path = f"eng-lang-tutor/{date_str}/keypoint_full.mp3"
-
-                # Update keypoint with audio metadata
-                keypoint['audio'] = {
-                    'composed': audio_path,
-                    'duration_seconds': result.duration_seconds,
-                    'generated_at': datetime.now().isoformat()
-                }
+            # Step 1: Compose audio to MP3 (intermediate format)
+            result = composer.compose_keypoint_audio(keypoint, mp3_path)
 
-                # Save updated keypoint
-                daily_path = self.get_daily_dir(target_date)
-                file_path = daily_path / "keypoint.json"
-                with open(file_path, 'w', encoding='utf-8') as f:
-                    json.dump(keypoint, f, ensure_ascii=False, indent=2)
-
-                return {
-                    'success': True,
-                    'audio_path': audio_path,
-                    'duration_seconds': result.duration_seconds
-                }
-            else:
+            if not result.success:
                 return {
                     'success': False,
                     'error_message': result.error_message
                 }
+
+            # Step 2: Convert to Opus format for Feishu voice bubble compatibility
+            # .opus = Ogg container + libopus codec
+            # - Feishu plugin: detects libopus → triggers voice bubble
+            # - Discord: native Opus support
+            # - Other platforms: may need fallback
+            convert_result = convert_mp3_to_opus(
+                input_path=mp3_path,
+                output_path=opus_path
+            )
+
+            if convert_result.success:
+                # Use Opus format
+                audio_path = f"eng-lang-tutor/{date_str}/keypoint_full.opus"
+                duration_seconds = convert_result.duration_seconds or result.duration_seconds
+                audio_format = 'opus'
+            else:
+                # Fallback to MP3 if conversion fails
+                audio_path = f"eng-lang-tutor/{date_str}/keypoint_full.mp3"
+                duration_seconds = result.duration_seconds
+                audio_format = 'mp3'
+
+            # Update keypoint with audio metadata
+            keypoint['audio'] = {
+                'composed': audio_path,
+                'duration_seconds': duration_seconds,
+                'generated_at': datetime.now().isoformat(),
+                'format': audio_format
+            }
+
+            # Save updated keypoint
+            daily_path = self.get_daily_dir(target_date)
+            file_path = daily_path / "keypoint.json"
+            with open(file_path, 'w', encoding='utf-8') as f:
+                json.dump(keypoint, f, ensure_ascii=False, indent=2)
+
+            return {
+                'success': True,
+                'audio_path': audio_path,
+                'duration_seconds': duration_seconds
+            }
         except Exception as e:
             return {
                 'success': False,