# ReplyOnPause 简化接口说明

## 一句话解释

**FastRTC 的 ReplyOnPause = 你只管写"怎么回复"，它帮你搞定"什么时候该回复"**

---

## 对比：我们 vs ReplyOnPause

### 我们的实现（v5）- 手动管理状态
```python
class VoiceAgent:
    async def process_audio_frame(self, audio_data: bytes):
        # 1. 手动 VAD 检测
        vad_result = self.vad.process_frame(audio_data)
        
        # 2. 手动判断状态
        if vad_result is True:
            if self._state == AgentState.SPEAKING:
                await self._handle_barge_in()
            elif self._state == AgentState.IDLE:
                await self.set_state(AgentState.LISTENING)
        
        elif vad_result is False:
            if self._state == AgentState.LISTENING:
                audio_buffer = self.vad.get_buffer()
                if len(audio_buffer) > 3200:
                    await self._handle_speech(audio_buffer)
    
    async def _handle_speech(self, audio_buffer: bytes):
        # 3. 手动调用 STT → LLM → TTS
        text = await self.stt.recognize(audio_buffer)
        async for sentence in self.splitter.process_stream(self.llm.chat(text)):
            await self.tts_synthesize_and_play(sentence)
```

**问题:** 需要手动管理状态机，代码复杂

---

### ReplyOnPause 风格 - 自动管理
```python
from fastrtc_style import ReplyOnPause

# 只需定义"收到语音后怎么处理"
async def my_handler(audio: bytes) -> AsyncGenerator[bytes, None]:
    # 1. STT
    text = await stt.recognize(audio)
    
    # 2. LLM
    response = await llm.chat(text)
    
    # 3. TTS (流式输出)
    async for chunk in tts.synthesize_stream(response):
        yield chunk  # ← 直接 yield 音频块

# 启动 - 全自动
reply_on_pause = ReplyOnPause(my_handler)
await reply_on_pause.start_streaming(audio_source)
```

**优势:** 
- ✅ 不需要关心 VAD 检测
- ✅ 不需要关心状态机
- ✅ 不需要关心"什么时候该响应"
- ✅ 只需关注"收到语音后做什么"

---

## 具体简化了什么？

| 我们 v5 (手动) | ReplyOnPause (自动) |
|---------------|---------------------|
| 手动检测 VAD | 内置 VAD 检测 |
| 手动管理 IDLE/LISTENING/SPEAKING | 自动状态切换 |
| 手动判断"用户说完没" | 自动静音检测 (500ms) |
| 手动处理打断 | 自动打断 (can_interrupt=True) |
| 100+ 行状态机代码 | 只需定义 handler 函数 |

---

## 完整示例

### 使用 ReplyOnPause
```python
import asyncio
from fastrtc_style import ReplyOnPause

# 1. 定义你的处理器
async def voice_handler(audio: bytes):
    """收到完整语音后的处理逻辑"""
    
    # STT
    text = await stt.recognize(audio)
    print(f"🎤 识别: {text}")
    
    # LLM
    response = await llm.chat(text)
    print(f"🤖 回复: {response}")
    
    # TTS
    async for audio_chunk in tts.synthesize_stream(response):
        yield audio_chunk

# 2. 创建 ReplyOnPause 实例
handler = ReplyOnPause(voice_handler)

# 3. 启动（全自动）
async def main():
    audio_source = get_audio_source()  # 你的音频源
    await handler.start_streaming(audio_source)

asyncio.run(main())
```

### 等价于我们 v5 的 100+ 行代码

---

## 为什么建议简化？

### 场景对比

| 场景 | 推荐方案 |
|------|---------|
| 学习/研究 | 我们用 v5 的手动状态机（理解原理） |
| 快速开发 | ReplyOnPause（省时间） |
| 生产环境 | 两者皆可，ReplyOnPause 更易维护 |
| IoT 设备 | 我们 v5（更低内存，更可控） |

### 核心思想

**FastRTC 的设计哲学:**
> "开发者只需要关心业务逻辑（怎么回复），不需要关心工程细节（VAD、状态机）"

**我们的选择:**
- 保留了底层控制能力（TEN VAD, 分句合成, 连接预热）
- 可选地提供 ReplyOnPause 简化接口
- 让不同场景有不同选择

---

## 总结

| 特性 | 我们 v5 | ReplyOnPause |
|------|---------|-------------|
| 代码量 | 100+ 行 | ~20 行 |
| 控制力 | 高（可微调每个环节） | 低（黑盒） |
| 性能 | 最优（TEN VAD） | 良好 |
| 易用性 | 中 | 高 |
| 适用场景 | 生产/IoT | 快速原型 |

**我的建议:** 
- 保留 v5 作为核心（性能最优）
- 提供 ReplyOnPause 作为可选简化接口
- 开发者按需选择