Local-Voice/README_MANUAL_CONTROL.md

# 多进程音频控制系统 - 主进程控制功能

## 概述

本系统已经重构，支持主进程对输入进程的校准和监听功能进行精确控制。通过这些新功能，你可以：

1. **手动控制校准过程**：在适当的时间启动语音检测器校准
2. **精确控制监听状态**：按需启用或禁用音频监听
3. **获取实时状态**：查询校准进度和监听状态

## 主要功能

### 1. 校准功能

#### 启动校准
```python
# 启动语音检测器校准
success = control_system.start_calibration()
if success:
    print("校准已启动")
```

#### 获取校准状态
```python
# 获取当前校准状态
status = control_system.get_calibration_status()
if status:
    print(f"校准进度: {status['progress']*100:.1f}%")
    print(f"是否在校准中: {status['calibrating']}")
```

#### 等待校准完成
```python
# 等待校准完成（30秒超时）
if control_system.wait_for_calibration_complete(timeout=30):
    print("校准完成")
else:
    print("校准超时")
```

### 2. 监听功能

#### 启动监听
```python
# 启动音频监听
success = control_system.start_monitoring()
if success:
    print("监听已启动")
```

#### 停止监听
```python
# 停止音频监听
success = control_system.stop_monitoring()
if success:
    print("监听已停止")
```

#### 获取监听状态
```python
# 获取当前监听状态
status = control_system.get_monitoring_status()
if status:
    print(f"监听启用: {status['enabled']}")
    print(f"正在录音: {status['recording']}")
    print(f"音频流活跃: {status['audio_stream_active']}")
```

## 使用示例

### 方法1：自动启动（推荐）

```python
from control_system import ControlSystem

# 1. 创建控制系统
config = {
    'system': {'log_level': "INFO"},
    'audio': {'sample_rate': 16000, 'channels': 1, 'chunk_size': 1024},
    'recording': {'min_duration': 2.0, 'max_duration': 30.0, 'silence_threshold': 3.0},
    'processing': {'enable_asr': True, 'enable_llm': True, 'enable_tts': True, 'character': 'libai'}
}

control_system = ControlSystem(config)

# 2. 一键启动（自动校准和监听）
control_system.start(auto_calibration=True, auto_monitoring=True)

# 系统现在正在运行，会自动处理语音检测和录音
```

### 方法2：手动控制

```python
from control_system import ControlSystem
import time

# 1. 创建控制系统
config = {
    'system': {'log_level': "INFO"},
    'audio': {'sample_rate': 16000, 'channels': 1, 'chunk_size': 1024},
    'recording': {'min_duration': 2.0, 'max_duration': 30.0, 'silence_threshold': 3.0},
    'processing': {'enable_asr': True, 'enable_llm': True, 'enable_tts': True, 'character': 'libai'}
}

control_system = ControlSystem(config)

# 2. 启动进程（但不自动启用监听）
control_system._start_processes()

# 3. 步骤1：校准
print("开始校准...")
control_system.start_calibration()

# 等待校准完成
if control_system.wait_for_calibration_complete(timeout=30):
    print("校准完成")
else:
    print("校准失败")
    exit(1)

# 4. 步骤2：启动监听
print("开始监听...")
control_system.start_monitoring()

# 5. 运行一段时间
print("系统运行中...")
try:
    while True:
        # 检查事件和显示状态
        control_system.check_events()
        control_system.display_status()
        time.sleep(0.1)
except KeyboardInterrupt:
    print("用户中断")

# 6. 停止监听
print("停止监听...")
control_system.stop_monitoring()

# 7. 关闭系统
control_system.shutdown()
```

### 方法3：混合控制

```python
from control_system import ControlSystem

# 1. 创建控制系统
control_system = ControlSystem(config)

# 2. 自动启动，但只校准，不自动监听
control_system.start(auto_calibration=True, auto_monitoring=False)

# 3. 手动控制监听
control_system.start_monitoring()  # 启动监听
# ... 运行一段时间 ...
control_system.stop_monitoring()  # 停止监听
control_system.start_monitoring()  # 重新启动监听

# 4. 关闭系统
control_system.shutdown()
```

### 自动化示例

查看 `example_manual_control.py` 文件获取完整的自动化控制示例。

## 关键变化

### 1. 默认行为变化

- **之前**：输入进程启动后自动开始校准和监听
- **现在**：输入进程启动后处于静默状态，等待主进程命令

### 2. 新增控制接口

在 `ControlSystem` 类中新增了以下方法：

- `start_calibration()` - 启动校准
- `start_monitoring()` - 启动监听
- `stop_monitoring()` - 停止监听
- `get_calibration_status()` - 获取校准状态
- `get_monitoring_status()` - 获取监听状态
- `wait_for_calibration_complete(timeout)` - 等待校准完成

### 3. 新增命令支持

在 `InputProcess` 中支持以下新命令：

- `start_calibration` - 开始校准
- `start_monitoring` - 开始监听
- `stop_monitoring` - 停止监听
- `get_calibration_status` - 获取校准状态
- `get_monitoring_status` - 获取监听状态

## 使用建议

1. **初始化顺序**：建议按照"启动进程 → 校准 → 启动监听"的顺序进行
2. **错误处理**：建议对每个操作进行错误检查和重试
3. **状态监控**：定期检查状态以确保系统正常运行
4. **资源清理**：使用完毕后正确关闭系统

## 注意事项

1. **进程间通信**：所有控制都是通过进程间队列实现的，可能会有轻微延迟
2. **超时处理**：建议为所有状态查询操作设置合理的超时时间
3. **并发安全**：确保在多线程环境中正确使用这些方法
4. **音频设备**：启动和停止监听会重新初始化音频设备，可能有短暂延迟