refactor(core): Architecturally decouple Audio, ASR, and TTS modules

This major refactoring decouples core functionalities from the services layer, establishing clearer architectural boundaries and improving modularity. The changes adhere to the principles of Separation of Concerns and single-responsibility, making the system more maintainable and extensible.

Key changes include:

1. **Decoupled Audio Subsystem (Strategy Pattern)**:
- The monolithic `AudioCapture` class has been split into multiple, single-responsibility components within the `audio/` directory.
- `base_capture.py` introduces an abstract base class for all capture strategies.
- `pyaudio_capture.py` and `aec_capture.py` provide concrete implementations for standard and echo-cancelled audio capture.
- The main `capture.py` now acts as a Facade, selecting the appropriate capture strategy at runtime, hiding implementation details from the rest of the application.

2. **Introduced PlayerService to Separate Concerns**:
- Resolved a reverse dependency where `audio/player.py` was dependent on `services/mixins.py`.
- `audio/player.py` is now a pure `AudioPlayer`, stripped of all business logic. Its sole responsibility is to play raw audio data from a queue.
- A new `services/player_service.py` has been created to handle all business logic previously in the player, such as processing `VoiceTask`, managing state, and updating history. This service now directs the pure `AudioPlayer`.

3. **Elevated ASR and TTS to Top-Level Modules**:
- Relocated speech recognition models (`recognizers`) from `services/speech` to a new, dedicated `asr/` module.
- Relocated speech synthesis models (`generators`) from `services/audio` to a new, dedicated `tts/` module.
- This gives ASR and TTS first-class status within the project architecture, clarifying their roles as core, independent capabilities rather than sub-components of a generic service.

src/voice_dialogue/__init__.py

@@ -1,14 +0,0 @@
-from .core.constants import (
-    audio_frames_queue,
-    user_voice_queue,
-    transcribed_text_queue,
-    text_input_queue,
-    audio_output_queue
-)
-from .services.audio.capture import AudioCapture
-from .services.audio.generator import TTSAudioGenerator
-from .services.audio.generators.models import tts_config_registry
-from .services.audio.player import AudioStreamPlayer
-from .services.speech.monitor import SpeechStateMonitor
-from .services.speech.recognizer import ASRWorker
-from .services.text.generator import LLMResponseGenerator

src/voice_dialogue/api/core/config.py

@@ -1,6 +1,6 @@
 from typing import Dict, Any
 
-from voice_dialogue.services.audio.generators import tts_config_registry
+from voice_dialogue.tts import tts_config_registry
 from voice_dialogue.utils.logger import logger
 
 

src/voice_dialogue/api/core/lifespan.py

@@ -3,7 +3,7 @@ from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
 
-from voice_dialogue.services.audio.generators import tts_config_registry
+from voice_dialogue.tts import tts_config_registry
 from voice_dialogue.utils import get_system_language, logger
 from .config import TTSConfigInitializer
 from .service_factories import get_core_voice_service_definitions

src/voice_dialogue/api/core/service_factories.py

@@ -1,11 +1,10 @@
+from voice_dialogue.audio.capture import AudioCapture
 from voice_dialogue.core.constants import (
     transcribed_text_queue, text_input_queue, audio_output_queue,
     audio_frames_queue, user_voice_queue, websocket_message_queue
 )
-from voice_dialogue.services.audio import AudioCapture, TTSAudioGenerator, AudioStreamPlayer
-from voice_dialogue.services.audio.generators import BaseTTSConfig, tts_config_registry
-from voice_dialogue.services.speech import SpeechStateMonitor, ASRWorker
-from voice_dialogue.services.text.generator import LLMResponseGenerator
+from voice_dialogue.services import SpeechStateMonitor, ASRService, AudioPlayerService, LLMService, TTSAudioGenerator
+from voice_dialogue.tts import BaseTTSConfig, tts_config_registry
 from .service_manager import ServiceDefinition
 
 
@@ -30,18 +29,18 @@ class ServiceFactories:
         )
 
     @staticmethod
-    def create_asr_worker(language: str) -> ASRWorker:
+    def create_asr_worker(language: str) -> ASRService:
         """创建ASR服务"""
