operating-room-monitor-server/voice_confirmation_client

手术室耗材语音确认客户端（桌面版）

独立桌面程序：按可配置间隔（默认 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）

cd /path/to/operation-room-monitor-server
uv sync --group voice-client

运行（开发态）

未配置项目 build-system 时，uv 可能不会注册 voice-confirmation-client 命令，推荐：

./start_voice_confirmation_client.sh

或在仓库根目录：

uv run --group voice-client python -m voice_confirmation_client

Windows（仓库根目录）：

start_voice_confirmation_client.bat

若 entry point 已可用，也可：

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 桌面程序）。

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 启动。