Update `AudioCapture` to support both PyAudio and macOS native AEC＋VAD libraries

- Add PyAudio-based standard audio capture as an option.
- Enable runtime switching between PyAudio and macOS native libraries based on echo cancellation settings.
- Refactor capture methods for better modularity and maintainability.

src/voice_dialogue/services/audio/capture.py

@@ -1,6 +1,9 @@
 """
-回声消除音频捕获模块
-使用 AEC (Acoustic Echo Cancellation) 技术的音频采集器
+音频捕获模块
+
+提供两种音频采集方式：
+1.  使用 PyAudio 进行标准音频采集。
+2.  使用集成了声学回声消除(AEC)和语音活动检测(VAD)的 macOS 原生库进行音频采集。
 """
 
 import ctypes
@@ -9,6 +12,7 @@ import time
 from multiprocessing import Queue
 
 import numpy as np
+import pyaudio
 
 from voice_dialogue.config.paths import LIBRARIES_PATH
 from voice_dialogue.core.base import BaseThread
@@ -17,8 +21,10 @@ from voice_dialogue.utils.logger import logger
 
 class AudioCapture(BaseThread):
     """
-    回声消除音频捕获器
-    使用原生 C 库进行音频捕获，支持回声消除和语音活动检测
+    音频捕获器。
+
+    根据配置选择使用 PyAudio 或带回声消除(AEC)的 macOS 原生库进行音频采集。
+    作为一个后台线程运行，将捕获的音频帧放入队列中。
     """
 
     def __init__(
@@ -26,6 +32,15 @@ class AudioCapture(BaseThread):
             audio_frames_queue: Queue = None,
             enable_echo_cancellation: bool = True,
     ):
+        """
+        初始化音频捕获器。
+
+        Args:
+            audio_frames_queue (Queue): 用于存放捕获的音频帧的队列。
+            enable_echo_cancellation (bool): 是否启用回声消除功能。
+                                             若为 True，则使用原生库进行捕获；
+                                             否则，使用 PyAudio。
+        """
         super().__init__(group, target, name, args, kwargs, daemon=daemon)
 
         self.audio_frames_queue = audio_frames_queue
@@ -33,43 +48,104 @@ class AudioCapture(BaseThread):
         self._enable_echo_cancellation = enable_echo_cancellation
 
     @property
-    def is_paused(self):
+    def is_paused(self) -> bool:
+        """检查捕获器是否已暂停。"""
         return self._pause_event.is_set()
 
     def pause(self):
+        """暂停音频捕获。"""
         self._pause_event.set()
 
     def resume(self):
+        """恢复音频捕获。"""
         self._pause_event.clear()
 
     def run(self):
-        """主运行循环，持续获取音频数据"""
+        """
+        线程主循环。
+
+        根据 `_enable_echo_cancellation` 标志，分派到相应的捕获方法。
+        """
+        if self._enable_echo_cancellation:
+            self._run_with_aec()
+        else:
+            self._run()
+
+    def _run(self):
+        """
+        使用 PyAudio 进行标准的音频采集。
+
+        此方法不提供回声消除或语音活动检测。
+        """
+        p = pyaudio.PyAudio()
+        chunk = 512
+        sample_rate = 16000
+        stream = p.open(
+            format=pyaudio.paInt16,
+            channels=1,
+            rate=sample_rate,
+            input=True,
+            frames_per_buffer=chunk,
+        )
+
+        logger.info("使用 PyAudio 开始音频采集...")
+        self.is_ready = True
+
+        try:
+            while not self.is_exited:
+                data = stream.read(chunk)
+
+                if self.is_paused:
+                    time.sleep(0.01)
+                    continue
+
+                # 将音频数据转换为 [-1.0, 1.0] 范围内的浮点数
+                audio_frame = np.frombuffer(data, dtype=np.int16).astype(np.float32) / np.iinfo(np.int16).max
+                self.audio_frames_queue.put(audio_frame)
+
+        except Exception as e:
+            logger.error(f'PyAudio 音频捕获器运行时发生错误: {e}')
+        finally:
+            logger.info("停止 PyAudio 音频采集...")
+            stream.stop_stream()
+            stream.close()
+            p.terminate()
+
+    def _run_with_aec(self):
+        """
+        使用 macOS 原生库进行音频捕获。
+
+        此方法通过 ctypes 调用外部动态库，支持声学回声消除(AEC)和语音活动检测(VAD)。
+        """
         audio_recorder = ctypes.CDLL(LIBRARIES_PATH / 'libAudioCapture.dylib')
         audio_recorder.getAudioData.argtypes = [ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_bool)]
         audio_recorder.getAudioData.restype = ctypes.POINTER(ctypes.c_ubyte)
         audio_recorder.freeAudioData.argtypes = [ctypes.POINTER(ctypes.c_ubyte)]
-        audio_recorder.startRecord()
 
+        audio_recorder.startRecord()
         self.is_ready = True
 
         try:
             while not self.is_exited:
                 size = ctypes.c_int(0)
                 is_voice_active = ctypes.c_bool(False)
-                # 获取音频数据
+                # 从原生库获取音频数据
                 data_ptr = audio_recorder.getAudioData(ctypes.byref(size), ctypes.byref(is_voice_active))
 
                 if data_ptr and size.value > 0:
                     audio_data = bytes(data_ptr[: size.value])
-                    audio_frame = np.frombuffer(audio_data, dtype=np.int16).astype(np.float32) / np.iinfo(np.int16).max
+                    # 将音频数据转换为 [-1.0, 1.0] 范围内的浮点数
+                    audio_frame = np.frombuffer(audio_data, dtype=np.int16).astype(np.float32) / np.iinfo(
+                        np.int16).max
 
                     if not self.is_paused:
+                        # 将音频帧和语音活动状态一同放入队列
                         self.audio_frames_queue.put((audio_frame, is_voice_active.value))
 
-                    # 使用完数据后释放内存
+                    # 释放原生库分配的内存
                     audio_recorder.freeAudioData(data_ptr)
                 else:
-                    # 无数据时等待
+                    # 无数据时短暂休眠，避免CPU空转
                     time.sleep(0.01)
         except Exception as e:
             logger.error(f'回声消除音频捕获器运行时发生错误: {e}')