@rookiestar/eng-lang-tutor 1.0.1

package/scripts/audio/composer.py

@@ -0,0 +1,367 @@
+#!/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
+
+from .tts import TTSManager
+from .utils import get_ffmpeg_path, get_audio_duration
+
+
+@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 get_ffmpeg_path()
+
+        # 创建临时目录用于存放中间文件
+        self.temp_dir = Path(tempfile.mkdtemp(prefix="audio_composer_"))
+
+    def __enter__(self):
+        """上下文管理器入口"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """上下文管理器退出，确保清理临时目录"""
+        self._cleanup()
+        return False
+
+    def _cleanup(self):
+        """清理临时目录"""
+        if hasattr(self, 'temp_dir') and self.temp_dir.exists():
+            shutil.rmtree(self.temp_dir, ignore_errors=True)
+
+    def __del__(self):
+        """析构函数（备用清理，不保证被调用）"""
+        self._cleanup()
+
+    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 = get_audio_duration(final_audio, self.ffmpeg_path)
+
+            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

package/scripts/audio/converter.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+音频格式转换器 - 将 MP3 转换为飞书语音格式
+
+飞书语音消息要求：
+- 格式: Opus / Speex / AAC / AMR
+- 采样率: 8000Hz / 16000Hz
+- 声道: 单声道
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Optional
+from dataclasses import dataclass
+
+from .utils import get_ffmpeg_path, get_audio_duration
+
+
+@dataclass
+class ConversionResult:
+    """转换结果"""
+    success: bool
+    output_path: Optional[Path] = None
+    error_message: Optional[str] = None
+    duration_seconds: Optional[float] = None
+
+
+class AudioConverter:
+    """音频格式转换器"""
+
+    # 飞书支持的语音格式
+    SUPPORTED_FORMATS = ["opus", "speex", "aac", "amr"]
+    SUPPORTED_SAMPLE_RATES = [8000, 16000]
+
+    def __init__(self, ffmpeg_path: Optional[str] = None):
+        """
+        初始化转换器
+
+        Args:
+            ffmpeg_path: ffmpeg 可执行文件路径（默认自动检测）
+        """
+        self.ffmpeg_path = ffmpeg_path or get_ffmpeg_path()
+
+    def convert_to_voice(
+        self,
+        input_path: Path,
+        output_path: Optional[Path] = None,
+        format: str = "opus",
+        sample_rate: int = 16000,
+        bitrate: str = "24k"
+    ) -> ConversionResult:
+        """
+        将音频文件转换为飞书语音格式
+
+        Args:
+            input_path: 输入文件路径（支持 MP3, WAV, M4A 等）
+            output_path: 输出文件路径（可选，默认同目录更换扩展名）
+            format: 输出格式（opus, speex, aac, amr）
+            sample_rate: 采样率（8000 或 16000）
+            bitrate: 比特率（默认 24k，适合语音）
+
+        Returns:
+            ConversionResult: 转换结果
+        """
+        # 参数验证
+        if format not in self.SUPPORTED_FORMATS:
+            return ConversionResult(
+                success=False,
+                error_message=f"Unsupported format: {format}. Supported: {self.SUPPORTED_FORMATS}"
+            )
+
+        if sample_rate not in self.SUPPORTED_SAMPLE_RATES:
+            return ConversionResult(
+                success=False,
+                error_message=f"Unsupported sample rate: {sample_rate}. Supported: {self.SUPPORTED_SAMPLE_RATES}"
+            )
+
+        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(f".{format}")
+        else:
+            output_path = Path(output_path)
+
+        # 确保输出目录存在
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # 构建 ffmpeg 命令
+        codec_map = {
+            "opus": "libopus",
+            "speex": "libspeex",
+            "aac": "aac",
+            "amr": "libvo_amrwbenc"
+        }
+
+        cmd = [
+            self.ffmpeg_path,
+            "-i", str(input_path),      # 输入文件
+            "-acodec", codec_map[format],  # 编码器
+            "-ar", str(sample_rate),    # 采样率
+            "-ac", "1",                 # 单声道
+            "-ab", bitrate,             # 比特率
+            "-y",                       # 覆盖输出文件
+            str(output_path)
+        ]
+
+        # 特定格式优化
+        if format == "opus":
+            # Opus 针对语音优化
+            cmd.extend(["-application", "audio"])
+        elif format == "speex":
+            # Speex 针对语音优化
+            cmd.extend(["-compression_level", "10"])
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=60  # 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 batch_convert(
+        self,
+        input_dir: Path,
+        output_dir: Optional[Path] = None,
+        format: str = "opus",
+        sample_rate: int = 16000
+    ) -> dict:
+        """
+        批量转换目录中的音频文件
+
+        Args:
+            input_dir: 输入目录
+            output_dir: 输出目录（可选，默认在输入目录下创建 voice/ 子目录）
+            format: 输出格式
+            sample_rate: 采样率
+
+        Returns:
+            转换结果字典 {原文件名: ConversionResult}
+        """
+        input_dir = Path(input_dir)
+        if output_dir is None:
+            output_dir = input_dir / "voice"
+        else:
+            output_dir = Path(output_dir)
+
+        results = {}
+
+        # 支持的输入格式
+        input_extensions = [".mp3", ".wav", ".m4a", ".flac", ".ogg"]
+
+        for input_file in input_dir.glob("*"):
+            if input_file.suffix.lower() not in input_extensions:
+                continue
+
+            output_file = output_dir / input_file.with_suffix(f".{format}").name
+            results[input_file.name] = self.convert_to_voice(
+                input_path=input_file,
+                output_path=output_file,
+                format=format,
+                sample_rate=sample_rate
+            )
+
+        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,
+    output_path: Optional[Path] = None
+) -> ConversionResult:
+    """
+    将 MP3 转换为 Opus 格式（飞书推荐）
+
+    Args:
+        input_path: MP3 文件路径
+        output_path: 输出路径（可选）
+
+    Returns:
+        ConversionResult
+    """
+    converter = AudioConverter()
+    return converter.convert_to_voice(
+        input_path=input_path,
+        output_path=output_path,
+        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
+    )