-        return ASRWorker(
+        return ASRService(
             user_voice_queue=user_voice_queue,
             transcribed_text_queue=transcribed_text_queue,
             language=language
         )
 
     @staticmethod
-    def create_llm_generator() -> LLMResponseGenerator:
+    def create_llm_generator() -> LLMService:
         """创建LLM文本生成服务"""
-        return LLMResponseGenerator(
+        return LLMService(
             user_question_queue=transcribed_text_queue,
             generated_answer_queue=text_input_queue,
             websocket_message_queue=websocket_message_queue,
@@ -60,9 +59,9 @@ class ServiceFactories:
         )
 
     @staticmethod
-    def create_audio_player() -> AudioStreamPlayer:
+    def create_audio_player() -> AudioPlayerService:
         """创建音频播放服务"""
-        return AudioStreamPlayer(
+        return AudioPlayerService(
             audio_playing_queue=audio_output_queue,
             websocket_message_queue=websocket_message_queue
         )

src/voice_dialogue/api/routes/asr_routes.py

@@ -1,6 +1,6 @@
 from fastapi import APIRouter, HTTPException, Request, BackgroundTasks
 
-from voice_dialogue.services.speech.recognizers import asr_manager
+from voice_dialogue.asr import asr_manager
 from voice_dialogue.utils.logger import logger
 from ..core.service_factories import get_asr_worker_service_definition
 from ..schemas.asr_schemas import (

src/voice_dialogue/api/routes/system_routes.py

@@ -121,7 +121,7 @@ async def stop_system(request: Request):
                 audio_capture_service = service_manager.get_service("audio_capture")
                 if audio_capture_service:
                     try:
-                        audio_capture_service.exit()
+                        audio_capture_service.stop()
                         logger.info("音频捕获服务已停止")
 
                         # 等待服务停止

src/voice_dialogue/api/routes/tts_routes.py

@@ -3,7 +3,7 @@ from typing import Optional
 from fastapi import APIRouter, HTTPException, BackgroundTasks, Request
 from fastapi.responses import FileResponse
 
-from voice_dialogue.services.audio.generators import tts_config_registry
+from voice_dialogue.tts import tts_config_registry
 from voice_dialogue.utils.logger import logger
 from ..core.service_factories import get_tts_audio_generator_service_definition
 from ..schemas.tts_schemas import (

src/voice_dialogue/{services/speech/recognizers → asr}/models/funasr.py

@@ -4,10 +4,10 @@ import typing
 import numpy as np
 from funasr_onnx import SeacoParaformer, CT_Transformer
 
+from voice_dialogue.asr.manager import asr_tables
+from voice_dialogue.asr.models.base import ASRInterface
+from voice_dialogue.asr.utils import ensure_minimum_audio_duration
 from voice_dialogue.config import paths
-from voice_dialogue.services.speech.recognizers.manager import asr_tables
-from voice_dialogue.services.speech.recognizers.models.base import ASRInterface
-from voice_dialogue.services.speech.recognizers.utils import ensure_minimum_audio_duration
 from voice_dialogue.utils.logger import logger
 
 

src/voice_dialogue/{services/speech/recognizers → asr}/models/whisper.py

@@ -3,10 +3,10 @@ import typing
 import numpy as np
 from pywhispercpp.model import Model
 
+from voice_dialogue.asr.manager import asr_tables
+from voice_dialogue.asr.models.base import ASRInterface
+from voice_dialogue.asr.utils import ensure_minimum_audio_duration
 from voice_dialogue.config import paths
-from voice_dialogue.services.speech.recognizers.manager import asr_tables
-from voice_dialogue.services.speech.recognizers.models.base import ASRInterface
-from voice_dialogue.services.speech.recognizers.utils import ensure_minimum_audio_duration
 from voice_dialogue.utils.logger import logger
 
 

src/voice_dialogue/{services/audio → audio}/__init__.py

@@ -1,9 +1,7 @@
 from .capture import AudioCapture
-from .generator import TTSAudioGenerator
-from .player import AudioStreamPlayer
+from .player import play_audio
 
 __all__ = (
     "AudioCapture",
-    "TTSAudioGenerator",
-    "AudioStreamPlayer",
+    "play_audio",
 )

src/voice_dialogue/audio/capture/__init__.py

@@ -0,0 +1,78 @@
+"""
+音频捕获模块门面。
+
+根据配置选择并管理具体的音频捕获策略。
+"""
+from multiprocessing import Queue
+
+from voice_dialogue.utils.logger import logger
+from .aec_capture import AecCapture
+from .pyaudio_capture import PyAudioCapture
+
+
+class AudioCapture:
+    """
+    音频捕获器门面 (Facade)。
+
+    根据配置选择并管理具体的音频捕获策略（PyAudio 或 AEC）。
+    为上层应用提供统一的、简化的音频捕获接口。
+    它不是一个线程，而是线程安全策略的管理者。
+    """
+
+    def __init__(
+            self,
+            audio_frames_queue: Queue,
+            enable_echo_cancellation: bool = True,
+    ):
+        """
+        初始化音频捕获器。
+
+        Args:
+            audio_frames_queue (Queue): 用于存放捕获的音频帧的队列。
+            enable_echo_cancellation (bool): 是否启用回声消除功能。
+                                             若为 True，则使用 AEC 原生库；
+                                             否则，使用 PyAudio。
+        """
+        self._strategy = None
+        try:
+            if enable_echo_cancellation:
+                self._strategy = AecCapture(audio_frames_queue=audio_frames_queue)
+            else:
+                self._strategy = PyAudioCapture(audio_frames_queue=audio_frames_queue)
+            logger.info(f"音频捕获策略已选择: {self._strategy.__class__.__name__}")
+        except Exception as e:
+            logger.error(
+                f"初始化 {AecCapture.__name__ if enable_echo_cancellation else PyAudioCapture.__name__} 失败: {e}, 将回退到 PyAudio。")
+            # 只有在尝试 AEC 失败时才回退
+            if not isinstance(self._strategy, PyAudioCapture):
+                self._strategy = PyAudioCapture(audio_frames_queue=audio_frames_queue)
+                logger.info(f"已回退到音频捕获策略: {self._strategy.__class__.__name__}")
+
+    def start(self):
+        """启动音频捕获线程。"""
+        self._strategy.start()
+
+    def stop(self):
+        """停止音频捕获线程。"""
+        self._strategy.exit()
+
+    def pause(self):
+        """暂停音频捕获。"""
+        self._strategy.pause()
+
+    def resume(self):
+        """恢复音频捕获。"""
+        self._strategy.resume()
+
+    @property
+    def is_paused(self) -> bool:
+        """检查捕获器是否已暂停。"""
+        return self._strategy.is_paused
+
+    @property
+    def is_ready(self) -> bool:
+        """检查捕获线程是否已准备就绪。"""
+        return self._strategy.is_ready
+
+    def is_alive(self):
+        return self._strategy.is_alive()

src/voice_dialogue/audio/capture/aec_capture.py

@@ -0,0 +1,74 @@
+import ctypes
+import time
+from multiprocessing import Queue
+
+from voice_dialogue.config.paths import LIBRARIES_PATH
+from voice_dialogue.utils.logger import logger
+from .base_capture import BaseCapture
+
+
+class AecCapture(BaseCapture):
+    """
+    使用 macOS 原生库进行支持 AEC 的音频捕获策略。
+    """
+
+    def __init__(self, audio_frames_queue: Queue, **kwargs):
+        super().__init__(audio_frames_queue=audio_frames_queue, **kwargs)
+
+    def _load_library(self):
+        """加载并配置 AEC 原生库。"""
+        try:
+            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)]
+            return audio_recorder
+        except Exception as e:
+            logger.error(f"加载 AEC 动态库失败: {e}")
+            raise
+
+    def _capture_loop(self, audio_recorder):
+        """AEC 音频捕获的主循环。"""
+        logger.info("使用 AEC 音频捕获器开始采集...")
+        audio_recorder.startRecord()
+        self.is_ready = True
+
+        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])
+
+                if not self.is_paused:
+                    # 将音频帧和语音活动状态一同放入队列
+                    self.audio_frames_queue.put((audio_data, is_voice_active.value))
+
+                # 释放原生库分配的内存
+                audio_recorder.freeAudioData(data_ptr)
+            else:
+                # 无数据时短暂休眠，避免CPU空转
+                time.sleep(0.01)
+
+    def _cleanup(self, audio_recorder):
+        """清理 AEC 资源。"""
+        logger.info("停止 AEC 音频采集...")
+        if not audio_recorder:
+            return
+        audio_recorder.stopRecord()
+
+    def run(self):
+        """
+        线程主循环，执行 AEC 音频捕获。
+        """
+        audio_recorder = None
+        try:
+            audio_recorder = self._load_library()
+            self._capture_loop(audio_recorder)
+        except Exception as e:
+            logger.error(f'回声消除音频捕获器运行时发生错误: {e}')
+            # 如果 AEC 失败，这里可以考虑触发一个事件或回退机制，但目前只记录错误
+        finally:
+            self._cleanup(audio_recorder)

src/voice_dialogue/audio/capture/base_capture.py

@@ -0,0 +1,50 @@
+import threading
+from abc import ABC, abstractmethod
+from multiprocessing import Queue
+
+from voice_dialogue.core.base import BaseThread
+
+
+class BaseCapture(BaseThread, ABC):
+    """
+    抽象音频捕获器基类。
+
+    定义了所有音频捕获策略应遵循的通用接口。
+    """
+
+    def __init__(
+            self,
+            audio_frames_queue: Queue,
+            group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None
+    ):
+        """
+        初始化音频捕获器。
+
+        Args:
+            audio_frames_queue (Queue): 用于存放捕获的音频帧的队列。
+        """
+        super().__init__(group, target, name, args, kwargs, daemon=daemon)
+        self.audio_frames_queue = audio_frames_queue
+        self._pause_event = threading.Event()
+
+    @property
+    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()
+
+    @abstractmethod
+    def run(self):
+        """
+        线程主循环。
+
+        子类必须实现此方法以提供具体的音频捕获逻辑。
+        """
+        raise NotImplementedError

src/voice_dialogue/audio/capture/pyaudio_capture.py

@@ -0,0 +1,69 @@
+from multiprocessing import Queue
+
+import pyaudio
+
+from voice_dialogue.utils.logger import logger
+from .base_capture import BaseCapture
+
+
+class PyAudioCapture(BaseCapture):
+    """
+    使用 PyAudio 进行标准的音频采集策略。
+    """
+
+    def __init__(self, audio_frames_queue: Queue, **kwargs):
+        super().__init__(audio_frames_queue=audio_frames_queue, **kwargs)
+
+    def _init_pyaudio(self):
+        """初始化 PyAudio 并返回实例和配置。"""
+        p = pyaudio.PyAudio()
+        chunk = 1024
+        sample_rate = 16000
+        return p, chunk, sample_rate
+
+    def _open_stream(self, p, chunk, sample_rate):
+        """打开 PyAudio 音频流。"""
+        return p.open(
+            format=pyaudio.paInt16,
+            channels=1,
+            rate=sample_rate,
+            input=True,
+            frames_per_buffer=chunk,
+        )
+
+    def _capture_loop(self, stream, chunk):
+        """PyAudio 音频捕获的主循环。"""
+        logger.info("使用 PyAudio 开始音频采集...")
+        self.is_ready = True
+
+        while not self.is_exited:
+            data = stream.read(chunk, exception_on_overflow=False)
+            if data is None:
+                continue
+
+            if self.is_paused:
+                continue
+
+            self.audio_frames_queue.put(data)
+
+    def _cleanup(self, stream, p):
+        """清理 PyAudio 资源。"""
+        logger.info("停止 PyAudio 音频采集...")
+        stream.stop_stream()
+        stream.close()
+        p.terminate()
+
+    def run(self):
+        """
+        线程主循环，执行 PyAudio 音频采集。
+        """
+        p, chunk, sample_rate = self._init_pyaudio()
+        stream = None
+        try:
+            stream = self._open_stream(p, chunk, sample_rate)
+            self._capture_loop(stream, chunk)
+        except Exception as e:
+            logger.error(f'PyAudio 音频捕获器运行时发生错误: {e}')
+        finally:
+            if stream:
+                self._cleanup(stream, p)

src/voice_dialogue/audio/player.py

@@ -0,0 +1,10 @@
+import tempfile
+
+import soundfile as sf
+from playsound import playsound
+
+
+def play_audio(audio_data, sample_rate=16000):
+    with tempfile.NamedTemporaryFile('w+b', suffix='.wav') as soundfile:
+        sf.write(soundfile, audio_data, samplerate=sample_rate, subtype='PCM_16', closefd=False)
+        playsound(soundfile.name, block=True)

src/voice_dialogue/config/speaker_config.py

@@ -4,7 +4,7 @@ TTS说话人配置管理
 提供说话人配置的查找、映射和管理功能
 """
 
-from voice_dialogue.services.audio.generators.models import tts_config_registry
+from voice_dialogue.tts.models import tts_config_registry
 
 
 def get_tts_config_by_speaker_name(speaker_name: str):

src/voice_dialogue/core/launcher.py

@@ -6,6 +6,7 @@
 
 import time
 
+from voice_dialogue.audio.capture import AudioCapture
 from voice_dialogue.config.speaker_config import get_tts_config_by_speaker_name, get_available_speaker_names
 from voice_dialogue.core.constants import (
     audio_frames_queue,
@@ -14,12 +15,7 @@ from voice_dialogue.core.constants import (
     text_input_queue,
     audio_output_queue
 )
-from voice_dialogue.services.audio.capture import AudioCapture
-from voice_dialogue.services.audio.generator import TTSAudioGenerator
-from voice_dialogue.services.audio.player import AudioStreamPlayer
-from voice_dialogue.services.speech.monitor import SpeechStateMonitor
-from voice_dialogue.services.speech.recognizer import ASRWorker
-from voice_dialogue.services.text.generator import LLMResponseGenerator
+from voice_dialogue.services import ASRService, LLMService, AudioPlayerService, SpeechStateMonitor, TTSAudioGenerator
 from voice_dialogue.utils.logger import logger
 
 
@@ -62,7 +58,7 @@ def launch_system(
     threads = []
 
     # 语音识别
-    asr_worker = ASRWorker(
+    asr_worker = ASRService(
         user_voice_queue=user_voice_queue,
         transcribed_text_queue=transcribed_text_queue,
         language=user_language
@@ -72,7 +68,7 @@ def launch_system(
     threads.append(asr_worker)
 
     # 文本生成
-    text_generator = LLMResponseGenerator(
+    text_generator = LLMService(
         user_question_queue=transcribed_text_queue,
         generated_answer_queue=text_input_queue
     )
@@ -98,7 +94,7 @@ def launch_system(
     threads.append(audio_generator)
 
     # 音频播放
-    audio_player = AudioStreamPlayer(audio_playing_queue=audio_output_queue)
+    audio_player = AudioPlayerService(audio_playing_queue=audio_output_queue)
     audio_player.daemon = True
     audio_player.start()
     threads.append(audio_player)

src/voice_dialogue/services/__init__.py

@@ -0,0 +1,13 @@
+from .asr_service import ASRService
+from .audio_player_service import AudioPlayerService
+from .llm_service import LLMService
+from .speech_monitor import SpeechStateMonitor
+from .tts_service import TTSAudioGenerator
+
+__all__ = (
+    'ASRService',
+    'AudioPlayerService',
+    'LLMService',
+    'SpeechStateMonitor',
+    'TTSAudioGenerator',
+)

src/voice_dialogue/services/{speech/recognizer.py → asr_service.py}

@@ -9,10 +9,10 @@ from voice_dialogue.core.constants import user_still_speaking_event, voice_state
 from voice_dialogue.models.voice_task import VoiceTask
 from voice_dialogue.services.mixins import PerformanceLogMixin
 from voice_dialogue.utils.cache import LRUCacheDict
-from .recognizers import asr_manager
+from voice_dialogue.asr import asr_manager
 
 
-class ASRWorker(BaseThread, PerformanceLogMixin):
+class ASRService(BaseThread, PerformanceLogMixin):
     def __init__(self, group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None,
                  user_voice_queue: Queue,
                  transcribed_text_queue: Queue,

src/voice_dialogue/services/audio/capture.py

@@ -1,148 +0,0 @@
-"""
-音频捕获模块
-
-提供两种音频采集方式：
-1.  使用 PyAudio 进行标准音频采集。
-2.  使用集成了声学回声消除(AEC)和语音活动检测(VAD)的 macOS 原生库进行音频采集。
-"""
-
-import ctypes
-import threading
-import time
-from multiprocessing import Queue
-
-import pyaudio
-
-from voice_dialogue.config.paths import LIBRARIES_PATH
-from voice_dialogue.core.base import BaseThread
-from voice_dialogue.utils.logger import logger
-
-
-class AudioCapture(BaseThread):
-    """
-    音频捕获器。
-
-    根据配置选择使用 PyAudio 或带回声消除(AEC)的 macOS 原生库进行音频采集。
-    作为一个后台线程运行，将捕获的音频帧放入队列中。
-    """
-
-    def __init__(
-            self, group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None,
-            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
-        self._pause_event = threading.Event()
-        self._enable_echo_cancellation = enable_echo_cancellation
-
-    @property
-    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 = 1024
-        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, exception_on_overflow=False)
-                if data is None:
-                    continue
-
-                if self.is_paused:
-                    continue
-
-                self.audio_frames_queue.put(data)
-
-        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()
-        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])
-
-                    if not self.is_paused:
-                        # 将音频帧和语音活动状态一同放入队列
-                        self.audio_frames_queue.put((audio_data, is_voice_active.value))
-
-                    # 释放原生库分配的内存
-                    audio_recorder.freeAudioData(data_ptr)
-                else:
-                    # 无数据时短暂休眠，避免CPU空转
-                    time.sleep(0.01)
-        except Exception as e:
-            logger.error(f'回声消除音频捕获器运行时发生错误: {e}')
-        finally:
-            audio_recorder.stopRecord()

src/voice_dialogue/services/{audio/player.py → audio_player_service.py}

@@ -1,22 +1,17 @@
-import tempfile
 import time
 from multiprocessing import Queue
 from queue import Empty
 from typing import Optional
 
-import soundfile as sf
-from playsound import playsound
-
+from voice_dialogue.audio.player import play_audio
 from voice_dialogue.core.base import BaseThread
-from voice_dialogue.core.constants import (
-    voice_state_manager, silence_over_threshold_event
-)
+from voice_dialogue.core.constants import voice_state_manager, silence_over_threshold_event
 from voice_dialogue.models.voice_task import VoiceTask, AnswerDisplayMessage
 from voice_dialogue.services.mixins import TaskStatusMixin, HistoryMixin, PerformanceLogMixin
 from voice_dialogue.utils.logger import logger
 
 
-class AudioStreamPlayer(BaseThread, TaskStatusMixin, HistoryMixin, PerformanceLogMixin):
+class AudioPlayerService(BaseThread, TaskStatusMixin, HistoryMixin, PerformanceLogMixin):
     """音频流播放器 - 负责播放生成的音频并管理播放状态"""
 
     def __init__(
@@ -69,16 +64,11 @@ class AudioStreamPlayer(BaseThread, TaskStatusMixin, HistoryMixin, PerformanceLo
 
             if not self.is_stopped:
                 audio_data, sample_rate = voice_task.tts_generated_sentence_audio
-                self._play_audio(audio_data, sample_rate)
+                play_audio(audio_data, sample_rate)
 
             # 任务处理完毕，跳出内部循环
             break
 
-    def _play_audio(self, audio_data, sample_rate=16000):
-        with tempfile.NamedTemporaryFile('w+b', suffix='.wav') as soundfile:
-            sf.write(soundfile, audio_data, samplerate=sample_rate, subtype='PCM_16', closefd=False)
-            playsound(soundfile.name, block=True)
-
     def run(self):
         """
         主运行循环。

src/voice_dialogue/services/{text/generator.py → llm_service.py}

@@ -10,16 +10,16 @@ from voice_dialogue.config.llm_config import get_llm_model_params, get_apple_sil
 from voice_dialogue.config.user_config import get_prompt
 from voice_dialogue.core.base import BaseThread
 from voice_dialogue.core.constants import chat_history_cache
-from voice_dialogue.models.voice_task import VoiceTask, QuestionDisplayMessage
-from voice_dialogue.services.mixins import TaskStatusMixin
-from voice_dialogue.services.text.processor import (
+from voice_dialogue.llm.processor import (
     preprocess_sentence_text, create_langchain_chat_llamacpp_instance,
     create_langchain_pipeline, warmup_langchain_pipeline
 )
+from voice_dialogue.models.voice_task import VoiceTask, QuestionDisplayMessage
+from voice_dialogue.services.mixins import TaskStatusMixin
 from voice_dialogue.utils.logger import logger
 
 
-class LLMResponseGenerator(BaseThread, TaskStatusMixin):
+class LLMService(BaseThread, TaskStatusMixin):
     """LLM 回答生成器 - 负责使用语言模型生成回答文本"""
 
     def __init__(

src/voice_dialogue/services/mixins.py

@@ -74,7 +74,7 @@ class PerformanceLogMixin:
             return
 
         try:
-            from voice_dialogue.services.utils import calculate_audio_duration
+            from voice_dialogue.utils.audio_utils import calculate_audio_duration
 
             asr_duration = getattr(voice_task, 'whisper_end_time', 0) - getattr(voice_task, 'whisper_start_time', 0)
             llm_duration = getattr(voice_task, 'llm_end_time', 0) - getattr(voice_task, 'llm_start_time', 0)

src/voice_dialogue/services/speech/__init__.py

@@ -1,4 +0,0 @@
-from .recognizer import ASRWorker
-from .monitor import SpeechStateMonitor
-
-__all__ = ['ASRWorker', 'SpeechStateMonitor']

src/voice_dialogue/services/{speech/monitor.py → speech_monitor.py}

@@ -13,13 +13,13 @@ from queue import Empty
 import librosa
 import numpy as np
 
+from voice_dialogue.audio.vad import SileroVAD
 from voice_dialogue.core.base import BaseThread
 from voice_dialogue.core.constants import (
     voice_state_manager, silence_over_threshold_event, user_still_speaking_event, session_manager
 )
 from voice_dialogue.core.enums import AudioState
 from voice_dialogue.models.voice_task import VoiceTask
-from voice_dialogue.services.audio.vad import SileroVAD
 from voice_dialogue.services.utils import normalize_audio_frame, calculate_audio_duration
 from voice_dialogue.utils.logger import logger
 

src/voice_dialogue/services/{audio/generator.py → tts_service.py}

@@ -7,8 +7,8 @@ from voice_dialogue.core.constants import voice_state_manager
 from voice_dialogue.models.voice_task import VoiceTask
 from voice_dialogue.services.mixins import TaskStatusMixin
 from voice_dialogue.services.utils import has_no_words
+from voice_dialogue.tts import tts_manager, BaseTTSConfig
 from voice_dialogue.utils.logger import logger
-from .generators import tts_manager, BaseTTSConfig
 
 
 class TTSAudioGenerator(BaseThread, TaskStatusMixin):

src/voice_dialogue/{services/audio/generators → tts}/runtime/kokoro.py

@@ -3,9 +3,9 @@ from typing import Tuple, Optional
 import numpy as np
 from kokoro_onnx import Kokoro
 
-from voice_dialogue.services.audio.generators.configs.kokoro import KokoroTTSConfig
-from voice_dialogue.services.audio.generators.manager import tts_tables
-from voice_dialogue.services.audio.generators.runtime.interface import TTSInterface
+from voice_dialogue.tts.configs.kokoro import KokoroTTSConfig
+from voice_dialogue.tts.manager import tts_tables
+from voice_dialogue.tts.runtime.interface import TTSInterface
 from voice_dialogue.utils.logger import logger
 
 

src/voice_dialogue/{services/audio/generators → tts}/runtime/moyoyo.py

@@ -6,9 +6,9 @@ from typing import Tuple
 import numpy as np
 
 from voice_dialogue.config.paths import load_third_party
-from voice_dialogue.services.audio.generators.manager import tts_tables
-from voice_dialogue.services.audio.generators.models.moyoyo import MoYoYoTTSConfig
-from voice_dialogue.services.audio.generators.runtime.interface import TTSInterface
+from voice_dialogue.tts.manager import tts_tables
+from voice_dialogue.tts.models.moyoyo import MoYoYoTTSConfig
+from voice_dialogue.tts.runtime.interface import TTSInterface
 from voice_dialogue.utils.logger import logger
 
 load_third_party()

src/voice_dialogue/utils/audio_utils.py

@@ -0,0 +1,17 @@
+import numpy as np
+
+
+def calculate_audio_duration(audio_data: np.ndarray, sample_rate: int) -> float:
+    """
+    计算音频数据的时长（秒）。
+
+    Args:
+        audio_data (np.ndarray): 音频数据数组。
+        sample_rate (int): 采样率。
+
+    Returns:
+        float: 音频时长（秒）。
+    """
+    if audio_data is None or sample_rate == 0:
+        return 0.0
+    return len(audio_data) / sample_rate

tests/test_llm_dialogue.py

@@ -13,7 +13,7 @@ if lib_path.exists() and lib_path.as_posix() not in sys.path:
     sys.path.insert(0, lib_path.as_posix())
 
 from voice_dialogue.config.llm_config import get_llm_model_params, BUILTIN_LLM_MODEL_PATH
-from voice_dialogue.services.text.processor import create_langchain_pipeline
+from voice_dialogue.llm.processor import create_langchain_pipeline
 
 CHINESE_SYSTEM_PROMPT = (
     "你是AI助手。请以自然流畅的中文口语化表达直接回答问题，避免冗余的思考过程。"