4c3f9a367b
Add voice_confirmation_client (poll, TTS MP3 playback, mic WAV resolve), PyInstaller spec, start/build helpers, and API unit tests. Pending manual testing: end-to-end on OR workstations and packaged exe. Made-with: Cursor
81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
# 手术室耗材语音确认客户端（桌面版）
|
||
|
||
独立桌面程序：按可配置间隔（默认 **5 秒**）轮询 `GET /client/surgeries/{surgery_id}/pending-confirmation`，播放服务端返回的 **MP3 话术**，录制医生麦克风为 **16 kHz 单声道 WAV**，并调用 `POST .../pending-confirmation/{confirmation_id}/resolve`（`multipart` 字段名 `audio`）。协议与 `[docs/客户端手术通信接口说明.md](../docs/客户端手术通信接口说明.md)` 一致。
|
||
|
||
## 环境
|
||
|
||
- Python **3.13+**（与主项目一致）
|
||
- 安装可选依赖组 `**voice-client`**（PySide6、httpx、numpy、sounddevice）
|
||
|
||
```bash
|
||
cd /path/to/operation-room-monitor-server
|
||
uv sync --group voice-client
|
||
```
|
||
|
||
## 运行（开发态）
|
||
|
||
未配置项目 `build-system` 时，`uv` 可能不会注册 `voice-confirmation-client` 命令，推荐：
|
||
|
||
```bash
|
||
./start_voice_confirmation_client.sh
|
||
```
|
||
|
||
或在仓库根目录：
|
||
|
||
```bash
|
||
uv run --group voice-client python -m voice_confirmation_client
|
||
```
|
||
|
||
Windows（仓库根目录）：
|
||
|
||
```bat
|
||
start_voice_confirmation_client.bat
|
||
```
|
||
|
||
若 entry point 已可用，也可：
|
||
|
||
```bash
|
||
uv run --group voice-client voice-confirmation-client
|
||
```
|
||
|
||
在界面中填写 **服务端 Base URL**、**6 位手术号**，点击 **开始监控**。
|
||
|
||
## 音频说明
|
||
|
||
- **播放 MP3**：优先使用本机 `ffplay`（ffmpeg），其次 macOS 使用 `afplay`；可将 `ffplay` 放到 `voice_confirmation_client/bin/`（与包同级目录下的 `bin/`）以便离线环境使用。
|
||
- **录音**：默认使用 **sounddevice** 录制并重采样为 16 kHz 单声道 WAV（与浏览器 Demo 一致）。可选勾选 **优先使用 ffmpeg 录音**（依赖本机 ffmpeg 及可用的设备参数；Windows 默认设备名可能需按现场调整，见 `voice_confirmation_client/core/record.py` 中 `default_ffmpeg_input_args`）。
|
||
|
||
## 打包（PyInstaller）
|
||
|
||
在 **目标操作系统** 上构建（不要交叉编译 Qt 桌面程序）。
|
||
|
||
```bash
|
||
uv sync --group voice-client-build
|
||
uv run --group voice-client-build pyinstaller voice_client.spec --noconfirm
|
||
# 或
|
||
uv run --group voice-client-build python scripts/build_voice_client.py
|
||
```
|
||
|
||
**Windows 一键打包（仓库根目录）**：双击或在 `cmd` 中执行 `build_voice_confirmation_client.bat`；需要干净构建时加参数 `--clean`（会先删除 `build/`、`dist/`）。
|
||
|
||
产物目录：`dist/voice-confirmation-client/`（目录分发，内含可执行文件）。Windows 下可执行文件为 `voice-confirmation-client.exe`。
|
||
|
||
**说明**：
|
||
|
||
- 体积较大（含 PySide6）；杀毒软件可能对 PyInstaller 打包的 exe 误报，可向医院 IT 申请加白。
|
||
- **macOS**：未签名/未公证的 `.app` 可能需在「隐私与安全性」中手动允许；正式发布需 Apple 开发者签名与公证。
|
||
- **可选**：将 `ffmpeg`/`ffplay` 二进制放入打包目录下的 `voice_confirmation_bin/`，程序会优先使用（需在 spec 中增加 `datas` 将该目录打入包内，或手动复制到分发目录）。
|
||
|
||
## 术间排查
|
||
|
||
1. **网络**：客户端机器能访问监控服务 HTTP/HTTPS 端口（默认文档为 `38080`）。
|
||
2. **麦克风**：在「输入设备」中选择正确设备；无列表时检查系统隐私权限（麦克风）。
|
||
3. **无待确认**：轮询返回 404 为常态；可关闭「隐藏 404 轮询日志」观察请求节奏。
|
||
4. **解析失败**：使用 **重试本轮** 重新播放 + 录音 + 上传；或使用 **仅重播话术** 听清提示。
|
||
|
||
## 与浏览器 Demo 的差异
|
||
|
||
- 浏览器 Demo（`scripts/demo_client/`）默认 **10 秒** 轮询；本客户端默认 **5 秒**，可在界面修改。
|
||
- 本客户端无「开始/结束手术」按钮；手术需由既有流程或他端调用 `POST /client/surgeries/start` 启动。
|
||
|